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

package/src/lib/shader-assembly/assemble-wgsl-shaders.ts

@@ -27,13 +27,12 @@ import {assert} from '../utils/assert';
 import {preprocess} from '../preprocessor/preprocessor';
 import {assembleShaderPluginVertexInputsWGSL} from './shader-plugin-vertex-inputs';
 import {assembleShaderPluginInterStageVariablesWGSL} from './shader-plugin-varyings';
+import {normalizeShaderHooks, validateShaderHookInjections, getShaderHooks} from './shader-hooks';
 import {
-  normalizeShaderHooks,
-  validateShaderHookInjections,
-  isShaderHookRegistered,
-  getShaderHooks
-} from './shader-hooks';
-import {type ShaderInjection, injectShader} from './shader-injections';
+  type ResolvedShaderInjection,
+  injectShader,
+  resolveShaderInjections
+} from './shader-injections';
 import {checkShaderModuleDeprecations, type ShaderModule} from '../shader-module/shader-module';
 import {
   getWGSLBindingDeclarationMatches,
@@ -159,18 +158,27 @@ export function assembleShaderWGSL(
   // `
   // `;
 
-  const hookFunctionMap = normalizeShaderHooks(hookFunctions);
+  const hookFunctionMap = normalizeShaderHooks(hookFunctions, options.pluginHooks, 'wgsl');
 
   // Add source of dependent modules in resolved order
-  const hookInjections: Record<string, ShaderInjection[]> = {};
-  const declInjections: Record<string, ShaderInjection[]> = {};
-  const mainInjections: Record<string, ShaderInjection[]> = {};
+  const hookInjections: Record<string, ResolvedShaderInjection[]> = {};
+  const declInjections: Record<string, ResolvedShaderInjection[]> = {};
+  const mainInjections: Record<string, ResolvedShaderInjection[]> = {};
 
   appendInjections(pluginInjections, hookInjections, declInjections, mainInjections);
 
-  for (const key in inject) {
-    const injection: ShaderInjection =
-      typeof inject[key] === 'string' ? {injection: inject[key], order: 0} : inject[key];
+  const applicationInjections = Array.isArray(inject)
+    ? resolveShaderInjections(inject, 'wgsl')
+    : {};
+  appendInjections(applicationInjections, hookInjections, declInjections, mainInjections);
+  const injectionMap = Array.isArray(inject)
+    ? {}
+    : (inject as Record<string, string | ResolvedShaderInjection>);
+  for (const key in injectionMap) {
+    const injection: ResolvedShaderInjection =
+      typeof injectionMap[key] === 'string'
+        ? {injection: injectionMap[key], order: 0}
+        : injectionMap[key];
     const match = /^(v|f)s:(#)?([\w-]+)$/.exec(key);
     if (match) {
       const hash = match[2];
@@ -232,22 +240,6 @@ export function assembleShaderWGSL(
       checkShaderModuleDeprecations(module, coreSource, log);
     }
     assembledSource += moduleSource;
-
-    const injections = getWGSLModuleInjections(module);
-    for (const key in injections) {
-      const match = /^(v|f)s:#([\w-]+)$/.exec(key);
-      if (match) {
-        const name = match[2];
-        const injectionType = name === 'decl' ? declInjections : mainInjections;
-        injectionType[key] = injectionType[key] || [];
-        injectionType[key].push(injections[key]);
-      } else if (isShaderHookRegistered(hookFunctionMap, key)) {
-        // `ShaderModule.inject` is not language-specific and often carries GLSL-only hook
-        // injections, so WGSL silently skips module injections into hooks it has not declared.
-        hookInjections[key] = hookInjections[key] || [];
-        hookInjections[key].push(injections[key]);
-      }
-    }
   }
 
   // For injectShader
@@ -282,8 +274,8 @@ export function assembleShaderWGSL(
 export function appendGeneratedVertexInputInjections(
   declarations: string,
   initialization: string,
-  declarationInjections: Record<string, ShaderInjection[]>,
-  mainInjections: Record<string, ShaderInjection[]>
+  declarationInjections: Record<string, ResolvedShaderInjection[]>,
+  mainInjections: Record<string, ResolvedShaderInjection[]>
 ): void {
   if (declarations) {
     declarationInjections['vs:#decl'] = declarationInjections['vs:#decl'] || [];
@@ -307,8 +299,8 @@ export function appendGeneratedVaryingInjections(
     vertexInitialization: string;
     fragmentInitialization: string;
   },
-  declarationInjections: Record<string, ShaderInjection[]>,
-  mainInjections: Record<string, ShaderInjection[]>
+  declarationInjections: Record<string, ResolvedShaderInjection[]>,
+  mainInjections: Record<string, ResolvedShaderInjection[]>
 ): void {
   if (assembly.declarations) {
     declarationInjections['vs:#decl'] = declarationInjections['vs:#decl'] || [];
@@ -333,16 +325,9 @@ export function appendGeneratedVaryingInjections(
   }
 }
 
-export function getWGSLModuleInjections(module: ShaderModule): Record<string, ShaderInjection> {
-  return {
-    ...(module.instance?.normalizedInjections.vertex || {}),
-    ...(module.instance?.normalizedInjections.fragment || {})
-  };
-}
-
 export function getWGSLDeclarationInjections(
-  declarationInjections: Record<string, ShaderInjection[]>
-): Record<string, ShaderInjection[]> {
+  declarationInjections: Record<string, ResolvedShaderInjection[]>
+): Record<string, ResolvedShaderInjection[]> {
   const unifiedDeclarations = [
     ...(declarationInjections['vs:#decl'] || []),
     ...(declarationInjections['fs:#decl'] || [])
@@ -353,7 +338,7 @@ export function getWGSLDeclarationInjections(
 
 export function getWGSLShaderHooks(
   hookFunctionMap: ReturnType<typeof normalizeShaderHooks>,
-  hookInjections: Record<string, ShaderInjection[]>
+  hookInjections: Record<string, ResolvedShaderInjection[]>
 ): string {
   return (
     getShaderHooks(hookFunctionMap.vertex, hookInjections, 'wgsl') +

package/src/lib/shader-assembly/shader-assembly-shared.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import {DECLARATION_INJECT_MARKER, type ShaderInjection} from './shader-injections';
+import {DECLARATION_INJECT_MARKER, type ResolvedShaderInjection} from './shader-injections';
 import {type ShaderModule} from '../shader-module/shader-module';
 import {assert} from '../utils/assert';
 import {validateShaderModuleUniformLayout} from '../shader-module/shader-module-uniform-layout';
@@ -31,10 +31,10 @@ export function assembleGetUniforms(modules: ShaderModule[]) {
 }
 
 export function appendInjections(
-  injections: Record<string, ShaderInjection[]>,
-  hookInjections: Record<string, ShaderInjection[]>,
-  declInjections: Record<string, ShaderInjection[]>,
-  mainInjections: Record<string, ShaderInjection[]>
+  injections: Record<string, ResolvedShaderInjection[]>,
+  hookInjections: Record<string, ResolvedShaderInjection[]>,
+  declInjections: Record<string, ResolvedShaderInjection[]>,
+  mainInjections: Record<string, ResolvedShaderInjection[]>
 ): void {
   for (const key in injections) {
     const match = /^(v|f)s:(#)?([\w-]+)$/.exec(key);

package/src/lib/shader-assembly/shader-assembly-types.ts

@@ -5,7 +5,7 @@
 import {type PlatformInfo} from './platform-info';
 import {type ShaderModule} from '../shader-module/shader-module';
 import {type ShaderHook} from './shader-hooks';
-import {type ShaderInjection} from './shader-injections';
+import {type ShaderInjection, type ResolvedShaderInjection} from './shader-injections';
 import {type AttributeShaderType} from '../../types';
 import {type ResolvedShaderPluginInterStageVariable} from '../shader-plugin';
 
@@ -45,11 +45,13 @@ export type AssembleShaderOptions = {
   /** GLSL only: Overrides to be injected. In WGSL these are supplied during Pipeline creation time */
   constants?: Record<string, number>;
   /** Per-call hooks, appended after registered assembler hooks; matching names override for this call. */
-  hookFunctions?: readonly (ShaderHook | string)[];
+  hookFunctions?: readonly ShaderHook[];
+  /** Hook declarations contributed by resolved plugins. */
+  pluginHooks?: readonly ShaderHook[];
   /** Code injections */
-  inject?: Record<string, string | ShaderInjection>;
+  inject?: readonly ShaderInjection[] | Record<string, string | ResolvedShaderInjection>;
   /** Ordered code injections contributed by ShaderPlugin descriptors. */
-  pluginInjections?: Record<string, ShaderInjection[]>;
+  pluginInjections?: Record<string, ResolvedShaderInjection[]>;
   /** Vertex inputs contributed by ShaderPlugin descriptors. */
   pluginVertexInputs?: Record<string, AttributeShaderType>;
   /** Inter-stage variables contributed by ShaderPlugin descriptors. */
@@ -79,11 +81,13 @@ export type AssembleStageOptions = {
   /** GLSL only: Overrides to be injected. In WGSL these are supplied during Pipeline creation time */
   constants?: Record<string, number>;
   /** Per-call hooks, appended after registered assembler hooks; matching names override for this call. */
-  hookFunctions?: readonly (ShaderHook | string)[];
+  hookFunctions?: readonly ShaderHook[];
+  /** Hook declarations contributed by resolved plugins. */
+  pluginHooks?: readonly ShaderHook[];
   /** Code injections */
-  inject?: Record<string, string | ShaderInjection>;
+  inject?: readonly ShaderInjection[] | Record<string, string | ResolvedShaderInjection>;
   /** Ordered code injections contributed by ShaderPlugin descriptors. */
-  pluginInjections?: Record<string, ShaderInjection[]>;
+  pluginInjections?: Record<string, ResolvedShaderInjection[]>;
   /** Vertex inputs contributed by ShaderPlugin descriptors. */
   pluginVertexInputs?: Record<string, AttributeShaderType>;
   /** Inter-stage variables contributed by ShaderPlugin descriptors. */

package/src/lib/shader-assembly/shader-hooks.ts

@@ -2,51 +2,57 @@
 // SPDX-License-Identifier: MIT
 // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import type {ShaderInjection} from './shader-injections';
+import type {ResolvedShaderInjection} from './shader-injections';
 
-/**
- * The shader hook mechanism allows the application to create shaders
- * that can be automatically extended by the shader modules the application
- * includes.
- *
- * A shader hook function that shader modules can inject code into.
- * Shaders can call these functions, which will be no-ops by default.
- *
- * If a shader module injects code it will be executed upon the hook
- * function call.
- */
-export type ShaderHook = {
-  /** `vs:` or `fs:` followed by the name and arguments of the function, e.g. `vs:MYHOOK_func(inout vec4 value)`. Hook name without arguments
-  will also be used as the name of the shader hook */
-  hook: string;
-  /** Code always included at the beginning of a hook function */
+/** Language-specific source for a callable shader hook. */
+export type ShaderHookImplementation = {
+  /** Function parameters in the selected shader language, without parentheses. */
+  parameters: string;
+  /** Return type in this language. Omit for a hook that returns no value. */
+  returnType?: string;
+  /** Source included before injected code. */
   header?: string;
-  /** Code always included at the end of a hook function */
+  /** Source included after injected code. */
   footer?: string;
-  /** To Be Documented */
-  signature?: string;
 };
 
-/** Optional source included before or after every injection in a hook function. */
-export type ShaderHookOptions = Pick<ShaderHook, 'header' | 'footer'>;
+/** One logical extension point with independent GLSL and WGSL syntax. */
+export type ShaderHook = {
+  /** Function name shared by both shader languages. */
+  name: string;
+  /** Shader stage that owns the hook. */
+  stage: 'vertex' | 'fragment';
+  /** GLSL implementation. Omit to skip this hook during GLSL assembly. */
+  glsl?: ShaderHookImplementation;
+  /** WGSL implementation. Omit to skip this hook during WGSL assembly. */
+  wgsl?: ShaderHookImplementation;
+};
+
+/** Language-selected hook ready for source generation. */
+type ResolvedShaderHook = ShaderHookImplementation & {signature: string};
 
-/** Shader hook declarations grouped by shader stage. */
+/** Normalized shader hooks per shader */
 export type ShaderHookRegistry = {
-  vertex: Record<string, Required<ShaderHook>>;
-  fragment: Record<string, Required<ShaderHook>>;
+  /** Normalized shader hooks for vertex shader */
+  vertex: Record<string, ResolvedShaderHook>;
+  /** Normalized shader hooks for fragment shader */
+  fragment: Record<string, ResolvedShaderHook>;
 };
 
 /** Generate hook source code */
 export function getShaderHooks(
-  hookFunctions: Record<string, Required<ShaderHook>>,
-  hookInjections: Record<string, ShaderInjection[]>,
+  hookFunctions: Record<string, ResolvedShaderHook>,
+  hookInjections: Record<string, ResolvedShaderInjection[]>,
   shaderLanguage: 'glsl' | 'wgsl' = 'glsl'
 ): string {
   let result = '';
   for (const hookName in hookFunctions) {
     const hookFunction = hookFunctions[hookName];
-    const functionPrefix = shaderLanguage === 'wgsl' ? 'fn' : 'void';
-    result += `${functionPrefix} ${hookFunction.signature} {\n`;
+    const returnType = hookFunction.returnType || 'void';
+    const functionPrefix = shaderLanguage === 'wgsl' ? 'fn' : returnType;
+    const returnSuffix =
+      shaderLanguage === 'wgsl' && returnType !== 'void' ? ` -> ${returnType}` : '';
+    result += `${functionPrefix} ${hookFunction.signature}${returnSuffix} {\n`;
     if (hookFunction.header) {
       result += `  ${hookFunction.header}`;
     }
@@ -66,19 +72,39 @@ export function getShaderHooks(
   return result;
 }
 
-/**
- * Parse string based hook functions and split them per shader stage.
- * A later declaration of the same stage-prefixed hook name replaces an earlier one.
- */
+/** Select language syntax and merge compatible plugin declarations without mutating descriptors. */
 export function normalizeShaderHooks(
-  hookFunctions: readonly (ShaderHook | string)[]
+  hookFunctions: readonly ShaderHook[],
+  pluginHooks: readonly ShaderHook[] = [],
+  language: 'glsl' | 'wgsl' = 'glsl'
 ): ShaderHookRegistry {
   const result: ShaderHookRegistry = {vertex: {}, fragment: {}};
-
-  for (const hookFunction of hookFunctions) {
-    addShaderHookToRegistry(result, hookFunction);
+  for (const hook of hookFunctions) {
+    const implementation = hook[language];
+    if (implementation) {
+      const prefix = hook.stage === 'vertex' ? 'vs' : 'fs';
+      result[hook.stage][`${prefix}:${hook.name}`] = {
+        ...implementation,
+        signature: `${hook.name}(${implementation.parameters})`
+      };
+    }
+  }
+  for (const hook of pluginHooks) {
+    const selected = normalizeShaderHooks([hook], [], language);
+    for (const stage of ['vertex', 'fragment'] as const) {
+      for (const [name, declaration] of Object.entries(selected[stage])) {
+        const existing = result[stage][name];
+        if (
+          existing &&
+          (existing.signature !== declaration.signature ||
+            (existing.returnType || 'void') !== (declaration.returnType || 'void'))
+        ) {
+          throw new Error(`Conflicting ShaderPlugin hook ${name}`);
+        }
+        result[stage][name] = existing || declaration;
+      }
+    }
   }
-
   return result;
 }
 
@@ -94,7 +120,7 @@ export function isShaderHookRegistered(registry: ShaderHookRegistry, hookName: s
  */
 export function validateShaderHookInjections(
   registry: ShaderHookRegistry,
-  hookInjections: Record<string, ShaderInjection[]>,
+  hookInjections: Record<string, ResolvedShaderInjection[]>,
   stage?: 'vertex' | 'fragment'
 ): void {
   const stagePrefix = stage === 'vertex' ? 'vs:' : stage === 'fragment' ? 'fs:' : null;
@@ -115,32 +141,3 @@ export function validateShaderHookInjections(
     }
   }
 }
-
-function addShaderHookToRegistry(
-  registry: ShaderHookRegistry,
-  hookFunction: ShaderHook | string
-): void {
-  const options: ShaderHookOptions = typeof hookFunction === 'string' ? {} : hookFunction;
-  const hook = (typeof hookFunction === 'string' ? hookFunction : hookFunction.hook).trim();
-  const stageSeparatorIndex = hook.indexOf(':');
-  const shaderStage = hook.slice(0, stageSeparatorIndex);
-  const signature = hook.slice(stageSeparatorIndex + 1);
-  const name = hook.replace(/\(.+/, '');
-  const normalizedHook: Required<ShaderHook> = {
-    hook: name,
-    signature,
-    header: options.header || '',
-    footer: options.footer || ''
-  };
-
-  switch (shaderStage) {
-    case 'vs':
-      registry.vertex[name] = normalizedHook;
-      break;
-    case 'fs':
-      registry.fragment[name] = normalizedHook;
-      break;
-    default:
-      throw new Error(shaderStage);
-  }
-}

package/src/lib/shader-assembly/shader-injections.ts

@@ -17,29 +17,71 @@ const fragments: string[] = [];
 
 export const DECLARATION_INJECT_MARKER = '__LUMA_INJECT_DECLARATIONS__';
 
-/**
- *
- */
+/** Language-specific source inserted at a named shader anchor or hook. */
 export type ShaderInjection = {
+  /** Shader stage receiving the injection. */
+  stage: 'vertex' | 'fragment';
+  /** Unqualified hook name or structural anchor such as #main-start. */
+  target: string;
+  /** GLSL source. Omit to skip this injection for GLSL assembly. */
+  glsl?: string;
+  /** WGSL source. Omit to skip this injection for WGSL assembly. */
+  wgsl?: string;
+  /** Relative order at the target; defaults to zero. */
+  order?: number;
+};
+
+/** Language-selected source and ordering used internally during shader assembly. */
+export type ResolvedShaderInjection = {
   /** Plugin responsible for this injection, when supplied by a ShaderPlugin. */
   pluginName?: string;
   injection: string;
   order: number;
 };
 
+/** Select language-specific injections while retaining repeated targets and declaration order. */
+export function resolveShaderInjections(
+  declarations: readonly ShaderInjection[],
+  language: 'glsl' | 'wgsl',
+  pluginName?: string
+): Record<string, ResolvedShaderInjection[]> {
+  const resolved: Record<string, ResolvedShaderInjection[]> = {};
+  for (const declaration of declarations) {
+    const source = declaration[language];
+    if (source === undefined) continue;
+    if (
+      (declaration.stage !== 'vertex' && declaration.stage !== 'fragment') ||
+      declaration.target.includes(':')
+    ) {
+      throw new Error('Shader injection targets require an explicit stage and unqualified target');
+    }
+    const target = `${declaration.stage === 'vertex' ? 'vs' : 'fs'}:${declaration.target}`;
+    if (!/^(vs|fs):(?:#(?:decl|main-start|main-end)|[A-Za-z_][A-Za-z0-9_]*)$/.test(target)) {
+      throw new Error(`Shader injection target "${target}" must be a named shader anchor or hook`);
+    }
+    resolved[target] ||= [];
+    resolved[target].push({
+      injection: source,
+      order: declaration.order ?? 0,
+      ...(pluginName ? {pluginName} : {})
+    });
+  }
+  return resolved;
+}
+
 /**
  *  ShaderInjections, parsed and split per shader
  */
 export type ShaderInjections = {
-  vertex: Record<string, ShaderInjection>;
-  fragment: Record<string, ShaderInjection>;
+  vertex: Record<string, ResolvedShaderInjection>;
+  fragment: Record<string, ResolvedShaderInjection>;
 };
 
 /**
  *
  */
 export function normalizeInjections(
-  injections: Record<string, string | ShaderInjection>
+  injections: Record<string, string | ResolvedShaderInjection>
 ): ShaderInjections {
   const result: ShaderInjections = {vertex: {}, fragment: {}};
 
@@ -84,7 +126,7 @@ function getHookStage(hook: string): 'vertex' | 'fragment' {
 export function injectShader(
   source: string,
   stage: 'vertex' | 'fragment',
-  inject: Record<string, ShaderInjection[]>,
+  inject: Record<string, ResolvedShaderInjection[]>,
   injectStandardStubs = false,
   language: 'glsl' | 'wgsl' = 'glsl',
   entryPoints: {vertex?: string; fragment?: string} = {}
@@ -93,7 +135,9 @@ export function injectShader(
 
   for (const key in inject) {
     const fragmentData = inject[key];
-    fragmentData.sort((a: ShaderInjection, b: ShaderInjection): number => a.order - b.order);
+    fragmentData.sort(
+      (a: ResolvedShaderInjection, b: ResolvedShaderInjection): number => a.order - b.order
+    );
     fragments.length = fragmentData.length;
     for (let i = 0, len = fragmentData.length; i < len; ++i) {
       fragments[i] = fragmentData[i].injection;

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

@@ -10,7 +10,7 @@ import {
   getValidatedProperties
 } from '../filters/prop-types';
 import type {ShaderModuleUniformValue, UniformTypes, UniformValue} from '../utils/uniform-types';
-import {ShaderInjection, normalizeInjections} from '../shader-assembly/shader-injections';
+import type {ResolvedShaderInjection} from '../shader-assembly/shader-injections';
 
 import type {ShaderBinding as Binding} from '../../types';
 
@@ -83,8 +83,6 @@ export type ShaderModule<
 
   /** Boolean or numeric preprocessor defines contributed by this shader module. */
   defines?: Record<string, boolean | number>;
-  /** Injections */
-  inject?: Record<string, string | {injection: string; order: number}>;
   dependencies?: ShaderModule<any, any>[];
   /** Information on deprecated properties */
   deprecations?: ShaderModuleDeprecation[];
@@ -93,10 +91,10 @@ export type ShaderModule<
   instance?: {
     propValidators?: Record<string, PropValidator>;
     parsedDeprecations: ShaderModuleDeprecation[];
-
+    /** Empty compatibility value for consumers using older shadertools assembly. */
     normalizedInjections: {
-      vertex: Record<string, ShaderInjection>;
-      fragment: Record<string, ShaderInjection>;
+      vertex: Record<string, ResolvedShaderInjection>;
+      fragment: Record<string, ResolvedShaderInjection>;
     };
   };
 };
@@ -123,16 +121,11 @@ export function initializeShaderModule(module: ShaderModule): void {
 
   initializeShaderModules(module.dependencies || []);
 
-  const {
-    propTypes = {},
-    deprecations = [],
-    // defines = {},
-    inject = {}
-  } = module;
+  const {propTypes = {}, deprecations = []} = module;
 
   const instance: Required<ShaderModule>['instance'] = {
-    normalizedInjections: normalizeInjections(inject),
-    parsedDeprecations: parseDeprecationDefinitions(deprecations)
+    parsedDeprecations: parseDeprecationDefinitions(deprecations),
+    normalizedInjections: {vertex: {}, fragment: {}}
   };
 
   if (propTypes) {