@luma.gl/shaders 0.0.0-stage → 10.0.0-alpha.10

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

@@ -0,0 +1,69 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderBinding as Binding, SamplerProps, TextureFormat} from '../../types';
+import type {PickBindings, PickUniforms, ShaderModule} from './shader-module';
+import type {UniformValue} from '../utils/uniform-types';
+
+export type ShaderPassRenderTarget = {
+  /** Width and height scale relative to the renderer output size. */
+  scale?: [number, number];
+  /** Render target format. Defaults to the device preferred color format. */
+  format?: TextureFormat;
+  /** Optional sampling behavior when later passes read this target. */
+  sampler?: SamplerProps;
+  /** Reuse an earlier transient target with an identical size, format, and sampler. */
+  aliasFor?: string;
+  /** Allow WebGPU compute shaders to write this target as a storage texture. */
+  storage?: boolean;
+  /** Resource lifetime. History targets retain their last successfully rendered value. */
+  lifetime?: 'transient' | 'history';
+  /** Initial value used after construction, resize, or an explicit history reset. */
+  initialize?: 'original' | {clearColor: [number, number, number, number]};
+};
+
+export type ShaderPassInputSource<TargetNameT extends string = string> =
+  | 'original'
+  | 'previous'
+  | TargetNameT;
+
+/**
+ * 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.
+ * A ShaderPass can require one or more sub passes.
+ */
+export type ShaderPass<
+  PropsT extends Record<string, any> = Record<string, any>,
+  UniformsT extends Record<string, UniformValue> = PickUniforms<PropsT>,
+  BindingsT extends Record<string, Binding> = PickBindings<PropsT>,
+  RenderTargetNameT extends string = never
+> = ShaderModule<PropsT, UniformsT, BindingsT> & {
+  /** A shader pass can run multiple sub passes */
+  passes?: ShaderSubPass<UniformsT, Extract<keyof BindingsT, string>, RenderTargetNameT>[];
+  // TODO better name
+  // subPasses?: ShaderSubPass[];
+};
+
+/** Information on how to run a specific sub pass */
+export type ShaderSubPass<
+  UniformsT extends Record<string, UniformValue> = Record<string, UniformValue>,
+  BindingNameT extends string = string,
+  RenderTargetNameT extends string = string
+> = {
+  /**
+   * Action indicates whether this pass:
+   * - filters the color in each pixel (provides a `<pass.name>_filterColor()` shader function)
+   * - performs its own sampling (provides a `<pass.name>_sampleColor()` shader function)
+   */
+  action?: 'filter' | 'sample';
+  sampler?: boolean;
+  filter?: boolean;
+  uniforms?: UniformsT;
+  /** Mapping from shader binding name to the logical texture source. */
+  inputs?: Partial<
+    Record<BindingNameT | 'sourceTexture', ShaderPassInputSource<RenderTargetNameT>>
+  >;
+  /** Output target for this sub pass. Defaults to the shared "previous" chain. */
+  output?: 'previous' | RenderTargetNameT;
+};

package/src/lib/shader-plugin.ts

