@solidtv/renderer 1.0.0

package/src/core/textures/ImageTexture.ts

@@ -0,0 +1,394 @@
+import type { CoreTextureManager } from '../CoreTextureManager.js';
+import { Texture, TextureType, type TextureData } from './Texture.js';
+import {
+  isCompressedTextureContainer,
+  loadCompressedTexture,
+} from '../lib/textureCompression.js';
+import {
+  convertUrlToAbsolute,
+  dataURIToBlob,
+  isBase64Image,
+} from '../lib/utils.js';
+import { isSvgImage, loadSvg } from '../lib/textureSvg.js';
+import { fetchJson } from '../lib/utils.js';
+import type { Platform } from '../platforms/Platform.js';
+import {
+  ENABLE_COMPRESSED_TEXTURES,
+  isProductionEnvironment,
+} from '../../utils.js';
+
+/**
+ * Properties of the {@link ImageTexture}
+ */
+export interface ImageTextureProps {
+  /**
+   * Source URL or ImageData for the image to be used as a texture.
+   *
+   * @remarks
+   * The ImageData type is currently only supported internally. End users should
+   * only set this property to a URL string.
+   *
+   * @default ''
+   */
+  src?: string | Blob | ImageData | (() => ImageData | null);
+  /**
+   * Whether to premultiply the alpha channel into the color channels of the
+   * image.
+   *
+   * @remarks
+   * Generally this should be set to `true` (the default). However, if the
+   * texture's associated Shader expects straight (non-premultiplied) colors,
+   * this should be set to `false`.
+   *
+   * @default true
+   */
+  premultiplyAlpha?: boolean | null;
+  /**
+   * `ImageData` textures are not cached unless a `key` is provided
+   */
+  key?: string | null;
+  /**
+   * Width of the image to be used as a texture. If not provided, the image's
+   * natural width will be used.
+   */
+  w?: number | null;
+  /**
+   * Height of the image to be used as a texture. If not provided, the image's
+   * natural height will be used.
+   */
+  h?: number | null;
+  /**
+   * Type, indicate an image type for overriding type detection
+   *
+   * @default null
+   */
+  type?: 'regular' | 'compressed' | 'svg' | null;
+  /**
+   * The width of the rectangle from which the ImageBitmap will be extracted. This value
+   * can be negative. Only works when createImageBitmap is supported on the browser.
+   *
+   * @default null
+   */
+  sw?: number | null;
+  /**
+   * The height of the rectangle from which the ImageBitmap will be extracted. This value
+   * can be negative. Only works when createImageBitmap is supported on the browser.
+   *
+   * @default null
+   */
+  sh?: number | null;
+  /**
+   * The y coordinate of the reference point of the rectangle from which the ImageBitmap
+   * will be extracted. Only used when `sw` and `sh` are provided. And only works when
+   * createImageBitmap is available.
+   *
+   * @default null
+   */
+  sx?: number | null;
+  /**
+   * The x coordinate of the reference point of the rectangle from which the
+   * ImageBitmap will be extracted. Only used when source `sw` width and `sh` height
+   * are provided. Only works when createImageBitmap is supported on the browser.
+   *
+   * @default null
+   */
+  sy?: number | null;
+  /**
+   * Maximum number of times to retry loading the image if it fails.
+   *
+   * @default 5
+   */
+  maxRetryCount?: number;
+}
+
+/**
+ * Texture consisting of an image loaded from a URL
+ *
+ * @remarks
+ * The ImageTexture's {@link ImageTextureProps.src} prop defines the image URL
+ * to be downloaded.
+ *
+ * By default, the texture's alpha values will be premultiplied into its color
+ * values which is generally the desired setting before they are sent to the
+ * texture's associated {@link Shader}. However, in special cases you may want
+ * the Shader to receive straight (non-premultiplied) values. In that case you
+ * can disable the default behavior by setting the
+ * {@link ImageTextureProps.premultiplyAlpha} prop to `false`.
+ */
+export class ImageTexture extends Texture {
+  private platform: Platform;
+
+  public props: Required<ImageTextureProps>;
+  public override type: TextureType = TextureType.image;
+
+  constructor(
+    txManager: CoreTextureManager,
+    props: Required<ImageTextureProps>,
+  ) {
+    super(txManager);
+
+    this.platform = txManager.platform;
+    this.props = props;
+    this.maxRetryCount = props.maxRetryCount as number;
+  }
+
+  hasAlphaChannel(mimeType: string) {
+    return mimeType.indexOf('image/png') !== -1;
+  }
+
+  async loadImageFallback(src: string | Blob, hasAlpha: boolean) {
+    const img = new Image();
+
+    if (typeof src === 'string' && isBase64Image(src) === false) {
+      img.crossOrigin = 'anonymous';
+    }
+
+    return new Promise<{
+      data: HTMLImageElement | null;
+      premultiplyAlpha: boolean;
+    }>((resolve, reject) => {
+      img.onload = () => {
+        resolve({ data: img, premultiplyAlpha: hasAlpha });
+      };
+
+      img.onerror = (err) => {
+        const errorMessage =
+          err instanceof Error
+            ? err.message
+            : err instanceof Event
+            ? `Image loading failed for ${img.src}`
+            : 'Unknown image loading error';
+        reject(new Error(`Image loading failed: ${errorMessage}`));
+      };
+
+      if (src instanceof Blob) {
+        img.src = URL.createObjectURL(src);
+      } else {
+        img.src = src;
+      }
+    });
+  }
+
+  async createImageBitmap(
+    blob: Blob,
+    premultiplyAlpha: boolean | null,
+    sx: number | null,
+    sy: number | null,
+    sw: number | null,
+    sh: number | null,
+  ): Promise<{
+    data: ImageBitmap | HTMLImageElement;
+    premultiplyAlpha: boolean;
+  }> {
+    const hasAlphaChannel = premultiplyAlpha ?? blob.type.includes('image/png');
+    const imageBitmapSupported = this.txManager.imageBitmapSupported;
+
+    if (imageBitmapSupported.full === true && sw !== null && sh !== null) {
+      // createImageBitmap with crop
+      const bitmap = await this.platform.createImageBitmap(
+        blob,
+        sx || 0,
+        sy || 0,
+        sw,
+        sh,
+        {
+          premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
+          colorSpaceConversion: 'none',
+          imageOrientation: 'none',
+        },
+      );
+      return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+    } else if (imageBitmapSupported.basic === true) {
+      // basic createImageBitmap without options or crop
+      // this is supported for Chrome v50 to v52/54 that doesn't support options
+      return {
+        data: await this.platform.createImageBitmap(blob),
+        premultiplyAlpha: hasAlphaChannel,
+      };
+    }
+
+    // default createImageBitmap without crop but with options
+    const bitmap = await this.platform.createImageBitmap(blob, {
+      premultiplyAlpha: hasAlphaChannel ? 'premultiply' : 'none',
+      colorSpaceConversion: 'none',
+      imageOrientation: 'none',
+    });
+    return { data: bitmap, premultiplyAlpha: hasAlphaChannel };
+  }
+
+  async loadImage(src: string) {
+    const { premultiplyAlpha, sx, sy, sw, sh } = this.props;
+
+    if (this.txManager.hasCreateImageBitmap === true) {
+      if (
+        isBase64Image(src) === false &&
+        this.txManager.hasWorker === true &&
+        this.txManager.imageWorkerManager !== null
+      ) {
+        return this.txManager.imageWorkerManager.getImage(
+          src,
+          premultiplyAlpha,
+          sx,
+          sy,
+          sw,
+          sh,
+        );
+      }
+
+      let blob;
+
+      if (isBase64Image(src) === true) {
+        blob = dataURIToBlob(src);
+      } else {
+        blob = await fetchJson(src, 'blob').then(
+          (response) => response as Blob,
+        );
+      }
+
+      return this.createImageBitmap(blob, premultiplyAlpha, sx, sy, sw, sh);
+    }
+
+    return this.loadImageFallback(src, premultiplyAlpha ?? true);
+  }
+
+  override async getTextureSource(): Promise<TextureData> {
+    let resp: TextureData;
+    try {
+      resp = await this.determineImageTypeAndLoadImage();
+    } catch (e) {
+      this.setState('failed', e as Error);
+
+      return {
+        data: null,
+      };
+    }
+
+    if (resp.data === null) {
+      this.setState('failed', Error('ImageTexture: No image data'));
+      return {
+        data: null,
+      };
+    }
+
+    return {
+      data: resp.data,
+      premultiplyAlpha: this.props.premultiplyAlpha ?? true,
+    };
+  }
+
+  determineImageTypeAndLoadImage() {
+    const { src, premultiplyAlpha, type } = this.props;
+    if (src === null) {
+      return {
+        data: null,
+      };
+    }
+
+    if (typeof src !== 'string') {
+      if (src instanceof Blob) {
+        if (this.txManager.hasCreateImageBitmap === true) {
+          const { sx, sy, sw, sh } = this.props;
+          return this.createImageBitmap(src, premultiplyAlpha, sx, sy, sw, sh);
+        } else {
+          return this.loadImageFallback(src, premultiplyAlpha ?? true);
+        }
+      }
+      if (src instanceof ImageData) {
+        return {
+          data: src,
+          premultiplyAlpha,
+        };
+      }
+      return {
+        data: src(),
+        premultiplyAlpha,
+      };
+    }
+
+    const absoluteSrc = convertUrlToAbsolute(src);
+    if (type === 'regular') {
+      return this.loadImage(absoluteSrc);
+    }
+
+    if (type === 'svg') {
+      return loadSvg(
+        absoluteSrc,
+        this.props.w,
+        this.props.h,
+        this.props.sx,
+        this.props.sy,
+        this.props.sw,
+        this.props.sh,
+      );
+    }
+
+    if (isSvgImage(src) === true) {
+      return loadSvg(
+        absoluteSrc,
+        this.props.w,
+        this.props.h,
+        this.props.sx,
+        this.props.sy,
+        this.props.sw,
+        this.props.sh,
+      );
+    }
+
+    if (
+      ENABLE_COMPRESSED_TEXTURES &&
+      (type === 'compressed' || isCompressedTextureContainer(src) === true)
+    ) {
+      return loadCompressedTexture(absoluteSrc);
+    }
+
+    // default
+    return this.loadImage(absoluteSrc);
+  }
+
+  /**
+   * Generates a cache key for the ImageTexture based on the provided props.
+   * @param props - The props used to generate the cache key.
+   * @returns The cache key as a string, or `false` if the key cannot be generated.
+   */
+  static override makeCacheKey(props: ImageTextureProps): string | false {
+    // Only cache key-able textures; prioritise key
+    const key = props.key || props.src;
+    if (typeof key !== 'string') {
+      return false;
+    }
+
+    let cacheKey = `ImageTexture,${key},${props.premultiplyAlpha ?? 'true'},${
+      props.maxRetryCount
+    }`;
+
+    if (props.sh !== null && props.sw !== null) {
+      cacheKey += ',';
+      cacheKey += props.sx ?? '';
+      cacheKey += props.sy ?? '';
+      cacheKey += props.sw || '';
+      cacheKey += props.sh || '';
+    }
+
+    return cacheKey;
+  }
+
+  static override resolveDefaults(
+    props: ImageTextureProps,
+  ): Required<ImageTextureProps> {
+    return {
+      src: props.src ?? '',
+      premultiplyAlpha: props.premultiplyAlpha ?? true, // null,
+      key: props.key ?? null,
+      type: props.type ?? null,
+      w: props.w ?? null,
+      h: props.h ?? null,
+      sx: props.sx ?? null,
+      sy: props.sy ?? null,
+      sw: props.sw ?? null,
+      sh: props.sh ?? null,
+      maxRetryCount: props.maxRetryCount ?? 5,
+    };
+  }
+
+  static z$__type__Props: ImageTextureProps;
+}

