@lightningtv/renderer 3.0.0-beta1

package/exports/webgl.ts

@@ -0,0 +1,50 @@
+/*
+ * 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.
+ */
+
+/**
+ * SDF Font renderer
+ *
+ * @remarks
+ * This module exports the SDF Font renderer for the Lightning 3 Renderer.
+ * The SDF Font renderer is used to render text using Single-Channel Signed
+ * Distance Field (SSDF) fonts or Multi-Channel Signed Distance Field (MSDF)
+ * fonts. The SDF font renderer is used to render text in a way that is
+ * optimized for GPU rendering.
+ *
+ * You can import the exports from this module like so:
+ * ```ts
+ * import { SdfTextRenderer } from '@lightning/renderer';
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { SdfTextRenderer } from '../src/core/text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.js';
+export { WebGlRenderer } from '../src/core/renderers/webgl/WebGlRenderer.js';
+export { WebGlCtxTexture } from '../src/core/renderers/webgl/WebGlCtxTexture.js';
+
+export * from '../src/core/renderers/webgl/WebGlShaderNode.js';
+
+/**
+ * @deprecated Use WebGlRenderer.
+ */
+export { WebGlRenderer as WebGlCoreRenderer } from '../src/core/renderers/webgl/WebGlRenderer.js';
+export { WebGlRenderer as WebGlCoreCtxTexture } from '../src/core/renderers/webgl/WebGlRenderer.js';
+
+export * as shaders from './webgl-shaders.js';

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@lightningtv/renderer",
+  "version": "3.0.0-beta1",
+  "description": "Lightning 3 Renderer",
+  "type": "module",
+  "main": "./dist/exports/index.js",
+  "exports": {
+    ".": "./dist/exports/index.js",
+    "./utils": "./dist/exports/utils.js",
+    "./canvas": "./dist/exports/canvas.js",
+    "./canvas/shaders": "./dist/exports/canvas-shaders.js",
+    "./webgl": "./dist/exports/webgl.js",
+    "./webgl/shaders": "./dist/exports/webgl-shaders.js",
+    "./inspector": "./dist/exports/inspector.js"
+  },
+  "scripts": {
+    "preinstall": "node scripts/please-use-pnpm.js",
+    "start": "cd examples && pnpm start",
+    "start:prod": "cd examples && pnpm start:prod",
+    "build": "tsc --build",
+    "build:docker": "cd visual-regression && pnpm build:docker",
+    "watch": "tsc --build --watch",
+    "test": "vitest",
+    "coverage": "vitest run --coverage",
+    "test:visual": "cd visual-regression && pnpm test:visual",
+    "lint": "pnpm run lint:prettier && pnpm run lint:eslint",
+    "lint:fix": "pnpm run lint:fix:prettier && pnpm run lint:fix:eslint",
+    "lint:prettier": "prettier --check \"**/*.{ts,js,cjs,md}\"",
+    "lint:fix:prettier": "prettier --write \"**/*.{ts,js,cjs,md}\"",
+    "lint:eslint": "eslint .",
+    "lint:fix:eslint": "eslint --fix .",
+    "typedoc": "typedoc",
+    "prepare": "husky install",
+    "prepack": "pnpm run build",
+    "node-version": "node --version"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lightning-tv/renderer.git"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "Lightning",
+    "LightningJS",
+    "WebGL",
+    "JS",
+    "WPE"
+  ],
+  "author": "Comcast Cable Communications Management, LLC",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/lightning-js/renderer/issues"
+  },
+  "homepage": "https://github.com/lightning-js/renderer#readme",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.16.0",
+    "@typescript-eslint/parser": "^8.16.0",
+    "@vitest/coverage-v8": "^2.1.5",
+    "concurrently": "^8.0.1",
+    "eslint": "^9.15.0",
+    "eslint-config-prettier": "^8.7.0",
+    "husky": "^8.0.3",
+    "lint-staged": "^13.2.0",
+    "prettier": "^2.8.4",
+    "typedoc": "^0.26.11",
+    "typescript": "~5.6.3",
+    "vitest": "^2.0.0",
+    "vitest-mock-extended": "^2.0.2"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "prettier --write",
+      "eslint --fix"
+    ],
+    "*.{js,cjs,md}": "prettier --write"
+  },
+  "files": [
+    "dist",
+    "src",
+    "exports",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "scripts"
+  ],
+  "packageManager": "pnpm@8.9.2",
+  "engines": {
+    "npm": ">= 10.0.0",
+    "pnpm": ">= 8.9.2",
+    "node": ">= 20.9.0"
+  }
+}

