@luma.gl/core 9.2.6 → 9.3.0-alpha.11

package/src/shadertypes/{textures → texture-types}/texture-format-generics.ts

@@ -8,54 +8,8 @@ import {
   type TextureFormatCompressed
 } from './texture-formats';
 
-import {type DataTypeArray, NormalizedDataTypeArray} from '../data-types/data-types';
-
-export type TextureFormatTypedArray<T extends TextureFormat> = DataTypeArray<
-  TextureFormatDataType<T>
->;
-
-export type TextureFormatNormalizedTypedArray<T extends TextureFormat> = NormalizedDataTypeArray<
-  TextureFormatDataType<T>
->;
-
-/** A numeric array of length matching the number of components in the texture format */
-export type TextureFormatPixel<T extends TextureFormat> =
-  TextureFormatPackedComponents<T> extends 1
-    ? [number]
-    : TextureFormatPackedComponents<T> extends 2
-      ? [number, number]
-      : TextureFormatPackedComponents<T> extends 3
-        ? [number, number, number]
-        : TextureFormatPackedComponents<T> extends 4
-          ? [number, number, number, number]
-          : never;
-
-/** @note packed formats have only one component. Use TextureFormatPackedComponents */
-export type TextureFormatComponents<T extends TextureFormat> = T extends
-  | TextureFormatR
-  | TextureFormatPackedRGB
-  | TextureFormatPackedRGBA
-  ? 1
-  : T extends TextureFormatRG
-    ? 2
-    : T extends TextureFormatRGB
-      ? 3
-      : T extends TextureFormatRGBA
-        ? 4
-        : never;
-
-export type TextureFormatPackedComponents<T extends TextureFormat> = T extends TextureFormatR
-  ? 1
-  : T extends TextureFormatRG
-    ? 2
-    : T extends TextureFormatRGB | TextureFormatPackedRGB
-      ? 3
-      : T extends TextureFormatRGBA | TextureFormatPackedRGBA
-        ? 4
-        : never;
-
-/** Get the data type for a texture format */
-export type TextureFormatDataType<T extends TextureFormat> = T extends TextureFormatUint8
+/** @type data type for a texture format */
+export type TextureFormatDataTypeT<T extends TextureFormat> = T extends TextureFormatUint8
   ? 'uint8'
   : T extends TextureFormatSint8
     ? 'sint8'
@@ -89,6 +43,46 @@ export type TextureFormatDataType<T extends TextureFormat> = T extends TextureFo
                                 ? 'uint32'
                                 : never;
 
+/** @type A numeric array of length matching the number of components in the texture format */
+export type TextureFormatPixelT<T extends TextureFormat> =
+  TextureFormatPackedComponentsT<T> extends 1
+    ? [number]
+    : TextureFormatPackedComponentsT<T> extends 2
+      ? [number, number]
+      : TextureFormatPackedComponentsT<T> extends 3
+        ? [number, number, number]
+        : TextureFormatPackedComponentsT<T> extends 4
+          ? [number, number, number, number]
+          : never;
+
+/**
+ * @type number - the number of components in a texture format
+ * @note packed formats have only one component. Use TextureFormatPackedComponentsT
+ */
+export type TextureFormatComponentsT<T extends TextureFormat> = T extends
+  | TextureFormatR
+  | TextureFormatPackedRGB
+  | TextureFormatPackedRGBA
+  ? 1
+  : T extends TextureFormatRG
+    ? 2
+    : T extends TextureFormatRGB
+      ? 3
+      : T extends TextureFormatRGBA
+        ? 4
+        : never;
+
+/** @type number - the number of components in a packed texture format */
+export type TextureFormatPackedComponentsT<T extends TextureFormat> = T extends TextureFormatR
+  ? 1
+  : T extends TextureFormatRG
+    ? 2
+    : T extends TextureFormatRGB | TextureFormatPackedRGB
+      ? 3
+      : T extends TextureFormatRGBA | TextureFormatPackedRGBA
+        ? 4
+        : never;
+
 // Component groups
 
 type TextureFormatR =