package/src/core/textures/NoiseTexture.ts

@@ -0,0 +1,87 @@
+import type { CoreTextureManager } from '../CoreTextureManager.js';
+import { Texture, TextureType, type TextureData } from './Texture.js';
+
+/**
+ * Properties of the {@link NoiseTexture}
+ */
+export interface NoiseTextureProps {
+  /**
+   * Width of texture
+   *
+   * @default 128
+   */
+  w?: number;
+  /**
+   * Height of texture
+   *
+   * @default 128
+   */
+  h?: number;
+  /**
+   * A number value that can be varied to force new textures to be generated
+   *
+   * @default 0
+   */
+  cacheId?: number;
+}
+
+/**
+ * Texture consisting of a random grid of greyscale pixels
+ *
+ * @remarks
+ * The width and height of the NoiseTexture are defined by it's
+ * {@link NoiseTextureProps.width} and {@link NoiseTextureProps.height}
+ * properties. The {@link NoiseTextureProps.cacheId} prop can be varied in order
+ * to bypass cache and get newly randomized texture data.
+ */
+export class NoiseTexture extends Texture {
+  props: Required<NoiseTextureProps>;
+
+  public override type: TextureType = TextureType.noise;
+
+  constructor(
+    txManager: CoreTextureManager,
+    props: Required<NoiseTextureProps>,
+  ) {
+    super(txManager);
+    this.props = props;
+  }
+
+  override async getTextureSource(): Promise<TextureData> {
+    const { w, h } = this.props;
+    const size = w * h * 4;
+    const pixelData8 = new Uint8ClampedArray(size);
+    for (let i = 0; i < size; i += 4) {
+      const v = Math.floor(Math.random() * 256);
+      pixelData8[i] = v;
+      pixelData8[i + 1] = v;
+      pixelData8[i + 2] = v;
+      pixelData8[i + 3] = 255;
+    }
+
+    // Noise Texture data ready - dimensions will be set during upload
+    return {
+      data: new ImageData(pixelData8, w, h),
+    };
+  }
+
+  static override makeCacheKey(props: NoiseTextureProps): string | false {
+    if (props.cacheId === undefined) {
+      return false;
+    }
+    const resolvedProps = NoiseTexture.resolveDefaults(props);
+    return `NoiseTexture,${resolvedProps.w},${resolvedProps.h},${resolvedProps.cacheId}`;
+  }
+
+  static override resolveDefaults(
+    props: NoiseTextureProps,
+  ): Required<NoiseTextureProps> {
+    return {
+      w: props.w ?? 128,
+      h: props.h ?? 128,
+      cacheId: props.cacheId ?? 0,
+    };
+  }
+
+  static z$__type__Props: NoiseTextureProps;
+}