package/scripts/please-use-pnpm.js

@@ -0,0 +1,13 @@
+if (
+  process.cwd() === process.env.INIT_CWD &&
+  !process.env.npm_execpath.includes('pnpm')
+) {
+  console.log('\x1b[31m');
+  console.log('=============================================\n');
+  console.log('     Please use PNPM as a package manager');
+  console.log('     See: https://pnpm.io/ for more info');
+  console.log('\n=============================================');
+  console.log('\x1b[0m');
+
+  process.exit(1);
+}

package/src/common/CommonTypes.ts

@@ -0,0 +1,146 @@
+/*
+ * 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 { CoreNodeRenderState } from '../core/CoreNode.js';
+
+/**
+ * Types shared between Main Space and Core Space
+ *
+ * @remarks
+ *
+ * @module
+ */
+
+/**
+ * Represents a width and height.
+ */
+export interface Dimensions {
+  width: number;
+  height: number;
+}
+
+/**
+ * Payload for when text is loaded
+ */
+export type NodeTextLoadedPayload = {
+  type: 'text';
+  dimensions: Dimensions;
+};
+
+/**
+ * Payload for when texture is loaded
+ */
+export type NodeTextureLoadedPayload = {
+  type: 'texture';
+  dimensions: Dimensions;
+};
+
+/**
+ * Combined type for all loaded payloads
+ */
+export type NodeLoadedPayload =
+  | NodeTextLoadedPayload
+  | NodeTextureLoadedPayload;
+
+/**
+ * Payload for when text failed to load
+ */
+export type NodeTextFailedPayload = {
+  type: 'text';
+  error: Error;
+};
+
+/**
+ * Payload for when texture failed to load
+ */
+export type NodeTextureFailedPayload = {
+  type: 'texture';
+  error: Error;
+};
+
+/**
+ * Payload for when texture failed to load
+ */
+export type NodeTextureFreedPayload = {
+  type: 'texture';
+};
+
+/**
+ * Combined type for all failed payloads
+ */
+export type NodeFailedPayload =
+  | NodeTextFailedPayload
+  | NodeTextureFailedPayload;
+
+/**
+ * Event handler for when the texture/text of a node has loaded
+ */
+export type NodeLoadedEventHandler = (
+  target: any,
+  payload: NodeLoadedPayload,
+) => void;
+
+/**
+ * Event handler for when the texture/text of a node has failed to load
+ */
+export type NodeFailedEventHandler = (
+  target: any,
+  payload: NodeFailedPayload,
+) => void;
+
+export type NodeRenderStatePayload = {
+  type: 'renderState';
+  payload: CoreNodeRenderState;
+};
+
+export type NodeRenderStateEventHandler = (
+  target: any,
+  payload: NodeRenderStatePayload,
+) => void;
+
+/**
+ * Event payload for when an FpsUpdate event is emitted by either the Stage or
+ * MainRenderer
+ */
+export interface FpsUpdatePayload {
+  fps: number;
+  contextSpyData: Record<string, number> | null;
+}
+
+/**
+ * Event payload for when a frame tick event is emitted by the Stage
+ */
+export interface FrameTickPayload {
+  time: number;
+  delta: number;
+}
+
+/**
+ * Event payload for when a an animtion tick event is emitted
+ */
+export interface AnimationTickPayload {
+  progress: number;
+}
+
+/**
+ * Event payload for when an QuadsUpdate event is emitted by the Stage
+ */
+export interface QuadsUpdatePayload {
+  quads: number;
+}

package/src/common/EventEmitter.ts

@@ -0,0 +1,77 @@
+/*
+ * 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-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unsafe-call */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { IEventEmitter } from './IEventEmitter.js';
+
+/**
+ * EventEmitter base class
+ */
+export class EventEmitter implements IEventEmitter {
+  private eventListeners: { [eventName: string]: any } = {};
+
+  on(event: string, listener: (target: any, data: any) => void): void {
+    let listeners = this.eventListeners[event];
+    if (!listeners) {
+      listeners = [];
+    }
+    listeners.push(listener);
+    this.eventListeners[event] = listeners;
+  }
+
+  off(event: string, listener?: (target: any, data: any) => void): void {
+    const listeners = this.eventListeners[event];
+    if (!listeners) {
+      return;
+    }
+    if (!listener) {
+      delete this.eventListeners[event];
+      return;
+    }
+    const index = listeners.indexOf(listener);
+    if (index >= 0) {
+      listeners.splice(index, 1);
+    }
+  }
+
+  once(event: string, listener: (target: any, data: any) => void): void {
+    const onceListener = (target: any, data: any) => {
+      this.off(event, onceListener);
+      listener(target, data);
+    };
+    this.on(event, onceListener);
+  }
+
+  emit(event: string, data?: any): void {
+    const listeners = this.eventListeners[event];
+    if (!listeners) {
+      return;
+    }
+    [...listeners].forEach((listener) => {
+      listener(this, data);
+    });
+  }
+
+  removeAllListeners() {
+    this.eventListeners = {};
+  }
+}

