@lightningjs/renderer 0.3.0 → 0.3.2

package/src/core/CoreTextureManager.ts

@@ -0,0 +1,323 @@
+/*
+ * 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 { CoreContextTexture } from './renderers/CoreContextTexture.js';
+import type { CoreRenderer } from './renderers/CoreRenderer.js';
+import { ColorTexture } from './textures/ColorTexture.js';
+import { ImageTexture } from './textures/ImageTexture.js';
+import { NoiseTexture } from './textures/NoiseTexture.js';
+import { SubTexture } from './textures/SubTexture.js';
+import type { Texture } from './textures/Texture.js';
+
+/**
+ * Augmentable map of texture 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 {
+  ColorTexture: typeof ColorTexture;
+  ImageTexture: typeof ImageTexture;
+  NoiseTexture: typeof NoiseTexture;
+  SubTexture: typeof SubTexture;
+}
+
+export type ExtractProps<Type> = Type extends { z$__type__Props: infer Props }
+  ? Props
+  : never;
+
+/**
+ * Contains information about the texture manager's internal state
+ * for debugging purposes.
+ */
+export interface TextureManagerDebugInfo {
+  keyCacheSize: number;
+  idCacheSize: number;
+}
+
+/**
+ * Universal options for all texture types
+ *
+ * @remarks
+ * Texture Options provide a way to specify options that are relevant to the
+ * texture loading process (including caching) and specifically for how a
+ * texture is rendered within a specific Node (or set of Nodes).
+ *
+ * They are not used in determining the cache key for a texture (except if
+ * the `cacheKey` option is provided explicitly to oveerride the default
+ * cache key for the texture instance) nor are they stored/referenced within
+ * the texture instance itself. Instead, the options are stored/referenced
+ * within individual Nodes. So a single texture instance can be used in
+ * multiple Nodes each using a different set of options.
+ */
+export interface TextureOptions {
+  /**
+   * Preload the texture immediately even if it's not being rendered to the
+   * screen.
+   *
+   * @remarks
+   * This allows the texture to be used immediately without any delay when it
+   * is first needed for rendering. Otherwise the loading process will start
+   * when the texture is first rendered, which may cause a delay in that texture
+   * being shown properly.
+   *
+   * @defaultValue `false`
+   */
+  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
+   *
+   * @defaultValue `false`
+   */
+  flipX?: boolean;
+
+  /**
+   * Flip the texture vertically when rendering
+   *
+   * @defaultValue `false`
+   */
+  flipY?: boolean;
+}
+
+export class CoreTextureManager {
+  /**
+   * Amount of used memory defined in pixels
+   */
+  usedMemory = 0;
+
+  txConstructors: Partial<TextureMap> = {};
+
+  textureKeyCache: Map<string, Texture> = new Map();
+  textureIdCache: Map<number, Texture> = new Map();
+
+  ctxTextureCache: WeakMap<Texture, CoreContextTexture> = new WeakMap();
+  textureRefCountMap: WeakMap<
+    Texture,
+    { cacheKey: string | false; count: number }
+  > = new WeakMap();
+
+  /**
+   * Renderer that this texture manager is associated with
+   *
+   * @remarks
+   * This MUST be set before the texture manager is used. Otherwise errors
+   * will occur when using the texture manager.
+   */
+  renderer!: CoreRenderer;
+
+  constructor() {
+    // Register default known texture types
+    this.registerTextureType('ImageTexture', ImageTexture);
+    this.registerTextureType('ColorTexture', ColorTexture);
+    this.registerTextureType('NoiseTexture', NoiseTexture);
+    this.registerTextureType('SubTexture', SubTexture);
+  }
+
+  registerTextureType<Type extends keyof TextureMap>(
+    textureType: Type,
+    textureClass: TextureMap[Type],
+  ): void {
+    this.txConstructors[textureType] = textureClass;
+  }
+
+  loadTexture<Type extends keyof TextureMap>(
+    textureType: Type,
+    props: ExtractProps<TextureMap[Type]>,
+    options: TextureOptions | null = null,
+  ): InstanceType<TextureMap[Type]> {
+    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)) {
+        // console.log('Getting texture by cache key', cacheKey);
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        texture = this.textureKeyCache.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 that the `TextureDesc` has been
+   * garbage collected. This allows us to remove the `Texture` from the 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) {
+      throw new Error(
+        `Texture ID ${textureDescId} is not in the texture ID cache`,
+      );
+    }
+    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);
+        }
+      }
+    }
+  }
+
+  /**
+   * 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,
+    };
+  }
+
+  /**
+   * Get a CoreContextTexture for the given Texture source.
+   *
+   * @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.
+   *
+   * @param textureSource
+   * @returns
+   */
+  getCtxTexture(textureSource: Texture): CoreContextTexture {
+    if (this.ctxTextureCache.has(textureSource)) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      return this.ctxTextureCache.get(textureSource)!;
+    }
+    const texture = this.renderer.createCtxTexture(textureSource);
+
+    this.ctxTextureCache.set(textureSource, texture);
+    return texture;
+  }
+}

