Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Canvas

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.

Hierarchy

Index

Constructors

constructor

  • new Canvas(element: HTMLCanvasElement | string, attributes?: WebGLContextAttributes): Canvas
  • 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:

    • data-multi-frame-number {number} - integer greater than 0
    • data-clear-color {Color} - rgba color for clearing
    • data-frame-scale {GLclampf2} - width and height frame scale in [0.0,1.0]
    • data-frame-size {GLizei2} - width and height frame size in pixel
    • data-frame-precision {RenderPrecision} - precision for, e.g., frame accumulation , either 'float', 'half', 'byte', or 'auto'.

    Note: data-frame-size takes precedence if both frame-scale and frame-size data attributes are provided.

    Parameters

    • element: HTMLCanvasElement | string

      Canvas element or element id {string} to be used for querying the canvas element.

    • Optional attributes: WebGLContextAttributes

      Overrides the internal default attributes @see{Context.DEFAULT_ATTRIBUTES}.

    Returns Canvas

Properties

Protected _clearColor

_clearColor: Color

Protected _context

_context: Context
see

context

Protected _controller

_controller: Controller

Protected _element

_element: HTMLCanvasElement
see

element

Protected _favorSizeOverScale

_favorSizeOverScale: boolean

Flag used to determine whether frame size or frame scale is the dominant configuration.

Protected _framePrecision

_framePrecision: Precision
see

framePrecision This property can be observed, e.g., aCanvas.framePrecisionObservable.subscribe().

Protected _framePrecisionSubject

_framePrecisionSubject: ReplaySubject<Precision> = new ReplaySubject<Wizard.Precision>(1)

Protected _frameScale

_frameScale: GLclampf2
see

frameScale This property can be observed, aCanvas.frameScaleObservable.subscribe().

Protected _frameScaleSubject

_frameScaleSubject: ReplaySubject<Object> = new ReplaySubject<GLclampf2>(1)

Protected _frameSize

_frameSize: GLsizei2
see

frameSize This property can be observed, aCanvas.frameSizeObservable.subscribe().

Protected _frameSizeSubject

_frameSizeSubject: ReplaySubject<Object> = new ReplaySubject<GLsizei2>(1)

Protected _mouseEventProvider

_mouseEventProvider: MouseEventProvider

Protected _renderer

_renderer: Renderer | undefined
see

renderer

Protected _size

_size: GLsizei2 = [1, 1]
see

size This property can be observed, e.g., aCanvas.sizeObservable.subscribe().

Protected _sizeSubject

_sizeSubject: ReplaySubject<Object> = new ReplaySubject<GLsizei2>(1)

Protected _touchEventProvider

_touchEventProvider: TouchEventProvider

Static Protected DEFAULT_CLEAR_COLOR

DEFAULT_CLEAR_COLOR: Color = new Color([0.203, 0.227, 0.250, 1.0])

Default color that is used if none is set via data attributes.

Static Protected DEFAULT_FRAME_PRECISION

DEFAULT_FRAME_PRECISION: Precision = Wizard.Precision.auto

Default frame precision, e.g., accumulation format when multi-frame rendering is used.

Static Protected DEFAULT_MULTI_FRAME_NUMBER

DEFAULT_MULTI_FRAME_NUMBER: 0 = 0

Default multi-frame number used if none is set via data attributes.

Accessors

backend

  • get backend(): string
  • Getter for the created rendering backend (webgl context type).

    Returns string

    • Backend that was created on construction, either 'webgl' or 'webgl2' based on which one was created successfully. If no context could be created null is returned.

clearColor

  • get clearColor(): Color
  • set clearColor(clearColor: Color): void
  • 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.

    Returns Color

    • Color object passed to any renderer bound to this canvas.
  • 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.

    Parameters

    • clearColor: Color

      Color object that will be referenced.

    Returns void

    • Color object passed to any renderer bound to this canvas.

context

  • Provides access to the WebGL context (leaky abstraction).

    Returns Context

controller

  • Single controller that is managing the rendering control flow of a bound renderer.

    Returns Controller

    • The controller used by the canvas.

element

  • get element(): HTMLElement
  • Canvas element within the HTML5 document.

    Returns HTMLElement

framePrecision

  • Getter for the targeted frame precision. This property can be observed, e.g., canvas.framePrecisionObservable.subscribe().

    Returns Precision

    • Accumulation format as string passed to any renderer bound.
  • 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.

    Parameters

    • precision: Precision

      Frame precision, 'float', 'half', 'byte' or 'auto' are supported.

    Returns void

    • Accumulation format as string passed to any renderer bound.

