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
swap calls. Please note that the
adaptive batch mode is yet experimental (can be enabled using
Holds the handle of the pending / executed animate frame request, if requested. Throughout the controller, only a single request at a time is allowed.
Number of intermediate frames that are rendered during one browser frame
Blocking updates can be used to re-configure the controller without triggering
Number of update requested while being in blocked mode. If there is one or more blocked requests, an update will be triggered when unblocked.
Controllable, e.g., an instance of a Renderer.
Total number of rendered intermediate frames.
Time tracker used to the minimum and maximum frame time of an intermediate frame (per multi-frame).
Total number of completed multi-frames.
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.
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.
Observable event that is triggered after frame invocation (renderer).
Observable event that is triggered after swap invocation (renderer).
Holds the handle of the running timeout to execute a new multi frame. Undefined if we currently do not wait for a new multi frame.
Time tracker used to capture the time the update callback took.
Toggle for debug outputs; if true control flow will be logged.
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 whether or not the control is blocking updates.
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.
Controllable for update, frame, and swap invocation.
Returns the debug-frame number greater than or equal to zero.
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.
Observable that can be used to subscribe to debug-frame number changes.
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).
Observable that can be used to subscribe to frame number changes.
The frames per second is based on the average number of a full intermediate frame request up to the current frame number.
Returns the total number of rendered (requested and probably completed) intermediate frames.
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.
Provides the minimum rendering time tracked over all intermediate frames of the current multi-frame.
Returns the total number of completed multi-frames.
Time in milliseconds used to delay rendering of subsequent intermediate frames after an update.
Sets the multi-frame delay in milliseconds. This is used to delay rendering of subsequent intermediate frames after an update.
A multi-frame delay in milliseconds.
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.
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.
The multi-frame number targeted for rendering.
Observable that can be used to subscribe to multi-frame number changes.
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.
Observable that can be used to subscribe to post frame events.
Observable that can be used to subscribe to post swap events.
Provides the update time tracked for the current multi-frame.
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
Utility for communicating this._debugFrameNumber changes to its associated subject.
Utility for communicating this._frameNumber changes to its associated subject.
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.
Actual invocation of the controllable's prepare method.
Actual invocation of the controllable's update method. Returns true if multi frame rendering should be restarted, false otherwise.
Utility for communicating this._multiFrameNumber changes to its associated subject.
Unblock updates. If there was at least one blocked update request, an immediate update is invoked.