feat(core): Shadertypes refactor

examples/api/animation/app.ts

@@ -1,4 +1,4 @@
-import {UniformStore, VariableShaderType} from '@luma.gl/core';
+import {UniformStore, UniformShaderType} from '@luma.gl/core';
 import {
   AnimationLoopTemplate,
   AnimationProps,
@@ -24,7 +24,7 @@ type AppUniforms = {
   uProjection: number[];
 };
 
-const app: {uniformTypes: Record<string, VariableShaderType>} = {
+const app: {uniformTypes: Record<string, UniformShaderType>} = {
   uniformTypes: {
     uColor: 'vec3<f32>',
     uModel: 'mat4x4<f32>',

examples/showcase/persistence/app.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {NumberArray, VariableShaderType} from '@luma.gl/core';
+import type {NumberArray, UniformShaderType} from '@luma.gl/core';
 import {UniformStore, Framebuffer} from '@luma.gl/core';
 import type {AnimationProps} from '@luma.gl/engine';
 import {
@@ -26,7 +26,7 @@ type SphereUniforms = {
   projectionMatrix: NumberArray;
 };
 
-const sphere: {uniformTypes: Record<keyof SphereUniforms, VariableShaderType>} = {
+const sphere: {uniformTypes: Record<keyof SphereUniforms, UniformShaderType>} = {
   uniformTypes: {
     // TODO make sure order doesn't matter
     color: 'vec3<f32>',
@@ -133,7 +133,7 @@ type ScreenQuadUniforms = {
   resolution: NumberArray;
 };
 
-const screenQuad: {uniformTypes: Record<keyof ScreenQuadUniforms, VariableShaderType>} = {
+const screenQuad: {uniformTypes: Record<keyof ScreenQuadUniforms, UniformShaderType>} = {
   uniformTypes: {
     resolution: 'vec2<f32>'
   }
@@ -216,7 +216,7 @@ type PersistenceQuadUniforms = {
   resolution: NumberArray;
 };
 
-const persistenceQuad: {uniformTypes: Record<keyof ScreenQuadUniforms, VariableShaderType>} = {
+const persistenceQuad: {uniformTypes: Record<keyof ScreenQuadUniforms, UniformShaderType>} = {
   uniformTypes: {
     resolution: 'vec2<f32>'
   }

examples/tutorials/hello-cube/app.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {NumberArray, VariableShaderType} from '@luma.gl/core';
+import type {NumberArray, UniformShaderType} from '@luma.gl/core';
 import {Texture, UniformStore} from '@luma.gl/core';
 import type {AnimationProps} from '@luma.gl/engine';
 import {AnimationLoopTemplate, Model, CubeGeometry, loadImageBitmap, AsyncTexture} from '@luma.gl/engine';
@@ -97,7 +97,7 @@ type AppUniforms = {
   mvpMatrix: NumberArray;
 };
 
-const app: {uniformTypes: Record<keyof AppUniforms, VariableShaderType>} = {
+const app: {uniformTypes: Record<keyof AppUniforms, UniformShaderType>} = {
   uniformTypes: {
     mvpMatrix: 'mat4x4<f32>'
   }

modules/core/src/adapter/types/shader-layout.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {TextureFormat} from '../../shadertypes/texture-formats';
-import type {VariableShaderType, AttributeShaderType} from '../../shadertypes/shader-types';
+import type {UniformShaderType, AttributeShaderType} from '../../shadertypes/shader-types';
 import type {Buffer} from '../resources/buffer';
 import type {Sampler} from '../resources/sampler';
 import type {Texture} from '../resources/texture';
@@ -89,7 +89,7 @@ export type UniformBufferBindingLayout = {
 
 export type UniformInfo = {
   name: string;
-  format: VariableShaderType;
+  format: UniformShaderType;
   type?: string;
   arrayLength: number;
   byteOffset: number;

modules/core/src/index.ts

@@ -123,11 +123,11 @@ export type {
 
 export type {UniformValue} from './adapter/types/uniforms';
 
-// GPU TYPE UTILS - GPU MEMORY LAYOUT TYPES - EXTERNAL
+// SHADER TYPES
 
 export type {NumberArray, TypedArray, TypedArrayConstructor} from './types';
 export type {PrimitiveDataType, SignedDataType, NormalizedDataType} from './shadertypes/data-types';
-export type {AttributeShaderType, VariableShaderType} from './shadertypes/shader-types';
+export type {AttributeShaderType, UniformShaderType} from './shadertypes/shader-types';
 export type {VertexFormat} from './shadertypes/vertex-formats';
 export type {
   TextureFormat,
@@ -146,9 +146,11 @@ export {
   getTypedArrayFromDataType
 } from './shadertypes/utils/decode-data-types';
 export {
+  getShaderTypeInfo,
   getVariableShaderTypeInfo,
   getAttributeShaderTypeInfo
 } from './shadertypes/utils/decode-shader-types';
+export {calculateMemoryOffsets} from './shadertypes/utils/memory-layout';
 export {
   getVertexFormatFromAttribute,
   getVertexFormatInfo

modules/core/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 {UniformShaderType} from '../shadertypes/shader-types';
 import type {UniformValue} from '../adapter/types/uniforms';
 import {
   ShaderLayout,
@@ -30,7 +30,7 @@ export class UniformBlock<
   constructor(props?: {
     name?: string;
     shaderLayout?: ShaderLayout;
-    uniformTypes?: Record<keyof TUniforms, Record<string, VariableShaderType>>;
+    uniformTypes?: Record<keyof TUniforms, Record<string, UniformShaderType>>;
   }) {
     this.name = props?.name || 'unnamed';
 

modules/core/src/portable/uniform-buffer-layout.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {PrimitiveDataType} from '../shadertypes/data-types';
-import type {VariableShaderType} from '../shadertypes/shader-types';
+import type {UniformShaderType} from '../shadertypes/shader-types';
 import {alignTo} from '../shadertypes/utils/decode-data-types';
 import {getVariableShaderTypeInfo} from '../shadertypes/utils/decode-shader-types';
 
@@ -29,7 +29,7 @@ export class UniformBufferLayout {
   readonly byteLength: number;
 
   /** Create a new UniformBufferLayout given a map of attributes. */
-  constructor(uniformTypes: Record<string, VariableShaderType>) {
+  constructor(uniformTypes: Record<string, UniformShaderType>) {
     /** number of 4 byte slots taken */
     let size: number = 0;
 

modules/core/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 {UniformShaderType} from '../shadertypes/shader-types';
 import type {UniformValue} from '../adapter/types/uniforms';
 import type {Device} from '../adapter/device';
 import {Buffer} from '../adapter/resources/buffer';
@@ -38,7 +38,7 @@ export class UniformStore<
     blocks: Record<
       keyof TPropGroups,
       {
-        uniformTypes?: Record<string, VariableShaderType>;
+        uniformTypes?: Record<string, UniformShaderType>;
         defaultProps?: Record<string, unknown>;
         defaultUniforms?: Record<string, UniformValue>;
       }

modules/core/src/shadertypes/shader-types.ts

@@ -4,6 +4,21 @@
 
 import type {PrimitiveDataType} from './data-types';
 
+/**
+ * A composite shader type can include structs and arrays, recursively
+ * This type is designed to allow applications to create compact specifications of shader types.
+ * @note To obtain detailed information about a composite shader type, including memory layout, call `getShaderTypeInfo`.
+ */
+export type ShaderType = VariableShaderType | StructShaderType | ArrayShaderType;
+
+export type ShaderTypeAlias = VariableShaderTypeAlias;
+
+/** Represents a struct in WGSL */
+export type StructShaderType = {[member: string]: ShaderType};
+
+/** Represents an array in WGSL */
+export type ArrayShaderType = [type: ShaderType, length: number];
+
 /**
  * Describes the type of an attribute as defined in the shader source code.
  * @note This is a subset of shader variable types
@@ -16,12 +31,12 @@ export type AttributeShaderType =
   | `vec4<${PrimitiveDataType}>`;
 
 /**
- * Describes the type of a variable that can declared in shader source code.
+ * Describes the type of a uniform that can declared in shader source code.
  * @note Uniforms can be declared using these types
  * @note Uniforms can be of a wider range of types than attributes.
  * @note to WebGL users: "bindings" (textures, samplers, and uniform buffers) are considered "bindings", not shader variables/uniforms
  */
-export type VariableShaderType =
+export type UniformShaderType =
   | PrimitiveDataType
   | `vec2<${PrimitiveDataType}>`
   | `vec3<${PrimitiveDataType}>`
@@ -36,17 +51,27 @@ export type VariableShaderType =
   | `mat4x3<${PrimitiveDataType}>`
   | `mat4x4<${PrimitiveDataType}>`;
 
+export type AtomicShaderType = 'atomic<i32>' | 'atomic<u32>';
+
+/**
+ * Describes the type of an "internal" variable that can declared in shader source code.
+ * @note Uniforms can be declared using these types
+ * @note Uniforms can be of a wider range of types than attributes.
+ * @note to WebGL users: "bindings" (textures, samplers, and uniform buffers) are considered "bindings", not shader variables/uniforms
+ */
+export type VariableShaderType = UniformShaderType | AtomicShaderType | 'bool';
+
 /* Suffixes used by WGSL alias types */
 type ShaderTypeAliasSuffix = 'f' | 'i' | 'u' | 'h';
 
-/** Shorthand type aliases recognized by WGSL */
+/** Shorthand type aliases recognized by WGSL for attributes */
 export type AttributeShaderTypeAlias =
   | `vec2${ShaderTypeAliasSuffix}`
   | `vec3${ShaderTypeAliasSuffix}`
   | `vec4${ShaderTypeAliasSuffix}`;
 
-/** Shorthand type aliases recognized by WGSL */
-export type VariableShaderTypeAlias =
+/** Shorthand type aliases recognized by WGSL for uniforms and storage */
+export type UniformShaderTypeAlias =
   | AttributeShaderTypeAlias
   | `mat2x2${ShaderTypeAliasSuffix}`
   | `mat2x3${ShaderTypeAliasSuffix}`
@@ -58,30 +83,31 @@ export type VariableShaderTypeAlias =
   | `mat4x3${ShaderTypeAliasSuffix}`
   | `mat4x4${ShaderTypeAliasSuffix}`;
 
-/** A composite shader type can include structs and arrays, recursively */
-export type CompositeShaderType = VariableShaderType | StructShaderType | ArrayShaderType;
+/** Shorthand type aliases recognized by WGSL for internal types */
+export type VariableShaderTypeAlias = UniformShaderTypeAlias;
 
-/** Represents a struct in WGSL */
-export type StructShaderType = {
-  members: Record<string, CompositeShaderType>;
-};
-
-/** Represents an array in WGSL */
-export type ArrayShaderType = {
-  type: CompositeShaderType;
-  length: number;
-};
+/**
+ * Info about any ShaderType
+ * @note `offset` will be zero until getMemoryOffsets has been called.
+ */
+// prettier-ignore
+export type ShaderTypeInfo =
+  | {kind: 'array'; shaderType: ArrayShaderType; elementType: ShaderTypeInfo, elements?: number; byteLength: number; byteOffset: number;}
+  | {kind: 'struct'; shaderType: StructShaderType; fields: Record<string, ShaderTypeInfo>; byteLength: number; byteOffset: number;}
+  | {kind: 'primitive'; shaderType: VariableShaderType; byteLength: number, byteOffset: number;} & AttributeShaderTypeInfo;
 
 /** Information extracted from a AttributeShaderType constant */
 export type AttributeShaderTypeInfo = {
   /** WGSL-style primitive data type, f32, i32, u32 */
   primitiveType: PrimitiveDataType;
   /** Whether this is a normalized integer (that must be used as float) */
   components: 1 | 2 | 3 | 4;
-  /** Length in bytes of the data for one vertex */
-  byteLength?: number;
   /** Whether this is for integer or float vert */
   integer: boolean;
   /** Whether this data type is signed */
   signed: boolean;
+  /** Size of this */
+  byteLength: number;
+  /** Memory alignment required by this type */
+  byteAlignment: number;
 };

modules/core/src/shadertypes/utils/decode-data-types.ts

@@ -35,7 +35,7 @@ export function alignTo(size: number, count: number): number {
   }
 }
 
-/** Returns the VariableShaderType that corresponds to a typed array */
+/** Returns the UniformShaderType that corresponds to a typed array */
 export function getDataTypeFromTypedArray(
   arrayOrType: TypedArray | TypedArrayConstructor
 ): SignedDataType {