@lightningtv/renderer 2.16.1

package/dist/src/main-api/Renderer.js

@@ -0,0 +1,431 @@
+/*
+ * 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,
+            targetFPS: settings.targetFPS || 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 || 42,
+            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,
+            targetFPS: this.settings.targetFPS,
+            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) {
+        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(shaderType, props) {
+        return this.stage.shManager.loadShader(shaderType, props);
+    }
+    /**
+     * Create a new Dynamic Shader controller
+     *
+     * @remarks
+     * A Dynamic Shader is a shader that can be composed of an array of mulitple
+     * effects. Each effect can be animated or changed after creation (provided
+     * the effect is given a name).
+     *
+     * Example:
+     * ```ts
+     * renderer.createNode({
+     *   shader: renderer.createDynamicShader([
+     *     renderer.createEffect('radius', {
+     *       radius: 0
+     *     }, 'effect1'),
+     *     renderer.createEffect('border', {
+     *       color: 0xff00ffff,
+     *       width: 10,
+     *     }, 'effect2'),
+     *   ]),
+     * });
+     * ```
+     *
+     * @param effects
+     * @returns
+     */
+    createDynamicShader(effects) {
+        return this.stage.shManager.loadDynamicShader({
+            effects: effects,
+        });
+    }
+    /**
+     * Create an effect to be used in a Dynamic Shader
+     *
+     * @remark
+     * The {name} parameter is optional but required if you want to animate the effect
+     * or change the effect's properties after creation.
+     *
+     * See {@link createDynamicShader} for an example.
+     *
+     * @param type
+     * @param props
+     * @param name
+     * @returns
+     */
+    createEffect(type, props, name) {
+        return {
+            name,
+            type,
+            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);
+    }
+    /**
+     * Gets the target FPS for the global render loop
+     *
+     * @returns The current target FPS (0 means no throttling)
+     *
+     * @remarks
+     * This controls the maximum frame rate of the entire rendering system.
+     * When 0, the system runs at display refresh rate.
+     */
+    get targetFPS() {
+        return this.stage.options.targetFPS;
+    }
+    /**
+     * Sets the target FPS for the global render loop
+     *
+     * @param fps - The target FPS to set for the global render loop.
+     *              Set to 0 or a negative value to disable throttling.
+     *
+     * @remarks
+     * This setting affects the entire rendering system immediately.
+     * All animations, rendering, and frame updates will be throttled
+     * to this target FPS. Provides global performance control.
+     *
+     * @example
+     * ```typescript
+     * // Set global target to 30fps for better performance
+     * renderer.targetFPS = 30;
+     *
+     * // Disable global throttling (use display refresh rate)
+     * renderer.targetFPS = 0;
+     * ```
+     */
+    set targetFPS(fps) {
+        this.stage.options.targetFPS = fps > 0 ? fps : 0;
+        this.stage.updateTargetFrameTime();
+    }
+}
+//# sourceMappingURL=Renderer.js.map

package/dist/src/main-api/Renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Renderer.js","sourceRoot":"","sources":["../../../src/main-api/Renderer.ts"],"names":[],"mappings":"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"}

package/dist/src/main-api/ShaderController.d.ts

@@ -0,0 +1,31 @@
+import type { ShaderMap } from '../core/CoreShaderManager.js';
+import type { ExtractProps } from '../core/CoreTextureManager.js';
+import type { Stage } from '../core/Stage.js';
+import type { CoreShader } from '../core/renderers/CoreShader.js';
+/**
+ * Shader Controller Base Interface
+ *
+ * @remarks
+ * Used directly this interface is like an `any` type for Shader Controllers.
+ * But it is also used as a base for more specific Shader Controller interfaces.
+ */
+export interface BaseShaderController {
+    type: keyof ShaderMap;
+    shader: CoreShader;
+    props: Record<string, any>;
+    getResolvedProps: () => Record<string, any>;
+}
+/**
+ * Shader Controller Class
+ *
+ * @remarks
+ * This class is used to control shader props.
+ */
+export declare class ShaderController<S extends keyof ShaderMap> implements BaseShaderController {
+    readonly type: S;
+    readonly shader: InstanceType<ShaderMap[S]>;
+    private resolvedProps;
+    props: ExtractProps<ShaderMap[S]>;
+    constructor(type: S, shader: InstanceType<ShaderMap[S]>, props: ExtractProps<ShaderMap[S]>, stage: Stage);
+    getResolvedProps(): ExtractProps<ShaderMap[S]>;
+}

