@aura3d/rendering 1.0.6

package/src/ShaderModule.ts

@@ -0,0 +1,36 @@
+import { type RenderDevice, type RenderShaderProgram } from "./RenderDevice";
+import { type CompiledShaderSource, type ShaderLibrary } from "./ShaderLibrary";
+import { reflectShaderSources, type ShaderReflection } from "./ShaderReflection";
+
+export class ShaderModule {
+  private program: RenderShaderProgram | null = null;
+  public readonly reflection: ShaderReflection;
+
+  constructor(public readonly source: CompiledShaderSource) {
+    this.reflection = reflectShaderSources(source);
+  }
+
+  static fromLibrary(library: ShaderLibrary, name: string): ShaderModule {
+    return new ShaderModule(library.compileSource(name));
+  }
+
+  static fromLibraryVariant(library: ShaderLibrary, name: string, variantName: string): ShaderModule {
+    return new ShaderModule(library.compileVariant(name, variantName));
+  }
+
+  compile(device: RenderDevice): RenderShaderProgram {
+    if (!this.program || this.program.disposed) {
+      this.program = device.createShaderProgram({
+        label: this.source.label,
+        marker: this.source.marker,
+        vertex: this.source.vertex,
+        fragment: this.source.fragment
+      });
+    }
+    return this.program;
+  }
+
+  dispose(): void {
+    this.program?.dispose();
+  }
+}

package/src/ShaderPreprocessor.ts

