@solidtv/renderer 1.0.0

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

@@ -0,0 +1,471 @@
+import { EventEmitter } from '../common/EventEmitter.js';
+import { isProductionEnvironment } from '../utils.js';
+import { Stage } from '../core/Stage.js';
+import { CoreNode } from '../core/CoreNode.js';
+import {} from '../core/CoreTextNode.js';
+import { WebPlatform } from '../core/platforms/web/WebPlatform.js';
+import { Platform } from '../core/platforms/Platform.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(),
+ * );
+ * ```
+ *
+ * ## Event Handling
+ *
+ * Listen to events using the standard EventEmitter API:
+ * ```typescript
+ * renderer.on('fpsUpdate', (data: RendererMainFpsUpdateEvent) => {
+ *   console.log(`FPS: ${data.fps}`);
+ * });
+ *
+ * renderer.on('idle', (data: RendererMainIdleEvent) => {
+ *   // Renderer is idle - no scene changes
+ * });
+ * ```
+ *
+ * @see {@link RendererMainFpsUpdateEvent}
+ * @see {@link RendererMainFrameTickEvent}
+ * @see {@link RendererMainRenderUpdateEvent}
+ * @see {@link RendererMainIdleEvent}
+ * @see {@link RendererMainCriticalCleanupEvent}
+ * @see {@link RendererMainCriticalCleanupFailedEvent}
+ *
+ * @fires RendererMain#fpsUpdate
+ * @fires RendererMain#frameTick
+ * @fires RendererMain#renderUpdate
+ * @fires RendererMain#idle
+ * @fires RendererMain#criticalCleanup
+ * @fires RendererMain#criticalCleanupFailed
+ */
+export class RendererMain extends EventEmitter {
+    root;
+    canvas;
+    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 = this.resolveTxSettings(settings.textureMemory || {});
+        settings = {
+            appWidth: settings.appWidth || 1920,
+            appHeight: settings.appHeight || 1080,
+            textureMemory: resolvedTxSettings,
+            boundsMargin: settings.boundsMargin || 0,
+            deviceLogicalPixelRatio: settings.deviceLogicalPixelRatio || 1,
+            devicePhysicalPixelRatio: settings.devicePhysicalPixelRatio || window.devicePixelRatio || 1,
+            clearColor: settings.clearColor ?? 0x00000000,
+            fpsUpdateInterval: settings.fpsUpdateInterval || 0,
+            enableClear: settings.enableClear ?? true,
+            targetFPS: settings.targetFPS || 0,
+            numImageWorkers: settings.numImageWorkers !== undefined ? settings.numImageWorkers : 2,
+            enableContextSpy: settings.enableContextSpy ?? false,
+            forceWebGL2: settings.forceWebGL2 ?? false,
+            inspector: settings.inspector ?? false,
+            inspectorOptions: settings.inspectorOptions ?? {},
+            renderEngine: settings.renderEngine,
+            quadBufferSize: settings.quadBufferSize ?? 4 * 1024 * 1024,
+            fontEngines: settings.fontEngines ?? [],
+            textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
+            canvas: settings.canvas,
+            createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
+            platform: settings.platform || null,
+            maxRetryCount: settings.maxRetryCount ?? 5,
+        };
+        const { appWidth, appHeight, deviceLogicalPixelRatio, devicePhysicalPixelRatio, inspector, } = settings;
+        let platform;
+        if (settings.platform !== undefined &&
+            settings.platform !== null &&
+            settings.platform.prototype instanceof Platform === true) {
+            // @ts-ignore - if Platform is a valid class, it will be used
+            platform = new settings.platform();
+        }
+        else {
+            platform = new WebPlatform();
+        }
+        const canvas = settings.canvas || platform.createCanvas();
+        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,
+            appHeight,
+            boundsMargin: settings.boundsMargin,
+            clearColor: settings.clearColor,
+            canvas: this.canvas,
+            deviceLogicalPixelRatio,
+            devicePhysicalPixelRatio,
+            enableContextSpy: settings.enableContextSpy,
+            forceWebGL2: settings.forceWebGL2,
+            fpsUpdateInterval: settings.fpsUpdateInterval,
+            enableClear: settings.enableClear,
+            numImageWorkers: settings.numImageWorkers,
+            renderEngine: settings.renderEngine,
+            textureMemory: resolvedTxSettings,
+            eventBus: this,
+            quadBufferSize: settings.quadBufferSize,
+            fontEngines: settings.fontEngines,
+            inspector: settings.inspector !== null,
+            targetFPS: settings.targetFPS,
+            textureProcessingTimeLimit: settings.textureProcessingTimeLimit,
+            createImageBitmapSupport: settings.createImageBitmapSupport,
+            platform,
+            maxRetryCount: settings.maxRetryCount ?? 5,
+        });
+        // Extract the root node
+        this.root = this.stage.root;
+        // Get the target element and attach the canvas to it
+        if (target) {
+            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);
+        }
+        else if (settings.canvas !== canvas) {
+            throw new Error('New canvas element could not be appended to undefined target');
+        }
+        // Initialize inspector (if enabled)
+        if (inspector && isProductionEnvironment === false) {
+            this.inspector = new inspector(canvas, settings);
+        }
+    }
+    /**
+     * Resolves the Texture Memory Manager values
+     *
+     * @param props
+     * @returns
+     */
+    resolveTxSettings(textureMemory) {
+        const currentTxSettings = (this.stage && this.stage.options.textureMemory) || {};
+        return {
+            criticalThreshold: textureMemory?.criticalThreshold ??
+                currentTxSettings?.criticalThreshold ??
+                200e6,
+            targetThresholdLevel: textureMemory?.targetThresholdLevel ??
+                currentTxSettings?.targetThresholdLevel ??
+                0.8,
+            cleanupInterval: textureMemory?.cleanupInterval ??
+                currentTxSettings?.cleanupInterval ??
+                5000,
+            debugLogging: textureMemory?.debugLogging ?? currentTxSettings?.debugLogging ?? false,
+            baselineMemoryAllocation: textureMemory?.baselineMemoryAllocation ??
+                currentTxSettings?.baselineMemoryAllocation ??
+                26e6,
+            doNotExceedCriticalThreshold: textureMemory?.doNotExceedCriticalThreshold ??
+                currentTxSettings?.doNotExceedCriticalThreshold ??
+                false,
+        };
+    }
+    /**
+     * 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 (!isProductionEnvironment && this.inspector) {
+            return this.inspector.createNode(node);
+        }
+        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 (!isProductionEnvironment && this.inspector) {
+            return this.inspector.createTextNode(textNode);
+        }
+        return textNode;
+    }
+    /**
+     * Destroy a node
+     *
+     * @remarks
+     * This method destroys a node
+     *
+     * @param node
+     * @returns
+     */
+    destroyNode(node) {
+        if (!isProductionEnvironment && 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() {
+        this.stage.cleanup();
+    }
+    /**
+     * Sets the clear color for the stage.
+     *
+     * @param color - The color to set as the clear color.
+     */
+    setClearColor(color) {
+        this.stage.setClearColor(color);
+    }
+    /**
+     * Set options for the renderer
+     *
+     * @param options
+     */
+    setOptions(options) {
+        const stage = this.stage;
+        if (options.textureMemory !== undefined) {
+            const textureMemory = (options.textureMemory = this.resolveTxSettings(options.textureMemory));
+            stage.txMemManager.updateSettings(textureMemory);
+            stage.txMemManager.cleanup();
+        }
+        if (options.boundsMargin !== undefined) {
+            let bm = options.boundsMargin;
+            options.boundsMargin = Array.isArray(bm) ? bm : [bm, bm, bm, bm];
+        }
+        const stageOptions = stage.options;
+        for (let key in options) {
+            stageOptions[key] = options[key];
+        }
+        if (options.inspector !== undefined && !isProductionEnvironment) {
+            if (options.inspector === false) {
+                this.inspector?.destroy();
+                this.inspector = null;
+            }
+            else if (this.inspector === null ||
+                this.inspector.constructor !== options.inspector) {
+                this.inspector = new options.inspector(this.canvas, stage.options);
+                this.inspector?.createNodes(this.root);
+            }
+        }
+        let needDimensionsUpdate = false;
+        if (options.deviceLogicalPixelRatio ||
+            options.devicePhysicalPixelRatio !== undefined) {
+            this.stage.pixelRatio =
+                stageOptions.devicePhysicalPixelRatio *
+                    stageOptions.deviceLogicalPixelRatio;
+            this.inspector?.updateViewport(stageOptions.appWidth, stageOptions.appHeight, stageOptions.deviceLogicalPixelRatio);
+            needDimensionsUpdate = true;
+        }
+        if (options.appWidth !== undefined || options.appHeight !== undefined) {
+            this.inspector?.updateViewport(stageOptions.appWidth, stageOptions.appHeight, stageOptions.deviceLogicalPixelRatio);
+            needDimensionsUpdate = true;
+        }
+        if (options.boundsMargin !== undefined) {
+            this.stage.setBoundsMargin(options.boundsMargin);
+        }
+        if (options.clearColor !== undefined) {
+            this.stage.setClearColor(options.clearColor);
+        }
+        if (needDimensionsUpdate) {
+            this.updateAppDimensions();
+        }
+    }
+    updateAppDimensions() {
+        const { appWidth, appHeight, deviceLogicalPixelRatio, devicePhysicalPixelRatio, } = this.stage.options;
+        const deviceLogicalWidth = appWidth * deviceLogicalPixelRatio;
+        const deviceLogicalHeight = appHeight * deviceLogicalPixelRatio;
+        this.canvas.width = deviceLogicalWidth * devicePhysicalPixelRatio;
+        this.canvas.height = deviceLogicalHeight * devicePhysicalPixelRatio;
+        this.canvas.style.width = `${deviceLogicalWidth}px`;
+        this.canvas.style.height = `${deviceLogicalHeight}px`;
+        this.stage.renderer.updateViewport();
+        this.root.w = appWidth;
+        this.root.h = appHeight;
+        this.stage.updateViewportBounds();
+    }
+    get settings() {
+        return this.stage.options;
+    }
+    /**
+     * 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 || 0;
+    }
+    /**
+     * 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/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,123 @@
+import type { ContextSpy } from './core/lib/ContextSpy.js';
+export declare function createWebGLContext(canvas: HTMLCanvasElement | OffscreenCanvas, forceWebGL2: boolean | undefined, contextSpy: ContextSpy | null): WebGLRenderingContext;
+export declare const isProductionEnvironment: boolean;
+export declare const USE_RTT: boolean;
+export declare const RENDER_TEXT_BATCHING: boolean;
+export declare const ENABLE_AUTOSIZE: boolean;
+export declare const ENABLE_COMPRESSED_TEXTURES: boolean;
+export declare const CALCULATE_FPS: boolean;
+export declare const DIRTY_QUAD_BUFFER: boolean;
+export declare const EMIT_BOUNDS_EVENTS: boolean;
+/**
+ * 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;
+/**
+ * Optimized version of {@link mergeColorAlphaPremultiplied} that always
+ * outputs ABGR (for shader attributes) and uses bitwise truncation (`| 0`)
+ * instead of `Math.trunc`.
+ *
+ * @internal
+ * @param rgba RGBA encoded color
+ * @param alpha Normalized alpha (0.0 – 1.0)
+ * @returns ABGR encoded premultiplied color
+ */
+export declare function premultiplyColorABGR(rgba: number, alpha: number): 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;
+export declare function getNewId(): number;
+/**
+ * Makes a deep clone of an object
+ * @param object
+ * @returns
+ */
+export declare function deepClone<T>(obj: T): T;