@solidtv/renderer 1.0.0

package/src/core/textures/Texture.ts

@@ -0,0 +1,505 @@
+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';
+import type { Bound } from '../lib/utils.js';
+import type { TextureError } from '../TextureError.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.
+ */
+export interface CompressedData {
+  /**
+   * GLenum spcifying compression format
+   */
+  glInternalFormat: number;
+
+  /**
+   * All mipmap levels
+   */
+  mipmaps: ArrayBuffer[];
+
+  /**
+   * Supported container types ('pvr' or 'ktx').
+   */
+  type: 'pvr' | 'ktx' | 'astc';
+
+  /**
+   * The width of the compressed texture in pixels. Defaults to 0.
+   *
+   * @default 0
+   */
+  w: number;
+
+  /**
+   * The height of the compressed texture in pixels.
+   **/
+  h: number;
+
+  /**
+   * block info compressed texture format
+   */
+  blockInfo: {
+    width: number;
+    height: number;
+    bytes: number;
+  };
+}
+
+/**
+ * Event handler for when a Texture fails to load
+ */
+export type TextureFailedEventHandler = (
+  target: any,
+  error: TextureError,
+) => 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;
+}
+/**
+ * TextureCoords generally numbers between 0 - 1
+ */
+export type TextureCoords = Bound;
+
+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: TextureError | null = null;
+
+  // aggregate state
+  public state: TextureState = 'initial';
+
+  readonly renderableOwners: any[] = [];
+
+  readonly renderable: boolean = false;
+
+  public type: TextureType = TextureType.generic;
+
+  public preventCleanup = false;
+
+  public ctxTexture: CoreContextTexture | undefined;
+
+  public textureData: TextureData | null = null;
+
+  public memUsed = 0;
+
+  /**
+   * Memory used by this texture in bytes
+   *
+   * @remarks
+   * This is tracked by the TextureMemoryManager and updated when the texture
+   * is loaded/freed. Set to 0 when texture is not loaded.
+   */
+  public retryCount = 0;
+  public maxRetryCount: number;
+
+  /**
+   * Timestamp when texture was created (for startup grace period)
+   */
+  private createdAt: number = Date.now();
+
+  /**
+   * Flag to track if grace period has expired to avoid repeated Date.now() calls
+   */
+  private gracePeriodExpired: boolean = false;
+
+  /**
+   * Grace period in milliseconds to prevent premature cleanup during app startup
+   * This helps prevent race conditions when bounds calculation is delayed
+   */
+  private static readonly STARTUP_GRACE_PERIOD = 2000; // 2 seconds
+
+  constructor(protected txManager: CoreTextureManager) {
+    super();
+    this.maxRetryCount = this.txManager.maxRetryCount;
+  }
+
+  get dimensions(): Dimensions | null {
+    return this._dimensions;
+  }
+
+  get error(): TextureError | null {
+    return this._error;
+  }
+
+  /**
+   * Checks if the texture is within the startup grace period.
+   * During this period, textures are protected from cleanup to prevent
+   * race conditions during app initialization.
+   */
+  isWithinStartupGracePeriod(): boolean {
+    // If grace period already expired, return false immediately
+    if (this.gracePeriodExpired === true) {
+      return false;
+    }
+
+    // Check if grace period has expired now
+    const hasExpired =
+      Date.now() - this.createdAt >= Texture.STARTUP_GRACE_PERIOD;
+
+    if (hasExpired) {
+      // Cache the result to avoid future Date.now() calls
+      this.gracePeriodExpired = true;
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Checks if the texture can be safely cleaned up.
+   * Considers the renderable state, startup grace period, and renderable owners.
+   */
+  canBeCleanedUp(): boolean {
+    // Never cleanup if explicitly prevented
+    if (this.preventCleanup) {
+      return false;
+    }
+
+    // Don't cleanup if still within startup grace period
+    if (this.isWithinStartupGracePeriod()) {
+      return false;
+    }
+
+    // Don't cleanup if not renderable
+    if (this.renderable === true) {
+      return false;
+    }
+
+    // Don't cleanup if there are still renderable owners
+    if (this.renderableOwners.length > 0) {
+      return false;
+    }
+
+    // Safe to cleanup
+    return true;
+  }
+
+  /**
+   * 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: string | number, renderable: boolean): void {
+    const oldSize = this.renderableOwners.length;
+    const hasOwnerIndex = this.renderableOwners.indexOf(owner);
+
+    if (renderable === true) {
+      if (hasOwnerIndex === -1) {
+        // Add the owner to the set
+        this.renderableOwners.push(owner);
+      }
+
+      const newSize = this.renderableOwners.length;
+      if (oldSize !== newSize && newSize === 1) {
+        (this.renderable as boolean) = true;
+        this.onChangeIsRenderable?.(true);
+        this.load();
+      }
+    } else {
+      if (hasOwnerIndex !== -1) {
+        this.renderableOwners.splice(hasOwnerIndex, 1);
+      }
+
+      const newSize = this.renderableOwners.length;
+      if (oldSize !== newSize && newSize === 0) {
+        (this.renderable as boolean) = false;
+        this.onChangeIsRenderable?.(false);
+
+        // note, not doing a cleanup here, cleanup is managed by the Stage/TextureMemoryManager
+        // when it deems appropriate based on memory pressure
+      }
+    }
+  }
+
+  load(): void {
+    if (this.retryCount > this.maxRetryCount) {
+      // We've exceeded the max retry count, do not attempt to load again
+      return;
+    }
+    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();
+  }
+
+  /**
+   * Release the texture data and core context texture for this Texture without changing state.
+   *
+   * @remarks
+   * The ctxTexture is created by the renderer and lives on the GPU.
+   */
+  release(): void {
+    this.ctxTexture?.release();
+    this.ctxTexture = undefined;
+    this.freeTextureData();
+  }
+
+  /**
+   * 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 {
+    queueMicrotask(this.freeTextureDataTask);
+  }
+
+  public setState(
+    state: TextureState,
+    errorOrDimensions?: TextureError | Dimensions,
+  ): void {
+    if (this.state === state) {
+      return;
+    }
+
+    let payload: TextureError | Dimensions | null = null;
+    if (state === 'loaded') {
+      if (
+        errorOrDimensions !== undefined &&
+        'w' in errorOrDimensions === true &&
+        'h' in errorOrDimensions === true &&
+        errorOrDimensions.w !== undefined &&
+        errorOrDimensions.h !== undefined
+      ) {
+        this._dimensions = errorOrDimensions;
+      }
+
+      payload = this._dimensions;
+    } else if (state === 'failed') {
+      this._error = errorOrDimensions as TextureError;
+      payload = this._error;
+
+      // increment the retry count for the texture
+      // this is used to compare against maxRetryCount, if set
+      // to determine if we should try loading again
+      this.retryCount += 1;
+
+      queueMicrotask(this.releaseTask);
+    } else if (state === 'loading') {
+      this._error = null;
+      this._dimensions = null;
+    } else {
+      this._error = null;
+    }
+
+    // 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;
+  }
+
+  /**
+   * Task for queueMicrotask to free texture data.
+   *
+   * @remarks
+   * This method is called in a microtask to free the texture data.
+   */
+  private freeTextureDataTask = (): void => {
+    this.textureData = null;
+  };
+
+  /**
+   * Task for queueMicrotask to release the texture.
+   *
+   * @remarks
+   * This method is called in a microtask to release the texture.
+   */
+  private releaseTask = (): void => {
+    this.release();
+  };
+
+  /**
+   * 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, any> {
+    return {};
+  }
+}

package/src/core/utils.ts

@@ -0,0 +1,210 @@
+/**
+ * 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 type TimingFunction = (t: number) => number;
+
+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,
+): TimingFunction => {
+  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) {
+    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;
+      }
+    }
+
+    return time;
+  };
+};
+
+interface TimingFunctionMap {
+  [key: string]: TimingFunction;
+}
+
+type TimingLookupArray = number[];
+interface TimingLookup {
+  [key: string]: TimingLookupArray;
+}
+
+const timingMapping: TimingFunctionMap = {};
+
+const timingLookup: TimingLookup = {
+  ease: [0.25, 0.1, 0.25, 1.0],
+  'ease-in': [0.42, 0, 1.0, 1.0],
+  'ease-out': [0, 0, 0.58, 1.0],
+  'ease-in-out': [0.42, 0, 0.58, 1.0],
+  'ease-in-sine': [0.12, 0, 0.39, 0],
+  'ease-out-sine': [0.12, 0, 0.39, 0],
+  'ease-in-out-sine': [0.37, 0, 0.63, 1],
+  'ease-in-cubic': [0.32, 0, 0.67, 0],
+  'ease-out-cubic': [0.33, 1, 0.68, 1],
+  'ease-in-out-cubic': [0.65, 0, 0.35, 1],
+  'ease-in-circ': [0.55, 0, 1, 0.45],
+  'ease-out-circ': [0, 0.55, 0.45, 1],
+  'ease-in-out-circ': [0.85, 0, 0.15, 1],
+  'ease-in-back': [0.36, 0, 0.66, -0.56],
+  'ease-out-back': [0.34, 1.56, 0.64, 1],
+  'ease-in-out-back': [0.68, -0.6, 0.32, 1.6],
+};
+
+const defaultTiming = (t: number): number => t;
+
+const parseCubicBezier = (str: string) => {
+  //cubic-bezier(0.84, 0.52, 0.56, 0.6)
+  const regex = /-?\d*\.?\d+/g;
+  const match = str.match(regex);
+
+  if (match) {
+    const [num1, num2, num3, num4] = match;
+    const a = parseFloat(num1 || '0.42');
+    const b = parseFloat(num2 || '0');
+    const c = parseFloat(num3 || '1');
+    const d = parseFloat(num4 || '1');
+
+    const timing = getTimingBezier(a, b, c, d);
+    timingMapping[str] = timing;
+
+    return timing;
+  }
+
+  // parse failed, return linear
+  console.warn('Unknown cubic-bezier timing: ' + str);
+  return defaultTiming;
+};
+
+export const getTimingFunction = (str: string): TimingFunction => {
+  if (str === 'linear') {
+    return defaultTiming;
+  }
+
+  if (timingMapping[str] !== undefined) {
+    return timingMapping[str] || defaultTiming;
+  }
+
+  if (str === 'step-start') {
+    return () => {
+      return 1;
+    };
+  }
+
+  if (str === 'step-end') {
+    return (time: number) => {
+      return time === 1 ? 1 : 0;
+    };
+  }
+
+  const lookup = timingLookup[str];
+  if (lookup !== undefined) {
+    const [a, b, c, d] = lookup;
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore - TS doesn't understand that we've checked for undefined
+
+    const timing = getTimingBezier(a, b, c, d);
+    timingMapping[str] = timing;
+    return timing;
+  }
+
+  if (str.startsWith('cubic-bezier')) {
+    return parseCubicBezier(str);
+  }
+
+  console.warn('Unknown timing function: ' + str);
+  return defaultTiming;
+};
+
+/**
+ * Convert bytes to string of megabytes with 2 decimal points
+ *
+ * @param bytes
+ * @returns
+ */
+export function bytesToMb(bytes: number) {
+  return (bytes / 1024 / 1024).toFixed(2);
+}

package/src/env.d.ts

@@ -0,0 +1,7 @@
+interface ImportMetaEnv {
+  readonly PROD: boolean;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}