@@ -0,0 +1,236 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderInjectionTarget} from './shader-assembly/shader-injection-targets';
+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';
+
+/** Portable interpolation modes for ShaderPlugin inter-stage variables. */
+export type ShaderPluginInterStageVariableInterpolation = 'smooth' | 'flat';
+
+/** Cross-stage value contributed by a ShaderPlugin. */
+export type ShaderPluginInterStageVariable = {
+  /** Portable scalar or vector shader type. */
+  type: AttributeShaderType;
+  /** Defaults to smooth for floating-point types and flat for integer types. */
+  interpolation?: ShaderPluginInterStageVariableInterpolation;
+};
+
+/** Fully normalized ShaderPlugin inter-stage variable declaration. */
+export type ResolvedShaderPluginInterStageVariable = {
+  type: AttributeShaderType;
+  interpolation: ShaderPluginInterStageVariableInterpolation;
+};
+
+/** 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 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. */
+  injectionTargets?: ShaderInjectionTarget[];
+  /** 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. */
+  interStageVariables?: Record<string, ShaderPluginInterStageVariable>;
+};
+
+/** ShaderPlugin contributions resolved for one shader language. */
+export type ResolvedShaderPlugins = {
+  /** Resolved shader modules in plugin declaration order. */
+  modules: ShaderModule[];
+  /** Language-selected callable injection target declarations. */
+  injectionTargets: ShaderInjectionTarget[];
+  /** Resolved boolean or numeric preprocessor defines. */
+  defines: Record<string, boolean | number>;
+  /** Resolved named code injections grouped by target. */
+  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>;
+};
+
+/** Resolve plugin interfaces and select injection source for one shader language. */
+export function resolveShaderPlugins(
+  plugins: readonly ShaderPlugin[] = [],
+  shaderLanguage: 'glsl' | 'wgsl'
+): ResolvedShaderPlugins {
+  const resolved: ResolvedShaderPlugins = {
+    modules: [],
+    injectionTargets: [],
+    defines: {},
+    injections: {},
+    vertexInputs: {},
+    interStageVariables: {}
+  };
+
+  for (const plugin of plugins) {
+    appendShaderPlugin(resolved, plugin, shaderLanguage);
+  }
+  const {vertexInputs, interStageVariables} = resolved;
+
+  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 resolved;
+}
+
+/**
+ * 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[] = [],
+  options: {onConflict?: (name: string, selected: ShaderModule, ignored: ShaderModule) => void} = {}
+): ShaderModule[] {
+  const mergedModules: ShaderModule[] = [...modules];
+  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) {
+    const selected = selectedModules.get(pluginModule.name);
+    if (selected && selected !== pluginModule) {
+      options.onConflict?.(pluginModule.name, selected, pluginModule);
+    }
+    if (!selected) {
+      mergedModules.push(pluginModule);
+      selectedModules.set(pluginModule.name, pluginModule);
+    }
+  }
+
+  return mergedModules;
+}
+
+function appendShaderPlugin(
+  resolved: ResolvedShaderPlugins,
+  plugin: ShaderPlugin,
+  shaderLanguage: 'glsl' | 'wgsl'
+): void {
+  if (plugin.module) {
+    resolved.modules.push(plugin.module);
+  }
+  if (plugin.defines) {
+    Object.assign(resolved.defines, plugin.defines);
+  }
+  for (const [name, type] of Object.entries(plugin.vertexInputs || {})) {
+    assertShaderPluginInterfaceName(name, 'vertex input');
+    const existingType = resolved.vertexInputs[name];
+    if (existingType && existingType !== type) {
+      throw new Error(
+        `ShaderPlugin vertex input "${name}" has conflicting types "${existingType}" and "${type}"`
+      );
+    }
+    resolved.vertexInputs[name] = type;
+  }
+  for (const [name, varying] of Object.entries(plugin.interStageVariables || {})) {
+    assertShaderPluginInterfaceName(name, 'varying');
+    const normalizedVarying = normalizeShaderPluginInterStageVariable(name, varying);
+    const existingVarying = resolved.interStageVariables[name];
+    if (
+      existingVarying &&
+      (existingVarying.type !== normalizedVarying.type ||
+        existingVarying.interpolation !== normalizedVarying.interpolation)
+    ) {
+      throw new Error(
+        `ShaderPlugin varying "${name}" has conflicting declarations ` +
+          `"${existingVarying.type}/${existingVarying.interpolation}" and ` +
+          `"${normalizedVarying.type}/${normalizedVarying.interpolation}"`
+      );
+    }
+    resolved.interStageVariables[name] = normalizedVarying;
+  }
+
+  for (const injectionTarget of plugin.injectionTargets || []) {
+    const implementation = injectionTarget[shaderLanguage];
+    if (!implementation) continue;
+    const target = `${injectionTarget.stage === 'vertex' ? 'vs' : 'fs'}:${injectionTarget.name}`;
+    if (!/^(vs|fs):[A-Za-z_][A-Za-z0-9_]*$/.test(target)) {
+      throw new Error(`Invalid ShaderPlugin injection target ${target}`);
+    }
+    const existing = resolved.injectionTargets.find(
+      value => value.stage === injectionTarget.stage && value.name === injectionTarget.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 injection target ${target}`);
+    }
+    if (!existing)
+      resolved.injectionTargets.push({
+        name: injectionTarget.name,
+        stage: injectionTarget.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);
+  }
+}
+
+function assertShaderPluginInterfaceName(name: string, kind: 'vertex input' | 'varying'): void {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || name.startsWith('_luma_')) {
+    throw new Error(`ShaderPlugin ${kind} "${name}" must be a valid non-reserved identifier`);
+  }
+}
+
+function normalizeShaderPluginInterStageVariable(
+  name: string,
+  varying: ShaderPluginInterStageVariable
+): ResolvedShaderPluginInterStageVariable {
+  const {primitiveType} = shaderTypeDecoder.getAttributeShaderTypeInfo(varying.type);
+  const integerType = primitiveType === 'i32' || primitiveType === 'u32';
+  const interpolation = varying.interpolation || (integerType ? 'flat' : 'smooth');
+  if (integerType && interpolation === 'smooth') {
+    throw new Error(`ShaderPlugin integer varying "${name}" must use flat interpolation`);
+  }
+  return {type: varying.type, interpolation};
+}
+
+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/lib/shader-transpiler/shader-transpiler.ts

@@ -0,0 +1,34 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {PlatformInfo} from '../shader-assembly/platform-info';
+
+export type ShaderTranspilerEntryPoints = {
+  vertex?: string;
+  fragment?: string;
+  compute?: string;
+};
+
+/** One translation unit, including source-language module dependencies. */
+export type ShaderTranspileProps = {
+  source: string;
+  target: 'glsl' | 'wgsl';
+  /** GLSL compiles one stage at a time; WGSL may compile a unified render program. */
+  stage?: 'vertex' | 'fragment' | 'compute';
+  entryPoints: ShaderTranspilerEntryPoints;
+  platformInfo: PlatformInfo;
+};
+
+export type ShaderTranspileResult = {
+  code: string;
+  /** Generated names selected by subsequent interface scanning and pipeline creation. */
+  entryPoints?: ShaderTranspilerEntryPoints;
+};
+
+/** Application-owned compiler. Shaders has no dependency on its implementation. */
+export type ShaderTranspiler = {
+  name: string;
+  sourceLanguage: string;
+  transpile: (props: ShaderTranspileProps) => ShaderTranspileResult;
+};

