《游戏引擎实现原理》11.1 WGSL 组织与 include

// file: src/render/shader/include-resolver.ts
// tier: L1
// verify: npx vitest run src/render/shader/include-resolver.test.ts
//
// helio 渲染卷：WGSL 的 #include 预处理。
// WGSL 语言本身没有 include，但引擎需要把公共函数拆成多个文件复用。
// 这里在 createShaderModule() 之前做一层文本级展开：递归拼接、去重（include once）、
// 检测环，并产出「展开后行号 -> 原文件行号」的映射，供 11.3 的错误定位使用。

/** 一个待展开的源文件。 */
export interface SourceFile {
  /** 相对路径，如 `shaders/lib/color.wgsl`。 */
  readonly path: string;
  readonly text: string;
}

/** 展开后某一行的来源。 */
export interface LineMapping {
  /** 展开后源码里的 1 基行号。 */
  readonly outLine: number;
  /** 该行来自哪个源文件。 */
  readonly file: string;
  /** 在源文件里的 1 基行号。 */
  readonly inLine: number;
}

export interface ResolveResult {
  /** 展开后的完整 WGSL，可直接喂给 createShaderModule()。 */
  readonly code: string;
  /** 与 code 每一行一一对应的来源映射（长度 = code 行数）。 */
  readonly lines: LineMapping[];
  /** 按首次出现顺序记录被展开的文件（不含根文件）。 */
  readonly included: string[];
}

const INCLUDE_RE = /^\s*#include\s+"([^"]+)"\s*$/;

/** 把 `a/b/../c` 归一化成 `a/c`，相对路径解析用。 */
export function normalizePath(path: string): string {
  const parts: string[] = [];
  for (const seg of path.split('/')) {
    if (seg === '' || seg === '.') continue;
    if (seg === '..') parts.pop();
    else parts.push(seg);
  }
  return parts.join('/');
}

/** 把 include 目标解析成相对根文件的路径。 */
export function resolveIncludePath(fromFile: string, target: string): string {
  if (target.startsWith('/')) return normalizePath(target);
  const dir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : '';
  return normalizePath(dir ? `${dir}/${target}` : target);
}

/**
 * 递归展开 `#include "..."`。
 * - 同一个文件只展开一次（include once，按首次出现的位置）；
 * - 检测环并抛错；
 * - 缺文件抛错，且报出是哪个文件 include 的。
 */
export function resolveIncludes(
  root: SourceFile,
  files: ReadonlyMap<string, string>,
): ResolveResult {
  const out: string[] = [];
  const lines: LineMapping[] = [];
  const included: string[] = [];
  const emitted = new Set<string>();
  const stack: string[] = [];

  const emit = (file: string, inLine: number, text: string): void => {
    out.push(text);
    lines.push({ outLine: out.length, file, inLine });
  };

  const visit = (file: SourceFile): void => {
    stack.push(file.path);
    const srcLines = file.text.split('\n');
    for (let i = 0; i < srcLines.length; i++) {
      const line = srcLines[i]!;
      const m = INCLUDE_RE.exec(line);
      if (m) {
        const target = resolveIncludePath(file.path, m[1]!);
        if (stack.includes(target)) {
          throw new Error(`循环 include: ${[...stack, target].join(' -> ')}`);
        }
        if (emitted.has(target)) continue; // include once
        const text = files.get(target);
        if (text === undefined) {
          throw new Error(`${file.path} 引用了不存在的文件 ${target}`);
        }
        emitted.add(target);
        included.push(target);
        visit({ path: target, text });
        continue;
      }
      emit(file.path, i + 1, line);
    }
    stack.pop();
  };

  emitted.add(root.path);
  visit(root);
  return { code: out.join('\n'), lines, included };
}

/** 展开后行号 -> 原始位置；越界返回 null。 */
export function lookupLine(result: ResolveResult, outLine: number): LineMapping | null {
  return result.lines[outLine - 1] ?? null;
}

// shaders/island.wgsl
// shaders/lib/color.wgsl
fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> {
  return pow(c, vec3<f32>(2.2));
}
// shaders/lib/mathx.wgsl
fn luma(c: vec3<f32>) -> f32 {
  return dot(c, vec3<f32>(0.2126, 0.7152, 0.0722));
}

struct VSOut { @builtin(position) pos: vec4<f32>, @location(0) uv: vec2<f32> };
...

// file: shaders/lib/color.wgsl
// tier: L2
// verify: node tools/run-l2.mjs src/render/shader/wgsl-include-l2.ts

// 颜色工具：sRGB 近似转线性（gamma 2.2）。
fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> {
  return pow(c, vec3<f32>(2.2));
}

// snippet: 带 #include 的根文件，须先展开才能编译
// shaders/island-material.wgsl
#include "lib/color.wgsl"
#include "lib/mathx.wgsl"

struct VSOut { @builtin(position) pos: vec4<f32>, @location(0) uv: vec2<f32> };

@vertex
fn vs(@builtin(vertex_index) i: u32) -> VSOut {
  var p = array<vec2<f32>, 3>(
    vec2<f32>(-1.0, -1.0), vec2<f32>(3.0, -1.0), vec2<f32>(-1.0, 3.0),
  );
  var o: VSOut;
  o.pos = vec4<f32>(p[i], 0.0, 1.0);
  o.uv = p[i] * 0.5 + vec2<f32>(0.5);
  return o;
}

@fragment
fn fs(in: VSOut) -> @location(0) vec4<f32> {
  let lin = srgb_to_linear(vec3<f32>(in.uv, 0.5));
  let y = luma(vec3<f32>(0.2126, 0.7152, 0.0722));
  return vec4<f32>(vec3<f32>(y), 1.0);
}

included   [shaders/lib/color.wgsl, shaders/lib/mathx.wgsl]
codeLines  29
errors     0
center     [143,143,143,255]