《游戏引擎实现原理》4.1 WebGPU / WebGL2 能力探测与降级

// file: src/render/rhi/probe-to-config.ts
// tier: L1
// verify: npx vitest run src/render/rhi/probe-to-config.test.ts
//
// 启动期：把浏览器探测回来的原始数字，翻译成一份具体的渲染配置，
// 并逐条记录「哪些能力缺了、退到了哪条路径」。
// 纯数据进出，不碰 GPU，可在 Node 里单测——真实 GPU 差异见同章的 L2 探测。

export interface WebGpuProbe {
  readonly limits: Readonly<Record<string, number>>;
  readonly features: readonly string[];
}
export interface WebGl2Probe {
  readonly maxTextureSize: number;
  readonly maxVertexAttribs: number;
  readonly hasDepthTexture: boolean;
}
/** 一次启动探测的原始快照；某后端探测失败即为 null。 */
export interface ProbeSnapshot {
  readonly webgpu: WebGpuProbe | null;
  readonly webgl2: WebGl2Probe | null;
}
export type BackendChoice = 'webgpu' | 'webgl2' | 'none';

/** 《微光岛》在启动期声明的最低要求。低于它就别硬上，宁可报错。 */
export interface GameRequirement {
  readonly minTextureDimension2D: number;
  readonly wantsCompute: boolean;
  readonly wantsStorageBuffer: boolean;
}

/** 一条降级记录：哪个特性、退到哪条路径、为什么。 */
export interface Downgrade {
  readonly feature: string;
  readonly strategy: string;
  readonly reason: string;
}

export interface RenderConfig {
  readonly backend: BackendChoice;
  readonly maxTextureDimension2D: number;
  readonly shadowMapSize: number;
  readonly depthFormat: 'depth32float' | 'depth24unorm';
  readonly useCompute: boolean;
  readonly useStorageBuffer: boolean;
  readonly downgrades: readonly Downgrade[];
}

/** 后端选择：优先 WebGPU，其次 WebGL2，都不满足最低纹理尺寸则 none。 */
export function selectBackend(snapshot: ProbeSnapshot, req: GameRequirement): BackendChoice {
  const gpu = snapshot.webgpu;
  if (gpu && (gpu.limits.maxTextureDimension2D ?? 0) >= req.minTextureDimension2D) return 'webgpu';
  const gl = snapshot.webgl2;
  if (gl && gl.maxTextureSize >= req.minTextureDimension2D) return 'webgl2';
  return 'none';
}

/** helio 自定的纹理尺寸天花板：再大对《微光岛》的收益为零，只吃显存。 */
const TEXTURE_CEILING = 8192;

export function resolveRenderConfig(snapshot: ProbeSnapshot, req: GameRequirement): RenderConfig {
  const backend = selectBackend(snapshot, req);

  if (backend === 'none') {
    return {
      backend, maxTextureDimension2D: 0, shadowMapSize: 0, depthFormat: 'depth24unorm',
      useCompute: false, useStorageBuffer: false,
      downgrades: [{ feature: 'backend', strategy: 'none', reason: `无后端满足纹理下限 ${req.minTextureDimension2D}` }],
    };
  }

  const downgrades: Downgrade[] = [];

  if (backend === 'webgpu') {
    const gpu = snapshot.webgpu as WebGpuProbe;
    const maxTex = Math.min(gpu.limits.maxTextureDimension2D ?? TEXTURE_CEILING, TEXTURE_CEILING);
    // depth32float 与 storage buffer 属 WebGPU 核心能力，无需特性位申请。
    if (!gpu.features.includes('timestamp-query')) {
      downgrades.push({ feature: 'gpu-timing', strategy: 'cpu-fence', reason: 'adapter 未提供 timestamp-query' });
    }
    return {
      backend, maxTextureDimension2D: maxTex, shadowMapSize: 2048, depthFormat: 'depth32float',
      useCompute: req.wantsCompute, useStorageBuffer: req.wantsStorageBuffer, downgrades,
    };
  }

  // WebGL2：compute 与 storage buffer 不存在；helio 的 WebGL2 后端统一走 depth24 省带宽。
  const gl = snapshot.webgl2 as WebGl2Probe;
  const maxTex = Math.min(gl.maxTextureSize, TEXTURE_CEILING);
  if (req.wantsCompute) {
    downgrades.push({ feature: 'compute-shader', strategy: 'transform-feedback', reason: 'WebGL2 无 compute shader' });
  }
  if (req.wantsStorageBuffer) {
    downgrades.push({ feature: 'storage-buffer', strategy: 'texture-as-storage', reason: 'WebGL2 无 storage buffer' });
  }
  downgrades.push({ feature: 'depth32float', strategy: 'depth24', reason: 'helio WebGL2 后端统一走 depth24' });
  if (!gl.hasDepthTexture) {
    downgrades.push({ feature: 'depth-texture', strategy: 'renderbuffer-copy', reason: '无 depth texture 扩展' });
  }
  return {
    backend, maxTextureDimension2D: maxTex, shadowMapSize: 1024, depthFormat: 'depth24unorm',
    useCompute: false, useStorageBuffer: false, downgrades,
  };
}