package/src/lib/shader-transpiler/transpile-glsl-shader.ts

@@ -0,0 +1,78 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+// TRANSPILATION TABLES
+
+/**
+ * Transpiles GLSL 3.00 shader source code to target GLSL version (3.00 or 1.00)
+ *
+ * @note We always run transpiler even if same version e.g. 3.00 => 3.00
+ * @note For texture sampling transpilation, apps need to use non-standard texture* calls in GLSL 3.00 source
+ * RFC: https://github.com/visgl/luma.gl/blob/7.0-release/dev-docs/RFCs/v6.0/portable-glsl-300-rfc.md
+ */
+export function transpileGLSLShader(source: string, stage: 'vertex' | 'fragment'): string {
+  const sourceGLSLVersion = Number(source.match(/^#version[ \t]+(\d+)/m)?.[1] || 100);
+  if (sourceGLSLVersion !== 300) {
+    // TODO - we splurge on a longer error message to help deck.gl custom layer developers
+    throw new Error('luma.gl v9 only supports GLSL 3.00 shader sources');
+  }
+
+  switch (stage) {
+    case 'vertex':
+      source = convertShader(source, ES300_VERTEX_REPLACEMENTS);
+      return source;
+    case 'fragment':
+      source = convertShader(source, ES300_FRAGMENT_REPLACEMENTS);
+      return source;
+    default:
+      // Unknown shader stage
+      throw new Error(stage);
+  }
+}
+
+type GLSLReplacement = [RegExp, string];
+
+/** Simple regex replacements for GLSL ES 1.00 syntax that has changed in GLSL ES 3.00 */
+const ES300_REPLACEMENTS: GLSLReplacement[] = [
+  // Fix poorly formatted version directive
+  [/^(#version[ \t]+(100|300[ \t]+es))?[ \t]*\n/, '#version 300 es\n'],
+  // The individual `texture...()` functions were replaced with `texture()` overloads
+  [/\btexture(2D|2DProj|Cube)Lod(EXT)?\(/g, 'textureLod('],
+  [/\btexture(2D|2DProj|Cube)(EXT)?\(/g, 'texture(']
+];
+
+const ES300_VERTEX_REPLACEMENTS: GLSLReplacement[] = [
+  ...ES300_REPLACEMENTS,
+  // `attribute` keyword replaced with `in`
+  [makeVariableTextRegExp('attribute'), 'in $1'],
+  // `varying` keyword replaced with `out`
+  [makeVariableTextRegExp('varying'), 'out $1']
+];
+
+/** Simple regex replacements for GLSL ES 1.00 syntax that has changed in GLSL ES 3.00 */
+const ES300_FRAGMENT_REPLACEMENTS: GLSLReplacement[] = [
+  ...ES300_REPLACEMENTS,
+  // `varying` keyword replaced with `in`
+  [makeVariableTextRegExp('varying'), 'in $1']
+];
+
+function convertShader(source: string, replacements: GLSLReplacement[]) {
+  for (const [pattern, replacement] of replacements) {
+    source = source.replace(pattern, replacement);
+  }
+  return source;
+}
+
+/**
+ * Creates a regexp that tests for a specific variable type
+ * @example
+ *   should match:
+ *     in float weight;
+ *     out vec4 positions[2];
+ *   should not match:
+ *     void f(out float a, in float b) {}
+ */
+function makeVariableTextRegExp(qualifier: 'attribute' | 'varying' | 'in' | 'out'): RegExp {
+  return new RegExp(`\\b${qualifier}[ \\t]+(\\w+[ \\t]+\\w+(\\[\\w+\\])?;)`, 'g');
+}

package/src/lib/utils/assert.ts

@@ -0,0 +1,13 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+// Recommendation is to ignore message but current test suite checks against the
+// message so keep it for now.
+export function assert(condition: unknown, message?: string): void {
+  if (!condition) {
+    const error = new Error(message || 'shaders: assertion failed.');
+    Error.captureStackTrace?.(error, assert);
+    throw error;
+  }
+}

package/src/lib/utils/uniform-types.ts

@@ -0,0 +1,89 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {
+  Matrix3,
+  Matrix4,
+  Vector2,
+  Vector3,
+  Vector4,
+  NumberArray2,
+  NumberArray3,
+  NumberArray4,
+  NumberArray6,
+  NumberArray8,
+  NumberArray9,
+  NumberArray12,
+  NumberArray16
+} from '@math.gl/core';
+
+import type {CompositeShaderType} from '../../types';
+
+/*
+ * Allowed types to be used for uniform values
+ *
+ * Only allow types whose length we can type-check (not `TypedArray`)
+ */
+export type UniformValue = Readonly<
+  | number
+  | boolean
+  | NumberArray2
+  | NumberArray3
+  | NumberArray4
+  | NumberArray6
+  | NumberArray8
+  | NumberArray9
+  | NumberArray12
+  | NumberArray16
+  | Vector2
+  | Vector3
+  | Vector4
+  | Matrix3
+  | Matrix4
+>;
+
+export type ShaderModuleUniformValue =
+  | UniformValue
+  | ShaderModuleUniformStruct
+  | ShaderModuleUniformArray;
+
+export type ShaderModuleUniformStruct = {
+  [name: string]: ShaderModuleUniformValue | undefined;
+};
+
+export type ShaderModuleUniformArray = ReadonlyArray<ShaderModuleUniformValue | undefined>;
+
+type UniformLeafType<ValueT extends UniformValue> = ValueT extends number | boolean
+  ? 'f32' | 'i32' | 'u32'
+  : ValueT extends Readonly<NumberArray2 | Vector2>
+    ? 'vec2<f32>' | 'vec2<i32>' | 'vec2<u32>'
+    : ValueT extends Readonly<NumberArray3 | Vector3>
+      ? 'vec3<f32>' | 'vec3<i32>' | 'vec3<u32>'
+      : ValueT extends Readonly<NumberArray4 | Vector4>
+        ? 'vec4<f32>' | 'vec4<i32>' | 'vec4<u32>' | 'mat2x2<f32>'
+        : ValueT extends Readonly<NumberArray6>
+          ? 'mat2x3<f32>' | 'mat3x2<f32>'
+          : ValueT extends Readonly<NumberArray8>
+            ? 'mat2x4<f32>' | 'mat4x2<f32>'
+            : ValueT extends Readonly<NumberArray9 | Matrix3>
+              ? 'mat3x3<f32>'
+              : ValueT extends Readonly<NumberArray12>
+                ? 'mat3x4<f32>' | 'mat4x3<f32>'
+                : ValueT extends Readonly<NumberArray16 | Matrix4>
+                  ? 'mat4x4<f32>'
+                  : never;
+
+type UniformType<ValueT> = ValueT extends UniformValue
+  ? UniformLeafType<ValueT>
+  : ValueT extends ReadonlyArray<infer ElementT>
+    ? readonly [UniformType<NonNullable<ElementT>>, number]
+    : ValueT extends Record<string, unknown>
+      ? {[name in keyof ValueT]-?: UniformType<NonNullable<ValueT[name]>>}
+      : never;
+
+type UniformProps = Record<string, unknown>;
+
+export type UniformTypes<PropsT extends UniformProps> = {
+  [name in keyof PropsT]-?: UniformType<NonNullable<PropsT[name]>> & CompositeShaderType;
+};

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

@@ -0,0 +1,122 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {ShaderAssembler} from './shader-assembler-base';
+import type {ShaderModule} from './shader-module/shader-module';
+import type {AssembleShaderProps, GetUniformsFunc} from './shader-assembly/shader-assembly-types';
+import {assembleWGSLSource} from './shader-assembly/assemble-wgsl-shaders';
+import {
+  getShaderBindingDebugRowsFromWGSL,
+  type ShaderBindingDebugRow
+} from './shader-assembly/wgsl-binding-debug';
+import {preprocess} from './preprocessor/preprocessor';
+import {scanWGSLInterface} from './shader-assembly/wgsl-interface-scan';
+import type {ShaderLayout} from '../types';
+import type {ShaderTranspilerEntryPoints} from './shader-transpiler/shader-transpiler';
+
+/** Stateful assembler for unified WGSL shaders. */
+export class WGSLShaderAssembler extends ShaderAssembler {
+  readonly shaderLanguage: 'wgsl' = 'wgsl';
+  /** Stable per-run WGSL auto-binding assignments keyed by group/module/binding. */
+  private readonly _wgslBindingRegistry = new Map<string, number>();
+
+  /**
+   * Assemble a WGSL unified shader.
+   * @param props WGSL source, platform information, shader modules, defines, and injections.
+   * @returns Assembled WGSL source, resolved modules, uniforms, and binding debug metadata.
+   */
+  assembleWGSLShader(props: AssembleShaderProps): {
+    source: string;
+    getUniforms: GetUniformsFunc;
+    modules: ShaderModule[];
+    bindingAssignments: {moduleName: string; name: string; group: number; location: number}[];
+    bindingTable: ShaderBindingDebugRow[];
+    shaderLayout: ShaderLayout | null;
+    entryPoints: ShaderTranspilerEntryPoints;
+  } {
+    const modules = this._getModuleList(props.modules); // Combine with default modules
+    const injectionTargets = [...this._injectionTargets, ...(props.injectionTargets || [])];
+    const translated = this._transpileShader(
+      props,
+      modules,
+      props.source,
+      props.shaderStage ?? (props.computeEntryPoint ? 'compute' : undefined)
+    );
+    const entryPoints = {
+      vertex: translated.entryPoints?.vertex ?? props.vertexEntryPoint,
+      fragment: translated.entryPoints?.fragment ?? props.fragmentEntryPoint,
+      compute: translated.entryPoints?.compute ?? props.computeEntryPoint
+    };
+    const defines = WGSLShaderAssembler.getShaderPreprocessorDefines(props, modules);
+    const preprocessedApplicationSource =
+      props.platformInfo.shaderLanguage === 'wgsl' && translated.code
+        ? preprocess(translated.code, {defines})
+        : translated.code;
+    const {
+      source: assembledSource,
+      getUniforms,
+      bindingAssignments
+    } = assembleWGSLSource({
+      ...props,
+      source: preprocessedApplicationSource,
+      vertexEntryPoint: entryPoints.vertex,
+      fragmentEntryPoint: entryPoints.fragment,
+      defines,
+      _bindingRegistry: this._wgslBindingRegistry,
+      modules: translated.modules,
+      injectionTargets
+    });
+    // WGSL does not have built-in preprocessing support (just compile time constants)
+    const preprocessedSource =
+      props.platformInfo.shaderLanguage === 'wgsl'
+        ? preprocess(assembledSource, {defines})
+        : assembledSource;
+    return {
+      source: preprocessedSource,
+      entryPoints,
+      getUniforms,
+      modules,
+      bindingAssignments,
+      bindingTable: getShaderBindingDebugRowsFromWGSL(preprocessedSource, bindingAssignments),
+      shaderLayout: scanWGSLInterface(preprocessedSource, {
+        vertexEntryPoint: entryPoints.vertex,
+        scanVertexAttributes: props.scanVertexAttributes
+      })
+    };
+  }
+
+  private static getShaderPreprocessorDefines(
+    props: AssembleShaderProps,
+    modules: ShaderModule[]
+  ): Record<string, boolean | number> {
+    return {
+      ...WGSLShaderAssembler.getPlatformPreprocessorDefines(props.platformInfo),
+      ...modules.reduce<Record<string, boolean | number>>((accumulator, module) => {
+        Object.assign(accumulator, module.defines);
+        return accumulator;
+      }, {}),
+      ...props.defines
+    };
+  }
+
+  private static getPlatformPreprocessorDefines(
+    platformInfo: AssembleShaderProps['platformInfo']
+  ): Record<string, boolean> {
+    const limits = platformInfo.limits || {};
+    return {
+      LUMA_SUPPORTS_VERTEX_STORAGE_BUFFERS:
+        platformInfo.type === 'webgpu' && (limits['maxStorageBuffersInVertexStage'] || 0) > 0,
+      // Native tan() does not provide enough precision on all WebGPU implementations.
+      LUMA_FP32_TAN_PRECISION_WORKAROUND:
+        platformInfo.type === 'webgpu' &&
+        platformInfo.gpu.toLowerCase() !== 'nvidia' &&
+        platformInfo.gpu.toLowerCase() !== 'amd',
+      // Metal may reassociate the floating-point transforms used by classic
+      // double-single arithmetic. The integer path makes each rounding point
+      // explicit while preserving the public vec2<f32> representation.
+      LUMA_FP64_INTEGER_ARITHMETIC:
+        platformInfo.type === 'webgpu' && platformInfo.gpu.toLowerCase() === 'apple'
+    };
+  }
+}

package/src/module-injectors.ts

@@ -0,0 +1,32 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export const MODULE_INJECTORS_VS = /* glsl */ `\
+#ifdef MODULE_LOGDEPTH
+  logdepth_adjustPosition(gl_Position);
+#endif
+`;
+
+export const MODULE_INJECTORS_FS = /* glsl */ `\
+#ifdef MODULE_MATERIAL
+  fragColor = material_filterColor(fragColor);
+#endif
+
+#ifdef MODULE_LIGHTING
+  fragColor = lighting_filterColor(fragColor);
+#endif
+
+#ifdef MODULE_FOG
+  fragColor = fog_filterColor(fragColor);
+#endif
+
+#ifdef MODULE_PICKING
+  fragColor = picking_filterHighlightColor(fragColor);
+  fragColor = picking_filterPickingColor(fragColor);
+#endif
+
+#ifdef MODULE_LOGDEPTH
+  logdepth_setFragDepth();
+#endif
+`;