@luma.gl/core 9.2.0-alpha.1 → 9.2.0-alpha.5

package/src/adapter-utils/get-attribute-from-layouts.ts

@@ -3,14 +3,14 @@
 // Copyright (c) vis.gl contributors
 
 import {log} from '../utils/log';
-import type {PrimitiveDataType, NormalizedDataType} from '../shadertypes/data-types';
-import type {AttributeShaderType} from '../shadertypes/shader-types';
-import type {VertexFormat} from '../shadertypes/vertex-formats';
-import {getAttributeShaderTypeInfo} from '../shadertypes/utils/decode-shader-types';
+import type {PrimitiveDataType, NormalizedDataType} from '../shadertypes/data-types/data-types';
+import type {AttributeShaderType} from '../shadertypes/data-types/shader-types';
+import type {VertexFormat} from '../shadertypes/vertex-arrays/vertex-formats';
+import {getAttributeShaderTypeInfo} from '../shadertypes/data-types/decode-shader-types';
 import {
   getVertexFormatInfo,
   getCompatibleVertexFormat
-} from '../shadertypes/utils/decode-vertex-format';
+} from '../shadertypes/vertex-arrays/decode-vertex-format';
 import type {ShaderLayout, AttributeDeclaration} from '../adapter/types/shader-layout';
 import type {BufferLayout} from '../adapter/types/buffer-layout';
 

package/src/index.ts

@@ -21,17 +21,13 @@ export type {CanvasContextProps} from './adapter/canvas-context';
 export {CanvasContext} from './adapter/canvas-context';
 
 // GPU RESOURCES
-export type {ResourceProps} from './adapter/resources/resource';
-export {Resource} from './adapter/resources/resource';
+export {Resource, type ResourceProps} from './adapter/resources/resource';
 
-export type {BufferProps} from './adapter/resources/buffer';
-export {Buffer} from './adapter/resources/buffer';
+export {Buffer, type BufferProps, type BufferMapCallback} from './adapter/resources/buffer';
 
-export type {TextureProps} from './adapter/resources/texture';
-export {Texture} from './adapter/resources/texture';
+export {Texture, type TextureProps} from './adapter/resources/texture';
 
-export type {TextureViewProps} from './adapter/resources/texture-view';
-export {TextureView} from './adapter/resources/texture-view';
+export {TextureView, type TextureViewProps} from './adapter/resources/texture-view';
 
 export type {ExternalTextureProps} from './adapter/resources/external-texture';
 export {ExternalTexture} from './adapter/resources/external-texture';
@@ -72,6 +68,9 @@ export {TransformFeedback} from './adapter/resources/transform-feedback';
 export type {QuerySetProps} from './adapter/resources/query-set';
 export {QuerySet} from './adapter/resources/query-set';
 
+export type {PipelineLayoutProps} from './adapter/resources/pipeline-layout';
+export {PipelineLayout} from './adapter/resources/pipeline-layout';
+
 // PORTABLE API - UNIFORM BUFFERS
 export {UniformBufferLayout} from './portable/uniform-buffer-layout';
 export {UniformBlock} from './portable/uniform-block';
@@ -82,7 +81,11 @@ export {UniformStore} from './portable/uniform-store';
 export type {CompilerMessage} from './adapter/types/compiler-message';
 
 export type {ExternalImage} from './image-utils/image-types';
-export type {CopyExternalImageOptions, CopyImageDataOptions} from './adapter/resources/texture';
+
+export {
+  type CopyExternalImageOptions,
+  type CopyImageDataOptions
+} from './adapter/resources/texture';
 
 export type {Parameters, PrimitiveTopology, IndexFormat} from './adapter/types/parameters';
 
