@lightningjs/renderer 0.9.4 → 1.0.0-rc.0

package/src/main-api/Inspector.ts

@@ -1,15 +1,13 @@
-import type {
-  INode,
-  INodeAnimatableProps,
-  INodeWritableProps,
-  ITextNode,
-  ITextNodeWritableProps,
-} from './INode.js';
-import type { ICoreDriver } from './ICoreDriver.js';
-import { type RendererMainSettings } from './RendererMain.js';
+import {
+  CoreNode,
+  type CoreNodeAnimateProps,
+  type CoreNodeProps,
+} from '../core/CoreNode.js';
+import { type RendererMainSettings } from './Renderer.js';
 import type { AnimationSettings } from '../core/animations/CoreAnimation.js';
 import type { IAnimationController } from '../common/IAnimationController.js';
 import { isProductionEnvironment } from '../utils.js';
+import type { CoreTextNode, CoreTextNodeProps } from '../core/CoreTextNode.js';
 
 /**
  * Inspector
@@ -219,31 +217,28 @@ export class Inspector {
   }
 
   createDiv(
-    node: INode | ITextNode,
-    properties: INodeWritableProps | ITextNodeWritableProps,
+    id: number,
+    properties: CoreNodeProps | CoreTextNodeProps,
   ): HTMLElement {
     const div = document.createElement('div');
     div.style.position = 'absolute';
-    div.id = node.id.toString();
+    div.id = id.toString();
 
     // set initial properties
     for (const key in properties) {
       this.updateNodeProperty(
         div,
         // really typescript? really?
-        key as keyof (INodeWritableProps & ITextNodeWritableProps),
-        (properties as INodeWritableProps & ITextNodeWritableProps)[
-          key as keyof (INodeWritableProps & ITextNodeWritableProps)
-        ],
+        key as keyof CoreNodeProps,
+        properties[key as keyof CoreNodeProps],
       );
     }
 
     return div;
   }
 
-  createNode(driver: ICoreDriver, properties: INodeWritableProps): INode {
-    const node = driver.createNode(properties);
-    const div = this.createDiv(node, properties);
+  createNode(node: CoreNode): CoreNode {
+    const div = this.createDiv(node.id, node.props);
 
     // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
     (div as any).node = node;
@@ -254,40 +249,39 @@ export class Inspector {
     return this.createProxy(node, div);
   }
 
-  createTextNode(
-    driver: ICoreDriver,
-    properties: ITextNodeWritableProps,
-  ): ITextNode {
-    const node = driver.createTextNode(properties);
-    const div = this.createDiv(node, properties);
+  createTextNode(node: CoreNode): CoreTextNode {
+    const div = this.createDiv(node.id, node.props);
     // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
     (div as any).node = node;
 
     // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
     (node as any).div = div;
-    return this.createProxy(node, div) as ITextNode;
+    return this.createProxy(node, div) as CoreTextNode;
   }
 
-  createProxy(node: INode | ITextNode, div: HTMLElement): INode | ITextNode {
+  createProxy(
+    node: CoreNode | CoreTextNode,
+    div: HTMLElement,
+  ): CoreNode | CoreTextNode {
     return new Proxy(node, {
-      set: (target, property: keyof INodeWritableProps, value) => {
+      set: (target, property: keyof CoreNodeProps, value) => {
         this.updateNodeProperty(div, property, value);
         return Reflect.set(target, property, value);
       },
-      get: (target, property: keyof INode, receiver: any): any => {
+      get: (target, property: keyof CoreNode, receiver: any): any => {
         if (property === 'destroy') {
-          this.destroyNode(target);
+          this.destroyNode(target.id);
         }
 
         if (property === 'animate') {
-          return (props: INodeAnimatableProps, settings: AnimationSettings) => {
+          return (props: CoreNodeAnimateProps, settings: AnimationSettings) => {
             const anim = target.animate(props, settings);
 
             // Trap the animate start function so we can update the inspector accordingly
             return new Proxy(anim, {
               get: (target, property: keyof IAnimationController, receiver) => {
                 if (property === 'start') {
-                  this.animateNode(div, node, props, settings);
+                  this.animateNode(div, props, settings);
                 }
 
                 return Reflect.get(target, property, receiver);
@@ -301,14 +295,14 @@ export class Inspector {
     });
   }
 
-  destroyNode(node: INode | ITextNode) {
-    const div = document.getElementById(node.id.toString());
+  destroyNode(id: number) {
+    const div = document.getElementById(id.toString());
     div?.remove();
   }
 
   updateNodeProperty(
     div: HTMLElement,
-    property: keyof INodeWritableProps | keyof ITextNodeWritableProps,
+    property: keyof CoreNodeProps | keyof CoreTextNodeProps,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     value: any,
   ) {
@@ -320,7 +314,7 @@ export class Inspector {
      * Special case for parent property
      */
     if (property === 'parent') {
-      const parentId: number = (value as INode).id;
+      const parentId: number = value.id;
 
       // only way to detect if the parent is the root node
       // if you are reading this and have a better way, please let me know
@@ -385,7 +379,12 @@ export class Inspector {
 
     // DOM properties
     if (domPropertyMap[property]) {
-      div.setAttribute(String(stylePropertyMap[property]), String(value));
+      const domProperty = domPropertyMap[property];
+      if (!domProperty) {
+        return;
+      }
+
+      div.setAttribute(String(domProperty), String(value));
       return;
     }
 
@@ -407,8 +406,7 @@ export class Inspector {
   // simple animation handler
   animateNode(
     div: HTMLElement,
-    node: INode,
-    props: INodeAnimatableProps,
+    props: CoreNodeAnimateProps,
     settings: AnimationSettings,
   ) {
     const {

package/src/main-api/Renderer.ts

@@ -0,0 +1,543 @@
+/*
+ * 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.
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import type { EffectMap, ShaderMap } from '../core/CoreShaderManager.js';
+import type {
+  ExtractProps,
+  TextureTypeMap,
+  TextureMap,
+} from '../core/CoreTextureManager.js';
+import { EventEmitter } from '../common/EventEmitter.js';
+import { Inspector } from './Inspector.js';
+import { assertTruthy, isProductionEnvironment } from '../utils.js';
+import { Stage } from '../core/Stage.js';
+import { CoreNode, type CoreNodeProps } from '../core/CoreNode.js';
+import { CoreTextNode, type CoreTextNodeProps } from '../core/CoreTextNode.js';
+import type {
+  BaseShaderController,
+  ShaderController,
+} from './ShaderController.js';
+import type { INode, INodeProps, ITextNode, ITextNodeProps } from './INode.js';
+import type {
+  DynamicEffects,
+  DynamicShaderController,
+} from './DynamicShaderController.js';
+import type {
+  EffectDesc,
+  EffectDescUnion,
+} from '../core/renderers/webgl/shaders/DynamicShader.js';
+import type { TextureMemoryManagerSettings } from '../core/TextureMemoryManager.js';
+
+/**
+ * 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}
+ */
+export interface RendererMainSettings {
+  /**
+   * Authored logical pixel width of the application
+   *
+   * @defaultValue `1920`
+   */
+  appWidth?: number;
+
+  /**
+   * Authored logical pixel height of the application
+   *
+   * @defaultValue `1080`
+   */
+  appHeight?: number;
+
+  /**
+   * Texture Memory Manager Settings
+   */
+  textureMemory?: Partial<TextureMemoryManagerSettings>;
+
+  /**
+   * Bounds margin to extend the boundary in which a Node is added as Quad.
+   */
+  boundsMargin?: number | [number, number, number, number];
+
+  /**
+   * Factor to convert app-authored logical coorindates to device logical coordinates
+   *
+   * @remarks
+   * This value allows auto-scaling to support larger/small resolutions than the
+   * app was authored for.
+   *
+   * If the app was authored for 1920x1080 and this value is 2, the app's canvas
+   * will be rendered at 3840x2160 logical pixels.
+   *
+   * Likewise, if the app was authored for 1920x1080 and this value is 0.66667,
+   * the app's canvas will be rendered at 1280x720 logical pixels.
+   *
+   * @defaultValue `1`
+   */
+  deviceLogicalPixelRatio?: number;
+
+  /**
+   * Factor to convert device logical coordinates to device physical coordinates
+   *
+   * @remarks
+   * This value allows auto-scaling to support devices with different pixel densities.
+   *
+   * This controls the number of physical pixels that are used to render each logical
+   * pixel. For example, if the device has a pixel density of 2, each logical pixel
+   * will be rendered using 2x2 physical pixels.
+   *
+   * By default, it will be set to `window.devicePixelRatio` which is the pixel
+   * density of the device the app is running on reported by the browser.
+   *
+   * @defaultValue `window.devicePixelRatio`
+   */
+  devicePhysicalPixelRatio?: number;
+
+  /**
+   * RGBA encoded number of the background to use
+   *
+   * @defaultValue `0x00000000`
+   */
+  clearColor?: number;
+
+  /**
+   * Interval in milliseconds to receive FPS updates
+   *
+   * @remarks
+   * If set to `0`, FPS updates will be disabled.
+   *
+   * @defaultValue `0` (disabled)
+   */
+  fpsUpdateInterval?: number;
+
+  /**
+   * Include context call (i.e. WebGL) information in FPS updates
+   *
+   * @remarks
+   * When enabled the number of calls to each context method over the
+   * `fpsUpdateInterval` will be included in the FPS update payload's
+   * `contextSpyData` property.
+   *
+   * Enabling the context spy has a serious impact on performance so only use it
+   * when you need to extract context call information.
+   *
+   * @defaultValue `false` (disabled)
+   */
+  enableContextSpy?: boolean;
+
+  /**
+   * Number or Image Workers to use
+   *
+   * @remarks
+   * On devices with multiple cores, this can be used to improve image loading
+   * as well as reduce the impact of image loading on the main thread.
+   * Set to 0 to disable image workers.
+   *
+   * @defaultValue `2`
+   */
+  numImageWorkers?: number;
+
+  /**
+   * Enable inspector
+   *
+   * @remarks
+   * When enabled the renderer will spawn a inspector. The inspector will
+   * replicate the state of the Nodes created in the renderer and allow
+   * inspection of the state of the nodes.
+   *
+   * @defaultValue `false` (disabled)
+   */
+  enableInspector?: boolean;
+
+  /**
+   * Renderer mode
+   */
+  renderMode?: 'webgl' | 'canvas';
+}
+
+/**
+ * The Renderer Main API
+ *
+ * @remarks
+ * This is the primary class used to configure and operate the Renderer.
+ *
+ * It is used to create and destroy Nodes, as well as Texture and Shader
+ * references.
+ *
+ * Example:
+ * ```ts
+ * import { RendererMain, MainCoreDriver } from '@lightningjs/renderer';
+ *
+ * // Initialize the Renderer
+ * const renderer = new RendererMain(
+ *   {
+ *     appWidth: 1920,
+ *     appHeight: 1080
+ *   },
+ *   'app',
+ *   new MainCoreDriver(),
+ * );
+ * ```
+ *
+ * ## Events
+ * - `fpsUpdate`
+ *   - Emitted every `fpsUpdateInterval` milliseconds with the current FPS
+ * - `frameTick`
+ *   - Emitted every frame tick
+ * - `idle`
+ *   - Emitted when the renderer is idle (no changes to the scene
+ *     graph/animations running)
+ * - `criticalCleanup`
+ *  - Emitted when the Texture Memory Manager Cleanup process is triggered
+ *  - Payload: { memUsed: number, criticalThreshold: number }
+ *    - `memUsed` - The amount of memory (in bytes) used by textures before the
+ *       cleanup process
+ *    - `criticalThreshold` - The critical threshold (in bytes)
+ * - `criticalCleanupFailed`
+ *   - Emitted when the Texture Memory Manager Cleanup process is unable to free
+ *     up enough texture memory to reach below the critical threshold.
+ *     This can happen when there is not enough non-renderable textures to
+ *     free up.
+ *   - Payload (object with keys):
+ *     - `memUsed` - The amount of memory (in bytes) used by textures after
+ *       the cleanup process
+ *     - `criticalThreshold` - The critical threshold (in bytes)
+ */
+export class RendererMain extends EventEmitter {
+  readonly root: INode<ShaderController<'DefaultShader'>>;
+  readonly canvas: HTMLCanvasElement;
+  readonly settings: Readonly<Required<RendererMainSettings>>;
+  readonly stage: Stage;
+  private inspector: Inspector | null = null;
+
+  /**
+   * Constructs a new Renderer instance
+   *
+   * @param settings Renderer settings
+   * @param target Element ID or HTMLElement to insert the canvas into
+   * @param driver Core Driver to use
+   */
+  constructor(settings: RendererMainSettings, target: string | HTMLElement) {
+    super();
+    const resolvedTxSettings: TextureMemoryManagerSettings = {
+      criticalThreshold: settings.textureMemory?.criticalThreshold || 124e6,
+      targetThresholdLevel: settings.textureMemory?.targetThresholdLevel || 0.5,
+      cleanupInterval: settings.textureMemory?.cleanupInterval || 30000,
+      debugLogging: settings.textureMemory?.debugLogging || false,
+    };
+    const resolvedSettings: Required<RendererMainSettings> = {
+      appWidth: settings.appWidth || 1920,
+      appHeight: settings.appHeight || 1080,
+      textureMemory: resolvedTxSettings,
+      boundsMargin: settings.boundsMargin || 0,
+      deviceLogicalPixelRatio: settings.deviceLogicalPixelRatio || 1,
+      devicePhysicalPixelRatio:
+        settings.devicePhysicalPixelRatio || window.devicePixelRatio,
+      clearColor: settings.clearColor ?? 0x00000000,
+      fpsUpdateInterval: settings.fpsUpdateInterval || 0,
+      numImageWorkers:
+        settings.numImageWorkers !== undefined ? settings.numImageWorkers : 2,
+      enableContextSpy: settings.enableContextSpy ?? false,
+      enableInspector: settings.enableInspector ?? false,
+      renderMode: settings.renderMode ?? 'webgl',
+    };
+    this.settings = resolvedSettings;
+
+    const {
+      appWidth,
+      appHeight,
+      deviceLogicalPixelRatio,
+      devicePhysicalPixelRatio,
+      enableInspector,
+    } = resolvedSettings;
+
+    const deviceLogicalWidth = appWidth * deviceLogicalPixelRatio;
+    const deviceLogicalHeight = appHeight * deviceLogicalPixelRatio;
+
+    const canvas = document.createElement('canvas');
+    this.canvas = canvas;
+    canvas.width = deviceLogicalWidth * devicePhysicalPixelRatio;
+    canvas.height = deviceLogicalHeight * devicePhysicalPixelRatio;
+
+    canvas.style.width = `${deviceLogicalWidth}px`;
+    canvas.style.height = `${deviceLogicalHeight}px`;
+
+    // Initialize the stage
+    this.stage = new Stage({
+      appWidth: this.settings.appWidth,
+      appHeight: this.settings.appHeight,
+      boundsMargin: this.settings.boundsMargin,
+      clearColor: this.settings.clearColor,
+      canvas: this.canvas,
+      deviceLogicalPixelRatio: this.settings.deviceLogicalPixelRatio,
+      devicePhysicalPixelRatio: this.settings.devicePhysicalPixelRatio,
+      enableContextSpy: this.settings.enableContextSpy,
+      fpsUpdateInterval: this.settings.fpsUpdateInterval,
+      numImageWorkers: this.settings.numImageWorkers,
+      renderMode: this.settings.renderMode,
+      textureMemory: resolvedTxSettings,
+      eventBus: this,
+    });
+
+    // Extract the root node
+    this.root = this.stage.root as unknown as INode<
+      ShaderController<'DefaultShader'>
+    >;
+
+    // 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 (!targetEl) {
+      throw new Error('Could not find target element');
+    }
+
+    targetEl.appendChild(canvas);
+
+    // Initialize inspector (if enabled)
+    if (enableInspector && !isProductionEnvironment()) {
+      this.inspector = new Inspector(canvas, resolvedSettings);
+    }
+  }
+
+  /**
+   * Create a new scene graph node
+   *
+   * @remarks
+   * A node is the main graphical building block of the Renderer scene graph. It
+   * can be a container for other nodes, or it can be a leaf node that renders a
+   * solid color, gradient, image, or specific texture, using a specific shader.
+   *
+   * To create a text node, see {@link createTextNode}.
+   *
+   * See {@link CoreNode} for more details.
+   *
+   * @param props
+   * @returns
+   */
+  createNode<
+    ShCtr extends BaseShaderController = ShaderController<'DefaultShader'>,
+  >(props: Partial<INodeProps<ShCtr>>): INode<ShCtr> {
+    assertTruthy(this.stage, 'Stage is not initialized');
+
+    const node = this.stage.createNode(props as Partial<CoreNodeProps>);
+
+    if (this.inspector) {
+      return this.inspector.createNode(node) as unknown as INode<ShCtr>;
+    }
+
+    // FIXME onDestroy event? node.once('beforeDestroy'
+    // FIXME onCreate event?
+    return node as unknown as INode<ShCtr>;
+  }
+
+  /**
+   * Create a new scene graph text node
+   *
+   * @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.
+   *
+   * See {@link ITextNode} for more details.
+   *
+   * @param props
+   * @returns
+   */
+  createTextNode(props: Partial<ITextNodeProps>): ITextNode {
+    const textNode = this.stage.createTextNode(props as CoreTextNodeProps);
+
+    if (this.inspector) {
+      return this.inspector.createTextNode(textNode);
+    }
+
+    return textNode as unknown as ITextNode;
+  }
+
+  /**
+   * Destroy a node
+   *
+   * @remarks
+   * This method destroys a node
+   *
+   * @param node
+   * @returns
+   */
+  destroyNode(node: INode) {
+    if (this.inspector) {
+      this.inspector.destroyNode(node.id);
+    }
+
+    return node.destroy();
+  }
+
+  /**
+   * Create a new texture reference
+   *
+   * @remarks
+   * This method creates a new reference to a texture. The texture is not
+   * loaded until it is used on a node.
+   *
+   * It can be assigned to a node's `texture` property, or it can be used
+   * when creating a SubTexture.
+   *
+   * @param textureType
+   * @param props
+   * @param options
+   * @returns
+   */
+  createTexture<TxType extends keyof TextureTypeMap>(
+    textureType: TxType,
+    props: ExtractProps<TextureTypeMap[TxType]>,
+  ): TextureMap[TxType] {
+    return this.stage.txManager.loadTexture(
+      textureType,
+      props,
+    ) as TextureMap[TxType];
+  }
+
+  /**
+   * Create a new shader controller for a shader type
+   *
+   * @remarks
+   * This method creates a new Shader Controller for a specific shader type.
+   *
+   * If the shader has not been loaded yet, it will be loaded. Otherwise, the
+   * existing shader will be reused.
+   *
+   * It can be assigned to a Node's `shader` property.
+   *
+   * @param shaderType
+   * @param props
+   * @returns
+   */
+  createShader<ShType extends keyof ShaderMap>(
+    shaderType: ShType,
+    props?: ExtractProps<ShaderMap[ShType]>,
+  ): ShaderController<ShType> {
+    return this.stage.shManager.loadShader(shaderType, props);
+  }
+
+  createDynamicShader<
+    T extends DynamicEffects<[...{ name: string; type: keyof EffectMap }[]]>,
+  >(effects: [...T]): DynamicShaderController<T> {
+    return this.stage.shManager.loadDynamicShader({
+      effects: effects as EffectDescUnion[],
+    });
+  }
+
+  createEffect<Name extends string, Type extends keyof EffectMap>(
+    name: Name,
+    type: Type,
+    props: EffectDesc<{ name: Name; type: Type }>['props'],
+  ): EffectDesc<{ name: Name; type: Type }> {
+    return {
+      name,
+      type,
+      props,
+    };
+  }
+
+  /**
+   * Get a Node by its ID
+   *
+   * @param id
+   * @returns
+   */
+  getNodeById(id: number): CoreNode | null {
+    const root = this.stage?.root;
+    if (!root) {
+      return null;
+    }
+
+    const findNode = (node: CoreNode): CoreNode | null => {
+      if (node.id === id) {
+        return node;
+      }
+
+      for (const child of node.children) {
+        const found = findNode(child);
+        if (found) {
+          return found;
+        }
+      }
+
+      return null;
+    };
+
+    return findNode(root);
+  }
+
+  toggleFreeze() {
+    throw new Error('Not implemented');
+  }
+
+  advanceFrame() {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Re-render the current frame without advancing any running animations.
+   *
+   * @remarks
+   * Any state changes will be reflected in the re-rendered frame. Useful for
+   * debugging.
+   *
+   * May not do anything if the render loop is running on a separate worker.
+   */
+  rerender() {
+    throw new Error('Not implemented');
+  }
+}