@@ -0,0 +1,260 @@
+export interface ShaderPreprocessOptions {
+  readonly defines?: Readonly<Record<string, string | number | boolean>>;
+  readonly includes?: ReadonlyMap<string, string>;
+}
+
+export interface ShaderSourceMapEntry {
+  readonly generatedLine: number;
+  readonly sourceName: string;
+  readonly sourceLine: number;
+}
+
+export interface ShaderPreprocessResult {
+  readonly source: string;
+  readonly included: readonly string[];
+  readonly sourceMap: readonly ShaderSourceMapEntry[];
+}
+
+interface ExpandedShaderSource {
+  readonly lines: readonly string[];
+  readonly sourceMap: readonly ShaderSourceMapEntry[];
+}
+
+export class ShaderPreprocessor {
+  preprocess(source: string, options: ShaderPreprocessOptions = {}): ShaderPreprocessResult {
+    const included: string[] = [];
+    const defines = normalizeDefines(options.defines ?? {});
+    const expanded = this.expandSource({
+      source,
+      sourceName: "root",
+      includes: options.includes ?? new Map(),
+      defines,
+      stack: [],
+      included
+    });
+    const defineLines = [...defines.entries()].map(([key, value]) => `#define ${key} ${value}`);
+    const { lines, sourceMap } = mergeDefines(expanded, defineLines);
+    return {
+      source: lines.filter(Boolean).join("\n"),
+      included,
+      sourceMap
+    };
+  }
+
+  private expandSource({
+    source,
+    sourceName,
+    includes,
+    defines,
+    stack,
+    included
+  }: {
+    readonly source: string;
+    readonly sourceName: string;
+    includes: ReadonlyMap<string, string>,
+    readonly defines: ReadonlyMap<string, string>;
+    stack: readonly string[],
+    included: string[]
+  }): ExpandedShaderSource {
+    const output: string[] = [];
+    const sourceMap: ShaderSourceMapEntry[] = [];
+    const conditions: Array<{ parentActive: boolean; conditionActive: boolean; elseSeen: boolean; line: number }> = [];
+    const lines = source.split(/\r?\n/);
+    const isActive = (): boolean => conditions.every((condition) => condition.parentActive && condition.conditionActive);
+
+    const pushLine = (line: string, sourceLine: number, mappedSourceName = sourceName): void => {
+      output.push(line);
+      sourceMap.push({
+        generatedLine: output.length,
+        sourceName: mappedSourceName,
+        sourceLine
+      });
+    };
+
+    lines.forEach((line, index) => {
+      const sourceLine = index + 1;
+      const conditional = parseConditionalDirective(line);
+      if (conditional) {
+        if (conditional.kind === "else") {
+          const current = conditions[conditions.length - 1];
+          if (!current) {
+            throw new Error(`Shader #else without matching #if at ${sourceName}:${sourceLine}`);
+          }
+          if (current.elseSeen) {
+            throw new Error(`Shader duplicate #else at ${sourceName}:${sourceLine}`);
+          }
+          current.conditionActive = !current.conditionActive;
+          current.elseSeen = true;
+          return;
+        }
+        if (conditional.kind === "endif") {
+          if (!conditions.pop()) {
+            throw new Error(`Shader #endif without matching #if at ${sourceName}:${sourceLine}`);
+          }
+          return;
+        }
+        if (conditional.kind === "if") {
+          const parentActive = isActive();
+          conditions.push({
+            parentActive,
+            conditionActive: evaluateCondition(conditional.expression, defines, sourceName, sourceLine),
+            elseSeen: false,
+            line: sourceLine
+          });
+        }
+        return;
+      }
+
+      if (!isActive()) {
+        return;
+      }
+
+      const includeName = parseInclude(line);
+      if (includeName !== null) {
+        if (stack.includes(includeName)) {
+          throw new Error(`Circular shader include detected: ${[...stack, includeName].join(" -> ")}`);
+        }
+        const includeSource = includes.get(includeName);
+        if (includeSource === undefined) {
+          throw new Error(`Shader include not found: ${includeName}`);
+        }
+        included.push(includeName);
+        const expanded = this.expandSource({
+          source: includeSource,
+          sourceName: includeName,
+          includes,
+          defines,
+          stack: [...stack, includeName],
+          included
+        });
+        for (const expandedLine of expanded.lines) {
+          output.push(expandedLine);
+        }
+        for (const entry of expanded.sourceMap) {
+          sourceMap.push({
+            ...entry,
+            generatedLine: output.length - expanded.lines.length + entry.generatedLine
+          });
+        }
+        return;
+      }
+
+      pushLine(line, sourceLine);
+    });
+
+    const unclosed = conditions[conditions.length - 1];
+    if (unclosed) {
+      throw new Error(`Shader conditional opened at ${sourceName}:${unclosed.line} is missing #endif`);
+    }
+
+    return { lines: output, sourceMap };
+  }
+}
+
+function mergeDefines(expanded: ExpandedShaderSource, defineLines: readonly string[]): ExpandedShaderSource {
+  if (defineLines.length === 0) return expanded;
+  const versionLineIndex = expanded.lines.findIndex((line) => line.trim().startsWith("#version"));
+  if (versionLineIndex === 0) {
+    return {
+      lines: [
+        expanded.lines[0]!,
+        ...defineLines,
+        ...expanded.lines.slice(1)
+      ],
+      sourceMap: [
+        {
+          ...expanded.sourceMap[0]!,
+          generatedLine: 1
+        },
+        ...defineLines.map((_, index) => ({
+          generatedLine: index + 2,
+          sourceName: "<defines>",
+          sourceLine: index + 1
+        })),
+        ...expanded.sourceMap.slice(1).map((entry) => ({
+          ...entry,
+          generatedLine: entry.generatedLine + defineLines.length
+        }))
+      ]
+    };
+  }
+  return {
+    lines: [...defineLines, ...expanded.lines],
+    sourceMap: [
+      ...defineLines.map((_, index) => ({
+        generatedLine: index + 1,
+        sourceName: "<defines>",
+        sourceLine: index + 1
+      })),
+      ...expanded.sourceMap.map((entry) => ({
+        ...entry,
+        generatedLine: entry.generatedLine + defineLines.length
+      }))
+    ]
+  };
+}
+
+function normalizeDefines(defines: Readonly<Record<string, string | number | boolean>>): ReadonlyMap<string, string> {
+  const normalized = new Map<string, string>();
+  for (const [key, value] of Object.entries(defines)) {
+    if (!/^[A-Za-z_]\w*$/.test(key)) {
+      throw new Error(`Shader define name is invalid: ${key}`);
+    }
+    normalized.set(key, formatDefine(value));
+  }
+  return normalized;
+}
+
+function formatDefine(value: string | number | boolean): string {
+  if (typeof value === "boolean") {
+    return value ? "1" : "0";
+  }
+  return String(value);
+}
+
+function parseInclude(line: string): string | null {
+  const match = line.match(/^\s*#include\s+<([^>]+)>\s*$/);
+  return match?.[1] ?? null;
+}
+
+function parseConditionalDirective(line: string):
+  | { readonly kind: "if"; readonly expression: string }
+  | { readonly kind: "else" | "endif" }
+  | null {
+  const match = line.match(/^\s*#(ifdef|ifndef|if|else|endif)\b\s*(.*?)\s*$/);
+  if (!match) return null;
+  const directive = match[1]!;
+  const expression = match[2] ?? "";
+  if (directive === "else" || directive === "endif") {
+    if (expression.length > 0) {
+      throw new Error(`Shader #${directive} does not accept an expression`);
+    }
+    return { kind: directive };
+  }
+  if (directive === "ifdef") return { kind: "if", expression: `defined(${expression})` };
+  if (directive === "ifndef") return { kind: "if", expression: `!defined(${expression})` };
+  return { kind: "if", expression };
+}
+
+function evaluateCondition(expression: string, defines: ReadonlyMap<string, string>, sourceName: string, sourceLine: number): boolean {
+  const trimmed = expression.trim();
+  const definedMatch = trimmed.match(/^(!)?defined\s*\(\s*([A-Za-z_]\w*)\s*\)$/);
+  if (definedMatch) {
+    const exists = defines.has(definedMatch[2]!);
+    return definedMatch[1] === "!" ? !exists : exists;
+  }
+  const bareMatch = trimmed.match(/^([A-Za-z_]\w*)$/);
+  if (bareMatch) {
+    const defineName = bareMatch[1]!;
+    const value = defines.get(defineName);
+    if (value === undefined) {
+      throw new Error(`Shader conditional references undefined define ${defineName} at ${sourceName}:${sourceLine}`);
+    }
+    return value !== "0" && value !== "false" && value !== "";
+  }
+  const literalMatch = trimmed.match(/^[01]$/);
+  if (literalMatch) {
+    return trimmed === "1";
+  }
+  throw new Error(`Unsupported shader conditional expression at ${sourceName}:${sourceLine}: ${expression}`);
+}

package/src/ShaderReflection.ts

@@ -0,0 +1,201 @@
+import { type ShaderSources } from "./RenderDevice";
+
+export interface ShaderAttributeReflection {
+  readonly name: string;
+  readonly type: string;
+  readonly location: number;
+  readonly source: "vertex";
+  readonly line: number;
+}
+
+export interface ShaderUniformReflection {
+  readonly name: string;
+  readonly type: string;
+  readonly arraySize: number | null;
+  readonly source: "vertex" | "fragment";
+  readonly line: number;
+}
+
+export interface ShaderReflection {
+  readonly attributes: ReadonlyMap<string, number>;
+  readonly uniforms: ReadonlySet<string>;
+  readonly attributeDetails: ReadonlyMap<string, ShaderAttributeReflection>;
+  readonly uniformDetails: ReadonlyMap<string, ShaderUniformReflection>;
+}
+
+interface DeclarationSource {
+  readonly source: "vertex" | "fragment";
+  readonly text: string;
+}
+
+export function reflectShaderSources(sources: ShaderSources): ShaderReflection {
+  const attributes = new Map<string, number>();
+  const uniforms = new Set<string>();
+  const attributeDetails = new Map<string, ShaderAttributeReflection>();
+  const uniformDetails = new Map<string, ShaderUniformReflection>();
+
+  const cleanVertex = stripShaderComments(sources.vertex);
+  const cleanFragment = stripShaderComments(sources.fragment);
+
+  for (const declaration of parseShaderDeclarations({ source: "vertex", text: cleanVertex })) {
+    if (declaration.kind !== "attribute") {
+      continue;
+    }
+    const location = declaration.location ?? nextAvailableLocation(attributes);
+    attributes.set(declaration.name, location);
+    attributeDetails.set(declaration.name, {
+      name: declaration.name,
+      type: declaration.type,
+      location,
+      source: "vertex",
+      line: declaration.line
+    });
+  }
+
+  for (const source of [
+    { source: "vertex" as const, text: cleanVertex },
+    { source: "fragment" as const, text: cleanFragment }
+  ]) {
+    for (const declaration of parseShaderDeclarations(source)) {
+      if (declaration.kind !== "uniform") {
+        continue;
+      }
+      uniforms.add(declaration.name);
+      uniformDetails.set(declaration.name, {
+        name: declaration.name,
+        type: declaration.type,
+        arraySize: declaration.arraySize,
+        source: source.source,
+        line: declaration.line
+      });
+    }
+  }
+
+  return { attributes, uniforms, attributeDetails, uniformDetails };
+}
+
+function stripShaderComments(source: string): string {
+  let output = "";
+  let inBlockComment = false;
+
+  for (let index = 0; index < source.length; index += 1) {
+    const current = source[index];
+    const next = source[index + 1];
+
+    if (inBlockComment) {
+      if (current === "*" && next === "/") {
+        inBlockComment = false;
+        index += 1;
+        continue;
+      }
+      output += current === "\n" ? "\n" : " ";
+      continue;
+    }
+
+    if (current === "/" && next === "*") {
+      inBlockComment = true;
+      output += "  ";
+      index += 1;
+      continue;
+    }
+
+    if (current === "/" && next === "/") {
+      while (index < source.length && source[index] !== "\n") {
+        output += " ";
+        index += 1;
+      }
+      if (source[index] === "\n") {
+        output += "\n";
+      }
+      continue;
+    }
+
+    output += current;
+  }
+
+  return output;
+}
+
+function parseShaderDeclarations(source: DeclarationSource): readonly ShaderDeclaration[] {
+  const declarations: ShaderDeclaration[] = [];
+
+  source.text.split("\n").forEach((lineText, lineIndex) => {
+    for (const statement of lineText.split(";")) {
+      const normalized = statement.replace(/\s+/g, " ").trim();
+      if (!normalized || normalized.startsWith("#")) {
+        continue;
+      }
+
+      const line = lineIndex + 1;
+      const attribute = parseAttributeDeclaration(normalized, line);
+      if (attribute) {
+        declarations.push(attribute);
+        continue;
+      }
+
+      const uniform = parseUniformDeclaration(normalized, line);
+      if (uniform) {
+        declarations.push(uniform);
+      }
+    }
+  });
+
+  return declarations;
+}
+
+interface BaseShaderDeclaration {
+  readonly name: string;
+  readonly type: string;
+  readonly line: number;
+}
+
+interface AttributeDeclaration extends BaseShaderDeclaration {
+  readonly kind: "attribute";
+  readonly location: number | null;
+}
+
+interface UniformDeclaration extends BaseShaderDeclaration {
+  readonly kind: "uniform";
+  readonly arraySize: number | null;
+}
+
+type ShaderDeclaration = AttributeDeclaration | UniformDeclaration;
+
+function parseAttributeDeclaration(statement: string, line: number): AttributeDeclaration | null {
+  const match = statement.match(
+    /^(?:layout\s*\(\s*location\s*=\s*(\d+)\s*\)\s*)?(?:flat\s+|smooth\s+|noperspective\s+|centroid\s+)*(?:(?:lowp|mediump|highp)\s+)?(?:in|attribute)\s+(\w+)\s+(\w+)(?:\s*\[[^\]]+\])?$/
+  );
+  if (!match) {
+    return null;
+  }
+  return {
+    kind: "attribute",
+    location: match[1] ? Number(match[1]) : null,
+    type: match[2] ?? "",
+    name: match[3] ?? "",
+    line
+  };
+}
+
+function parseUniformDeclaration(statement: string, line: number): UniformDeclaration | null {
+  const match = statement.match(/^(?:layout\s*\([^)]+\)\s*)?uniform\s+(?:(?:lowp|mediump|highp)\s+)?(\w+)\s+(\w+)(?:\s*\[\s*(\d+)\s*\])?$/);
+  if (!match) {
+    return null;
+  }
+  return {
+    kind: "uniform",
+    type: match[1] ?? "",
+    name: match[2] ?? "",
+    arraySize: match[3] ? Number(match[3]) : null,
+    line
+  };
+}
+
+function nextAvailableLocation(attributes: ReadonlyMap<string, number>): number {
+  const used = new Set(attributes.values());
+  let location = 0;
+  while (used.has(location)) {
+    location += 1;
+  }
+  return location;
+}