Improve ShaderModule docs

docs/api-reference/shadertools/shader-module.md

@@ -10,14 +10,17 @@ For more information see [Shader Module System Guide](/docs/api-guide/shaders/sh
 To define a new shader module, you create a descriptor object that brings together all the necessary pieces:
 
 ```typescript
-export const MY_SHADER_MODULE = {
+type ModuleProps = {
+  radius: number;
+}
+
+export const MY_SHADER_MODULE: ShaderModule<ModuleProps> = {
   name: 'my-shader-module',
   vs: '...',
   fs: '...',
   inject: {},
   dependencies: [],
   deprecations: [],
-  getUniforms
 };
 ```
 
@@ -36,7 +39,15 @@ export const MY_SHADER_MODULE = {
 
 - `fs` - (string | null)
 
-#### `uniforms` (_Object_) 
+#### `uniformTypes` (_Object_) - Uniform shader types (note: both order and types MUST match uniform block declarations in shader)
+
+#### `uniformPropTypes` (_Object_) - Uniform JS prop types
+
+#### `defaultUniforms` (_Object_) - Default uniform values
+
+#### `getUniforms` (_function_) - Function that maps props to uniforms & bindings. When not provided it is assumed that the names of the uniforms and bindings match those of the provided props
+
+#### `defines` (_Object_) - Constant defines to be injected into shader
 
 #### `inject` (_Object_) - injections the module will make into shader hooks, see below
 
@@ -52,33 +63,36 @@ If `deprecations` is supplied, `assembleShaders` will scan shader source code fo
 - `deprecated`: whether the old API is still supported.
 
 
-### Defining Uniforms
+### Statically defining Uniforms
 
-If the uniforms of this module can be directly pulled from user settings, they may declaratively defined by a `uniforms` object:
+If the uniforms of this module can be directly pulled from user props, they may declaratively defined by a `defaultUniforms` object:
 
 ```typescript
 {
   name: 'my-shader-module',
-  uniforms: {
-    strength: {type: 'number', value: 1, min: 0, max: 1},
-    center: [0.5, 0.5]
-  }
+  defaultUniforms: {center: [0.5, 0.5], strength: 0.9},
+  uniformTypes: {center: 'vec2<f32>' strength: 'f32'}
 }
 ```
 
-At runtime, this map will be used to generate the uniforms needed by the shaders. If either `strength` or `center` is present in the user's module settings, then the user's value will be used; otherwise, the default value in the original definition will be used.
-
-Each uniform definition may contain the following fields:
+At runtime, this map will be used to generate the uniforms needed by the shaders. If either `strength` or `center` is present in the user's module props, then the user's value will be used; otherwise, the default value in the original definition will be used.
 
-- `type` (string `number`, `boolean`, `array` or `object`
-- `value` - the default value of this uniform
+### Dynamically defining Uniforms
 
-With `type: 'number'`, the following additional fields may be added for validation:
+The shader module may want to perform more complex logic when mapping the user' module props to uniforms. This can be achieved using `getUniforms()`:
 
-- `min` (_Number_)
-- `max` (_Number_)
-
-Note: `uniforms` is ignored if `getUniforms` is provided.
+```typescript
+{
+  name: 'my-shader-module',
+  uniformTypes: {center: 'vec2<f32>' strength: 'f32'}
+  getUniforms(({intensity}) => {
+    return {
+      strength: Math.sqrt(intensity),
+      center: intensity > 0 ? [0.5, 0.5] : [0, 0]
+    }
+  }
+}
+```
 
 ## Defining Injections
 
@@ -111,7 +125,7 @@ getShaderModuleUniforms(module: ShaderModule)
 
 Each shader module provides a method to get a map of uniforms for the shader. This function will be called with two arguments:
 
-- `opts` - the module settings to update. This argument may not be provided when `getUniforms` is called to generate a set of default uniform values.
+- `opts` - the module props to update. This argument may not be provided when `getUniforms` is called to generate a set of default uniform values.
 - `context` - the uniforms generated by this module's dependencies.
 
 The function should return a JavaScript object with keys representing uniform names and values representing uniform values.

modules/shadertools/src/lib/shader-module/shader-module.ts

@@ -18,6 +18,7 @@ export type UniformInfo = {
 
 /**
  * A shader module definition object
+ *
  * @note Needs to be initialized with `initializeShaderModules`
  */
 export type ShaderModule<
@@ -46,9 +47,8 @@ export type ShaderModule<
   /** Default uniform values */
   defaultUniforms?: Required<UniformsT>; // Record<keyof UniformsT, UniformValue>;
 
-  /** Function that maps settings to uniforms & bindings */
-  // 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, UniformValue>;
 
   /** uniform buffers, textures, samplers, storage, ... */
   bindings?: Record<keyof BindingsT, {location: number; type: 'texture' | 'sampler' | 'uniforms'}>;