@luma.gl/engine 9.1.9 → 9.2.0-alpha.2

package/src/async-texture/async-texture.ts

@@ -2,24 +2,20 @@
 // Copyright (c) vis.gl contributors
 
 import type {
-  Texture,
   TextureProps,
-  Sampler,
+  SamplerProps,
   TextureView,
   Device,
-  Texture1DData,
-  Texture2DData,
-  Texture3DData,
-  TextureArrayData,
-  TextureCubeData,
-  TextureCubeArrayData
+  TypedArray,
+  TextureFormat,
+  ExternalImage
 } from '@luma.gl/core';
 
+import {Texture, Sampler, log} from '@luma.gl/core';
+
 import {loadImageBitmap} from '../application-utils/load-file';
 import {uid} from '../utils/uid';
 
-export type AsyncTextureProps = Omit<TextureProps, 'data'> & AsyncTextureDataProps;
-
 type AsyncTextureDataProps =
   | AsyncTexture1DProps
   | AsyncTexture2DProps
@@ -44,9 +40,73 @@ type AsyncTextureCubeArrayProps = {
   data: Promise<TextureCubeArrayData> | TextureCubeArrayData | null;
 };
 
-type TextureData = TextureProps['data'];
 type AsyncTextureData = AsyncTextureProps['data'];
 
