@luma.gl/core 9.2.5 → 9.3.0-alpha.10

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,131 @@
+// 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) {
+      // TODO - Special cases for WebGL (not supported on WebGPU), overrides the check below
+      case 'unorm8':
+        if (components === 1) {
+          return 'unorm8';
+        }
+        if (components === 3) {
+          return 'unorm8x3-webgl';
+        }
+        return `${dataType}x${components}`;
+
+      case 'snorm8':
+      case 'uint8':
+      case 'sint8':
+      // WebGPU 8 bit formats must be aligned to 16 bit boundaries');
+      // fall through
+      case 'uint16':
+      case 'sint16':
+      case 'unorm16':
+      case 'snorm16':
+      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();

package/src/shadertypes/vertex-types/vertex-formats.ts

@@ -0,0 +1,183 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  DataTypeIsIntegerT,
+  DataTypeIsNormalizedT,
+  DataTypeIsSignedT
+} from '../data-types/data-types';
+
+/**
+ * Describes the **memory format** and interpretation (normalization) of a buffer that will be supplied to vertex attributes
+ * @note Must be compatible with the AttributeShaderType of the shaders, see documentation.
+ * @note This is a superset of WebGPU vertex formats to allow for some flexibility for WebGL only applications
+ * @todo Add device.isVertexFormatSupported() method?
+ */
+export type VertexFormat =
+  // 8 bit integers, note that only 16 bit aligned formats are supported in WebGPU (x2 and x4)
+  | 'uint8' // Chrome 133+
+  | 'uint8x2'
+  | 'uint8x4'
+  | 'sint8' // Chrome 133+
+  | 'sint8x2'
+  | 'sint8x4'
+  | 'unorm8' // Chrome 133+
+  | 'unorm8x2'
+  | 'unorm8x3-webgl' // Not in WebGPU
+  | 'unorm8x4'
+  | 'unorm8x4-bgra' // Chrome 133+
+  | 'unorm10-10-10-2' // Chrome 119+
+  // | 'snorm-10-10-10-2' // Not in WebGPU, DXD12 doesn't support
+  | 'snorm8' // Chrome 133+
+  | 'snorm8x2'
+  | 'snorm8x3-webgl'
+  | 'snorm8x4'
+  // 16 bit integers, that only 32 bit aligned formats are supported in WebGPU (x2 and x4)
+  | 'uint16' // Chrome 133+
+  | 'sint16' // Chrome 133+
+  | 'unorm16' // Chrome 133+
+  | 'snorm16' // Chrome 133+
+  | 'uint16x2'
+  | 'uint16x4'
+  | 'sint16x2'
+  | 'sint16x4'
+  | 'unorm16x2'
+  | 'unorm16x4'
+  | 'snorm16x2'
+  | 'snorm16x4'
+  // 32 bit integers
+  | 'uint32'
+  | 'uint32x2'
+  | 'uint32x3'
+  | 'uint32x4'
+  | 'sint32'
+  | 'sint32x2'
+  | 'sint32x3'
+  | 'sint32x4'
+  // No normalized 32 bit integers in WebGPU...
+  // | 'unorm32'
+  // | 'unorm32x2'
+  // | 'unorm32x3'
+  // | 'unorm32x4'
+  // | 'snorm32'
+  // | 'snorm32x2'
+  // | 'snorm32x3'
+  // | 'snorm32x4'
+  // floats
+  | 'float16' // Chrome 133+
+  | 'float16x2'
+  | 'float16x4'
+  | 'float32'
+  | 'float32x2'
+  | 'float32x3'
+  | 'float32x4';
+
+/**
+ * @type Information about a vertex format
+ */
+export type VertexFormatInfo<T extends VertexFormat = VertexFormat> = {
+  /** Type of each component */
+  type: VertexFormatDataTypeT<T>;
+  /** Number of components per vertex / row */
+  components: VertexFormatComponentsT<T>;
+  /** Is this an integer format (normalized integer formats are not integer) */
+  integer: DataTypeIsIntegerT<VertexFormatDataTypeT<T>>;
+  /** Is this a signed format? */
+  signed: DataTypeIsSignedT<VertexFormatDataTypeT<T>>;
+  /** Is this a normalized format? */
+  normalized: DataTypeIsNormalizedT<VertexFormatDataTypeT<T>>;
+  /** Length in bytes */
+  byteLength: number;
+  /** Is this a bgra format? */
+  bgra?: boolean;
+  /** Is this a webgl only format? */
+  webglOnly?: boolean;
+};
+
+/** @type the NormalizedDataType of the components in a VertexFormat */
+export type VertexFormatDataTypeT<T extends VertexFormat> = T extends VertexFormatUint8
+  ? 'uint8'
+  : T extends VertexFormatSint8
+    ? 'sint8'
+    : T extends VertexFormatUnorm8
+      ? 'unorm8'
+      : T extends VertexFormatSnorm8
+        ? 'snorm8'
+        : T extends VertexFormatUint16
+          ? 'uint16'
+          : T extends VertexFormatSint16
+            ? 'sint16'
+            : T extends VertexFormatUnorm16
+              ? 'unorm16'
+              : T extends VertexFormatSnorm16
+                ? 'snorm16'
+                : T extends VertexFormatUint32
+                  ? 'uint32'
+                  : T extends VertexFormatSint32
+                    ? 'sint32'
+                    : T extends VertexFormatFloat16
+                      ? 'float16'
+                      : T extends VertexFormatFloat32
+                        ? 'float32'
+                        : never;
+
+/** @type number - the number of components in a VertexFormat */
+export type VertexFormatComponentsT<T extends VertexFormat> = T extends VertexFormat2Components
+  ? 2
+  : T extends VertexFormat3Components
+    ? 3
+    : T extends VertexFormat4Components
+      ? 4
+      : 1;
+
+// Helper types for the above
+
+type VertexFormatUint8 = 'uint8' | 'uint8x2' | 'uint8x4';
+type VertexFormatSint8 = 'sint8' | 'sint8x2' | 'sint8x4';
+type VertexFormatUnorm8 =
+  | 'unorm8'
+  | 'unorm8x2'
+  | 'unorm8x3-webgl'
+  | 'unorm8x4'
+  | 'unorm8x4-bgra'
+  | 'unorm10-10-10-2';
+type VertexFormatSnorm8 = 'snorm8' | 'snorm8x2' | 'snorm8x3-webgl' | 'snorm8x4';
+type VertexFormatUint16 = 'uint16' | 'uint16x2' | 'uint16x4';
+type VertexFormatSint16 = 'sint16' | 'sint16x2' | 'sint16x4';
+type VertexFormatUnorm16 = 'unorm16' | 'unorm16x2' | 'unorm16x4';
+type VertexFormatSnorm16 = 'snorm16' | 'snorm16x2' | 'snorm16x4';
+type VertexFormatUint32 = 'uint32' | 'uint32x2' | 'uint32x3' | 'uint32x4';
+type VertexFormatSint32 = 'sint32' | 'sint32x2' | 'sint32x3' | 'sint32x4';
+type VertexFormatFloat16 = 'float16' | 'float16x2' | 'float16x4';
+type VertexFormatFloat32 = 'float32' | 'float32x2' | 'float32x3' | 'float32x4';
+
+type VertexFormat2Components =
+  | 'uint8x2'
+  | 'sint8x2'
+  | 'unorm8x2'
+  | 'snorm8x2'
+  | 'uint16x2'
+  | 'sint16x2'
+  | 'unorm16x2'
+  | 'snorm16x2'
+  | 'uint32x2'
+  | 'sint32x2'
+  | 'float16x2'
+  | 'float32x2';
+type VertexFormat3Components = 'unorm8x3-webgl' | 'uint32x3' | 'sint32x3' | 'float32x3';
+type VertexFormat4Components =
+  | 'uint8x4'
+  | 'sint8x4'
+  | 'unorm8x4'
+  | 'unorm8x4-bgra'
+  | 'unorm10-10-10-2'
+  | 'snorm8x4'
+  | 'uint16x4'
+  | 'sint16x4'
+  | 'unorm16x4'
+  | 'snorm16x4'
+  | 'uint32x4'
+  | 'sint32x4'
+  | 'float16x4'
+  | 'float32x4';

