@lightningjs/renderer 3.0.0-beta18 → 3.0.0-beta19

package/src/core/textures/SubTexture.ts

@@ -30,6 +30,8 @@ import {
   type TextureState,
 } from './Texture.js';
 
+let subTextureId = 0;
+
 /**
  * Properties of the {@link SubTexture}
  */
@@ -83,10 +85,11 @@ export class SubTexture extends Texture {
   parentTexture: Texture;
 
   public override type: TextureType = TextureType.subTexture;
+  public subtextureId = `subtexture-${subTextureId++}`;
 
-  constructor(txManager: CoreTextureManager, props: SubTextureProps) {
+  constructor(txManager: CoreTextureManager, props: Required<SubTextureProps>) {
     super(txManager);
-    this.props = SubTexture.resolveDefaults(props || {});
+    this.props = props;
 
     assertTruthy(this.props.texture, 'SubTexture requires a parent texture');
     assertTruthy(
@@ -97,8 +100,8 @@ export class SubTexture extends Texture {
     // Resolve parent texture from cache or fallback to provided texture
     this.parentTexture = txManager.resolveParentTexture(this.props.texture);
 
-    if (this.renderableOwners.size > 0) {
-      this.parentTexture.setRenderableOwner(this, true);
+    if (this.renderableOwners.length > 0) {
+      this.parentTexture.setRenderableOwner(this.subtextureId, true);
     }
 
     // If parent texture is already loaded / failed, trigger loaded event manually
@@ -107,23 +110,17 @@ export class SubTexture extends Texture {
     // synchronous task after calling loadTexture()
     queueMicrotask(() => {
       const parentTx = this.parentTexture;
-      if (parentTx.state === 'loaded') {
-        this.onParentTxLoaded(parentTx, parentTx.dimensions!);
-      } else if (parentTx.state === 'fetching') {
-        this.onParentTxFetching();
-      } else if (parentTx.state === 'fetched') {
-        this.onParentTxFetched();
+      if (parentTx.state === 'loaded' && parentTx.dimensions !== null) {
+        this.onParentTxLoaded(parentTx, parentTx.dimensions);
       } else if (parentTx.state === 'loading') {
         this.onParentTxLoading();
-      } else if (parentTx.state === 'failed') {
-        this.onParentTxFailed(parentTx, parentTx.error!);
+      } else if (parentTx.state === 'failed' && parentTx.error !== null) {
+        this.onParentTxFailed(parentTx, parentTx.error);
       } else if (parentTx.state === 'freed') {
         this.onParentTxFreed();
       }
 
-      parentTx.on('fetched', this.onParentTxFetched);
       parentTx.on('loading', this.onParentTxLoading);
-      parentTx.on('fetching', this.onParentTxFetching);
       parentTx.on('loaded', this.onParentTxLoaded);
       parentTx.on('failed', this.onParentTxFailed);
       parentTx.on('freed', this.onParentTxFreed);
@@ -133,51 +130,33 @@ export class SubTexture extends Texture {
   private onParentTxLoaded: TextureLoadedEventHandler = () => {
     // We ignore the parent's passed dimensions, and simply use the SubTexture's
     // configured dimensions (because that's all that matters here)
-    this.forwardParentTxState('loaded', {
+    this.setState('loaded', {
       w: this.props.w,
       h: this.props.h,
     });
   };
 
   private onParentTxFailed: TextureFailedEventHandler = (target, error) => {
-    this.forwardParentTxState('failed', error);
-  };
-
-  private onParentTxFetched = () => {
-    this.forwardParentTxState('fetched', {
-      w: this.props.w,
-      h: this.props.h,
-    });
-  };
-
-  private onParentTxFetching = () => {
-    this.forwardParentTxState('fetching');
+    this.retryCount = this.parentTexture.retryCount - 1;
+    this.setState('failed', error);
   };
 
   private onParentTxLoading = () => {
-    this.forwardParentTxState('loading');
+    this.setState('loading');
   };
 
   private onParentTxFreed = () => {
-    this.forwardParentTxState('freed');
+    this.setState('freed');
   };
 
-  private forwardParentTxState(
-    state: TextureState,
-    errorOrDimensions?: Error | Dimensions,
-  ) {
-    this.setState(state, errorOrDimensions);
-  }
-
   override onChangeIsRenderable(isRenderable: boolean): void {
     // Propagate the renderable owner change to the parent texture
-    this.parentTexture.setRenderableOwner(this, isRenderable);
+    this.parentTexture.setRenderableOwner(this.subtextureId, isRenderable);
   }
 
   override async getTextureSource(): Promise<TextureData> {
     // Check if parent texture is loaded
     return new Promise((resolve, reject) => {
-      this.setState('fetched');
       resolve({
         data: this.props,
       });

package/src/core/textures/Texture.ts

@@ -54,12 +54,12 @@ export interface CompressedData {
   /**
    * All mipmap levels
    */
-  mipmaps?: ArrayBuffer[];
+  mipmaps: ArrayBuffer[];
 
   /**
    * Supported container types ('pvr' or 'ktx').
    */
-  type: 'pvr' | 'ktx';
+  type: 'pvr' | 'ktx' | 'astc';
 
   /**
    * The width of the compressed texture in pixels. Defaults to 0.
@@ -72,6 +72,15 @@ export interface CompressedData {
    * The height of the compressed texture in pixels.
    **/
   h: number;
+
+  /**
+   * block info compressed texture format
+   */
+  blockInfo: {
+    width: number;
+    height: number;
+    bytes: number;
+  };
 }
 
 /**
@@ -144,16 +153,10 @@ export abstract class Texture extends EventEmitter {
   private _dimensions: Dimensions | null = null;
   private _error: Error | null = null;
 
-  /**
-   * Texture states that are considered transitional and should be skipped during cleanup
-   */
-  public static readonly TRANSITIONAL_TEXTURE_STATES: readonly TextureState[] =
-    ['fetching', 'fetched', 'loading'];
-
   // aggregate state
   public state: TextureState = 'initial';
 
-  readonly renderableOwners = new Set<unknown>();
+  readonly renderableOwners: any[] = [];
 
   readonly renderable: boolean = false;
 
@@ -165,8 +168,37 @@ export abstract class Texture extends EventEmitter {
 
   public textureData: TextureData | null = null;
 
+  public memUsed = 0;
+
+  /**
+   * Memory used by this texture in bytes
+   *
+   * @remarks
+   * This is tracked by the TextureMemoryManager and updated when the texture
+   * is loaded/freed. Set to 0 when texture is not loaded.
+   */
+  public retryCount = 0;
+  public maxRetryCount: number;
+
+  /**
+   * Timestamp when texture was created (for startup grace period)
+   */
+  private createdAt: number = Date.now();
+
+  /**
+   * Flag to track if grace period has expired to avoid repeated Date.now() calls
+   */
+  private gracePeriodExpired: boolean = false;
+
+  /**
+   * Grace period in milliseconds to prevent premature cleanup during app startup
+   * This helps prevent race conditions when bounds calculation is delayed
+   */
+  private static readonly STARTUP_GRACE_PERIOD = 2000; // 2 seconds
+
   constructor(protected txManager: CoreTextureManager) {
     super();
+    this.maxRetryCount = this.txManager.maxRetryCount;
   }
 
   get dimensions(): Dimensions | null {
@@ -177,6 +209,59 @@ export abstract class Texture extends EventEmitter {
     return this._error;
   }
 
+  /**
+   * Checks if the texture is within the startup grace period.
+   * During this period, textures are protected from cleanup to prevent
+   * race conditions during app initialization.
+   */
+  isWithinStartupGracePeriod(): boolean {
+    // If grace period already expired, return false immediately
+    if (this.gracePeriodExpired === true) {
+      return false;
+    }
+
+    // Check if grace period has expired now
+    const hasExpired =
+      Date.now() - this.createdAt >= Texture.STARTUP_GRACE_PERIOD;
+
+    if (hasExpired) {
+      // Cache the result to avoid future Date.now() calls
+      this.gracePeriodExpired = true;
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Checks if the texture can be safely cleaned up.
+   * Considers the renderable state, startup grace period, and renderable owners.
+   */
+  canBeCleanedUp(): boolean {
+    // Never cleanup if explicitly prevented
+    if (this.preventCleanup) {
+      return false;
+    }
+
+    // Don't cleanup if still within startup grace period
+    if (this.isWithinStartupGracePeriod()) {
+      return false;
+    }
+
+    // Don't cleanup if not renderable
+    if (this.renderable === true) {
+      return false;
+    }
+
+    // Don't cleanup if there are still renderable owners
+    if (this.renderableOwners.length > 0) {
+      return false;
+    }
+
+    // Safe to cleanup
+    return true;
+  }
+
   /**
    * Add/remove an owner to/from the Texture based on its renderability.
    *
@@ -191,33 +276,43 @@ export abstract class Texture extends EventEmitter {
    * @param owner
    * @param renderable
    */
-  setRenderableOwner(owner: unknown, renderable: boolean): void {
-    const oldSize = this.renderableOwners.size;
+  setRenderableOwner(owner: string | number, renderable: boolean): void {
+    const oldSize = this.renderableOwners.length;
+    const hasOwnerIndex = this.renderableOwners.indexOf(owner);
 
     if (renderable === true) {
-      if (this.renderableOwners.has(owner) === false) {
+      if (hasOwnerIndex === -1) {
         // Add the owner to the set
-        this.renderableOwners.add(owner);
+        this.renderableOwners.push(owner);
       }
 
-      const newSize = this.renderableOwners.size;
-      if (newSize > oldSize && newSize === 1) {
+      const newSize = this.renderableOwners.length;
+      if (oldSize !== newSize && newSize === 1) {
         (this.renderable as boolean) = true;
         this.onChangeIsRenderable?.(true);
         this.load();
       }
     } else {
-      this.renderableOwners.delete(owner);
-      const newSize = this.renderableOwners.size;
-      if (newSize < oldSize && newSize === 0) {
+      if (hasOwnerIndex !== -1) {
+        this.renderableOwners.splice(hasOwnerIndex, 1);
+      }
+
+      const newSize = this.renderableOwners.length;
+      if (oldSize !== newSize && newSize === 0) {
         (this.renderable as boolean) = false;
         this.onChangeIsRenderable?.(false);
-        this.txManager.orphanTexture(this);
+
+        // note, not doing a cleanup here, cleanup is managed by the Stage/TextureMemoryManager
+        // when it deems appropriate based on memory pressure
       }
     }
   }
 
   load(): void {
+    if (this.retryCount > this.maxRetryCount) {
+      // We've exceeded the max retry count, do not attempt to load again
+      return;
+    }
     this.txManager.loadTexture(this);
   }
 
@@ -256,6 +351,18 @@ export abstract class Texture extends EventEmitter {
     this.ctxTexture?.free();
   }
 
+  /**
+   * Release the texture data and core context texture for this Texture without changing state.
+   *
+   * @remarks
+   * The ctxTexture is created by the renderer and lives on the GPU.
+   */
+  release(): void {
+    this.ctxTexture?.release();
+    this.ctxTexture = undefined;
+    this.freeTextureData();
+  }
+
   /**
    * Destroy the texture.
    *
@@ -281,7 +388,7 @@ export abstract class Texture extends EventEmitter {
    * e.g. ImageData that is downloaded from a URL.
    */
   freeTextureData(): void {
-    this.textureData = null;
+    queueMicrotask(this.freeTextureDataTask);
   }
 
   public setState(
@@ -308,6 +415,18 @@ export abstract class Texture extends EventEmitter {
     } else if (state === 'failed') {
       this._error = errorOrDimensions as Error;
       payload = this._error;
+
+      // increment the retry count for the texture
+      // this is used to compare against maxRetryCount, if set
+      // to determine if we should try loading again
+      this.retryCount += 1;
+
+      queueMicrotask(this.releaseTask);
+    } else if (state === 'loading') {
+      this._error = null;
+      this._dimensions = null;
+    } else {
+      this._error = null;
     }
 
     // emit the new state
@@ -333,6 +452,26 @@ export abstract class Texture extends EventEmitter {
     return this.textureData;
   }
 
+  /**
+   * Task for queueMicrotask to free texture data.
+   *
+   * @remarks
+   * This method is called in a microtask to free the texture data.
+   */
+  private freeTextureDataTask = (): void => {
+    this.textureData = null;
+  };
+
+  /**
+   * Task for queueMicrotask to release the texture.
+   *
+   * @remarks
+   * This method is called in a microtask to release the texture.
+   */
+  private releaseTask = (): void => {
+    this.release();
+  };
+
   /**
    * Get the texture source for this texture.
    *

package/src/main-api/Renderer.ts

@@ -425,6 +425,20 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    * @defaultValue `null`
    */
   platform: typeof Platform | null;
+
+  /**
+   * Number of times to retry loading a failed texture
+   *
+   * @remarks
+   * When a texture fails to load, Lightning will retry up to this many times
+   * before permanently giving up. Each retry will clear the texture ownership
+   * and then re-establish it to trigger a new load attempt.
+   *
+   * Set to null to disable retries. Set to 0 to always try once and never retry.
+   * This is typically only used on ImageTexture instances.
+   *
+   */
+  maxRetryCount?: number;
 };
 
 /**
@@ -493,7 +507,7 @@ export class RendererMain extends EventEmitter {
    */
   constructor(
     settings: Partial<RendererMainSettings>,
-    target: string | HTMLElement,
+    target?: string | HTMLElement,
   ) {
     super();
 
@@ -508,7 +522,7 @@ export class RendererMain extends EventEmitter {
       boundsMargin: settings.boundsMargin || 0,
       deviceLogicalPixelRatio: settings.deviceLogicalPixelRatio || 1,
       devicePhysicalPixelRatio:
-        settings.devicePhysicalPixelRatio || (window.devicePixelRatio || 1),
+        settings.devicePhysicalPixelRatio || window.devicePixelRatio || 1,
       clearColor: settings.clearColor ?? 0x00000000,
       fpsUpdateInterval: settings.fpsUpdateInterval || 0,
       targetFPS: settings.targetFPS || 0,
@@ -525,6 +539,7 @@ export class RendererMain extends EventEmitter {
       canvas: settings.canvas,
       createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
       platform: settings.platform || null,
+      maxRetryCount: settings.maxRetryCount ?? 5,
     };
 
     const {
@@ -582,24 +597,31 @@ export class RendererMain extends EventEmitter {
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit!,
       createImageBitmapSupport: settings.createImageBitmapSupport!,
       platform,
+      maxRetryCount: settings.maxRetryCount ?? 5,
     });
 
     // Extract the root node
     this.root = this.stage.root as unknown as INode;
 
     // Get the target element and attach the canvas to it
-    let targetEl: HTMLElement | null;
-    if (typeof target === 'string') {
-      targetEl = document.getElementById(target);
-    } else {
-      targetEl = target;
-    }
+    if (target) {
+      let targetEl: HTMLElement | null;
+      if (typeof target === 'string') {
+        targetEl = document.getElementById(target);
+      } else {
+        targetEl = target;
+      }
 
-    if (!targetEl) {
-      throw new Error('Could not find target element');
-    }
+      if (!targetEl) {
+        throw new Error('Could not find target element');
+      }
 
-    targetEl.appendChild(canvas);
+      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) {
@@ -832,8 +854,8 @@ export class RendererMain extends EventEmitter {
    * **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: boolean = false) {
-    this.stage.cleanup(aggressive);
+  cleanup() {
+    this.stage.cleanup();
   }
 
   /**

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

@@ -1,29 +0,0 @@
-import type { CoreNode } from './CoreNode.js';
-/**
- * Result of autosize calculation containing the new dimensions
- */
-interface AutosizeResult {
-    width: number;
-    height: number;
-    hasChanged: boolean;
-}
-/**
- * Creates an autosize manager for efficient child bounds calculation
- *
- * @remarks
- * This function creates a closure-based manager that tracks child transform
- * changes and calculates parent dimensions based on children's bounding boxes.
- * It's optimized for performance with minimal allocations and fast lookups.
- *
- * @param parentNode - The autosize parent node
- * @returns Object with autosize management methods
- */
-export declare function createAutosizeManager(parentNode: CoreNode): {
-    addOrUpdateChild: (child: CoreNode) => void;
-    removeChild: (child: CoreNode) => void;
-    calculateAutosize: () => AutosizeResult;
-    deactivate: () => void;
-    readonly active: boolean;
-    readonly childCount: number;
-};
-export {};

package/dist/src/core/AutosizeManager.js

@@ -1,171 +0,0 @@
-/*
- * 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 { Matrix3d } from './lib/Matrix3d.js';
-/**
- * Creates an autosize manager for efficient child bounds calculation
- *
- * @remarks
- * This function creates a closure-based manager that tracks child transform
- * changes and calculates parent dimensions based on children's bounding boxes.
- * It's optimized for performance with minimal allocations and fast lookups.
- *
- * @param parentNode - The autosize parent node
- * @returns Object with autosize management methods
- */
-export function createAutosizeManager(parentNode) {
-    const childDataMap = new Map();
-    let isActive = true;
-    let lastWidth = 0;
-    let lastHeight = 0;
-    let lastHasChanged = false;
-    const corners = [
-        { x: 0, y: 0 },
-        { x: 0, y: 0 },
-        { x: 0, y: 0 },
-        { x: 0, y: 0 },
-    ];
-    /**
-     * Add or update a child node in the autosize calculation chain
-     * @param child - Child node to add or update
-     */
-    const addOrUpdateChild = (child) => {
-        if (isActive === false)
-            return;
-        if (child === parentNode)
-            return; // Avoid circular references
-        const currentTransform = child.localTransform || Matrix3d.identity();
-        const existingData = childDataMap.get(child);
-        if (existingData !== undefined) {
-            // Update existing child
-            Matrix3d.copy(currentTransform, existingData.localTransform);
-            existingData.width = child.w;
-            existingData.height = child.h;
-            existingData.hasChanged = true;
-        }
-        else {
-            // Add new child
-            childDataMap.set(child, {
-                localTransform: Matrix3d.copy(currentTransform),
-                hasChanged: true,
-                width: child.w,
-                height: child.h,
-            });
-        }
-        // Mark parent for recalculation
-        parentNode.autosizeNeedsUpdate = true;
-    };
-    /**
-     * Remove a child node from the autosize calculation chain
-     * @param child - Child node to remove
-     */
-    const removeChild = (child) => {
-        if (childDataMap.delete(child) === true) {
-            parentNode.autosizeNeedsUpdate = true;
-        }
-    };
-    /**
-     * Calculate the autosize dimensions based on all child bounds
-     * @returns Autosize calculation result
-     */
-    const calculateAutosize = () => {
-        if (isActive === false || childDataMap.size === 0) {
-            return { width: 0, height: 0, hasChanged: false };
-        }
-        let hasAnyChildChanged = false;
-        for (const childData of childDataMap.values()) {
-            if (childData.hasChanged) {
-                hasAnyChildChanged = true;
-                break;
-            }
-        }
-        if (hasAnyChildChanged === false) {
-            return {
-                width: lastWidth,
-                height: lastHeight,
-                hasChanged: lastHasChanged,
-            };
-        }
-        let minX = Infinity;
-        let minY = Infinity;
-        let maxX = -Infinity;
-        let maxY = -Infinity;
-        for (const [child, childData] of childDataMap) {
-            if (!child.isRenderable)
-                continue;
-            const transform = child.localTransform || Matrix3d.identity();
-            const width = childData.width;
-            const height = childData.height;
-            corners[0].x = 0;
-            corners[0].y = 0;
-            corners[1].x = width;
-            corners[1].y = 0;
-            corners[2].x = width;
-            corners[2].y = height;
-            corners[3].x = 0;
-            corners[3].y = height;
-            for (let i = 0; i < 4; i++) {
-                const corner = corners[i];
-                const localX = transform.ta * corner.x + transform.tb * corner.y + transform.tx;
-                const localY = transform.tc * corner.x + transform.td * corner.y + transform.ty;
-                if (localX < minX)
-                    minX = localX;
-                if (localY < minY)
-                    minY = localY;
-                if (localX > maxX)
-                    maxX = localX;
-                if (localY > maxY)
-                    maxY = localY;
-            }
-            childData.hasChanged = false;
-        }
-        // Calculate container size based on maximum extent from container origin (0,0)
-        // This ensures the container position remains fixed and only size adjusts
-        const newWidth = maxX > 0 ? maxX : 0;
-        const newHeight = maxY > 0 ? maxY : 0;
-        const dimensionsChanged = lastWidth !== newWidth || lastHeight !== newHeight;
-        lastWidth = newWidth;
-        lastHeight = newHeight;
-        lastHasChanged = dimensionsChanged;
-        return {
-            width: newWidth,
-            height: newHeight,
-            hasChanged: dimensionsChanged,
-        };
-    };
-    /**
-     * Deactivate this autosize manager and clean up resources
-     */
-    const deactivate = () => {
-        isActive = false;
-        childDataMap.clear();
-    };
-    return {
-        addOrUpdateChild,
-        removeChild,
-        calculateAutosize,
-        deactivate,
-        get active() {
-            return isActive;
-        },
-        get childCount() {
-            return childDataMap.size;
-        },
-    };
-}
-//# sourceMappingURL=AutosizeManager.js.map