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

package/src/shadertypes/data-types/data-types.ts

@@ -13,7 +13,7 @@ export type PrimitiveDataType = 'u32' | 'i32' | 'f32' | 'f16';
  * Signed data types describe signed and unsigned integers as well as floats of varying sizes
  * @note These formats describe physical memory layouts in vertex and pixel formats, they are not used inside shaders
  */
-export type SignedDataType =
+export type DataType =
   | 'uint8'
   | 'sint8'
   | 'uint16'
@@ -23,6 +23,8 @@ export type SignedDataType =
   | 'float16'
   | 'float32';
 
+export type SignedDataType = DataType;
+
 /**
  * Normalized data types describe signed and unsigned integers as well as floats of varying sizes together with normalization behavior
  * @note These formats describe physical memory layouts in vertex and pixel formats, they are not used inside shaders
@@ -32,65 +34,115 @@ export type SignedDataType =
 export type NormalizedDataType = SignedDataType | 'unorm8' | 'snorm8' | 'unorm16' | 'snorm16';
 
 /** Returns information about a signed or normalized DataType */
-export type DataTypeInfo = {
-  signedType: SignedDataType;
-  primitiveType: PrimitiveDataType;
-  byteLength: 1 | 2 | 4;
-  normalized: boolean;
-  integer: boolean;
-  signed: boolean;
+export type DataTypeInfo<T extends NormalizedDataType = NormalizedDataType> = {
+  /** The corresponding data type without normalization */
+  signedType: SignedDataTypeT<T>;
+  /** The primitive data type (what the shader sees) */
+  primitiveType: PrimitiveDataTypeT<T>;
+  /** @type number - Length in bytes of the data type */
+  byteLength: DataTypeByteLengthT<T>;
+  /** @type boolean - indicating whether the data type is normalized */
+  normalized: DataTypeIsNormalizedT<T>;
+  /** @type boolean - indicating whether the data type is integer */
+  integer: DataTypeIsIntegerT<T>;
+  /** @type boolean - indicating whether the data type is signed */
+  signed: DataTypeIsSignedT<T>;
 };
 
-/** Returns a typed array appropriate to hold the actual values of a data type (integers for normalized integers) */
-export type DataTypeArray<T extends NormalizedDataType> = T extends 'uint8'
-  ? Uint8Array
-  : T extends 'sint8'
-    ? Int8Array
-    : T extends 'unorm8'
-      ? Uint8Array
-      : T extends 'snorm8'
-        ? Int8Array
-        : T extends 'uint16'
-          ? Uint16Array
-          : T extends 'sint16'
-            ? Int16Array
-            : T extends 'unorm16'
-              ? Uint16Array
-              : T extends 'snorm16'
-                ? Int16Array
-                : T extends 'uint32'
-                  ? Uint32Array
-                  : T extends 'sint32'
-                    ? Int32Array
-                    : T extends 'float16'
-                      ? Uint16Array
-                      : T extends 'float32'
-                        ? Float32Array
-                        : never;
+/** @type the primitive data type seen by the shader */
+export type PrimitiveDataTypeT<T extends NormalizedDataType> = T extends 'float32'
+  ? 'f32'
+  : T extends 'float16'
+    ? 'f16'
+    : T extends 'unorm8' | 'snorm8' | 'unorm16' | 'snorm16'
+      ? 'f32'
+      : T extends 'uint8' | 'uint16' | 'uint32'
+        ? 'u32'
+        : T extends 'sint8' | 'sint16' | 'sint32'
+          ? 'i32'
+          : never;
+
+/** @type The signed data type representing a normalized data type */
+export type SignedDataTypeT<T extends NormalizedDataType> = T extends 'unorm8'
+  ? 'uint8'
+  : T extends 'snorm8'
+    ? 'sint8'
+    : T extends 'unorm16'
+      ? 'uint16'
+      : T extends 'snorm16'
+        ? 'sint16'
+        : T extends NormalizedDataType
+          ? T
+          : never;
+
+/** @type a number type that is is the length in bytes of the data type */
+export type DataTypeByteLengthT<T extends NormalizedDataType = NormalizedDataType> = T extends
+  | 'uint8'
+  | 'sint8'
+  | 'unorm8'
+  | 'snorm8'
+  ? 1
+  : T extends 'uint16' | 'sint16' | 'unorm16' | 'snorm16' | 'float16'
+    ? 2
+    : T extends 'uint32' | 'sint32' | 'float32'
+      ? 4
+      : never;
+
+/** @type a boolean type that is true if the data format is signed */
+export type DataTypeIsSignedT<T extends NormalizedDataType = NormalizedDataType> = T extends
+  | 'sint8'
+  | 'sint16'
+  | 'sint32'
+  ? true
+  : false;
 
-/** Returns a type array appropriate to hold the logical values of a data type (floats for normalized integers) */
-export type NormalizedDataTypeArray<T extends NormalizedDataType> = T extends 'uint8'
-  ? Uint8Array
+/** @type a boolean type that is true if the data format is a normalized format */
+export type DataTypeIsNormalizedT<T extends NormalizedDataType = NormalizedDataType> =
+  T extends SignedDataType ? false : true;
+
+/** @type a boolean type that is true if the data format is an integer format */
+export type DataTypeIsIntegerT<T extends NormalizedDataType = NormalizedDataType> = T extends
+  | 'uint8'
+  | 'sint8'
+  | 'uint16'
+  | 'sint16'
+  | 'uint32'
+  | 'sint32'
+  ? true
+  : false;
+
+/** @type A typed array constructor type appropriate to hold the actual values of a data type (i.e. integers for normalized data types) */
+export type TypedArrayConstructorT<T extends NormalizedDataType> = T extends 'uint8'
+  ? Uint8ArrayConstructor
   : T extends 'sint8'
-    ? Int8Array
+    ? Int8ArrayConstructor
     : T extends 'unorm8'
-      ? Float32Array
+      ? Uint8ArrayConstructor
       : T extends 'snorm8'
-        ? Float32Array
+        ? Int8ArrayConstructor
         : T extends 'uint16'
-          ? Uint16Array
+          ? Uint16ArrayConstructor
           : T extends 'sint16'
-            ? Int16Array
+            ? Int16ArrayConstructor
             : T extends 'unorm16'
-              ? Uint16Array
+              ? Uint16ArrayConstructor
               : T extends 'snorm16'
-                ? Int16Array
+                ? Int16ArrayConstructor
                 : T extends 'uint32'
-                  ? Uint32Array
+                  ? Uint32ArrayConstructor
                   : T extends 'sint32'
-                    ? Int32Array
+                    ? Int32ArrayConstructor
                     : T extends 'float16'
-                      ? Float32Array
+                      ? Uint16ArrayConstructor
                       : T extends 'float32'
-                        ? Float32Array
+                        ? Float32ArrayConstructor
                         : never;
+
+/** @type A typed array constructor appropriate to hold the logical values of a data type (i.e. floats for normalized data types) */
+export type NormalizedTypedArrayConstructorT<T extends NormalizedDataType> = T extends
+  | 'unorm8'
+  | 'snorm8'
+  | 'unorm16'
+  | 'snorm16'
+  ? Float32ArrayConstructor
+  : TypedArrayConstructorT<T>;

package/src/shadertypes/data-types/decode-data-types.ts

@@ -10,10 +10,11 @@ import {PrimitiveDataType, SignedDataType, NormalizedDataType, DataTypeInfo} fro
  * @returns underlying primitive / signed types, byte length, normalization, integer, signed flags
  */
 export function getDataTypeInfo(type: NormalizedDataType): DataTypeInfo {
-  const [signedType, primitiveType, byteLength] = NORMALIZED_TYPE_MAP[type];
   const normalized: boolean = type.includes('norm');
   const integer: boolean = !normalized && !type.startsWith('float');
   const signed: boolean = type.startsWith('s');
+  const typeInfo = NORMALIZED_TYPE_MAP[type];
+  const [signedType, primitiveType, byteLength] = typeInfo || ['uint8 ', 'i32', 1];
   return {
     signedType,
     primitiveType,
@@ -27,7 +28,7 @@ export function getDataTypeInfo(type: NormalizedDataType): DataTypeInfo {
 /** Build a vertex format from a signed data type and a component */
 export function getNormalizedDataType(signedDataType: SignedDataType): NormalizedDataType {
   const dataType: NormalizedDataType = signedDataType;
-  // prettier-ignore
+  // biome-ignore format: preserve layout
   switch (dataType) {
     case 'uint8': return 'unorm8';
     case 'sint8': return 'snorm8';
@@ -39,7 +40,7 @@ export function getNormalizedDataType(signedDataType: SignedDataType): Normalize
 
 /** Align offset to 1, 2 or 4 elements (4, 8 or 16 bytes) */
 export function alignTo(size: number, count: number): number {
-  // prettier-ignore
+  // biome-ignore format: preserve layout
   switch (count) {
     case 1: return size; // Pad upwards to even multiple of 2
     case 2: return size + (size % 2); // Pad upwards to even multiple of 2

package/src/{image-utils → shadertypes/image-types}/image-types.ts

@@ -15,13 +15,6 @@ export type ExternalImage =
   | HTMLCanvasElement
   | OffscreenCanvas;
 
-export type ExternalImageData = {
-  data: ArrayBuffer | SharedArrayBuffer | ArrayBufferView;
-  byteOffset?: number;
-  bytesPerRow?: number;
-  rowsPerImage?: number;
-};
-
 /** Check if data is an external image */
 export function isExternalImage(data: unknown): data is ExternalImage {
   return (

package/src/shadertypes/shader-types/shader-block-layout.ts

@@ -0,0 +1,340 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {PrimitiveDataType} from '../data-types/data-types';
+import type {CompositeShaderType, VariableShaderType} from './shader-types';
+import {alignTo} from '../data-types/decode-data-types';
+import {getVariableShaderTypeInfo, resolveVariableShaderTypeAlias} from './shader-type-decoder';
+
+/**
+ * Describes the packing for one flattened field in a shader block.
+ *
+ * Offsets, sizes, and strides are expressed in 32-bit words so the result can
+ * be consumed directly by typed-array writers.
+ */
+export type ShaderBlockLayoutEntry = {
+  /** Offset in 32-bit words from the start of the block. */
+  offset: number;
+  /** Occupied size in 32-bit words, excluding external array stride. */
+  size: number;
+  /** Number of logical scalar components in the declared value. */
+  components: number;
+  /** Number of matrix columns, or `1` for scalars and vectors. */
+  columns: number;
+  /** Number of rows in each column, or vector length for vectors. */
+  rows: number;
+  /** Distance between matrix columns in 32-bit words. */
+  columnStride: number;
+  /** Canonical shader type after alias resolution. */
+  shaderType: VariableShaderType;
+  /** Scalar data type used to write the value. */
+  type: PrimitiveDataType;
+};
+
+/**
+ * Options for {@link makeShaderBlockLayout}.
+ */
+export type ShaderBlockLayoutOptions = {
+  /**
+   * Packing rules to apply when building the layout.
+   *
+   * Defaults to `'std140'`.
+   */
+  layout?: 'std140' | 'wgsl-uniform' | 'wgsl-storage';
+};
+
+/**
+ * Immutable layout metadata for a uniform or storage-style shader block.
+ */
+export type ShaderBlockLayout = {
+  /** Packing rules used when this layout was created. */
+  layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage';
+  /** Exact number of packed bytes required by the block. */
+  byteLength: number;
+  /** Original composite shader type declarations keyed by top-level field. */
+  uniformTypes: Record<string, CompositeShaderType>;
+  /** Flattened leaf field layouts keyed by field path. */
+  fields: Record<string, ShaderBlockLayoutEntry>;
+};
+
+/**
+ * Builds a deterministic shader-block layout from composite shader type declarations.
+ *
+ * The returned value is pure layout metadata. It records the packed field
+ * offsets and exact packed byte length, but it does not allocate buffers or
+ * serialize values.
+ */
+export function makeShaderBlockLayout(
+  uniformTypes: Readonly<Record<string, CompositeShaderType>>,
+  options: ShaderBlockLayoutOptions = {}
+): ShaderBlockLayout {
+  const copiedUniformTypes = {...uniformTypes};
+  const layout = options.layout ?? 'std140';
+  const fields: Record<string, ShaderBlockLayoutEntry> = {};
+
+  let size = 0;
+  for (const [key, uniformType] of Object.entries(copiedUniformTypes)) {
+    size = addToLayout(fields, key, uniformType, size, layout);
+  }
+
+  size = alignTo(size, getTypeAlignment(copiedUniformTypes, layout));
+
+  return {
+    layout,
+    byteLength: size * 4,
+    uniformTypes: copiedUniformTypes,
+    fields
+  };
+}
+
+/**
+ * Returns the layout metadata for a scalar, vector, or matrix leaf type.
+ *
+ * The result includes both the occupied size in 32-bit words and the alignment
+ * requirement that must be applied before placing the value in a shader block.
+ */
+export function getLeafLayoutInfo(
+  type: VariableShaderType,
+  layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage'
+): Omit<ShaderBlockLayoutEntry, 'offset'> & {alignment: 1 | 2 | 4} {
+  const resolvedType = resolveVariableShaderTypeAlias(type);
+  const decodedType = getVariableShaderTypeInfo(resolvedType);
+  const matrixMatch = /^mat(\d)x(\d)<.+>$/.exec(resolvedType);
+
+  if (matrixMatch) {
+    const columns = Number(matrixMatch[1]);
+    const rows = Number(matrixMatch[2]);
+    const columnInfo = getVectorLayoutInfo(
+      rows as 2 | 3 | 4,
+      resolvedType,
+      decodedType.type,
+      layout
+    );
+    const columnStride = getMatrixColumnStride(columnInfo.size, columnInfo.alignment, layout);
+
+    return {
+      alignment: columnInfo.alignment,
+      size: columns * columnStride,
+      components: columns * rows,
+      columns,
+      rows,
+      columnStride,
+      shaderType: resolvedType,
+      type: decodedType.type
+    };
+  }
+
+  const vectorMatch = /^vec(\d)<.+>$/.exec(resolvedType);
+  if (vectorMatch) {
+    return getVectorLayoutInfo(
+      Number(vectorMatch[1]) as 2 | 3 | 4,
+      resolvedType,
+      decodedType.type,
+      layout
+    );
+  }
+
+  return {
+    alignment: 1,
+    size: 1,
+    components: 1,
+    columns: 1,
+    rows: 1,
+    columnStride: 1,
+    shaderType: resolvedType,
+    type: decodedType.type
+  };
+}
+
+/**
+ * Type guard for composite struct declarations.
+ */
+export function isCompositeShaderTypeStruct(
+  value: CompositeShaderType
+): value is Record<string, CompositeShaderType> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Recursively adds a composite type to the flattened field map.
+ *
+ * @returns The next free 32-bit-word offset after the inserted type.
+ */
+function addToLayout(
+  fields: Record<string, ShaderBlockLayoutEntry>,
+  name: string,
+  type: CompositeShaderType,
+  offset: number,
+  layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage'
+): number {
+  if (typeof type === 'string') {
+    const info = getLeafLayoutInfo(type, layout);
+    const alignedOffset = alignTo(offset, info.alignment);
+    fields[name] = {
+      offset: alignedOffset,
+      ...info
+    };
+    return alignedOffset + info.size;
+  }
+
+  if (Array.isArray(type)) {
+    if (Array.isArray(type[0])) {
+      throw new Error(`Nested arrays are not supported for ${name}`);
+    }
+
+    const elementType = type[0] as CompositeShaderType;
+    const length = type[1] as number;
+    const stride = getArrayStride(elementType, layout);
+    const arrayOffset = alignTo(offset, getTypeAlignment(type, layout));
+
+    for (let i = 0; i < length; i++) {
+      addToLayout(fields, `${name}[${i}]`, elementType, arrayOffset + i * stride, layout);
+    }
+    return arrayOffset + stride * length;
+  }
+
+  if (isCompositeShaderTypeStruct(type)) {
+    const structAlignment = getTypeAlignment(type, layout);
+    let structOffset = alignTo(offset, structAlignment);
+    for (const [memberName, memberType] of Object.entries(type)) {
+      structOffset = addToLayout(fields, `${name}.${memberName}`, memberType, structOffset, layout);
+    }
+    return alignTo(structOffset, structAlignment);
+  }
+
+  throw new Error(`Unsupported CompositeShaderType for ${name}`);
+}
+
+/**
+ * Returns the occupied size of a composite type in 32-bit words.
+ */
+function getTypeSize(
+  type: CompositeShaderType,
+  layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage'
+): number {
+  if (typeof type === 'string') {
+    return getLeafLayoutInfo(type, layout).size;
+  }
+
+  if (Array.isArray(type)) {
+    const elementType = type[0] as CompositeShaderType;
+    const length = type[1] as number;
+
+    if (Array.isArray(elementType)) {
+      throw new Error('Nested arrays are not supported');
+    }
+
+    return getArrayStride(elementType, layout) * length;
+  }
+
+  let size = 0;
+  for (const memberType of Object.values(type)) {
+    const compositeMemberType = memberType as CompositeShaderType;
+    size = alignTo(size, getTypeAlignment(compositeMemberType, layout));
+    size += getTypeSize(compositeMemberType, layout);
+  }
+
+  return alignTo(size, getTypeAlignment(type, layout));
+}
+
+/**
+ * Returns the required alignment of a composite type in 32-bit words.
+ */
+function getTypeAlignment(
+  type: CompositeShaderType,
+  layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage'
+): 1 | 2 | 4 {
+  if (typeof type === 'string') {
+    return getLeafLayoutInfo(type, layout).alignment;
+  }
+
+  if (Array.isArray(type)) {
+    const elementType = type[0] as CompositeShaderType;
+    const elementAlignment = getTypeAlignment(elementType, layout);
+    return uses16ByteArrayAlignment(layout)
+      ? (Math.max(elementAlignment, 4) as 1 | 2 | 4)
+      : elementAlignment;
+  }
+
+  let maxAlignment: 1 | 2 | 4 = 1;
+  for (const memberType of Object.values(type)) {
+    const memberAlignment = getTypeAlignment(memberType as CompositeShaderType, layout);
+    maxAlignment = Math.max(maxAlignment, memberAlignment) as 1 | 2 | 4;
+  }
+
+  return uses16ByteStructAlignment(layout)
+    ? (Math.max(maxAlignment, 4) as 1 | 2 | 4)
+    : maxAlignment;
+}
+
+/**
+ * Returns the layout metadata for a vector leaf type.
+ */
+function getVectorLayoutInfo(
+  components: 2 | 3 | 4,
+  shaderType: VariableShaderType,
+  type: PrimitiveDataType,
+  layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage'
+): Omit<ShaderBlockLayoutEntry, 'offset'> & {alignment: 1 | 2 | 4} {
+  return {
+    alignment: components === 2 ? 2 : 4,
+    size: components === 3 ? 3 : components,
+    components,
+    columns: 1,
+    rows: components,
+    columnStride: components === 3 ? 3 : components,
+    shaderType,
+    type
+  };
+}
+
+/**
+ * Returns the stride of an array element in 32-bit words.
+ *
+ * This includes any layout-specific padding between adjacent array elements.
+ */
+function getArrayStride(
+  elementType: CompositeShaderType,
+  layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage'
+): number {
+  const elementSize = getTypeSize(elementType, layout);
+  const elementAlignment = getTypeAlignment(elementType, layout);
+  return getArrayLikeStride(elementSize, elementAlignment, layout);
+}
+
+/**
+ * Returns the common stride rule shared by array-like elements in the target layout.
+ */
+function getArrayLikeStride(
+  size: number,
+  alignment: 1 | 2 | 4,
+  layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage'
+): number {
+  return alignTo(size, uses16ByteArrayAlignment(layout) ? 4 : alignment);
+}
+
+/**
+ * Returns the stride of a matrix column in 32-bit words.
+ */
+function getMatrixColumnStride(
+  size: number,
+  alignment: 1 | 2 | 4,
+  layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage'
+): number {
+  return layout === 'std140' ? 4 : alignTo(size, alignment);
+}
+
+/**
+ * Returns `true` when arrays must be rounded up to 16-byte boundaries.
+ */
+function uses16ByteArrayAlignment(layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage'): boolean {
+  return layout === 'std140' || layout === 'wgsl-uniform';
+}
+
+/**
+ * Returns `true` when structs must be rounded up to 16-byte boundaries.
+ */
+function uses16ByteStructAlignment(layout: 'std140' | 'wgsl-uniform' | 'wgsl-storage'): boolean {
+  return layout === 'std140' || layout === 'wgsl-uniform';
+}