@luma.gl/shadertools 9.2.6 → 9.3.0-alpha.11

package/src/lib/shader-assembly/wgsl-binding-debug.ts

@@ -0,0 +1,227 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {WGSL_BINDABLE_VARIABLE_PATTERN, maskWGSLComments} from './wgsl-binding-scan';
+
+type ShaderBindingAssignment = {
+  moduleName: string;
+  name: string;
+  group: number;
+  location: number;
+};
+
+const WGSL_BINDING_DEBUG_REGEXES = [
+  new RegExp(
+    `@binding\\(\\s*(\\d+)\\s*\\)\\s*@group\\(\\s*(\\d+)\\s*\\)\\s*${WGSL_BINDABLE_VARIABLE_PATTERN}\\s*:\\s*([^;]+);`,
+    'g'
+  ),
+  new RegExp(
+    `@group\\(\\s*(\\d+)\\s*\\)\\s*@binding\\(\\s*(\\d+)\\s*\\)\\s*${WGSL_BINDABLE_VARIABLE_PATTERN}\\s*:\\s*([^;]+);`,
+    'g'
+  )
+] as const;
+
+/** One debug row describing a WGSL binding in the assembled shader source. */
+export type ShaderBindingDebugRow = {
+  /** Binding name as declared in WGSL. */
+  name: string;
+  /** Bind-group index. */
+  group: number;
+  /** Binding slot within the bind group. */
+  binding: number;
+  /** Resource kind inferred from the WGSL declaration. */
+  kind:
+    | 'uniform'
+    | 'storage'
+    | 'read-only-storage'
+    | 'texture'
+    | 'sampler'
+    | 'storage-texture'
+    | 'unknown';
+  /** Whether the binding came from application WGSL or a shader module. */
+  owner: 'application' | 'module';
+  /** Shader module name when the binding was contributed by a module. */
+  moduleName?: string;
+  /** Full WGSL resource type text from the declaration. */
+  resourceType?: string;
+  /** WGSL access mode when cheaply available. */
+  access?: string;
+  /** Texture view dimension when cheaply available. */
+  viewDimension?: string;
+  /** Texture sample type when cheaply available. */
+  sampleType?: string;
+  /** Sampler kind when cheaply available. */
+  samplerKind?: string;
+  /** Whether the texture is multisampled when cheaply available. */
+  multisampled?: boolean;
+};
+
+/** Builds a stable, table-friendly binding summary from assembled WGSL source. */
+export function getShaderBindingDebugRowsFromWGSL(
+  source: string,
+  bindingAssignments: ShaderBindingAssignment[] = []
+): ShaderBindingDebugRow[] {
+  const maskedSource = maskWGSLComments(source);
+  const assignmentMap = new Map<string, string>();
+  for (const bindingAssignment of bindingAssignments) {
+    assignmentMap.set(
+      getBindingAssignmentKey(
+        bindingAssignment.name,
+        bindingAssignment.group,
+        bindingAssignment.location
+      ),
+      bindingAssignment.moduleName
+    );
+  }
+
+  const rows: ShaderBindingDebugRow[] = [];
+  for (const regex of WGSL_BINDING_DEBUG_REGEXES) {
+    regex.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    match = regex.exec(maskedSource);
+    while (match) {
+      const isBindingFirst = regex === WGSL_BINDING_DEBUG_REGEXES[0];
+      const binding = Number(match[isBindingFirst ? 1 : 2]);
+      const group = Number(match[isBindingFirst ? 2 : 1]);
+      const accessDeclaration = match[3]?.trim();
+      const name = match[4];
+      const resourceType = match[5].trim();
+      const moduleName = assignmentMap.get(getBindingAssignmentKey(name, group, binding));
+
+      rows.push(
+        normalizeShaderBindingDebugRow({
+          name,
+          group,
+          binding,
+          owner: moduleName ? 'module' : 'application',
+          moduleName,
+          accessDeclaration,
+          resourceType
+        })
+      );
+      match = regex.exec(maskedSource);
+    }
+  }
+
+  return rows.sort((left, right) => {
+    if (left.group !== right.group) {
+      return left.group - right.group;
+    }
+    if (left.binding !== right.binding) {
+      return left.binding - right.binding;
+    }
+    return left.name.localeCompare(right.name);
+  });
+}
+
+function normalizeShaderBindingDebugRow(row: {
+  name: string;
+  group: number;
+  binding: number;
+  owner: 'application' | 'module';
+  moduleName?: string;
+  accessDeclaration?: string;
+  resourceType: string;
+}): ShaderBindingDebugRow {
+  const baseRow: ShaderBindingDebugRow = {
+    name: row.name,
+    group: row.group,
+    binding: row.binding,
+    owner: row.owner,
+    kind: 'unknown',
+    moduleName: row.moduleName,
+    resourceType: row.resourceType
+  };
+
+  if (row.accessDeclaration) {
+    const access = row.accessDeclaration.split(',').map(value => value.trim());
+    if (access[0] === 'uniform') {
+      return {...baseRow, kind: 'uniform', access: 'uniform'};
+    }
+    if (access[0] === 'storage') {
+      const storageAccess = access[1] || 'read_write';
+      return {
+        ...baseRow,
+        kind: storageAccess === 'read' ? 'read-only-storage' : 'storage',
+        access: storageAccess
+      };
+    }
+  }
+
+  if (row.resourceType === 'sampler' || row.resourceType === 'sampler_comparison') {
+    return {
+      ...baseRow,
+      kind: 'sampler',
+      samplerKind: row.resourceType === 'sampler_comparison' ? 'comparison' : 'filtering'
+    };
+  }
+
+  if (row.resourceType.startsWith('texture_storage_')) {
+    return {
+      ...baseRow,
+      kind: 'storage-texture',
+      access: getStorageTextureAccess(row.resourceType),
+      viewDimension: getTextureViewDimension(row.resourceType)
+    };
+  }
+
+  if (row.resourceType.startsWith('texture_')) {
+    return {
+      ...baseRow,
+      kind: 'texture',
+      viewDimension: getTextureViewDimension(row.resourceType),
+      sampleType: getTextureSampleType(row.resourceType),
+      multisampled: row.resourceType.startsWith('texture_multisampled_')
+    };
+  }
+
+  return baseRow;
+}
+
+function getBindingAssignmentKey(name: string, group: number, binding: number): string {
+  return `${group}:${binding}:${name}`;
+}
+
+function getTextureViewDimension(resourceType: string): string | undefined {
+  if (resourceType.includes('cube_array')) {
+    return 'cube-array';
+  }
+  if (resourceType.includes('2d_array')) {
+    return '2d-array';
+  }
+  if (resourceType.includes('cube')) {
+    return 'cube';
+  }
+  if (resourceType.includes('3d')) {
+    return '3d';
+  }
+  if (resourceType.includes('2d')) {
+    return '2d';
+  }
+  if (resourceType.includes('1d')) {
+    return '1d';
+  }
+  return undefined;
+}
+
+function getTextureSampleType(resourceType: string): string | undefined {
+  if (resourceType.startsWith('texture_depth_')) {
+    return 'depth';
+  }
+  if (resourceType.includes('<i32>')) {
+    return 'sint';
+  }
+  if (resourceType.includes('<u32>')) {
+    return 'uint';
+  }
+  if (resourceType.includes('<f32>')) {
+    return 'float';
+  }
+  return undefined;
+}
+
+function getStorageTextureAccess(resourceType: string): string | undefined {
+  const match = /,\s*([A-Za-z_][A-Za-z0-9_]*)\s*>$/.exec(resourceType);
+  return match?.[1];
+}