framePrecision$

  • get framePrecision$(): Observable<string>
  • Observable that can be used to subscribe to frame precision changes.

    Returns Observable<string>

frameScale

  • Targeted scale for rendering with respect to the canvas size. This property can be observed, e.g., canvas.frameScaleObservable.subscribe().

    Returns GLclampf2

    • The frame scale in [0.0, 1.0].
  • 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.

    Parameters

    Returns void

    • The frame scale in [0.0,1.0].

frameScale$

  • Observable that can be used to subscribe to frame scale changes.

    Returns Observable<GLclampf2>

frameSize

  • Targeted resolution (width and height) for rendering in pixel. This property can be observed, e.g., canvas.frameSizeObservable.subscribe().

    Returns GLsizei2

    • The frame size in pixel (must not be physical/native pixels).
  • 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).

    Parameters

    • frameSize: GLsizei2

      Size for rendering in pixel (must not be physical/native pixels).

    Returns void

    • The frame size in [1, canvas-size].

frameSize$

  • get frameSize$(): Observable<GLsizei2>
  • Observable that can be used to subscribe to frame size changes.

    Returns Observable<GLsizei2>

height

  • get height(): GLsizei
  • 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).

    Returns GLsizei

    • The canvas height in physical/native screen pixels.

mouseEventProvider

renderer

  • get renderer(): Renderer | undefined
  • set renderer(renderer: Renderer | undefined): void
  • The currently bound renderer. If no renderer is bound null is returned. If a renderer is bound, it should always be initialized (renderer initialization handled by the canvas).

    Returns Renderer | undefined

    • The currently bound renderer.
  • Binds a renderer to the canvas. A previously bound renderer will be unbound (see bind and unbind).

    Parameters

    • renderer: Renderer | undefined

      A renderer object or undefined.

    Returns void

    • The currently bound renderer.

size

  • 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().

    Returns GLsizei2

    • The canvas width and height in physical/native screen pixels as 2-tuple.

size$

  • Observable that can be used to subscribe to canvas size changes.

    Returns Observable<GLsizei2>

touchEventProvider

width

  • get width(): GLsizei
  • 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).

    Returns GLsizei

    • The canvas width in physical/native screen pixels.

Methods

Protected _resizeEventListener

  • _resizeEventListener(): void

Protected bind

  • bind(renderer: Renderer | undefined): void
  • The renderer (if not null) 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.

    Parameters

    • renderer: Renderer | undefined

      Either undefined or an uninitialized renderer.

    Returns void

Protected configureController

  • configureController(dataset: DOMStringMap): void
  • 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.

    Parameters

    • dataset: DOMStringMap

      The attributes data-multi-frame-number and data-debug-frame-number are supported.

    Returns void

Protected configureSizeAndScale

  • configureSizeAndScale(dataset: DOMStringMap): void
  • 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.

    Parameters

    • dataset: DOMStringMap

      The attributes data-frame-size and data-frame-scale are supported.

    Returns void

dispose

  • dispose(): void

Protected framePrecisionNext

  • framePrecisionNext(): void
  • Utility for communicating this._framePrecision changes to its associated subject.

    Returns void

Protected frameScaleNext

  • frameScaleNext(): void
  • Utility for communicating this._frameScale changes to its associated subject.

    Returns void

Protected frameSizeNext

  • frameSizeNext(): void
  • Utility for communicating this._frameSize changes to its associated subject.

    Returns void

Protected onResize

  • onResize(): void
  • Resize is invoked by the resizable mixin. It retrieves the canvas size and promotes it to the renderer.

    Returns void

resize

  • resize(): void
  • Allows for explicit trigger of onResize, e.g., in case resize event-handling is managed explicitly ...

    Returns void

Protected retrieveSize

  • retrieveSize(): void
  • Convenience function that triggers the canvas size retrieval. The native width and height of the canvas dom element is cached (in pixel).

    Returns void

Protected sizeNext

  • sizeNext(): void
  • Utility for communicating this._size changes to its associated subject.

    Returns void

Protected unbind

  • unbind(): void
  • Unbinds the current renderer from the canvas as well as the controller and navigation, and uninitializes the renderer.

    Returns void

Static elementSize

  • elementSize(element: HTMLElement): GLsizei2 | undefined
  • 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.

    Parameters

    • element: HTMLElement

      DOM element to get the width and height in (native) pixel from.

    Returns GLsizei2 | undefined

    • Size of the element in native screen pixels. Undefined when size is not available in 'px'.

Static Protected resize

  • resize(): void
  • 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.

    Returns void