package/src/core/textures/RenderTexture.ts

@@ -0,0 +1,68 @@
+import type { CoreTextureManager } from '../CoreTextureManager.js';
+import { Texture, TextureType, type TextureData } from './Texture.js';
+
+/**
+ * Properties of the {@link RenderTexture}
+ */
+export interface RenderTextureProps {
+  /**
+   * WebGL Texture width
+   * @default 256
+   */
+  w?: number;
+
+  /**
+   * WebGL Texture height
+   * @default 256
+   */
+  h?: number;
+}
+
+export class RenderTexture extends Texture {
+  props: Required<RenderTextureProps>;
+
+  public override type: TextureType = TextureType.renderToTexture;
+
+  constructor(
+    txManager: CoreTextureManager,
+    props: Required<RenderTextureProps>,
+  ) {
+    super(txManager);
+    this.props = props;
+  }
+
+  get w() {
+    return this.props.w;
+  }
+
+  set w(value: number) {
+    this.props.w = value;
+  }
+
+  get h() {
+    return this.props.h;
+  }
+
+  set h(value: number) {
+    this.props.h = value;
+  }
+
+  override async getTextureSource(): Promise<TextureData> {
+    // Render texture data ready - dimensions will be set during upload
+    return {
+      data: null,
+      premultiplyAlpha: null,
+    };
+  }
+
+  static override resolveDefaults(
+    props: RenderTextureProps,
+  ): Required<RenderTextureProps> {
+    return {
+      w: props.w || 256,
+      h: props.h || 256,
+    };
+  }
+
+  static z$__type__Props: RenderTextureProps;
+}

