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

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 ResolvedShaderInjection} 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, ResolvedShaderInjection[]>,
+  targetInjections: Record<string, ResolvedShaderInjection[]>,
+  declInjections: Record<string, ResolvedShaderInjection[]>,
+  mainInjections: Record<string, ResolvedShaderInjection[]>
+): 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
+        : targetInjections;
+      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,146 @@
+// 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 ShaderInjectionTarget} from './shader-injection-targets';
+import {type ShaderInjection, type ResolvedShaderInjection} from './shader-injections';
+import {type AttributeShaderType} from '../../types';
+import {type ResolvedShaderPluginInterStageVariable} 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>;
+  /** Per-call injection targets, appended after registered assembler targets; matching names override for this call. */
+  injectionTargets?: readonly ShaderInjectionTarget[];
+  /** Injection target declarations contributed by resolved plugins. */
+  pluginInjectionTargets?: readonly ShaderInjectionTarget[];
+  /** Code injections */
+  inject?: readonly ShaderInjection[] | Record<string, string | ResolvedShaderInjection>;
+  /** Ordered code injections contributed by ShaderPlugin descriptors. */
+  pluginInjections?: Record<string, ResolvedShaderInjection[]>;
+  /** Vertex inputs contributed by ShaderPlugin descriptors. */
+  pluginVertexInputs?: Record<string, AttributeShaderType>;
+  /** Inter-stage variables contributed by ShaderPlugin descriptors. */
+  pluginInterStageVariables?: Record<string, ResolvedShaderPluginInterStageVariable>;
+  /** 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>;
+  /** Per-call injection targets, appended after registered assembler targets; matching names override for this call. */
+  injectionTargets?: readonly ShaderInjectionTarget[];
+  /** Injection target declarations contributed by resolved plugins. */
+  pluginInjectionTargets?: readonly ShaderInjectionTarget[];
+  /** Code injections */
+  inject?: readonly ShaderInjection[] | Record<string, string | ResolvedShaderInjection>;
+  /** Ordered code injections contributed by ShaderPlugin descriptors. */
+  pluginInjections?: Record<string, ResolvedShaderInjection[]>;
+  /** Vertex inputs contributed by ShaderPlugin descriptors. */
+  pluginVertexInputs?: Record<string, AttributeShaderType>;
+  /** Inter-stage variables contributed by ShaderPlugin descriptors. */
+  pluginInterStageVariables?: Record<string, ResolvedShaderPluginInterStageVariable>;
+  /** 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-injection-targets.ts

@@ -0,0 +1,148 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ResolvedShaderInjection} from './shader-injections';
+
+/** A named callable target for shader source injections. */
+export type ShaderInjectionTarget = {
+  /** Function name shared by both shader languages. */
+  name: string;
+  /** Shader stage that calls the target. */
+  stage: 'vertex' | 'fragment';
+  /** GLSL signature and source surrounding injected statements. */
+  glsl?: {
+    parameters: string;
+    returnType?: string;
+    header?: string;
+    footer?: string;
+  };
+  /** WGSL signature and source surrounding injected statements. */
+  wgsl?: {
+    parameters: string;
+    returnType?: string;
+    header?: string;
+    footer?: string;
+  };
+};
+
+/** Language-selected target ready for source generation. */
+type ResolvedShaderInjectionTarget = NonNullable<ShaderInjectionTarget['glsl']> & {
+  signature: string;
+};
+
+/** Normalized shader injection targets per shader */
+export type ShaderInjectionTargetRegistry = {
+  /** Normalized shader injection targets for vertex shader */
+  vertex: Record<string, ResolvedShaderInjectionTarget>;
+  /** Normalized shader injection targets for fragment shader */
+  fragment: Record<string, ResolvedShaderInjectionTarget>;
+};
+
+/** Generate injection target source code */
+export function getShaderInjectionTargets(
+  injectionTargets: Record<string, ResolvedShaderInjectionTarget>,
+  targetInjections: Record<string, ResolvedShaderInjection[]>,
+  shaderLanguage: 'glsl' | 'wgsl' = 'glsl'
+): string {
+  let result = '';
+  for (const targetName in injectionTargets) {
+    const targetFunction = injectionTargets[targetName];
+    const returnType = targetFunction.returnType || 'void';
+    const functionPrefix = shaderLanguage === 'wgsl' ? 'fn' : returnType;
+    const returnSuffix =
+      shaderLanguage === 'wgsl' && returnType !== 'void' ? ` -> ${returnType}` : '';
+    result += `${functionPrefix} ${targetFunction.signature}${returnSuffix} {\n`;
+    if (targetFunction.header) {
+      result += `  ${targetFunction.header}`;
+    }
+    if (targetInjections[targetName]) {
+      const injections = targetInjections[targetName];
+      injections.sort((a: {order: number}, b: {order: number}): number => a.order - b.order);
+      for (const injection of injections) {
+        result += `  ${injection.injection}\n`;
+      }
+    }
+    if (targetFunction.footer) {
+      result += `  ${targetFunction.footer}`;
+    }
+    result += '}\n';
+  }
+
+  return result;
+}
+
+/** Select language syntax and merge compatible plugin declarations without mutating descriptors. */
+export function normalizeShaderInjectionTargets(
+  injectionTargets: readonly ShaderInjectionTarget[],
+  pluginInjectionTargets: readonly ShaderInjectionTarget[] = [],
+  language: 'glsl' | 'wgsl' = 'glsl'
+): ShaderInjectionTargetRegistry {
+  const result: ShaderInjectionTargetRegistry = {vertex: {}, fragment: {}};
+  for (const injectionTarget of injectionTargets) {
+    const implementation = injectionTarget[language];
+    if (implementation) {
+      const prefix = injectionTarget.stage === 'vertex' ? 'vs' : 'fs';
+      result[injectionTarget.stage][`${prefix}:${injectionTarget.name}`] = {
+        ...implementation,
+        signature: `${injectionTarget.name}(${implementation.parameters})`
+      };
+    }
+  }
+  for (const injectionTarget of pluginInjectionTargets) {
+    const selected = normalizeShaderInjectionTargets([injectionTarget], [], language);
+    for (const stage of ['vertex', 'fragment'] as const) {
+      for (const [name, declaration] of Object.entries(selected[stage])) {
+        const existing = result[stage][name];
+        if (
+          existing &&
+          (existing.signature !== declaration.signature ||
+            (existing.returnType || 'void') !== (declaration.returnType || 'void'))
+        ) {
+          throw new Error(`Conflicting ShaderPlugin injection target ${name}`);
+        }
+        result[stage][name] = existing || declaration;
+      }
+    }
+  }
+  return result;
+}
+
+/** Returns true if a stage-prefixed target name such as `vs:MY_HOOK` is declared. */
+export function isShaderInjectionTargetRegistered(
+  registry: ShaderInjectionTargetRegistry,
+  targetName: string
+): boolean {
+  const stageRegistry = targetName.startsWith('vs:') ? registry.vertex : registry.fragment;
+  return Boolean(stageRegistry[targetName]);
+}
+
+/**
+ * Throws if an injection into a named target refers to one that is not declared for this assembly.
+ * @param stage Only validate injections for this GLSL stage. WGSL validates both stages.
+ */
+export function validateShaderInjectionTargetInjections(
+  registry: ShaderInjectionTargetRegistry,
+  targetInjections: Record<string, ResolvedShaderInjection[]>,
+  stage?: 'vertex' | 'fragment'
+): void {
+  const stagePrefix = stage === 'vertex' ? 'vs:' : stage === 'fragment' ? 'fs:' : null;
+
+  for (const targetName in targetInjections) {
+    if (stagePrefix && !targetName.startsWith(stagePrefix)) {
+      continue;
+    }
+
+    if (!isShaderInjectionTargetRegistered(registry, targetName)) {
+      // The named target was not declared for this stage.
+      const pluginNames = [
+        ...new Set(
+          targetInjections[targetName].map(injection => injection.pluginName).filter(Boolean)
+        )
+      ];
+      throw new Error(
+        `Unknown shader injection target ${targetName}${pluginNames.length ? ` (plugins: ${pluginNames.join(', ')})` : ''}`
+      );
+    }
+  }
+}