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

package/src/lib/preprocessor/preprocessor.ts

@@ -0,0 +1,132 @@
+// 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 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,170 @@
+// 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 {ShaderHook, ShaderHookOptions} from './shader-assembly/shader-hooks';
+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 _hookFunctions: (ShaderHook | string)[] = [];
+  /** 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 hook
+   * @param hook Stage-prefixed hook signature, such as `vs:OFFSET_POSITION(inout vec4 position)`.
+   * @param options Optional hook metadata such as always-on header and footer source.
+   */
+  addShaderHook(hook: string, options?: ShaderHookOptions): void {
+    this._hookFunctions.push(options ? {...options, hook} : hook);
+  }
+
+  /**
+   * Remove all registered shader hooks, for example before re-registering hooks for a new
+   * application configuration. Default modules are not affected.
+   */
+  resetShaderHooks(): void {
+    this._hookFunctions.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';

package/src/lib/shader-assembly/assemble-glsl-shaders.ts

@@ -0,0 +1,305 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {getShaderModuleDependencies} from '../shader-module/shader-module-dependencies';
+import {
+  type AssembleShaderOptions,
+  type GetUniformsFunc,
+  type ShaderAssemblyLog
+} from './shader-assembly-types';
+import {
+  assembleGetUniforms,
+  appendInjections,
+  getShaderModuleSource,
+  INJECT_SHADER_DECLARATIONS
+} from './shader-assembly-shared';
+import {PlatformInfo} from './platform-info';
+import {type ShaderModule, checkShaderModuleDeprecations} from '../shader-module/shader-module';
+import {
+  type ShaderHook,
+  normalizeShaderHooks,
+  validateShaderHookInjections,
+  getShaderHooks
+} from './shader-hooks';
+import {type ShaderInjection, injectShader} from './shader-injections';
+import {type AttributeShaderType} from '../../types';
+import {type ResolvedShaderPluginVarying} from '../shader-plugin';
+import {assert} from '../utils/assert';
+import {getShaderInfo} from '../glsl-utils/get-shader-info';
+import {getPlatformShaderDefines} from './platform-defines';
+import {getShaderPluginVertexInputDeclarationsGLSL} from './shader-plugin-vertex-inputs';
+import {assembleShaderPluginVaryingsGLSL} from './shader-plugin-varyings';
+import {transpileGLSLShader} from '../shader-transpiler/transpile-glsl-shader';
+import {warnIfGLSLUniformBlocksAreNotStd140} from '../shader-module/shader-module-uniform-layout';
+
+/**
+ * Precision prologue to inject before functions are injected in shader
+ * TODO - extract any existing prologue in the fragment source and move it up...
+ */
+export const FRAGMENT_SHADER_PROLOGUE = /* glsl */ `\
+precision highp float;
+`;
+
+/**
+ * Injects dependent shader module sources into pair of main vertex/fragment shader sources for GLSL
+ */
+export function assembleGLSLShaderPair(
+  options: AssembleShaderOptions & {
+    /** Vertex shader */
+    vs: string;
+    /** Fragment shader */
+    fs?: string;
+  }
+): {
+  vs: string;
+  fs: string;
+  getUniforms: GetUniformsFunc;
+} {
+  const {vs, fs} = options;
+  const modules = getShaderModuleDependencies(options.modules || []);
+
+  return {
+    vs: assembleShaderGLSL(options.platformInfo, {
+      ...options,
+      source: vs,
+      stage: 'vertex',
+      modules
+    }),
+    fs: assembleShaderGLSL(options.platformInfo, {
+      ...options,
+      // @ts-expect-error
+      source: fs,
+      stage: 'fragment',
+      modules
+    }),
+    getUniforms: assembleGetUniforms(modules)
+  };
+}
+
+/**
+ * Pulls together complete source code for either a vertex or a fragment shader
+ * adding prologues, requested module chunks, and any final injections.
+ * @param gl
+ * @param options
+ * @returns
+ */
+export function assembleShaderGLSL(
+  platformInfo: PlatformInfo,
+  options: {
+    id?: string;
+    source: string;
+    language?: 'glsl' | 'wgsl';
+    stage: 'vertex' | 'fragment';
+    modules: ShaderModule[];
+    defines?: Record<string, boolean | number>;
+    hookFunctions?: readonly (ShaderHook | string)[];
+    inject?: Record<string, string | ShaderInjection>;
+    pluginInjections?: Record<string, ShaderInjection[]>;
+    pluginVertexInputs?: Record<string, AttributeShaderType>;
+    pluginVaryings?: Record<string, ResolvedShaderPluginVarying>;
+    prologue?: boolean;
+    log?: ShaderAssemblyLog;
+  }
+) {
+  const {
+    source,
+    stage,
+    language = 'glsl',
+    modules,
+    defines = {},
+    hookFunctions = [],
+    inject = {},
+    pluginInjections = {},
+    pluginVertexInputs = {},
+    pluginVaryings = {},
+    prologue = true,
+    log
+  } = options;
+
+  assert(typeof source === 'string', 'shader source must be a string');
+
+  const sourceVersion = language === 'glsl' ? getShaderInfo(source).version : -1;
+  const targetVersion = platformInfo.shaderLanguageVersion;
+
+  const sourceVersionDirective = sourceVersion === 100 ? '#version 100' : '#version 300 es';
+
+  const sourceLines = source.split('\n');
+  // TODO : keep all pre-processor statements at the beginning of the shader.
+  const coreSource = sourceLines.slice(1).join('\n');
+
+  // Combine Module and Application Defines
+  const allDefines = {};
+  modules.forEach(module => {
+    Object.assign(allDefines, module.defines);
+  });
+  Object.assign(allDefines, defines);
+
+  // Add platform defines (use these to work around platform-specific bugs and limitations)
+  // Add common defines (GLSL version compatibility, feature detection)
+  // Add precision declaration for fragment shaders
+  let assembledSource = '';
+  switch (language) {
+    case 'wgsl':
+      break;
+    case 'glsl':
+      assembledSource = prologue
+        ? `\
+${sourceVersionDirective}
+
+// ----- PROLOGUE -------------------------
+${`#define SHADER_TYPE_${stage.toUpperCase()}`}
+
+${getPlatformShaderDefines(platformInfo)}
+${stage === 'fragment' ? FRAGMENT_SHADER_PROLOGUE : ''}
+
+// ----- APPLICATION DEFINES -------------------------
+
+${getApplicationDefines(allDefines)}
+
+`
+        : `${sourceVersionDirective}
+`;
+      break;
+  }
+
+  const hookFunctionMap = normalizeShaderHooks(hookFunctions);
+
+  // Add source of dependent modules in resolved order
+  const hookInjections: Record<string, ShaderInjection[]> = {};
+  const declInjections: Record<string, ShaderInjection[]> = {};
+  const mainInjections: Record<string, ShaderInjection[]> = {};
+
+  appendInjections(pluginInjections, hookInjections, declInjections, mainInjections);
+
+  for (const key in inject) {
+    const injection: ShaderInjection =
+      typeof inject[key] === 'string' ? {injection: inject[key], order: 0} : inject[key];
+    const match = /^(v|f)s:(#)?([\w-]+)$/.exec(key);
+    if (match) {
+      const hash = match[2];
+      const name = match[3];
+      if (hash) {
+        if (name === 'decl') {
+          declInjections[key] = [injection];
+        } else {
+          mainInjections[key] = [injection];
+        }
+      } else {
+        hookInjections[key] = [injection];
+      }
+    } else {
+      // Regex injection
+      mainInjections[key] = [injection];
+    }
+  }
+  if (stage === 'vertex') {
+    const declarations = getShaderPluginVertexInputDeclarationsGLSL(coreSource, pluginVertexInputs);
+    if (declarations) {
+      declInjections['vs:#decl'] = declInjections['vs:#decl'] || [];
+      declInjections['vs:#decl'].push({
+        injection: declarations,
+        order: Number.MIN_SAFE_INTEGER
+      });
+    }
+  }
+  const pluginVaryingAssembly = assembleShaderPluginVaryingsGLSL(coreSource, stage, pluginVaryings);
+  if (pluginVaryingAssembly.declarations) {
+    const declarationTarget = stage === 'vertex' ? 'vs:#decl' : 'fs:#decl';
+    declInjections[declarationTarget] = declInjections[declarationTarget] || [];
+    declInjections[declarationTarget].push({
+      injection: pluginVaryingAssembly.declarations,
+      order: Number.MIN_SAFE_INTEGER
+    });
+  }
+  if (pluginVaryingAssembly.initialization) {
+    mainInjections['vs:#main-start'] = mainInjections['vs:#main-start'] || [];
+    mainInjections['vs:#main-start'].push({
+      injection: pluginVaryingAssembly.initialization,
+      order: Number.MIN_SAFE_INTEGER
+    });
+  }
+
+  for (const module of modules) {
+    if (log) {
+      checkShaderModuleDeprecations(module, coreSource, log);
+    }
+    const moduleSource = getShaderModuleSource(module, stage, log);
+    // Add the module source, and a #define that declares it presence
+    assembledSource += moduleSource;
+
+    const injections = module.instance?.normalizedInjections[stage] || {};
+    for (const key in injections) {
+      const match = /^(v|f)s:#([\w-]+)$/.exec(key);
+      if (match) {
+        const name = match[2];
+        const injectionType = name === 'decl' ? declInjections : mainInjections;
+        injectionType[key] = injectionType[key] || [];
+        injectionType[key].push(injections[key]);
+      } else {
+        hookInjections[key] = hookInjections[key] || [];
+        hookInjections[key].push(injections[key]);
+      }
+    }
+  }
+
+  // GLSL module injections are GLSL source, so application, plugin, and module hook targets must exist.
+  validateShaderHookInjections(hookFunctionMap, hookInjections, stage);
+
+  assembledSource += '// ----- MAIN SHADER SOURCE -------------------------';
+
+  // For injectShader
+  assembledSource += INJECT_SHADER_DECLARATIONS;
+
+  assembledSource = injectShader(assembledSource, stage, declInjections);
+
+  assembledSource += getShaderHooks(hookFunctionMap[stage], hookInjections);
+
+  // Add the version directive and actual source of this shader
+  assembledSource += coreSource;
+
+  // Apply any requested shader injections
+  assembledSource = injectShader(assembledSource, stage, mainInjections);
+
+  if (language === 'glsl' && sourceVersion !== targetVersion) {
+    assembledSource = transpileGLSLShader(assembledSource, stage);
+  }
+
+  if (language === 'glsl') {
+    warnIfGLSLUniformBlocksAreNotStd140(assembledSource, stage, log);
+  }
+
+  return assembledSource.trim();
+}
+
+/**
+ * NOTE: Removed as id injection defeated caching of shaders
+ *
+ * Generate "glslify-compatible" SHADER_NAME defines
+ * These are understood by the GLSL error parsing function
+ * If id is provided and no SHADER_NAME constant is present in source, create one
+ unction getShaderNameDefine(options: {
+  id?: string;
+  source: string;
+  stage: 'vertex' | 'fragment';
+}): string {
+  const {id, source, stage} = options;
+  const injectShaderName = id && source.indexOf('SHADER_NAME') === -1;
+  return injectShaderName
+    ? `
+#define SHADER_NAME ${id}_${stage}`
+    : '';
+}
+*/
+
+/** Generates application defines from an object of key value pairs */
+export function getApplicationDefines(defines: Record<string, boolean | number> = {}): string {
+  let sourceText = '';
+  for (const define in defines) {
+    const value = defines[define];
+    if (value || Number.isFinite(value)) {
+      sourceText += `#define ${define.toUpperCase()} ${defines[define]}\n`;
+    }
+  }
+  return sourceText;
+}

package/src/lib/shader-assembly/assemble-shaders.ts

@@ -0,0 +1,13 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export type {AssembleShaderProps} from './shader-assembly-types';
+export type {AssembleShaderOptions} from './shader-assembly-types';
+export type {GetUniformsFunc} from './shader-assembly-types';
+export {assembleWGSLShader} from './assemble-wgsl-shaders';
+export {assembleWGSLSource} from './assemble-wgsl-shaders';
+export {assembleGLSLShaderPair} from './assemble-glsl-shaders';
+export {assembleShaderWGSL} from './assemble-wgsl-shaders';
+export {assembleGetUniforms} from './shader-assembly-shared';
+export {getShaderModuleSource} from './shader-assembly-shared';