@lightningtv/renderer 2.16.1

package/src/core/textures/SubTexture.ts

@@ -0,0 +1,205 @@
+/*
+ * 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 { Dimensions } from '../../common/CommonTypes.js';
+import { assertTruthy } from '../../utils.js';
+import type { CoreTextureManager } from '../CoreTextureManager.js';
+import { ImageTexture } from './ImageTexture.js';
+import {
+  Texture,
+  TextureType,
+  type TextureData,
+  type TextureFailedEventHandler,
+  type TextureLoadedEventHandler,
+  type TextureState,
+} from './Texture.js';
+
+/**
+ * Properties of the {@link SubTexture}
+ */
+export interface SubTextureProps {
+  /**
+   * The texture that this sub-texture is a sub-region of.
+   */
+  texture: Texture;
+
+  /**
+   * 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;
+
+  public override type: TextureType = TextureType.subTexture;
+
+  constructor(txManager: CoreTextureManager, props: SubTextureProps) {
+    super(txManager);
+    this.props = SubTexture.resolveDefaults(props || {});
+
+    assertTruthy(this.props.texture, 'SubTexture requires a parent texture');
+    assertTruthy(
+      this.props.texture instanceof ImageTexture,
+      'SubTexture requires an ImageTexture parent',
+    );
+
+    // Resolve parent texture from cache or fallback to provided texture
+    this.parentTexture = txManager.resolveParentTexture(this.props.texture);
+
+    if (this.renderableOwners.size > 0) {
+      this.parentTexture.setRenderableOwner(this, true);
+    }
+
+    // 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 === 'fetching') {
+        this.onParentTxFetching();
+      } else if (parentTx.state === 'fetched') {
+        this.onParentTxFetched();
+      } else if (parentTx.state === 'loading') {
+        this.onParentTxLoading();
+      } else if (parentTx.state === 'failed') {
+        this.onParentTxFailed(parentTx, parentTx.error!);
+      } else if (parentTx.state === 'freed') {
+        this.onParentTxFreed();
+      }
+
+      parentTx.on('fetched', this.onParentTxFetched);
+      parentTx.on('loading', this.onParentTxLoading);
+      parentTx.on('fetching', this.onParentTxFetching);
+      parentTx.on('loaded', this.onParentTxLoaded);
+      parentTx.on('failed', this.onParentTxFailed);
+      parentTx.on('freed', this.onParentTxFreed);
+    });
+  }
+
+  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.forwardParentTxState('loaded', {
+      width: this.props.width,
+      height: this.props.height,
+    });
+  };
+
+  private onParentTxFailed: TextureFailedEventHandler = (target, error) => {
+    this.forwardParentTxState('failed', error);
+  };
+
+  private onParentTxFetched = () => {
+    this.forwardParentTxState('fetched', {
+      width: this.props.width,
+      height: this.props.height,
+    });
+  };
+
+  private onParentTxFetching = () => {
+    this.forwardParentTxState('fetching');
+  };
+
+  private onParentTxLoading = () => {
+    this.forwardParentTxState('loading');
+  };
+
+  private onParentTxFreed = () => {
+    this.forwardParentTxState('freed');
+  };
+
+  private forwardParentTxState(
+    state: TextureState,
+    errorOrDimensions?: Error | Dimensions,
+  ) {
+    this.setState(state, errorOrDimensions);
+  }
+
+  override onChangeIsRenderable(isRenderable: boolean): void {
+    // Propagate the renderable owner change to the parent texture
+    this.parentTexture.setRenderableOwner(this, isRenderable);
+  }
+
+  override async getTextureSource(): Promise<TextureData> {
+    // Check if parent texture is loaded
+    return new Promise((resolve, reject) => {
+      this.setState('fetched');
+      resolve({
+        data: 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,376 @@
+/*
+ * 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 } from '../../common/CommonTypes.js';
+import { EventEmitter } from '../../common/EventEmitter.js';
+import type { CoreContextTexture } from '../renderers/CoreContextTexture.js';
+
+/**
+ * Event handler for when a Texture is freed
+ */
+export type TextureFreedEventHandler = (target: any) => void;
+
+/**
+ * Event handler for when a Texture is loading
+ */
+export type TextureLoadingEventHandler = (target: any) => void;
+
+/**
+ * Event handler for when a Texture is loaded
+ */
+export type TextureLoadedEventHandler = (
+  target: any,
+  dimensions: Readonly<Dimensions>,
+) => void;
+
+/**
+ * Represents compressed texture data.
+ */
+interface CompressedData {
+  /**
+   * GLenum spcifying compression format
+   */
+  glInternalFormat: number;
+
+  /**
+   * All mipmap levels
+   */
+  mipmaps?: ArrayBuffer[];
+
+  /**
+   * Supported container types ('pvr' or 'ktx').
+   */
+  type: 'pvr' | 'ktx';
+
+  /**
+   * The width of the compressed texture in pixels. Defaults to 0.
+   *
+   * @default 0
+   */
+  width: number;
+
+  /**
+   * The height of the compressed texture in pixels.
+   **/
+  height: number;
+}
+
+/**
+ * Event handler for when a Texture fails to load
+ */
+export type TextureFailedEventHandler = (target: any, error: Error) => void;
+
+/**
+ * TextureData that is used to populate a CoreContextTexture
+ */
+export interface TextureData {
+  /**
+   * The texture data
+   */
+  data:
+    | ImageBitmap
+    | ImageData
+    | SubTextureProps
+    | CompressedData
+    | HTMLImageElement
+    | Uint8Array
+    | null;
+  /**
+   * Premultiply alpha when uploading texture data to the GPU
+   *
+   * @defaultValue `false`
+   */
+  premultiplyAlpha?: boolean | null;
+}
+
+export type TextureState =
+  | 'initial' // Before anything is loaded
+  | 'fetching' // Fetching or generating texture source
+  | 'fetched' // Texture source is ready
+  | 'loading' // Uploading to GPU
+  | 'loaded' // Fully loaded and usable
+  | 'failed' // Failed to load
+  | 'freed'; // Released and must be reloaded
+
+export enum TextureType {
+  'generic' = 0,
+  'color' = 1,
+  'image' = 2,
+  'noise' = 3,
+  'renderToTexture' = 4,
+  'subTexture' = 5,
+}
+
+/**
+ * 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`.
+   */
+  private _dimensions: Dimensions | null = null;
+  private _error: Error | null = null;
+
+  /**
+   * Texture states that are considered transitional and should be skipped during cleanup
+   */
+  public static readonly TRANSITIONAL_TEXTURE_STATES: readonly TextureState[] =
+    ['fetching', 'fetched', 'loading'];
+
+  // aggregate state
+  public state: TextureState = 'initial';
+
+  readonly renderableOwners = new Set<unknown>();
+
+  readonly renderable: boolean = false;
+
+  public type: TextureType = TextureType.generic;
+
+  public preventCleanup = false;
+
+  public ctxTexture: CoreContextTexture | undefined;
+
+  public textureData: TextureData | null = null;
+
+  constructor(protected txManager: CoreTextureManager) {
+    super();
+  }
+
+  get dimensions(): Dimensions | null {
+    return this._dimensions;
+  }
+
+  get error(): Error | null {
+    return this._error;
+  }
+
+  /**
+   * Add/remove an owner to/from the Texture based on its renderability.
+   *
+   * @remarks
+   * Any object can own a texture, be it a CoreNode or even the state object
+   * from a Text Renderer.
+   *
+   * When the reference to the texture that an owner object holds is replaced
+   * or cleared it must call this with `renderable=false` to release the owner
+   * association.
+   *
+   * @param owner
+   * @param renderable
+   */
+  setRenderableOwner(owner: unknown, renderable: boolean): void {
+    const oldSize = this.renderableOwners.size;
+
+    if (renderable === true) {
+      if (this.renderableOwners.has(owner) === false) {
+        // Add the owner to the set
+        this.renderableOwners.add(owner);
+      }
+
+      const newSize = this.renderableOwners.size;
+      if (newSize > oldSize && newSize === 1) {
+        (this.renderable as boolean) = true;
+        this.onChangeIsRenderable?.(true);
+        this.load();
+      }
+    } else {
+      this.renderableOwners.delete(owner);
+      const newSize = this.renderableOwners.size;
+      if (newSize < oldSize && newSize === 0) {
+        (this.renderable as boolean) = false;
+        this.onChangeIsRenderable?.(false);
+        this.txManager.orphanTexture(this);
+      }
+    }
+  }
+
+  load(): void {
+    this.txManager.loadTexture(this);
+  }
+
+  /**
+   * Event called when the Texture becomes renderable or unrenderable.
+   *
+   * @remarks
+   * Used by subclasses like SubTexture propogate then renderability of the
+   * Texture to other referenced Textures.
+   *
+   * @param isRenderable `true` if this Texture has renderable owners.
+   */
+  onChangeIsRenderable?(isRenderable: boolean): void;
+
+  /**
+   * Load the core context texture for this Texture.
+   * The ctxTexture is created by the renderer and lives on the GPU.
+   *
+   * @returns
+   */
+  loadCtxTexture(): CoreContextTexture {
+    if (this.ctxTexture === undefined) {
+      this.ctxTexture = this.txManager.renderer.createCtxTexture(this);
+    }
+
+    return this.ctxTexture;
+  }
+
+  /**
+   * Free the core context texture for this Texture.
+   *
+   * @remarks
+   * The ctxTexture is created by the renderer and lives on the GPU.
+   */
+  free(): void {
+    this.ctxTexture?.free();
+  }
+
+  /**
+   * Destroy the texture.
+   *
+   * @remarks
+   * This method is called when the texture is no longer needed and should be
+   * cleaned up.
+   */
+  destroy(): void {
+    // Only free GPU resources if we're in a state where they exist
+    if (this.state === 'loaded') {
+      this.free();
+    }
+
+    // Always free texture data regardless of state
+    this.freeTextureData();
+  }
+
+  /**
+   * Free the source texture data for this Texture.
+   *
+   * @remarks
+   * The texture data is the source data that is used to populate the CoreContextTexture.
+   * e.g. ImageData that is downloaded from a URL.
+   */
+  freeTextureData(): void {
+    this.textureData = null;
+  }
+
+  public setState(
+    state: TextureState,
+    errorOrDimensions?: Error | Dimensions,
+  ): void {
+    if (this.state === state) {
+      return;
+    }
+
+    let payload: Error | Dimensions | null = null;
+    if (state === 'loaded') {
+      if (
+        errorOrDimensions !== undefined &&
+        'width' in errorOrDimensions === true &&
+        'height' in errorOrDimensions === true &&
+        errorOrDimensions.width !== undefined &&
+        errorOrDimensions.height !== undefined
+      ) {
+        this._dimensions = errorOrDimensions;
+      }
+
+      payload = this._dimensions;
+    } else if (state === 'failed') {
+      this._error = errorOrDimensions as Error;
+      payload = this._error;
+    }
+
+    // emit the new state
+    this.state = state;
+    this.emit(state, payload);
+  }
+
+  /**
+   * 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.
+   */
+  async getTextureData(): Promise<TextureData> {
+    if (this.textureData === null) {
+      this.textureData = await this.getTextureSource();
+    }
+
+    return this.textureData;
+  }
+
+  /**
+   * Get the texture source for this texture.
+   *
+   * @remarks
+   * This method is called by the CoreContextTexture when the texture is loaded.
+   * The texture source is then used to populate the CoreContextTexture.
+   */
+  abstract getTextureSource(): 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 {};
+  }
+}