@lightningjs/renderer 0.9.3 → 1.0.0-rc.0

package/src/core/CoreShaderManager.ts

@@ -60,9 +60,17 @@ import {
   RadialProgressEffect,
   type RadialProgressEffectProps,
 } from './renderers/webgl/shaders/effects/RadialProgressEffect.js';
-import { HolePunchEffect } from './renderers/webgl/shaders/effects/HolePunchEffect.js';
+import {
+  HolePunchEffect,
+  type HolePunchEffectProps,
+} from './renderers/webgl/shaders/effects/HolePunchEffect.js';
 import { WebGlCoreShader } from './renderers/webgl/WebGlCoreShader.js';
 import { UnsupportedShader } from './renderers/canvas/shaders/UnsupportedShader.js';
+import { ShaderController } from '../main-api/ShaderController.js';
+import {
+  DynamicShaderController,
+  type DynamicEffects,
+} from '../main-api/DynamicShaderController.js';
 
 export type { FadeOutEffectProps };
 export type { LinearGradientEffectProps };
@@ -70,6 +78,7 @@ export type { RadialGradientEffectProps };
 export type { GrayscaleEffectProps };
 export type { GlitchEffectProps };
 export type { RadialProgressEffectProps };
+export type { HolePunchEffectProps };
 
 export interface ShaderMap {
   DefaultShader: typeof DefaultShader;
@@ -80,11 +89,6 @@ export interface ShaderMap {
   UnsupportedShader: typeof UnsupportedShader;
 }
 
-export type ShaderNode<Type extends keyof ShaderMap> = {
-  shader: InstanceType<ShaderMap[Type]>;
-  props: Record<string, unknown>;
-};
-
 export interface EffectMap {
   radius: typeof RadiusEffect;
   border: typeof BorderEffect;
@@ -107,7 +111,8 @@ export type EffectProps =
   | RadialGradientEffectProps
   | GrayscaleEffectProps
   | GlitchEffectProps
-  | RadialProgressEffectProps;
+  | RadialProgressEffectProps
+  | HolePunchEffectProps;
 
 export class CoreShaderManager {
   protected shCache: Map<string, InstanceType<ShaderMap[keyof ShaderMap]>> =
@@ -161,10 +166,17 @@ export class CoreShaderManager {
     return this.shConstructors;
   }
 
+  /**
+   * Loads a shader (if not already loaded) and returns a controller for it.
+   *
+   * @param shType
+   * @param props
+   * @returns
+   */
   loadShader<Type extends keyof ShaderMap>(
     shType: Type,
     props?: ExtractProps<ShaderMap[Type]>,
-  ): ShaderNode<Type> {
+  ): ShaderController<Type> {
     if (!this.renderer) {
       throw new Error(`Renderer is not been defined`);
     }
@@ -177,14 +189,17 @@ export class CoreShaderManager {
       this.renderer.mode === 'canvas' &&
       ShaderClass.prototype instanceof WebGlCoreShader
     ) {
-      return {
-        shader: new UnsupportedShader(shType) as InstanceType<ShaderMap[Type]>,
-        props: props as Record<string, unknown>,
-      };
+      return this._createShaderCtr(
+        shType,
+        new UnsupportedShader(shType) as InstanceType<ShaderMap[Type]>,
+        props as ExtractProps<ShaderMap[Type]>,
+      );
     }
 
     if (shType === 'DynamicShader') {
-      return this.loadDynamicShader(props!);
+      return this.loadDynamicShader(
+        props!,
+      ) as unknown as ShaderController<Type>;
     }
 
     const resolvedProps = ShaderClass.resolveDefaults(
@@ -193,10 +208,11 @@ export class CoreShaderManager {
     const cacheKey =
       ShaderClass.makeCacheKey(resolvedProps) || ShaderClass.name;
     if (cacheKey && this.shCache.has(cacheKey)) {
-      return {
-        shader: this.shCache.get(cacheKey) as InstanceType<ShaderMap[Type]>,
-        props: resolvedProps,
-      };
+      return this._createShaderCtr(
+        shType,
+        this.shCache.get(cacheKey) as InstanceType<ShaderMap[Type]>,
+        resolvedProps as ExtractProps<ShaderMap[Type]>,
+      );
     }
 
     // @ts-expect-error ShaderClass WILL accept a Renderer
@@ -206,15 +222,16 @@ export class CoreShaderManager {
     if (cacheKey) {
       this.shCache.set(cacheKey, shader);
     }
-    return {
+    return this._createShaderCtr(
+      shType,
       shader,
-      props: resolvedProps,
-    };
+      resolvedProps as ExtractProps<ShaderMap[Type]>,
+    );
   }
 
-  loadDynamicShader<Type extends keyof ShaderMap>(
-    props: DynamicShaderProps,
-  ): ShaderNode<Type> {
+  loadDynamicShader<
+    T extends DynamicEffects<[...{ name: string; type: keyof EffectMap }[]]>,
+  >(props: DynamicShaderProps): DynamicShaderController<T> {
     if (!this.renderer) {
       throw new Error(`Renderer is not been defined`);
     }
@@ -227,10 +244,10 @@ export class CoreShaderManager {
       this.effectConstructors,
     );
     if (cacheKey && this.shCache.has(cacheKey)) {
-      return {
-        shader: this.shCache.get(cacheKey) as InstanceType<ShaderMap[Type]>,
-        props: resolvedProps,
-      };
+      return this._createDynShaderCtr(
+        this.shCache.get(cacheKey) as InstanceType<ShaderMap['DynamicShader']>,
+        resolvedProps,
+      );
     }
     const shader = new DynamicShader(
       this.renderer as WebGlCoreRenderer,
@@ -240,10 +257,25 @@ export class CoreShaderManager {
     if (cacheKey) {
       this.shCache.set(cacheKey, shader);
     }
-    return {
-      shader: shader as InstanceType<ShaderMap[Type]>,
-      props: resolvedProps,
-    };
+
+    return this._createDynShaderCtr(shader, resolvedProps);
+  }
+
+  private _createShaderCtr<Type extends keyof ShaderMap>(
+    type: Type,
+    shader: InstanceType<ShaderMap[Type]>,
+    props: ExtractProps<ShaderMap[Type]>,
+  ): ShaderController<Type> {
+    return new ShaderController(type, shader, props, this.renderer.stage);
+  }
+
+  private _createDynShaderCtr<
+    T extends DynamicEffects<[...{ name: string; type: keyof EffectMap }[]]>,
+  >(
+    shader: InstanceType<ShaderMap['DynamicShader']>,
+    props: ExtractProps<ShaderMap['DynamicShader']>,
+  ): DynamicShaderController<T> {
+    return new DynamicShaderController(shader, props, this);
   }
 
   useShader(shader: CoreShader): void {

package/src/core/CoreTextNode.ts

@@ -32,21 +32,44 @@ import type {
   NodeTextFailedPayload,
   NodeTextLoadedPayload,
 } from '../common/CommonTypes.js';
-import type { Rect, RectWithValid } from './lib/utils.js';
+import type { RectWithValid } from './lib/utils.js';
 import { assertTruthy } from '../utils.js';
 import { Matrix3d } from './lib/Matrix3d.js';
 
 export interface CoreTextNodeProps extends CoreNodeProps, TrProps {
-  text: string;
+  /**
+   * Force Text Node to use a specific Text Renderer
+   *
+   * @remarks
+   * By default, Text Nodes resolve the Text Renderer to use based on the font
+   * that is matched using the font family and other font selection properties.
+   *
+   * If two fonts supported by two separate Text Renderers are matched setting
+   * this override forces the Text Node to resolve to the Text Renderer defined
+   * here.
+   *
+   * @default null
+   */
   textRendererOverride: keyof TextRendererMap | null;
 }
 
-type ICoreTextNode = Omit<
-  CoreTextNodeProps,
-  'texture' | 'textureOptions' | 'shader' | 'shaderProps'
->;
-
-export class CoreTextNode extends CoreNode implements ICoreTextNode {
+/**
+ * An CoreNode in the Renderer scene graph that renders text.
+ *
+ * @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.
+ *
+ * The text renderer can be overridden by setting the `textRendererOverride`
+ *
+ * The `texture` and `shader` properties are managed by loaded text renderer and
+ * should not be set directly.
+ *
+ * For non-text rendering, see {@link CoreNode}.
+ */
+export class CoreTextNode extends CoreNode implements CoreTextNodeProps {
   textRenderer: TextRenderer;
   trState: TextRendererState;
   private _textRendererOverride: CoreTextNodeProps['textRendererOverride'] =
@@ -356,6 +379,15 @@ export class CoreTextNode extends CoreNode implements ICoreTextNode {
   override renderQuads(renderer: CoreRenderer) {
     assertTruthy(this.globalTransform);
 
+    // If the text renderer does not support rendering quads, fallback to the
+    // default renderQuads method
+    if (!this.textRenderer.renderQuads) {
+      super.renderQuads(renderer);
+      return;
+    }
+
+    // If the text renderer does support rendering quads, use it...
+
     // Prevent quad rendering if parent has a render texture
     // and this node is not the render texture
     if (this.parentHasRenderTexture) {
@@ -410,7 +442,7 @@ export class CoreTextNode extends CoreNode implements ICoreTextNode {
       this._textRendererOverride,
     );
 
-    const textRendererState = resolvedTextRenderer.createState(props);
+    const textRendererState = resolvedTextRenderer.createState(props, this);
 
     textRendererState.emitter.on('loaded', this.onTextLoaded);
     textRendererState.emitter.on('failed', this.onTextFailed);

package/src/core/CoreTextureManager.ts

@@ -17,9 +17,7 @@
  * limitations under the License.
  */
 
-import { assertTruthy } from '../utils.js';
 import { ImageWorkerManager } from './lib/ImageWorker.js';
-import type { CoreContextTexture } from './renderers/CoreContextTexture.js';
 import type { CoreRenderer } from './renderers/CoreRenderer.js';
 import { ColorTexture } from './textures/ColorTexture.js';
 import { ImageTexture } from './textures/ImageTexture.js';
@@ -29,14 +27,14 @@ import { RenderTexture } from './textures/RenderTexture.js';
 import type { Texture } from './textures/Texture.js';
 
 /**
- * Augmentable map of texture types
+ * Augmentable map of texture class types
  *
  * @remarks
  * This interface can be augmented by other modules/apps to add additional
  * texture types. The ones included directly here are the ones that are
  * included in the core library.
  */
-export interface TextureMap {
+export interface TextureTypeMap {
   ColorTexture: typeof ColorTexture;
   ImageTexture: typeof ImageTexture;
   NoiseTexture: typeof NoiseTexture;
@@ -44,6 +42,13 @@ export interface TextureMap {
   RenderTexture: typeof RenderTexture;
 }
 
+/**
+ * Map of texture instance types
+ */
+export type TextureMap = {
+  [K in keyof TextureTypeMap]: InstanceType<TextureTypeMap[K]>;
+};
+
 export type ExtractProps<Type> = Type extends { z$__type__Props: infer Props }
   ? Props
   : never;
@@ -54,7 +59,6 @@ export type ExtractProps<Type> = Type extends { z$__type__Props: infer Props }
  */
 export interface TextureManagerDebugInfo {
   keyCacheSize: number;
-  idCacheSize: number;
 }
 
 export type ResizeModeOptions =
@@ -117,35 +121,6 @@ export interface TextureOptions {
    */
   preload?: boolean;
 
-  /**
-   * ID to use for this texture.
-   *
-   * @remarks
-   * This is for internal use only as an optimization.
-   *
-   * @privateRemarks
-   * This is used to avoid having to look up the texture in the texture cache
-   * by its cache key. Theoretically this should be faster.
-   *
-   * @defaultValue Automatically generated
-   */
-  id?: number;
-
-  /**
-   * Cache key to use for this texture
-   *
-   * @remarks
-   * If this is set, the texture will be cached using this key. If a texture
-   * with the same key is already cached, it will be returned instead of
-   * creating a new texture.
-   *
-   * If this is not set (undefined), it will be automatically generated via
-   * the specified `Texture`'s `makeCacheKey()` method.
-   *
-   * @defaultValue Automatically generated via `Texture.makeCacheKey()`
-   */
-  cacheKey?: string | false;
-
   /**
    * Flip the texture horizontally when rendering
    *
@@ -172,20 +147,20 @@ export interface TextureOptions {
 
 export class CoreTextureManager {
   /**
-   * Amount of used memory defined in pixels
+   * Map of textures by cache key
    */
-  usedMemory = 0;
+  keyCache: Map<string, Texture> = new Map();
 
-  txConstructors: Partial<TextureMap> = {};
+  /**
+   * Map of cache keys by texture
+   */
+  inverseKeyCache: WeakMap<Texture, string> = new WeakMap();
 
-  textureKeyCache: Map<string, Texture> = new Map();
-  textureIdCache: Map<number, Texture> = new Map();
+  /**
+   * Map of texture constructors by their type name
+   */
+  txConstructors: Partial<TextureTypeMap> = {};
 
-  ctxTextureCache: WeakMap<Texture, CoreContextTexture> = new WeakMap();
-  textureRefCountMap: WeakMap<
-    Texture,
-    { cacheKey: string | false; count: number }
-  > = new WeakMap();
   imageWorkerManager: ImageWorkerManager | null = null;
   hasCreateImageBitmap = !!self.createImageBitmap;
   hasWorker = !!self.Worker;
@@ -198,6 +173,17 @@ export class CoreTextureManager {
    */
   renderer!: CoreRenderer;
 
+  /**
+   * 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: number) {
     // Register default known texture types
     if (this.hasCreateImageBitmap && this.hasWorker && numImageWorkers > 0) {
@@ -217,165 +203,59 @@ export class CoreTextureManager {
     this.registerTextureType('RenderTexture', RenderTexture);
   }
 
-  registerTextureType<Type extends keyof TextureMap>(
+  registerTextureType<Type extends keyof TextureTypeMap>(
     textureType: Type,
-    textureClass: TextureMap[Type],
+    textureClass: TextureTypeMap[Type],
   ): void {
     this.txConstructors[textureType] = textureClass;
   }
 
-  loadTexture<Type extends keyof TextureMap>(
+  loadTexture<Type extends keyof TextureTypeMap>(
     textureType: Type,
-    props: ExtractProps<TextureMap[Type]>,
-    options: TextureOptions | null = null,
-  ): InstanceType<TextureMap[Type]> {
+    props: ExtractProps<TextureTypeMap[Type]>,
+  ): InstanceType<TextureTypeMap[Type]> {
+    let texture: Texture | undefined;
     const TextureClass = this.txConstructors[textureType];
     if (!TextureClass) {
       throw new Error(`Texture type "${textureType}" is not registered`);
     }
-    let texture: Texture | undefined;
-    // 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 as any);
-      if (cacheKey && this.textureKeyCache.has(cacheKey)) {
+      const cacheKey = TextureClass.makeCacheKey(props as any);
+      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 as any);
-      }
-      if (descId) {
-        this.addTextureIdToCache(descId, cacheKey, texture);
-      }
-    }
-    if (options?.preload) {
-      const ctxTx = this.getCtxTexture(texture);
-      ctxTx.load();
-    }
-    return texture as InstanceType<TextureMap[Type]>;
-  }
-
-  /**
-   * 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
-   */
-  private addTextureIdToCache(
-    textureDescId: number,
-    cacheKey: string | false,
-    texture: Texture,
-  ): void {
-    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: number): void {
-    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 as InstanceType<TextureTypeMap[Type]>;
   }
 
-  /**
-   * Get an object containing debug information about the texture manager.
-   *
-   * @returns
-   */
-  getDebugInfo(): TextureManagerDebugInfo {
-    // 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,
-    };
+  private initTextureToCache(texture: Texture, cacheKey: string) {
+    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.
+   * Called by Texture Cleanup when a texture is freed.
    *
-   * ContextTextures are stored in a WeakMap, so they will be garbage collected
-   * when the Texture source is no longer referenced.
-   *
-   * @param textureSource
-   * @returns
+   * @param texture
    */
-  getCtxTexture(textureSource: Texture): CoreContextTexture {
-    if (this.ctxTextureCache.has(textureSource)) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      return this.ctxTextureCache.get(textureSource)!;
+  removeTextureFromCache(texture: 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;
   }
 }