package/src/lib/shader-assembly/wgsl-binding-scan.ts

@@ -0,0 +1,228 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export const WGSL_BINDABLE_VARIABLE_PATTERN =
+  '(?:var<\\s*(uniform|storage(?:\\s*,\\s*[A-Za-z_][A-Za-z0-9_]*)?)\\s*>|var)\\s+([A-Za-z_][A-Za-z0-9_]*)';
+const WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN = '\\s*';
+
+export const MODULE_WGSL_BINDING_DECLARATION_REGEXES = [
+  new RegExp(
+    `@binding\\(\\s*(auto|\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}@group\\(\\s*(\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}${WGSL_BINDABLE_VARIABLE_PATTERN}`,
+    'g'
+  ),
+  new RegExp(
+    `@group\\(\\s*(\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}@binding\\(\\s*(auto|\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}${WGSL_BINDABLE_VARIABLE_PATTERN}`,
+    'g'
+  )
+] as const;
+
+export const WGSL_BINDING_DECLARATION_REGEXES = [
+  new RegExp(
+    `@binding\\(\\s*(auto|\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}@group\\(\\s*(\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}${WGSL_BINDABLE_VARIABLE_PATTERN}`,
+    'g'
+  ),
+  new RegExp(
+    `@group\\(\\s*(\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}@binding\\(\\s*(auto|\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}${WGSL_BINDABLE_VARIABLE_PATTERN}`,
+    'g'
+  )
+] as const;
+
+export const WGSL_EXPLICIT_BINDING_DECLARATION_REGEXES = [
+  new RegExp(
+    `@binding\\(\\s*(\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}@group\\(\\s*(\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}${WGSL_BINDABLE_VARIABLE_PATTERN}`,
+    'g'
+  ),
+  new RegExp(
+    `@group\\(\\s*(\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}@binding\\(\\s*(\\d+)\\s*\\)${WGSL_BINDING_DECLARATION_SEPARATOR_PATTERN}${WGSL_BINDABLE_VARIABLE_PATTERN}`,
+    'g'
+  )
+] as const;
+
+const WGSL_AUTO_BINDING_DECLARATION_REGEXES = [
+  new RegExp(
+    `@binding\\(\\s*(auto)\\s*\\)\\s*@group\\(\\s*(\\d+)\\s*\\)\\s*${WGSL_BINDABLE_VARIABLE_PATTERN}`,
+    'g'
+  ),
+  new RegExp(
+    `@group\\(\\s*(\\d+)\\s*\\)\\s*@binding\\(\\s*(auto)\\s*\\)\\s*${WGSL_BINDABLE_VARIABLE_PATTERN}`,
+    'g'
+  ),
+  new RegExp(
+    `@binding\\(\\s*(auto)\\s*\\)\\s*@group\\(\\s*(\\d+)\\s*\\)(?:[\\s\\n\\r]*@[A-Za-z_][^\\n\\r]*)*[\\s\\n\\r]*${WGSL_BINDABLE_VARIABLE_PATTERN}`,
+    'g'
+  ),
+  new RegExp(
+    `@group\\(\\s*(\\d+)\\s*\\)\\s*@binding\\(\\s*(auto)\\s*\\)(?:[\\s\\n\\r]*@[A-Za-z_][^\\n\\r]*)*[\\s\\n\\r]*${WGSL_BINDABLE_VARIABLE_PATTERN}`,
+    'g'
+  )
+] as const;
+
+export type WGSLBindingDeclarationMatch = {
+  match: string;
+  index: number;
+  length: number;
+  bindingToken: string;
+  groupToken: string;
+  accessDeclaration?: string;
+  name: string;
+};
+
+export function maskWGSLComments(source: string): string {
+  const maskedCharacters = source.split('');
+  let index = 0;
+  let blockCommentDepth = 0;
+  let inLineComment = false;
+  let inString = false;
+  let isEscaped = false;
+
+  while (index < source.length) {
+    const character = source[index];
+    const nextCharacter = source[index + 1];
+
+    if (inString) {
+      if (isEscaped) {
+        isEscaped = false;
+      } else if (character === '\\') {
+        isEscaped = true;
+      } else if (character === '"') {
+        inString = false;
+      }
+      index++;
+      continue;
+    }
+
+    if (inLineComment) {
+      if (character === '\n' || character === '\r') {
+        inLineComment = false;
+      } else {
+        maskedCharacters[index] = ' ';
+      }
+      index++;
+      continue;
+    }
+
+    if (blockCommentDepth > 0) {
+      if (character === '/' && nextCharacter === '*') {
+        maskedCharacters[index] = ' ';
+        maskedCharacters[index + 1] = ' ';
+        blockCommentDepth++;
+        index += 2;
+        continue;
+      }
+
+      if (character === '*' && nextCharacter === '/') {
+        maskedCharacters[index] = ' ';
+        maskedCharacters[index + 1] = ' ';
+        blockCommentDepth--;
+        index += 2;
+        continue;
+      }
+
+      if (character !== '\n' && character !== '\r') {
+        maskedCharacters[index] = ' ';
+      }
+      index++;
+      continue;
+    }
+
+    if (character === '"') {
+      inString = true;
+      index++;
+      continue;
+    }
+
+    if (character === '/' && nextCharacter === '/') {
+      maskedCharacters[index] = ' ';
+      maskedCharacters[index + 1] = ' ';
+      inLineComment = true;
+      index += 2;
+      continue;
+    }
+
+    if (character === '/' && nextCharacter === '*') {
+      maskedCharacters[index] = ' ';
+      maskedCharacters[index + 1] = ' ';
+      blockCommentDepth = 1;
+      index += 2;
+      continue;
+    }
+
+    index++;
+  }
+
+  return maskedCharacters.join('');
+}
+
+export function getWGSLBindingDeclarationMatches(
+  source: string,
+  regexes: readonly RegExp[]
+): WGSLBindingDeclarationMatch[] {
+  const maskedSource = maskWGSLComments(source);
+  const matches: WGSLBindingDeclarationMatch[] = [];
+
+  for (const regex of regexes) {
+    regex.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    match = regex.exec(maskedSource);
+    while (match) {
+      const isBindingFirst = regex === regexes[0];
+      const index = match.index;
+      const length = match[0].length;
+      matches.push({
+        match: source.slice(index, index + length),
+        index,
+        length,
+        bindingToken: match[isBindingFirst ? 1 : 2],
+        groupToken: match[isBindingFirst ? 2 : 1],
+        accessDeclaration: match[3]?.trim(),
+        name: match[4]
+      });
+      match = regex.exec(maskedSource);
+    }
+  }
+
+  return matches.sort((left, right) => left.index - right.index);
+}
+
+export function replaceWGSLBindingDeclarationMatches(
+  source: string,
+  regexes: readonly RegExp[],
+  replacer: (match: WGSLBindingDeclarationMatch) => string
+): string {
+  const matches = getWGSLBindingDeclarationMatches(source, regexes);
+  if (!matches.length) {
+    return source;
+  }
+
+  let relocatedSource = '';
+  let lastIndex = 0;
+
+  for (const match of matches) {
+    relocatedSource += source.slice(lastIndex, match.index);
+    relocatedSource += replacer(match);
+    lastIndex = match.index + match.length;
+  }
+
+  relocatedSource += source.slice(lastIndex);
+  return relocatedSource;
+}
+
+export function hasWGSLAutoBinding(source: string): boolean {
+  return /@binding\(\s*auto\s*\)/.test(maskWGSLComments(source));
+}
+
+export function getFirstWGSLAutoBindingDeclarationMatch(
+  source: string,
+  regexes: readonly RegExp[]
+): WGSLBindingDeclarationMatch | undefined {
+  const autoBindingRegexes =
+    regexes === MODULE_WGSL_BINDING_DECLARATION_REGEXES ||
+    regexes === WGSL_BINDING_DECLARATION_REGEXES
+      ? WGSL_AUTO_BINDING_DECLARATION_REGEXES
+      : regexes;
+
+  return getWGSLBindingDeclarationMatches(source, autoBindingRegexes).find(
+    declarationMatch => declarationMatch.bindingToken === 'auto'
+  );
+}

