Base class for hardware-accelerated processing and/or image-synthesis. It provides information such as the current
canvas, the canvas's size (native resolution), and the multi-frame number (for progressive rendering). A renderer's
properties are expected to be managed by its owning object or the canvas and should not be set directly/manually.
Alterations to these properties can be tracked with the
_altered property. This allows an inheritor to implement
partial asset reallocation and, e.g., speed up dynamic multi-frame reconfiguration. The alterable object can be
Object.assign(this._alterable, ... some structure of booleans).
This base class further provides the invalidate method that invokes an invalidation callback also provided by the owning/controlling canvas.
Since Initializable is extended, the initialization workflow applies to all specialized renderers (requires super calls in constructor as well as in initialize and uninitialize).
Note that a renderer is currently intended to always render to the canvas it is bound to. Hence, there is no interface for setting a frame target.
Alterable auxiliary object for tracking changes on renderer input and lazy updates.
Actual, native resolution for the canvas currently in charge of controlling the renderer. This might differ from the targeted frame resolution but is required, e.g., for specific non-proportional ratios between frame size and canvas size.
The clear color, provided by the canvas the renderer is bound to. This is used in frame calls of inheritors.
List of textures for debugging purposes such as normals, ids, depth, masks, etc. that can be populated by the inheritor. The index of a texture identifier can then be for specifying a debug output of a render texture.
Targeted frame precision, e.g., used for frame accumulation. Note that any renderer is currently expected to take advantage of progressive rendering (e.g., multi-frame sampling) and accumulation as well as a blit pass (since main intend is multi-frame based rendering).
Targeted resolution for image synthesis. This might differ from the canvas resolution and should be used in frame calls of inheritors.
The renderer's invalidation callback. This should usually be setup by the canvas and refer to a function in the canvas's controller, e.g., it should trigger an update within the controller.
This multi-frame number is for lazy reconfiguration and set on update. The inheritor can react to changes using this.altered.multiFrameNumber.
Whether or not any of the (relevant/monitored) rendering properties has been altered. This concept should be used by other classes (e.g., camera, rendering stages) for detecting modifications relevant for rendering output.
Sets the color used for clearing the background. This setter should only be used by the canvas this renderer is bound to. Changing the frame size invalidates the renderer.
Red, green, blue, and alpha color components.
Context that can be used for processing and rendering as well as passed to rendering stages.
The render texture index for debug output. This is -1 when debug output is disabled. This should be used in the renderers swap implementation.
Enables to specify the index of a render texture to be blit to the back buffer for debugging. This invalidates
but should result in a blit only if nothing else changed. When the requested debug texture was blit (and
debugTexture was actually altered)
this.debugTextureNext() should be called to inform observers.
Render texture index based on debuggableTextures array. This should be in [-1, length of array].
Observable that can be used to subscribe to debug texture changes.
Read only access to the renderers registered render textures that can be blit to the back buffer for debugging.
Set the frame precision.
Changes the frame size for rendering. This setter should only be used by the canvas this renderer is bound to. Changing the frame size invalidates the renderer.
Note: the frame size is detached from the canvas size. When blitting the frame into the canvas, the frame is rescaled to fill or fit the canvas size.
Resolution of the framebuffer.
Property getter for readonly access to the initialization status of an initializable instance.
Asserts the objects initialization status to be true. Note that the implementation is cached and forwarded to either an empty function when initialized and to an acutal assert(false) otherwise.
Asserts the objects initialization status to be false. Note that the implementation is cached and forwarded to either an empty function when uninitialized and to an acutal assert(false) otherwise.
Utility for communicating this._debugTexture changes to its associated subject.
Controllable interface intended to trigger rendering of a full pass of the renderer that results in either an intermediate frame for accumulation to a full multi-frame or full frame for itself. The inheritor should invoke frames of relevant rendering and processing stages.
The current frame number forwarded to onFrame.
Transforms local viewport coordinates into local intermediate frame coordinates.
Horizontal coordinate for the upper left corner of the viewport origin.
Vertical coordinate for the upper left corner of the viewport origin.
When extending (specializing) this class, initialize should initialize all required stages and allocate assets
that are shared between multiple stages. Note that
super.initialize() should always be call first when
'overriding' this function.
Note: the context handle is stored in a property, but should be passed to the stages by specializing renderer instead. The renderer itself should not allocate rendering resources directly, thus, it should not require a webgl context.
Wrapped gl context for function resolution (passed to all stages).
Functions that is invoked when the renderer (or any stage) is invalidated.
Provider for mouse events referring to the canvas element.
Actual frame call specified by inheritor. After (1) update and (2) preparation are invoked, a frame is invoked. This should be used for actual rendering implementation.
Actual prepare call specified by inheritor. This is invoked in order to prepare rendering of one or more frames. This should be used for rendering preparation, e.g., when using multi-frame rendering this might specify uniforms that do not change for every intermediate frame.
Actual swap call specified by inheritor. After (1) update, (2) preparation, and (3) frame are invoked, a swap might be invoked. In case of experimental batch rendering when using multi-frame a swap might be withhold for multiple frames. Any implementation is expected to ensure that contents of a frame to be on the OpenGL back buffer. The swap of front buffer and back buffer is scheduled after the invocation of this function by the browser.
Actual uninitialize call specified by inheritor.
Actual update call specified by inheritor. This is invoked in order to check if rendering of a frame is required by means of implementation specific evaluation (e.g., lazy non continuous rendering). Regardless of the return value a new frame (preparation, frame, swap) might be invoked anyway, e.g., when update is forced or canvas or context properties have changed or the renderer was invalidated @seeinvalidate.
Prepares the rendering of the next frame (or subsequent frames when multi-frame rendering). This is part of the controllable interface. The renderer should reconfigure as lazy as possible.
Interface intended to trigger swap (by controller).
Should release all assets and uninitialize all stages.
super.uninitialize() should always be call first when
overriding this function.
Method decorator for asserting the initialization status of an initializable to be true.
Method decorator for asserting the initialization status of an initializable to be false.
Method decorator for initialization of Initializable inheritors. This decorator asserts the initialization status
of the instance that is to be initialized, invokes its initialization with arbitrary number of parameters,
and sets the initialization status to the initialization success (either false or true).
In order to encourage the use of
assertUninitialized they are dynamically
bound to either a static, always-failing assert or an empty/undefined function.
Method decorator for uninitialization of Initializable inheritors. This decorator asserts the initialization
status of the instance that is to be uninitialized, invokes its uninitialization, and falsifies the
initialization status. In order to encourage the use of
assertUninitialized they are
dynamically bound to a static, always-failing assert and an empty/undefined function respectively.