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

package/src/lib/shader-generator/glsl/generate-glsl.ts

@@ -0,0 +1,101 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {UniformFormat} from '../../../types';
+import {ShaderModule} from '../../shader-module/shader-module';
+import {capitalize} from '../utils/capitalize';
+
+export type GLSLGenerationOptions = {
+  shaderLanguage: 'glsl';
+  uniforms: 'scoped-interface-blocks' | 'unscoped-interface-blocks' | 'uniforms';
+};
+
+export function generateGLSLForModule(module: ShaderModule, options: GLSLGenerationOptions) {
+  return generateGLSLUniformDeclarations(module, options);
+}
+
+function generateGLSLUniformDeclarations(
+  module: ShaderModule,
+  options: GLSLGenerationOptions
+): string {
+  const glsl: string[] = [];
+
+  // => layout(std140) uniform UniformBlockName {
+  switch (options.uniforms) {
+    case 'scoped-interface-blocks':
+    case 'unscoped-interface-blocks':
+      glsl.push(`layout(std140) uniform ${capitalize(module.name)} {`);
+      break;
+    case 'uniforms':
+    // ignore
+  }
+
+  for (const [uniformName, uniformFormat] of Object.entries(module.uniformTypes || {})) {
+    if (typeof uniformFormat !== 'string') {
+      throw new Error(
+        `Composite uniform types are not supported by GLSL shader generation: ${module.name}.${uniformName}`
+      );
+    }
+
+    const glslUniformType = getGLSLUniformType(uniformFormat as UniformFormat);
+    switch (options.uniforms) {
+      case 'scoped-interface-blocks':
+        // => layout(std140) uniform UniformBlockName {
+        glsl.push(`  ${glslUniformType} ${uniformName};`);
+        break;
+      case 'unscoped-interface-blocks':
+        // => layout(std140) uniform UniformBlockName {
+        glsl.push(`  ${glslUniformType} ${module.name}_${uniformName};`);
+        break;
+      case 'uniforms':
+        glsl.push(`uniform ${glslUniformType} ${module.name}_${uniformName};`);
+    }
+  }
+
+  switch (options.uniforms) {
+    case 'scoped-interface-blocks':
+      glsl.push(`} ${module.name};`);
+      break;
+    case 'unscoped-interface-blocks':
+      glsl.push('};');
+      break;
+    case 'uniforms':
+    // ignore
+  }
+
+  // final new line
+  glsl.push('');
+
+  return glsl.join('\n');
+}
+
+/** Map a luma.gl WebGPU style uniform type to GLSL */
+function getGLSLUniformType(uniformFormat: UniformFormat): string {
+  const UNIFORM_TYPE_TO_GLSL: Record<UniformFormat, string> = {
+    f32: 'float',
+    i32: 'int',
+    u32: 'uint',
+    'vec2<f32>': 'vec2',
+    'vec3<f32>': 'vec3',
+    'vec4<f32>': 'vec4',
+    'vec2<i32>': 'ivec2',
+    'vec3<i32>': 'ivec3',
+    'vec4<i32>': 'ivec4',
+    'vec2<u32>': 'uvec2',
+    'vec3<u32>': 'uvec3',
+    'vec4<u32>': 'uvec4',
+    'mat2x2<f32>': 'mat2',
+    'mat2x3<f32>': 'mat2x3',
+    'mat2x4<f32>': 'mat2x4',
+    'mat3x2<f32>': 'mat3x2',
+    'mat3x3<f32>': 'mat3',
+    'mat3x4<f32>': 'mat3x4',
+    'mat4x2<f32>': 'mat4x2',
+    'mat4x3<f32>': 'mat4x3',
+    'mat4x4<f32>': 'mat4'
+  };
+
+  const glsl = UNIFORM_TYPE_TO_GLSL[uniformFormat];
+  return glsl;
+}

package/src/lib/shader-generator/utils/capitalize.ts

