@luma.gl/shadertools 9.1.0-alpha.1 → 9.1.0-alpha.12

package/src/lib/shader-module/shader-module.ts

@@ -2,11 +2,20 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {NumberArray} from '@math.gl/types';
-import {UniformFormat} from '../../types';
-import {PropType} from '../filters/prop-types';
+import type {NumericArray} from '@math.gl/types';
+import {Sampler, Texture} from '@luma.gl/core';
+import type {UniformFormat} from '../../types';
+import {
+  PropType,
+  PropValidator,
+  makePropValidators,
+  getValidatedProperties
+} from '../filters/prop-types';
+import {ShaderInjection, normalizeInjections} from '../shader-assembly/shader-injections';
 
-export type UniformValue = number | boolean | Readonly<NumberArray>; // Float32Array> | Readonly<Int32Array> | Readonly<Uint32Array> | Readonly<number[]>;
+export type BindingValue = Buffer | Texture | Sampler;
+export type UniformValue = number | boolean | Readonly<NumericArray>;
+// Float32Array> | Readonly<Int32Array> | Readonly<Uint32Array> | Readonly<number[]>;
 
 export type UniformInfo = {
   format?: UniformFormat;
@@ -14,20 +23,26 @@ export type UniformInfo = {
 
 /**
  * A shader module definition object
- * @note Can be viewed as the ShaderModuleProps for a ShaderModuleInstance
+ *
+ * @note Needs to be initialized with `initializeShaderModules`
  */
 export type ShaderModule<
   PropsT extends Record<string, unknown> = Record<string, unknown>,
   UniformsT extends Record<string, UniformValue> = Record<string, UniformValue>,
-  BindingsT extends Record<string, unknown> = {}
+  BindingsT extends Record<string, BindingValue> = Record<string, BindingValue>
 > = {
   /** Used for type inference not for values */
-  props?: Required<PropsT>;
+  props?: PropsT;
   /** Used for type inference, not currently used for values */
   uniforms?: UniformsT;
 
   name: string;
+
+  /** WGSL code */
+  source?: string;
+  /** GLSL fragment shader code */
   fs?: string;
+  /** GLSL vertex shader code */
   vs?: string;
 
   /** Uniform shader types @note: Both order and types MUST match uniform block declarations in shader */
@@ -37,9 +52,8 @@ export type ShaderModule<
   /** Default uniform values */
   defaultUniforms?: Required<UniformsT>; // Record<keyof UniformsT, UniformValue>;
 
-  /** Function that maps settings to uniforms */
-  // getUniforms?: (settings?: Partial<SettingsT>, prevUniforms?: any /* UniformsT */) => UniformsT;
-  getUniforms?: (settings?: any, prevUniforms?: any) => Record<string, UniformValue>;
+  /** Function that maps props to uniforms & bindings */
+  getUniforms?: (props?: any, oldProps?: any) => Record<string, BindingValue | UniformValue>;
 
   /** uniform buffers, textures, samplers, storage, ... */
   bindings?: Record<keyof BindingsT, {location: number; type: 'texture' | 'sampler' | 'uniforms'}>;
@@ -51,8 +65,16 @@ export type ShaderModule<
   /** Information on deprecated properties */
   deprecations?: ShaderModuleDeprecation[];
 
-  /** Internal */
-  normalized?: boolean;
+  /** The instance field contains information that is generated at run-time */
+  instance?: {
+    propValidators?: Record<string, PropValidator>;
+    parsedDeprecations: ShaderModuleDeprecation[];
+
+    normalizedInjections: {
+      vertex: Record<string, ShaderInjection>;
+      fragment: Record<string, ShaderInjection>;
+    };
+  };
 };
 
 /** Use to generate deprecations when shader module is used */
@@ -64,16 +86,109 @@ export type ShaderModuleDeprecation = {
   deprecated?: boolean;
 };
 
+// SHNDER MODULE API
+
+export function initializeShaderModules(modules: ShaderModule[]): void {
+  modules.map((module: ShaderModule) => initializeShaderModule(module));
+}
+
+export function initializeShaderModule(module: ShaderModule): void {
+  if (module.instance) {
+    return;
+  }
+
+  initializeShaderModules(module.dependencies || []);
+
+  const {
+    uniformPropTypes = {},
+    deprecations = [],
+    // defines = {},
+    inject = {}
+  } = module;
+
+  const instance: Required<ShaderModule>['instance'] = {
+    normalizedInjections: normalizeInjections(inject),
+    parsedDeprecations: parseDeprecationDefinitions(deprecations)
+  };
+
+  if (uniformPropTypes) {
+    instance.propValidators = makePropValidators(uniformPropTypes);
+  }
+
+  module.instance = instance;
+}
+
 /** Convert module props to uniforms */
 export function getShaderModuleUniforms<
   ShaderModuleT extends ShaderModule<Record<string, unknown>, Record<string, UniformValue>>
->(module: ShaderModuleT, props: ShaderModuleT['props']): ShaderModuleT['uniforms'] {
-  const uniforms = {...module.defaultUniforms};
+>(
+  module: ShaderModuleT,
+  props: ShaderModuleT['props'],
+  oldUniforms?: ShaderModuleT['uniforms']
+): Record<string, BindingValue | UniformValue> {
+  initializeShaderModule(module);
+
+  const uniforms = oldUniforms || {...module.defaultUniforms};
+  // If module has a getUniforms function, use it
   if (module.getUniforms) {
-    // @ts-expect-error
-    Object.assign(props, module.getUniforms(props));
-  } else {
-    Object.assign(uniforms, props);
+    return module.getUniforms(props, uniforms);
   }
-  return uniforms;
+
+  // Build uniforms from the uniforms array
+  // @ts-expect-error
+  return getValidatedProperties(props, module.instance?.propValidators, module.name);
+}
+
+/* TODO this looks like it was unused code
+  _defaultGetUniforms(opts: Record<string, any> = {}): Record<string, any> {
+    const uniforms: Record<string, any> = {};
+    const propTypes = this.uniforms;
+
+    for (const key in propTypes) {
+      const propDef = propTypes[key];
+      if (key in opts && !propDef.private) {
+        if (propDef.validate) {
+          assert(propDef.validate(opts[key], propDef), `${this.name}: invalid ${key}`);
+        }
+        uniforms[key] = opts[key];
+      } else {
+        uniforms[key] = propDef.value;
+      }
+    }
+
+    return uniforms;
+  }
+}
+*/
+// Warn about deprecated uniforms or functions
+export function checkShaderModuleDeprecations(
+  shaderModule: ShaderModule,
+  shaderSource: string,
+  log: any
+): void {
+  shaderModule.deprecations?.forEach(def => {
+    if (def.regex?.test(shaderSource)) {
+      if (def.deprecated) {
+        log.deprecated(def.old, def.new)();
+      } else {
+        log.removed(def.old, def.new)();
+      }
+    }
+  });
+}
+
+// HELPERS
+
+function parseDeprecationDefinitions(deprecations: ShaderModuleDeprecation[]) {
+  deprecations.forEach(def => {
+    switch (def.type) {
+      case 'function':
+        def.regex = new RegExp(`\\b${def.old}\\(`);
+        break;
+      default:
+        def.regex = new RegExp(`${def.type} ${def.old};`);
+    }
+  });
+
+  return deprecations;
 }

package/src/lib/shader-module/shader-pass.ts

@@ -5,8 +5,8 @@
 import type {ShaderModule, UniformValue} from './shader-module';
 
 /**
- * A shaderpass is a shader module with additional information
- * on how to run
+ * A ShaderPass is a ShaderModule that can be run "standalone" (e.g. post processing effects)
+ * It adds additional information on how to run the module in one or more passes.
  */
 export type ShaderPass<
   PropsT extends Record<string, unknown> = Record<string, unknown>,
@@ -15,6 +15,7 @@ export type ShaderPass<
   passes: ShaderPassData[];
 };
 
+/** Information on how to run a specific pass */
 type ShaderPassData = {
   sampler?: boolean;
   filter?: boolean;

package/src/module-injectors.ts

@@ -2,15 +2,13 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {glsl} from './lib/glsl-utils/highlight';
-
-export const MODULE_INJECTORS_VS = glsl`\
+export const MODULE_INJECTORS_VS = /* glsl */ `\
 #ifdef MODULE_LOGDEPTH
   logdepth_adjustPosition(gl_Position);
 #endif
 `;
 
-export const MODULE_INJECTORS_FS = glsl`\
+export const MODULE_INJECTORS_FS = /* glsl */ `\
 #ifdef MODULE_MATERIAL
   gl_FragColor = material_filterColor(gl_FragColor);
 #endif

package/src/modules/engine/geometry/geometry.ts

@@ -3,10 +3,9 @@
 // Copyright (c) vis.gl contributors
 
 // import {ShaderModule} from '../../types';
-import {glsl} from '../../../lib/glsl-utils/highlight';
 
 // TODO - reuse normal from geometry module
-const vs = glsl`\
+const vs = /* glsl */ `\
 varying vec4 geometry_vPosition;
 varying vec3 geometry_vNormal;
 
@@ -23,7 +22,7 @@ void geometry_setPosition(vec3 position) {
 }
 `;
 
-const fs = glsl`\
+const fs = /* glsl */ `\
 varying vec4 geometry_vPosition;
 varying vec3 geometry_vNormal;
 

package/src/modules/engine/picking/picking.ts

@@ -2,8 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {NumberArray} from '../../../types';
-import {glsl} from '../../../lib/glsl-utils/highlight';
+import {NumericArray} from '../../../types';
 import {ShaderModule} from '../../../lib/shader-module/shader-module';
 
 // cyan color
@@ -20,9 +19,9 @@ export type PickingProps = {
   /** Set to true when picking an attribute value instead of object index */
   isAttribute?: boolean;
   /** Set to a picking color to visually highlight that item, or `null` to explicitly clear **/
-  highlightedObjectColor?: NumberArray | null;
+  highlightedObjectColor?: NumericArray | null;
   /** Color of visual highlight of "selected" item */
-  highlightColor?: NumberArray;
+  highlightColor?: NumericArray;
   /** Color range 0-1 or 0-255 */
   useFloatColors?: boolean;
 };
@@ -45,12 +44,12 @@ export type PickingUniforms = {
   /** Do we have a highlighted item? */
   isHighlightActive?: boolean;
   /** Set to a picking color to visually highlight that item */
-  highlightedObjectColor?: NumberArray;
+  highlightedObjectColor?: NumericArray;
   /** Color of visual highlight of "selected" item */
-  highlightColor?: NumberArray;
+  highlightColor?: NumericArray;
 };
 
-const vs = glsl`\
+const vs = /* glsl */ `\
 uniform pickingUniforms {
   float isActive;
   float isAttribute;
@@ -124,7 +123,7 @@ void picking_setPickingAttribute(vec3 value) {
 }
 `;
 
-const fs = glsl`\
+const fs = /* glsl */ `\
 uniform pickingUniforms {
   float isActive;
   float isAttribute;
@@ -191,7 +190,11 @@ vec4 picking_filterColor(vec4 color) {
  * primitives with the same picking color in non-instanced draw-calls
  */
 export const picking = {
+  props: {} as PickingProps,
+  uniforms: {} as PickingUniforms,
+
   name: 'picking',
+
   uniformTypes: {
     isActive: 'f32',
     isAttribute: 'f32',
@@ -208,10 +211,9 @@ export const picking = {
     highlightedObjectColor: new Float32Array([0, 0, 0]),
     highlightColor: DEFAULT_HIGHLIGHT_COLOR
   },
+
   vs,
   fs,
-  props: {} as Required<PickingProps>,
-  uniforms: {} as PickingUniforms,
   getUniforms
 } as const satisfies ShaderModule<PickingProps, PickingUniforms>;
 

package/src/modules/engine/project/project.ts

@@ -4,7 +4,6 @@
 
 import {NumericArray as NumberArray, Matrix4, Vector3} from '@math.gl/core';
 import {ShaderModule} from '../../../lib/shader-module/shader-module';
-import {glsl} from '../../../lib/glsl-utils/highlight';
 
 const IDENTITY_MATRIX: Readonly<NumberArray> = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
 
@@ -70,7 +69,7 @@ function getUniforms(
  * @note varyings must match vertex shader
  * @note project module uses unprefixed uniforms to match conventions
  */
-const vs = glsl`\
+const vs = /* glsl */ `\
 varying vec4 project_vPositionWorld;
 varying vec3 project_vNormalWorld;
 
@@ -132,7 +131,7 @@ vec4 project_to_clipspace(vec3 position) {
  * Functions to get the position and normal from the vertex shader
  * @note varyings must match vertex shader
  */
-const fs = glsl`\
+const fs = /* glsl */ `\
 varying vec4 project_vPositionWorld;
 varying vec3 project_vNormalWorld;
 

package/src/modules/engine/transform/transform.ts

@@ -2,9 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {glsl} from '../../../lib/glsl-utils/highlight';
-
-const vs = glsl`\
+const vs = /* glsl */ `\
 attribute float transform_elementID;
 
 // returns half of pixel size, used to move the pixel position to center of the pixel.

package/src/modules/lighting/gouraud-material/gouraud-material.ts

@@ -18,6 +18,9 @@ export type GouraudMaterialUniforms = {
 
 /** In Gouraud shading, color is calculated for each triangle vertex normal, and then color is interpolated colors across the triangle */
 export const gouraudMaterial = {
+  props: {} as GouraudMaterialProps,
+  uniforms: {} as GouraudMaterialUniforms,
+
   name: 'gouraud-lighting',
   // Note these are switched between phong and gouraud
   vs: GOURAUD_VS,
@@ -38,6 +41,7 @@ export const gouraudMaterial = {
     shininess: 32,
     specularColor: [0.15, 0.15, 0.15]
   },
+
   getUniforms(props: GouraudMaterialProps): GouraudMaterialUniforms {
     return {...gouraudMaterial.defaultUniforms, ...props};
   }

package/src/modules/lighting/gouraud-material/gouraud-shaders-glsl.ts

@@ -2,9 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {glsl} from '../../../lib/glsl-utils/highlight';
-
-export const GOURAUD_VS = glsl`\
+export const GOURAUD_VS = /* glsl */ `\
 uniform materialUniforms {
   uniform float ambient;
   uniform float diffuse;
@@ -13,7 +11,7 @@ uniform materialUniforms {
 } material;
 `;
 
-export const GOURAUD_FS = glsl`\
+export const GOURAUD_FS = /* glsl */ `\
 uniform materialUniforms {
   uniform float ambient;
   uniform float diffuse;

package/src/modules/lighting/lights/lighting-uniforms-glsl.ts

@@ -2,9 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {glsl} from '../../../lib/glsl-utils/highlight';
-
-export const lightingUniforms = glsl`\
+export const lightingUniformsGLSL = /* glsl */ `\
 precision highp int;
 
 // #if (defined(SHADER_TYPE_FRAGMENT) && defined(LIGHTING_FRAGMENT)) || (defined(SHADER_TYPE_VERTEX) && defined(LIGHTING_VERTEX))

package/src/modules/lighting/lights/lighting-uniforms-wgsl.ts

@@ -0,0 +1,57 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export const lightingUniformsWGSL = /* wgsl */ `\
+// #if (defined(SHADER_TYPE_FRAGMENT) && defined(LIGHTING_FRAGMENT)) || (defined(SHADER_TYPE_VERTEX) && defined(LIGHTING_VERTEX))
+struct AmbientLight {
+  color: vec3<f32>,
+};
+
+struct PointLight {
+  color: vec3<f32>,
+  position: vec3<f32>,
+  attenuation: vec3<f32>, // 2nd order x:Constant-y:Linear-z:Exponential
+};
+
+struct DirectionalLight {
+  color: vec3<f32>,
+  direction: vec3<f32>,
+};
+
+struct lightingUniforms {
+  enabled: i32,
+  poightCount: i32,
+  directionalLightCount: i32,
+
+  ambientColor: vec3<f32>,
+
+  // TODO - support multiple lights by uncommenting arrays below
+  lightType: i32,
+  lightColor: vec3<f32>,
+  lightDirection: vec3<f32>,
+  lightPosition: vec3<f32>,
+  lightAttenuation: vec3<f32>,
+
+  // AmbientLight ambientLight;
+  // PointLight pointLight[MAX_LIGHTS];
+  // DirectionalLight directionalLight[MAX_LIGHTS];
+};
+
+// Binding 0:1 is reserved for lighting (Note: could go into separate bind group as it is stable across draw calls)
+@binding(1) @group(0) var<uniform> lighting : lightingUniforms;
+
+fn lighting_getPointLight(index: i32) -> PointLight {
+  return PointLight(lighting.lightColor, lighting.lightPosition, lighting.lightAttenuation);
+}
+
+fn lighting_getDirectionalLight(index: i32) -> DirectionalLight {
+  return DirectionalLight(lighting.lightColor, lighting.lightDirection);
+} 
+
+fn getPointLightAttenuation(pointLight: PointLight, distance: f32) -> f32 {
+  return pointLight.attenuation.x
+       + pointLight.attenuation.y * distance
+       + pointLight.attenuation.z * distance * distance;
+}
+`;

package/src/modules/lighting/lights/lighting.ts

@@ -4,7 +4,8 @@
 
 import type {NumberArray} from '@math.gl/types';
 import {ShaderModule} from '../../../lib/shader-module/shader-module';
-import {lightingUniforms} from './lighting-uniforms-glsl';
+import {lightingUniformsGLSL} from './lighting-uniforms-glsl';
+import {lightingUniformsWGSL} from './lighting-uniforms-wgsl';
 
 /** Max number of supported lights (in addition to ambient light */
 const MAX_LIGHTS = 5;
@@ -68,7 +69,11 @@ export type LightingUniforms = {
 
 /** UBO ready lighting module */
 export const lighting = {
+  props: {} as LightingProps,
+  uniforms: {} as LightingUniforms,
+
   name: 'lighting',
+
   defines: {
     MAX_LIGHTS
   },
@@ -96,11 +101,10 @@ export const lighting = {
     lightDirection: [1, 1, 1],
     lightAttenuation: [1, 1, 1]
   },
-  vs: lightingUniforms,
-  fs: lightingUniforms,
+  source: lightingUniformsWGSL,
+  vs: lightingUniformsGLSL,
+  fs: lightingUniformsGLSL,
 
-  props: {} as Required<LightingProps>,
-  uniforms: {} as LightingUniforms,
   getUniforms
 } as const satisfies ShaderModule<LightingProps, LightingUniforms>;
 

package/src/modules/lighting/no-material/dirlight.ts

@@ -2,37 +2,45 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {NumberArray} from '@math.gl/types';
-import {glsl} from '../../../lib/glsl-utils/highlight';
+import type {Vector3Like, TypedArray} from '@math.gl/core';
 import {ShaderModule} from '../../../lib/shader-module/shader-module';
 
 export type DirlightProps = {
-  lightDirection?: NumberArray | [number, number, number];
+  lightDirection?: Vector3Like | TypedArray;
 };
 
 export type DirlightUniforms = DirlightProps;
 
 // TODO
-export const VS_WGSL = /* WGSL */ `\  
-void dirlight_setNormal(normal: vec3<f32>) {
-  dirlight_vNormal = normalize(normal);
-}
-`;
+export const SOURCE_WGSL = /* WGSL */ `\  
+struct dirlightUniforms {
+  lightDirection: vec3<f32>,
+};
 
-// TODO
-export const FS_WGSL = /* WGSL */ `\
-uniform dirlightUniforms {
-  vec3 lightDirection;
-} dirlight;
+alias DirlightNormal = vec3<f32>;
+
+struct DirlightInputs {
+  normal: DirlightNormal,
+};
+
+@binding(1) @group(0) var<uniform> dirlight : dirlightUniforms;
+
+// For vertex
+fn dirlight_setNormal(normal: vec3<f32>) -> DirlightNormal {
+  return normalize(normal);
+}
 
 // Returns color attenuated by angle from light source
-fn dirlight_filterColor(color: vec4<f32>, dirlightInputs): vec4<f32> {
-  const d: float = abs(dot(dirlight_vNormal, normalize(dirlight.lightDirection)));
+fn dirlight_filterColor(color: vec4<f32>, inputs: DirlightInputs) -> vec4<f32> {
+  // TODO - fix default light direction
+  // let lightDirection = dirlight.lightDirection;
+  let lightDirection = vec3<f32>(1, 1, 1);
+  let d: f32 = abs(dot(inputs.normal, normalize(lightDirection)));
   return vec4<f32>(color.rgb * d, color.a);
 }
 `;
 
-const VS_GLSL = glsl`\
+const VS_GLSL = /* glsl */ `\
 out vec3 dirlight_vNormal;
 
 void dirlight_setNormal(vec3 normal) {
@@ -40,7 +48,7 @@ void dirlight_setNormal(vec3 normal) {
 }
 `;
 
-const FS_GLSL = glsl`\
+const FS_GLSL = /* glsl */ `\
 uniform dirlightUniforms {
   vec3 lightDirection;
 } dirlight;
@@ -58,10 +66,15 @@ vec4 dirlight_filterColor(vec4 color) {
  * Cheap lighting - single directional light, single dot product, one uniform
  */
 export const dirlight = {
+  props: {} as DirlightProps,
+  uniforms: {} as DirlightUniforms,
+
   name: 'dirlight',
   dependencies: [],
+  source: SOURCE_WGSL,
   vs: VS_GLSL,
   fs: FS_GLSL,
+
   // fragmentInputs: [
   //   {
   //     name: 'dirlight_vNormal',
@@ -74,8 +87,6 @@ export const dirlight = {
   defaultUniforms: {
     lightDirection: new Float32Array([1, 1, 2])
   },
-  props: {} as Required<DirlightProps>,
-  uniforms: {} as DirlightUniforms,
   getUniforms
 } as const satisfies ShaderModule<DirlightProps, DirlightUniforms>;
 

package/src/modules/lighting/pbr-material/pbr-fragment-glsl.ts

@@ -9,9 +9,8 @@
 // a microfacet surface material defined by a glTF model.
 
 // TODO - better do the checks outside of shader
-import {glsl} from '../../../lib/glsl-utils/highlight';
 
-export const fs = glsl`\
+export const fs = /* glsl */ `\
 precision highp float;
 
 uniform Projection {