@lightningjs/renderer 0.3.3 → 0.3.4

package/src/core/renderers/webgl/shaders/DynamicShader.ts

@@ -38,6 +38,44 @@ import { GlitchEffect } from './effects/GlitchEffect.js';
 import { FadeOutEffect } from './effects/FadeOutEffect.js';
 import { RadialGradientEffect } from './effects/RadialGradientEffect.js';
 
+/**
+ * Allows the `keyof EffectMap` to be mapped over and form an discriminated
+ * union of all the EffectDescs structures individually.
+ *
+ * @remarks
+ * When used like the following:
+ * ```
+ * MapEffectDescs<keyof EffectMap>[]
+ * ```
+ * The resultant type will be a discriminated union like so:
+ * ```
+ * (
+ *   {
+ *     type: 'radius',
+ *     props?: {
+ *       radius?: number | number[];
+ *     }
+ *   } |
+ *   {
+ *     type: 'border',
+ *     props?: {
+ *       width?: number;
+ *       color?: number;
+ *     }
+ *   } |
+ *   // ...
+ * )[]
+ * ```
+ * Which means TypeScript will now base its type checking on the `type` field
+ * and will know exactly what the `props` field should be based on the `type`
+ * field.
+ */
+type MapEffectDescs<T extends keyof EffectMap> = T extends keyof EffectMap
+  ? SpecificEffectDesc<T>
+  : never;
+
+type EffectDesc = MapEffectDescs<keyof EffectMap>;
+
 export interface DynamicShaderProps
   extends DimensionsShaderProp,
     AlphaShaderProp {
@@ -72,7 +110,9 @@ const Effects = {
   glitch: GlitchEffect,
 };
 
-export interface EffectDesc<FxType extends keyof EffectMap = keyof EffectMap> {
+export interface SpecificEffectDesc<
+  FxType extends keyof EffectMap = keyof EffectMap,
+> {
   type: FxType;
   props?: ExtractProps<EffectMap[FxType]>;
 }
@@ -325,7 +365,7 @@ export class DynamicShader extends WebGlCoreShader {
       effects: (props.effects ?? []).map((effect) => ({
         type: effect.type,
         props: Effects[effect.type].resolveDefaults(effect.props || {}),
-      })),
+      })) as MapEffectDescs<keyof EffectMap>[],
       $dimensions: {
         width: 0,
         height: 0,

package/src/core/text-rendering/renderers/CanvasTextRenderer.ts

@@ -85,12 +85,18 @@ export interface CanvasTextRendererState extends TextRendererState {
 }
 
 export class CanvasTextRenderer extends TextRenderer<CanvasTextRendererState> {
-  protected canvas: OffscreenCanvas;
-  protected context: OffscreenCanvasRenderingContext2D;
+  protected canvas: OffscreenCanvas | HTMLCanvasElement;
+  protected context:
+    | OffscreenCanvasRenderingContext2D
+    | CanvasRenderingContext2D;
 
   constructor(stage: Stage) {
     super(stage);
-    this.canvas = new OffscreenCanvas(0, 0);
+    if (typeof OffscreenCanvas !== 'undefined') {
+      this.canvas = new OffscreenCanvas(0, 0);
+    } else {
+      this.canvas = document.createElement('canvas');
+    }
     const context = this.canvas.getContext('2d');
     assertTruthy(context);
     this.context = context;

package/src/core/text-rendering/renderers/LightningTextTextureRenderer.ts

@@ -126,14 +126,16 @@ export interface RenderInfo {
 }
 
 export class LightningTextTextureRenderer {
-  private _canvas: OffscreenCanvas;
-  private _context: OffscreenCanvasRenderingContext2D;
+  private _canvas: OffscreenCanvas | HTMLCanvasElement;
+  private _context:
+    | OffscreenCanvasRenderingContext2D
+    | CanvasRenderingContext2D;
   private _settings: Settings;
   private renderInfo: RenderInfo | undefined;
 
   constructor(
-    canvas: OffscreenCanvas,
-    context: OffscreenCanvasRenderingContext2D,
+    canvas: OffscreenCanvas | HTMLCanvasElement,
+    context: OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D,
   ) {
     this._canvas = canvas;
     this._context = context;

package/src/core/textures/SubTexture.ts

@@ -21,7 +21,7 @@ import type {
   TextureFailedEventHandler,
   TextureLoadedEventHandler,
 } from '../../common/CommonTypes.js';
-import type { TextureDesc } from '../../main-api/RendererMain.js';
+import type { TextureRef } from '../../main-api/RendererMain.js';
 import type { CoreTextureManager } from '../CoreTextureManager.js';
 import { Texture } from './Texture.js';
 
@@ -32,7 +32,7 @@ export interface SubTextureProps {
   /**
    * The texture that this sub-texture is a sub-region of.
    */
-  texture: TextureDesc;
+  texture: TextureRef;
 
   /**
    * The x pixel position of the top-left of the sub-texture within the parent

package/src/main-api/INode.ts

@@ -19,7 +19,7 @@
 
 import type { IEventEmitter } from '@lightningjs/threadx';
 import type { IAnimationController } from '../common/IAnimationController.js';
-import type { ShaderDesc, TextureDesc } from './RendererMain.js';
+import type { ShaderRef, TextureRef } from './RendererMain.js';
 import type {
   TextRendererMap,
   TrProps,
@@ -206,7 +206,7 @@ export interface INodeWritableProps {
    * and TBD properties.
    *
    * To create a Texture in order to set it on this property, call
-   * {@link RendererMain.makeTexture}.
+   * {@link RendererMain.createTexture}.
    *
    * If the {@link src} is set on a Node, the Node will use the
    * {@link ImageTexture} by default and the Node will simply load the image at
@@ -215,7 +215,7 @@ export interface INodeWritableProps {
    * Note: If this is a Text Node, the Texture will be managed by the Node's
    * {@link TextRenderer} and should not be set explicitly.
    */
-  texture: TextureDesc | null;
+  texture: TextureRef | null;
   /**
    * The Node's shader
    *
@@ -225,12 +225,12 @@ export interface INodeWritableProps {
    * or {@link color}(s) within the Node without any special effects.
    *
    * To create a Shader in order to set it on this property, call
-   * {@link RendererMain.makeShader}.
+   * {@link RendererMain.createShader}.
    *
    * Note: If this is a Text Node, the Shader will be managed by the Node's
    * {@link TextRenderer} and should not be set explicitly.
    */
-  shader: ShaderDesc | null;
+  shader: ShaderRef | null;
   /**
    * Image URL
    *

package/src/main-api/RendererMain.ts

@@ -31,29 +31,80 @@ import type {
   ITextNodeWritableProps,
 } from './INode.js';
 import type { IRenderDriver } from './IRenderDriver.js';
+import {
+  ManualCountTextureUsageTracker,
+  type ManualCountTextureUsageTrackerOptions,
+} from './texture-usage-trackers/ManualCountTextureUsageTracker.js';
+import { FinalizationRegistryTextureUsageTracker } from './texture-usage-trackers/FinalizationRegistryTextureUsageTracker.js';
+import type { TextureUsageTracker } from './texture-usage-trackers/TextureUsageTracker.js';
 
 /**
- * A description of a Texture
+ * An immutable reference to a specific Texture type
  *
  * @remarks
- * This structure should only be created by the RendererMain's `makeTexture`
- * method. The structure is immutable and should not be modified once created.
+ * See {@link TextureRef} for more details.
  */
-export interface TextureDesc<
-  TxType extends keyof TextureMap = keyof TextureMap,
-> {
+export interface SpecificTextureRef<TxType extends keyof TextureMap> {
   readonly descType: 'texture';
   readonly txType: TxType;
   readonly props: ExtractProps<TextureMap[TxType]>;
   readonly options?: Readonly<TextureOptions>;
 }
 
-export interface ShaderDesc<ShType extends keyof ShaderMap = keyof ShaderMap> {
+type MapTextureRefs<TxType extends keyof TextureMap> =
+  TxType extends keyof TextureMap ? SpecificTextureRef<TxType> : never;
+
+/**
+ * An immutable reference to a Texture
+ *
+ * @remarks
+ * This structure should only be created by the RendererMain's `createTexture`
+ * method. The structure is immutable and should not be modified once created.
+ *
+ * A `TextureRef` exists in the Main API Space and is used to point to an actual
+ * `Texture` instance in the Core API Space. The `TextureRef` is used to
+ * communicate with the Core API Space to create, load, and destroy the
+ * `Texture` instance.
+ *
+ * This type is technically a discriminated union of all possible texture types.
+ * If you'd like to represent a specific texture type, you can use the
+ * `SpecificTextureRef` generic type.
+ */
+export type TextureRef = MapTextureRefs<keyof TextureMap>;
+
+/**
+ * An immutable reference to a specific Shader type
+ *
+ * @remarks
+ * See {@link ShaderRef} for more details.
+ */
+export interface SpecificShaderRef<ShType extends keyof ShaderMap> {
   readonly descType: 'shader';
   readonly shType: ShType;
   readonly props: ExtractProps<ShaderMap[ShType]>;
 }
 
+type MapShaderRefs<ShType extends keyof ShaderMap> =
+  ShType extends keyof ShaderMap ? SpecificShaderRef<ShType> : never;
+
+/**
+ * An immutable reference to a Shader
+ *
+ * @remarks
+ * This structure should only be created by the RendererMain's `createShader`
+ * method. The structure is immutable and should not be modified once created.
+ *
+ * A `ShaderRef` exists in the Main API Space and is used to point to an actual
+ * `Shader` instance in the Core API Space. The `ShaderRef` is used to
+ * communicate with the Core API Space to create, load, and destroy the
+ * `Shader` instance.
+ *
+ * This type is technically a discriminated union of all possible shader types.
+ * If you'd like to represent a specific shader type, you can use the
+ * `SpecificShaderRef` generic type.
+ */
+export type ShaderRef = MapShaderRefs<keyof ShaderMap>;
+
 /**
  * Configuration settings for {@link RendererMain}
  */
@@ -115,8 +166,40 @@ export interface RendererMainSettings {
 
   /**
    * Path to a custom core module to use
+   *
+   * @defaultValue `null`
    */
   coreExtensionModule?: string | null;
+
+  /**
+   * Enable experimental FinalizationRegistry-based texture usage tracking
+   * for texture garbage collection
+   *
+   * @remarks
+   * By default, the Renderer uses a manual reference counting system to track
+   * texture usage. Textures are eventually released from the Core Texture
+   * Manager's Usage Cache when they are no longer referenced by any Nodes (or
+   * SubTextures that are referenced by nodes). This works well enough, but has
+   * the consequence of textures being removed from Usage Cache even if their
+   * references are still alive in memory. This can require a texture to be
+   * reloaded from the source when it is used again after being removed from
+   * cache.
+   *
+   * This is an experimental feature that uses a FinalizationRegistry to track
+   * texture usage. This causes textures to be removed from the Usage Cache only
+   * when their references are no longer alive in memory. Meaning a loaded texture
+   * will remain in the Usage Cache until it's reference is garbage collected.
+   *
+   * This feature is not enabled by default because browser support for the
+   * FinalizationRegistry is limited. It should NOT be enabled in production apps
+   * as this behavior is not guaranteed to be supported in the future. Developer
+   * feedback on this feature, however, is welcome.
+   *
+   * @defaultValue `false`
+   */
+  experimental_FinalizationRegistryTextureUsageTracker?: boolean;
+
+  textureCleanupOptions?: ManualCountTextureUsageTrackerOptions;
 }
 
 /**
@@ -151,11 +234,13 @@ export class RendererMain {
   private nodes: Map<number, INode> = new Map();
   private nextTextureId = 1;
 
-  private textureRegistry = new FinalizationRegistry(
-    (textureDescId: number) => {
-      this.driver.releaseTexture(textureDescId);
-    },
-  );
+  /**
+   * Texture Usage Tracker for Usage Based Texture Garbage Collection
+   *
+   * @remarks
+   * For internal use only. DO NOT ACCESS.
+   */
+  public textureTracker: TextureUsageTracker;
 
   /**
    * Constructs a new Renderer instance
@@ -177,6 +262,9 @@ export class RendererMain {
         settings.devicePhysicalPixelRatio || window.devicePixelRatio,
       clearColor: settings.clearColor ?? 0x00000000,
       coreExtensionModule: settings.coreExtensionModule || null,
+      experimental_FinalizationRegistryTextureUsageTracker:
+        settings.experimental_FinalizationRegistryTextureUsageTracker ?? false,
+      textureCleanupOptions: settings.textureCleanupOptions || {},
     };
     this.settings = resolvedSettings;
 
@@ -187,6 +275,20 @@ export class RendererMain {
       devicePhysicalPixelRatio,
     } = resolvedSettings;
 
+    const releaseCallback = (textureId: number) => {
+      this.driver.releaseTexture(textureId);
+    };
+
+    const useFinalizationRegistryTracker =
+      resolvedSettings.experimental_FinalizationRegistryTextureUsageTracker &&
+      typeof FinalizationRegistry === 'function';
+    this.textureTracker = useFinalizationRegistryTracker
+      ? new FinalizationRegistryTextureUsageTracker(releaseCallback)
+      : new ManualCountTextureUsageTracker(
+          releaseCallback,
+          this.settings.textureCleanupOptions,
+        );
+
     const deviceLogicalWidth = appWidth * deviceLogicalPixelRatio;
     const deviceLogicalHeight = appHeight * deviceLogicalPixelRatio;
 
@@ -373,13 +475,13 @@ export class RendererMain {
    * @param options
    * @returns
    */
-  makeTexture<Type extends keyof TextureMap>(
-    textureType: Type,
-    props: TextureDesc<Type>['props'],
+  createTexture<TxType extends keyof TextureMap>(
+    textureType: TxType,
+    props: SpecificTextureRef<TxType>['props'],
     options?: TextureOptions,
-  ): TextureDesc<Type> {
+  ): SpecificTextureRef<TxType> {
     const id = this.nextTextureId++;
-    const desc: TextureDesc<Type> = {
+    const desc = {
       descType: 'texture',
       txType: textureType,
       props,
@@ -389,8 +491,8 @@ export class RendererMain {
         // ID Texture Map cache.
         id,
       },
-    };
-    this.textureRegistry.register(desc, id);
+    } satisfies SpecificTextureRef<TxType>;
+    this.textureTracker.registerTexture(desc as TextureRef);
     return desc;
   }
 
@@ -407,14 +509,14 @@ export class RendererMain {
    * @param props
    * @returns
    */
-  makeShader<ShType extends keyof ShaderMap>(
+  createShader<ShType extends keyof ShaderMap>(
     shaderType: ShType,
-    props?: ShaderDesc<ShType>['props'],
-  ): ShaderDesc<ShType> {
+    props?: SpecificShaderRef<ShType>['props'],
+  ): SpecificShaderRef<ShType> {
     return {
       descType: 'shader',
       shType: shaderType,
-      props: props as ShaderDesc<ShType>['props'],
+      props: props as SpecificShaderRef<ShType>['props'],
     };
   }
 

package/src/main-api/texture-usage-trackers/FinalizationRegistryTextureUsageTracker.ts

@@ -0,0 +1,45 @@
+/*
+ * 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 { assertTruthy } from '../../utils.js';
+import type { TextureRef } from '../RendererMain.js';
+import { TextureUsageTracker } from './TextureUsageTracker.js';
+
+export class FinalizationRegistryTextureUsageTracker extends TextureUsageTracker {
+  private registry: FinalizationRegistry<number>;
+
+  constructor(releaseCallback: (textureDescId: number) => void) {
+    super(releaseCallback);
+    this.registry = new FinalizationRegistry(releaseCallback);
+  }
+
+  override registerTexture(texture: TextureRef): void {
+    assertTruthy(
+      texture.options?.id,
+      'Texture must have an ID to be registered',
+    );
+    this.registry.register(texture, texture.options?.id);
+  }
+  override incrementTextureRefCount(): void {
+    // No-op for FinalizationRegistry
+  }
+  override decrementTextureRefCount(): void {
+    // No-op for FinalizationRegistry
+  }
+}

package/src/main-api/texture-usage-trackers/ManualCountTextureUsageTracker.ts

@@ -0,0 +1,154 @@
+/*
+ * 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 { assertTruthy } from '../../utils.js';
+import type { TextureRef } from '../RendererMain.js';
+import { TextureUsageTracker } from './TextureUsageTracker.js';
+
+interface TextureRefInfo {
+  /**
+   * Texture Reference ID
+   */
+  id: number;
+  /**
+   * The number of references to this texture that are currently assigned to
+   * Nodes.
+   */
+  nodeRefCount: number;
+  /**
+   * The last time the texture reference count was updated.
+   *
+   * @remarks
+   * This is used to determine when a texture is no longer referenced by any
+   * Nodes and can be removed from the GPU.
+   */
+  lastUpdate: number;
+}
+
+export interface ManualCountTextureUsageTrackerOptions {
+  /**
+   * The interval at which to check if textures that are no longer referenced
+   * by any Nodes can be released from the Core Space Texture Usage Cache.
+   *
+   * @remarks
+   * Only valid when the {@link ManualCountTextureUsageTracker} is used.
+   *
+   * @defaultValue 10000 (10 seconds)
+   */
+  textureCleanupIntervalMs?: number;
+  /**
+   * The age at which a texture is considered to be no longer referenced by any
+   * Nodes and can be released from the Core Space Texture Usage Cache.
+   *
+   * @remarks
+   * Only valid when the {@link ManualCountTextureUsageTracker} is used.
+   *
+   * @defaultValue 60000 (1 minute)
+   */
+  textureCleanupAgeThreadholdMs?: number;
+}
+
+/**
+ * Usage-based Texture Garbage Collection Registry
+ */
+export class ManualCountTextureUsageTracker extends TextureUsageTracker {
+  textureMap: Map<number, TextureRefInfo> = new Map();
+  zeroReferenceTextureSet: Set<TextureRefInfo> = new Set();
+  options: Required<ManualCountTextureUsageTrackerOptions>;
+
+  constructor(
+    releaseCallback: (textureDescId: number) => void,
+    options: ManualCountTextureUsageTrackerOptions,
+  ) {
+    super(releaseCallback);
+    this.options = {
+      textureCleanupIntervalMs: options.textureCleanupIntervalMs ?? 10000,
+      textureCleanupAgeThreadholdMs:
+        options.textureCleanupAgeThreadholdMs ?? 60000,
+    };
+    // Periodically check for textures that are no longer referenced by any
+    // Nodes and notify RendererMain to release them.
+    setInterval(() => {
+      const now = Date.now();
+      const thresholdMs = this.options.textureCleanupAgeThreadholdMs;
+      for (const textureRefInfo of this.zeroReferenceTextureSet) {
+        if (now - textureRefInfo.lastUpdate > thresholdMs) {
+          this.releaseCallback(textureRefInfo.id);
+          this.textureMap.delete(textureRefInfo.id);
+          this.zeroReferenceTextureSet.delete(textureRefInfo);
+        }
+      }
+    }, this.options.textureCleanupIntervalMs);
+  }
+
+  registerTexture(texture: TextureRef) {
+    const textureId = texture.options?.id;
+    assertTruthy(textureId, 'Texture must have an id to be registered');
+    if (!this.textureMap.has(textureId)) {
+      const textureRefInfo: TextureRefInfo = {
+        id: textureId,
+        nodeRefCount: 0,
+        lastUpdate: Date.now(),
+      };
+      this.textureMap.set(textureId, textureRefInfo);
+      this.zeroReferenceTextureSet.add(textureRefInfo);
+    }
+  }
+
+  incrementTextureRefCount(texture: TextureRef) {
+    const textureId = texture.options?.id;
+    assertTruthy(textureId, 'Texture must have an id to be registered');
+    let textureRefInfo = this.textureMap.get(textureId);
+    if (!textureRefInfo) {
+      // Texture has not been registered yet, so register it now.
+      // This may happen if the TextureRef was cleaned up from the registry
+      // but was still alive in memory and eventually re-used.
+      this.registerTexture(texture);
+      textureRefInfo = this.textureMap.get(textureId);
+    }
+    assertTruthy(textureRefInfo, 'Texture must have been registered');
+    if (texture.txType === 'SubTexture') {
+      // If this is a SubTexture, then increment the reference count of the
+      // parent texture as well.
+      this.incrementTextureRefCount(texture.props.texture);
+    }
+    textureRefInfo.nodeRefCount++;
+    textureRefInfo.lastUpdate = Date.now();
+    if (this.zeroReferenceTextureSet.has(textureRefInfo)) {
+      this.zeroReferenceTextureSet.delete(textureRefInfo);
+    }
+  }
+
+  decrementTextureRefCount(texture: TextureRef) {
+    const textureId = texture.options?.id;
+    assertTruthy(textureId, 'Texture must have an id to be registered');
+    const textureRefInfo = this.textureMap.get(textureId);
+    assertTruthy(textureRefInfo, 'Texture must have been registered');
+    textureRefInfo.nodeRefCount--;
+    textureRefInfo.lastUpdate = Date.now();
+    if (textureRefInfo.nodeRefCount === 0) {
+      this.zeroReferenceTextureSet.add(textureRefInfo);
+    }
+    if (texture.txType === 'SubTexture') {
+      // If this is a SubTexture, then decrement the reference count of the
+      // parent texture as well.
+      this.decrementTextureRefCount(texture.props.texture);
+    }
+  }
+}

package/src/main-api/texture-usage-trackers/TextureUsageTracker.ts

@@ -0,0 +1,54 @@
+/*
+ * 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 type { TextureRef } from '../RendererMain.js';
+
+/**
+ * Texture Usage Tracker for Usage Based Texture Garbage Collection
+ */
+export abstract class TextureUsageTracker {
+  constructor(protected releaseCallback: (textureDescId: number) => void) {}
+
+  /**
+   * Register a texture with the tracker.
+   *
+   * @param texture
+   */
+  abstract registerTexture(texture: TextureRef): void;
+
+  /**
+   * Increment the reference count for a texture.
+   *
+   * @remarks
+   * This should be called anytime a Node sets a new texture.
+   *
+   * @param texture
+   */
+  abstract incrementTextureRefCount(texture: TextureRef): void;
+
+  /**
+   * Decrement the Node reference count for a texture.
+   *
+   * @remarks
+   * This should be called anytime a Node removes a texture.
+   *
+   * @param texture
+   */
+  abstract decrementTextureRefCount(texture: TextureRef): void;
+}