@@ -0,0 +1,12 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/**
+ * Capitalize first letter of a string
+ * @param {string} str
+ * @returns {string}
+ */
+export function capitalize(str: string): string {
+  return typeof str === 'string' ? str.charAt(0).toUpperCase() + str.slice(1) : str;
+}

package/src/lib/shader-generator/wgsl/generate-wgsl.ts

@@ -0,0 +1,40 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {ShaderModule} from '../../shader-module/shader-module';
+import {capitalize} from '../utils/capitalize';
+
+export type WGSLGenerationOptions = {
+  shaderLanguage: 'wgsl';
+};
+
+export function generateWGSLForModule(module: ShaderModule, options: WGSLGenerationOptions) {
+  return generateWGSLUniformDeclarations(module, options);
+}
+
+export function generateWGSLUniformDeclarations(
+  module: ShaderModule,
+  options: WGSLGenerationOptions
+) {
+  const wgsl: string[] = [];
+
+  // => uniform UniformBlockName {
+  wgsl.push(`struct ${capitalize(module.name)} {`);
+
+  for (const [uniformName, uniformFormat] of Object.entries(module?.uniformTypes || {})) {
+    if (typeof uniformFormat !== 'string') {
+      throw new Error(
+        `Composite uniform types are not supported by WGSL shader generation: ${module.name}.${uniformName}`
+      );
+    }
+
+    const wgslUniformType = uniformFormat;
+    wgsl.push(`  ${uniformName} : ${wgslUniformType};`);
+  }
+  wgsl.push('};');
+
+  wgsl.push(`var<uniform> ${module.name} : ${capitalize(module.name)};`);
+
+  return wgsl.join('\n');
+}

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

@@ -0,0 +1,47 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {UniformValue} from '../utils/uniform-types';
+import type {ShaderPass, ShaderPassInputSource, ShaderPassRenderTarget} from './shader-pass';
+
+/** One ordered step in a {@link CompositeShaderPass}. */
+export type CompositeShaderPassStep<TargetNameT extends string = string> = {
+  shaderPass: ShaderPass<any, any, any, any>;
+  inputs?: Record<string, ShaderPassInputSource<TargetNameT>>;
+  output?: 'previous' | TargetNameT;
+  uniforms?: Record<string, UniformValue>;
+};
+
+/** Optional WebGPU compute stage that replaces equivalent fragment-only fallback passes. */
+export type CompositeShaderPassComputeOptimization<TargetNameT extends string = string> = {
+  /** Stable identifier used for compute resources and command labels. */
+  name: string;
+  /** Complete WGSL compute entry point with explicit binding locations. */
+  source: string;
+  /** Existing fragment module that owns the scalar runtime uniforms. */
+  uniformModule: string;
+  /** Explicit WGSL uniform-buffer binding name used by the compute entry point. */
+  uniformBinding: string;
+  /** Scalar uniform packing order used by the compute shader. */
+  uniformNames: readonly string[];
+  /** Composite-pass scalar defaults layered below per-frame runtime overrides. */
+  uniforms: Record<string, number>;
+  /** Logical source image consumed by the fused compute dispatch. */
+  input: ShaderPassInputSource<TargetNameT>;
+  /** Mapping from compute storage-texture names to owned render targets. */
+  outputs: Record<string, TargetNameT>;
+  /** Fragment pass names removed when the WebGPU optimization is supported. */
+  replacedPasses: readonly string[];
+  /** Compute workgroup width and height in highest-resolution output texels. */
+  workgroupSize: readonly [number, number];
+};
+
+/** Declarative composition of shader passes with owned targets and optional compute execution. */
+export type CompositeShaderPass<TargetNameT extends string = string> = {
+  name: string;
+  renderTargets?: Record<TargetNameT, ShaderPassRenderTarget>;
+  steps: CompositeShaderPassStep<TargetNameT>[];
+  /** Optional fused WebGPU dispatch; existing fragment steps remain the portable fallback. */
+  compute?: CompositeShaderPassComputeOptimization<TargetNameT>;
+};

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

