@lightningtv/renderer 3.0.0-beta1

package/src/core/animations/CoreAnimationController.ts

@@ -0,0 +1,157 @@
+/* eslint-disable @typescript-eslint/unbound-method */
+/*
+ * 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 {
+  AnimationControllerState,
+  IAnimationController,
+} from '../../common/IAnimationController.js';
+import type { AnimationManager } from './AnimationManager.js';
+import type { CoreAnimation } from './CoreAnimation.js';
+import { assertTruthy } from '../../utils.js';
+import { EventEmitter } from '../../common/EventEmitter.js';
+import type { AnimationTickPayload } from '../../common/CommonTypes.js';
+
+export class CoreAnimationController
+  extends EventEmitter
+  implements IAnimationController
+{
+  stoppedPromise: Promise<void>;
+  /**
+   * If this is null, then the animation is in a finished / stopped state.
+   */
+  stoppedResolve: (() => void) | null = null;
+  state: AnimationControllerState;
+
+  constructor(
+    private manager: AnimationManager,
+    private animation: CoreAnimation,
+  ) {
+    super();
+    this.state = 'stopped';
+    // Initial stopped promise is resolved (since the animation is stopped)
+    this.stoppedPromise = Promise.resolve();
+
+    // Bind event handlers
+    this.onAnimating = this.onAnimating.bind(this);
+    this.onFinished = this.onFinished.bind(this);
+    this.onTick = this.onTick.bind(this);
+  }
+
+  start(): IAnimationController {
+    if (this.state !== 'running' && this.state !== 'scheduled') {
+      this.makeStoppedPromise();
+      this.registerAnimation();
+      this.state = 'scheduled';
+    }
+    return this;
+  }
+
+  stop(): IAnimationController {
+    this.unregisterAnimation();
+    if (this.stoppedResolve !== null) {
+      this.stoppedResolve();
+      this.stoppedResolve = null;
+      this.emit('stopped', this);
+    }
+    this.animation.reset();
+    this.state = 'stopped';
+    return this;
+  }
+
+  pause(): IAnimationController {
+    this.unregisterAnimation();
+    this.state = 'paused';
+    return this;
+  }
+
+  restore(): IAnimationController {
+    this.stoppedResolve = null;
+    this.animation.restore();
+    return this;
+  }
+
+  waitUntilStopped(): Promise<void> {
+    return this.stoppedPromise;
+  }
+
+  private registerAnimation(): void {
+    // Hook up event listeners
+    this.animation.once('finished', this.onFinished);
+    this.animation.on('animating', this.onAnimating);
+    this.animation.on('tick', this.onTick);
+    // Then register the animation
+    this.manager.registerAnimation(this.animation);
+  }
+
+  private unregisterAnimation(): void {
+    // First unregister the animation
+    this.manager.unregisterAnimation(this.animation);
+    // Then unhook event listeners
+    this.animation.off('finished', this.onFinished);
+    this.animation.off('animating', this.onAnimating);
+    this.animation.off('tick', this.onTick);
+  }
+
+  private makeStoppedPromise(): void {
+    if (this.stoppedResolve === null) {
+      this.stoppedPromise = new Promise((resolve) => {
+        this.stoppedResolve = resolve;
+      });
+    }
+  }
+
+  private onFinished(this: CoreAnimationController): void {
+    assertTruthy(this.stoppedResolve);
+    // If the animation is looping, then we need to restart it.
+    const { loop, stopMethod } = this.animation.settings;
+
+    if (stopMethod === 'reverse') {
+      this.animation.once('finished', this.onFinished);
+      this.animation.reverse();
+      return;
+    }
+
+    if (loop) {
+      return;
+    }
+
+    // unregister animation
+    this.unregisterAnimation();
+
+    // resolve promise
+    this.stoppedResolve();
+    this.stoppedResolve = null;
+    this.emit('stopped', this);
+    this.state = 'stopped';
+  }
+
+  private onAnimating(this: CoreAnimationController): void {
+    this.state = 'running';
+    this.emit('animating', this);
+  }
+
+  private onTick(
+    this: CoreAnimationController,
+    _animation: CoreAnimation,
+    data: AnimationTickPayload,
+  ): void {
+    this.emit('tick', data);
+  }
+}