package/src/shadertypes/{textures → texture-types}/texture-format-table.ts

@@ -24,6 +24,7 @@ const float32_renderable: TextureFeature = 'float32-renderable-webgl';
 const float16_renderable: TextureFeature = 'float16-renderable-webgl';
 const rgb9e5ufloat_renderable: TextureFeature = 'rgb9e5ufloat-renderable-webgl';
 const snorm8_renderable: TextureFeature = 'snorm8-renderable-webgl';
+const norm16_webgl: TextureFeature = 'norm16-webgl';
 const norm16_renderable: TextureFeature = 'norm16-renderable-webgl';
 const snorm16_renderable: TextureFeature = 'snorm16-renderable-webgl';
 
@@ -67,7 +68,7 @@ export function getTextureFormatTable(): Readonly<Record<TextureFormat, TextureF
   return TEXTURE_FORMAT_TABLE;
 }
 
-// prettier-ignore
+// biome-ignore format: preserve layout
 const TEXTURE_FORMAT_COLOR_DEPTH_TABLE: Readonly<Record<TextureFormatColorUncompressed | TextureFormatDepthStencil, TextureFormatDefinition>> = {
   // 8-bit formats
   'r8unorm': {},
@@ -93,15 +94,15 @@ const TEXTURE_FORMAT_COLOR_DEPTH_TABLE: Readonly<Record<TextureFormatColorUncomp
   'bgra8unorm-srgb': {},
 
 
-  'r16unorm': {f: norm16_renderable},
-  'rg16unorm': {render: norm16_renderable},
-  'rgb16unorm-webgl': {f: norm16_renderable}, // rgb not renderable
-  'rgba16unorm': {render: norm16_renderable},
+  'r16unorm': {f: norm16_webgl, render: norm16_renderable},
+  'rg16unorm': {f: norm16_webgl, render: norm16_renderable},
+  'rgb16unorm-webgl': {f: norm16_webgl, render: false}, // rgb not renderable
+  'rgba16unorm': {f: norm16_webgl, render: norm16_renderable},
 
-  'r16snorm': {f: snorm16_renderable},
-  'rg16snorm': {render: snorm16_renderable},
-  'rgb16snorm-webgl': {f: norm16_renderable}, // rgb not renderable
-  'rgba16snorm': {render: snorm16_renderable},
+  'r16snorm': {f: norm16_webgl, render: snorm16_renderable},
+  'rg16snorm': {f: norm16_webgl, render: snorm16_renderable},
+  'rgb16snorm-webgl': {f: norm16_webgl, render: false}, // rgb not renderable
+  'rgba16snorm': {f: norm16_webgl, render: snorm16_renderable},
 
   'r16uint': {},
   'rg16uint': {},
@@ -152,7 +153,7 @@ const TEXTURE_FORMAT_COLOR_DEPTH_TABLE: Readonly<Record<TextureFormatColorUncomp
   'depth32float-stencil8': {attachment: 'depth-stencil', bitsPerChannel: [32, 8, 0, 0], packed: true},
 };
 
