CanvasSpace is an implementation of the abstract class Space. It represents a space for HTML Canvas.
Learn more about the concept of Space in this guide.
Create a CanvasSpace which represents a HTML Canvas Space
Specify an element by its "id" attribute as string, or by the element object itself. An element can be an existing <canvas>, or a <div> container in which a new <canvas> will be created. If left empty, a <div id="pt_container"><canvas id="pt" /></div> will be added to DOM. Use css to customize its appearance if needed.
an optional callback function(boundingBox, spaceElement) to be called when canvas is appended and ready. Alternatively, a "ready" event will also be fired from the <canvas> element when it's appended, which can be traced with spaceInstance.canvas.addEventListener("ready")
new CanvasSpace( "#myElementID" )
Set whether the canvas element should resize when its container is resized.
a boolean value indicating if auto size is set
Set a background color for this canvas. Alternatively, you may use clear() function.
background color as hex or rgba string
Get the rendering context of offscreen canvas (if created via setup())
pixelScale property returns a number that let you determine if the screen is "retina" (when value >= 2)
The center of this space's bounding box.
Space.center in src/Space.tsSet a custom rendering function fn(graphics_context, canvas_space) if needed.
Space.customRendering in src/Space.tsThe height of this space's bounding box.
Space.height in src/Space.tsThe inner bounding box of the space, excluding its positions.
Space.innerBound in src/Space.tsIndicate whether the animation is playing.
Space.isPlaying in src/Space.tsThe outer bounding box which includes its positions.
Space.outerBound in src/Space.tsGet the mouse or touch pointer that stores the last action.
MultiTouchSpace.pointer in src/Space.tsThe width of this space's bounding box.
Space.width in src/Space.tsClear the canvas with its background color. Overrides Space's clear function.
Optionally specify a custom background color in hex or rgba string, or "transparent". If not defined, it will use its bgcolor property as background color to clear the canvas.
Space.clear in src/Canvas.tsSimiliar to clear() but clear the offscreen canvas instead
Optionally specify a custom background color in hex or rgba string, or "transparent". If not defined, it will use its bgcolor property as background color to clear the canvas.
Dispose of browser resources held by this space and remove all players. Call this before unmounting the canvas.
Get a new CanvasForm for drawing
CanvasForm
Space.getForm in src/Canvas.tsMain animation function.
current time
Space.playItems in src/Canvas.tsGet a MediaRecorder to record the current CanvasSpace. You can then call its start() function to start recording, and stop() to either download the video file or handle the blob data in the callback function you provided.
Either true to download the video, or provide a callback function to handle the Blob data, when recording is completed.
video format. Default is "webm".
bitrate per second
let rec = space.recorder(true); rec.start(); setTimeout( () => rec.stop(), 5000); // record 5s of video and download the file
This overrides Space's resize function. It's used as a callback function for window's resize event and not usually called directly. You can keep track of resize events with resize: (bound ,evt) callback in your player objects.
a Bound object to resize to
Optionally pass a resize event
Space.add
Space.resize in src/Canvas.tsSet up various options for CanvasSpace. The opt parameter is an object with the following fields. This is usually set during instantiation, eg new CanvasSpace(...).setup( { opt } )
a CanvasSpaceOptions object with optional settings, ie { bgcolor:string, resize:boolean, retina:boolean, offscreen:boolean, pixelDensity:number }.
space.setup({ bgcolor: "#f00", retina: true, resize: true })
Add an IPlayer object or a AnimateCallbackFn callback function to handle events in this Space. An IPlayer is an object with the following callback functions:
animate: fn( time, ftime, space )start: fn(bound, space)resize: fn( size, event )action: fn( type, x, y, event )
Subclasses of Space may define other callback functions.Space.add in src/Space.tsBind event listener in canvas element. You can also use MultiTouchSpace.bindMouse or MultiTouchSpace.bindTouch to bind mouse or touch events conveniently.
an event string such as "mousedown"
callback function for this event
options for addEventListener.
If needed, this is an optional parameter to set another event target that's not the canvas element itself. See Technical Notes guide for use cases.
MultiTouchSpace.bindCanvas in src/Space.tsMultiTouchSpace.bindDoc in src/Space.tsMultiTouchSpace.bindKeyboard in src/Space.tsA convenient method to bind (or unbind) all mouse events in canvas element.
All IPlayer objects added to this space that implement an action callback property will receive mouse event callbacks.
The types of mouse actions are defined by UIPointerActions constants: "up", "down", "move", "drag", "drop", "over", and "out".
a boolean value to bind mouse events if set to true. If false, all mouse events will be unbound. Default is true.
If needed, this is an optional parameter to set another event target that's not the canvas element itself. See Technical Notes guide for use cases.
MultiTouchSpace.bindMouse in src/Space.tsA convenient method to bind (or unbind) all touch events in canvas element.
All IPlayer objects added to this space that implement an action callback property will receive touch event callbacks.
The types of mouse actions are defined by UIPointerActions constants: "up", "down", "move", "drag", "drop", "over", and "out".
a boolean value to bind touch events if set to true. If false, all mouse events will be unbound. Default is true.
a boolean value to set passive mode, ie, it won't block scrolling. Default is false.
If needed, this is an optional parameter to set another event target that's not the canvas element itself. See Technical Notes guide for use cases.
MultiTouchSpace.bindTouch in src/Space.tsSet a minimum frame time
at least this amount of miniseconds must have elapsed before frame advances
Space.minFrameTime in src/Space.tsPause the animation.
a boolean value to set if this function call should be a toggle (between pause and resume)
Space.pause in src/Space.tsMain play loop. This implements window.requestAnimationFrame and calls it recursively.
You may override this play() function to implement your own animation loop.
current time
Space.play in src/Space.tsPlay animation loop once. Optionally set a duration time to play for that specific duration.
a value in millisecond to specify a time period to play before stopping, or -1 to play forever
Space.playOnce in src/Space.tsSet whether the rendering should be repainted on each frame.
a boolean value to set whether to repaint each frame
Space.refresh in src/Space.tsRemove a player from this Space.
an IPlayer that has an animateID property
Space.remove in src/Space.tsRemove all players from this Space.
Space.removeAll in src/Space.tsCustom rendering.
rendering context
Space.render in src/Space.tsReplay the animation after Space.stop. This resets the end-time counter.
You may also use Space.pause and resume for temporary pause.
Space.replay in src/Space.tsSpecify when the animation should stop: immediately, after a time period, or never stops.
a value in millisecond to specify a time period to play before stopping, or -1 to play forever, or 0 to end immediately. Default is 0 which will stop the animation immediately.
Space.stop in src/Space.tsA convenient method to convert the touch points in a touch event to an array of Pts.
a touch event which contains touches, changedTouches, and targetTouches list
a string to select a touches list: "touches", "changedTouches", or "targetTouches". Default is "touches"
an array of Pt, whose origin position (0,0) is offset to the top-left of this space
MultiTouchSpace.touchesToPoints in src/Space.tsUnbind a callback from the event listener.
an event string such as "mousedown"
callback function to unbind
options for removeEventListener. This should match the options set in bindCanvas.
If customTarget is set in bindCanvas, you'll need to pass the same instance here to unbind
MultiTouchSpace.unbindCanvas in src/Space.tsMultiTouchSpace.unbindDoc in src/Space.ts