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

package/src/lib/glsl-utils/shader-utils.ts

@@ -0,0 +1,110 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+const FS_GLES = /* glsl */ `\
+out vec4 transform_output;
+void main() {
+  transform_output = vec4(0);
+}`;
+const FS300 = `#version 300 es\n${FS_GLES}`;
+
+type QualifierInfo = {
+  qualifier: string;
+  type: string;
+  name: string;
+};
+
+// Prase given glsl line and return qualifier details or null
+export function getQualifierDetails(
+  line: string,
+  qualifiers: string | string[]
+): QualifierInfo | null {
+  qualifiers = Array.isArray(qualifiers) ? qualifiers : [qualifiers];
+  const words = line.replace(/^\s+/, '').split(/\s+/);
+  // TODO add support for precession qualifiers (highp, mediump and lowp)
+  const [qualifier, type, definition] = words;
+  if (!qualifiers.includes(qualifier) || !type || !definition) {
+    return null;
+  }
+  const name = definition.split(';')[0];
+  return {qualifier, type, name};
+}
+
+/**
+ * Given the shader input and output variable names,
+ * builds and return a pass through fragment shader.
+ */
+export function getPassthroughFS(options?: {
+  input?: string;
+  inputChannels?: 1 | 2 | 3 | 4;
+  output?: string;
+}): string {
+  const {input, inputChannels, output} = options || {};
+  if (!input) {
+    // Default shader
+    return FS300;
+  }
+  if (!inputChannels) {
+    throw new Error('inputChannels');
+  }
+  const inputType = channelCountToType(inputChannels);
+  const outputValue = convertToVec4(input, inputChannels);
+  return `\
+#version 300 es
+in ${inputType} ${input};
+out vec4 ${output};
+void main() {
+  ${output} = ${outputValue};
+}`;
+}
+
+/** convert glsl type to suffix */
+export function typeToChannelSuffix(type: string): 'x' | 'xy' | 'xyz' | 'xyzw' {
+  // biome-ignore format: preserve layout
+  switch (type) {
+    case 'float': return 'x';
+    case 'vec2': return 'xy';
+    case 'vec3': return 'xyz';
+    case 'vec4': return 'xyzw';
+    default:
+      throw new Error(type);
+  }
+}
+
+/** convert glsl type to channel count */
+export function typeToChannelCount(type: string): 1 | 2 | 3 | 4 {
+  // biome-ignore format: preserve layout
+  switch (type) {
+    case 'float': return 1;
+    case 'vec2': return 2;
+    case 'vec3': return 3;
+    case 'vec4': return 4;
+    default:
+      throw new Error(type);
+  }
+}
+function channelCountToType(channels: 1 | 2 | 3 | 4): 'float' | 'vec2' | 'vec3' | 'vec4' {
+  // biome-ignore format: preserve layout
+  switch (channels) {
+    case 1: return 'float';
+    case 2: return 'vec2';
+    case 3: return 'vec3';
+    case 4: return 'vec4';
+    default:
+      throw new Error(`invalid channels: ${channels}`);
+  }
+}
+
+/** Returns glsl instruction for converting to vec4 */
+export function convertToVec4(variable: string, channels: 1 | 2 | 3 | 4): string {
+  // biome-ignore format: preserve layout
+  switch (channels) {
+    case 1: return `vec4(${variable}, 0.0, 0.0, 1.0)`;
+    case 2: return `vec4(${variable}, 0.0, 1.0)`;
+    case 3: return `vec4(${variable}, 1.0)`;
+    case 4: return variable;
+    default:
+      throw new Error(`invalid channels: ${channels}`);
+  }
+}

package/src/lib/preprocessor/preprocessor.ts

