Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Controller

This class controls the rendering flow by means of triggering rendering of a well defined amount of frames (multi-frame number) for frame accumulation. Single frame rendering is handled with a multi-frame number of 1. If a full multi-frame is accumulated, rendering halts. The rendering is not intended to be controlled by owning objects, but via invalidation from within the renderer instead. However, an explicit redraw of a full single or multi-frame can be invoked by calling update(). Furthermore, when using multi-frame rendering, the renderer can be halted at a specific frame by setting a debug-frame number.

Terminology: a multi-frame is the final result after accumulating a number of intermediate frames (frame). The number of intermediate frames is defined by the multi-frame number. For a multi-frame, the controller invokes the prepare on a controllable first, followed by multiple frame and swap calls. Please note that the adaptive batch mode is yet experimental (can be enabled using batchSize).

Hierarchy

  • Controller

Index

Properties

Protected _batchSize

_batchSize: number = 1

Number of intermediate frames that are rendered during one browser frame

Protected _block

_block: boolean = false

Blocking updates can be used to re-configure the controller without triggering

Protected _blockedUpdates

_blockedUpdates: number = 0

Number of update requested while being in blocked mode. If there is one or more blocked requests, an update will be triggered when unblocked.

Protected _controllable

_controllable: Controllable | undefined

Controllable, e.g., an instance of a Renderer.

Protected _debugFrameNumber

_debugFrameNumber: number = 0
see

debugFrameNumber This property can be observed, e.g., aController.debugFrameNumberObservable.subscribe().

Protected _debugFrameNumberSubject

_debugFrameNumberSubject: ReplaySubject<number> = new ReplaySubject<number>(1)

Protected _frameNumber

_frameNumber: number = 0
see

frameNumber This property can be observed, e.g., aController.frameNumberObservable.subscribe().

Protected _frameNumberSubject

_frameNumberSubject: ReplaySubject<number> = new ReplaySubject<number>(1)

Protected _intermediateFrameCount

_intermediateFrameCount: number = 0

Total number of rendered intermediate frames.

Protected _intermediateFrameTimes

_intermediateFrameTimes: number[] = new Array<number>(2)

Time tracker used to the minimum and maximum frame time of an intermediate frame (per multi-frame).

Protected _multiFrameCount

_multiFrameCount: number = 0

Total number of completed multi-frames.

Protected _multiFrameNumber

_multiFrameNumber: number = 1
see

multiFrameNumber This property can be observed, e.g., aController.multiFrameNumberObservable.subscribe().

Protected _multiFrameNumberSubject

_multiFrameNumberSubject: ReplaySubject<number> = new ReplaySubject<number>(1)

Protected _multiFrameTime

_multiFrameTime: number

Time tracker used to accumulate all durations of executed frame and swap callbacks per multi-frame. This is the net rendering time and is used to derive the average frame time.

Protected _multiTime

_multiTime: Array<number> = [0.0, 0.0]

Used to measure the gross rendering time of a multi-frame. The first point in time denotes the start of the rendering, the second, the point in time the last frame was rendered.

Note: point in times might be shifted due to (un)pausing. Their intent is to allow measuring the rendering duration, nothing else.

Protected _pause

_pause: boolean = false

Stores the controller's pause state.

Protected _pauseTime

_pauseTime: number | undefined

Point in time when the pause started. This is used to shift the gross rendering time measurement in _multiTime.

Protected _pendingRequest

_pendingRequest: number = 0

Holds the handle of the pending animate frame request, if requested. Throughout the controller, only a single request at a time is allowed.

Protected _updateFrameTime

_updateFrameTime: number

Time tracker used to capture the time the update callback took.

Static Protected _debug

_debug: boolean = false

Toggle for debug outputs; if true control flow will be logged.

Accessors

averageFrameTime

  • get averageFrameTime(): number
  • Provides the average time it takes to render an intermediate frame within the current displayed multi-frame (if a new multi-frame is triggered, the average frame time is reset).

    Returns number

    • Average frame time (intermediate frame rendering) in ms

batch

  • set batch(size: number): void

blocked

  • get blocked(): boolean
  • Returns whether or not the control is blocking updates.

    Returns boolean

    • True if blocked, else false.

controllable

  • set controllable(controllable: Controllable | undefined): void
  • Sets the controllable, for which updates, frames, and swaps are invoked whenever rendering is invalidated and an updated multi-frame is required. Swap is detached from frame since rendering an intermediate frame is usually done offscreen and explicit swap control can be useful.

    Parameters

    • controllable: Controllable | undefined

      Controllable for update, frame, and swap invocation.

    Returns void

debug

  • set debug(value: boolean): void

debugFrameNumber

  • get debugFrameNumber(): number
  • set debugFrameNumber(debugFrameNumber: number): void
  • Returns the debug-frame number greater than or equal to zero.

    If the debug number is greater than the frame number rendering is restarted by means of an update(). If the debug number is less than the frame number the rendering continues and halts accordingly. If the debug number equals the current debug number set, nothing happens. If the debug number is greater than the multi-frame number, it is reduced to the multi-frame number.

    Note: in contrast to setting the multi-frame number, setting the debug-frame number unpauses the controller.

    Returns number

    • Debug-frame number.
  • Sets the debug.-frame number (debug number) that, if greater than zero, causes the rendering to halt when the current frame number (frame number) equals the debug number. Debugging can be disabled by setting the debug number to zero.

    If the debug number is greater than the frame number rendering is restarted by means of an update(). If the debug number is less than the frame number the rendering continues and halts accordingly. If the debug number equals the current debug number set, nothing happens. If the debug number is greater than the multi-frame number, it is reduced to the multi-frame number.

    Note: in contrast to setting the multi-frame number, setting the debug-frame number unpauses the controller.

    Parameters

    • debugFrameNumber: number

      Debug-frame number.

    Returns void

    • Debug-frame number.

