@luma.gl/engine 9.3.0-alpha.4 → 9.3.0-alpha.8

package/src/dynamic-texture/dynamic-texture.ts

@@ -1,9 +1,16 @@
 // luma.gl, MIT license
 // Copyright (c) vis.gl contributors
 
-import type {TextureProps, SamplerProps, TextureView, Device} from '@luma.gl/core';
+import type {
+  TextureProps,
+  SamplerProps,
+  TextureView,
+  Device,
+  TextureFormat,
+  TextureReadOptions
+} from '@luma.gl/core';
 
-import {Texture, Sampler, log} from '@luma.gl/core';
+import {Buffer, Texture, Sampler, log} from '@luma.gl/core';
 
 // import {loadImageBitmap} from '../application-utils/load-file';
 import {uid} from '../utils/uid';
@@ -26,10 +33,10 @@ import {
   type TextureArrayData,
   type TextureCubeArrayData,
   type TextureCubeData,
-  type TextureImageData,
 
   // Helpers
   getTextureSizeFromData,
+  resolveTextureImageFormat,
   getTexture1DSubresources,
   getTexture2DSubresources,
   getTexture3DSubresources,
@@ -37,7 +44,6 @@ import {
   getTextureArraySubresources,
   getTextureCubeArraySubresources
 } from './texture-data';
-import {generateMipmap} from './mipmaps';
 
 /**
  * Properties for a dynamic texture
@@ -131,7 +137,7 @@ export class DynamicTexture {
   }
 
   /** @note Fire and forget; caller can await `ready` */
-  async initAsync(originalPropsWithAsyncData: TextureDataAsyncProps): Promise<void> {
+  async initAsync(originalPropsWithAsyncData: DynamicTextureProps): Promise<void> {
     try {
       // TODO - Accept URL string for 2D: turn into ExternalImage promise
       // const dataProps =
@@ -141,6 +147,18 @@ export class DynamicTexture {
 
       const propsWithSyncData = await this._loadAllData(originalPropsWithAsyncData);
       this._checkNotDestroyed();
+      const subresources = propsWithSyncData.data
+        ? getTextureSubresources({
+            ...propsWithSyncData,
+            width: originalPropsWithAsyncData.width,
+            height: originalPropsWithAsyncData.height,
+            format: originalPropsWithAsyncData.format
+          })
+        : [];
+      const userProvidedFormat =
+        'format' in originalPropsWithAsyncData && originalPropsWithAsyncData.format !== undefined;
+      const userProvidedUsage =
+        'usage' in originalPropsWithAsyncData && originalPropsWithAsyncData.usage !== undefined;
 
       // Deduce size when not explicitly provided
       // TODO - what about depth?
@@ -162,15 +180,32 @@ export class DynamicTexture {
         throw new Error(`${this} size could not be determined or was zero`);
       }
 
+      // Normalize caller-provided subresources into one validated mip chain description.
+      const textureData = analyzeTextureSubresources(this.device, subresources, size, {
+        format: userProvidedFormat ? originalPropsWithAsyncData.format : undefined
+      });
+      const resolvedFormat = textureData.format ?? this.props.format;
+
       // Create a minimal TextureProps and validate via `satisfies`
       const baseTextureProps = {
         ...this.props,
         ...size,
+        format: resolvedFormat,
         mipLevels: 1, // temporary; updated below
         data: undefined
       } satisfies TextureProps;
 
-      if (this.device.type === 'webgpu' && this.props.mipmaps) {
+      if (this.device.isTextureFormatCompressed(resolvedFormat) && !userProvidedUsage) {
+        baseTextureProps.usage = Texture.SAMPLE | Texture.COPY_DST;
+      }
+
+      // Explicit mip arrays take ownership of the mip chain; otherwise we may auto-generate it.
+      const shouldGenerateMipmaps =
+        this.props.mipmaps &&
+        !textureData.hasExplicitMipChain &&
+        !this.device.isTextureFormatCompressed(resolvedFormat);
+
+      if (this.device.type === 'webgpu' && shouldGenerateMipmaps) {
         const requiredUsage =
           this.props.dimension === '3d'
             ? Texture.SAMPLE | Texture.STORAGE | Texture.COPY_DST | Texture.COPY_SRC
@@ -180,8 +215,9 @@ export class DynamicTexture {
 
       // Compute mip levels (auto clamps to max)
       const maxMips = this.device.getMipLevelCount(baseTextureProps.width, baseTextureProps.height);
-      const desired =
-        this.props.mipLevels === 'auto'
+      const desired = textureData.hasExplicitMipChain
+        ? textureData.mipLevels
+        : this.props.mipLevels === 'auto'
           ? maxMips
           : Math.max(1, Math.min(maxMips, this.props.mipLevels ?? 1));
 
@@ -192,33 +228,15 @@ export class DynamicTexture {
       this._view = this.texture.view;
 
       // Upload data if provided
-      if (propsWithSyncData.data) {
-        switch (propsWithSyncData.dimension) {
-          case '1d':
-            this.setTexture1DData(propsWithSyncData.data);
-            break;
-          case '2d':
-            this.setTexture2DData(propsWithSyncData.data);
-            break;
-          case '3d':
-            this.setTexture3DData(propsWithSyncData.data);
-            break;
-          case '2d-array':
-            this.setTextureArrayData(propsWithSyncData.data);
-            break;
-          case 'cube':
-            this.setTextureCubeData(propsWithSyncData.data);
-            break;
-          case 'cube-array':
-            this.setTextureCubeArrayData(propsWithSyncData.data);
-            break;
-          default: {
-            throw new Error(`Unhandled dimension ${propsWithSyncData.dimension}`);
-          }
-        }
+      if (textureData.subresources.length) {
+        this._setTextureSubresources(textureData.subresources);
+      }
+
+      if (this.props.mipmaps && !textureData.hasExplicitMipChain && !shouldGenerateMipmaps) {
+        log.warn(`${this} skipping auto-generated mipmaps for compressed texture format`)();
       }
 
-      if (this.props.mipmaps) {
+      if (shouldGenerateMipmaps) {
         this.generateMipmaps();
       }
 
@@ -229,7 +247,6 @@ export class DynamicTexture {
     } catch (e) {
       const err = e instanceof Error ? e : new Error(String(e));
       this.rejectReady(err);
-      throw err;
     }
   }
 
@@ -247,7 +264,7 @@ export class DynamicTexture {
     if (this.device.type === 'webgl') {
       this.texture.generateMipmapsWebGL();
     } else if (this.device.type === 'webgpu') {
-      generateMipmap(this.device, this.texture);
+      this.device.generateMipmapsWebGPU(this.texture);
     } else {
       log.warn(`${this} mipmaps not supported on ${this.device.type}`);
     }
@@ -261,6 +278,59 @@ export class DynamicTexture {
     this._sampler = s;
   }
 
+  /**
+   * Copies texture contents into a GPU buffer and waits until the copy is complete.
+   * The caller owns the returned buffer and must destroy it when finished.
+   */
+  async readBuffer(options: TextureReadOptions = {}): Promise<Buffer> {
+    if (!this.isReady) {
+      await this.ready;
+    }
+
+    const width = options.width ?? this.texture.width;
+    const height = options.height ?? this.texture.height;
+    const depthOrArrayLayers = options.depthOrArrayLayers ?? this.texture.depth;
+    const layout = this.texture.computeMemoryLayout({width, height, depthOrArrayLayers});
+
+    const buffer = this.device.createBuffer({
+      byteLength: layout.byteLength,
+      usage: Buffer.COPY_DST | Buffer.MAP_READ
+    });
+
+    this.texture.readBuffer(
+      {
+        ...options,
+        width,
+        height,
+        depthOrArrayLayers
+      },
+      buffer
+    );
+
+    const fence = this.device.createFence();
+    await fence.signaled;
+    fence.destroy();
+
+    return buffer;
+  }
+
+  /** Reads texture contents back to CPU memory. */
+  async readAsync(options: TextureReadOptions = {}): Promise<ArrayBuffer> {
+    if (!this.isReady) {
+      await this.ready;
+    }
+
+    const width = options.width ?? this.texture.width;
+    const height = options.height ?? this.texture.height;
+    const depthOrArrayLayers = options.depthOrArrayLayers ?? this.texture.depth;
+    const layout = this.texture.computeMemoryLayout({width, height, depthOrArrayLayers});
+
+    const buffer = await this.readBuffer(options);
+    const data = await buffer.readAsync(0, layout.byteLength);
+    buffer.destroy();
+    return data.buffer;
+  }
+
   /**
    * Resize by cloning the underlying immutable texture.
    * Does not copy contents; caller may need to re-upload and/or regenerate mips.
@@ -342,7 +412,7 @@ export class DynamicTexture {
   }
 
   /** Cube array: multiple cubes (faces×layers), each face may carry multiple mips */
-  private setTextureCubeArrayData(data: TextureCubeArrayData): void {
+  setTextureCubeArrayData(data: TextureCubeArrayData): void {
     if (this.texture.props.dimension !== 'cube-array') {
       throw new Error(`${this} is not cube-array`);
     }
@@ -367,10 +437,13 @@ export class DynamicTexture {
           this.texture.copyExternalImage({image, z, mipLevel, flipY});
           break;
         case 'texture-data':
-          const {data} = subresource;
-          // TODO - we are throwing away some of the info in data.
-          // Did we not need it in the first place? Can we use it to validate?
-          this.texture.writeData(getAlignedUploadData(this.texture, data), {
+          const {data, textureFormat} = subresource;
+          if (textureFormat && textureFormat !== this.texture.format) {
+            throw new Error(
+              `${this} mip level ${mipLevel} uses format "${textureFormat}" but texture format is "${this.texture.format}"`
+            );
+          }
+          this.texture.writeData(data.data, {
             x: 0,
             y: 0,
             z,
@@ -415,36 +488,196 @@ export class DynamicTexture {
   };
 }
 
-function getAlignedUploadData(
-  texture: DynamicTexture['texture'],
-  data: TextureImageData
-): ArrayBuffer | Uint8Array {
-  const {width, height, data: uploadData} = data;
-  const {bytesPerPixel} = texture.device.getTextureFormatInfo(texture.format);
-  const bytesPerRow = width * bytesPerPixel;
-  const alignedBytesPerRow = Math.ceil(bytesPerRow / texture.byteAlignment) * texture.byteAlignment;
-
-  if (alignedBytesPerRow === bytesPerRow) {
-    return uploadData;
-  }
-
-  const sourceBytes = new Uint8Array(
-    uploadData.buffer,
-    uploadData.byteOffset,
-    uploadData.byteLength
-  );
-  const paddedBytes = new Uint8Array(alignedBytesPerRow * height);
-
-  for (let row = 0; row < height; row++) {
-    const sourceOffset = row * bytesPerRow;
-    const destinationOffset = row * alignedBytesPerRow;
-    paddedBytes.set(
-      sourceBytes.subarray(sourceOffset, sourceOffset + bytesPerRow),
-      destinationOffset
+type TextureSubresourceAnalysis = {
+  readonly subresources: TextureSubresource[];
+  readonly mipLevels: number;
+  readonly format?: TextureFormat;
+  readonly hasExplicitMipChain: boolean;
+};
+
+// Flatten dimension-specific texture data into one list of uploadable subresources.
+function getTextureSubresources(
+  props: TextureDataProps & Partial<Pick<TextureProps, 'width' | 'height' | 'format'>>
+): TextureSubresource[] {
+  if (!props.data) {
+    return [];
+  }
+
+  const baseLevelSize =
+    props.width && props.height ? {width: props.width, height: props.height} : undefined;
+  const textureFormat = 'format' in props ? props.format : undefined;
+
+  switch (props.dimension) {
+    case '1d':
+      return getTexture1DSubresources(props.data);
+    case '2d':
+      return getTexture2DSubresources(0, props.data, baseLevelSize, textureFormat);
+    case '3d':
+      return getTexture3DSubresources(props.data);
+    case '2d-array':
+      return getTextureArraySubresources(props.data);
+    case 'cube':
+      return getTextureCubeSubresources(props.data);
+    case 'cube-array':
+      return getTextureCubeArraySubresources(props.data);
+    default:
+      throw new Error(`Unhandled dimension ${(props as TextureDataProps).dimension}`);
+  }
+}
+
+// Resolve a consistent texture format and the longest mip chain valid across all slices.
+function analyzeTextureSubresources(
+  device: Device,
+  subresources: TextureSubresource[],
+  size: {width: number; height: number},
+  options: {format?: TextureFormat}
+): TextureSubresourceAnalysis {
+  if (subresources.length === 0) {
+    return {
+      subresources,
+      mipLevels: 1,
+      format: options.format,
+      hasExplicitMipChain: false
+    };
+  }
+
+  const groupedSubresources = new Map<number, TextureSubresource[]>();
+  for (const subresource of subresources) {
+    const group = groupedSubresources.get(subresource.z) ?? [];
+    group.push(subresource);
+    groupedSubresources.set(subresource.z, group);
+  }
+
+  const hasExplicitMipChain = subresources.some(subresource => subresource.mipLevel > 0);
+  let resolvedFormat = options.format;
+  let resolvedMipLevels = Number.POSITIVE_INFINITY;
+  const validSubresources: TextureSubresource[] = [];
+
+  for (const [z, sliceSubresources] of groupedSubresources) {
+    // Validate each slice independently, then keep only the mip levels that are valid everywhere.
+    const sortedSubresources = [...sliceSubresources].sort(
+      (left, right) => left.mipLevel - right.mipLevel
     );
+    const baseLevel = sortedSubresources[0];
+    if (!baseLevel || baseLevel.mipLevel !== 0) {
+      throw new Error(`DynamicTexture: slice ${z} is missing mip level 0`);
+    }
+
+    const baseSize = getTextureSubresourceSize(device, baseLevel);
+    if (baseSize.width !== size.width || baseSize.height !== size.height) {
+      throw new Error(
+        `DynamicTexture: slice ${z} base level dimensions ${baseSize.width}x${baseSize.height} do not match expected ${size.width}x${size.height}`
+      );
+    }
+
+    const baseFormat = getTextureSubresourceFormat(baseLevel);
+    if (baseFormat) {
+      if (resolvedFormat && resolvedFormat !== baseFormat) {
+        throw new Error(
+          `DynamicTexture: slice ${z} base level format "${baseFormat}" does not match texture format "${resolvedFormat}"`
+        );
+      }
+      resolvedFormat = baseFormat;
+    }
+
+    const mipLevelLimit =
+      resolvedFormat && device.isTextureFormatCompressed(resolvedFormat)
+        ? // Block-compressed formats cannot have mips smaller than a single compression block.
+          getMaxCompressedMipLevels(device, baseSize.width, baseSize.height, resolvedFormat)
+        : device.getMipLevelCount(baseSize.width, baseSize.height);
+
+    let validMipLevelsForSlice = 0;
+    for (
+      let expectedMipLevel = 0;
+      expectedMipLevel < sortedSubresources.length;
+      expectedMipLevel++
+    ) {
+      const subresource = sortedSubresources[expectedMipLevel];
+      // Stop at the first gap so callers can provide extra trailing data without breaking creation.
+      if (!subresource || subresource.mipLevel !== expectedMipLevel) {
+        break;
+      }
+      if (expectedMipLevel >= mipLevelLimit) {
+        break;
+      }
+
+      const subresourceSize = getTextureSubresourceSize(device, subresource);
+      const expectedWidth = Math.max(1, baseSize.width >> expectedMipLevel);
+      const expectedHeight = Math.max(1, baseSize.height >> expectedMipLevel);
+      if (subresourceSize.width !== expectedWidth || subresourceSize.height !== expectedHeight) {
+        break;
+      }
+
+      const subresourceFormat = getTextureSubresourceFormat(subresource);
+      if (subresourceFormat) {
+        if (!resolvedFormat) {
+          resolvedFormat = subresourceFormat;
+        }
+        // Later mip levels must stay on the same format as the validated base level.
+        if (subresourceFormat !== resolvedFormat) {
+          break;
+        }
+      }
+
+      validMipLevelsForSlice++;
+      validSubresources.push(subresource);
+    }
+
+    resolvedMipLevels = Math.min(resolvedMipLevels, validMipLevelsForSlice);
   }
 
-  return paddedBytes;
+  const mipLevels = Number.isFinite(resolvedMipLevels) ? Math.max(1, resolvedMipLevels) : 1;
+
+  return {
+    // Keep every slice trimmed to the same mip count so the texture shape stays internally consistent.
+    subresources: validSubresources.filter(subresource => subresource.mipLevel < mipLevels),
+    mipLevels,
+    format: resolvedFormat,
+    hasExplicitMipChain
+  };
+}
+
+// Read the per-level format using the transitional textureFormat -> format fallback rules.
+function getTextureSubresourceFormat(subresource: TextureSubresource): TextureFormat | undefined {
+  if (subresource.type !== 'texture-data') {
+    return undefined;
+  }
+  return subresource.textureFormat ?? resolveTextureImageFormat(subresource.data);
+}
+
+// Resolve dimensions from either raw bytes or external-image subresources.
+function getTextureSubresourceSize(
+  device: Device,
+  subresource: TextureSubresource
+): {width: number; height: number} {
+  switch (subresource.type) {
+    case 'external-image':
+      return device.getExternalImageSize(subresource.image);
+    case 'texture-data':
+      return {width: subresource.data.width, height: subresource.data.height};
+    default:
+      throw new Error('Unsupported texture subresource');
+  }
+}
+
+// Count the mip levels that stay at or above one compression block in each dimension.
+function getMaxCompressedMipLevels(
+  device: Device,
+  baseWidth: number,
+  baseHeight: number,
+  format: TextureFormat
+): number {
+  const {blockWidth = 1, blockHeight = 1} = device.getTextureFormatInfo(format);
+  let mipLevels = 1;
+  for (let mipLevel = 1; ; mipLevel++) {
+    const width = Math.max(1, baseWidth >> mipLevel);
+    const height = Math.max(1, baseHeight >> mipLevel);
+    if (width < blockWidth || height < blockHeight) {
+      break;
+    }
+    mipLevels++;
+  }
+  return mipLevels;
 }
 
 // HELPERS
@@ -457,7 +690,7 @@ async function awaitAllPromises(x: any): Promise<any> {
   }
   if (x && typeof x === 'object' && x.constructor === Object) {
     const object: Record<string, any> = x;
-    const values = await Promise.all(Object.values(object));
+    const values = await Promise.all(Object.values(object).map(awaitAllPromises));
     const keys = Object.keys(object);
     const resolvedObject: Record<string, any> = {};
     for (let i = 0; i < keys.length; i++) {

package/src/dynamic-texture/texture-data.ts

@@ -9,6 +9,8 @@ export type TextureImageSource = ExternalImage;
  * additional optional fields can describe compressed texture data.
  */
 export type TextureImageData = {
+  /** Preferred WebGPU style format string. */
+  textureFormat?: TextureFormat;
   /** WebGPU style format string. Defaults to 'rgba8unorm' */
   format?: TextureFormat;
   /** Typed Array with the bytes of the image. @note beware row byte alignment requirements */
@@ -104,6 +106,7 @@ export type TextureSubresource = {
   | {
       type: 'texture-data';
       data: TextureImageData;
+      textureFormat?: TextureFormat;
     }
 );
 
@@ -173,8 +176,8 @@ function getTextureMipLevelSize(data: TextureMipLevelData): {width: number; heig
   throw new Error('Unsupported mip-level data');
 }
 
-/** Type guard: is a mip-level `TextureImageData` (vs ExternalImage) */
-function isTextureImageData(data: TextureMipLevelData): data is TextureImageData {
+/** Type guard: is a mip-level `TextureImageData` (vs ExternalImage or bare typed array) */
+function isTextureImageData(data: unknown): data is TextureImageData {
   return (
     typeof data === 'object' &&
     data !== null &&
@@ -184,6 +187,20 @@ function isTextureImageData(data: TextureMipLevelData): data is TextureImageData
   );
 }
 
+function isTypedArrayMipLevelData(data: unknown): data is TypedArray {
+  return ArrayBuffer.isView(data);
+}
+
+export function resolveTextureImageFormat(data: TextureImageData): TextureFormat | undefined {
+  const {textureFormat, format} = data;
+  if (textureFormat && format && textureFormat !== format) {
+    throw new Error(
+      `Conflicting texture formats "${textureFormat}" and "${format}" provided for the same mip level`
+    );
+  }
+  return textureFormat ?? format;
+}
+
 /** Resolve size for a single mip-level datum */
 // function getTextureMipLevelSizeFromData(data: TextureMipLevelData): {
 //   width: number;
@@ -222,14 +239,18 @@ export function getTexture1DSubresources(data: Texture1DData): TextureSubresourc
 }
 
 /** Normalize 2D layer payload into an array of mip-level items */
-function _normalizeTexture2DData(data: Texture2DData): (TextureImageData | ExternalImage)[] {
+function _normalizeTexture2DData(
+  data: Texture2DData
+): (TextureImageData | ExternalImage | TypedArray)[] {
   return Array.isArray(data) ? data : [data];
 }
 
 /** Experimental: Set multiple mip levels (2D), optionally at `z` (depth/array index) */
 export function getTexture2DSubresources(
   slice: number,
-  lodData: Texture2DData
+  lodData: Texture2DData,
+  baseLevelSize?: {width: number; height: number},
+  textureFormat?: TextureFormat
 ): TextureSubresource[] {
   const lodArray = _normalizeTexture2DData(lodData);
   const z = slice;
@@ -249,6 +270,20 @@ export function getTexture2DSubresources(
       subresources.push({
         type: 'texture-data',
         data: imageData,
+        textureFormat: resolveTextureImageFormat(imageData),
+        z,
+        mipLevel
+      });
+    } else if (isTypedArrayMipLevelData(imageData) && baseLevelSize) {
+      subresources.push({
+        type: 'texture-data',
+        data: {
+          data: imageData,
+          width: Math.max(1, baseLevelSize.width >> mipLevel),
+          height: Math.max(1, baseLevelSize.height >> mipLevel),
+          ...(textureFormat ? {format: textureFormat} : {})
+        },
+        textureFormat,
         z,
         mipLevel
       });

package/src/geometries/cone-geometry.ts

@@ -2,13 +2,18 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import type {TruncatedConeGeometryProps} from './truncated-cone-geometry';
 import {TruncatedConeGeometry} from './truncated-cone-geometry';
 import {uid} from '../utils/uid';
 
-export type ConeGeometryProps = {
+export type ConeGeometryProps = Omit<
+  TruncatedConeGeometryProps,
+  'topRadius' | 'bottomRadius' | 'topCap' | 'bottomCap'
+> & {
   id?: string;
   radius?: number;
   cap?: boolean;
+  attributes?: any;
 };
 
 export class ConeGeometry extends TruncatedConeGeometry {

package/src/geometries/cylinder-geometry.ts

@@ -2,10 +2,14 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import type {TruncatedConeGeometryProps} from './truncated-cone-geometry';
 import {TruncatedConeGeometry} from './truncated-cone-geometry';
 import {uid} from '../utils/uid';
 
-export type CylinderGeometryProps = {
+export type CylinderGeometryProps = Omit<
+  TruncatedConeGeometryProps,
+  'topRadius' | 'bottomRadius'
+> & {
   id?: string;
   radius?: number;
   attributes?: any;

package/src/geometry/gpu-geometry.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {PrimitiveTopology, BufferLayout} from '@luma.gl/core';
-import {Device, Buffer, getVertexFormatFromAttribute} from '@luma.gl/core';
+import {Device, Buffer, vertexFormatDecoder} from '@luma.gl/core';
 import type {Geometry} from '../geometry/geometry';
 import {uid} from '../utils/uid';
 
@@ -127,8 +127,13 @@ export function getAttributeBuffersFromGeometry(
         id: `${attributeName}-buffer`
       });
       const {value, size, normalized} = attribute;
-      // @ts-expect-error
-      bufferLayout.push({name, format: getVertexFormatFromAttribute(value, size, normalized)});
+      if (size === undefined) {
+        throw new Error(`Attribute ${attributeName} is missing a size`);
+      }
+      bufferLayout.push({
+        name,
+        format: vertexFormatDecoder.getVertexFormatFromAttribute(value, size, normalized)
+      });
     }
   }