@@ -110,7 +113,12 @@ export type {
   ComputeShaderLayout,
   AttributeDeclaration,
   BindingDeclaration,
-  Binding
+  Binding,
+  UniformBufferBindingLayout,
+  StorageBufferBindingLayout,
+  TextureBindingLayout,
+  SamplerBindingLayout,
+  StorageTextureBindingLayout
 } from './adapter/types/shader-layout';
 export type {BufferLayout, BufferAttributeLayout} from './adapter/types/buffer-layout';
 export type {
@@ -133,41 +141,58 @@ export type {
   BigTypedArrayConstructor
 } from './types';
 
-// GPU TYPE UTILS - GPU MEMORY LAYOUT TYPES - EXTERNAL
-
-export type {PrimitiveDataType, SignedDataType, NormalizedDataType} from './shadertypes/data-types';
-export type {AttributeShaderType, VariableShaderType} from './shadertypes/shader-types';
-export type {VertexFormat} from './shadertypes/vertex-formats';
-export type {
-  TextureFormat,
-  ColorTextureFormat,
-  DepthStencilTextureFormat,
-  TextureCompression,
-  TextureFormatInfo,
-  TextureFormatCapabilities
-} from './shadertypes/texture-formats';
-
-// GPU TYPE UTILS - GPU MEMORY LAYOUT HELPERS - CAN BE USED BY APPS BUT MOSTLY USED INTERNALLY
+// GPU TYPE UTILS - BASIC DATA TYPES
 
+export {
+  type PrimitiveDataType,
+  type SignedDataType,
+  type NormalizedDataType,
+  type DataTypeInfo,
+  type DataTypeArray,
+  type NormalizedDataTypeArray
+} from './shadertypes/data-types/data-types';
+export {
+  type AttributeShaderType,
+  type VariableShaderType
+} from './shadertypes/data-types/shader-types';
 export {
   getDataTypeInfo,
-  getDataTypeFromTypedArray,
-  getTypedArrayFromDataType,
-  makeNormalizedDataType
-} from './shadertypes/utils/decode-data-types';
+  getDataType,
+  getTypedArrayConstructor,
+  getNormalizedDataType
+} from './shadertypes/data-types/decode-data-types';
 export {
   getVariableShaderTypeInfo,
   getAttributeShaderTypeInfo
-} from './shadertypes/utils/decode-shader-types';
+} from './shadertypes/data-types/decode-shader-types';
+
+// GPU TYPE UTILS - VERTEX ARRAYs
+
+export {type VertexFormat} from './shadertypes/vertex-arrays/vertex-formats';
+
 export {
   getVertexFormatInfo,
   getVertexFormatFromAttribute,
   makeVertexFormat
-} from './shadertypes/utils/decode-vertex-format';
+} from './shadertypes/vertex-arrays/decode-vertex-format';
+
+// GPU TYPE UTILS - Texture Formats
+
+export {
+  type TextureFormat,
+  type TextureFormatColor,
+  type TextureFormatDepthStencil,
+  type TextureCompression,
+  type TextureFormatInfo,
+  type TextureFormatCapabilities
+} from './shadertypes/textures/texture-formats';
+
 export {
-  getTextureFormatInfo,
-  getTextureFormatCapabilities
-} from './shadertypes/utils/decode-texture-format';
+  TextureFormatDecoder,
+  textureFormatDecoder
+} from './shadertypes/textures/texture-format-decoder';
+
+export {type PixelData, readPixel, writePixel} from './shadertypes/textures/pixel-utils';
 
 // GENERAL EXPORTS - FOR APPLICATIONS
 
@@ -186,11 +211,10 @@ export type {
 export {log} from './utils/log';
 export {getScratchArray} from './utils/array-utils-flat';
 export type {AttributeInfo} from './adapter-utils/get-attribute-from-layouts';
-export {BufferLayoutHelper as _BufferLayoutHelper} from './adapter-utils/buffer-layout-helper';
 export {getAttributeInfosFromLayouts} from './adapter-utils/get-attribute-from-layouts';
 
 // TEST EXPORTS
 export {
   getTextureFormatDefinition as _getTextureFormatDefinition,
   getTextureFormatTable as _getTextureFormatTable
-} from './shadertypes/utils/texture-format-table';
+} from './shadertypes/textures/texture-format-table';

