@lightningtv/renderer
Version:
Lightning 3 Renderer
342 lines • 12.5 kB
JavaScript
/*
* If not stated otherwise in this file or this component's LICENSE file the
* following copyright and licenses apply:
*
* Copyright 2023 Comcast Cable Communications Management, LLC.
*
* Licensed under the Apache License, Version 2.0 (the License);
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { EventEmitter } from '../common/EventEmitter.js';
import { assertTruthy, isProductionEnvironment } from '../utils.js';
import { Stage } from '../core/Stage.js';
import { CoreNode } from '../core/CoreNode.js';
import {} from '../core/CoreTextNode.js';
/**
* The Renderer Main API
*
* @remarks
* This is the primary class used to configure and operate the Renderer.
*
* It is used to create and destroy Nodes, as well as Texture and Shader
* references.
*
* Example:
* ```ts
* import { RendererMain, MainCoreDriver } from '@lightningjs/renderer';
*
* // Initialize the Renderer
* const renderer = new RendererMain(
* {
* appWidth: 1920,
* appHeight: 1080
* },
* 'app',
* new MainCoreDriver(),
* );
* ```
*
* ## Events
* - `fpsUpdate`
* - Emitted every `fpsUpdateInterval` milliseconds with the current FPS
* - `frameTick`
* - Emitted every frame tick
* - `quadsUpdate`
* - Emitted when number of quads rendered is updated
* - `idle`
* - Emitted when the renderer is idle (no changes to the scene
* graph/animations running)
* - `criticalCleanup`
* - Emitted when the Texture Memory Manager Cleanup process is triggered
* - Payload: { memUsed: number, criticalThreshold: number }
* - `memUsed` - The amount of memory (in bytes) used by textures before the
* cleanup process
* - `criticalThreshold` - The critical threshold (in bytes)
* - `criticalCleanupFailed`
* - Emitted when the Texture Memory Manager Cleanup process is unable to free
* up enough texture memory to reach below the critical threshold.
* This can happen when there is not enough non-renderable textures to
* free up.
* - Payload (object with keys):
* - `memUsed` - The amount of memory (in bytes) used by textures after
* the cleanup process
* - `criticalThreshold` - The critical threshold (in bytes)
*/
export class RendererMain extends EventEmitter {
root;
canvas;
settings;
stage;
inspector = null;
/**
* Constructs a new Renderer instance
*
* @param settings Renderer settings
* @param target Element ID or HTMLElement to insert the canvas into
* @param driver Core Driver to use
*/
constructor(settings, target) {
super();
const resolvedTxSettings = {
criticalThreshold: settings.textureMemory?.criticalThreshold || 124e6,
targetThresholdLevel: settings.textureMemory?.targetThresholdLevel || 0.5,
cleanupInterval: settings.textureMemory?.cleanupInterval || 5000,
debugLogging: settings.textureMemory?.debugLogging || false,
baselineMemoryAllocation: settings.textureMemory?.baselineMemoryAllocation || 26e6,
doNotExceedCriticalThreshold: settings.textureMemory?.doNotExceedCriticalThreshold || false,
};
const resolvedSettings = {
appWidth: settings.appWidth || 1920,
appHeight: settings.appHeight || 1080,
textureMemory: resolvedTxSettings,
boundsMargin: settings.boundsMargin || 0,
deviceLogicalPixelRatio: settings.deviceLogicalPixelRatio || 1,
devicePhysicalPixelRatio: settings.devicePhysicalPixelRatio || window.devicePixelRatio,
clearColor: settings.clearColor ?? 0x00000000,
fpsUpdateInterval: settings.fpsUpdateInterval || 0,
numImageWorkers: settings.numImageWorkers !== undefined ? settings.numImageWorkers : 2,
enableContextSpy: settings.enableContextSpy ?? false,
forceWebGL2: settings.forceWebGL2 ?? false,
inspector: settings.inspector ?? false,
renderEngine: settings.renderEngine,
quadBufferSize: settings.quadBufferSize ?? 4 * 1024 * 1024,
fontEngines: settings.fontEngines,
strictBounds: settings.strictBounds ?? true,
textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
canvas: settings.canvas || document.createElement('canvas'),
createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
};
this.settings = resolvedSettings;
const { appWidth, appHeight, deviceLogicalPixelRatio, devicePhysicalPixelRatio, inspector, canvas, } = resolvedSettings;
const deviceLogicalWidth = appWidth * deviceLogicalPixelRatio;
const deviceLogicalHeight = appHeight * deviceLogicalPixelRatio;
this.canvas = canvas;
canvas.width = deviceLogicalWidth * devicePhysicalPixelRatio;
canvas.height = deviceLogicalHeight * devicePhysicalPixelRatio;
canvas.style.width = `${deviceLogicalWidth}px`;
canvas.style.height = `${deviceLogicalHeight}px`;
// Initialize the stage
this.stage = new Stage({
appWidth: this.settings.appWidth,
appHeight: this.settings.appHeight,
boundsMargin: this.settings.boundsMargin,
clearColor: this.settings.clearColor,
canvas: this.canvas,
deviceLogicalPixelRatio: this.settings.deviceLogicalPixelRatio,
devicePhysicalPixelRatio: this.settings.devicePhysicalPixelRatio,
enableContextSpy: this.settings.enableContextSpy,
forceWebGL2: this.settings.forceWebGL2,
fpsUpdateInterval: this.settings.fpsUpdateInterval,
numImageWorkers: this.settings.numImageWorkers,
renderEngine: this.settings.renderEngine,
textureMemory: resolvedTxSettings,
eventBus: this,
quadBufferSize: this.settings.quadBufferSize,
fontEngines: this.settings.fontEngines,
inspector: this.settings.inspector !== null,
strictBounds: this.settings.strictBounds,
textureProcessingTimeLimit: this.settings.textureProcessingTimeLimit,
createImageBitmapSupport: this.settings.createImageBitmapSupport,
});
// Extract the root node
this.root = this.stage.root;
// Get the target element and attach the canvas to it
let targetEl;
if (typeof target === 'string') {
targetEl = document.getElementById(target);
}
else {
targetEl = target;
}
if (!targetEl) {
throw new Error('Could not find target element');
}
targetEl.appendChild(canvas);
// Initialize inspector (if enabled)
if (inspector && !isProductionEnvironment()) {
this.inspector = new inspector(canvas, resolvedSettings);
}
}
/**
* Create a new scene graph node
*
* @remarks
* A node is the main graphical building block of the Renderer scene graph. It
* can be a container for other nodes, or it can be a leaf node that renders a
* solid color, gradient, image, or specific texture, using a specific shader.
*
* To create a text node, see {@link createTextNode}.
*
* See {@link CoreNode} for more details.
*
* @param props
* @returns
*/
createNode(props) {
assertTruthy(this.stage, 'Stage is not initialized');
const node = this.stage.createNode(props);
if (this.inspector) {
return this.inspector.createNode(node);
}
// FIXME onDestroy event? node.once('beforeDestroy'
// FIXME onCreate event?
return node;
}
/**
* Create a new scene graph text node
*
* @remarks
* A text node is the second graphical building block of the Renderer scene
* graph. It renders text using a specific text renderer that is automatically
* chosen based on the font requested and what type of fonts are installed
* into an app.
*
* See {@link ITextNode} for more details.
*
* @param props
* @returns
*/
createTextNode(props) {
const textNode = this.stage.createTextNode(props);
if (this.inspector) {
return this.inspector.createTextNode(textNode);
}
return textNode;
}
/**
* Destroy a node
*
* @remarks
* This method destroys a node
*
* @param node
* @returns
*/
destroyNode(node) {
if (this.inspector) {
this.inspector.destroyNode(node.id);
}
return node.destroy();
}
/**
* Create a new texture reference
*
* @remarks
* This method creates a new reference to a texture. The texture is not
* loaded until it is used on a node.
*
* It can be assigned to a node's `texture` property, or it can be used
* when creating a SubTexture.
*
* @param textureType
* @param props
* @param options
* @returns
*/
createTexture(textureType, props) {
return this.stage.txManager.createTexture(textureType, props);
}
/**
* Create a new shader controller for a shader type
*
* @remarks
* This method creates a new Shader Controller for a specific shader type.
*
* If the shader has not been loaded yet, it will be loaded. Otherwise, the
* existing shader will be reused.
*
* It can be assigned to a Node's `shader` property.
*
* @param shaderType
* @param props
* @returns
*/
createShader(shType, props) {
return this.stage.shManager.createShader(shType, props);
}
/**
* Get a Node by its ID
*
* @param id
* @returns
*/
getNodeById(id) {
const root = this.stage?.root;
if (!root) {
return null;
}
const findNode = (node) => {
if (node.id === id) {
return node;
}
for (const child of node.children) {
const found = findNode(child);
if (found) {
return found;
}
}
return null;
};
return findNode(root);
}
toggleFreeze() {
throw new Error('Not implemented');
}
advanceFrame() {
throw new Error('Not implemented');
}
getBufferInfo() {
return this.stage.renderer.getBufferInfo();
}
/**
* Re-render the current frame without advancing any running animations.
*
* @remarks
* Any state changes will be reflected in the re-rendered frame. Useful for
* debugging.
*
* May not do anything if the render loop is running on a separate worker.
*/
rerender() {
this.stage.requestRender();
}
/**
* Cleanup textures that are not being used
*
* @param aggressive - If true, will cleanup all textures, regardless of render status
*
* @remarks
* This can be used to free up GFX memory used by textures that are no longer
* being displayed.
*
* This routine is also called automatically when the memory used by textures
* exceeds the critical threshold on frame generation **OR** when the renderer
* is idle and the memory used by textures exceeds the target threshold.
*
* **NOTE**: This is a heavy operation and should be used sparingly.
* **NOTE2**: This will not cleanup textures that are currently being displayed.
* **NOTE3**: This will not cleanup textures that are marked as `preventCleanup`.
* **NOTE4**: This has nothing to do with the garbage collection of JavaScript.
*/
cleanup(aggressive = false) {
this.stage.cleanup(aggressive);
}
/**
* Sets the clear color for the stage.
*
* @param color - The color to set as the clear color.
*/
setClearColor(color) {
this.stage.setClearColor(color);
}
}
//# sourceMappingURL=Renderer.js.map