+/** Names of cube texture faces */
+export type TextureCubeFace = '+X' | '-X' | '+Y' | '-Y' | '+Z' | '-Z';
+export const TextureCubeFaces: TextureCubeFace[] = ['+X', '-X', '+Y', '-Y', '+Z', '-Z'];
+// prettier-ignore
+export const TextureCubeFaceMap = {'+X': 0, '-X': 1, '+Y': 2, '-Y': 3, '+Z': 4, '-Z': 5};
+
+/**
+ * One mip level
+ * Basic data structure is similar to `ImageData`
+ * additional optional fields can describe compressed texture data.
+ */
+export type TextureImageData = {
+  /** WebGPU style format string. Defaults to 'rgba8unorm' */
+  format?: TextureFormat;
+  data: TypedArray;
+  width: number;
+  height: number;
+
+  compressed?: boolean;
+  byteLength?: number;
+  hasAlpha?: boolean;
+};
+
+export type TextureLevelSource = TextureImageData | ExternalImage;
+
+/** Texture data can be one or more mip levels */
+export type TextureData = TextureImageData | ExternalImage | (TextureImageData | ExternalImage)[];
+
+/** @todo - define what data type is supported for 1D textures */
+export type Texture1DData = TypedArray | TextureImageData;
+
+/** Texture data can be one or more mip levels */
+export type Texture2DData =
+  | TypedArray
+  | TextureImageData
+  | ExternalImage
+  | (TextureImageData | ExternalImage)[];
+
+/** 6 face textures */
+export type TextureCubeData = Record<TextureCubeFace, TextureData>;
+
+/** Array of textures */
+export type Texture3DData = TextureData[];
+
+/** Array of textures */
+export type TextureArrayData = TextureData[];
+
+/** Array of 6 face textures */
+export type TextureCubeArrayData = Record<TextureCubeFace, TextureData>[];
+
+export const CubeFaces: TextureCubeFace[] = ['+X', '-X', '+Y', '-Y', '+Z', '-Z'];
+
+/** Properties for an async texture */
+export type AsyncTextureProps = Omit<TextureProps, 'data' | 'mipLevels' | 'width' | 'height'> &
+  AsyncTextureDataProps & {
+    /** Generate mipmaps after creating textures and setting data */
+    mipmaps?: boolean;
+    /** nipLevels can be set to 'auto' to generate max number of mipLevels */
+    mipLevels?: number | 'auto';
+    /** Width - can be auto-calculated when initializing from ExternalImage */
+    width?: number;
+    /** Height - can be auto-calculated when initializing from ExternalImage */
+    height?: number;
+  };
+
 /**
  * It is very convenient to be able to initialize textures with promises
  * This can add considerable complexity to the Texture class, and doesn't
@@ -56,6 +116,7 @@ type AsyncTextureData = AsyncTextureProps['data'];
 export class AsyncTexture {
   readonly device: Device;
   readonly id: string;
+  props: Required<Omit<AsyncTextureProps, 'data'>>;
 
   // TODO - should we type these as possibly `null`? It will make usage harder?
   // @ts-expect-error
@@ -82,12 +143,21 @@ export class AsyncTexture {
 
   constructor(device: Device, props: AsyncTextureProps) {
     this.device = device;
-    this.id = props.id || uid('async-texture');
-    // this.id = typeof props?.data === 'string' ? props.data.slice(-20) : uid('async-texture');
 
+    // TODO - if we support URL strings as data...
+    const id = uid('async-texture'); // typeof props?.data === 'string' ? props.data.slice(-20) : uid('async-texture');
+    this.props = {...AsyncTexture.defaultProps, id, ...props};
+    this.id = this.props.id;
+
+    props = {...props};
     // Signature: new AsyncTexture(device, {data: url})
     if (typeof props?.data === 'string' && props.dimension === '2d') {
-      props = {...props, data: loadImageBitmap(props.data)};
+      props.data = loadImageBitmap(props.data);
+    }
+
+    // If mipmaps are requested, we need to allocate space for them
+    if (props.mipmaps) {
+      props.mipLevels = 'auto';
     }
 
     this.ready = new Promise<void>((resolve, reject) => {
@@ -102,13 +172,11 @@ export class AsyncTexture {
   }
 
   async initAsync(props: AsyncTextureProps): Promise<void> {
+    let resolveReady;
+    let rejectReady;
+
     const asyncData: AsyncTextureData = props.data;
-    let data: TextureData;
-    try {
-      data = await awaitAllPromises(asyncData);
-    } catch (error) {
-      this.rejectReady(error as Error);
-    }
+    const data: TextureData = await awaitAllPromises(asyncData).then(resolveReady, rejectReady);
 
     // Check that we haven't been destroyed while waiting for texture data to load
     if (this.destroyed) {
@@ -116,14 +184,57 @@ export class AsyncTexture {
     }
 
     // Now we can actually create the texture
-    // @ts-expect-error Discriminated union
-    const syncProps: TextureProps = {...props, data};
+
+    // Auto-deduce width and height if not supplied
+    const size =
+      this.props.width && this.props.height
+        ? {width: this.props.width, height: this.props.height}
+        : this.getTextureDataSize(data);
+    if (!size) {
+      throw new Error('Texture size could not be determined');
+    }
+    const syncProps: TextureProps = {...size, ...props, data: undefined, mipLevels: 1};
+
+    // Auto-calculate the number of mip levels as a convenience
+    // TODO - Should we clamp to 1-getMipLevelCount?
+    const maxMips = this.device.getMipLevelCount(syncProps.width, syncProps.height);
+    syncProps.mipLevels =
+      this.props.mipLevels === 'auto' ? maxMips : Math.min(maxMips, this.props.mipLevels);
 
     this.texture = this.device.createTexture(syncProps);
     this.sampler = this.texture.sampler;
     this.view = this.texture.view;
     this.isReady = true;
-    this.resolveReady();
+
+    if (props.data) {
+      switch (this.props.dimension) {
+        case '1d':
+          this._setTexture1DData(this.texture, data as Texture1DData);
+          break;
+        case '2d':
+          this._setTexture2DData(data);
+          break;
+        case '3d':
+          this._setTexture3DData(this.texture, data as Texture3DData);
+          break;
+        case '2d-array':
+          this._setTextureArrayData(this.texture, data as TextureArrayData);
+          break;
+        case 'cube':
+          this._setTextureCubeData(this.texture, data as unknown as TextureCubeData);
+          break;
+        case 'cube-array':
+          this._setTextureCubeArrayData(this.texture, data as unknown as TextureCubeArrayData);
+          break;
+      }
+    }
+
+    // Do we need to generate mipmaps?
+    if (this.props.mipmaps) {
+      this.generateMipmaps();
+    }
+
+    log.info(1, `${this} loaded`);
   }
 
   destroy(): void {
@@ -135,10 +246,24 @@ export class AsyncTexture {
     this.destroyed = true;
   }
 
+  generateMipmaps(): void {
+    // if (this.device.type === 'webgl') {
+    this.texture.generateMipmapsWebGL();
+    // }
+  }
+
+  /** Set sampler or create and set new Sampler from SamplerProps */
+  setSampler(sampler: Sampler | SamplerProps = {}): void {
+    this.texture.setSampler(
+      sampler instanceof Sampler ? sampler : this.device.createSampler(sampler)
+    );
+  }
+
   /**
    * Textures are immutable and cannot be resized after creation,
    * but we can create a similar texture with the same parameters but a new size.
    * @note Does not copy contents of the texture
+   * @note Mipmaps may need to be regenerated after resizing / setting new data
    * @todo Abort pending promise and create a texture with the new size?
    */
   resize(size: {width: number; height: number}): boolean {
@@ -155,9 +280,247 @@ export class AsyncTexture {
       this.texture = texture.clone(size);
       texture.destroy();
     }
+
     return true;
   }