package/src/lib/shader-generator/glsl/generate-glsl.ts

@@ -21,25 +21,31 @@ function generateGLSLUniformDeclarations(
 ): string {
   const glsl: string[] = [];
 
-  // => uniform UniformBlockName {
+  // => layout(std140) uniform UniformBlockName {
   switch (options.uniforms) {
     case 'scoped-interface-blocks':
     case 'unscoped-interface-blocks':
-      glsl.push(`uniform ${capitalize(module.name)} {`);
+      glsl.push(`layout(std140) uniform ${capitalize(module.name)} {`);
       break;
     case 'uniforms':
     // ignore
   }
 
   for (const [uniformName, uniformFormat] of Object.entries(module.uniformTypes || {})) {
-    const glslUniformType = getGLSLUniformType(uniformFormat);
+    if (typeof uniformFormat !== 'string') {
+      throw new Error(
+        `Composite uniform types are not supported by GLSL shader generation: ${module.name}.${uniformName}`
+      );
+    }
+
+    const glslUniformType = getGLSLUniformType(uniformFormat as UniformFormat);
     switch (options.uniforms) {
       case 'scoped-interface-blocks':
-        // => uniform UniformBlockName {
+        // => layout(std140) uniform UniformBlockName {
         glsl.push(`  ${glslUniformType} ${uniformName};`);
         break;
       case 'unscoped-interface-blocks':
-        // => uniform UniformBlockName {
+        // => layout(std140) uniform UniformBlockName {
         glsl.push(`  ${glslUniformType} ${module.name}_${uniformName};`);
         break;
       case 'uniforms':

package/src/lib/shader-generator/wgsl/generate-wgsl.ts

@@ -23,6 +23,12 @@ export function generateWGSLUniformDeclarations(
   wgsl.push(`struct ${capitalize(module.name)} {`);
 
   for (const [uniformName, uniformFormat] of Object.entries(module?.uniformTypes || {})) {
+    if (typeof uniformFormat !== 'string') {
+      throw new Error(
+        `Composite uniform types are not supported by WGSL shader generation: ${module.name}.${uniformName}`
+      );
+    }
+
     const wgslUniformType = uniformFormat;
     wgsl.push(`  ${uniformName} : ${wgslUniformType};`);
   }