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

package/src/index.ts

@@ -14,13 +14,33 @@ export type {ShaderBindingDebugRow} from './lib/shader-assembly/wgsl-binding-deb
 // ShaderModules
 
 export type {ShaderModule} from './lib/shader-module/shader-module';
-export type {ShaderPass} from './lib/shader-module/shader-pass';
+export type {
+  ResolvedShaderPlugins,
+  ResolvedShaderPluginVarying,
+  ShaderPlugin,
+  ShaderPluginInjection,
+  ShaderPluginInjectionTarget,
+  ShaderPluginVarying,
+  ShaderPluginVaryingInterpolation,
+  ShaderPluginVariant
+} from './lib/shader-plugin';
+export type {
+  ShaderPass,
+  ShaderPassInputSource,
+  ShaderPassRenderTarget,
+  ShaderSubPass
+} from './lib/shader-module/shader-pass';
+export type {
+  ShaderPassPipeline,
+  ShaderPassPipelineStep
+} from './lib/shader-module/shader-pass-pipeline';
 export type {ShaderModuleUniformValue, UniformTypes} from './lib/utils/uniform-types';
 
 export {initializeShaderModule, initializeShaderModules} from './lib/shader-module/shader-module';
 export {getShaderModuleUniforms} from './lib/shader-module/shader-module';
 export {getShaderModuleDependencies} from './lib/shader-module/shader-module-dependencies';
 export {checkShaderModuleDeprecations} from './lib/shader-module/shader-module';