package/src/utils/array-equal.ts

@@ -4,23 +4,35 @@
 
 import {isNumberArray} from './is-array';
 
-/** Test if two arrays are deep equal, with a length limit that defaults to 16 */
+const MAX_ELEMENTWISE_ARRAY_COMPARE_LENGTH = 128;
+
+/** Test if two arrays are deep equal, with a small-array length limit that defaults to 16 */
 export function arrayEqual(a: unknown, b: unknown, limit: number = 16) {
-  if (a !== b) {
-    return false;
+  if (a === b) {
+    return true;
   }
+
   const arrayA = a;
   const arrayB = b;
-  if (!isNumberArray(arrayA)) {
+  if (!isNumberArray(arrayA) || !isNumberArray(arrayB)) {
+    return false;
+  }
+
+  if (arrayA.length !== arrayB.length) {
     return false;
   }
-  if (isNumberArray(arrayB) && arrayA.length === arrayB.length) {
-    for (let i = 0; i < arrayA.length; ++i) {
-      if (arrayB[i] !== arrayA[i]) {
-        return false;
-      }
+
+  const maxCompareLength = Math.min(limit, MAX_ELEMENTWISE_ARRAY_COMPARE_LENGTH);
+  if (arrayA.length > maxCompareLength) {
+    return false;
+  }
+
+  for (let i = 0; i < arrayA.length; ++i) {
+    if (arrayB[i] !== arrayA[i]) {
+      return false;
     }
   }
+
   return true;
 }
 

package/src/utils/assert.ts

@@ -0,0 +1,18 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Throws if condition is true and narrows type */
+export function assert(condition: unknown, message?: string): asserts condition {
+  if (!condition) {
+    const error = new Error(message ?? 'luma.gl assertion failed.');
+    Error.captureStackTrace?.(error, assert);
+    throw error;
+  }
+}
+
+/** Throws if value is not defined, narrows type */
+export function assertDefined<T>(value: T | undefined, message?: string): T {
+  assert(value, message);
+  return value;
+}