// snippet: src/render/rhi/probe-to-config.test.ts 节选
it('只有 WebGL2 时降级表列出 compute / storage / depth / depth-texture 四条', () => {
  const cfg = resolveRenderConfig(GL_ONLY, REQ);
  expect(cfg.backend).toBe('webgl2');
  expect(cfg.downgrades.map((d) => d.feature)).toEqual([
    'compute-shader', 'storage-buffer', 'depth32float', 'depth-texture',
  ]);
});

// file: src/render/rhi/probe-l2.ts
// tier: L2
// verify: node tools/run-l2.mjs src/render/rhi/probe-l2.ts
//
// 真实探测：从浏览器读回 WebGPU adapter 的 limits/features 与 WebGL2 的
// MAX_TEXTURE_SIZE，喂给 probe-to-config.ts 的 resolveRenderConfig，
// 断言「探测 → 配置」这条链在真机（headless Chromium + swiftshader）上闭合。

import { resolveRenderConfig, selectBackend, type ProbeSnapshot } from './probe-to-config.ts';

export interface L2Check { readonly name: string; readonly ok: boolean; readonly detail: string }
export interface L2Result {
  readonly checks: L2Check[];
  readonly data: Record<string, unknown>;
}

const REQ = { minTextureDimension2D: 2048, wantsCompute: true, wantsStorageBuffer: true } as const;

export async function runL2(): Promise<L2Result> {
  const checks: L2Check[] = [];
  const data: Record<string, unknown> = {};
  const push = (name: string, ok: boolean, detail: unknown): void => {
    checks.push({ name, ok, detail: String(detail) });
  };

  let webgpu: ProbeSnapshot['webgpu'] = null;
  if (navigator.gpu) {
    const adapter = await navigator.gpu.requestAdapter();
    if (adapter) {
      const device = await adapter.requestDevice();
      webgpu = {
        limits: {
          maxTextureDimension2D: device.limits.maxTextureDimension2D,
          maxBindGroups: device.limits.maxBindGroups,
          maxBufferSize: device.limits.maxBufferSize,
        },
        features: Array.from(adapter.features),
      };
      data.webgpu = webgpu;
      device.destroy();
    }
  }

  let webgl2: ProbeSnapshot['webgl2'] = null;
  const canvas = document.createElement('canvas');
  const gl = canvas.getContext('webgl2');
  if (gl) {
    webgl2 = {
      maxTextureSize: gl.getParameter(gl.MAX_TEXTURE_SIZE) as number,
      maxVertexAttribs: gl.getParameter(gl.MAX_VERTEX_ATTRIBS) as number,
      hasDepthTexture: true, // WebGL2 核心即含 depth texture，无需扩展
    };
    data.webgl2 = webgl2;
  }

  const snapshot: ProbeSnapshot = { webgpu, webgl2 };
  const backend = selectBackend(snapshot, REQ);
  const cfg = resolveRenderConfig(snapshot, REQ);
  data.backend = backend;
  data.config = cfg;

  push('probe.webgpu.present', webgpu !== null, webgpu ? 'ok' : 'null');
  push('probe.webgl2.present', webgl2 !== null, webgl2 ? 'ok' : 'null');
  push('select=webgpu', backend === 'webgpu', backend);
  push('config.maxTextureDimension2D in (0,8192]',
    cfg.maxTextureDimension2D > 0 && cfg.maxTextureDimension2D <= 8192, cfg.maxTextureDimension2D);
  push('config.useCompute=true', cfg.useCompute === true, cfg.useCompute);
  return { checks, data };
}