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

package/src/lib/shader-assembly/platform-defines.ts

@@ -0,0 +1,58 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {PlatformInfo} from './platform-info';
+
+/** Adds defines to help identify GPU architecture / platform */
+export function getPlatformShaderDefines(platformInfo: PlatformInfo): string {
+  switch (platformInfo?.gpu.toLowerCase()) {
+    case 'apple':
+      return /* glsl */ `\
+#define APPLE_GPU
+// Apple optimizes away the calculation necessary for emulated fp64
+#define LUMA_FP64_CODE_ELIMINATION_WORKAROUND 1
+#define LUMA_FP32_TAN_PRECISION_WORKAROUND 1
+// Intel GPU doesn't have full 32 bits precision in same cases, causes overflow
+#define LUMA_FP64_HIGH_BITS_OVERFLOW_WORKAROUND 1
+`;
+
+    case 'nvidia':
+      return /* glsl */ `\
+#define NVIDIA_GPU
+// Nvidia optimizes away the calculation necessary for emulated fp64
+#define LUMA_FP64_CODE_ELIMINATION_WORKAROUND 1
+`;
+
+    case 'intel':
+      return /* glsl */ `\
+#define INTEL_GPU
+// Intel optimizes away the calculation necessary for emulated fp64
+#define LUMA_FP64_CODE_ELIMINATION_WORKAROUND 1
+// Intel's built-in 'tan' function doesn't have acceptable precision
+#define LUMA_FP32_TAN_PRECISION_WORKAROUND 1
+// Intel GPU doesn't have full 32 bits precision in same cases, causes overflow
+#define LUMA_FP64_HIGH_BITS_OVERFLOW_WORKAROUND 1
+`;
+
+    case 'amd':
+      // AMD Does not eliminate fp64 code
+      return /* glsl */ `\
+#define AMD_GPU
+`;
+
+    default:
+      // We don't know what GPU it is, could be that the GPU driver or
+      // browser is not implementing UNMASKED_RENDERER constant and not
+      // reporting a correct name
+      return /* glsl */ `\
+#define DEFAULT_GPU
+// Prevent driver from optimizing away the calculation necessary for emulated fp64
+#define LUMA_FP64_CODE_ELIMINATION_WORKAROUND 1
+// Headless Chrome's software shader 'tan' function doesn't have acceptable precision
+#define LUMA_FP32_TAN_PRECISION_WORKAROUND 1
+// If the GPU doesn't have full 32 bits precision, will causes overflow
+#define LUMA_FP64_HIGH_BITS_OVERFLOW_WORKAROUND 1
+`;
+  }
+}

package/src/lib/shader-assembly/platform-info.ts

@@ -0,0 +1,23 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/**
+ * PlatformInfo
+ * @note Designed so that it can be easily created from a luma.gl Device instance
+ * Without having any actual dependency on `@luma.gl/core`
+ */
+export type PlatformInfo = {
+  /** Current Web GPU API backend */
+  type: 'webgl' | 'webgpu' | 'null' | 'unknown';
+  /** Which shader language is supported */
+  shaderLanguage: 'glsl' | 'wgsl';
+  /** Which shader language version is preferred */
+  shaderLanguageVersion: 100 | 300;
+  /** string identifying current GPU */
+  gpu: string;
+  /** Device limits exposed to shader preprocessing decisions such as platform capability defines. */
+  limits?: Record<string, number | undefined>;
+  /** Feature strings for feature detection */
+  features: Set<string>;
+};

package/src/lib/shader-assembly/shader-assembly-shared.ts

