@luma.gl/shaders 10.0.0-alpha.5 → 10.0.0-alpha.7

package/src/lib/shader-plugin.ts

@@ -21,131 +21,135 @@ export type ShaderPluginInjectionTarget =
 export type ShaderPluginInjection = {
   /** Named shader anchor or hook that receives this source. */
   target: ShaderPluginInjectionTarget;
-  /** Shader source to inject at the target. */
-  injection: string;
+  /** GLSL source for this target. Omit to skip this injection when assembling GLSL. */
+  glsl?: string;
+  /** WGSL source for this target. Omit to skip this injection when assembling WGSL. */
+  wgsl?: string;
   /** Relative injection order within the target. */
   order?: number;
 };
 
-/** Portable interpolation modes for ShaderPlugin varyings. */
-export type ShaderPluginVaryingInterpolation = 'smooth' | 'flat';
+/** Portable interpolation modes for ShaderPlugin inter-stage variables. */
+export type ShaderPluginInterStageVariableInterpolation = 'smooth' | 'flat';
 
 /** Cross-stage value contributed by a ShaderPlugin. */
-export type ShaderPluginVarying = {
+export type ShaderPluginInterStageVariable = {
   /** Portable scalar or vector shader type. */
   type: AttributeShaderType;
   /** Defaults to smooth for floating-point types and flat for integer types. */
-  interpolation?: ShaderPluginVaryingInterpolation;
+  interpolation?: ShaderPluginInterStageVariableInterpolation;
 };
 
-/** Fully normalized ShaderPlugin varying declaration. */
-export type ResolvedShaderPluginVarying = {
+/** Fully normalized ShaderPlugin inter-stage variable declaration. */
+export type ResolvedShaderPluginInterStageVariable = {
   type: AttributeShaderType;
-  interpolation: ShaderPluginVaryingInterpolation;
+  interpolation: ShaderPluginInterStageVariableInterpolation;
 };
 
-/** Shared or backend-specific shader assembly contributions. */
-export type ShaderPluginVariant = {
-  /** Shader modules added to shader assembly. */
-  modules?: ShaderModule[];
-  /** Boolean preprocessor defines added to shader assembly. */
-  defines?: Record<string, boolean>;
+/** Reusable shader assembly descriptor with one portable interface and language-specific source. */
+export type ShaderPlugin = {
+  /** Stable plugin identifier. */
+  name: string;
+  /** Primary shader module. Supporting modules belong in its dependencies; omit for injection-only plugins. */
+  module?: ShaderModule<any, any, any>;
+  /** Boolean or numeric preprocessor defines added to shader assembly. */
+  defines?: Record<string, boolean | number>;
   /** Named code injections added to shader assembly. */
   injections?: ShaderPluginInjection[];
   /** Shader-facing vertex inputs added by this plugin. Buffer ownership remains with the caller. */
   vertexInputs?: Record<string, AttributeShaderType>;
   /** Values transported from the selected vertex entry point to the fragment entry point. */
-  varyings?: Record<string, ShaderPluginVarying>;
-};
-
-/** Reusable cross-backend shader assembly descriptor. */
-export type ShaderPlugin = ShaderPluginVariant & {
-  /** Stable plugin identifier. */
-  name: string;
-  /** GLSL-only shader assembly contributions. */
-  glsl?: ShaderPluginVariant;
-  /** WGSL-only shader assembly contributions. */
-  wgsl?: ShaderPluginVariant;
+  interStageVariables?: Record<string, ShaderPluginInterStageVariable>;
 };
 
 /** ShaderPlugin contributions resolved for one shader language. */
 export type ResolvedShaderPlugins = {
   /** Resolved shader modules in plugin declaration order. */
   modules: ShaderModule[];
-  /** Resolved boolean preprocessor defines. */
-  defines: Record<string, boolean>;
+  /** Resolved boolean or numeric preprocessor defines. */
+  defines: Record<string, boolean | number>;
   /** Resolved named code injections grouped by target. */
   injections: Record<string, ShaderInjection[]>;
   /** Resolved shader-facing vertex inputs in plugin declaration order. */
   vertexInputs: Record<string, AttributeShaderType>;
-  /** Resolved cross-stage varyings in plugin declaration order. */
-  varyings: Record<string, ResolvedShaderPluginVarying>;
+  /** Resolved inter-stage variables in plugin declaration order. */
+  interStageVariables: Record<string, ResolvedShaderPluginInterStageVariable>;
 };
 
 const SHADER_PLUGIN_INJECTION_TARGET_REGEX =
   /^(vs|fs):(?:#(?:decl|main-start|main-end)|[A-Za-z_][\w-]*)$/;
 
-/** Resolve shared and backend-specific contributions from shader plugins. */
+/** Resolve plugin interfaces and select injection source for one shader language. */
 export function resolveShaderPlugins(
   plugins: readonly ShaderPlugin[] = [],
   shaderLanguage: 'glsl' | 'wgsl'
 ): ResolvedShaderPlugins {
-  const modules: ShaderModule[] = [];
-  const defines: Record<string, boolean> = {};
-  const injections: Record<string, ShaderInjection[]> = {};
-  const vertexInputs: Record<string, AttributeShaderType> = {};
-  const varyings: Record<string, ResolvedShaderPluginVarying> = {};
+  const resolved: ResolvedShaderPlugins = {
+    modules: [],
+    defines: {},
+    injections: {},
+    vertexInputs: {},
+    interStageVariables: {}
+  };
 
   for (const plugin of plugins) {
-    appendShaderPluginVariant({modules, defines, injections, vertexInputs, varyings}, plugin);
-    appendShaderPluginVariant(
-      {modules, defines, injections, vertexInputs, varyings},
-      plugin[shaderLanguage]
-    );
+    appendShaderPlugin(resolved, plugin, shaderLanguage);
   }
+  const {vertexInputs, interStageVariables} = resolved;
 
-  for (const name of Object.keys(varyings)) {
+  for (const name of Object.keys(interStageVariables)) {
     if (vertexInputs[name]) {
       throw new Error(`ShaderPlugin name "${name}" cannot be both a vertex input and a varying`);
     }
   }
 
-  return {modules, defines, injections, vertexInputs, varyings};
+  return resolved;
 }
 
-/** Preserve explicit module inputs while appending plugin modules by first-seen name. */
+/**
+ * Preserve explicit module inputs while appending plugin modules by first-seen name.
+ * Optional diagnostics report distinct descriptors sharing a name, without changing selection.
+ * Descriptor identity is checked; equivalent independently-created descriptors also report a conflict.
+ */
 export function mergeShaderPluginModules(
   modules: readonly ShaderModule[] = [],
-  pluginModules: readonly ShaderModule[] = []
+  pluginModules: readonly ShaderModule[] = [],
+  options: {onConflict?: (name: string, selected: ShaderModule, ignored: ShaderModule) => void} = {}
 ): ShaderModule[] {
   const mergedModules: ShaderModule[] = [...modules];
-  const seenModuleNames = new Set(mergedModules.map(module => module.name));
+  const selectedModules = new Map<string, ShaderModule>();
+  for (const module of mergedModules) {
+    const selected = selectedModules.get(module.name);
+    if (selected && selected !== module) options.onConflict?.(module.name, selected, module);
+    if (!selected) selectedModules.set(module.name, module);
+  }
 
   for (const pluginModule of pluginModules) {
-    if (!seenModuleNames.has(pluginModule.name)) {
+    const selected = selectedModules.get(pluginModule.name);
+    if (selected && selected !== pluginModule) {
+      options.onConflict?.(pluginModule.name, selected, pluginModule);
+    }
+    if (!selected) {
       mergedModules.push(pluginModule);
-      seenModuleNames.add(pluginModule.name);
+      selectedModules.set(pluginModule.name, pluginModule);
     }
   }
 
   return mergedModules;
 }
 
-function appendShaderPluginVariant(
+function appendShaderPlugin(
   resolved: ResolvedShaderPlugins,
-  variant: ShaderPluginVariant | undefined
+  plugin: ShaderPlugin,
+  shaderLanguage: 'glsl' | 'wgsl'
 ): void {
-  if (!variant) {
-    return;
-  }
-
-  if (variant.modules?.length) {
-    resolved.modules.push(...variant.modules);
+  if (plugin.module) {
+    resolved.modules.push(plugin.module);
   }
-  if (variant.defines) {
-    Object.assign(resolved.defines, variant.defines);
+  if (plugin.defines) {
+    Object.assign(resolved.defines, plugin.defines);
   }
-  for (const [name, type] of Object.entries(variant.vertexInputs || {})) {
+  for (const [name, type] of Object.entries(plugin.vertexInputs || {})) {
     assertShaderPluginInterfaceName(name, 'vertex input');
     const existingType = resolved.vertexInputs[name];
     if (existingType && existingType !== type) {
@@ -155,10 +159,10 @@ function appendShaderPluginVariant(
     }
     resolved.vertexInputs[name] = type;
   }
-  for (const [name, varying] of Object.entries(variant.varyings || {})) {
+  for (const [name, varying] of Object.entries(plugin.interStageVariables || {})) {
     assertShaderPluginInterfaceName(name, 'varying');
-    const normalizedVarying = normalizeShaderPluginVarying(name, varying);
-    const existingVarying = resolved.varyings[name];
+    const normalizedVarying = normalizeShaderPluginInterStageVariable(name, varying);
+    const existingVarying = resolved.interStageVariables[name];
     if (
       existingVarying &&
       (existingVarying.type !== normalizedVarying.type ||
@@ -170,17 +174,20 @@ function appendShaderPluginVariant(
           `"${normalizedVarying.type}/${normalizedVarying.interpolation}"`
       );
     }
-    resolved.varyings[name] = normalizedVarying;
+    resolved.interStageVariables[name] = normalizedVarying;
   }
 
-  for (const injection of variant.injections || []) {
+  for (const injection of plugin.injections || []) {
+    const source = injection[shaderLanguage];
+    if (source === undefined) continue;
     assertNamedShaderPluginInjectionTarget(injection.target);
     if (!resolved.injections[injection.target]) {
       resolved.injections[injection.target] = [];
     }
     const injections = resolved.injections[injection.target];
     injections.push({
-      injection: injection.injection,
+      pluginName: plugin.name,
+      injection: source,
       order: injection.order ?? 0
     });
   }
@@ -192,10 +199,10 @@ function assertShaderPluginInterfaceName(name: string, kind: 'vertex input' | 'v
   }
 }
 
-function normalizeShaderPluginVarying(
+function normalizeShaderPluginInterStageVariable(
   name: string,
-  varying: ShaderPluginVarying
-): ResolvedShaderPluginVarying {
+  varying: ShaderPluginInterStageVariable
+): ResolvedShaderPluginInterStageVariable {
   const {primitiveType} = shaderTypeDecoder.getAttributeShaderTypeInfo(varying.type);
   const integerType = primitiveType === 'i32' || primitiveType === 'u32';
   const interpolation = varying.interpolation || (integerType ? 'flat' : 'smooth');

package/src/lib/wgsl-shader-assembler.ts

@@ -36,7 +36,7 @@ export class WGSLShaderAssembler extends ShaderAssembler {
     entryPoints: ShaderTranspilerEntryPoints;
   } {
     const modules = this._getModuleList(props.modules); // Combine with default modules
-    const hookFunctions = this._hookFunctions; // TODO - combine with default hook functions
+    const hookFunctions = [...this._hookFunctions, ...(props.hookFunctions || [])];
     const translated = this._transpileShader(
       props,
       modules,

package/src/modules/engine/clip/clip.ts

@@ -100,50 +100,38 @@ fn clip_isInBounds(coordinates: vec2<f32>) -> bool {
 /** Coordinate-system-neutral instance and geometry clipping. */
 export const clipShaderPlugin: ShaderPlugin = {
   name: 'clip',
-  modules: [clipShaderModule],
-  varyings: {
+  module: clipShaderModule,
+  interStageVariables: {
     clipCoordinates: {type: 'vec2<f32>', interpolation: 'smooth'}
   },
-  glsl: {
-    injections: [
-      {
-        target: 'vs:CLIP_POSITION',
-        injection: `\
+  injections: [
+    {
+      target: 'vs:CLIP_POSITION',
+      glsl: `\
 clipCoordinates = geometryCoordinates;
 if (clipState.enabled != 0 && clipState.mode == ${CLIP_MODE_INSTANCE} &&
     !clip_isInBounds(instanceCoordinates)) {
   position = vec4(2.0, 2.0, 2.0, 1.0);
-}`
-      },
-      {
-        target: 'fs:CLIP_COLOR',
-        injection: `\
-if (clipState.enabled != 0 && clipState.mode == ${CLIP_MODE_GEOMETRY} &&
-    !clip_isInBounds(clipCoordinates)) {
-  discard;
-}`
-      }
-    ]
-  },
-  wgsl: {
-    injections: [
-      {
-        target: 'vs:CLIP_POSITION',
-        injection: `\
+}`,
+      wgsl: `\
 clipCoordinates = geometryCoordinates;
 if (clipUniforms.enabled != 0 && clipUniforms.mode == ${CLIP_MODE_INSTANCE} &&
     !clip_isInBounds(instanceCoordinates)) {
   *position = vec4<f32>(2.0, 2.0, 2.0, 1.0);
 }`
-      },
-      {
-        target: 'fs:CLIP_COLOR',
-        injection: `\
+    },
+    {
+      target: 'fs:CLIP_COLOR',
+      glsl: `\
+if (clipState.enabled != 0 && clipState.mode == ${CLIP_MODE_GEOMETRY} &&
+    !clip_isInBounds(clipCoordinates)) {
+  discard;
+}`,
+      wgsl: `\
 if (clipUniforms.enabled != 0 && clipUniforms.mode == ${CLIP_MODE_GEOMETRY} &&
     !clip_isInBounds(clipCoordinates)) {
   discard;
 }`
-      }
-    ]
-  }
+    }
+  ]
 };

package/src/modules/engine/filter/filter.ts

@@ -78,30 +78,21 @@ fn filter_isVisible(value: f32) -> bool {
 /** Scalar inclusive-range filtering for shaders that expose the `FILTER_POSITION` vertex hook. */
 export const filterShaderPlugin: ShaderPlugin = {
   name: 'filter',
-  modules: [filterShaderModule],
+  module: filterShaderModule,
   vertexInputs: {
     filterValues: 'f32'
   },
-  glsl: {
-    injections: [
-      {
-        target: 'vs:FILTER_POSITION',
-        injection: `\
+  injections: [
+    {
+      target: 'vs:FILTER_POSITION',
+      glsl: `\
 if (!filter_isVisible(filterValues)) {
   position = vec4(2.0, 2.0, 2.0, 1.0);
-}`
-      }
-    ]
-  },
-  wgsl: {
-    injections: [
-      {
-        target: 'vs:FILTER_POSITION',
-        injection: `\
+}`,
+      wgsl: `\
 if (!filter_isVisible(filterValues)) {
   *position = vec4<f32>(2.0, 2.0, 2.0, 1.0);
 }`
-      }
-    ]
-  }
+    }
+  ]
 };

package/src/modules/math/fp64/fp64.ts

@@ -4,7 +4,7 @@
 
 import {ShaderModule} from '../../../lib/shader-module/shader-module';
 
-import {fp64ify, fp64LowPart, fp64ifyMatrix4} from '../../../modules/math/fp64/fp64-utils';
+import {fp64ify, fp64LowPart, fp64ifyMatrix4} from './fp64-utils';
 import {fp64arithmeticShader} from './fp64-arithmetic-glsl';
 import {fp64arithmeticWGSL} from './fp64-arithmetic-wgsl';
 import {fp64functionShader} from './fp64-functions-glsl';

package/src/types.ts

@@ -35,13 +35,81 @@ export type UniformFormat =
   | 'mat4x3<f32>'
   | 'mat4x4<f32>';
 
-export * from './types/primitive-data-types';
-export * from './types/shader-types';
-export * from './types/shader-type-decoder';
-export * from './types/shader-block-layout';
-export * from './types/shader-layout';
-export * from './types/texture-formats';
-export * from './types/sampler-props';
+export {type PrimitiveDataType} from './types/primitive-data-types';
+export {
+  type AttributeShaderType,
+  type VariableShaderType,
+  type CompositeShaderType,
+  type StructShaderType,
+  type ArrayShaderType,
+  type AttributeShaderTypeAlias,
+  type VariableShaderTypeAlias,
+  type AttributeShaderTypeT,
+  type VariableShaderTypeT,
+  type AttributeShaderTypeAliasT,
+  type VariableShaderTypeAliasT
+} from './types/shader-types';
+export {
+  getVariableShaderTypeInfo,
+  getAttributeShaderTypeInfo,
+  makeShaderAttributeType,
+  resolveAttributeShaderTypeAlias,
+  resolveVariableShaderTypeAlias,
+  type VariableShaderTypeInfo,
+  type AttributeShaderTypeInfo,
+  ShaderTypeDecoder,
+  shaderTypeDecoder,
+  WGSL_ATTRIBUTE_TYPE_ALIAS_MAP,
+  WGSL_VARIABLE_TYPE_ALIAS_MAP
+} from './types/shader-type-decoder';
+export {
+  makeShaderBlockLayout,
+  getLeafLayoutInfo,
+  isCompositeShaderTypeStruct,
+  type ShaderBlockLayoutEntry,
+  type ShaderBlockLayoutOptions,
+  type ShaderBlockLayout
+} from './types/shader-block-layout';
+export {
+  type ShaderLayout,
+  type ComputeShaderLayout,
+  type AttributeDeclaration,
+  type BindingDeclaration,
+  type UniformBufferBindingLayout,
+  type UniformBlockLayout,
+  type UniformInfo,
+  type StorageBufferBindingLayout,
+  type TextureBindingLayout,
+  type ExternalTextureBindingLayout,
+  type SamplerBindingLayout,
+  type StorageTextureBindingLayout,
+  type VaryingBinding,
+  type UniformBlockBinding,
+  type UniformBinding
+} from './types/shader-layout';
+export {
+  type TextureFormat,
+  type TextureFormatDepthStencil,
+  type TextureFormatColor,
+  type TextureFormatColorUncompressed,
+  type TextureFormatUnorm8,
+  type TextureFormatSnorm8,
+  type TextureFormatUint8,
+  type TextureFormatSint8,
+  type TextureFormatUnorm16,
+  type TextureFormatSnorm16,
+  type TextureFormatUint16,
+  type TextureFormatSint16,
+  type TextureFormatFloat16,
+  type TextureFormatUint32,
+  type TextureFormatSint32,
+  type TextureFormatFloat32,
+  type TextureFormatPacked16,
+  type TextureFormatPacked32,
+  type TextureFormatCompressed,
+  type CompressedTextureFormat
+} from './types/texture-formats';
+export {type CompareFunction, type SamplerProps} from './types/sampler-props';
 export {alignTo} from './types/align-to';
 
 /** Resource values remain opaque until an execution adapter binds them. */

package/src/wgsl.ts

@@ -20,4 +20,15 @@ export {
   type ShaderBindingDebugRow
 } from './lib/shader-assembly/wgsl-binding-debug';
 
-export * from './lib/shader-assembly/wgsl-binding-scan';
+export {
+  maskWGSLComments,
+  getWGSLBindingDeclarationMatches,
+  replaceWGSLBindingDeclarationMatches,
+  hasWGSLAutoBinding,
+  getFirstWGSLAutoBindingDeclarationMatch,
+  WGSL_BINDABLE_VARIABLE_PATTERN,
+  MODULE_WGSL_BINDING_DECLARATION_REGEXES,
+  WGSL_BINDING_DECLARATION_REGEXES,
+  WGSL_EXPLICIT_BINDING_DECLARATION_REGEXES,
+  type WGSLBindingDeclarationMatch
+} from './lib/shader-assembly/wgsl-binding-scan';