@lightningjs/renderer 0.3.0 → 0.3.2

package/src/core/textures/SubTexture.ts

@@ -0,0 +1,140 @@
+/*
+ * 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 {
+  TextureFailedEventHandler,
+  TextureLoadedEventHandler,
+} from '../../common/CommonTypes.js';
+import type { TextureDesc } from '../../main-api/RendererMain.js';
+import type { CoreTextureManager } from '../CoreTextureManager.js';
+import { Texture } from './Texture.js';
+
+/**
+ * Properties of the {@link SubTexture}
+ */
+export interface SubTextureProps {
+  /**
+   * The texture that this sub-texture is a sub-region of.
+   */
+  texture: TextureDesc;
+
+  /**
+   * The x pixel position of the top-left of the sub-texture within the parent
+   * texture.
+   *
+   * @default 0
+   */
+  x?: number;
+
+  /**
+   * The y pixel position of the top-left sub-texture within the parent
+   * texture.
+   *
+   * @default 0
+   **/
+  y?: number;
+
+  /**
+   * The width of the sub-texture in pixels.
+   *
+   * @default 0
+   */
+  width?: number;
+
+  /**
+   * The height of the sub-texture in pixels
+   **/
+  height?: number;
+}
+
+/**
+ * A Texture that is a sub-region of another Texture.
+ *
+ * @remarks
+ * The parent texture can be a Sprite Sheet/Texture Atlas and set using the
+ * {@link SubTextureProps.texture} prop. The sub-region relative to the parent
+ * texture is defined with the {@link SubTextureProps.x},
+ * {@link SubTextureProps.y}, {@link SubTextureProps.width}, and
+ * {@link SubTextureProps.height} pixel values.
+ */
+export class SubTexture extends Texture {
+  props: Required<SubTextureProps>;
+  parentTexture: Texture;
+
+  constructor(txManager: CoreTextureManager, props: SubTextureProps) {
+    super(txManager);
+    this.parentTexture = this.txManager.loadTexture(
+      props.texture.txType,
+      props.texture.props,
+      props.texture.options,
+    );
+    this.props = SubTexture.resolveDefaults(props || {});
+
+    // If parent texture is already loaded / failed, trigger loaded event manually
+    // so that users get a consistent event experience.
+    // We do this in a microtask to allow listeners to be attached in the same
+    // synchronous task after calling loadTexture()
+    queueMicrotask(() => {
+      const parentTx = this.parentTexture;
+      if (parentTx.state === 'loaded') {
+        this.onParentTxLoaded(parentTx, parentTx.dimensions!);
+      } else if (parentTx.state === 'failed') {
+        this.onParentTxFailed(parentTx, parentTx.error!);
+      }
+      parentTx.on('loaded', this.onParentTxLoaded);
+      parentTx.on('failed', this.onParentTxFailed);
+    });
+  }
+
+  private onParentTxLoaded: TextureLoadedEventHandler = () => {
+    // We ignore the parent's passed dimensions, and simply use the SubTexture's
+    // configured dimensions (because that's all that matters here)
+    this.setState('loaded', {
+      width: this.props.width,
+      height: this.props.height,
+    });
+  };
+
+  private onParentTxFailed: TextureFailedEventHandler = (target, error) => {
+    this.setState('failed', error);
+  };
+
+  override async getTextureData(): Promise<SubTextureProps> {
+    return this.props;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  static override makeCacheKey(props: SubTextureProps): string | false {
+    return false;
+  }
+
+  static override resolveDefaults(
+    props: SubTextureProps,
+  ): Required<SubTextureProps> {
+    return {
+      texture: props.texture,
+      x: props.x || 0,
+      y: props.y || 0,
+      width: props.width || 0,
+      height: props.height || 0,
+    };
+  }
+
+  static z$__type__Props: SubTextureProps;
+}

package/src/core/textures/Texture.ts

@@ -0,0 +1,162 @@
+/*
+ * 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 { CoreTextureManager } from '../CoreTextureManager.js';
+import type { SubTextureProps } from './SubTexture.js';
+import type {
+  Dimensions,
+  TextureFailedEventHandler,
+  TextureLoadedEventHandler,
+  TextureLoadingEventHandler,
+} from '../../common/CommonTypes.js';
+import { EventEmitter } from '../../common/EventEmitter.js';
+
+/**
+ * Texture sources that are used to populate a CoreContextTexture
+ */
+export type TextureData = ImageBitmap | SubTextureProps | null;
+
+export type TextureState = 'loading' | 'loaded' | 'failed';
+
+export interface TextureStateEventMap {
+  loading: TextureLoadingEventHandler;
+  loaded: TextureLoadedEventHandler;
+  failed: TextureFailedEventHandler;
+}
+
+/**
+ * Like the built-in Parameters<> type but skips the first parameter (which is
+ * `target` currently)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ParametersSkipTarget<T extends (...args: any) => any> = T extends (
+  target: any,
+  ...args: infer P
+) => any
+  ? P
+  : never;
+
+/**
+ * Represents a source of texture data for a CoreContextTexture.
+ *
+ * @remarks
+ * Texture sources are used to populate a CoreContextTexture when that texture
+ * is loaded. Texture data retrieved by the CoreContextTexture by the
+ * `getTextureData` method. It's the responsibility of the concerete `Texture`
+ * subclass to implement this method appropriately.
+ */
+export abstract class Texture extends EventEmitter {
+  /**
+   * The dimensions of the texture
+   *
+   * @remarks
+   * Until the texture data is loaded for the first time the value will be
+   * `null`.
+   */
+  readonly dimensions: Readonly<Dimensions> | null = null;
+
+  readonly error: Error | null = null;
+
+  readonly state: TextureState = 'loading';
+
+  constructor(protected txManager: CoreTextureManager) {
+    super();
+  }
+
+  /**
+   * Set the state of the texture
+   *
+   * @remark
+   * Intended for internal-use only but declared public so that it can be set
+   * by it's associated {@link CoreContextTexture}
+   *
+   * @param state
+   * @param args
+   */
+  setState<State extends TextureState>(
+    state: State,
+    ...args: ParametersSkipTarget<TextureStateEventMap[State]>
+  ): void {
+    if (this.state !== state) {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+      (this.state as TextureState) = state;
+      if (state === 'loaded') {
+        const loadedArgs = args as ParametersSkipTarget<
+          TextureStateEventMap['loaded']
+        >;
+        (this.dimensions as Dimensions) = loadedArgs[0];
+      } else if (state === 'failed') {
+        const failedArgs = args as ParametersSkipTarget<
+          TextureStateEventMap['failed']
+        >;
+        (this.error as Error) = failedArgs[0];
+      }
+      this.emit(state, ...args);
+    }
+  }
+
+  /**
+   * Get the texture data for this texture.
+   *
+   * @remarks
+   * This method is called by the CoreContextTexture when the texture is loaded.
+   * The texture data is then used to populate the CoreContextTexture.
+   *
+   * @returns
+   * The texture data for this texture.
+   */
+  abstract getTextureData(): Promise<TextureData>;
+
+  /**
+   * Make a cache key for this texture.
+   *
+   * @remarks
+   * Each concrete `Texture` subclass must implement this method to provide an
+   * appropriate cache key for the texture type including the texture's
+   * properties that uniquely identify a copy of the texture. If the texture
+   * type does not support caching, then this method should return `false`.
+   *
+   * @param props
+   * @returns
+   * A cache key for this texture or `false` if the texture type does not
+   * support caching.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  static makeCacheKey(props: unknown): string | false {
+    return false;
+  }
+
+  /**
+   * Resolve the default values for the texture's properties.
+   *
+   * @remarks
+   * Each concrete `Texture` subclass must implement this method to provide
+   * default values for the texture's optional properties.
+   *
+   * @param props
+   * @returns
+   * The default values for the texture's properties.
+   */
+  static resolveDefaults(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    props: unknown,
+  ): Record<string, unknown> {
+    return {};
+  }
+}

package/src/core/utils.ts

@@ -0,0 +1,222 @@
+/*
+ * 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.
+ */
+
+/**
+ * Core Utility Functions
+ *
+ * @module
+ */
+
+export const EPSILON = 0.000001;
+export let ARRAY_TYPE =
+  typeof Float32Array !== 'undefined' ? Float32Array : Array;
+export const RANDOM = Math.random;
+export const ANGLE_ORDER = 'zyx';
+const degree = Math.PI / 180;
+
+export const setMatrixArrayType = (
+  type: Float32ArrayConstructor | ArrayConstructor,
+) => {
+  ARRAY_TYPE = type;
+};
+
+export const toRadian = (a: number) => {
+  return a * degree;
+};
+
+export const equals = (a: number, b: number) => {
+  return Math.abs(a - b) <= EPSILON * Math.max(1.0, Math.abs(a), Math.abs(b));
+};
+
+export const rand = (min: number, max: number) => {
+  return Math.floor(Math.random() * (max - min + 1) + min);
+};
+
+export const isPowerOfTwo = (value: number) => {
+  return value && !(value & (value - 1));
+};
+
+const getTimingBezier = (
+  a: number,
+  b: number,
+  c: number,
+  d: number,
+): ((time: number) => number | undefined) => {
+  const xc = 3.0 * a;
+  const xb = 3.0 * (c - a) - xc;
+  const xa = 1.0 - xc - xb;
+  const yc = 3.0 * b;
+  const yb = 3.0 * (d - b) - yc;
+  const ya = 1.0 - yc - yb;
+
+  return function (time: number): number | undefined {
+    if (time >= 1.0) {
+      return 1;
+    }
+    if (time <= 0) {
+      return 0;
+    }
+
+    let t = 0.5,
+      cbx,
+      cbxd,
+      dx;
+
+    for (let it = 0; it < 20; it++) {
+      cbx = t * (t * (t * xa + xb) + xc);
+      dx = time - cbx;
+      if (dx > -1e-8 && dx < 1e-8) {
+        return t * (t * (t * ya + yb) + yc);
+      }
+
+      // Cubic bezier derivative.
+      cbxd = t * (t * (3 * xa) + 2 * xb) + xc;
+
+      if (cbxd > 1e-10 && cbxd < 1e-10) {
+        // Problematic. Fall back to binary search method.
+        break;
+      }
+
+      t += dx / cbxd;
+    }
+
+    // Fallback: binary search method. This is more reliable when there are near-0 slopes.
+    let minT = 0;
+    let maxT = 1;
+    for (let it = 0; it < 20; it++) {
+      t = 0.5 * (minT + maxT);
+
+      cbx = t * (t * (t * xa + xb) + xc);
+
+      dx = time - cbx;
+      if (dx > -1e-8 && dx < 1e-8) {
+        // Solution found!
+        return t * (t * (t * ya + yb) + yc);
+      }
+
+      if (dx < 0) {
+        maxT = t;
+      } else {
+        minT = t;
+      }
+    }
+  };
+};
+
+export const getTimingFunction = (
+  str: string,
+): ((time: number) => number | undefined) => {
+  switch (str) {
+    case 'linear':
+      return function (time: number) {
+        return time;
+      };
+    case 'ease':
+      return getTimingBezier(0.25, 0.1, 0.25, 1.0);
+
+    case 'ease-in':
+      return getTimingBezier(0.42, 0, 1.0, 1.0);
+    case 'ease-out':
+      return getTimingBezier(0, 0, 0.58, 1.0);
+    case 'ease-in-out':
+      return getTimingBezier(0.42, 0, 0.58, 1.0);
+
+    case 'ease-in-sine':
+      return getTimingBezier(0.12, 0, 0.39, 0);
+    case 'ease-out-sine':
+      return getTimingBezier(0.12, 0, 0.39, 0);
+    case 'ease-in-out-sine':
+      return getTimingBezier(0.37, 0, 0.63, 1);
+
+    case 'ease-in-cubic':
+      return getTimingBezier(0.32, 0, 0.67, 0);
+    case 'ease-out-cubic':
+      return getTimingBezier(0.33, 1, 0.68, 1);
+    case 'ease-in-out-cubic':
+      return getTimingBezier(0.65, 0, 0.35, 1);
+
+    case 'ease-in-circ':
+      return getTimingBezier(0.55, 0, 1, 0.45);
+    case 'ease-out-circ':
+      return getTimingBezier(0, 0.55, 0.45, 1);
+    case 'ease-in-out-circ':
+      return getTimingBezier(0.85, 0, 0.15, 1);
+
+    case 'ease-in-back':
+      return getTimingBezier(0.36, 0, 0.66, -0.56);
+    case 'ease-out-back':
+      return getTimingBezier(0.34, 1.56, 0.64, 1);
+    case 'ease-in-out-back':
+      return getTimingBezier(0.68, -0.6, 0.32, 1.6);
+
+    case 'step-start':
+      return function () {
+        return 1;
+      };
+    case 'step-end':
+      return function (time: number) {
+        return time === 1 ? 1 : 0;
+      };
+    default:
+      // eslint-disable-next-line no-case-declarations
+      const s = 'cubic-bezier(';
+      if (str && str.indexOf(s) === 0) {
+        const parts = str
+          .substr(s.length, str.length - s.length - 1)
+          .split(',');
+        if (parts.length !== 4) {
+          console.warn('Unknown timing function: ' + str);
+          // Fallback: use linear.
+          return function (time) {
+            return time;
+          };
+        }
+        const a = parseFloat(parts[0] || '0.42');
+        const b = parseFloat(parts[1] || '0');
+        const c = parseFloat(parts[2] || '1');
+        const d = parseFloat(parts[3] || '1');
+
+        if (isNaN(a) || isNaN(b) || isNaN(c) || isNaN(d)) {
+          console.warn(' Unknown timing function: ' + str);
+          // Fallback: use linear.
+          return function (time) {
+            return time;
+          };
+        }
+
+        return getTimingBezier(a, b, c, d);
+      } else {
+        console.warn('Unknown timing function: ' + str);
+        // Fallback: use linear.
+        return function (time) {
+          return time;
+        };
+      }
+  }
+};
+
+if (!Math.hypot)
+  Math.hypot = (...args: number[]) => {
+    let y = 0,
+      i = args.length;
+    while (i--) {
+      y += args[i]! * args[i]!;
+    }
+    return Math.sqrt(y);
+  };