package/dist/src/main-api/ShaderController.js

@@ -0,0 +1,37 @@
+/**
+ * Shader Controller Class
+ *
+ * @remarks
+ * This class is used to control shader props.
+ */
+export class ShaderController {
+    type;
+    shader;
+    resolvedProps;
+    props;
+    constructor(type, shader, props, stage) {
+        this.type = type;
+        this.shader = shader;
+        this.resolvedProps = props;
+        const keys = Object.keys(props);
+        const l = keys.length;
+        const definedProps = {};
+        for (let i = 0; i < l; i++) {
+            const name = keys[i];
+            Object.defineProperty(definedProps, name, {
+                get: () => {
+                    return this.resolvedProps[name];
+                },
+                set: (value) => {
+                    this.resolvedProps[name] = value;
+                    stage.requestRender();
+                },
+            });
+        }
+        this.props = definedProps;
+    }
+    getResolvedProps() {
+        return this.resolvedProps;
+    }
+}
+//# sourceMappingURL=ShaderController.js.map

package/dist/src/main-api/ShaderController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShaderController.js","sourceRoot":"","sources":["../../../src/main-api/ShaderController.ts"],"names":[],"mappings":"AAsCA;;;;;GAKG;AAEH,MAAM,OAAO,gBAAgB;IAMhB;IACA;IAJH,aAAa,CAA6B;IAClD,KAAK,CAA6B;IAClC,YACW,IAAO,EACP,MAAkC,EAC3C,KAAiC,EACjC,KAAY;QAHH,SAAI,GAAJ,IAAI,CAAG;QACP,WAAM,GAAN,MAAM,CAA4B;QAI3C,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QAEtB,MAAM,YAAY,GAAG,EAAE,CAAC;QACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;YACtB,MAAM,CAAC,cAAc,CAAC,YAAY,EAAE,IAAI,EAAE;gBACxC,GAAG,EAAE,GAAG,EAAE;oBACR,OAAO,IAAI,CAAC,aAAa,CAAC,IAAwC,CAAC,CAAC;gBACtE,CAAC;gBACD,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE;oBACb,IAAI,CAAC,aAAa,CAAC,IAAwC,CAAC,GAAG,KAAK,CAAC;oBACrE,KAAK,CAAC,aAAa,EAAE,CAAC;gBACxB,CAAC;aACF,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,YAA0C,CAAC;IAC1D,CAAC;IAED,gBAAgB;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/src/main-api/utils.d.ts

@@ -0,0 +1,2 @@
+import type { CustomDataMap } from '../core/CoreNode.js';
+export declare function santizeCustomDataMap(d: CustomDataMap): CustomDataMap;

package/dist/src/main-api/utils.js

@@ -0,0 +1,34 @@
+export function santizeCustomDataMap(d) {
+    const validTypes = {
+        boolean: true,
+        string: true,
+        number: true,
+        undefined: true,
+    };
+    const keys = Object.keys(d);
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        if (!key) {
+            continue;
+        }
+        const value = d[key];
+        const valueType = typeof value;
+        // Typescript doesn't understand the above const valueType ¯\_(ツ)_/¯
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore-next-line
+        if (valueType === 'string' && value.length > 2048) {
+            console.warn(`Custom Data value for ${key} is too long, it will be truncated to 2048 characters`);
+            // same here, see above comment, this can only be a string at this point
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore-next-line
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
+            d[key] = value.substring(0, 2048);
+        }
+        if (!validTypes[valueType]) {
+            console.warn(`Custom Data value for ${key} is not a boolean, string, or number, it will be ignored`);
+            delete d[key];
+        }
+    }
+    return d;
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/main-api/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/main-api/utils.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,oBAAoB,CAAC,CAAgB;IACnD,MAAM,UAAU,GAAG;QACjB,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,IAAI;KAChB,CAAC;IAEF,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QACrB,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;QAE/B,oEAAoE;QACpE,6DAA6D;QAC7D,uBAAuB;QACvB,IAAI,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;YAClD,OAAO,CAAC,IAAI,CACV,yBAAyB,GAAG,uDAAuD,CACpF,CAAC;YAEF,wEAAwE;YACxE,6DAA6D;YAC7D,uBAAuB;YACvB,sGAAsG;YACtG,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,SAAoC,CAAC,EAAE,CAAC;YACtD,OAAO,CAAC,IAAI,CACV,yBAAyB,GAAG,0DAA0D,CACvF,CAAC;YACF,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/src/utils.d.ts