package/src/core/lib/ContextSpy.ts

@@ -0,0 +1,41 @@
+/*
+ * 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.
+ */
+
+/**
+ * Class that keeps track of the invocations of Context methods when
+ * the `enableContextSpy` renderer option is enabled.
+ */
+export class ContextSpy {
+  private data: Record<string, number> = {};
+
+  reset() {
+    this.data = {};
+  }
+
+  increment(name: string) {
+    if (!this.data[name]) {
+      this.data[name] = 0;
+    }
+    this.data[name]++;
+  }
+
+  getData() {
+    return { ...this.data };
+  }
+}

package/src/core/lib/ImageWorker.ts

@@ -0,0 +1,279 @@
+/*
+ * 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 { CreateImageBitmapSupport } from '../lib/validateImageBitmap.js';
+import { type TextureData } from '../textures/Texture.js';
+
+type MessageCallback = [(value: any) => void, (reason: any) => void];
+interface getImageReturn {
+  data: ImageBitmap;
+  premultiplyAlpha: boolean | null;
+}
+
+interface ImageWorkerMessage {
+  id: number;
+  src: string;
+  data: getImageReturn;
+  error: string;
+  sx: number | null;
+  sy: number | null;
+  sw: number | null;
+  sh: number | null;
+}
+
+/**
+ * Note that, within the createImageWorker function, we must only use ES5 code to keep it ES5-valid after babelifying, as
+ *  the converted code of this section is converted to a blob and used as the js of the web worker thread.
+ *
+ * The createImageWorker function is a web worker that fetches an image from a URL and returns an ImageBitmap object.
+ * The eslint @typescript rule is disabled for the entire function because the function is converted to a blob and used as the
+ * js of the web worker thread, so the typescript syntax is not valid in this context.
+ */
+
+/* eslint-disable */
+function createImageWorker() {
+  function hasAlphaChannel(mimeType: string) {
+    return mimeType.indexOf('image/png') !== -1;
+  }
+
+  function getImage(
+    src: string,
+    premultiplyAlpha: boolean | null,
+    x: number | null,
+    y: number | null,
+    width: number | null,
+    height: number | null,
+    options: {
+      supportsOptionsCreateImageBitmap: boolean;
+      supportsFullCreateImageBitmap: boolean;
+    },
+  ): Promise<getImageReturn> {
+    return new Promise(function (resolve, reject) {
+      var supportsOptionsCreateImageBitmap =
+        options.supportsOptionsCreateImageBitmap;
+      var supportsFullCreateImageBitmap = options.supportsFullCreateImageBitmap;
+      var xhr = new XMLHttpRequest();
+      xhr.open('GET', src, true);
+      xhr.responseType = 'blob';
+
+      xhr.onload = function () {
+        // On most devices like WebOS and Tizen, the file protocol returns 0 while http(s) protocol returns 200
+        if (xhr.status !== 200 && xhr.status !== 0) {
+          return reject(new Error('Failed to load image: ' + xhr.statusText));
+        }
+
+        var blob = xhr.response;
+        var withAlphaChannel =
+          premultiplyAlpha !== undefined
+            ? premultiplyAlpha
+            : hasAlphaChannel(blob.type);
+
+        // createImageBitmap with crop and options
+        if (
+          supportsFullCreateImageBitmap === true &&
+          width !== null &&
+          height !== null
+        ) {
+          createImageBitmap(blob, x || 0, y || 0, width, height, {
+            premultiplyAlpha: withAlphaChannel ? 'premultiply' : 'none',
+            colorSpaceConversion: 'none',
+            imageOrientation: 'none',
+          })
+            .then(function (data) {
+              resolve({ data, premultiplyAlpha: premultiplyAlpha });
+            })
+            .catch(function (error) {
+              reject(error);
+            });
+          return;
+        } else if (
+          supportsOptionsCreateImageBitmap === false &&
+          supportsOptionsCreateImageBitmap === false
+        ) {
+          // Fallback for browsers that do not support createImageBitmap with options
+          // this is supported for Chrome v50 to v52/54 that doesn't support options
+          createImageBitmap(blob)
+            .then(function (data) {
+              resolve({ data, premultiplyAlpha: premultiplyAlpha });
+            })
+            .catch(function (error) {
+              reject(error);
+            });
+        } else {
+          createImageBitmap(blob, {
+            premultiplyAlpha: withAlphaChannel ? 'premultiply' : 'none',
+            colorSpaceConversion: 'none',
+            imageOrientation: 'none',
+          })
+            .then(function (data) {
+              resolve({ data, premultiplyAlpha: premultiplyAlpha });
+            })
+            .catch(function (error) {
+              reject(error);
+            });
+        }
+      };
+
+      xhr.onerror = function () {
+        reject(
+          new Error('Network error occurred while trying to fetch the image.'),
+        );
+      };
+
+      xhr.send();
+    });
+  }
+
+  self.onmessage = (event) => {
+    var src = event.data.src;
+    var id = event.data.id;
+    var premultiplyAlpha = event.data.premultiplyAlpha;
+    var x = event.data.sx;
+    var y = event.data.sy;
+    var width = event.data.sw;
+    var height = event.data.sh;
+
+    // these will be set to true if the browser supports the createImageBitmap options or full
+    var supportsOptionsCreateImageBitmap = false;
+    var supportsFullCreateImageBitmap = false;
+
+    getImage(src, premultiplyAlpha, x, y, width, height, {
+      supportsOptionsCreateImageBitmap,
+      supportsFullCreateImageBitmap,
+    })
+      .then(function (data) {
+        self.postMessage({ id: id, src: src, data: data });
+      })
+      .catch(function (error) {
+        self.postMessage({ id: id, src: src, error: error.message });
+      });
+  };
+}
+/* eslint-enable */
+
+export class ImageWorkerManager {
+  imageWorkersEnabled = true;
+  messageManager: Record<number, MessageCallback> = {};
+  workers: Worker[] = [];
+  workerIndex = 0;
+  nextId = 0;
+
+  constructor(
+    numImageWorkers: number,
+    createImageBitmapSupport: CreateImageBitmapSupport,
+  ) {
+    this.workers = this.createWorkers(
+      numImageWorkers,
+      createImageBitmapSupport,
+    );
+    this.workers.forEach((worker) => {
+      worker.onmessage = this.handleMessage.bind(this);
+    });
+  }
+
+  private handleMessage(event: MessageEvent) {
+    const { id, data, error } = event.data as ImageWorkerMessage;
+    const msg = this.messageManager[id];
+    if (msg) {
+      const [resolve, reject] = msg;
+      delete this.messageManager[id];
+      if (error) {
+        reject(new Error(error));
+      } else {
+        resolve(data);
+      }
+    }
+  }
+
+  private createWorkers(
+    numWorkers = 1,
+    createImageBitmapSupport: CreateImageBitmapSupport,
+  ): Worker[] {
+    let workerCode = `(${createImageWorker.toString()})()`;
+
+    // Replace placeholders with actual initialization values
+    if (createImageBitmapSupport.options === true) {
+      workerCode = workerCode.replace(
+        'var supportsOptionsCreateImageBitmap = false;',
+        'var supportsOptionsCreateImageBitmap = true;',
+      );
+    }
+
+    if (createImageBitmapSupport.full === true) {
+      workerCode = workerCode.replace(
+        'var supportsOptionsCreateImageBitmap = false;',
+        'var supportsOptionsCreateImageBitmap = true;',
+      );
+
+      workerCode = workerCode.replace(
+        'var supportsFullCreateImageBitmap = false;',
+        'var supportsFullCreateImageBitmap = true;',
+      );
+    }
+
+    workerCode = workerCode.replace('"use strict";', '');
+    const blob: Blob = new Blob([workerCode], {
+      type: 'application/javascript',
+    });
+    const blobURL: string = (self.URL ? URL : webkitURL).createObjectURL(blob);
+    const workers: Worker[] = [];
+    for (let i = 0; i < numWorkers; i++) {
+      workers.push(new Worker(blobURL));
+    }
+    return workers;
+  }
+
+  private getNextWorker(): Worker | undefined {
+    const worker = this.workers[this.workerIndex];
+    this.workerIndex = (this.workerIndex + 1) % this.workers.length;
+    return worker;
+  }
+
+  getImage(
+    src: string,
+    premultiplyAlpha: boolean | null,
+    sx: number | null,
+    sy: number | null,
+    sw: number | null,
+    sh: number | null,
+  ): Promise<TextureData> {
+    return new Promise((resolve, reject) => {
+      try {
+        if (this.workers) {
+          const id = this.nextId++;
+          this.messageManager[id] = [resolve, reject];
+          const nextWorker = this.getNextWorker();
+          if (nextWorker) {
+            nextWorker.postMessage({
+              id,
+              src: src,
+              premultiplyAlpha,
+              sx,
+              sy,
+              sw,
+              sh,
+            });
+          }
+        }
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+}

package/src/core/lib/Matrix3d.ts

@@ -0,0 +1,244 @@
+/*
+ * 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.
+ */
+
+/**
+ * A 3D matrix representing a 2D graphics transformation
+ *
+ * @remarks
+ * For convenience, entries in the first two rows can be accessed by the following
+ * properties:
+ * | ta tb tx |
+ * | tc td ty |
+ * | 0  0  1  |
+ *
+ * This matrix is optimized for 2D transformations and hence the last row will
+ * always be considered [0, 0 ,1].
+ *
+ * To access a column major array for WebGL, use the {@link getFloatArr} method.
+ */
+export class Matrix3d {
+  public ta: number;
+  public tb: number;
+  public tx: number;
+  public tc: number;
+  public td: number;
+  public ty: number;
+  private _floatArr: Float32Array | null = null;
+  /**
+   * Potential Mutation Flag
+   *
+   * @remarks
+   * This flag is set to true whenever the matrix is potentially modified.
+   * We don't waste CPU trying to identify if each operation actually modifies
+   * the matrix. Instead, we set this flag to true whenever we think the matrix
+   * is modified. This signals that the `floatArr` should to be updated.
+   */
+  private mutation: boolean;
+
+  /**
+   * Creates a new 3x3 matrix.
+   *
+   * @param entries Row-major 3x3 matrix
+   */
+  public constructor() {
+    this.ta = 0;
+    this.tb = 0;
+    this.tx = 0;
+    this.tc = 0;
+    this.td = 0;
+    this.ty = 0;
+    this.mutation = true;
+  }
+
+  /**
+   * Returns a temporary matrix that can be used for calculations.
+   *
+   * @remarks
+   * This is useful for avoiding allocations in tight loops.
+   *
+   * The matrix is not guaranteed to be the same between calls.
+   *
+   * @returns
+   */
+  public static get temp(): Matrix3d {
+    return tempMatrix;
+  }
+
+  public static multiply(a: Matrix3d, b: Matrix3d, out?: Matrix3d): Matrix3d {
+    const e0 = a.ta * b.ta + a.tb * b.tc;
+    const e1 = a.ta * b.tb + a.tb * b.td;
+    const e2 = a.ta * b.tx + a.tb * b.ty + a.tx;
+    const e3 = a.tc * b.ta + a.td * b.tc;
+    const e4 = a.tc * b.tb + a.td * b.td;
+    const e5 = a.tc * b.tx + a.td * b.ty + a.ty;
+    if (!out) {
+      out = new Matrix3d();
+    }
+    out.ta = e0;
+    out.tb = e1;
+    out.tx = e2;
+    out.tc = e3;
+    out.td = e4;
+    out.ty = e5;
+    out.mutation = true;
+    return out;
+  }
+
+  public static identity(out?: Matrix3d): Matrix3d {
+    if (!out) {
+      out = new Matrix3d();
+    }
+    out.ta = 1;
+    out.tb = 0;
+    out.tx = 0;
+    out.tc = 0;
+    out.td = 1;
+    out.ty = 0;
+    out.mutation = true;
+    return out;
+  }
+
+  public static translate(x: number, y: number, out?: Matrix3d): Matrix3d {
+    if (!out) {
+      out = new Matrix3d();
+    }
+    out.ta = 1;
+    out.tb = 0;
+    out.tx = x;
+    out.tc = 0;
+    out.td = 1;
+    out.ty = y;
+    out.mutation = true;
+    return out;
+  }
+
+  public static scale(sx: number, sy: number, out?: Matrix3d): Matrix3d {
+    if (!out) {
+      out = new Matrix3d();
+    }
+    out.ta = sx;
+    out.tb = 0;
+    out.tx = 0;
+    out.tc = 0;
+    out.td = sy;
+    out.ty = 0;
+    out.mutation = true;
+    return out;
+  }
+
+  public static rotate(angle: number, out?: Matrix3d): Matrix3d {
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    if (!out) {
+      out = new Matrix3d();
+    }
+    out.ta = cos;
+    out.tb = -sin;
+    out.tx = 0;
+    out.tc = sin;
+    out.td = cos;
+    out.ty = 0;
+    out.mutation = true;
+    return out;
+  }
+
+  public static copy(src: Matrix3d, dst?: Matrix3d): Matrix3d {
+    if (!dst) {
+      dst = new Matrix3d();
+    }
+    dst.ta = src.ta;
+    dst.tc = src.tc;
+    dst.tb = src.tb;
+    dst.td = src.td;
+    dst.tx = src.tx;
+    dst.ty = src.ty;
+    dst.mutation = true;
+    return dst;
+  }
+
+  public translate(x: number, y: number): Matrix3d {
+    this.tx = this.ta * x + this.tb * y + this.tx;
+    this.ty = this.tc * x + this.td * y + this.ty;
+    this.mutation = true;
+    return this;
+  }
+
+  public scale(sx: number, sy: number): Matrix3d {
+    this.ta = this.ta * sx;
+    this.tb = this.tb * sy;
+    this.tc = this.tc * sx;
+    this.td = this.td * sy;
+    this.mutation = true;
+    return this;
+  }
+
+  public rotate(angle: number): Matrix3d {
+    if (angle === 0 || !((angle % Math.PI) * 2)) {
+      return this;
+    }
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    const e0 = this.ta * cos + this.tb * sin;
+    const e1 = this.tb * cos - this.ta * sin;
+    const e3 = this.tc * cos + this.td * sin;
+    const e4 = this.td * cos - this.tc * sin;
+    this.ta = e0;
+    this.tb = e1;
+    this.tc = e3;
+    this.td = e4;
+    this.mutation = true;
+    return this;
+  }
+
+  public multiply(other: Matrix3d): Matrix3d {
+    return Matrix3d.multiply(this, other, this);
+  }
+
+  /**
+   * Returns the matrix as a Float32Array in column-major order.
+   *
+   * @remarks
+   * This method is optimized to avoid unnecessary allocations. The same array
+   * is returned every time this method is called, and is updated in place.
+   *
+   * WARNING: Use the array only for passing directly to a WebGL shader uniform
+   * during a frame render. Do not modify or hold onto the array for longer than
+   * a frame.
+   */
+  getFloatArr(): Float32Array {
+    if (!this._floatArr) {
+      this._floatArr = new Float32Array(9);
+    }
+    if (this.mutation) {
+      this._floatArr[0] = this.ta;
+      this._floatArr[1] = this.tc;
+      this._floatArr[2] = 0;
+      this._floatArr[3] = this.tb;
+      this._floatArr[4] = this.td;
+      this._floatArr[5] = 0;
+      this._floatArr[6] = this.tx;
+      this._floatArr[7] = this.ty;
+      this._floatArr[8] = 1;
+      this.mutation = false;
+    }
+    return this._floatArr;
+  }
+}
+
+const tempMatrix = new Matrix3d();