package/src/common/IAnimationController.ts

@@ -0,0 +1,92 @@
+/*
+ * 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 { IEventEmitter } from './IEventEmitter.js';
+
+export type AnimationControllerState =
+  | 'scheduled'
+  | 'running'
+  | 'paused'
+  | 'stopped';
+
+/**
+ * Animation Controller interface
+ *
+ * @remarks
+ * This interface is used to control animations. It provides methods to start,
+ * stop, pause, and restore animations. It also provides a way to wait for the
+ * animation to stop.
+ *
+ * This interface extends the `IEventEmitter` interface, which means you can
+ * listen to these events emitted by the animation controller:
+ * - `animating` - Emitted when the animation finishes it's delay phase and
+ *   starts animating.
+ * - `stopped` - Emitted when the animation stops either by calling the `stop()`
+ *    method or when the animation finishes naturally.
+ */
+export interface IAnimationController extends IEventEmitter {
+  /**
+   * Start the animation
+   *
+   * @remarks
+   * If the animation is paused this method will resume the animation.
+   */
+  start(): IAnimationController;
+  /**
+   * Stop the animation
+   *
+   * @remarks
+   * Resets the animation to the start state
+   */
+  stop(): IAnimationController;
+  /**
+   * Pause the animation
+   */
+  pause(): IAnimationController;
+  /**
+   * Restore the animation to the original values
+   */
+  restore(): IAnimationController;
+
+  /**
+   * Promise that resolves when the last active animation is stopped (including
+   * when the animation finishes naturally).
+   *
+   * @remarks
+   * The Promise returned by this method is reset every time the animation
+   * enters a new start/stop cycle. This means you must call `start()` before
+   * calling this method if you want to wait for the animation to stop.
+   *
+   * This method always returns a resolved promise if the animation is currently
+   * in a stopped state.
+   *
+   * @returns
+   */
+  waitUntilStopped(): Promise<void>;
+
+  /**
+   * Current state of the animation
+   *
+   * @remarks
+   * - `stopped` - The animation is currently stopped (at the beggining or end
+   *   of the animation)
+   * - `running` - The animation is currently running
+   * - `paused` - The animation is currently paused
+   */
+  readonly state: AnimationControllerState;
+}

package/src/common/IEventEmitter.ts