@@ -0,0 +1,104 @@
+import type { ContextSpy } from './core/lib/ContextSpy.js';
+export declare function createWebGLContext(canvas: HTMLCanvasElement | OffscreenCanvas, forceWebGL2: boolean | undefined, contextSpy: ContextSpy | null): WebGLRenderingContext;
+/**
+ * Asserts a condition is truthy, otherwise throws an error
+ *
+ * @remarks
+ * Useful at the top of functions to ensure certain conditions, arguments and
+ * properties are set/met before continuing. When using this function,
+ * TypeScript will narrow away falsy types from the condition.
+ *
+ * @param condition
+ * @param message
+ * @returns
+ */
+export declare function assertTruthy(condition: unknown, message?: string): asserts condition;
+/**
+ * Merges two colors based on a given progress value.
+ *
+ * This function takes two colors (c1 and c2) represented as 32-bit integers
+ * in RGBA format and blends them based on the provided progress value (p).
+ * The result is a new color that is a weighted combination of the input colors,
+ * where the weight is determined by the progress value.
+ *
+ * @param {number} c1 - The first color in RGBA format (32-bit integer).
+ * @param {number} c2 - The second color in RGBA format (32-bit integer).
+ * @param {number} p - The progress value between 0 and 1.
+ * @returns {number} The merged color as a 32-bit integer in RGBA format.
+ */
+export declare function mergeColorProgress(rgba1: number, rgba2: number, p: number): number;
+/**
+ * Given an RGBA encoded number, returns back the RGBA number with it's alpha
+ * component multiplied by the passed `alpha` parameter.
+ *
+ * @internalRemarks
+ * This method does NOT premultiply the alpha into the color channels. If that
+ * is required (for internal use only) use {@link mergeColorAlphaPremultiplied}
+ * instead.
+ *
+ * @param rgba RGBA encoded number
+ * @param alpha Normalized alpha value (Range: 0.0 - 1.0)
+ * @returns
+ */
+export declare function mergeColorAlpha(rgba: number, alpha: number): number;
+/**
+ * RGB components should not be premultiplied when using Canvas renderer
+ * @param mode  Renderer mode
+ */
+export declare function setPremultiplyMode(mode: 'webgl' | 'canvas'): void;
+/**
+ * Given an RGBA encoded number, returns back the RGBA number with it's alpha
+ * component multiplied by the passed `alpha` parameter.
+ *
+ * For the webGl renderer, each color channel is premultiplied by the final alpha value.
+ *
+ * @remarks
+ * If `flipEndianess` is set to true, the function will returned an ABGR encoded number
+ * which is useful when the color value needs to be passed into a shader attribute.
+ *
+ * NOTE: Depending on the mode set by {@link setPremultiplyMode}, this method returns
+ * a PREMULTIPLIED alpha color which is generally only useful in the context of the
+ * internal rendering process. Use {@link mergeColorAlpha} if you need to blend an alpha
+ * value into a color in the context of the Renderer's main API.
+ *
+ * @internalRemarks
+ * Do not expose this method in the main API because Renderer users should instead use
+ * {@link mergeColorAlpha} to manipulate the alpha value of a color.
+ *
+ * @internal
+ * @param rgba RGBA encoded number
+ * @param alpha Normalized alpha value (Range: 0.0 - 1.0)
+ * @param flipEndianess Flip the endianess. RGBA becomes encoded as ABGR (for inserting colors into shader attributes)
+ * @returns
+ */
+export declare function mergeColorAlphaPremultiplied(rgba: number, alpha: number, flipEndianess?: boolean): number;
+/**
+ * Returns true if the given object has the given "own" property.
+ *
+ * @param obj
+ * @param prop
+ * @returns
+ */
+export declare function hasOwn(obj: object, prop: string | number | symbol): boolean;
+/**
+ * Converts degrees to radians
+ *
+ * @param degrees
+ * @returns
+ */
+export declare function deg2Rad(degrees: number): number;
+/**
+ * Returns image aspect ratio
+ *
+ * @param width
+ * @param height
+ * @returns
+ */
+export declare function getImageAspectRatio(width: number, height: number): number;
+/**
+ * Checks import.meta if env is production
+ *
+ * @returns
+ */
+export declare function isProductionEnvironment(): boolean;
+export declare function getNewId(): number;