@lightningjs/renderer 0.9.4 → 1.0.0-rc.1

package/dist/src/core/CoreTextureManager.js

@@ -16,7 +16,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { assertTruthy } from '../utils.js';
 import { ImageWorkerManager } from './lib/ImageWorker.js';
 import { ColorTexture } from './textures/ColorTexture.js';
 import { ImageTexture } from './textures/ImageTexture.js';
@@ -25,14 +24,17 @@ import { SubTexture } from './textures/SubTexture.js';
 import { RenderTexture } from './textures/RenderTexture.js';
 export class CoreTextureManager {
     /**
-     * Amount of used memory defined in pixels
+     * Map of textures by cache key
+     */
+    keyCache = new Map();
+    /**
+     * Map of cache keys by texture
+     */
+    inverseKeyCache = new WeakMap();
+    /**
+     * Map of texture constructors by their type name
      */
-    usedMemory = 0;
     txConstructors = {};
-    textureKeyCache = new Map();
-    textureIdCache = new Map();
-    ctxTextureCache = new WeakMap();
-    textureRefCountMap = new WeakMap();
     imageWorkerManager = null;
     hasCreateImageBitmap = !!self.createImageBitmap;
     hasWorker = !!self.Worker;
@@ -44,6 +46,16 @@ export class CoreTextureManager {
      * will occur when using the texture manager.
      */
     renderer;
+    /**
+     * The current frame time in milliseconds
+     *
+     * @remarks
+     * This is used to populate the `lastRenderableChangeTime` property of
+     * {@link Texture} instances when their renderable state changes.
+     *
+     * Set by stage via `updateFrameTime` method.
+     */
+    frameTime = 0;
     constructor(numImageWorkers) {
         // Register default known texture types
         if (this.hasCreateImageBitmap && this.hasWorker && numImageWorkers > 0) {
@@ -61,147 +73,48 @@ export class CoreTextureManager {
     registerTextureType(textureType, textureClass) {
         this.txConstructors[textureType] = textureClass;
     }
-    loadTexture(textureType, props, options = null) {
+    loadTexture(textureType, props) {
+        let texture;
         const TextureClass = this.txConstructors[textureType];
         if (!TextureClass) {
             throw new Error(`Texture type "${textureType}" is not registered`);
         }
-        let texture;
-        // If an ID is specified, try to get the texture from the ID cache first
-        if (options?.id !== undefined && this.textureIdCache.has(options.id)) {
-            // console.log('Getting texture by texture desc ID', options.id);
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            texture = this.textureIdCache.get(options.id);
-        }
-        // If the texture is not found in the ID cache, try to get it from the key cache
         if (!texture) {
-            const descId = options?.id;
-            const cacheKey = options?.cacheKey ?? TextureClass.makeCacheKey(props);
-            if (cacheKey && this.textureKeyCache.has(cacheKey)) {
+            const cacheKey = TextureClass.makeCacheKey(props);
+            if (cacheKey && this.keyCache.has(cacheKey)) {
                 // console.log('Getting texture by cache key', cacheKey);
                 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                texture = this.textureKeyCache.get(cacheKey);
+                texture = this.keyCache.get(cacheKey);
             }
             else {
                 // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any
                 texture = new TextureClass(this, props);
-            }
-            if (descId) {
-                this.addTextureIdToCache(descId, cacheKey, texture);
-            }
-        }
-        if (options?.preload) {
-            const ctxTx = this.getCtxTexture(texture);
-            ctxTx.load();
-        }
-        return texture;
-    }
-    /**
-     * Add a `Texture` to the texture cache by its texture desc ID and cache key
-     *
-     * @remarks
-     * This is used internally by the `CoreTextureManager` to cache textures
-     * when they are created.
-     *
-     * It handles updating the texture ID cache, texture key cache, and texture
-     * reference count map.
-     *
-     * @param textureDescId
-     * @param cacheKey
-     * @param texture
-     */
-    addTextureIdToCache(textureDescId, cacheKey, texture) {
-        const { textureIdCache, textureRefCountMap } = this;
-        textureIdCache.set(textureDescId, texture);
-        if (textureRefCountMap.has(texture)) {
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            textureRefCountMap.get(texture).count++;
-        }
-        else {
-            textureRefCountMap.set(texture, { cacheKey, count: 1 });
-            if (cacheKey) {
-                this.textureKeyCache.set(cacheKey, texture);
-            }
-        }
-    }
-    /**
-     * Remove a `Texture` from the texture cache by its texture desc ID
-     *
-     * @remarks
-     * This is called externally by when we know (at least reasonably well) that
-     * the `TextureRef` in the Main API space has been is no longer used. This
-     * allows us to remove the `Texture` from the Usage Cache so that it can be
-     * garbage collected as well.
-     *
-     * @param textureDescId
-     */
-    removeTextureIdFromCache(textureDescId) {
-        const { textureIdCache, textureRefCountMap } = this;
-        const texture = textureIdCache.get(textureDescId);
-        if (!texture) {
-            // Sometimes a texture is removed from the cache before it ever gets
-            // added to the cache. This is fine and not an error.
-            return;
-        }
-        textureIdCache.delete(textureDescId);
-        if (textureRefCountMap.has(texture)) {
-            const refCountObj = textureRefCountMap.get(texture);
-            assertTruthy(refCountObj);
-            refCountObj.count--;
-            if (refCountObj.count === 0) {
-                textureRefCountMap.delete(texture);
-                // If the texture is not referenced anywhere else, remove it from the key cache
-                // as well.
-                // This should allow the `Texture` instance to be garbage collected.
-                if (refCountObj.cacheKey) {
-                    this.textureKeyCache.delete(refCountObj.cacheKey);
+                if (cacheKey) {
+                    this.initTextureToCache(texture, cacheKey);
                 }
             }
         }
-        // Free the ctx texture if it exists.
-        this.ctxTextureCache.get(texture)?.free();
+        return texture;
     }
-    /**
-     * Get an object containing debug information about the texture manager.
-     *
-     * @returns
-     */
-    getDebugInfo() {
-        // const textureSet = new Set<Texture>();
-        // for (const texture of this.textureIdCache.values()) {
-        //   textureSet.add(texture);
-        // }
-        // for (const texture of this.textureKeyCache.values()) {
-        //   textureSet.add(texture);
-        // }
-        // TODO: Output number of bytes used by textures
-        return {
-            keyCacheSize: this.textureKeyCache.size,
-            idCacheSize: this.textureIdCache.size,
-        };
+    initTextureToCache(texture, cacheKey) {
+        const { keyCache, inverseKeyCache } = this;
+        keyCache.set(cacheKey, texture);
+        inverseKeyCache.set(texture, cacheKey);
     }
     /**
-     * Get a CoreContextTexture for the given Texture source.
+     * Remove a texture from the cache
      *
      * @remarks
-     * If the texture source already has an allocated CoreContextTexture, it will be
-     * returned from the cache. Otherwise, a new CoreContextTexture will be created
-     * and cached.
-     *
-     * ContextTextures are stored in a WeakMap, so they will be garbage collected
-     * when the Texture source is no longer referenced.
+     * Called by Texture Cleanup when a texture is freed.
      *
-     * @param textureSource
-     * @returns
+     * @param texture
      */
-    getCtxTexture(textureSource) {
-        if (this.ctxTextureCache.has(textureSource)) {
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            return this.ctxTextureCache.get(textureSource);
+    removeTextureFromCache(texture) {
+        const { inverseKeyCache, keyCache } = this;
+        const cacheKey = inverseKeyCache.get(texture);
+        if (cacheKey) {
+            keyCache.delete(cacheKey);
         }
-        const texture = this.renderer.createCtxTexture(textureSource);
-        this.ctxTextureCache.set(textureSource, texture);
-        return texture;
     }
 }
 //# sourceMappingURL=CoreTextureManager.js.map

package/dist/src/core/CoreTextureManager.js.map

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

package/dist/src/core/Stage.d.ts

@@ -1,19 +1,20 @@
 import { AnimationManager } from './animations/AnimationManager.js';
-import { CoreNode } from './CoreNode.js';
+import { CoreNode, type CoreNodeProps } from './CoreNode.js';
 import { CoreTextureManager } from './CoreTextureManager.js';
 import { TrFontManager } from './text-rendering/TrFontManager.js';
-import { CoreShaderManager } from './CoreShaderManager.js';
+import { CoreShaderManager, type ShaderMap } from './CoreShaderManager.js';
 import type { TextRenderer, TextRendererMap, TrProps } from './text-rendering/renderers/TextRenderer.js';
 import { EventEmitter } from '../common/EventEmitter.js';
 import { ContextSpy } from './lib/ContextSpy.js';
 import type { FpsUpdatePayload, FrameTickPayload } from '../common/CommonTypes.js';
-import { TextureMemoryManager } from './TextureMemoryManager.js';
+import { TextureMemoryManager, type TextureMemoryManagerSettings } from './TextureMemoryManager.js';
 import type { CoreRenderer } from './renderers/CoreRenderer.js';
+import type { BaseShaderController } from '../main-api/ShaderController.js';
+import { CoreTextNode, type CoreTextNodeProps } from './CoreTextNode.js';
 export interface StageOptions {
-    rootId: number;
     appWidth: number;
     appHeight: number;
-    txMemByteThreshold: number;
+    textureMemory: TextureMemoryManagerSettings;
     boundsMargin: number | [number, number, number, number];
     deviceLogicalPixelRatio: number;
     devicePhysicalPixelRatio: number;
@@ -23,13 +24,11 @@ export interface StageOptions {
     enableContextSpy: boolean;
     numImageWorkers: number;
     renderMode: 'webgl' | 'canvas';
-    debug?: {
-        monitorTextureCache?: boolean;
-    };
+    eventBus: EventEmitter;
 }
 export type StageFpsUpdateHandler = (stage: Stage, fpsData: FpsUpdatePayload) => void;
 export type StageFrameTickHandler = (stage: Stage, frameTickData: FrameTickPayload) => void;
-export declare class Stage extends EventEmitter {
+export declare class Stage {
     readonly options: StageOptions;
     readonly animationManager: AnimationManager;
     readonly txManager: CoreTextureManager;
@@ -40,17 +39,29 @@ export declare class Stage extends EventEmitter {
     readonly renderer: CoreRenderer;
     readonly root: CoreNode;
     readonly boundsMargin: [number, number, number, number];
+    readonly defShaderCtr: BaseShaderController;
+    /**
+     * Renderer Event Bus for the Stage to emit events onto
+     *
+     * @remarks
+     * In reality this is just the RendererMain instance, which is an EventEmitter.
+     * this allows us to directly emit events from the Stage to RendererMain
+     * without having to set up forwarding handlers.
+     */
+    readonly eventBus: EventEmitter;
     deltaTime: number;
     lastFrameTime: number;
     currentFrameTime: number;
     private fpsNumFrames;
     private fpsElapsedTime;
     private renderRequested;
+    private frameEventQueue;
     contextSpy: ContextSpy | null;
     /**
      * Stage constructor
      */
     constructor(options: StageOptions);
+    updateFrameTime(): void;
     /**
      * Update animations
      */
@@ -63,6 +74,31 @@ export declare class Stage extends EventEmitter {
      * Start a new frame draw
      */
     drawFrame(): void;
+    /**
+     * Queue an event to be emitted after the current/next frame is rendered
+     *
+     * @remarks
+     * When we are operating in the context of the render loop, we may want to
+     * emit events that are related to the current frame. However, we generally do
+     * NOT want to emit events directly in the middle of the render loop, since
+     * this could enable event handlers to modify the scene graph and cause
+     * unexpected behavior. Instead, we queue up events to be emitted and then
+     * flush the queue after the frame has been rendered.
+     *
+     * @param name
+     * @param data
+     */
+    queueFrameEvent(name: string, data: unknown): void;
+    /**
+     * Emit all queued frame events
+     *
+     * @remarks
+     * This method should be called after the frame has been rendered to emit
+     * all events that were queued during the frame.
+     *
+     * See {@link queueFrameEvent} for more information.
+     */
+    flushFrameEvents(): void;
     calculateFps(): void;
     addQuads(node: CoreNode): void;
     /**
@@ -80,4 +116,26 @@ export declare class Stage extends EventEmitter {
      * @returns
      */
     resolveTextRenderer(trProps: TrProps, textRendererOverride?: keyof TextRendererMap | null): TextRenderer;
+    /**
+     * Create a shader controller instance
+     *
+     * @param type
+     * @param props
+     * @returns
+     */
+    createShaderCtr(type: keyof ShaderMap, props: Record<string, unknown>): BaseShaderController;
+    createNode(props: Partial<CoreNodeProps>): CoreNode;
+    createTextNode(props: Partial<CoreTextNodeProps>): CoreTextNode;
+    /**
+     * Resolves the default property values for a Node
+     *
+     * @remarks
+     * This method is used internally by the RendererMain to resolve the default
+     * property values for a Node. It is exposed publicly so that it can be used
+     * by Core Driver implementations.
+     *
+     * @param props
+     * @returns
+     */
+    protected resolveNodeDefaults(props: Partial<CoreNodeProps>): CoreNodeProps;
 }

package/dist/src/core/Stage.js

@@ -28,11 +28,13 @@ import { SdfTextRenderer } from './text-rendering/renderers/SdfTextRenderer/SdfT
 import { CanvasTextRenderer } from './text-rendering/renderers/CanvasTextRenderer.js';
 import { EventEmitter } from '../common/EventEmitter.js';
 import { ContextSpy } from './lib/ContextSpy.js';
-import { TextureMemoryManager } from './TextureMemoryManager.js';
+import { TextureMemoryManager, } from './TextureMemoryManager.js';
 import { CanvasCoreRenderer } from './renderers/canvas/CanvasCoreRenderer.js';
+import { CoreTextNode } from './CoreTextNode.js';
+import { santizeCustomDataMap } from '../main-api/utils.js';
 const bufferMemory = 2e6;
 const autoStart = true;
-export class Stage extends EventEmitter {
+export class Stage {
     options;
     /// Module Instances
     animationManager;
@@ -44,6 +46,16 @@ export class Stage extends EventEmitter {
     renderer;
     root;
     boundsMargin;
+    defShaderCtr;
+    /**
+     * Renderer Event Bus for the Stage to emit events onto
+     *
+     * @remarks
+     * In reality this is just the RendererMain instance, which is an EventEmitter.
+     * this allows us to directly emit events from the Stage to RendererMain
+     * without having to set up forwarding handlers.
+     */
+    eventBus;
     /// State
     deltaTime = 0;
     lastFrameTime = 0;
@@ -51,17 +63,18 @@ export class Stage extends EventEmitter {
     fpsNumFrames = 0;
     fpsElapsedTime = 0;
     renderRequested = false;
+    frameEventQueue = [];
     /// Debug data
     contextSpy = null;
     /**
      * Stage constructor
      */
     constructor(options) {
-        super();
         this.options = options;
-        const { canvas, clearColor, rootId, debug, appWidth, appHeight, boundsMargin, enableContextSpy, numImageWorkers, txMemByteThreshold, renderMode, } = options;
+        const { canvas, clearColor, appWidth, appHeight, boundsMargin, enableContextSpy, numImageWorkers, textureMemory, renderMode, } = options;
+        this.eventBus = options.eventBus;
         this.txManager = new CoreTextureManager(numImageWorkers);
-        this.txMemManager = new TextureMemoryManager(txMemByteThreshold);
+        this.txMemManager = new TextureMemoryManager(this, textureMemory);
         this.shManager = new CoreShaderManager();
         this.animationManager = new AnimationManager();
         this.contextSpy = enableContextSpy ? new ContextSpy() : null;
@@ -72,14 +85,6 @@ export class Stage extends EventEmitter {
                 : [boundsMargin, boundsMargin, boundsMargin, boundsMargin];
         }
         this.boundsMargin = bm;
-        if (debug?.monitorTextureCache) {
-            setInterval(() => {
-                assertTruthy(this.txManager);
-                const debugInfo = this.txManager.getDebugInfo();
-                console.log('Texture ID Cache Size: ', debugInfo.idCacheSize);
-                console.log('Texture Key Cache Size: ', debugInfo.keyCacheSize);
-            }, 1000);
-        }
         const rendererOptions = {
             stage: this,
             canvas,
@@ -97,6 +102,7 @@ export class Stage extends EventEmitter {
         else {
             this.renderer = new WebGlCoreRenderer(rendererOptions);
         }
+        this.defShaderCtr = this.renderer.getDefShaderCtr();
         setPremultiplyMode(renderMode);
         // Must do this after renderer is created
         this.txManager.renderer = this.renderer;
@@ -112,7 +118,6 @@ export class Stage extends EventEmitter {
         this.fontManager = new TrFontManager(this.textRenderers);
         // create root node
         const rootNode = new CoreNode(this, {
-            id: rootId,
             x: 0,
             y: 0,
             width: appWidth,
@@ -142,10 +147,11 @@ export class Stage extends EventEmitter {
             rotation: 0,
             parent: null,
             texture: null,
-            textureOptions: null,
-            shader: null,
-            shaderProps: null,
+            textureOptions: {},
+            shader: this.defShaderCtr,
             rtt: false,
+            src: null,
+            scale: 1,
         });
         this.root = rootNode;
         // execute platform start loop
@@ -153,6 +159,22 @@ export class Stage extends EventEmitter {
             startLoop(this);
         }
     }
+    updateFrameTime() {
+        const newFrameTime = getTimeStamp();
+        this.lastFrameTime = this.currentFrameTime;
+        this.currentFrameTime = newFrameTime;
+        this.deltaTime = !this.lastFrameTime
+            ? 100 / 6
+            : newFrameTime - this.lastFrameTime;
+        this.txManager.frameTime = newFrameTime;
+        this.txMemManager.frameTime = newFrameTime;
+        // This event is emitted at the beginning of the frame (before any updates
+        // or rendering), so no need to to use `stage.queueFrameEvent` here.
+        this.eventBus.emit('frameTick', {
+            time: this.currentFrameTime,
+            delta: this.deltaTime,
+        });
+    }
     /**
      * Update animations
      */
@@ -161,15 +183,6 @@ export class Stage extends EventEmitter {
         if (!this.root) {
             return;
         }
-        this.lastFrameTime = this.currentFrameTime;
-        this.currentFrameTime = getTimeStamp();
-        this.deltaTime = !this.lastFrameTime
-            ? 100 / 6
-            : this.currentFrameTime - this.lastFrameTime;
-        this.emit('frameTick', {
-            time: this.currentFrameTime,
-            delta: this.deltaTime,
-        });
         // step animation
         animationManager.update(this.deltaTime);
     }
@@ -191,9 +204,9 @@ export class Stage extends EventEmitter {
         }
         // Reset render operations and clear the canvas
         renderer.reset();
-        // Check if we need to garbage collect
-        if (renderer.txMemManager.gcRequested) {
-            renderer.txMemManager.gc();
+        // Check if we need to cleanup textures
+        if (this.txMemManager.criticalCleanupRequested) {
+            this.txMemManager.cleanup();
         }
         // If we have RTT nodes draw them first
         // So we can use them as textures in the main scene
@@ -210,6 +223,38 @@ export class Stage extends EventEmitter {
             this.renderRequested = false;
         }
     }
+    /**
+     * Queue an event to be emitted after the current/next frame is rendered
+     *
+     * @remarks
+     * When we are operating in the context of the render loop, we may want to
+     * emit events that are related to the current frame. However, we generally do
+     * NOT want to emit events directly in the middle of the render loop, since
+     * this could enable event handlers to modify the scene graph and cause
+     * unexpected behavior. Instead, we queue up events to be emitted and then
+     * flush the queue after the frame has been rendered.
+     *
+     * @param name
+     * @param data
+     */
+    queueFrameEvent(name, data) {
+        this.frameEventQueue.push([name, data]);
+    }
+    /**
+     * Emit all queued frame events
+     *
+     * @remarks
+     * This method should be called after the frame has been rendered to emit
+     * all events that were queued during the frame.
+     *
+     * See {@link queueFrameEvent} for more information.
+     */
+    flushFrameEvents() {
+        for (const [name, data] of this.frameEventQueue) {
+            this.eventBus.emit(name, data);
+        }
+        this.frameEventQueue = [];
+    }
     calculateFps() {
         // If there's an FPS update interval, emit the FPS update event
         // when the specified interval has elapsed.
@@ -221,7 +266,7 @@ export class Stage extends EventEmitter {
                 const fps = Math.round((this.fpsNumFrames * 1000) / this.fpsElapsedTime);
                 this.fpsNumFrames = 0;
                 this.fpsElapsedTime = 0;
-                this.emit('fpsUpdate', {
+                this.queueFrameEvent('fpsUpdate', {
                     fps,
                     contextSpyData: this.contextSpy?.getData() ?? null,
                 });
@@ -305,5 +350,104 @@ export class Stage extends EventEmitter {
         // the covariant state argument in the setter method map
         return resolvedTextRenderer;
     }
+    /**
+     * Create a shader controller instance
+     *
+     * @param type
+     * @param props
+     * @returns
+     */
+    createShaderCtr(type, props) {
+        return this.shManager.loadShader(type, props);
+    }
+    createNode(props) {
+        const resolvedProps = this.resolveNodeDefaults(props);
+        return new CoreNode(this, resolvedProps);
+    }
+    createTextNode(props) {
+        const fontSize = props.fontSize ?? 16;
+        const resolvedProps = {
+            ...this.resolveNodeDefaults(props),
+            text: props.text ?? '',
+            textRendererOverride: props.textRendererOverride ?? null,
+            fontSize,
+            fontFamily: props.fontFamily ?? 'sans-serif',
+            fontStyle: props.fontStyle ?? 'normal',
+            fontWeight: props.fontWeight ?? 'normal',
+            fontStretch: props.fontStretch ?? 'normal',
+            textAlign: props.textAlign ?? 'left',
+            contain: props.contain ?? 'none',
+            scrollable: props.scrollable ?? false,
+            scrollY: props.scrollY ?? 0,
+            offsetY: props.offsetY ?? 0,
+            letterSpacing: props.letterSpacing ?? 0,
+            lineHeight: props.lineHeight,
+            maxLines: props.maxLines ?? 0,
+            textBaseline: props.textBaseline ?? 'alphabetic',
+            verticalAlign: props.verticalAlign ?? 'middle',
+            overflowSuffix: props.overflowSuffix ?? '...',
+            debug: props.debug ?? {},
+            shaderProps: null,
+        };
+        return new CoreTextNode(this, resolvedProps);
+    }
+    /**
+     * Resolves the default property values for a Node
+     *
+     * @remarks
+     * This method is used internally by the RendererMain to resolve the default
+     * property values for a Node. It is exposed publicly so that it can be used
+     * by Core Driver implementations.
+     *
+     * @param props
+     * @returns
+     */
+    resolveNodeDefaults(props) {
+        const color = props.color ?? 0xffffffff;
+        const colorTl = props.colorTl ?? props.colorTop ?? props.colorLeft ?? color;
+        const colorTr = props.colorTr ?? props.colorTop ?? props.colorRight ?? color;
+        const colorBl = props.colorBl ?? props.colorBottom ?? props.colorLeft ?? color;
+        const colorBr = props.colorBr ?? props.colorBottom ?? props.colorRight ?? color;
+        const data = santizeCustomDataMap(props.data ?? {});
+        return {
+            x: props.x ?? 0,
+            y: props.y ?? 0,
+            width: props.width ?? 0,
+            height: props.height ?? 0,
+            alpha: props.alpha ?? 1,
+            autosize: props.autosize ?? false,
+            clipping: props.clipping ?? false,
+            color,
+            colorTop: props.colorTop ?? color,
+            colorBottom: props.colorBottom ?? color,
+            colorLeft: props.colorLeft ?? color,
+            colorRight: props.colorRight ?? color,
+            colorBl,
+            colorBr,
+            colorTl,
+            colorTr,
+            zIndex: props.zIndex ?? 0,
+            zIndexLocked: props.zIndexLocked ?? 0,
+            parent: props.parent ?? null,
+            texture: props.texture ?? null,
+            textureOptions: props.textureOptions ?? {},
+            shader: props.shader ?? this.defShaderCtr,
+            // Since setting the `src` will trigger a texture load, we need to set it after
+            // we set the texture. Otherwise, problems happen.
+            src: props.src ?? null,
+            scale: props.scale ?? null,
+            scaleX: props.scaleX ?? props.scale ?? 1,
+            scaleY: props.scaleY ?? props.scale ?? 1,
+            mount: props.mount ?? 0,
+            mountX: props.mountX ?? props.mount ?? 0,
+            mountY: props.mountY ?? props.mount ?? 0,
+            pivot: props.pivot ?? 0.5,
+            pivotX: props.pivotX ?? props.pivot ?? 0.5,
+            pivotY: props.pivotY ?? props.pivot ?? 0.5,
+            rotation: props.rotation ?? 0,
+            rtt: props.rtt ?? false,
+            data: data,
+        };
+    }
 }
 //# sourceMappingURL=Stage.js.map