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

package/src/lib/shader-plugin.ts

@@ -2,33 +2,15 @@
 // SPDX-License-Identifier: MIT
 // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import type {ShaderInjection} from './shader-assembly/shader-injections';
+import type {ShaderHook} from './shader-assembly/shader-hooks';
+import {
+  resolveShaderInjections,
+  type ShaderInjection,
+  type ResolvedShaderInjection
+} from './shader-assembly/shader-injections';
 import type {ShaderModule} from './shader-module/shader-module';
 import {shaderTypeDecoder, type AttributeShaderType} from '../types';
 
-/** Named shader anchor or hook target accepted by ShaderPlugin injections. */
-export type ShaderPluginInjectionTarget =
-  | 'vs:#decl'
-  | 'vs:#main-start'
-  | 'vs:#main-end'
-  | 'fs:#decl'
-  | 'fs:#main-start'
-  | 'fs:#main-end'
-  | `vs:${string}`
-  | `fs:${string}`;
-
-/** Named shader source injection contributed by a ShaderPlugin. */
-export type ShaderPluginInjection = {
-  /** Named shader anchor or hook that receives this source. */
-  target: ShaderPluginInjectionTarget;
-  /** 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 inter-stage variables. */
 export type ShaderPluginInterStageVariableInterpolation = 'smooth' | 'flat';
 
@@ -54,8 +36,10 @@ export type ShaderPlugin = {
   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[];
+  /** Named injections as explicit-stage objects or optionally language-qualified string keys. */
+  injections?: ShaderInjection[] | Record<string, string>;
+  /** Callable extension points with a shared name and language-specific source. */
+  hooks?: ShaderHook[];
   /** 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. */
@@ -66,19 +50,18 @@ export type ShaderPlugin = {
 export type ResolvedShaderPlugins = {
   /** Resolved shader modules in plugin declaration order. */
   modules: ShaderModule[];
+  /** Language-selected hook declarations. */
+  hooks: ShaderHook[];
   /** Resolved boolean or numeric preprocessor defines. */
   defines: Record<string, boolean | number>;
   /** Resolved named code injections grouped by target. */
-  injections: Record<string, ShaderInjection[]>;
+  injections: Record<string, ResolvedShaderInjection[]>;
   /** Resolved shader-facing vertex inputs in plugin declaration order. */
   vertexInputs: Record<string, AttributeShaderType>;
   /** 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 plugin interfaces and select injection source for one shader language. */
 export function resolveShaderPlugins(
   plugins: readonly ShaderPlugin[] = [],
@@ -86,6 +69,7 @@ export function resolveShaderPlugins(
 ): ResolvedShaderPlugins {
   const resolved: ResolvedShaderPlugins = {
     modules: [],
+    hooks: [],
     defines: {},
     injections: {},
     vertexInputs: {},
@@ -177,19 +161,49 @@ function appendShaderPlugin(
     resolved.interStageVariables[name] = normalizedVarying;
   }
 
-  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] = [];
+  for (const hook of plugin.hooks || []) {
+    const implementation = hook[shaderLanguage];
+    if (!implementation) continue;
+    const target = `${hook.stage === 'vertex' ? 'vs' : 'fs'}:${hook.name}`;
+    if (!/^(vs|fs):[A-Za-z_][A-Za-z0-9_]*$/.test(target)) {
+      throw new Error(`Invalid ShaderPlugin hook ${target}`);
+    }
+    const existing = resolved.hooks.find(
+      value => value.stage === hook.stage && value.name === hook.name
+    );
+    const previous = existing?.[shaderLanguage];
+    if (
+      previous &&
+      (previous.parameters !== implementation.parameters ||
+        (previous.returnType || 'void') !== (implementation.returnType || 'void') ||
+        previous.header !== implementation.header ||
+        previous.footer !== implementation.footer)
+    ) {
+      throw new Error(`Conflicting ShaderPlugin hook ${target}`);
     }
-    const injections = resolved.injections[injection.target];
-    injections.push({
-      pluginName: plugin.name,
-      injection: source,
-      order: injection.order ?? 0
-    });
+    if (!existing)
+      resolved.hooks.push({name: hook.name, stage: hook.stage, [shaderLanguage]: implementation});
+  }
+  const pluginInjections = Array.isArray(plugin.injections)
+    ? plugin.injections
+    : Object.entries(plugin.injections || {}).flatMap(([key, source]): ShaderInjection[] => {
+        const target = selectShaderLanguage(key, shaderLanguage);
+        if (target === undefined) return [];
+        const [stage, ...name] = target.split(':');
+        if (stage !== 'vs' && stage !== 'fs')
+          throw new Error(`Invalid ShaderPlugin injection ${key}`);
+        return [
+          {
+            stage: stage === 'vs' ? ('vertex' as const) : ('fragment' as const),
+            target: name.join(':'),
+            [shaderLanguage]: source
+          }
+        ];
+      });
+  const selectedInjections = resolveShaderInjections(pluginInjections, shaderLanguage, plugin.name);
+  for (const [target, injections] of Object.entries(selectedInjections)) {
+    resolved.injections[target] ||= [];
+    resolved.injections[target].push(...injections);
   }
 }
 
@@ -212,10 +226,7 @@ function normalizeShaderPluginInterStageVariable(
   return {type: varying.type, interpolation};
 }
 
-function assertNamedShaderPluginInjectionTarget(target: ShaderPluginInjectionTarget): void {
-  if (!SHADER_PLUGIN_INJECTION_TARGET_REGEX.test(target)) {
-    throw new Error(
-      `ShaderPlugin injection target "${target}" must be a named shader anchor or hook`
-    );
-  }
+function selectShaderLanguage(value: string, language: 'glsl' | 'wgsl'): string | undefined {
+  const match = /^(glsl|wgsl):([\s\S]+)$/.exec(value);
+  return match ? (match[1] === language ? match[2] : undefined) : value;
 }

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

@@ -106,7 +106,8 @@ export const clipShaderPlugin: ShaderPlugin = {
   },
   injections: [
     {
-      target: 'vs:CLIP_POSITION',
+      stage: 'vertex',
+      target: 'CLIP_POSITION',
       glsl: `\
 clipCoordinates = geometryCoordinates;
 if (clipState.enabled != 0 && clipState.mode == ${CLIP_MODE_INSTANCE} &&
@@ -121,7 +122,8 @@ if (clipUniforms.enabled != 0 && clipUniforms.mode == ${CLIP_MODE_INSTANCE} &&
 }`
     },
     {
-      target: 'fs:CLIP_COLOR',
+      stage: 'fragment',
+      target: 'CLIP_COLOR',
       glsl: `\
 if (clipState.enabled != 0 && clipState.mode == ${CLIP_MODE_GEOMETRY} &&
     !clip_isInBounds(clipCoordinates)) {

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

@@ -84,7 +84,8 @@ export const filterShaderPlugin: ShaderPlugin = {
   },
   injections: [
     {
-      target: 'vs:FILTER_POSITION',
+      stage: 'vertex',
+      target: 'FILTER_POSITION',
       glsl: `\
 if (!filter_isVisible(filterValues)) {
   position = vec4(2.0, 2.0, 2.0, 1.0);

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

@@ -49,7 +49,7 @@ export type PointLight = {
 export type DirectionalLight = {
   /** Discriminator used to identify directional lights in `lights: Light[]`. */
   type: 'directional';
-  /** World-space light direction. */
+  /** World-space direction in which light travels. */
   direction: Readonly<NumberArray3>;
   /** RGB light color in the existing `0..255` convention used by luma.gl materials. */
   color?: Readonly<NumberArray3>;

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

@@ -1249,7 +1249,7 @@ vec4 pbr_filterColorWithSpotShadows(vec4 vertexColor, vec4 spotVisibility)
 
       for(int i = 0; i < lighting.directionalLightCount; i++) {
         if (i < lighting.directionalLightCount) {
-          PBRInfo_setDirectionalLight(pbrInfo, lighting_getDirectionalLight(i).direction);
+          PBRInfo_setDirectionalLight(pbrInfo, -lighting_getDirectionalLight(i).direction);
           color += calculateFinalColor(pbrInfo, lighting_getDirectionalLight(i).color);
         }
       }
@@ -1537,7 +1537,7 @@ vec4 pbr_filterColorWithSpotShadows(vec4 vertexColor, vec4 spotVisibility)
     // Apply directional light
     for(int i = 0; i < lighting.directionalLightCount; i++) {
       if (i < lighting.directionalLightCount) {
-        PBRInfo_setDirectionalLight(pbrInfo, lighting_getDirectionalLight(i).direction);
+        PBRInfo_setDirectionalLight(pbrInfo, -lighting_getDirectionalLight(i).direction);
         color += calculateMaterialLightColor(
           pbrInfo,
           lighting_getDirectionalLight(i).color,

package/src/modules/lighting/pbr-material/pbr-material-wgsl.ts

@@ -1468,7 +1468,7 @@ fn pbr_filterColorWithSpotShadows(vertexColor: vec4<f32>, spotVisibility: vec4f)
 
       for (var i = 0; i < lighting.directionalLightCount; i++) {
         if (i < lighting.directionalLightCount) {
-          PBRInfo_setDirectionalLight(&pbrInfo, lighting_getDirectionalLight(i).direction);
+          PBRInfo_setDirectionalLight(&pbrInfo, -lighting_getDirectionalLight(i).direction);
           color += calculateFinalColor(pbrInfo, lighting_getDirectionalLight(i).color);
         }
       }
@@ -1828,7 +1828,7 @@ fn pbr_filterColorWithSpotShadows(vertexColor: vec4<f32>, spotVisibility: vec4f)
     // Apply directional light
     for (var i = 0; i < lighting.directionalLightCount; i++) {
       if (i < lighting.directionalLightCount) {
-        PBRInfo_setDirectionalLight(&pbrInfo, lighting_getDirectionalLight(i).direction);
+        PBRInfo_setDirectionalLight(&pbrInfo, -lighting_getDirectionalLight(i).direction);
         color += calculateMaterialLightColor(
           pbrInfo,
           lighting_getDirectionalLight(i).color,

package/src/types/texture-formats.ts

@@ -85,6 +85,8 @@ export type TextureFormatCompressed =
   | 'pvrtc-rgba4unorm-webgl'
   | 'pvrtc-rgb2unorm-webgl'
   | 'pvrtc-rgba2unorm-webgl'
+  | 'etc1-rgb-unorm-webgl'
+  // Legacy misspelling retained for compatibility.
   | 'etc1-rbg-unorm-webgl'
   | 'atc-rgb-unorm-webgl'
   | 'atc-rgba-unorm-webgl'