+
+  /** Check if texture data is a typed array */
+  isTextureLevelData(data: TextureData): data is TextureImageData {
+    const typedArray = (data as TextureImageData)?.data;
+    return ArrayBuffer.isView(typedArray);
+  }
+
+  /** Get the size of the texture described by the provided TextureData */
+  getTextureDataSize(
+    data: TextureData | TextureCubeData | TextureArrayData | TextureCubeArrayData | TypedArray
+  ): {width: number; height: number} | null {
+    if (!data) {
+      return null;
+    }
+    if (ArrayBuffer.isView(data)) {
+      return null;
+    }
+    // Recurse into arrays (array of miplevels)
+    if (Array.isArray(data)) {
+      return this.getTextureDataSize(data[0]);
+    }
+    if (this.device.isExternalImage(data)) {
+      return this.device.getExternalImageSize(data);
+    }
+    if (data && typeof data === 'object' && data.constructor === Object) {
+      const textureDataArray = Object.values(data);
+      const untypedData = textureDataArray[0];
+      return {width: untypedData.width, height: untypedData.height};
+    }
+    throw new Error('texture size deduction failed');
+  }
+
+  /** Convert luma.gl cubemap face constants to depth index */
+  getCubeFaceDepth(face: TextureCubeFace): number {
+    // prettier-ignore
+    switch (face) {
+        case '+X': return  0;
+        case '-X': return  1;
+        case '+Y': return  2;
+        case '-Y': return  3;
+        case '+Z': return  4;
+        case '-Z': return  5;
+        default: throw new Error(face);
+      }
+  }
+
+  // EXPERIMENTAL
+
+  setTextureData(data: TextureData) {}
+
+  /** Experimental: Set multiple mip levels */
+  _setTexture1DData(texture: Texture, data: Texture1DData): void {
+    throw new Error('setTexture1DData not supported in WebGL.');
+  }
+
+  /** Experimental: Set multiple mip levels */
+  _setTexture2DData(lodData: Texture2DData, depth = 0): void {
+    if (!this.texture) {
+      throw new Error('Texture not initialized');
+    }
+
+    const lodArray = this._normalizeTextureData(lodData);
+
+    // If the user provides multiple LODs, then automatic mipmap
+    // generation generateMipmap() should be disabled to avoid overwriting them.
+    if (lodArray.length > 1 && this.props.mipmaps !== false) {
+      log.warn(`Texture ${this.id} mipmap and multiple LODs.`)();
+    }
+
+    for (let mipLevel = 0; mipLevel < lodArray.length; mipLevel++) {
+      const imageData = lodArray[mipLevel];
+      if (this.device.isExternalImage(imageData)) {
+        this.texture.copyExternalImage({image: imageData, depth, mipLevel, flipY: true});
+      } else {
+        this.texture.copyImageData({data: imageData.data /* , depth */, mipLevel});
+      }
+    }
+  }
+
+  /**
+   * Experimental: Sets 3D texture data: multiple depth slices, multiple mip levels
+   * @param data
+   */
+  _setTexture3DData(texture: Texture, data: Texture3DData): void {
+    if (this.texture?.props.dimension !== '3d') {
+      throw new Error(this.id);
+    }
+    for (let depth = 0; depth < data.length; depth++) {
+      this._setTexture2DData(data[depth], depth);
+    }
+  }
+
+  /**
+   * Experimental: Set Cube texture data, multiple faces, multiple mip levels
+   * @todo - could support TextureCubeArray with depth
+   * @param data
+   * @param index
+   */
+  _setTextureCubeData(texture: Texture, data: TextureCubeData): void {
+    if (this.texture?.props.dimension !== 'cube') {
+      throw new Error(this.id);
+    }
+    for (const [face, faceData] of Object.entries(data)) {
+      const faceDepth = CubeFaces.indexOf(face as TextureCubeFace);
+      this._setTexture2DData(faceData, faceDepth);
+    }
+  }
+
+  /**
+   * Experimental: Sets texture array data, multiple levels, multiple depth slices
+   * @param data
+   */
+  _setTextureArrayData(texture: Texture, data: TextureArrayData): void {
+    if (this.texture?.props.dimension !== '2d-array') {
+      throw new Error(this.id);
+    }
+    for (let depth = 0; depth < data.length; depth++) {
+      this._setTexture2DData(data[depth], depth);
+    }
+  }
+
+  /**
+   * Experimental: Sets texture cube array, multiple faces, multiple levels, multiple mip levels
+   * @param data
+   */
+  _setTextureCubeArrayData(texture: Texture, data: TextureCubeArrayData): void {
+    throw new Error('setTextureCubeArrayData not supported in WebGL2.');
+  }
+
+  /** Experimental */
+  _setTextureCubeFaceData(
+    texture: Texture,
+    lodData: Texture2DData,
+    face: TextureCubeFace,
+    depth: number = 0
+  ): void {
+    // assert(this.props.dimension === 'cube');
+
+    // If the user provides multiple LODs, then automatic mipmap
+    // generation generateMipmap() should be disabled to avoid overwriting them.
+    if (Array.isArray(lodData) && lodData.length > 1 && this.props.mipmaps !== false) {
+      log.warn(`${this.id} has mipmap and multiple LODs.`)();
+    }
+
+    const faceDepth = TextureCubeFaces.indexOf(face);
+    this._setTexture2DData(lodData, faceDepth);
+  }
+
+  /**
+   * Normalize TextureData to an array of TextureImageData / ExternalImages
+   * @param data
+   * @param options
+   * @returns array of TextureImageData / ExternalImages
+   */
+  _normalizeTextureData(data: Texture2DData): (TextureImageData | ExternalImage)[] {
+    const options: {width: number; height: number; depth: number} = this.texture;
+    let mipLevelArray: (TextureImageData | ExternalImage)[];
+    if (ArrayBuffer.isView(data)) {
+      mipLevelArray = [
+        {
+          // ts-expect-error does data really need to be Uint8ClampedArray?
+          data,
+          width: options.width,
+          height: options.height
+          // depth: options.depth
+        }
+      ];
+    } else if (!Array.isArray(data)) {
+      mipLevelArray = [data];
+    } else {
+      mipLevelArray = data;
+    }
+    return mipLevelArray;
+  }
+
+  static defaultProps: Required<AsyncTextureProps> = {
+    ...Texture.defaultProps,
+    data: null,
+    mipmaps: false
+  };
+}
+
+// TODO - Remove when texture refactor is complete
+
+/*
+setCubeMapData(options: {
+  width: number;
+  height: number;
+  data: Record<GL, Texture2DData> | Record<TextureCubeFace, Texture2DData>;
+  format?: any;
+  type?: any;
+  /** @deprecated Use .data *
+  pixels: any;
+}): void {
+  const {gl} = this;
+
+  const {width, height, pixels, data, format = GL.RGBA, type = GL.UNSIGNED_BYTE} = options;
+
+  // pixel data (imageDataMap) is an Object from Face to Image or Promise.
+  // For example:
+  // {
+  // GL.TEXTURE_CUBE_MAP_POSITIVE_X : Image-or-Promise,
+  // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : Image-or-Promise,
+  // ... }
+  // To provide multiple level-of-details (LODs) this can be Face to Array
+  // of Image or Promise, like this
+  // {
+  // GL.TEXTURE_CUBE_MAP_POSITIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
+  // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
+  // ... }
+
+  const imageDataMap = this._getImageDataMap(pixels || data);
+
+  const resolvedFaces = WEBGLTexture.FACES.map(face => {
+    const facePixels = imageDataMap[face];
+    return Array.isArray(facePixels) ? facePixels : [facePixels];
+  });
+  this.bind();
+
+  WEBGLTexture.FACES.forEach((face, index) => {
+    if (resolvedFaces[index].length > 1 && this.props.mipmaps !== false) {
+      // If the user provides multiple LODs, then automatic mipmap
+      // generation generateMipmaps() should be disabled to avoid overwritting them.
+      log.warn(`${this.id} has mipmap and multiple LODs.`)();
+    }
+    resolvedFaces[index].forEach((image, lodLevel) => {
+      // TODO: adjust width & height for LOD!
+      if (width && height) {
+        gl.texImage2D(face, lodLevel, format, width, height, 0 /* border*, format, type, image);
+      } else {
+        gl.texImage2D(face, lodLevel, format, format, type, image);
+      }
+    });
+  });
+
+  this.unbind();
 }
+*/
 
 // HELPERS