package/src/portable/uniform-block.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {VariableShaderType} from '../shadertypes/shader-types';
+import type {VariableShaderType} from '../shadertypes/data-types/shader-types';
 import type {UniformValue} from '../adapter/types/uniforms';
 import {
   ShaderLayout,

package/src/portable/uniform-buffer-layout.ts

@@ -2,10 +2,10 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {PrimitiveDataType} from '../shadertypes/data-types';
-import type {VariableShaderType} from '../shadertypes/shader-types';
-import {alignTo} from '../shadertypes/utils/decode-data-types';
-import {getVariableShaderTypeInfo} from '../shadertypes/utils/decode-shader-types';
+import type {PrimitiveDataType} from '../shadertypes/data-types/data-types';
+import type {VariableShaderType} from '../shadertypes/data-types/shader-types';
+import {alignTo} from '../shadertypes/data-types/decode-data-types';
+import {getVariableShaderTypeInfo} from '../shadertypes/data-types/decode-shader-types';
 
 import type {UniformValue} from '../adapter/types/uniforms';
 import {getScratchArrayBuffer} from '../utils/array-utils-flat';
@@ -29,14 +29,19 @@ export class UniformBufferLayout {
   readonly byteLength: number;
 
   /** Create a new UniformBufferLayout given a map of attributes. */
-  constructor(uniformTypes: Record<string, VariableShaderType>) {
+  constructor(
+    uniformTypes: Record<string, VariableShaderType>,
+    uniformSizes: Record<string, number> = {}
+  ) {
     /** number of 4 byte slots taken */
     let size: number = 0;
 
     // Add layout (type, size and offset) definitions for each uniform in the layout
     for (const [key, uniformType] of Object.entries(uniformTypes)) {
       const typeAndComponents = getVariableShaderTypeInfo(uniformType);
-      const {type, components: count} = typeAndComponents;
+      const {type, components} = typeAndComponents;
+      // Calculate total count for uniform arrays.
+      const count = components * (uniformSizes?.[key] ?? 1);
       // First, align (bump) current offset to an even multiple of current object (1, 2, 4)
       size = alignTo(size, count);
       // Use the aligned size as the offset of the current uniform.
@@ -53,10 +58,8 @@ export class UniformBufferLayout {
 
   /** Get the data for the complete buffer */
   getData(uniformValues: Record<string, UniformValue>): Uint8Array {
-    const bufferSize = Math.max(this.byteLength, minBufferSize);
-
     // Allocate three typed arrays pointing at same memory
-    const arrayBuffer = getScratchArrayBuffer(bufferSize);
+    const arrayBuffer = getScratchArrayBuffer(this.byteLength);
     const typedArrays = {
       i32: new Int32Array(arrayBuffer),
       u32: new Uint32Array(arrayBuffer),
@@ -64,8 +67,6 @@ export class UniformBufferLayout {
       // TODO not implemented
       f16: new Uint16Array(arrayBuffer)
     };
-    // TODO is this needed?
-    // typedArrays.i32.fill(0);
 
     for (const [name, value] of Object.entries(uniformValues)) {
       const uniformLayout = this.layout[name];
@@ -101,7 +102,7 @@ export class UniformBufferLayout {
       }
     }
 
-    return new Uint8Array(arrayBuffer);
+    return new Uint8Array(arrayBuffer, 0, this.byteLength);
   }
 
   /** Does this layout have a field with specified name */

package/src/portable/uniform-store.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {VariableShaderType} from '../shadertypes/shader-types';
+import type {VariableShaderType} from '../shadertypes/data-types/shader-types';
 import type {UniformValue} from '../adapter/types/uniforms';
 import type {Device} from '../adapter/device';
 import {Buffer} from '../adapter/resources/buffer';
@@ -39,6 +39,7 @@ export class UniformStore<
       keyof TPropGroups,
       {
         uniformTypes?: Record<string, VariableShaderType>;
+        uniformSizes?: Record<string, number>;
         defaultProps?: Record<string, unknown>;
         defaultUniforms?: Record<string, UniformValue>;
       }
@@ -48,7 +49,10 @@ export class UniformStore<
       const uniformBufferName = bufferName as keyof TPropGroups;
 
       // Create a layout object to help us generate correctly formatted binary uniform buffers
-      const uniformBufferLayout = new UniformBufferLayout(block.uniformTypes || {});
+      const uniformBufferLayout = new UniformBufferLayout(
+        block.uniformTypes ?? {},
+        block.uniformSizes ?? {}
+      );
       this.uniformBufferLayouts.set(uniformBufferName, uniformBufferLayout);
 
       // Create a Uniform block to store the uniforms for each buffer.

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

@@ -0,0 +1,96 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Primitive data types that shaders can perform calculations in and declare variables with.
+ * @note attribute inputs and texture samples can be populated from a different in-memory types, see below.
+ * @note `f16` requires the `f16` extension
+ */
+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 =
+  | 'uint8'
+  | 'sint8'
+  | 'uint16'
+  | 'sint16'
+  | 'uint32'
+  | 'sint32'
+  | 'float16'
+  | 'float32';
+
+/**
+ * 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
+ * @note Normalization means that these formats are converted into floats on read (shader must use f32 to process them)
+ * @note WebGPU does not support normalized 32 bit integer attributes: 'unorm32' | 'snorm32'
+ */
+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;
+};
+
+/** 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;
+
+/** 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
+  : T extends 'sint8'
+    ? Int8Array
+    : T extends 'unorm8'
+      ? Float32Array
+      : T extends 'snorm8'
+        ? Float32Array
+        : 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'
+                      ? Float32Array
+                      : T extends 'float32'
+                        ? Float32Array
+                        : never;

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

@@ -0,0 +1,91 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {TypedArray, TypedArrayConstructor} from '../../types';
+import {PrimitiveDataType, SignedDataType, NormalizedDataType, DataTypeInfo} from './data-types';
+
+/**
+ * Gets info about a data type constant (signed or normalized)
+ * @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');
+  return {
+    signedType,
+    primitiveType,
+    byteLength,
+    normalized,
+    integer,
+    signed
+  };
+}
+
+/** Build a vertex format from a signed data type and a component */
+export function getNormalizedDataType(signedDataType: SignedDataType): NormalizedDataType {
+  const dataType: NormalizedDataType = signedDataType;
+  // prettier-ignore
+  switch (dataType) {
+    case 'uint8': return 'unorm8';
+    case 'sint8': return 'snorm8';
+    case 'uint16': return 'unorm16';
+    case 'sint16': return 'snorm16';
+    default: return dataType;
+  }
+}
+
+/** Align offset to 1, 2 or 4 elements (4, 8 or 16 bytes) */
+export function alignTo(size: number, count: number): number {
+  // prettier-ignore
+  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
+    default: return size + ((4 - (size % 4)) % 4); // Pad upwards to even multiple of 4
+  }
+}
+
+/** Returns the VariableShaderType that corresponds to a typed array */
+export function getDataType(arrayOrType: TypedArray | TypedArrayConstructor): SignedDataType {
+  const Constructor = ArrayBuffer.isView(arrayOrType) ? arrayOrType.constructor : arrayOrType;
+  if (Constructor === Uint8ClampedArray) {
+    return 'uint8';
+  }
+  const info = Object.values(NORMALIZED_TYPE_MAP).find(entry => Constructor === entry[4]);
+  if (!info) {
+    throw new Error(Constructor.name);
+  }
+  return info[0];
+}
+
+/** Returns the TypedArray that corresponds to a shader data type */
+export function getTypedArrayConstructor(type: NormalizedDataType): TypedArrayConstructor {
+  const [, , , , Constructor] = NORMALIZED_TYPE_MAP[type];
+  return Constructor;
+}
+
+const NORMALIZED_TYPE_MAP: Record<
+  NormalizedDataType,
+  [
+    SignedDataType,
+    PrimitiveDataType,
+    bytes: 1 | 2 | 4,
+    normalized: boolean,
+    arrayConstructor: TypedArrayConstructor
+  ]
+> = {
+  uint8: ['uint8', 'u32', 1, false, Uint8Array],
+  sint8: ['sint8', 'i32', 1, false, Int8Array],
+  unorm8: ['uint8', 'f32', 1, true, Uint8Array],
+  snorm8: ['sint8', 'f32', 1, true, Int8Array],
+  uint16: ['uint16', 'u32', 2, false, Uint16Array],
+  sint16: ['sint16', 'i32', 2, false, Int16Array],
+  unorm16: ['uint16', 'u32', 2, true, Uint16Array],
+  snorm16: ['sint16', 'i32', 2, true, Int16Array],
+  float16: ['float16', 'f16', 2, false, Uint16Array],
+  float32: ['float32', 'f32', 4, false, Float32Array],
+  uint32: ['uint32', 'u32', 4, false, Uint32Array],
+  sint32: ['sint32', 'i32', 4, false, Int32Array]
+};

package/src/shadertypes/{utils → data-types}/decode-shader-types.ts

@@ -2,14 +2,14 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {PrimitiveDataType} from '../data-types';
+import {PrimitiveDataType} from './data-types';
 import type {
   VariableShaderType,
   AttributeShaderType,
   AttributeShaderTypeInfo,
   VariableShaderTypeAlias,
   AttributeShaderTypeAlias
-} from '../shader-types';
+} from './shader-types';
 
 /** Split a uniform type string into type and components */
 export function getVariableShaderTypeInfo(format: VariableShaderType): {