@@ -0,0 +1,157 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+const DEFINE_NAME_PATTERN = '([a-zA-Z_][a-zA-Z0-9_]*)';
+const IF_REGEXP = /^\s*\#\s*if\s+(.+?)\s*(?:\/\/.*)?$/;
+const IFDEF_REGEXP = new RegExp(`^\\s*\\#\\s*ifdef\\s*${DEFINE_NAME_PATTERN}\\s*$`);
+const IFNDEF_REGEXP = new RegExp(`^\\s*\\#\\s*ifndef\\s*${DEFINE_NAME_PATTERN}\\s*(?:\\/\\/.*)?$`);
+const ELSE_REGEXP = /^\s*\#\s*else\s*(?:\/\/.*)?$/;
+const ENDIF_REGEXP = /^\s*\#\s*endif\s*$/;
+const IFDEF_WITH_COMMENT_REGEXP = new RegExp(
+  `^\\s*\\#\\s*ifdef\\s*${DEFINE_NAME_PATTERN}\\s*(?:\\/\\/.*)?$`
+);
+const ENDIF_WITH_COMMENT_REGEXP = /^\s*\#\s*endif\s*(?:\/\/.*)?$/;
+
+/** Options for the luma.gl shader source preprocessor. */
+export type PreprocessorOptions = {
+  /** Boolean or numeric values used by `#if`, `#ifdef`, and `#ifndef` conditionals. */
+  defines?: Record<string, boolean | number>;
+};
+
+/**
+ * Removes inactive conditional branches from shader source.
+ * Supports `#ifdef`, `#ifndef`, and simple `#if` expressions using a define name,
+ * `!NAME`, `defined(NAME)`, `!defined(NAME)`, or a boolean or numeric literal.
+ * @param source Shader source containing luma.gl-supported conditional directives.
+ * @param options Defines used while evaluating conditional directives.
+ * @returns Shader source with inactive branches removed.
+ */
+export function preprocess(source: string, options?: PreprocessorOptions): string {
+  const lines = source.split('\n');
+  const output: string[] = [];
+
+  const conditionalStack: Array<{
+    parentActive: boolean;
+    branchTaken: boolean;
+    active: boolean;
+  }> = [];
+  let conditional = true;
+
+  for (const line of lines) {
+    const matchIfExpression = line.match(IF_REGEXP);
+    const matchIf = line.match(IFDEF_WITH_COMMENT_REGEXP) || line.match(IFDEF_REGEXP);
+    const matchIfNot = line.match(IFNDEF_REGEXP);
+    const matchElse = line.match(ELSE_REGEXP);
+    const matchEnd = line.match(ENDIF_WITH_COMMENT_REGEXP) || line.match(ENDIF_REGEXP);
+
+    if (matchIfExpression) {
+      const branchTaken: boolean = evaluateIfExpression(
+        matchIfExpression[1],
+        options?.defines || {}
+      );
+      const active: boolean = conditional && branchTaken;
+      conditionalStack.push({parentActive: conditional, branchTaken, active});
+      conditional = active;
+    } else if (matchIf || matchIfNot) {
+      const defineName = (matchIf || matchIfNot)?.[1];
+      const defineValue: boolean = Boolean(options?.defines?.[defineName!]);
+      const branchTaken: boolean = matchIf ? defineValue : !defineValue;
+      const active: boolean = conditional && branchTaken;
+      conditionalStack.push({parentActive: conditional, branchTaken, active});
+      conditional = active;
+    } else if (matchElse) {
+      const currentConditional = conditionalStack[conditionalStack.length - 1];
+      if (!currentConditional) {
+        throw new Error('Encountered #else without matching #if, #ifdef or #ifndef');
+      }
+      currentConditional.active =
+        currentConditional.parentActive && !currentConditional.branchTaken;
+      currentConditional.branchTaken = true;
+      conditional = currentConditional.active;
+    } else if (matchEnd) {
+      conditionalStack.pop();
+      conditional = conditionalStack.length
+        ? conditionalStack[conditionalStack.length - 1].active
+        : true;
+    } else if (conditional) {
+      output.push(line);
+    }
+  }
+
+  if (conditionalStack.length > 0) {
+    throw new Error('Unterminated conditional block in shader source');
+  }
+
+  return output.join('\n');
+}
+
+function evaluateIfExpression(
+  expression: string,
+  defines: Record<string, boolean | number>
+): boolean {
+  const trimmedExpression = expression.trim();
+
+  if (/^[+-]?\d+(?:\.\d+)?$/.test(trimmedExpression)) {
+    return Number(trimmedExpression) !== 0;
+  }
+
+  if (trimmedExpression === 'true') {
+    return true;
+  }
+
+  if (trimmedExpression === 'false') {
+    return false;
+  }
+
+  const operandPattern = '(?:[A-Za-z_][A-Za-z0-9_]*|[+-]?\\d+(?:\\.\\d+)?)';
+  const comparison = trimmedExpression.match(
+    new RegExp(`^(${operandPattern})\\s*(==|!=|<=|>=|<|>)\\s*(${operandPattern})$`)
+  );
+  if (comparison) {
+    const resolveOperand = (operand: string) =>
+      /^[A-Za-z_]/.test(operand) ? Number(defines[operand] ?? 0) : Number(operand);
+    const left = resolveOperand(comparison[1]);
+    const right = resolveOperand(comparison[3]);
+    switch (comparison[2]) {
+      case '==':
+        return left === right;
+      case '!=':
+        return left !== right;
+      case '<=':
+        return left <= right;
+      case '>=':
+        return left >= right;
+      case '<':
+        return left < right;
+      case '>':
+        return left > right;
+    }
+  }
+
+  const negatedDefineMatch = trimmedExpression.match(new RegExp(`^!\\s*${DEFINE_NAME_PATTERN}$`));
+  if (negatedDefineMatch) {
+    return !Boolean(defines[negatedDefineMatch[1]]);
+  }
+
+  const defineMatch = trimmedExpression.match(new RegExp(`^${DEFINE_NAME_PATTERN}$`));
+  if (defineMatch) {
+    return Boolean(defines[defineMatch[1]]);
+  }
+
+  const definedMatch = trimmedExpression.match(
+    new RegExp(`^defined\\s*\\(\\s*${DEFINE_NAME_PATTERN}\\s*\\)$`)
+  );
+  if (definedMatch) {
+    return defines[definedMatch[1]] !== undefined;
+  }
+
+  const negatedDefinedMatch = trimmedExpression.match(
+    new RegExp(`^!\\s*defined\\s*\\(\\s*${DEFINE_NAME_PATTERN}\\s*\\)$`)
+  );
+  if (negatedDefinedMatch) {
+    return defines[negatedDefinedMatch[1]] === undefined;
+  }
+
+  throw new Error(`Unsupported #if expression "${expression}"`);
+}

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

