@luma.gl/shadertools 9.3.5 → 9.4.0-alpha.1

package/src/lib/shader-assembly/shader-plugin-vertex-inputs.ts

@@ -0,0 +1,279 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {shaderTypeDecoder, type AttributeShaderType} from '@luma.gl/core';
+
+export type ShaderPluginVertexInputAssembly = {
+  source: string;
+  declarations: string;
+  initialization: string;
+};
+
+/** Generate GLSL vertex input declarations contributed by shader plugins. */
+export function getShaderPluginVertexInputDeclarationsGLSL(
+  source: string,
+  vertexInputs: Record<string, AttributeShaderType>
+): string {
+  const declarations: string[] = [];
+  for (const [name, type] of Object.entries(vertexInputs)) {
+    assertGLSLVertexInputIsNew(source, name);
+    declarations.push(`in ${getGLSLAttributeType(type)} ${name};`);
+  }
+  return declarations.join('\n');
+}
+
+/** Add WGSL plugin inputs to the selected vertex entry point. */
+export function assembleShaderPluginVertexInputsWGSL(
+  source: string,
+  vertexEntryPoint: string,
+  vertexInputs: Record<string, AttributeShaderType>
+): ShaderPluginVertexInputAssembly {
+  const entries = Object.entries(vertexInputs);
+  if (entries.length === 0) {
+    return {source, declarations: '', initialization: ''};
+  }
+
+  const functionRange = getWGSLFunctionParameterRange(source, vertexEntryPoint);
+  const parameterSource = source.slice(
+    functionRange.openParenthesis + 1,
+    functionRange.closeParenthesis
+  );
+  const interfaceInfo = getWGSLVertexInterfaceInfo(source, parameterSource);
+  const usedLocations = new Set(interfaceInfo.locations);
+  const generatedParameters: string[] = [];
+  const declarations: string[] = [];
+  const initialization: string[] = [];
+
+  for (const [name, type] of entries) {
+    if (interfaceInfo.names.has(name) || hasWGSLModuleVariable(source, name)) {
+      throw new Error(
+        `ShaderPlugin vertex input "${name}" conflicts with an existing WGSL shader input or variable`
+      );
+    }
+    const location = getFirstUnusedLocation(usedLocations);
+    usedLocations.add(location);
+    const parameterName = `_luma_${name}`;
+    generatedParameters.push(`@location(${location}) ${parameterName}: ${type}`);
+    declarations.push(`var<private> ${name}: ${type};`);
+    initialization.push(`${name} = ${parameterName};`);
+  }
+
+  const separator = parameterSource.trim() ? ',\n  ' : '\n  ';
+  const suffix = parameterSource.trim() ? '' : '\n';
+  const injectedParameters = `${parameterSource}${separator}${generatedParameters.join(',\n  ')}${suffix}`;
+  const transformedSource =
+    source.slice(0, functionRange.openParenthesis + 1) +
+    injectedParameters +
+    source.slice(functionRange.closeParenthesis);
+
+  return {
+    source: transformedSource,
+    declarations: declarations.join('\n'),
+    initialization: initialization.join('\n')
+  };
+}
+
+export function getGLSLAttributeType(type: AttributeShaderType): string {
+  const {primitiveType, components} = shaderTypeDecoder.getAttributeShaderTypeInfo(type);
+  const scalarType = primitiveType === 'i32' ? 'int' : primitiveType === 'u32' ? 'uint' : 'float';
+  if (components === 1) {
+    return scalarType;
+  }
+  const prefix = scalarType === 'int' ? 'i' : scalarType === 'uint' ? 'u' : '';
+  return `${prefix}vec${components}`;
+}
+
+function assertGLSLVertexInputIsNew(source: string, name: string): void {
+  const escapedName = escapeRegExp(name);
+  const declaration = new RegExp(
+    `\\b(?:in|attribute)\\s+(?:(?:lowp|mediump|highp)\\s+)?[A-Za-z_][A-Za-z0-9_]*\\s+${escapedName}\\s*(?:\\[|;)`
+  );
+  if (declaration.test(source)) {
+    throw new Error(`ShaderPlugin vertex input "${name}" conflicts with an existing GLSL input`);
+  }
+}
+
+function getWGSLFunctionParameterRange(
+  source: string,
+  entryPoint: string
+): {openParenthesis: number; closeParenthesis: number} {
+  const functionPattern = new RegExp(`\\bfn\\s+${escapeRegExp(entryPoint)}\\s*\\(`, 'g');
+  const match = functionPattern.exec(source);
+  if (!match) {
+    throw new Error(`ShaderPlugin vertex inputs require WGSL vertex entry point "${entryPoint}"`);
+  }
+  const openParenthesis = source.indexOf('(', match.index);
+  const closeParenthesis = findMatchingDelimiter(source, openParenthesis, '(', ')');
+  if (closeParenthesis < 0) {
+    throw new Error(`Unable to parse WGSL vertex entry point "${entryPoint}" parameters`);
+  }
+  return {openParenthesis, closeParenthesis};
+}
+
+function getWGSLVertexInterfaceInfo(
+  source: string,
+  parameterSource: string
+): {locations: number[]; names: Set<string>} {
+  const locations = getWGSLLocations(parameterSource);
+  const names = new Set(getWGSLDeclaredNames(parameterSource));
+  const parameterTypes = getWGSLParameterTypes(parameterSource);
+  for (const parameterType of parameterTypes) {
+    const structBody = getWGSLStructBody(source, parameterType);
+    if (structBody === null) {
+      continue;
+    }
+    locations.push(...getWGSLLocations(structBody));
+    for (const name of getWGSLDeclaredNames(structBody)) {
+      names.add(name);
+    }
+  }
+  return {locations, names};
+}
+
+function getWGSLLocations(source: string): number[] {
+  const locations: number[] = [];
+  const locationPattern = /@location\s*\(\s*(\d+)\s*\)/g;
+  let match = locationPattern.exec(source);
+  while (match) {
+    locations.push(Number(match[1]));
+    match = locationPattern.exec(source);
+  }
+  return locations;
+}
+
+function getWGSLDeclaredNames(source: string): string[] {
+  const names: string[] = [];
+  const namePattern = /(?:^|,)\s*(?:@[A-Za-z_][\w]*(?:\([^)]*\))?\s*)*([A-Za-z_][\w]*)\s*:/gm;
+  let match = namePattern.exec(source);
+  while (match) {
+    names.push(match[1]);
+    match = namePattern.exec(source);
+  }
+  return names;
+}
+
+function getWGSLParameterTypes(source: string): string[] {
+  const types: string[] = [];
+  const typePattern = /:\s*([A-Za-z_][\w]*)\b/g;
+  let match = typePattern.exec(source);
+  while (match) {
+    types.push(match[1]);
+    match = typePattern.exec(source);
+  }
+  return types;
+}
+
+function getWGSLStructBody(source: string, structName: string): string | null {
+  const structPattern = new RegExp(`\\bstruct\\s+${escapeRegExp(structName)}\\s*\\{`, 'g');
+  const match = structPattern.exec(source);
+  if (!match) {
+    return null;
+  }
+  const openBrace = source.indexOf('{', match.index);
+  const closeBrace = findMatchingDelimiter(source, openBrace, '{', '}');
+  return closeBrace < 0 ? null : source.slice(openBrace + 1, closeBrace);
+}
+
+function hasWGSLModuleVariable(source: string, name: string): boolean {
+  const escapedName = escapeRegExp(name);
+  const variablePattern = new RegExp(`\\b(?:var(?:<[^>]+>)?|let|const)\\s+${escapedName}\\b`, 'g');
+  let match = variablePattern.exec(source);
+  while (match) {
+    if (getBraceDepthAt(source, match.index) === 0) {
+      return true;
+    }
+    match = variablePattern.exec(source);
+  }
+  return false;
+}
+
+function getFirstUnusedLocation(usedLocations: Set<number>): number {
+  let location = 0;
+  while (usedLocations.has(location)) {
+    location++;
+  }
+  return location;
+}
+
+function findMatchingDelimiter(
+  source: string,
+  openIndex: number,
+  openCharacter: string,
+  closeCharacter: string
+): number {
+  let depth = 0;
+  let blockCommentDepth = 0;
+  let lineComment = false;
+  for (let index = openIndex; index < source.length; index++) {
+    const character = source[index];
+    const nextCharacter = source[index + 1];
+    if (lineComment) {
+      if (character === '\n') lineComment = false;
+      continue;
+    }
+    if (blockCommentDepth > 0) {
+      if (character === '/' && nextCharacter === '*') {
+        blockCommentDepth++;
+        index++;
+      } else if (character === '*' && nextCharacter === '/') {
+        blockCommentDepth--;
+        index++;
+      }
+      continue;
+    }
+    if (character === '/' && nextCharacter === '/') {
+      lineComment = true;
+      index++;
+      continue;
+    }
+    if (character === '/' && nextCharacter === '*') {
+      blockCommentDepth = 1;
+      index++;
+      continue;
+    }
+    if (character === openCharacter) depth++;
+    if (character === closeCharacter && --depth === 0) return index;
+  }
+  return -1;
+}
+
+function getBraceDepthAt(source: string, endIndex: number): number {
+  let depth = 0;
+  let blockCommentDepth = 0;
+  let lineComment = false;
+  for (let index = 0; index < endIndex; index++) {
+    const character = source[index];
+    const nextCharacter = source[index + 1];
+    if (lineComment) {
+      if (character === '\n') lineComment = false;
+      continue;
+    }
+    if (blockCommentDepth > 0) {
+      if (character === '/' && nextCharacter === '*') {
+        blockCommentDepth++;
+        index++;
+      } else if (character === '*' && nextCharacter === '/') {
+        blockCommentDepth--;
+        index++;
+      }
+      continue;
+    }
+    if (character === '/' && nextCharacter === '/') {
+      lineComment = true;
+      index++;
+    } else if (character === '/' && nextCharacter === '*') {
+      blockCommentDepth = 1;
+      index++;
+    } else if (character === '{') {
+      depth++;
+    } else if (character === '}') {
+      depth--;
+    }
+  }
+  return depth;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -25,6 +25,8 @@ export type UniformInfo = {
 export type ShaderModuleBindingLayout = {
   name: string;
   group: number;
+  /** Which shader stages can access this binding. Uses GPUShaderStage bit flags. */
+  visibility?: number;
 };
 
 // Helper types
@@ -78,6 +80,7 @@ export type ShaderModule<
     prevUniforms?: UniformsT
   ) => Partial<UniformsT & BindingsT>;
 
+  /** Boolean or numeric preprocessor defines contributed by this shader module. */
   defines?: Record<string, boolean | number>;
   /** Injections */
   inject?: Record<string, string | {injection: string; order: number}>;

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

@@ -0,0 +1,19 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {UniformValue} from '../utils/uniform-types';
+import type {ShaderPass, ShaderPassInputSource, ShaderPassRenderTarget} from './shader-pass';
+
+export type ShaderPassPipelineStep<TargetNameT extends string = string> = {
+  shaderPass: ShaderPass<any, any, any, any>;
+  inputs?: Record<string, ShaderPassInputSource<TargetNameT>>;
+  output?: 'previous' | TargetNameT;
+  uniforms?: Record<string, UniformValue>;
+};
+
+export type ShaderPassPipeline<TargetNameT extends string = string> = {
+  name: string;
+  renderTargets?: Record<TargetNameT, ShaderPassRenderTarget>;
+  steps: ShaderPassPipelineStep<TargetNameT>[];
+};

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

@@ -2,10 +2,26 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {Binding} from '@luma.gl/core';
+import type {Binding, TextureFormat} from '@luma.gl/core';
 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;
+  /** 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.
@@ -14,17 +30,20 @@ import type {UniformValue} from '../utils/uniform-types';
 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>
+  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>[];
+  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>
+  UniformsT extends Record<string, UniformValue> = Record<string, UniformValue>,
+  BindingNameT extends string = string,
+  RenderTargetNameT extends string = string
 > = {
   /**
    * Action indicates whether this pass:
@@ -35,4 +54,10 @@ export type ShaderSubPass<
   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,214 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ShaderInjection} from './shader-assembly/shader-injections';
+import type {ShaderModule} from './shader-module/shader-module';
+import {shaderTypeDecoder, type AttributeShaderType} from '@luma.gl/core';
+
+/** 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;
+  /** Shader source to inject at the target. */
+  injection: string;
+  /** Relative injection order within the target. */
+  order?: number;
+};
+
+/** Portable interpolation modes for ShaderPlugin varyings. */
+export type ShaderPluginVaryingInterpolation = 'smooth' | 'flat';
+
+/** Cross-stage value contributed by a ShaderPlugin. */
+export type ShaderPluginVarying = {
+  /** Portable scalar or vector shader type. */
+  type: AttributeShaderType;
+  /** Defaults to smooth for floating-point types and flat for integer types. */
+  interpolation?: ShaderPluginVaryingInterpolation;
+};
+
+/** Fully normalized ShaderPlugin varying declaration. */
+export type ResolvedShaderPluginVarying = {
+  type: AttributeShaderType;
+  interpolation: ShaderPluginVaryingInterpolation;
+};
+
+/** 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>;
+  /** 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;
+};
+
+/** 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 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>;
+};
+
+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. */
+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> = {};
+
+  for (const plugin of plugins) {
+    appendShaderPluginVariant({modules, defines, injections, vertexInputs, varyings}, plugin);
+    appendShaderPluginVariant(
+      {modules, defines, injections, vertexInputs, varyings},
+      plugin[shaderLanguage]
+    );
+  }
+
+  for (const name of Object.keys(varyings)) {
+    if (vertexInputs[name]) {
+      throw new Error(`ShaderPlugin name "${name}" cannot be both a vertex input and a varying`);
+    }
+  }
+
+  return {modules, defines, injections, vertexInputs, varyings};
+}
+
+/** Preserve explicit module inputs while appending plugin modules by first-seen name. */
+export function mergeShaderPluginModules(
+  modules: readonly ShaderModule[] = [],
+  pluginModules: readonly ShaderModule[] = []
+): ShaderModule[] {
+  const mergedModules: ShaderModule[] = [...modules];
+  const seenModuleNames = new Set(mergedModules.map(module => module.name));
+
+  for (const pluginModule of pluginModules) {
+    if (!seenModuleNames.has(pluginModule.name)) {
+      mergedModules.push(pluginModule);
+      seenModuleNames.add(pluginModule.name);
+    }
+  }
+
+  return mergedModules;
+}
+
+function appendShaderPluginVariant(
+  resolved: ResolvedShaderPlugins,
+  variant: ShaderPluginVariant | undefined
+): void {
+  if (!variant) {
+    return;
+  }
+
+  if (variant.modules?.length) {
+    resolved.modules.push(...variant.modules);
+  }
+  if (variant.defines) {
+    Object.assign(resolved.defines, variant.defines);
+  }
+  for (const [name, type] of Object.entries(variant.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(variant.varyings || {})) {
+    assertShaderPluginInterfaceName(name, 'varying');
+    const normalizedVarying = normalizeShaderPluginVarying(name, varying);
+    const existingVarying = resolved.varyings[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.varyings[name] = normalizedVarying;
+  }
+
+  for (const injection of variant.injections || []) {
+    assertNamedShaderPluginInjectionTarget(injection.target);
+    if (!resolved.injections[injection.target]) {
+      resolved.injections[injection.target] = [];
+    }
+    const injections = resolved.injections[injection.target];
+    injections.push({
+      injection: injection.injection,
+      order: injection.order ?? 0
+    });
+  }
+}
+
+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 normalizeShaderPluginVarying(
+  name: string,
+  varying: ShaderPluginVarying
+): ResolvedShaderPluginVarying {
+  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 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`
+    );
+  }
+}

package/src/lib/utils/assert.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-// Recommendation is to ignore message but current test suite checks agains the
+// 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) {