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

package/src/lib/shader-module/shader-module-uniform-layout.ts

@@ -0,0 +1,420 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from './shader-module';
+import {assert} from '../utils/assert';
+
+/**
+ * Shader stages supported by shader-module uniform-layout validation helpers.
+ */
+export type ShaderModuleUniformLayoutStage = 'vertex' | 'fragment' | 'wgsl';
+
+/**
+ * Describes the result of comparing declared `uniformTypes` with the fields
+ * found in a shader uniform block.
+ */
+export type ShaderModuleUniformLayoutValidationResult = {
+  /** Name of the shader module being validated. */
+  moduleName: string;
+  /** Expected block name derived from the shader module name. */
+  uniformBlockName: string;
+  /** Shader stage that was inspected. */
+  stage: ShaderModuleUniformLayoutStage;
+  /** Field names declared by the module metadata. */
+  expectedUniformNames: string[];
+  /** Field names parsed from the shader source. */
+  actualUniformNames: string[];
+  /** Whether the declared and parsed field lists match exactly. */
+  matches: boolean;
+};
+
+/**
+ * Parsed information about one GLSL uniform block declaration.
+ */
+export type GLSLUniformBlockInfo = {
+  /** Declared block type name. */
+  blockName: string;
+  /** Optional instance name that follows the block declaration. */
+  instanceName: string | null;
+  /** Raw layout qualifier text, if present. */
+  layoutQualifier: string | null;
+  /** Whether any explicit layout qualifier was present. */
+  hasLayoutQualifier: boolean;
+  /** Whether the block explicitly declares `layout(std140)`. */
+  isStd140: boolean;
+  /** Raw source text inside the block braces. */
+  body: string;
+};
+
+/**
+ * Logging surface used by validation and warning helpers.
+ */
+type Logger = {
+  /** Error logger compatible with luma's deferred log API. */
+  error?: (...args: unknown[]) => () => unknown;
+  /** Warning logger compatible with luma's deferred log API. */
+  warn?: (...args: unknown[]) => () => unknown;
+};
+
+/**
+ * Matches one field declaration inside a GLSL uniform block body.
+ */
+const GLSL_UNIFORM_BLOCK_FIELD_REGEXP =
+  /^(?:uniform\s+)?(?:(?:lowp|mediump|highp)\s+)?[A-Za-z0-9_]+(?:<[^>]+>)?\s+([A-Za-z0-9_]+)(?:\s*\[[^\]]+\])?\s*;/;
+/**
+ * Matches full GLSL uniform block declarations, including optional layout qualifiers.
+ */
+const GLSL_UNIFORM_BLOCK_REGEXP =
+  /((?:layout\s*\([^)]*\)\s*)*)uniform\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{([\s\S]*?)\}\s*([A-Za-z_][A-Za-z0-9_]*)?\s*;/g;
+
+/**
+ * Returns the uniform block type name expected for the supplied shader module.
+ */
+export function getShaderModuleUniformBlockName(module: ShaderModule): string {
+  return `${module.name}Uniforms`;
+}
+
+/**
+ * Returns the ordered field names parsed from a shader module's uniform block.
+ *
+ * @returns `null` when the stage has no source or the expected block is absent.
+ */
+export function getShaderModuleUniformBlockFields(
+  module: ShaderModule,
+  stage: ShaderModuleUniformLayoutStage
+): string[] | null {
+  const shaderSource =
+    stage === 'wgsl' ? module.source : stage === 'vertex' ? module.vs : module.fs;
+
+  if (!shaderSource) {
+    return null;
+  }
+
+  const uniformBlockName = getShaderModuleUniformBlockName(module);
+  return extractShaderUniformBlockFieldNames(
+    shaderSource,
+    stage === 'wgsl' ? 'wgsl' : 'glsl',
+    uniformBlockName
+  );
+}
+
+/**
+ * Computes the validation result for a shader module's declared and parsed
+ * uniform-block field lists.
+ *
+ * @returns `null` when the module has no declared uniform types or no matching block.
+ */
+export function getShaderModuleUniformLayoutValidationResult(
+  module: ShaderModule,
+  stage: ShaderModuleUniformLayoutStage
+): ShaderModuleUniformLayoutValidationResult | null {
+  const expectedUniformNames = Object.keys(module.uniformTypes || {});
+  if (!expectedUniformNames.length) {
+    return null;
+  }
+
+  const actualUniformNames = getShaderModuleUniformBlockFields(module, stage);
+  if (!actualUniformNames) {
+    return null;
+  }
+
+  return {
+    moduleName: module.name,
+    uniformBlockName: getShaderModuleUniformBlockName(module),
+    stage,
+    expectedUniformNames,
+    actualUniformNames,
+    matches: areStringArraysEqual(expectedUniformNames, actualUniformNames)
+  };
+}
+
+/**
+ * Validates that a shader module's parsed uniform block matches `uniformTypes`.
+ *
+ * When a mismatch is detected, the helper logs a formatted error and optionally
+ * throws via {@link assert}.
+ */
+export function validateShaderModuleUniformLayout(
+  module: ShaderModule,
+  stage: ShaderModuleUniformLayoutStage,
+  options: {
+    log?: Logger;
+    throwOnError?: boolean;
+  } = {}
+): ShaderModuleUniformLayoutValidationResult | null {
+  const validationResult = getShaderModuleUniformLayoutValidationResult(module, stage);
+  if (!validationResult || validationResult.matches) {
+    return validationResult;
+  }
+
+  const message = formatShaderModuleUniformLayoutError(validationResult);
+  options.log?.error?.(message, validationResult)();
+
+  if (options.throwOnError !== false) {
+    assert(false, message);
+  }
+
+  return validationResult;
+}
+
+/**
+ * Parses all GLSL uniform blocks in a shader source string.
+ */
+export function getGLSLUniformBlocks(shaderSource: string): GLSLUniformBlockInfo[] {
+  const blocks: GLSLUniformBlockInfo[] = [];
+  const uncommentedSource = stripShaderComments(shaderSource);
+
+  for (const sourceMatch of uncommentedSource.matchAll(GLSL_UNIFORM_BLOCK_REGEXP)) {
+    const layoutQualifier = sourceMatch[1]?.trim() || null;
+    blocks.push({
+      blockName: sourceMatch[2],
+      body: sourceMatch[3],
+      instanceName: sourceMatch[4] || null,
+      layoutQualifier,
+      hasLayoutQualifier: Boolean(layoutQualifier),
+      isStd140: Boolean(
+        layoutQualifier && /\blayout\s*\([^)]*\bstd140\b[^)]*\)/.exec(layoutQualifier)
+      )
+    });
+  }
+
+  return blocks;
+}
+
+/**
+ * Emits warnings for GLSL uniform blocks that do not explicitly declare
+ * `layout(std140)`.
+ *
+ * @returns The list of parsed blocks that were considered non-compliant.
+ */
+export function warnIfGLSLUniformBlocksAreNotStd140(
+  shaderSource: string,
+  stage: Exclude<ShaderModuleUniformLayoutStage, 'wgsl'>,
+  log?: Logger,
+  context?: {label?: string}
+): GLSLUniformBlockInfo[] {
+  const nonStd140Blocks = getGLSLUniformBlocks(shaderSource).filter(block => !block.isStd140);
+  const seenBlockNames = new Set<string>();
+
+  for (const block of nonStd140Blocks) {
+    if (seenBlockNames.has(block.blockName)) {
+      continue;
+    }
+    seenBlockNames.add(block.blockName);
+
+    const shaderLabel = context?.label ? `${context.label} ` : '';
+    const actualLayout = block.hasLayoutQualifier
+      ? `declares ${normalizeWhitespace(block.layoutQualifier!)} instead of layout(std140)`
+      : 'does not declare layout(std140)';
+    const message = `${shaderLabel}${stage} shader uniform block ${
+      block.blockName
+    } ${actualLayout}. luma.gl host-side shader block packing assumes explicit layout(std140) for GLSL uniform blocks. Add \`layout(std140)\` to the block declaration.`;
+    log?.warn?.(message, block)();
+  }
+
+  return nonStd140Blocks;
+}
+
+/**
+ * Extracts field names from the named GLSL or WGSL uniform block/struct.
+ */
+function extractShaderUniformBlockFieldNames(
+  shaderSource: string,
+  language: 'glsl' | 'wgsl',
+  uniformBlockName: string
+): string[] | null {
+  const sourceBody =
+    language === 'wgsl'
+      ? extractWGSLStructBody(shaderSource, uniformBlockName)
+      : extractGLSLUniformBlockBody(shaderSource, uniformBlockName);
+
+  if (!sourceBody) {
+    return null;
+  }
+
+  const fieldNames: string[] = [];
+
+  for (const sourceLine of sourceBody.split('\n')) {
+    const line = sourceLine.replace(/\/\/.*$/, '').trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+
+    const fieldMatch =
+      language === 'wgsl'
+        ? line.match(/^([A-Za-z0-9_]+)\s*:/)
+        : line.match(GLSL_UNIFORM_BLOCK_FIELD_REGEXP);
+
+    if (fieldMatch) {
+      fieldNames.push(fieldMatch[1]);
+    }
+  }
+
+  return fieldNames;
+}
+
+/**
+ * Extracts the body of a WGSL struct with the supplied name.
+ */
+function extractWGSLStructBody(shaderSource: string, uniformBlockName: string): string | null {
+  const structMatch = new RegExp(`\\bstruct\\s+${uniformBlockName}\\b`, 'm').exec(shaderSource);
+  if (!structMatch) {
+    return null;
+  }
+
+  const openBraceIndex = shaderSource.indexOf('{', structMatch.index);
+  if (openBraceIndex < 0) {
+    return null;
+  }
+
+  let braceDepth = 0;
+  for (let index = openBraceIndex; index < shaderSource.length; index++) {
+    const character = shaderSource[index];
+    if (character === '{') {
+      braceDepth++;
+      continue;
+    }
+    if (character !== '}') {
+      continue;
+    }
+
+    braceDepth--;
+    if (braceDepth === 0) {
+      return shaderSource.slice(openBraceIndex + 1, index);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extracts the body of a named GLSL uniform block from shader source.
+ */
+function extractGLSLUniformBlockBody(
+  shaderSource: string,
+  uniformBlockName: string
+): string | null {
+  const block = getGLSLUniformBlocks(shaderSource).find(
+    candidate => candidate.blockName === uniformBlockName
+  );
+  return block?.body || null;
+}
+
+/**
+ * Returns `true` when the two arrays contain the same strings in the same order.
+ */
+function areStringArraysEqual(leftValues: string[], rightValues: string[]): boolean {
+  if (leftValues.length !== rightValues.length) {
+    return false;
+  }
+
+  for (let valueIndex = 0; valueIndex < leftValues.length; valueIndex++) {
+    if (leftValues[valueIndex] !== rightValues[valueIndex]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Formats the standard validation error message for a shader-module layout mismatch.
+ */
+function formatShaderModuleUniformLayoutError(
+  validationResult: ShaderModuleUniformLayoutValidationResult
+): string {
+  const {expectedUniformNames, actualUniformNames} = validationResult;
+  const missingUniformNames = expectedUniformNames.filter(
+    uniformName => !actualUniformNames.includes(uniformName)
+  );
+  const unexpectedUniformNames = actualUniformNames.filter(
+    uniformName => !expectedUniformNames.includes(uniformName)
+  );
+  const mismatchDetails = [
+    `Expected ${expectedUniformNames.length} fields, found ${actualUniformNames.length}.`
+  ];
+  const firstMismatchDescription = getFirstUniformMismatchDescription(
+    expectedUniformNames,
+    actualUniformNames
+  );
+  if (firstMismatchDescription) {
+    mismatchDetails.push(firstMismatchDescription);
+  }
+  if (missingUniformNames.length) {
+    mismatchDetails.push(
+      `Missing from shader block (${missingUniformNames.length}): ${formatUniformNameList(
+        missingUniformNames
+      )}.`
+    );
+  }
+  if (unexpectedUniformNames.length) {
+    mismatchDetails.push(
+      `Unexpected in shader block (${unexpectedUniformNames.length}): ${formatUniformNameList(
+        unexpectedUniformNames
+      )}.`
+    );
+  }
+  if (
+    expectedUniformNames.length <= 12 &&
+    actualUniformNames.length <= 12 &&
+    (missingUniformNames.length || unexpectedUniformNames.length)
+  ) {
+    mismatchDetails.push(`Expected: ${expectedUniformNames.join(', ')}.`);
+    mismatchDetails.push(`Actual: ${actualUniformNames.join(', ')}.`);
+  }
+
+  return `${validationResult.moduleName}: ${validationResult.stage} shader uniform block ${
+    validationResult.uniformBlockName
+  } does not match module.uniformTypes. ${mismatchDetails.join(' ')}`;
+}
+
+/**
+ * Removes line and block comments from shader source before lightweight parsing.
+ */
+function stripShaderComments(shaderSource: string): string {
+  return shaderSource.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
+}
+
+/**
+ * Collapses repeated whitespace in a layout qualifier for log-friendly output.
+ */
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function getFirstUniformMismatchDescription(
+  expectedUniformNames: string[],
+  actualUniformNames: string[]
+): string | null {
+  const minimumLength = Math.min(expectedUniformNames.length, actualUniformNames.length);
+  for (let index = 0; index < minimumLength; index++) {
+    if (expectedUniformNames[index] !== actualUniformNames[index]) {
+      return `First mismatch at field ${index + 1}: expected ${
+        expectedUniformNames[index]
+      }, found ${actualUniformNames[index]}.`;
+    }
+  }
+
+  if (expectedUniformNames.length > actualUniformNames.length) {
+    return `Shader block ends after field ${actualUniformNames.length}; expected next field ${
+      expectedUniformNames[actualUniformNames.length]
+    }.`;
+  }
+  if (actualUniformNames.length > expectedUniformNames.length) {
+    return `Shader block has extra field ${actualUniformNames.length}: ${
+      actualUniformNames[expectedUniformNames.length]
+    }.`;
+  }
+
+  return null;
+}
+
+function formatUniformNameList(uniformNames: string[], maxNames = 8): string {
+  if (uniformNames.length <= maxNames) {
+    return uniformNames.join(', ');
+  }
+
+  const remainingCount = uniformNames.length - maxNames;
+  return `${uniformNames.slice(0, maxNames).join(', ')}, ... (${remainingCount} more)`;
+}

package/src/lib/shader-module/shader-module.ts

@@ -0,0 +1,244 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {UniformFormat} from '../../types';
+import {
+  PropType,
+  PropValidator,
+  makePropValidators,
+  getValidatedProperties
+} from '../filters/prop-types';
+import type {ShaderModuleUniformValue, UniformTypes, UniformValue} from '../utils/uniform-types';
+import {ShaderInjection, normalizeInjections} from '../shader-assembly/shader-injections';
+
+import type {ShaderBinding as Binding} from '../../types';
+
+export type UniformInfo = {
+  format?: UniformFormat;
+} & PropType;
+
+export type ShaderModuleBindingLayout = {
+  name: string;
+  group: number;
+  /** Which shader stages can access this binding. Uses GPUShaderStage bit flags. */
+  visibility?: number;
+};
+
+// Helper types
+type BindingKeys<T> = {[K in keyof T]: T[K] extends UniformValue ? never : K}[keyof T];
+type UniformKeys<T> = {[K in keyof T]: T[K] extends UniformValue ? K : never}[keyof T];
+export type PickBindings<T> = {[K in BindingKeys<Required<T>>]: T[K]};
+export type PickUniforms<T> = {[K in UniformKeys<Required<T>>]: T[K]};
+
+/**
+ * A shader module definition object
+ *
+ * @note Needs to be initialized with `initializeShaderModules`
+ * @note `UniformsT` & `BindingsT` are deduced from `PropsT` by default. If
+ * a custom type for `UniformsT` is used, `BindingsT` should be also be provided.
+ */
+export type ShaderModule<
+  PropsT extends Record<string, any> = Record<string, any>,
+  UniformsT extends Record<string, ShaderModuleUniformValue> = PickUniforms<PropsT>,
+  BindingsT extends Record<string, Binding> = PickBindings<PropsT>
+> = {
+  /** Used for type inference not for values */
+  props?: PropsT;
+  /** Used for type inference, not currently used for values */
+  uniforms?: UniformsT;
+  /** Used for type inference, not currently used for values */
+  bindings?: BindingsT;
+  /** Logical bind-group assignment for bindings declared by this module */
+  bindingLayout?: readonly ShaderModuleBindingLayout[];
+  /** Preferred starting binding slot for this module's WGSL `@binding(auto)` declarations. */
+  firstBindingSlot?: number;
+
+  name: string;
+
+  /** Exclusive named shader interface provided by this module. */
+  implements?: string;
+
+  /** Language of source when an application-owned transpiler is required. */
+  sourceLanguage?: string;
+  /** WGSL code, or reusable code in sourceLanguage combined with the application source. */
+  source?: string;
+  /** GLSL fragment shader code */
+  fs?: string;
+  /** GLSL vertex shader code */
+  vs?: string;
+
+  /** Uniform shader types @note: Both order and types MUST match uniform block declarations in shader */
+  uniformTypes?: Required<UniformTypes<UniformsT>>; // Record<keyof UniformsT, UniformFormat>;
+  /** Uniform JS prop types  */
+  propTypes?: Record<keyof UniformsT, UniformInfo>;
+  /** Default uniform values */
+  defaultUniforms?: Required<UniformsT>; // Record<keyof UniformsT, UniformValue>;
+
+  /** Function that maps props to uniforms & bindings */
+  getUniforms?: (
+    props: Partial<PropsT>,
+    prevUniforms?: UniformsT
+  ) => Partial<UniformsT & BindingsT>;
+
+  /** Boolean or numeric preprocessor defines contributed by this shader module. */
+  defines?: Record<string, boolean | number>;
+  /** Injections */
+  inject?: Record<string, string | {injection: string; order: number}>;
+  dependencies?: ShaderModule<any, any>[];
+  /** Information on deprecated properties */
+  deprecations?: ShaderModuleDeprecation[];
+
+  /** The instance field contains information that is generated at run-time */
+  instance?: {
+    propValidators?: Record<string, PropValidator>;
+    parsedDeprecations: ShaderModuleDeprecation[];
+
+    normalizedInjections: {
+      vertex: Record<string, ShaderInjection>;
+      fragment: Record<string, ShaderInjection>;
+    };
+  };
+};
+
+/** Use to generate deprecations when shader module is used */
+export type ShaderModuleDeprecation = {
+  type: string;
+  regex?: RegExp;
+  new: string;
+  old: string;
+  deprecated?: boolean;
+};
+
+// SHNDER MODULE API
+
+export function initializeShaderModules(modules: ShaderModule[]): void {
+  modules.map((module: ShaderModule) => initializeShaderModule(module));
+}
+
+export function initializeShaderModule(module: ShaderModule): void {
+  if (module.instance) {
+    return;
+  }
+
+  initializeShaderModules(module.dependencies || []);
+
+  const {
+    propTypes = {},
+    deprecations = [],
+    // defines = {},
+    inject = {}
+  } = module;
+
+  const instance: Required<ShaderModule>['instance'] = {
+    normalizedInjections: normalizeInjections(inject),
+    parsedDeprecations: parseDeprecationDefinitions(deprecations)
+  };
+
+  if (propTypes) {
+    instance.propValidators = makePropValidators(propTypes);
+  }
+
+  module.instance = instance;
+
+  // TODO(ib) - we need to apply the original prop types to the default uniforms
+  let defaultProps: ShaderModule['props'] = {};
+  if (propTypes) {
+    defaultProps = Object.entries(propTypes).reduce(
+      (obj: ShaderModule['props'], [key, propType]) => {
+        // @ts-expect-error
+        const value = propType?.value;
+        if (value) {
+          // @ts-expect-error
+          obj[key] = value;
+        }
+        return obj;
+      },
+      {} as ShaderModule['props']
+    );
+  }
+
+  // Merge validated default props with existing uniforms. Type assertion needed due to complex generics.
+  module.defaultUniforms = {
+    ...module.defaultUniforms,
+    ...defaultProps
+  } as typeof module.defaultUniforms;
+}
+
+/** Convert module props to uniforms */
+export function getShaderModuleUniforms<
+  ShaderModuleT extends ShaderModule<
+    Record<string, unknown>,
+    Record<string, ShaderModuleUniformValue>
+  >
+>(
+  module: ShaderModuleT,
+  props?: ShaderModuleT['props'],
+  oldUniforms?: ShaderModuleT['uniforms']
+): Record<string, Binding | ShaderModuleUniformValue> {
+  initializeShaderModule(module);
+
+  const uniforms = oldUniforms || {...module.defaultUniforms};
+  // If module has a getUniforms function, use it
+  if (props && module.getUniforms) {
+    return module.getUniforms(props, uniforms);
+  }
+
+  // Build uniforms from the uniforms array
+  // @ts-expect-error
+  return getValidatedProperties(props, module.instance?.propValidators, module.name);
+}
+
+/* TODO this looks like it was unused code
+  _defaultGetUniforms(opts: Record<string, any> = {}): Record<string, any> {
+    const uniforms: Record<string, any> = {};
+    const propTypes = this.uniforms;
+
+    for (const key in propTypes) {
+      const propDef = propTypes[key];
+      if (key in opts && !propDef.private) {
+        if (propDef.validate) {
+          assert(propDef.validate(opts[key], propDef), `${this.name}: invalid ${key}`);
+        }
+        uniforms[key] = opts[key];
+      } else {
+        uniforms[key] = propDef.value;
+      }
+    }
+
+    return uniforms;
+  }
+}
+*/
+// Warn about deprecated uniforms or functions
+export function checkShaderModuleDeprecations(
+  shaderModule: ShaderModule,
+  shaderSource: string,
+  log: any
+): void {
+  shaderModule.deprecations?.forEach(def => {
+    if (def.regex?.test(shaderSource)) {
+      if (def.deprecated) {
+        log.deprecated(def.old, def.new)();
+      } else {
+        log.removed(def.old, def.new)();
+      }
+    }
+  });
+}
+
+// HELPERS
+
+function parseDeprecationDefinitions(deprecations: ShaderModuleDeprecation[]) {
+  deprecations.forEach(def => {
+    switch (def.type) {
+      case 'function':
+        def.regex = new RegExp(`\\b${def.old}\\(`);
+        break;
+      default:
+        def.regex = new RegExp(`${def.type} ${def.old};`);
+    }
+  });
+
+  return deprecations;
+}