Create and initialize a multi-frame controller, setup a default multi-frame number and get the canvas's webgl context as well as the canvas resolution. The context and resolution will be passed on to the set renderer and its stages/passes appropriately. The canvas does not provide lazy initialization and is strictly bound to a single canvas element (DOM) that cannot be changed.
Note: the multi-frame number can be set using a data attribute in the canvas element called 'data-multi-frame-number'.
The canvas supports the following data attributes:
Note: data-frame-size takes precedence if both frame-scale and frame-size data attributes are provided.
Canvas element or element id {string} to be used for querying the canvas element.
Overrides the internal default attributes @see{Context.DEFAULT_ATTRIBUTES}.
Flag used to determine whether frame size or frame scale is the dominant configuration.
Default color that is used if none is set via data attributes.
Default frame precision, e.g., accumulation format when multi-frame rendering is used.
Default multi-frame number used if none is set via data attributes.
Getter for the created rendering backend (webgl context type).
Getter for the canvas's clear color. The clear color is provided to the renderer (on bind). Since this is a canvas specific setting it is stored here, not in a renderer or controller.
Sets the clear color that is then passed to the currently bound renderer as well as to any pipelines bound in the future. The provided color will be clamped to [0.0;1.0] for every component.
Color object that will be referenced.
Provides access to the WebGL context (leaky abstraction).
Single controller that is managing the rendering control flow of a bound renderer.
Canvas element within the HTML5 document.
Eye gaze event provider referring to the canvas element.
Getter for the targeted frame precision. This property can be observed, e.g.,
canvas.framePrecisionObservable.subscribe().
Sets the targeted frame precision that is then passed to the currently bound renderer as well as to any renderers bound in the future. This might be used for frame accumulation in multi-frame based rendering.
Frame precision, 'float', 'half', 'byte' or 'auto' are supported.
Observable that can be used to subscribe to frame precision changes.
Targeted scale for rendering with respect to the canvas size. This property can be observed, e.g.,
canvas.frameScaleObservable.subscribe().
Set the targeted scale for rendering with respect to the canvas size. The scale will be clamped to [0.0,1.0]. A scale of 0.0 results in 1px frame resolution for the respective component. The frame scale allows to detach the rendering resolution from the native canvas resolution, e.g., in order to decrease rendering cost. The frame resolution can also be specified explicitly by width and height. Non-finite values will be ignored.
Scale of rendering.
Observable that can be used to subscribe to frame scale changes.
Targeted resolution (width and height) for rendering in pixel. This property can be observed, e.g.,
canvas.frameSizeObservable.subscribe().
Set the targeted size for rendering in pixels. The size will be clamped to [1, canvas-size]. The frame size allows to detach the rendering resolution from the native canvas resolution, e.g., in order to decrease rendering cost. Non-finite values will be ignored. The render resolution can also be specified implicitly by width and height in scale (@see frameScale).
Size for rendering in pixel (must not be physical/native pixels).
Observable that can be used to subscribe to frame size changes.
Height of the canvas measured in physical/native screen pixels. This is the 'managed' canvas height. The unmanaged canvas height is available via context.gl.canvas_height (which should always be the same).
Canvas mouse event provider referring to the canvas element.
The currently bound renderer. If no renderer is bound, undefined is returned. If a renderer is bound, it should always be initialized (renderer initialization handled by the canvas).
Binds a renderer to the canvas. A previously bound renderer will be unbound (see bind and unbind).
A renderer object or undefined.
Size of the canvas measured in physical/native screen pixels. This is the 'managed' canvas width and height. The
unmanaged canvas width and height are available via context.gl.canvas.width and context.gl.canvas.height (which
should always be the same).
This property can be observed, e.g., allocationRegister.bytesObservable.subscribe().
Observable that can be used to subscribe to canvas size changes.
Canvas touch event provider referring to the canvas element.
Width of the canvas measured in physical/native screen pixels. This is the 'managed' canvas width. The unmanaged canvas width is available via context.gl.canvas_width (which should always be the same).
Activates the eye gaze event provider referring to the canvas element.
The renderer (if not undefined) will be connected to the controller and navigation. The controller will immediately trigger a multi-frame, thereby causing the renderer to render frames.
Note that no renderer should be bound to multiple canvases simultaneously. The reference is non owning.
Either undefined or an uninitialized renderer.
Register 'webglcontextlost' and 'webglcontextrestored' to handle lost and restoration of WebGL contexts.
Obtain the WEBGL_lose_context extension, store it with this canvas instance and use it for emulation of the context lost and restore feature.
Creates and initializes a new controller that is used for this canvas. If provided via data attributes multi-frame number and debug-frame number are set.
The attributes data-multi-frame-number and data-debug-frame-number are supported.
Initializes the frame size and scale. By default, the scale is 1.0 for width and height and the size reflects the native canvas size.
The attributes data-frame-size and data-frame-scale are supported.
Uninitializes and deletes the controller as well as all other properties.
Utility for communicating this._framePrecision changes to its associated subject.
Utility for communicating this._frameScale changes to its associated subject.
Utility for communicating this._frameSize changes to its associated subject.
Observe a certain element for style or class mutations. Any mutation invokes the resize event.
element that can be observed for style mutations (style mutation will trigger resize).
Handle a WebGL context lost event. This is for both natural and emulated lost contexts.
Handle a WebGL context restore event. This is for both natural and emulated restored contexts.
Resize is invoked by the resizable mixin. It retrieves the canvas size and promotes it to the renderer.
Allows for explicit trigger of onResize, e.g., in case resize event-handling is managed explicitly ...
Convenience function that triggers the canvas size retrieval. The native width and height of the canvas dom element is cached (in pixel).
Utility for communicating this._size changes to its associated subject.
Emulate a WebGL context loss. This functionality requires to have configureContextLostAndRestoreEmulation() called before. This function is usually called within the constructor of this canvas.
Emulate a WebGL context restore. This functionality requires to have configureContextLostAndRestoreEmulation() called before. This function is usually called within the constructor of this canvas.
Unbinds the current renderer from the canvas as well as the controller and navigation, and uninitializes the renderer.
Retrieves the native width and height of a given element in device pixel (size on screen in physical pixels). If the element is not found, or either window or its device pixel ratio are not defined, a default vec2 is returned. If the canvas size is not yet computed, i.e., not provided in px unit, undefined will be return.
DOM element to get the width and height in (native) pixel from.
This function is called when the window is resized (and the event listener was successfully registered). The event is forwarded to each registered resizable object.
A canvas is associated to a single canvas element (DOM) and integrates or delegates event handling as well as control over the rendering loop and the attached renderer respectively. Furthermore, the canvas can bind a single renderer (non owning) and sets up communication between controller, renderer, and navigation. The controller invokes the renderer's update, frame, and swap methods. The navigation manipulates the renderer's camera. The renderer can invalidate itself which causes a controller update.
Note: Since only the multi-frame number is used by the renderer and the controller, the canvas provides getter, setter, and change callback setter. Debug-frame and frame number are managed exclusively by the controller.
Note: the canvas should hold any properties that are required to be passed onto a newly bound renderer (in the case multiple renderer are used with a canvas). The clear color is one example of such a property.