@@ -0,0 +1,28 @@
+/*
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface IEventEmitter<
+  T extends object = { [s: string]: (target: any, data: any) => void },
+> {
+  on<K extends keyof T>(event: Extract<K, string>, listener: T[K]): void;
+  once<K extends keyof T>(event: Extract<K, string>, listener: T[K]): void;
+  off<K extends keyof T>(event: Extract<K, string>, listener: T[K]): void;
+  emit<K extends keyof T>(
+    event: Extract<K, string>,
+    data: Parameters<any>[1],
+  ): void;
+}

package/src/core/CoreNode.test.ts

@@ -0,0 +1,203 @@
+/*
+ * 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 { describe, expect, it, vi } from 'vitest';
+import { CoreNode, type CoreNodeProps, UpdateType } from './CoreNode.js';
+import { Stage } from './Stage.js';
+import { mock } from 'vitest-mock-extended';
+import { type TextureOptions } from './CoreTextureManager.js';
+import { createBound } from './lib/utils.js';
+import { ImageTexture } from './textures/ImageTexture.js';
+
+describe('set color()', () => {
+  const defaultProps: CoreNodeProps = {
+    alpha: 0,
+    autosize: false,
+    boundsMargin: null,
+    clipping: false,
+    color: 0,
+    colorBl: 0,
+    colorBottom: 0,
+    colorBr: 0,
+    colorLeft: 0,
+    colorRight: 0,
+    colorTl: 0,
+    colorTop: 0,
+    colorTr: 0,
+    height: 0,
+    mount: 0,
+    mountX: 0,
+    mountY: 0,
+    parent: null,
+    pivot: 0,
+    pivotX: 0,
+    pivotY: 0,
+    rotation: 0,
+    rtt: false,
+    scale: 0,
+    scaleX: 0,
+    scaleY: 0,
+    shader: null,
+    src: '',
+    texture: null,
+    textureOptions: {} as TextureOptions,
+    width: 0,
+    x: 0,
+    y: 0,
+    zIndex: 0,
+    zIndexLocked: 0,
+    preventCleanup: false,
+    strictBounds: false,
+  };
+
+  const clippingRect = {
+    x: 0,
+    y: 0,
+    width: 200,
+    height: 200,
+    valid: false,
+  };
+
+  const stage = mock<Stage>({
+    strictBound: createBound(0, 0, 200, 200),
+    preloadBound: createBound(0, 0, 200, 200),
+    defaultTexture: {
+      state: 'loaded',
+    },
+  });
+
+  describe('set color()', () => {
+    it('should set all color subcomponents.', () => {
+      const node = new CoreNode(stage, defaultProps);
+      node.colorBl = 0x99aabbff;
+      node.colorBr = 0xaabbccff;
+      node.colorTl = 0xbbcceeff;
+      node.colorTr = 0xcceeffff;
+
+      node.color = 0xffffffff;
+      node.color = 0xffffffff;
+
+      expect(node.color).toBe(0xffffffff);
+      expect(node.colorBl).toBe(0xffffffff);
+      expect(node.colorBr).toBe(0xffffffff);
+      expect(node.colorTl).toBe(0xffffffff);
+      expect(node.colorTr).toBe(0xffffffff);
+      expect(node.colorLeft).toBe(0xffffffff);
+      expect(node.colorRight).toBe(0xffffffff);
+      expect(node.colorTop).toBe(0xffffffff);
+      expect(node.colorBottom).toBe(0xffffffff);
+    });
+
+    it('should set update type.', () => {
+      const node = new CoreNode(stage, defaultProps);
+      node.updateType = 0;
+
+      node.color = 0xffffffff;
+      node.color = 0xffffffff;
+
+      expect(node.updateType).toBe(UpdateType.PremultipliedColors);
+    });
+  });
+
+  describe('isRenderable checks', () => {
+    it('should return false if node is not renderable', () => {
+      const node = new CoreNode(stage, defaultProps);
+      expect(node.isRenderable).toBe(false);
+    });
+
+    it('visible node that is a color texture', () => {
+      const node = new CoreNode(stage, defaultProps);
+      node.alpha = 1;
+      node.x = 0;
+      node.y = 0;
+      node.width = 100;
+      node.height = 100;
+      node.color = 0xffffffff;
+
+      node.update(0, clippingRect);
+      expect(node.isRenderable).toBe(true);
+    });
+
+    it('visible node that is a texture', () => {
+      const node = new CoreNode(stage, defaultProps);
+      node.alpha = 1;
+      node.x = 0;
+      node.y = 0;
+      node.width = 100;
+      node.height = 100;
+      node.texture = mock<ImageTexture>({
+        state: 'initial',
+      });
+
+      node.update(0, clippingRect);
+      expect(node.isRenderable).toBe(false);
+
+      node.texture.state = 'loaded';
+      node.setUpdateType(UpdateType.IsRenderable);
+      node.update(1, clippingRect);
+
+      expect(node.isRenderable).toBe(true);
+    });
+
+    it('a node with a texture with alpha 0 should not be renderable', () => {
+      const node = new CoreNode(stage, defaultProps);
+      node.alpha = 0;
+      node.x = 0;
+      node.y = 0;
+      node.width = 100;
+      node.height = 100;
+      node.texture = mock<ImageTexture>({
+        state: 'loaded',
+      });
+
+      node.update(0, clippingRect);
+      expect(node.isRenderable).toBe(false);
+    });
+
+    it('a node with a texture that is OutOfBounds should not be renderable', () => {
+      const node = new CoreNode(stage, defaultProps);
+      node.alpha = 1;
+      node.x = 300;
+      node.y = 300;
+      node.width = 100;
+      node.height = 100;
+      node.texture = mock<ImageTexture>({
+        state: 'loaded',
+      });
+
+      node.update(0, clippingRect);
+      expect(node.isRenderable).toBe(false);
+    });
+
+    it('a node with a freed texture should not be renderable', () => {
+      const node = new CoreNode(stage, defaultProps);
+      node.alpha = 1;
+      node.x = 0;
+      node.y = 0;
+      node.width = 100;
+      node.height = 100;
+      node.texture = mock<ImageTexture>({
+        state: 'freed',
+      });
+
+      node.update(0, clippingRect);
+      expect(node.isRenderable).toBe(false);
+    });
+  });
+});