package/src/core/Matrix2DContext.ts

@@ -0,0 +1,52 @@
+/*
+ * 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.
+ */
+
+/**
+ *  Represents a 2D transformation context, providing a 2x2 matrix for transformations.
+ */
+export class Matrix2DContext {
+  // world alpha
+  alpha = 1;
+
+  // world position
+  px = 0;
+  py = 0;
+
+  ta = 1;
+  tb = 0;
+  tc = 0;
+  td = 1;
+
+  isIdentity(): boolean {
+    return (
+      this.alpha === 1 &&
+      this.px === 0 &&
+      this.py === 0 &&
+      this.isIdentityMatrix()
+    );
+  }
+
+  isIdentityMatrix(): boolean {
+    return this.ta === 1 && this.tb === 0 && this.tc === 0 && this.td === 1;
+  }
+
+  isSquare(): boolean {
+    return this.tb === 0 && this.tc === 0;
+  }
+}

package/src/core/Stage.ts

@@ -0,0 +1,280 @@
+/*
+ * 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 { Scene } from './scene/Scene.js';
+
+import { startLoop, getTimeStamp } from './platform.js';
+
+import { WebGlCoreRenderer } from './renderers/webgl/WebGlCoreRenderer.js';
+import { assertTruthy } from '../utils.js';
+import { AnimationManager } from './animations/AnimationManager.js';
+import { CoreNode } from './CoreNode.js';
+import { CoreTextureManager } from './CoreTextureManager.js';
+import { TrFontManager } from './text-rendering/TrFontManager.js';
+import { CoreShaderManager } from './CoreShaderManager.js';
+import type {
+  TextRenderer,
+  TextRendererMap,
+  TrProps,
+} from './text-rendering/renderers/TextRenderer.js';
+import { SdfTextRenderer } from './text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.js';
+import { CanvasTextRenderer } from './text-rendering/renderers/CanvasTextRenderer.js';
+import { intersectRect, type Rect } from './lib/utils.js';
+
+export interface StageOptions {
+  rootId: number;
+  appWidth: number;
+  appHeight: number;
+  deviceLogicalPixelRatio: number;
+  devicePhysicalPixelRatio: number;
+  canvas: HTMLCanvasElement | OffscreenCanvas;
+  clearColor: number;
+  debug?: {
+    monitorTextureCache?: boolean;
+  };
+}
+
+const bufferMemory = 2e6;
+const autoStart = true;
+
+export class Stage {
+  /// Module Instances
+  public readonly animationManager: AnimationManager;
+  public readonly txManager: CoreTextureManager;
+  public readonly fontManager: TrFontManager;
+  public readonly textRenderers: Partial<TextRendererMap>;
+  public readonly shManager: CoreShaderManager;
+  public readonly renderer: WebGlCoreRenderer;
+  private scene: Scene;
+
+  /// State
+  deltaTime = 0;
+  lastFrameTime = 0;
+  currentFrameTime = 0;
+
+  /**
+   * Stage constructor
+   */
+  constructor(readonly options: StageOptions) {
+    const { canvas, clearColor, rootId, debug, appWidth, appHeight } = options;
+    this.txManager = new CoreTextureManager();
+    this.shManager = new CoreShaderManager();
+    this.animationManager = new AnimationManager();
+
+    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);
+    }
+
+    this.renderer = new WebGlCoreRenderer({
+      stage: this,
+      canvas,
+      pixelRatio:
+        options.devicePhysicalPixelRatio * options.deviceLogicalPixelRatio,
+      clearColor: clearColor ?? 0xff000000,
+      bufferMemory,
+      txManager: this.txManager,
+      shManager: this.shManager,
+    });
+
+    // Must do this after renderer is created
+    this.txManager.renderer = this.renderer;
+
+    this.textRenderers = {
+      canvas: new CanvasTextRenderer(this),
+      sdf: new SdfTextRenderer(this),
+    };
+    this.fontManager = new TrFontManager(this.textRenderers);
+
+    // create root node
+    const rootNode = new CoreNode(this, {
+      id: rootId,
+      x: 0,
+      y: 0,
+      width: appWidth,
+      height: appHeight,
+      alpha: 1,
+      clipping: false,
+      color: 0x00000000,
+      colorTop: 0x00000000,
+      colorBottom: 0x00000000,
+      colorLeft: 0x00000000,
+      colorRight: 0x00000000,
+      colorTl: 0x00000000,
+      colorTr: 0x00000000,
+      colorBl: 0x00000000,
+      colorBr: 0x00000000,
+      zIndex: 0,
+      zIndexLocked: 0,
+      scale: 1,
+      mountX: 0,
+      mountY: 0,
+      mount: 0,
+      pivot: 0.5,
+      pivotX: 0.5,
+      pivotY: 0.5,
+      rotation: 0,
+      parent: null,
+      texture: null,
+      textureOptions: null,
+      shader: null,
+      shaderProps: null,
+    });
+
+    this.scene = new Scene(rootNode);
+
+    // execute platform start loop
+    if (autoStart) {
+      startLoop(this);
+    }
+  }
+  /**
+   * Start a new frame draw
+   */
+  drawFrame() {
+    const { renderer, scene, animationManager } = this;
+    if (!scene?.root) {
+      return;
+    }
+    this.lastFrameTime = this.currentFrameTime;
+    this.currentFrameTime = getTimeStamp();
+
+    this.deltaTime = !this.lastFrameTime
+      ? 100 / 6
+      : this.currentFrameTime - this.lastFrameTime;
+
+    // step animation
+    animationManager.update(this.deltaTime);
+
+    // reset and clear viewport
+    renderer?.reset();
+
+    // test if we need to update the scene
+    if (scene?.root?.hasUpdates) {
+      scene?.root?.update(this.deltaTime);
+    }
+
+    this.addQuads(scene.root);
+
+    renderer?.sortRenderables();
+    renderer?.render();
+  }
+
+  addQuads(node: CoreNode, parentClippingRect: Rect | null = null) {
+    assertTruthy(this.renderer);
+    let clippingRect: Rect | null = node.clipping
+      ? {
+          x: node.worldContext.px,
+          y: node.worldContext.py,
+          width: node.width,
+          height: node.height,
+        }
+      : null;
+    if (parentClippingRect && clippingRect) {
+      clippingRect = intersectRect(parentClippingRect, clippingRect);
+    } else if (parentClippingRect) {
+      clippingRect = parentClippingRect;
+    }
+
+    node.renderQuads(this.renderer, clippingRect);
+    node.children.forEach((child) => {
+      if (child.alpha === 0) {
+        return;
+      }
+      this.addQuads(child, clippingRect);
+    });
+  }
+
+  /**
+   * Given a font name, and possible renderer override, return the best compatible text renderer.
+   *
+   * @remarks
+   * Will always return at least a canvas renderer if no other suitable renderer can be resolved.
+   *
+   * @param fontFamily
+   * @param textRendererOverride
+   * @returns
+   */
+  resolveTextRenderer(
+    trProps: TrProps,
+    textRendererOverride: keyof TextRendererMap | null = null,
+  ): TextRenderer {
+    let rendererId = textRendererOverride;
+
+    let overrideFallback = false;
+    // Check if the override is valid (if one is provided)
+    if (rendererId) {
+      const possibleRenderer = this.textRenderers[rendererId];
+      if (!possibleRenderer) {
+        console.warn(`Text renderer override '${rendererId}' not found.`);
+        rendererId = null;
+        overrideFallback = true;
+      } else if (!possibleRenderer.canRenderFont(trProps)) {
+        console.warn(
+          `Cannot use override text renderer '${rendererId}' for font`,
+          trProps,
+        );
+        rendererId = null;
+        overrideFallback = true;
+      }
+    }
+
+    if (!rendererId) {
+      // Iterate through the text renderers and find the first one that can render the font
+      for (const [trId, tr] of Object.entries(this.textRenderers)) {
+        if (trId === 'canvas') {
+          // Canvas is always a fallback
+          continue;
+        }
+        if (tr.canRenderFont(trProps)) {
+          rendererId = trId as keyof TextRendererMap;
+          break;
+        }
+      }
+      if (!rendererId) {
+        // If no renderer can be found, use the canvas renderer
+        rendererId = 'canvas';
+      }
+    }
+
+    if (overrideFallback) {
+      console.warn(`Falling back to text renderer ${String(rendererId)}`);
+    }
+
+    // By now we are guaranteed to have a valid rendererId (at least Canvas);
+    const resolvedTextRenderer = this.textRenderers[rendererId];
+    assertTruthy(resolvedTextRenderer, 'resolvedTextRenderer undefined');
+
+    // Need to explicitly cast to TextRenderer because TS doesn't like
+    // the covariant state argument in the setter method map
+    return resolvedTextRenderer as unknown as TextRenderer;
+  }
+
+  //#region Properties
+
+  get root() {
+    return this.scene?.root || null;
+  }
+
+  //#endregion Properties
+}

package/src/core/animations/AnimationManager.ts

@@ -0,0 +1,38 @@
+/*
+ * 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 { CoreAnimation } from './CoreAnimation.js';
+
+export class AnimationManager {
+  activeAnimations: Set<CoreAnimation> = new Set();
+
+  registerAnimation(animation: CoreAnimation) {
+    this.activeAnimations.add(animation);
+  }
+
+  unregisterAnimation(animation: CoreAnimation) {
+    this.activeAnimations.delete(animation);
+  }
+
+  update(dt: number) {
+    this.activeAnimations.forEach((animation) => {
+      animation.update(dt);
+    });
+  }
+}