@@ -0,0 +1,128 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {ShaderModule, initializeShaderModules} from './shader-module';
+import {assert} from '../utils/assert';
+
+// import type {ShaderModule} from './shader-module';
+
+type AbstractModule = {
+  name: string;
+  implements?: string;
+  dependencies?: AbstractModule[];
+};
+
+/**
+ * Takes a list of shader module names and returns a new list of
+ * shader module names that includes all dependencies, sorted so
+ * that modules that are dependencies of other modules come first.
+ *
+ * If the shader glsl code from the returned modules is concatenated
+ * in the reverse order, it is guaranteed that all functions be resolved and
+ * that all function and variable definitions come before use.
+ *
+ * @param modules - Array of modules (inline modules or module names)
+ * @return - Array of modules
+ */
+export function getShaderModuleDependencies<T extends AbstractModule>(modules: T[]): T[] {
+  // Data structures for topological sort
+  const visited = new Set<T>(); // Fully processed modules (black nodes)
+  const recursionStack = new Set<T>(); // Modules in current DFS path (gray nodes)
+  const result: T[] = []; // Post-order traversal result
+  const nameToModule = new Map<string, T>(); // Name collision detection
+
+  /**
+   * Check for name collisions between distinct module objects
+   */
+  function checkNameCollision(module: T): void {
+    const existing = nameToModule.get(module.name);
+    if (existing && existing !== module) {
+      throw new Error(
+        `Shader module name collision: Multiple different module objects share the name "${module.name}". ` +
+          `Each module object must have a unique name.`
+      );
+    }
+    nameToModule.set(module.name, module);
+  }
+
+  /**
+   * DFS visit function for topological sort with cycle detection
+   */
+  function visit(module: T, path: string[]): void {
+    // Cycle detection: if module is in recursion stack, we've found a back edge
+    if (recursionStack.has(module)) {
+      const cyclePath = [...path, module.name].join(' -> ');
+      throw new Error(`Shader module dependency cycle detected: ${cyclePath}`);
+    }
+
+    // Already processed: skip if visited
+    if (visited.has(module)) {
+      return;
+    }
+
+    // Check for name collision before processing
+    checkNameCollision(module);
+
+    // Mark as visiting (white -> gray)
+    recursionStack.add(module);
+    const newPath = [...path, module.name];
+
+    // Recursively visit all dependencies
+    if (module.dependencies) {
+      for (const dep of module.dependencies) {
+        visit(dep as T, newPath);
+      }
+    }
+
+    // Mark as visited (gray -> black)
+    recursionStack.delete(module);
+    visited.add(module);
+
+    // Post-order: add to result after all dependencies processed
+    result.push(module);
+  }
+
+  // Start DFS from each root module
+  for (const module of modules) {
+    visit(module, []);
+  }
+
+  const interfaceProviders = new Set<string>();
+  for (const module of result) {
+    if (module.implements !== undefined) {
+      // Distinct modules cannot provide the same exclusive shader interface.
+      assert(!interfaceProviders.has(module.implements));
+      interfaceProviders.add(module.implements);
+    }
+  }
+
+  initializeShaderModules(result);
+  return result;
+}
+
+/**
+ * Takes a list of shader module names and returns a new list of
+ * shader module names that includes all dependencies, sorted so
+ * that modules that are dependencies of other modules come first.
+ *
+ * If the shader glsl code from the returned modules is concatenated
+ * in the reverse order, it is guaranteed that all functions be resolved and
+ * that all function and variable definitions come before use.
+ *
+ * @param modules - Array of modules (inline modules or module names)
+ * @return - Array of modules
+ */
+export function getShaderDependencies(modules: ShaderModule[]): ShaderModule[] {
+  return getShaderModuleDependencies(modules);
+}
+
+// DEPRECATED
+
+/**
+ * Instantiate shader modules and resolve any dependencies
+ * @deprecated Use getShaderDpendencies
+ */
+export function resolveModules(modules: ShaderModule[]): ShaderModule[] {
+  return getShaderDependencies(modules);
+}