+export {mergeShaderPluginModules, resolveShaderPlugins} from './lib/shader-plugin';
 export type {
   GLSLUniformBlockInfo,
   ShaderModuleUniformLayoutStage,
@@ -81,8 +101,26 @@ export {random} from './modules/math/random/random';
 
 export {fp32} from './modules/math/fp32/fp32';
 export {fp64, fp64arithmetic} from './modules/math/fp64/fp64';
-export type {FloatColorsProps, FloatColorsUniforms} from './modules/color/float-colors';
-export {floatColors} from './modules/color/float-colors';
+export {dggs} from './modules/geospatial/dggs/dggs';
+export type {
+  ColorsProps,
+  ColorsUniforms,
+  FloatColorsProps,
+  FloatColorsUniforms,
+  StorageColorFormat,
+  StorageColorFormatValue,
+  StorageColorsBindings,
+  StorageColorsProps,
+  StorageColorsUniforms
+} from './modules/color/float-colors';
+export {
+  colors,
+  floatColors,
+  STORAGE_COLOR_DEFAULT_BYTE_STRIDES,
+  STORAGE_COLOR_FORMAT,
+  STORAGE_COLOR_FORMAT_BYTE_LENGTHS,
+  storageColors
+} from './modules/color/float-colors';
 
 // engine shader modules
 
@@ -91,6 +129,10 @@ export {floatColors} from './modules/color/float-colors';
 // export {projection} from './modules/engine/project/project';
 export type {PickingProps, PickingUniforms} from './modules/engine/picking/picking';
 export {picking} from './modules/engine/picking/picking';
+export type {FilterShaderPluginProps} from './modules/engine/filter/filter';
+export {filterShaderPlugin} from './modules/engine/filter/filter';
+export type {ClipShaderPluginProps} from './modules/engine/clip/clip';
+export {clipShaderPlugin} from './modules/engine/clip/clip';
 export {skin} from './modules/engine/skin/skin';
 
 // lighting
@@ -114,6 +156,11 @@ export type {GouraudMaterialProps} from './modules/lighting/gouraud-material/gou
 export {gouraudMaterial} from './modules/lighting/gouraud-material/gouraud-material';
 export type {PhongMaterialProps} from './modules/lighting/phong-material/phong-material';
 export {phongMaterial} from './modules/lighting/phong-material/phong-material';
+export type {
+  WaterMaterialProps,
+  WaterMaterialUniforms
+} from './modules/lighting/water-material/water-material';
+export {waterMaterial} from './modules/lighting/water-material/water-material';
 export type {
   PBRMaterialBindings,
   PBRMaterialProps,

package/src/lib/preprocessor/preprocessor.ts

@@ -3,6 +3,7 @@
 // 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*(?:\/\/.*)?$/;
@@ -12,10 +13,20 @@ const IFDEF_WITH_COMMENT_REGEXP = new RegExp(
 );
 const ENDIF_WITH_COMMENT_REGEXP = /^\s*\#\s*endif\s*(?:\/\/.*)?$/;
 
+/** Options for the luma.gl shader source preprocessor. */
 export type PreprocessorOptions = {
-  defines?: Record<string, boolean>;
+  /** 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[] = [];
@@ -28,12 +39,21 @@ export function preprocess(source: string, options?: PreprocessorOptions): strin
   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 (matchIf || matchIfNot) {
+    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;
@@ -43,7 +63,7 @@ export function preprocess(source: string, options?: PreprocessorOptions): strin
     } else if (matchElse) {
       const currentConditional = conditionalStack[conditionalStack.length - 1];
       if (!currentConditional) {
-        throw new Error('Encountered #else without matching #ifdef or #ifndef');
+        throw new Error('Encountered #else without matching #if, #ifdef or #ifndef');
       }
       currentConditional.active =
         currentConditional.parentActive && !currentConditional.branchTaken;
@@ -65,3 +85,48 @@ export function preprocess(source: string, options?: PreprocessorOptions): strin
 
   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.ts

@@ -32,7 +32,7 @@ export class ShaderAssembler {
 
   /**
    * A default shader assembler instance - the natural place to register default modules and hooks
-   * @returns
+   * @returns Shared default shader assembler.
    */
   static getDefaultShaderAssembler(): ShaderAssembler {
     ShaderAssembler.defaultShaderAssembler =
@@ -41,7 +41,8 @@ export class ShaderAssembler {
   }
 
   /**
-   * Add a default module that does not have to be provided with every call to assembleShaders()
+   * 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 (
@@ -55,6 +56,7 @@ export class ShaderAssembler {
 
   /**
    * 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;
@@ -63,8 +65,8 @@ export class ShaderAssembler {
 
   /**
    * Register a shader hook
-   * @param hook
-   * @param opts
+   * @param hook Stage-prefixed hook signature, such as `vs:OFFSET_POSITION(inout vec4 position)`.
+   * @param opts Optional hook metadata such as always-on header and footer source.
    */
   addShaderHook(hook: string, opts?: any): void {
     if (opts) {
@@ -75,9 +77,8 @@ export class ShaderAssembler {
 
   /**
    * Assemble a WGSL unified shader
-   * @param platformInfo
-   * @param props
-   * @returns
+   * @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;
@@ -88,24 +89,29 @@ export class ShaderAssembler {
   } {
     const modules = this._getModuleList(props.modules); // Combine with default modules
     const hookFunctions = this._hookFunctions; // TODO - combine with default hook functions
-    const {source, getUniforms, bindingAssignments} = assembleWGSLShader({
+    const defines = getShaderPreprocessorDefines(props, modules);
+    const preprocessedApplicationSource =
+      props.platformInfo.shaderLanguage === 'wgsl' && props.source
+        ? preprocess(props.source, {defines})
+        : props.source;
+    const {
+      source: assembledSource,
+      getUniforms,
+      bindingAssignments
+    } = assembleWGSLShader({
       ...props,
       // @ts-expect-error
-      source: props.source,
+      source: preprocessedApplicationSource,
+      defines,
       _bindingRegistry: this._wgslBindingRegistry,
       modules,
       hookFunctions
     });
-    const defines = {
-      ...modules.reduce<Record<string, boolean>>((accumulator, module) => {
-        Object.assign(accumulator, module.defines);
-        return accumulator;
-      }, {}),
-      ...props.defines
-    };
     // WGSL does not have built-in preprocessing support (just compile time constants)
     const preprocessedSource =
-      props.platformInfo.shaderLanguage === 'wgsl' ? preprocess(source, {defines}) : source;
+      props.platformInfo.shaderLanguage === 'wgsl'
+        ? preprocess(assembledSource, {defines})
+        : assembledSource;
     return {
       source: preprocessedSource,
       getUniforms,
@@ -117,9 +123,8 @@ export class ShaderAssembler {
 
   /**
    * Assemble a pair of shaders into a single shader program
-   * @param platformInfo
-   * @param props
-   * @returns
+   * @param props GLSL vertex and fragment source, platform information, shader modules, defines, and injections.
+   * @returns Assembled GLSL source, resolved modules, and combined uniform getter.
    */
   assembleGLSLShaderPair(props: AssembleShaderProps): {
     vs: string;
@@ -172,3 +177,27 @@ export class ShaderAssembler {
     return modules;
   }
 }
+
+function getShaderPreprocessorDefines(
+  props: AssembleShaderProps,
+  modules: ShaderModule[]
+): Record<string, boolean | number> {
+  return {
+    ...getPlatformPreprocessorDefines(props.platformInfo),
+    ...modules.reduce<Record<string, boolean | number>>((accumulator, module) => {
+      Object.assign(accumulator, module.defines);
+      return accumulator;
+    }, {}),
+    ...props.defines
+  };
+}
+
+function getPlatformPreprocessorDefines(
+  platformInfo: AssembleShaderProps['platformInfo']
+): Record<string, boolean> {
+  const limits = platformInfo.limits || {};
+  return {
+    LUMA_SUPPORTS_VERTEX_STORAGE_BUFFERS:
+      platformInfo.type === 'webgpu' && (limits['maxStorageBuffersInVertexStage'] || 0) > 0
+  };
+}