@@ -0,0 +1,95 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {DECLARATION_INJECT_MARKER, type ShaderInjection} from './shader-injections';
+import {type ShaderModule} from '../shader-module/shader-module';
+import {assert} from '../utils/assert';
+import {validateShaderModuleUniformLayout} from '../shader-module/shader-module-uniform-layout';
+
+export const INJECT_SHADER_DECLARATIONS = `\n\n${DECLARATION_INJECT_MARKER}\n`;
+
+/**
+ * Returns a combined `getUniforms` covering the options for all the modules,
+ * the created function will pass on options to the inidividual `getUniforms`
+ * function of each shader module and combine the results into one object that
+ * can be passed to setUniforms.
+ * @param modules
+ * @returns
+ */
+export function assembleGetUniforms(modules: ShaderModule[]) {
+  return function getUniforms(opts: Record<string, any>): Record<string, any> {
+    const uniforms = {};
+    for (const module of modules) {
+      // `modules` is already sorted by dependency level. This guarantees that
+      // modules have access to the uniforms that are generated by their dependencies.
+      const moduleUniforms = module.getUniforms?.(opts, uniforms);
+      Object.assign(uniforms, moduleUniforms);
+    }
+    return uniforms;
+  };
+}
+
+export function appendInjections(
+  injections: Record<string, ShaderInjection[]>,
+  hookInjections: Record<string, ShaderInjection[]>,
+  declInjections: Record<string, ShaderInjection[]>,
+  mainInjections: Record<string, ShaderInjection[]>
+): void {
+  for (const key in injections) {
+    const match = /^(v|f)s:(#)?([\w-]+)$/.exec(key);
+    if (match) {
+      const hash = match[2];
+      const name = match[3];
+      const injectionType = hash
+        ? name === 'decl'
+          ? declInjections
+          : mainInjections
+        : hookInjections;
+      injectionType[key] = injectionType[key] || [];
+      injectionType[key].push(...injections[key]);
+    } else {
+      mainInjections[key] = mainInjections[key] || [];
+      mainInjections[key].push(...injections[key]);
+    }
+  }
+}
+
+/** Extracts the source code chunk for the specified shader type from the named shader module */
+export function getShaderModuleSource(
+  module: ShaderModule,
+  stage: 'vertex' | 'fragment' | 'wgsl',
+  log?: any
+): string {
+  let moduleSource;
+  switch (stage) {
+    case 'vertex':
+      moduleSource = module.vs || '';
+      break;
+    case 'fragment':
+      moduleSource = module.fs || '';
+      break;
+    case 'wgsl':
+      moduleSource = module.source || '';
+      break;
+    default:
+      assert(false);
+  }
+
+  if (!module.name) {
+    throw new Error('Shader module must have a name');
+  }
+
+  validateShaderModuleUniformLayout(module, stage, {log});
+
+  const moduleName = module.name.toUpperCase().replace(/[^0-9a-z]/gi, '_');
+  let source = `\
+// ----- MODULE ${module.name} ---------------
+
+`;
+  if (stage !== 'wgsl') {
+    source += `#define MODULE_${moduleName}\n`;
+  }
+  source += `${moduleSource}\n`;
+  return source;
+}

package/src/lib/shader-assembly/shader-assembly-types.ts

@@ -0,0 +1,142 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {type PlatformInfo} from './platform-info';
+import {type ShaderModule} from '../shader-module/shader-module';
+import {type ShaderHook} from './shader-hooks';
+import {type ShaderInjection} from './shader-injections';
+import {type AttributeShaderType} from '../../types';
+import {type ResolvedShaderPluginVarying} from '../shader-plugin';
+
+export type ShaderAssemblyLog = {
+  deprecated?: (...args: unknown[]) => () => unknown;
+  removed?: (...args: unknown[]) => () => unknown;
+  warn?: (...args: unknown[]) => () => unknown;
+};
+
+/** Props accepted by `ShaderAssembler` assembly methods. */
+export type AssembleShaderProps = AssembleShaderOptions & {
+  platformInfo: PlatformInfo;
+  /** WGSL: single shader source. */
+  source?: string | null;
+  /** GLSL vertex shader source. */
+  vs?: string | null;
+  /** GLSL fragment shader source. */
+  fs?: string | null;
+};
+
+/** Shared shader assembly options. */
+export type AssembleShaderOptions = {
+  /** information about the platform (which shader language & version, extensions etc.) */
+  platformInfo: PlatformInfo;
+  /** Inject shader id #defines */
+  id?: string;
+  /** Input language compiled by a registered ShaderAssembler transpiler. Defaults to the target language. */
+  sourceLanguage?: string;
+  /** Select compute compilation independently of an optional WGSL entry-point name. */
+  shaderStage?: 'compute';
+  /** WGSL compute entry point selected by the compute pipeline. */
+  computeEntryPoint?: string;
+  /** Modules to be injected */
+  modules?: ShaderModule[];
+  /** Boolean or numeric preprocessor defines evaluated before shader assembly. */
+  defines?: Record<string, boolean | number>;
+  /** GLSL only: Overrides to be injected. In WGSL these are supplied during Pipeline creation time */
+  constants?: Record<string, number>;
+  /** Hook functions */
+  hookFunctions?: readonly (ShaderHook | string)[];
+  /** Code injections */
+  inject?: Record<string, string | ShaderInjection>;
+  /** Ordered code injections contributed by ShaderPlugin descriptors. */
+  pluginInjections?: Record<string, ShaderInjection[]>;
+  /** Vertex inputs contributed by ShaderPlugin descriptors. */
+  pluginVertexInputs?: Record<string, AttributeShaderType>;
+  /** Cross-stage varyings contributed by ShaderPlugin descriptors. */
+  pluginVaryings?: Record<string, ResolvedShaderPluginVarying>;
+  /** WGSL vertex entry point selected by the render pipeline. */
+  vertexEntryPoint?: string;
+  /** Whether WGSL interface scanning should include vertex attributes. */
+  scanVertexAttributes?: boolean;
+  /** WGSL fragment entry point selected by the render pipeline. */
+  fragmentEntryPoint?: string;
+  /** Whether to inject prologue */
+  prologue?: boolean;
+  /** logger object */
+  log?: ShaderAssemblyLog;
+};
+
+export type AssembleStageOptions = {
+  /** Inject shader id #defines */
+  id?: string;
+  /** Vertex shader */
+  source: string;
+  stage: 'vertex' | 'fragment';
+  /** Modules to be injected */
+  modules: any[];
+  /** Boolean or numeric preprocessor defines evaluated before shader assembly. */
+  defines?: Record<string, boolean | number>;
+  /** GLSL only: Overrides to be injected. In WGSL these are supplied during Pipeline creation time */
+  constants?: Record<string, number>;
+  /** Hook functions */
+  hookFunctions?: readonly (ShaderHook | string)[];
+  /** Code injections */
+  inject?: Record<string, string | ShaderInjection>;
+  /** Ordered code injections contributed by ShaderPlugin descriptors. */
+  pluginInjections?: Record<string, ShaderInjection[]>;
+  /** Vertex inputs contributed by ShaderPlugin descriptors. */
+  pluginVertexInputs?: Record<string, AttributeShaderType>;
+  /** Cross-stage varyings contributed by ShaderPlugin descriptors. */
+  pluginVaryings?: Record<string, ResolvedShaderPluginVarying>;
+  /** WGSL vertex entry point selected by the render pipeline. */
+  vertexEntryPoint?: string;
+  /** WGSL fragment entry point selected by the render pipeline. */
+  fragmentEntryPoint?: string;
+  /** Whether to inject prologue */
+  prologue?: boolean;
+  /** logger object */
+  log?: ShaderAssemblyLog;
+  /** @internal Stable per-assembler WGSL binding assignments. */
+  _bindingRegistry?: Map<string, number>;
+};
+
+/**
+ * getUniforms function returned from the shader module system
+ */
+export type GetUniformsFunc = (opts: Record<string, any>) => Record<string, any>;
+
+export type AssembleWGSLShaderOptions = AssembleShaderOptions & {
+  /** Single WGSL shader */
+  source: string;
+  /** @internal Stable per-assembler WGSL binding assignments. */
+  _bindingRegistry?: Map<string, number>;
+};
+
+export type BindingRelocationContext = {
+  usedBindingsByGroup: Map<number, Set<number>>;
+  bindingRegistry?: Map<string, number>;
+  reservedBindingKeysByGroup: Map<number, Map<number, string>>;
+};
+
+export type WGSLBindingAssignment = {
+  moduleName: string;
+  name: string;
+  group: number;
+  location: number;
+};
+
+export type WGSLApplicationRelocationState = {
+  sawSupportedBindingDeclaration: boolean;
+};
+
+export type WGSLRelocationState = {
+  sawSupportedBindingDeclaration: boolean;
+  nextHintedBindingLocation: number | null;
+};
+
+export type WGSLRelocationParams = {
+  module: ShaderModule;
+  context: BindingRelocationContext;
+  bindingAssignments: WGSLBindingAssignment[];
+  relocationState: WGSLRelocationState;
+};

package/src/lib/shader-assembly/shader-hooks.ts

@@ -0,0 +1,141 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderInjection} from './shader-injections';
+
+/**
+ * The shader hook mechanism allows the application to create shaders
+ * that can be automatically extended by the shader modules the application
+ * includes.
+ *
+ * A shader hook function that shader modules can inject code into.
+ * Shaders can call these functions, which will be no-ops by default.
+ *
+ * If a shader module injects code it will be executed upon the hook
+ * function call.
+ */
+export type ShaderHook = {
+  /** `vs:` or `fs:` followed by the name and arguments of the function, e.g. `vs:MYHOOK_func(inout vec4 value)`. Hook name without arguments
+  will also be used as the name of the shader hook */
+  hook: string;
+  /** Code always included at the beginning of a hook function */
+  header?: string;
+  /** Code always included at the end of a hook function */
+  footer?: string;
+  /** To Be Documented */
+  signature?: string;
+};
+
+/** Optional source included before or after every injection in a hook function. */
+export type ShaderHookOptions = Pick<ShaderHook, 'header' | 'footer'>;
+
+/** Shader hook declarations grouped by shader stage. */
+export type ShaderHookRegistry = {
+  vertex: Record<string, Required<ShaderHook>>;
+  fragment: Record<string, Required<ShaderHook>>;
+};
+
+/** Generate hook source code */
+export function getShaderHooks(
+  hookFunctions: Record<string, Required<ShaderHook>>,
+  hookInjections: Record<string, ShaderInjection[]>,
+  shaderLanguage: 'glsl' | 'wgsl' = 'glsl'
+): string {
+  let result = '';
+  for (const hookName in hookFunctions) {
+    const hookFunction = hookFunctions[hookName];
+    const functionPrefix = shaderLanguage === 'wgsl' ? 'fn' : 'void';
+    result += `${functionPrefix} ${hookFunction.signature} {\n`;
+    if (hookFunction.header) {
+      result += `  ${hookFunction.header}`;
+    }
+    if (hookInjections[hookName]) {
+      const injections = hookInjections[hookName];
+      injections.sort((a: {order: number}, b: {order: number}): number => a.order - b.order);
+      for (const injection of injections) {
+        result += `  ${injection.injection}\n`;
+      }
+    }
+    if (hookFunction.footer) {
+      result += `  ${hookFunction.footer}`;
+    }
+    result += '}\n';
+  }
+
+  return result;
+}
+
+/**
+ * Parse string based hook functions and split them per shader stage.
+ * A later declaration of the same stage-prefixed hook name replaces an earlier one.
+ */
+export function normalizeShaderHooks(
+  hookFunctions: readonly (ShaderHook | string)[]
+): ShaderHookRegistry {
+  const result: ShaderHookRegistry = {vertex: {}, fragment: {}};
+
+  for (const hookFunction of hookFunctions) {
+    addShaderHookToRegistry(result, hookFunction);
+  }
+
+  return result;
+}
+
+/** Returns true if a stage-prefixed hook name such as `vs:MY_HOOK` is declared. */
+export function isShaderHookRegistered(registry: ShaderHookRegistry, hookName: string): boolean {
+  const stageRegistry = hookName.startsWith('vs:') ? registry.vertex : registry.fragment;
+  return Boolean(stageRegistry[hookName]);
+}
+
+/**
+ * Throws if a named hook injection targets a hook that is not declared for this assembly.
+ * @param stage Only validate injections for this GLSL stage. WGSL validates both stages.
+ */
+export function validateShaderHookInjections(
+  registry: ShaderHookRegistry,
+  hookInjections: Record<string, ShaderInjection[]>,
+  stage?: 'vertex' | 'fragment'
+): void {
+  const stagePrefix = stage === 'vertex' ? 'vs:' : stage === 'fragment' ? 'fs:' : null;
+
+  for (const hookName in hookInjections) {
+    if (stagePrefix && !hookName.startsWith(stagePrefix)) {
+      continue;
+    }
+
+    if (!isShaderHookRegistered(registry, hookName)) {
+      // The injection targets a hook that was not declared for this stage.
+      throw new Error(`Unknown shader hook ${hookName}`);
+    }
+  }
+}
+
+function addShaderHookToRegistry(
+  registry: ShaderHookRegistry,
+  hookFunction: ShaderHook | string
+): void {
+  const options: ShaderHookOptions = typeof hookFunction === 'string' ? {} : hookFunction;
+  const hook = (typeof hookFunction === 'string' ? hookFunction : hookFunction.hook).trim();
+  const stageSeparatorIndex = hook.indexOf(':');
+  const shaderStage = hook.slice(0, stageSeparatorIndex);
+  const signature = hook.slice(stageSeparatorIndex + 1);
+  const name = hook.replace(/\(.+/, '');
+  const normalizedHook: Required<ShaderHook> = {
+    hook: name,
+    signature,
+    header: options.header || '',
+    footer: options.footer || ''
+  };
+
+  switch (shaderStage) {
+    case 'vs':
+      registry.vertex[name] = normalizedHook;
+      break;
+    case 'fs':
+      registry.fragment[name] = normalizedHook;
+      break;
+    default:
+      throw new Error(shaderStage);
+  }
+}