-// prettier-ignore
+// biome-ignore format: preserve layout
 const TEXTURE_FORMAT_COMPRESSED_TABLE: Readonly<Record<TextureFormatCompressed, TextureFormatDefinition>> = {
 
   // BC compressed formats: check device.features.has("texture-compression-bc");
@@ -225,7 +226,7 @@ const TEXTURE_FORMAT_COMPRESSED_TABLE: Readonly<Record<TextureFormatCompressed,
 
   'pvrtc-rgb4unorm-webgl': {f: texture_compression_pvrtc_webgl},
   'pvrtc-rgba4unorm-webgl': {f: texture_compression_pvrtc_webgl},
-  'pvrtc-rbg2unorm-webgl': {f: texture_compression_pvrtc_webgl},
+  'pvrtc-rgb2unorm-webgl': {f: texture_compression_pvrtc_webgl},
   'pvrtc-rgba2unorm-webgl': {f: texture_compression_pvrtc_webgl},
 
   // WEBGL_compressed_texture_etc1

package/src/shadertypes/{textures → texture-types}/texture-formats.ts

@@ -2,7 +2,11 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {NormalizedDataType} from '../data-types/data-types';
+import type {
+  NormalizedDataType,
+  TypedArrayConstructorT,
+  NormalizedTypedArrayConstructorT
+} from '../data-types/data-types';
 
 /** Information about the structure of a texture format */
 export type TextureFormatInfo = {
@@ -18,6 +22,8 @@ export type TextureFormatInfo = {
   dataType?: NormalizedDataType;
   /** Number of bytes per pixel */
   bytesPerPixel: number;
+  /** Compressed formats only: Number of bytes per block */
+  bytesPerBlock?: number;
   /** Number of bits per channel (may be unreliable for packed formats) */
   bitsPerChannel: [number, number, number, number];
   /** If this is a packed data type */
@@ -58,6 +64,33 @@ export type TextureFormatCapabilities = {
   store: TextureFeature | boolean;
 };
 
+/**
+ * Memory layout for reading/writing data to a texture's memory.
+ *
+ * @note Due to alignment, GPU texture data is typically not contiguous.
+ *
+ * @note  GPU texure data must be accessed according to this layout.
+ * - On CPU, only the range of rows that are actually read or written need to be allocated.
+ * - However, space for the full, padded/aligned rows must be allocated in the buffer,
+ *   even if just a partial horizontal range `{x, width}` is actually read or written.
+ *
+ * @note byteLength = bytesPerRow * rowsPerImage * depthOrArrayLayers.
+ */
+export type TextureMemoryLayout = {
+  /** Total length in bytes */
+  byteLength: number;
+  /** Number of images */
+  depthOrArrayLayers: number;
+  /** Stride between successive images (Use when depthOrArrayLayers > 1) */
+  bytesPerImage: number;
+  /** Number of rows per image */
+  rowsPerImage: number;
+  /** Number of bytes per row (padded) */
+  bytesPerRow: number;
+  /** Number of bytes per pixel */
+  bytesPerPixel: number;
+};
+
 /**
  * These represent the main compressed texture formats
  * Each format typically has a number of more specific subformats
@@ -89,6 +122,7 @@ export type TextureFeature =
   | 'float16-renderable-webgl'
   | 'rgb9e5ufloat-renderable-webgl'
   | 'snorm8-renderable-webgl'
+  | 'norm16-webgl'
   | 'norm16-renderable-webgl'
   | 'snorm16-renderable-webgl'
   | 'float32-filterable'
@@ -133,7 +167,7 @@ export type TextureFormatColorUncompressed =
   | TextureFormatPacked16
   | TextureFormatPacked32;
 
-type TextureFormatUnorm8 =
+export type TextureFormatUnorm8 =
   | 'r8unorm'
   | 'rg8unorm'
   | 'rgb8unorm-webgl'
@@ -142,39 +176,42 @@ type TextureFormatUnorm8 =
   | 'bgra8unorm'
   | 'bgra8unorm-srgb';
 
-type TextureFormatSnorm8 = 'r8snorm' | 'rg8snorm' | 'rgb8snorm-webgl' | 'rgba8snorm';
+export type TextureFormatSnorm8 = 'r8snorm' | 'rg8snorm' | 'rgb8snorm-webgl' | 'rgba8snorm';
 
-type TextureFormatUint8 = 'r8uint' | 'rg8uint' | 'rgba8uint';
+export type TextureFormatUint8 = 'r8uint' | 'rg8uint' | 'rgba8uint';
 
-type TextureFormatSint8 = 'r8sint' | 'rg8sint' | 'rgba8sint';
+export type TextureFormatSint8 = 'r8sint' | 'rg8sint' | 'rgba8sint';
 
-type TextureFormatUnorm16 = 'r16unorm' | 'rg16unorm' | 'rgb16unorm-webgl' | 'rgba16unorm';
+export type TextureFormatUnorm16 = 'r16unorm' | 'rg16unorm' | 'rgb16unorm-webgl' | 'rgba16unorm';
 
-type TextureFormatSnorm16 = 'r16snorm' | 'rg16snorm' | 'rgb16snorm-webgl' | 'rgba16snorm';
+export type TextureFormatSnorm16 = 'r16snorm' | 'rg16snorm' | 'rgb16snorm-webgl' | 'rgba16snorm';
 
-type TextureFormatUint16 = 'r16uint' | 'rg16uint' | 'rgba16uint';
+export type TextureFormatUint16 = 'r16uint' | 'rg16uint' | 'rgba16uint';
 
-type TextureFormatSint16 = 'r16sint' | 'rg16sint' | 'rgba16sint';
+export type TextureFormatSint16 = 'r16sint' | 'rg16sint' | 'rgba16sint';
 
-type TextureFormatFloat16 = 'r16float' | 'rg16float' | 'rgba16float';
+export type TextureFormatFloat16 = 'r16float' | 'rg16float' | 'rgba16float';
 
 // 96-bit formats (deprecated!)
-type TextureFormatUint32 = 'r32uint' | 'rg32uint' | 'rgba32uint';
+export type TextureFormatUint32 = 'r32uint' | 'rg32uint' | 'rgba32uint';
 
-type TextureFormatSint32 = 'r32sint' | 'rg32sint' | 'rgba32sint';
+export type TextureFormatSint32 = 'r32sint' | 'rg32sint' | 'rgba32sint';
 
-type TextureFormatFloat32 = 'r32float' | 'rg32float' | 'rgb32float-webgl' | 'rgba32float';
+export type TextureFormatFloat32 = 'r32float' | 'rg32float' | 'rgb32float-webgl' | 'rgba32float';
 
-type TextureFormatPacked16 = 'rgba4unorm-webgl' | 'rgb565unorm-webgl' | 'rgb5a1unorm-webgl';
-
-type TextureFormatPacked32 = 'rgb9e5ufloat' | 'rg11b10ufloat' | 'rgb10a2unorm' | 'rgb10a2uint';
+export type TextureFormatPacked16 = 'rgba4unorm-webgl' | 'rgb565unorm-webgl' | 'rgb5a1unorm-webgl';
 
+export type TextureFormatPacked32 =
+  | 'rgb9e5ufloat'
+  | 'rg11b10ufloat'
+  | 'rgb10a2unorm'
+  | 'rgb10a2uint';
 export type TextureFormatCompressed =
   | 'bc1-rgb-unorm-webgl'
   | 'bc1-rgb-unorm-srgb-webgl'
   | 'pvrtc-rgb4unorm-webgl'
   | 'pvrtc-rgba4unorm-webgl'
-  | 'pvrtc-rbg2unorm-webgl'
+  | 'pvrtc-rgb2unorm-webgl'
   | 'pvrtc-rgba2unorm-webgl'
   | 'etc1-rbg-unorm-webgl'
   | 'atc-rgb-unorm-webgl'
@@ -243,8 +280,18 @@ export type TextureFormatCompressed =
   | 'astc-12x12-unorm'
   | 'astc-12x12-unorm-srgb';
 
+export type CompressedTextureFormat = TextureFormatCompressed;
+
 // Texture format helper types
 
+export type TextureFormatTypedArray<T extends TextureFormat> = DataTypeArray<
+  TextureFormatDataType<T>
+>;
+
+export type TextureFormatNormalizedTypedArray<T extends TextureFormat> = NormalizedDataTypeArray<
+  TextureFormatDataType<T>
+>;
+
 export type TextureFormatDataType<T extends TextureFormat> = T extends TextureFormatUint8
   ? 'uint8'
   : T extends TextureFormatSint8
@@ -279,6 +326,15 @@ export type TextureFormatDataType<T extends TextureFormat> = T extends TextureFo
                                 ? 'uint32'
                                 : never;
 
+export type TextureFormatDataTypeT<T extends TextureFormat> = TextureFormatDataType<T>;
+
+type DataTypeArray<T extends NormalizedDataType> = InstanceType<TypedArrayConstructorT<T>>;
+type NormalizedDataTypeArray<T extends NormalizedDataType> = InstanceType<
+  NormalizedTypedArrayConstructorT<T>
+>;
+
+// HELPER TYPES
+
 /*
 export type TextureFormatColorWebGPU =
   // 8-bit formats

package/src/shadertypes/texture-types/texture-layout.ts

@@ -0,0 +1,60 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {TypedArray} from '@math.gl/types';
+import {type TextureFormat, type TextureMemoryLayout} from './texture-formats';
+import {textureFormatDecoder} from './texture-format-decoder';
+
+export function getTextureImageView<T extends TextureFormat>(
+  arrayBuffer: ArrayBuffer,
+  memoryLayout: TextureMemoryLayout,
+  format: T,
+  image = 0
+) {
+  const formatInfo = textureFormatDecoder.getInfo(format);
+  const bytesPerComponent = formatInfo.bytesPerPixel / formatInfo.components;
+  const {bytesPerImage} = memoryLayout;
+  const offset = bytesPerImage * image;
+  const totalPixels = memoryLayout.bytesPerImage / bytesPerComponent;
+
+  switch (format) {
+    case 'rgba8unorm':
+    case 'bgra8unorm':
+    case 'rgba8uint':
+      return new Uint8Array(arrayBuffer, offset, totalPixels);
+    case 'r8unorm':
+      return new Uint8Array(arrayBuffer, offset, totalPixels);
+    case 'r16uint':
+    case 'rgba16uint':
+      return new Uint16Array(arrayBuffer, offset, totalPixels);
+    case 'r32uint':
+    case 'rgba32uint':
+      return new Uint32Array(arrayBuffer, offset, totalPixels);
+    case 'r32float':
+      return new Float32Array(arrayBuffer, offset, totalPixels);
+    case 'rgba16float':
+      return new Uint16Array(arrayBuffer, offset, totalPixels); // 4 channels
+    case 'rgba32float':
+      return new Float32Array(arrayBuffer, offset, totalPixels);
+    default:
+      throw new Error(`Unsupported format: ${format}`);
+  }
+}
+
+export function setTextureImageData<T extends TextureFormat>(
+  arrayBuffer: ArrayBuffer,
+  memoryLayout: TextureMemoryLayout,
+  format: T,
+  data: TypedArray,
+  image = 0
+): void {
+  const offset = 0; // memoryLayout.bytesPerImage * image;
+
+  const totalPixels = memoryLayout.bytesPerImage / memoryLayout.bytesPerPixel;
+  const subArray = data.subarray(0, totalPixels);
+
+  const typedArray = getTextureImageView(arrayBuffer, memoryLayout, format, image);
+
+  typedArray.set(subArray, offset);
+}

package/src/shadertypes/vertex-types/vertex-format-decoder.ts

@@ -0,0 +1,175 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TypedArray} from '../../types';
+import type {NormalizedDataType, PrimitiveDataType, SignedDataType} from '../data-types/data-types';
+import type {VertexFormat, VertexFormatInfo} from './vertex-formats';
+import {dataTypeDecoder} from '../data-types/data-type-decoder';
+
+export class VertexFormatDecoder {
+  /**
+   * Decodes a vertex format, returning type, components, byte  length and flags (integer, signed, normalized)
+   */
+  getVertexFormatInfo<T extends VertexFormat = VertexFormat>(format: T): VertexFormatInfo<T> {
+    // Strip the -webgl ending if present
+    let webglOnly: boolean | undefined;
+    if (format.endsWith('-webgl')) {
+      format.replace('-webgl', '');
+      webglOnly = true;
+    }
+    // split components from type
+    const [type_, count] = format.split('x');
+    const type = type_ as NormalizedDataType;
+    const components = (count ? parseInt(count) : 1) as 1 | 2 | 3 | 4;
+    // decode the type
+    const decodedType = dataTypeDecoder.getDataTypeInfo(type);
+    const result: VertexFormatInfo = {
+      type,
+      components,
+      byteLength: decodedType.byteLength * components,
+      integer: decodedType.integer,
+      signed: decodedType.signed,
+      normalized: decodedType.normalized
+    };
+    if (webglOnly) {
+      result.webglOnly = true;
+    }
+    return result;
+  }
+
+  /** Build a vertex format from a signed data type and a component */
+  makeVertexFormat(
+    signedDataType: SignedDataType,
+    components: 1 | 2 | 3 | 4,
+    normalized?: boolean
+  ): VertexFormat {
+    const dataType: NormalizedDataType = normalized
+      ? dataTypeDecoder.getNormalizedDataType(signedDataType)
+      : signedDataType;
+
+    switch (dataType) {
+      // Special cases for WebGL-only x3 formats that WebGPU does not support.
+      case 'unorm8':
+        if (components === 1) {
+          return 'unorm8';
+        }
+        if (components === 3) {
+          return 'unorm8x3-webgl';
+        }
+        return `${dataType}x${components}`;
+
+      case 'snorm8':
+        if (components === 1) {
+          return 'snorm8';
+        }
+        if (components === 3) {
+          return 'snorm8x3-webgl';
+        }
+        return `${dataType}x${components}`;
+
+      case 'uint8':
+      case 'sint8':
+        // WebGPU 8 bit formats must be aligned to 16 bit boundaries.
+        if (components === 1 || components === 3) {
+          throw new Error(`size: ${components}`);
+        }
+        return `${dataType}x${components}`;
+
+      case 'uint16':
+        if (components === 1) {
+          return 'uint16';
+        }
+        if (components === 3) {
+          return 'uint16x3-webgl';
+        }
+        return `${dataType}x${components}`;
+
+      case 'sint16':
+        if (components === 1) {
+          return 'sint16';
+        }
+        if (components === 3) {
+          return 'sint16x3-webgl';
+        }
+        return `${dataType}x${components}`;
+
+      case 'unorm16':
+        if (components === 1) {
+          return 'unorm16';
+        }
+        if (components === 3) {
+          return 'unorm16x3-webgl';
+        }
+        return `${dataType}x${components}`;
+
+      case 'snorm16':
+        if (components === 1) {
+          return 'snorm16';
+        }
+        if (components === 3) {
+          return 'snorm16x3-webgl';
+        }
+        return `${dataType}x${components}`;
+
+      case 'float16':
+        // WebGPU 16 bit formats must be aligned to 32 bit boundaries
+        if (components === 1 || components === 3) {
+          throw new Error(`size: ${components}`);
+        }
+        return `${dataType}x${components}`;
+
+      default:
+        return components === 1 ? dataType : `${dataType}x${components}`;
+    }
+  }
+
+  /** Get the vertex format for an attribute with TypedArray and size */
+  getVertexFormatFromAttribute(
+    typedArray: TypedArray,
+    size: number,
+    normalized?: boolean
+  ): VertexFormat {
+    if (!size || size > 4) {
+      throw new Error(`size ${size}`);
+    }
+
+    const components = size as 1 | 2 | 3 | 4;
+    const signedDataType = dataTypeDecoder.getDataType(typedArray);
+    return this.makeVertexFormat(signedDataType, components, normalized);
+  }
+
+  /**
+   * Return a "default" vertex format for a certain shader data type
+   * The simplest vertex format that matches the shader attribute's data type
+   */
+
+  getCompatibleVertexFormat(opts: {
+    primitiveType: PrimitiveDataType;
+    components: 1 | 2 | 3 | 4;
+  }): VertexFormat {
+    let vertexType: NormalizedDataType;
+    switch (opts.primitiveType) {
+      case 'f32':
+        vertexType = 'float32';
+        break;
+      case 'i32':
+        vertexType = 'sint32';
+        break;
+      case 'u32':
+        vertexType = 'uint32';
+        break;
+      case 'f16':
+        return opts.components <= 2 ? 'float16x2' : 'float16x4';
+    }
+
+    // TODO logic does not work for float16
+    if (opts.components === 1) {
+      return vertexType;
+    }
+    return `${vertexType}x${opts.components}`;
+  }
+}
+
+/** Decoder for luma.gl vertex types */
+export const vertexFormatDecoder = new VertexFormatDecoder();