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

package/src/lib/shader-assembly/shader-plugin-vertex-inputs.ts

@@ -0,0 +1,279 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {shaderTypeDecoder, type AttributeShaderType} from '../../types';
+
+export type ShaderPluginVertexInputAssembly = {
+  source: string;
+  declarations: string;
+  initialization: string;
+};
+
+/** Generate GLSL vertex input declarations contributed by shader plugins. */
+export function getShaderPluginVertexInputDeclarationsGLSL(
+  source: string,
+  vertexInputs: Record<string, AttributeShaderType>
+): string {
+  const declarations: string[] = [];
+  for (const [name, type] of Object.entries(vertexInputs)) {
+    assertGLSLVertexInputIsNew(source, name);
+    declarations.push(`in ${getGLSLAttributeType(type)} ${name};`);
+  }
+  return declarations.join('\n');
+}
+
+/** Add WGSL plugin inputs to the selected vertex entry point. */
+export function assembleShaderPluginVertexInputsWGSL(
+  source: string,
+  vertexEntryPoint: string,
+  vertexInputs: Record<string, AttributeShaderType>
+): ShaderPluginVertexInputAssembly {
+  const entries = Object.entries(vertexInputs);
+  if (entries.length === 0) {
+    return {source, declarations: '', initialization: ''};
+  }
+
+  const functionRange = getWGSLFunctionParameterRange(source, vertexEntryPoint);
+  const parameterSource = source.slice(
+    functionRange.openParenthesis + 1,
+    functionRange.closeParenthesis
+  );
+  const interfaceInfo = getWGSLVertexInterfaceInfo(source, parameterSource);
+  const usedLocations = new Set(interfaceInfo.locations);
+  const generatedParameters: string[] = [];
+  const declarations: string[] = [];
+  const initialization: string[] = [];
+
+  for (const [name, type] of entries) {
+    if (interfaceInfo.names.has(name) || hasWGSLModuleVariable(source, name)) {
+      throw new Error(
+        `ShaderPlugin vertex input "${name}" conflicts with an existing WGSL shader input or variable`
+      );
+    }
+    const location = getFirstUnusedLocation(usedLocations);
+    usedLocations.add(location);
+    const parameterName = `_luma_${name}`;
+    generatedParameters.push(`@location(${location}) ${parameterName}: ${type}`);
+    declarations.push(`var<private> ${name}: ${type};`);
+    initialization.push(`${name} = ${parameterName};`);
+  }
+
+  const separator = parameterSource.trim() ? ',\n  ' : '\n  ';
+  const suffix = parameterSource.trim() ? '' : '\n';
+  const injectedParameters = `${parameterSource}${separator}${generatedParameters.join(',\n  ')}${suffix}`;
+  const transformedSource =
+    source.slice(0, functionRange.openParenthesis + 1) +
+    injectedParameters +
+    source.slice(functionRange.closeParenthesis);
+
+  return {
+    source: transformedSource,
+    declarations: declarations.join('\n'),
+    initialization: initialization.join('\n')
+  };
+}
+
+export function getGLSLAttributeType(type: AttributeShaderType): string {
+  const {primitiveType, components} = shaderTypeDecoder.getAttributeShaderTypeInfo(type);
+  const scalarType = primitiveType === 'i32' ? 'int' : primitiveType === 'u32' ? 'uint' : 'float';
+  if (components === 1) {
+    return scalarType;
+  }
+  const prefix = scalarType === 'int' ? 'i' : scalarType === 'uint' ? 'u' : '';
+  return `${prefix}vec${components}`;
+}
+
+function assertGLSLVertexInputIsNew(source: string, name: string): void {
+  const escapedName = escapeRegExp(name);
+  const declaration = new RegExp(
+    `\\b(?:in|attribute)\\s+(?:(?:lowp|mediump|highp)\\s+)?[A-Za-z_][A-Za-z0-9_]*\\s+${escapedName}\\s*(?:\\[|;)`
+  );
+  if (declaration.test(source)) {
+    throw new Error(`ShaderPlugin vertex input "${name}" conflicts with an existing GLSL input`);
+  }
+}
+
+function getWGSLFunctionParameterRange(
+  source: string,
+  entryPoint: string
+): {openParenthesis: number; closeParenthesis: number} {
+  const functionPattern = new RegExp(`\\bfn\\s+${escapeRegExp(entryPoint)}\\s*\\(`, 'g');
+  const match = functionPattern.exec(source);
+  if (!match) {
+    throw new Error(`ShaderPlugin vertex inputs require WGSL vertex entry point "${entryPoint}"`);
+  }
+  const openParenthesis = source.indexOf('(', match.index);
+  const closeParenthesis = findMatchingDelimiter(source, openParenthesis, '(', ')');
+  if (closeParenthesis < 0) {
+    throw new Error(`Unable to parse WGSL vertex entry point "${entryPoint}" parameters`);
+  }
+  return {openParenthesis, closeParenthesis};
+}
+
+function getWGSLVertexInterfaceInfo(
+  source: string,
+  parameterSource: string
+): {locations: number[]; names: Set<string>} {
+  const locations = getWGSLLocations(parameterSource);
+  const names = new Set(getWGSLDeclaredNames(parameterSource));
+  const parameterTypes = getWGSLParameterTypes(parameterSource);
+  for (const parameterType of parameterTypes) {
+    const structBody = getWGSLStructBody(source, parameterType);
+    if (structBody === null) {
+      continue;
+    }
+    locations.push(...getWGSLLocations(structBody));
+    for (const name of getWGSLDeclaredNames(structBody)) {
+      names.add(name);
+    }
+  }
+  return {locations, names};
+}
+
+function getWGSLLocations(source: string): number[] {
+  const locations: number[] = [];
+  const locationPattern = /@location\s*\(\s*(\d+)\s*\)/g;
+  let match = locationPattern.exec(source);
+  while (match) {
+    locations.push(Number(match[1]));
+    match = locationPattern.exec(source);
+  }
+  return locations;
+}
+
+function getWGSLDeclaredNames(source: string): string[] {
+  const names: string[] = [];
+  const namePattern = /(?:^|,)\s*(?:@[A-Za-z_][\w]*(?:\([^)]*\))?\s*)*([A-Za-z_][\w]*)\s*:/gm;
+  let match = namePattern.exec(source);
+  while (match) {
+    names.push(match[1]);
+    match = namePattern.exec(source);
+  }
+  return names;
+}
+
+function getWGSLParameterTypes(source: string): string[] {
+  const types: string[] = [];
+  const typePattern = /:\s*([A-Za-z_][\w]*)\b/g;
+  let match = typePattern.exec(source);
+  while (match) {
+    types.push(match[1]);
+    match = typePattern.exec(source);
+  }
+  return types;
+}
+
+function getWGSLStructBody(source: string, structName: string): string | null {
+  const structPattern = new RegExp(`\\bstruct\\s+${escapeRegExp(structName)}\\s*\\{`, 'g');
+  const match = structPattern.exec(source);
+  if (!match) {
+    return null;
+  }
+  const openBrace = source.indexOf('{', match.index);
+  const closeBrace = findMatchingDelimiter(source, openBrace, '{', '}');
+  return closeBrace < 0 ? null : source.slice(openBrace + 1, closeBrace);
+}
+
+function hasWGSLModuleVariable(source: string, name: string): boolean {
+  const escapedName = escapeRegExp(name);
+  const variablePattern = new RegExp(`\\b(?:var(?:<[^>]+>)?|let|const)\\s+${escapedName}\\b`, 'g');
+  let match = variablePattern.exec(source);
+  while (match) {
+    if (getBraceDepthAt(source, match.index) === 0) {
+      return true;
+    }
+    match = variablePattern.exec(source);
+  }
+  return false;
+}
+
+function getFirstUnusedLocation(usedLocations: Set<number>): number {
+  let location = 0;
+  while (usedLocations.has(location)) {
+    location++;
+  }
+  return location;
+}
+
+function findMatchingDelimiter(
+  source: string,
+  openIndex: number,
+  openCharacter: string,
+  closeCharacter: string
+): number {
+  let depth = 0;
+  let blockCommentDepth = 0;
+  let lineComment = false;
+  for (let index = openIndex; index < source.length; index++) {
+    const character = source[index];
+    const nextCharacter = source[index + 1];
+    if (lineComment) {
+      if (character === '\n') lineComment = false;
+      continue;
+    }
+    if (blockCommentDepth > 0) {
+      if (character === '/' && nextCharacter === '*') {
+        blockCommentDepth++;
+        index++;
+      } else if (character === '*' && nextCharacter === '/') {
+        blockCommentDepth--;
+        index++;
+      }
+      continue;
+    }
+    if (character === '/' && nextCharacter === '/') {
+      lineComment = true;
+      index++;
+      continue;
+    }
+    if (character === '/' && nextCharacter === '*') {
+      blockCommentDepth = 1;
+      index++;
+      continue;
+    }
+    if (character === openCharacter) depth++;
+    if (character === closeCharacter && --depth === 0) return index;
+  }
+  return -1;
+}
+
+function getBraceDepthAt(source: string, endIndex: number): number {
+  let depth = 0;
+  let blockCommentDepth = 0;
+  let lineComment = false;
+  for (let index = 0; index < endIndex; index++) {
+    const character = source[index];
+    const nextCharacter = source[index + 1];
+    if (lineComment) {
+      if (character === '\n') lineComment = false;
+      continue;
+    }
+    if (blockCommentDepth > 0) {
+      if (character === '/' && nextCharacter === '*') {
+        blockCommentDepth++;
+        index++;
+      } else if (character === '*' && nextCharacter === '/') {
+        blockCommentDepth--;
+        index++;
+      }
+      continue;
+    }
+    if (character === '/' && nextCharacter === '/') {
+      lineComment = true;
+      index++;
+    } else if (character === '/' && nextCharacter === '*') {
+      blockCommentDepth = 1;
+      index++;
+    } else if (character === '{') {
+      depth++;
+    } else if (character === '}') {
+      depth--;
+    }
+  }
+  return depth;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -0,0 +1,227 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 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];
+}