@@ -0,0 +1,169 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from './shader-module/shader-module';
+import {initializeShaderModules} from './shader-module/shader-module';
+import type {AssembleShaderProps} from './shader-assembly/shader-assembly-types';
+import type {ShaderInjectionTarget} from './shader-assembly/shader-injection-targets';
+import {assert} from './utils/assert';
+import type {
+  ShaderTranspiler,
+  ShaderTranspileResult,
+  ShaderTranspilerEntryPoints
+} from './shader-transpiler/shader-transpiler';
+import {getShaderModuleDependencies} from './shader-module/shader-module-dependencies';
+
+/**
+ * A stateful version of `assembleShaders` that can be used to assemble shaders.
+ * Supports setting of default modules and hooks.
+ */
+export abstract class ShaderAssembler {
+  /** Shader language accepted by this assembler. */
+  abstract readonly shaderLanguage: 'glsl' | 'wgsl';
+  /** Compilers registered by the application, isolated to this assembler. */
+  private readonly _shaderTranspilers = new Map<string, ShaderTranspiler>();
+  /** Hook functions */
+  protected readonly _injectionTargets: ShaderInjectionTarget[] = [];
+  /** Shader modules */
+  protected _defaultModules: ShaderModule[] = [];
+
+  /** Register or replace the compiler for one input language. */
+  addShaderTranspiler(transpiler: ShaderTranspiler): void {
+    this._shaderTranspilers.set(transpiler.sourceLanguage, transpiler);
+  }
+
+  /** Remove the compiler for one input language. */
+  removeShaderTranspiler(sourceLanguage: string): void {
+    this._shaderTranspilers.delete(sourceLanguage);
+  }
+
+  /** Translate application and reusable module source together before native assembly. */
+  protected _transpileShader(
+    props: AssembleShaderProps,
+    modules: ShaderModule[],
+    source: string | null | undefined,
+    stage?: 'vertex' | 'fragment' | 'compute'
+  ): ShaderTranspileResult & {modules: ShaderModule[]} {
+    const sourceLanguage = props.sourceLanguage || this.shaderLanguage;
+    if (sourceLanguage === this.shaderLanguage) {
+      // Foreign module code requires an application translation unit in the same language.
+      assert(
+        !getShaderModuleDependencies(modules).some(
+          module => module.sourceLanguage && module.sourceLanguage !== this.shaderLanguage
+        )
+      );
+      return {code: source || '', modules};
+    }
+    const transpiler = this._shaderTranspilers.get(sourceLanguage);
+    // The application must register a transpiler before assembling a foreign input language.
+    assert(transpiler);
+    const dependencies = getShaderModuleDependencies(modules);
+    // A translation unit can contain only one foreign source language.
+    assert(
+      !dependencies.some(
+        module =>
+          module.sourceLanguage &&
+          module.sourceLanguage !== sourceLanguage &&
+          module.sourceLanguage !== this.shaderLanguage
+      )
+    );
+    const moduleSource = dependencies
+      .filter(module => module.sourceLanguage === sourceLanguage)
+      .map(module => module.source || '')
+      .join('\n');
+    const entryPoints: ShaderTranspilerEntryPoints = {
+      vertex: props.vertexEntryPoint,
+      fragment: props.fragmentEntryPoint,
+      compute: props.computeEntryPoint
+    };
+    const result =
+      source === undefined || source === null
+        ? {code: ''}
+        : transpiler!.transpile({
+            source: [moduleSource, source].filter(Boolean).join('\n'),
+            target: this.shaderLanguage,
+            stage,
+            entryPoints,
+            platformInfo: props.platformInfo
+          });
+    // Preserve uniform metadata and target-language code without emitting foreign source twice.
+    const nativeModules = dependencies.map(module => ({
+      ...module,
+      dependencies: undefined,
+      ...(module.sourceLanguage === sourceLanguage
+        ? {source: undefined, vs: undefined, fs: undefined}
+        : {})
+    }));
+    return {...result, modules: nativeModules};
+  }
+
+  /**
+   * Add a default module that does not have to be provided with every assembly call.
+   * @param module Shader module to include in later assembly calls.
+   */
+  addDefaultModule(module: ShaderModule): void {
+    if (
+      !this._defaultModules.find(
+        m => m.name === (typeof module === 'string' ? module : module.name)
+      )
+    ) {
+      this._defaultModules.push(module);
+    }
+  }
+
+  /**
+   * Remove a default module
+   * @param module Shader module to remove from later assembly calls.
+   */
+  removeDefaultModule(module: ShaderModule): void {
+    const moduleName = typeof module === 'string' ? module : module.name;
+    this._defaultModules = this._defaultModules.filter(m => m.name !== moduleName);
+  }
+
+  /**
+   * Register a shader injection target
+   * @param injectionTarget Shared stage and name with language-specific parameters, return type, and source.
+   */
+  addShaderInjectionTarget(injectionTarget: ShaderInjectionTarget): void {
+    this._injectionTargets.push(injectionTarget);
+  }
+
+  /**
+   * Remove all registered shader injection targets, for example before re-registering targets for a new
+   * application configuration. Default modules are not affected.
+   */
+  resetShaderInjectionTargets(): void {
+    this._injectionTargets.length = 0;
+  }
+
+  /**
+   * Dedupe and combine with default modules
+   */
+  _getModuleList(appModules: ShaderModule[] = []): ShaderModule[] {
+    const modules = new Array<ShaderModule>(this._defaultModules.length + appModules.length);
+    const seen: Record<string, boolean> = {};
+    let count = 0;
+
+    for (let i = 0, len = this._defaultModules.length; i < len; ++i) {
+      const module = this._defaultModules[i];
+      const name = module.name;
+      modules[count++] = module;
+      seen[name] = true;
+    }
+
+    for (let i = 0, len = appModules.length; i < len; ++i) {
+      const module = appModules[i];
+      const name = module.name;
+      if (!seen[name]) {
+        modules[count++] = module;
+        seen[name] = true;
+      }
+    }
+
+    modules.length = count;
+
+    initializeShaderModules(modules);
+    return modules;
+  }
+}

package/src/lib/shader-assembler.ts

@@ -0,0 +1,7 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {ShaderAssembler} from './shader-assembler-base';
+export {GLSLShaderAssembler} from './glsl-shader-assembler';
+export {WGSLShaderAssembler} from './wgsl-shader-assembler';