package/src/core/textures/SubTexture.ts

@@ -0,0 +1,165 @@
+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';
+
+let subTextureId = 0;
+
+/**
+ * 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
+   */
+  w?: number;
+
+  /**
+   * The height of the sub-texture in pixels
+   **/
+  h?: 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.w}, and
+ * {@link SubTextureProps.h} pixel values.
+ */
+export class SubTexture extends Texture {
+  props: Required<SubTextureProps>;
+  parentTexture: Texture;
+
+  public override type: TextureType = TextureType.subTexture;
+  public subtextureId = `subtexture-${subTextureId++}`;
+
+  constructor(txManager: CoreTextureManager, props: Required<SubTextureProps>) {
+    super(txManager);
+    this.props = 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.length > 0) {
+      this.parentTexture.setRenderableOwner(this.subtextureId, 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' && parentTx.dimensions !== null) {
+        this.onParentTxLoaded(parentTx, parentTx.dimensions);
+      } else if (parentTx.state === 'loading') {
+        this.onParentTxLoading();
+      } else if (parentTx.state === 'failed' && parentTx.error !== null) {
+        this.onParentTxFailed(parentTx, parentTx.error);
+      } else if (parentTx.state === 'freed') {
+        this.onParentTxFreed();
+      }
+
+      parentTx.on('loading', this.onParentTxLoading);
+      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.setState('loaded', {
+      w: this.props.w,
+      h: this.props.h,
+    });
+  };
+
+  private onParentTxFailed: TextureFailedEventHandler = (target, error) => {
+    this.retryCount = this.parentTexture.retryCount - 1;
+    this.setState('failed', error);
+  };
+
+  private onParentTxLoading = () => {
+    this.setState('loading');
+  };
+
+  private onParentTxFreed = () => {
+    this.setState('freed');
+  };
+
+  override onChangeIsRenderable(isRenderable: boolean): void {
+    // Propagate the renderable owner change to the parent texture
+    this.parentTexture.setRenderableOwner(this.subtextureId, isRenderable);
+  }
+
+  override async getTextureSource(): Promise<TextureData> {
+    // Check if parent texture is loaded
+    return new Promise((resolve, reject) => {
+      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,
+      w: props.w || 0,
+      h: props.h || 0,
+    };
+  }
+
+  static z$__type__Props: SubTextureProps;
+}