debugFrameNumber$

  • get debugFrameNumber$(): Observable<number>
  • Observable that can be used to subscribe to debug-frame number changes.

    Returns Observable<number>

frameNumber

  • get frameNumber(): number
  • The current multi-frame number; it is less than or equal to the multi-frame number and enumerates the last rendered frame. Note that this does not denote the number of 'completed' multi-frames rendered (not a continuous frame count).

    Returns number

    • The current (intermediate) frame number.

frameNumber$

  • get frameNumber$(): Observable<number>
  • Observable that can be used to subscribe to frame number changes.

    Returns Observable<number>

framesPerSecond

  • get framesPerSecond(): number
  • The frames per second is based on the average number of a full intermediate frame request up to the current frame number.

    Returns number

    • Number of frames per second based on the current multi-frame

intermediateFrameCount

  • get intermediateFrameCount(): number
  • Returns the total number of rendered (requested and probably completed) intermediate frames.

    Returns number

    • The total number of intermediate frames rendered.

maximumFrameTime

  • get maximumFrameTime(): number
  • Provides the maximum rendering time tracked over all intermediate frames of the current multi-frame. Note that the maximum frame time is most often caused by the first intermediate frame within a multi-frame due to lazy stage initialization or reconfiguration.

    Returns number

    • Maximum intermediate frame time in ms

minimumFrameTime

  • get minimumFrameTime(): number
  • Provides the minimum rendering time tracked over all intermediate frames of the current multi-frame.

    Returns number

    • Minimum intermediate frame time in ms

multiFrameCount

  • get multiFrameCount(): number
  • Returns the total number of completed multi-frames.

    Returns number

    • The total number of multi-frames completed.

multiFrameNumber

  • get multiFrameNumber(): number
  • set multiFrameNumber(multiFrameNumber: number): void
  • Returns the multi-frame number. The number is greater than or equal to zero. Multi-frame number is implemented as a property and allows for change callback.

    Returns number

    • Multi-frame number.
  • Changes the multi-frame number. If the provided value equals the current number set, nothing happens. If the provided value is negative, the multi-frame number is set to 1.

    Parameters

    • multiFrameNumber: number

      The multi-frame number targeted for rendering.

    Returns void

    • Multi-frame number.

multiFrameNumber$

  • get multiFrameNumber$(): Observable<number>
  • Observable that can be used to subscribe to multi-frame number changes.

    Returns Observable<number>

multiFrameTime

  • get multiFrameTime(): number
  • The time in milliseconds that passed since the current multi-frame (up to the current frame number) was requested. This time excludes time spent paused (e.g., caused by halting rendering at debug-frame number). Note that this is not a measure of frame rendering performance. The number of frame requests per second might be limited to 60Hz even though the rendering of an intermediate frame takes only a few milliseconds.

    Returns number

    • Time passed for current multi-frame in milliseconds.

paused

  • get paused(): boolean
  • Returns whether or not the control is paused.

    Returns boolean

    • True if paused, else false.

updateFrameTime

  • get updateFrameTime(): number
  • Provides the update time tracked for the current multi-frame.

    Returns number

    • Time of the multi-frame update (before first intermediate frame is rendered) in ms

Methods

block

  • block(): void
  • Block implicit updates, e.g., caused by various setters. This can be used to reconfigure the controller without triggering to multiple intermediate updates. The block updates mode can be exited using unblock.

    Returns void

Protected cancel

  • cancel(): void
  • Cancel a pending frame invocation (if existing).

    Returns void

Protected debugFrameNumberNext

  • debugFrameNumberNext(): void
  • Utility for communicating this._debugFrameNumber changes to its associated subject.

    Returns void

Protected frameNumberNext

  • frameNumberNext(): void
  • Utility for communicating this._frameNumber changes to its associated subject.

    Returns void

Protected invoke

Protected invokeFrame

  • invokeFrame(): void
  • Invokes rendering of an intermediate frame, increments the frame counter, and requests rendering of the next frame. The rendering is invoked by means of a callback to the canvas renderer. This function implements various asserts to assure correct control logic and absolutely prevent unnecessary frame requests.

    Returns void

Protected invokePrepare

  • invokePrepare(): void
  • Actual invocation of the controllable's prepare method.

    Returns void

Protected invokeUpdate

  • invokeUpdate(force?: boolean): void
  • Parameters

    • Default value force: boolean = false

    Returns void

Protected multiFrameNumberNext

  • multiFrameNumberNext(): void
  • Utility for communicating this._multiFrameNumber changes to its associated subject.

    Returns void

pause

  • pause(): void
  • Sets pause state to true which affects subsequent requests. Any pending requests are canceled.

    Returns void

prepare

  • prepare(): void

Protected request

  • Triggers a frame invocation before the browser repaints. If no rendering callback is setup, the request is ignored.

    Parameters

    Returns void

Protected reset

  • reset(): boolean

unblock

  • unblock(): void
  • Unblock updates. If there was at least one blocked update request, an immediate update is invoked.

    Returns void

unpause

  • unpause(): void
  • Sets pause state to false which affects subsequent requests. Furthermore, a request is invoked.

    Returns void

update

  • update(force?: boolean): void
  • Resets multi-frame rendering by restarting at the first frame. If paused, this unpauses the controller. If updates where blocked using block, block updates is disabled.

    Parameters

    • Default value force: boolean = false

    Returns void