《游戏引擎实现原理》1.2 渲染器的分层：RHI / 渲染器 / 场景

src/render/
├── rhi/            RHI：设备、缓冲、纹理、管线、命令录制（不认识场景）
│   ├── rhi.ts          RHI 的统一词汇（接口与常量）
│   ├── webgpu-rhi.ts   WebGPU 后端
│   ├── webgl2-rhi.ts   WebGL2 后端
│   └── null-rhi.ts     NullRHI：只记录调用，供单测
├── scene.ts        场景：实例、相机、光源（纯数据，不认识 GPU）
├── renderer.ts     渲染器：读场景 → 录命令 → 提交（唯一认识两边的一层）
└── frame/          帧图：Pass 的组织与资源生命周期（第 14 章）

// file: src/render/rhi/rhi.ts
// tier: L3
//
// helio 渲染：RHI（渲染硬件接口）—— 渲染层的最底层。
// 它只描述「设备能做什么」，不认识场景、材质、光照，也不认识「帧」。
// 三种后端（WebGPU / WebGL2 / NullRHI）各自实现这组接口。
// 本节为类型级草图：真实设备句柄无法在命令行复现，需在浏览器中手动验证。

export type BufferUsage = 'vertex' | 'index' | 'uniform' | 'storage' | 'copy-src' | 'copy-dst';
export type TextureFormat = 'rgba8unorm' | 'bgra8unorm' | 'rgba16float' | 'depth32float';
export type TextureUsage = 'render-target' | 'sampled' | 'copy-src' | 'copy-dst';
export type RhiBackend = 'webgpu' | 'webgl2' | 'null';

export interface BufferDesc { readonly label: string; readonly size: number; readonly usage: readonly BufferUsage[]; }
export interface TextureDesc {
  readonly label: string;
  readonly width: number;
  readonly height: number;
  readonly format: TextureFormat;
  readonly usage: readonly TextureUsage[];
}
export interface ShaderModuleDesc { readonly label: string; readonly code: string; }

/** 后端能力表：渲染器据此决定用哪条路径（如 WebGL2 无 compute）。 */
export interface RhiCapabilities {
  readonly backend: RhiBackend;
  readonly maxTextureSize: number;
  readonly storageBuffers: boolean;
  readonly compute: boolean;
}

export interface RhiBuffer { readonly desc: BufferDesc; }
export interface RhiTexture { readonly desc: TextureDesc; }
export interface RhiShaderModule { readonly desc: ShaderModuleDesc; }
export interface RhiCommandBuffer { readonly label: string; }

/** 命令录制器：RHI 只认「命令」，不认「帧」——帧是渲染器层的概念。 */
export interface RhiCommandEncoder {
  beginRenderPass(target: RhiTexture, clear: readonly [number, number, number, number]): void;
  draw(vertexCount: number, instanceCount: number): void;
  endRenderPass(): void;
  finish(): RhiCommandBuffer;
}

/** 设备：RHI 的入口。渲染器持有它；场景永远不持有它。 */
export interface RhiDevice {
  readonly capabilities: RhiCapabilities;
  createBuffer(desc: BufferDesc): RhiBuffer;
  createTexture(desc: TextureDesc): RhiTexture;
  createShaderModule(desc: ShaderModuleDesc): RhiShaderModule;
  createCommandEncoder(): RhiCommandEncoder;
  submit(commands: readonly RhiCommandBuffer[]): void;
  destroy(): void;
}

// file: src/render/scene.ts
// tier: L3
//
// helio 渲染：场景层 —— 纯数据，不含任何 GPU 概念。
// 渲染器读它；它不认识渲染器，更不认识 RHI。
// 只依赖内核层的数学（第 8–9 章的 Vec3/Mat4）。本节为类型级草图，运行期见第 7 章。

export interface Vec3 { readonly x: number; readonly y: number; readonly z: number; }
export interface Mat4 { readonly m: Float32Array; } // 列主序 4x4
export interface Transform {
  readonly position: Vec3;
  readonly rotation: Vec3; // 欧拉角（弧度）
  readonly scale: Vec3;
}

export interface MeshInstance {
  readonly id: number;
  readonly meshId: number;
  readonly materialId: number;
  readonly transform: Transform;
  readonly worldMatrix: Mat4; // 由渲染器在剔除前算好，见第 7 章
  readonly visible: boolean;
}

export interface Camera {
  readonly view: Mat4;
  readonly projection: Mat4;
  readonly near: number;
  readonly far: number;
}

export interface Light {
  readonly kind: 'directional' | 'point' | 'spot';
  readonly color: Vec3;
  readonly intensity: number;
}

/** 场景 = 一堆实例 + 一台相机 + 若干光源。没有「怎么画」，只有「有什么」。 */
export interface Scene {
  readonly instances: readonly MeshInstance[];
  readonly camera: Camera;
  readonly lights: readonly Light[];
}

// file: src/render/renderer.ts
// tier: L3
//
// helio 渲染：渲染器层 —— 帧的组织者。
// 它是唯一同时认识「场景」和「RHI」的一层：读场景 → 录命令 → 提交。
// 本节为类型级草图；真正跑起来在第 5 章（后端）与第 14 章（帧图）。

import type { RhiDevice } from './rhi/rhi.ts';
import type { Scene } from './scene.ts';

export interface FrameContext {
  readonly frameIndex: number;
  readonly deltaMs: number;
}

export interface Renderer {
  /** 初始化：拿到设备后建立管线与常驻 GPU 资源。 */
  init(device: RhiDevice): void;
  /** 组织并提交一帧：读场景 → 录命令 → 提交给设备。这是「帧」的唯一出处。 */
  renderFrame(scene: Scene, ctx: FrameContext): void;
  /** 释放 GPU 资源。 */
  shutdown(): void;
}

// file: src/render/dep-graph.ts
// tier: L1
// verify: npx vitest run src/render/dep-graph.test.ts
//
// helio 渲染：三层依赖方向的可执行守卫。
// RHI 在最底，Scene 是纯数据，Renderer 是唯一同时认识两者的层。
// 依赖只准 Renderer -> {RHI, Scene}；RHI 与 Scene 都不认识 Renderer。

export const RENDER_LAYERS = ['rhi', 'scene', 'renderer'] as const;
export type RenderLayer = (typeof RENDER_LAYERS)[number];

/** 每层允许 import 的层。renderer 依赖 rhi/scene；rhi 与 scene 都不依赖任何上层。 */
export const ALLOWED: Record<RenderLayer, readonly RenderLayer[]> = {
  rhi: [],
  scene: [],
  renderer: ['rhi', 'scene'],
};

export interface RenderModule {
  readonly name: string;
  readonly layer: RenderLayer;
  readonly imports: readonly RenderLayer[];
}

export interface Violation {
  readonly from: string;
  readonly fromLayer: RenderLayer;
  readonly toLayer: RenderLayer;
}

/** 扫出一组渲染模块里所有不在 ALLOWED 内的非法依赖边。 */
export function findIllegalDeps(modules: readonly RenderModule[]): Violation[] {
  const out: Violation[] = [];
  for (const m of modules) {
    const allowed = ALLOWED[m.layer];
    for (const dep of m.imports) {
      if (!allowed.includes(dep)) out.push({ from: m.name, fromLayer: m.layer, toLayer: dep });
    }
  }
  return out;
}

✓ render dep-graph > 合法依赖：renderer 同时依赖 rhi 与 scene
✓ render dep-graph > RHI 反向依赖 renderer 是非法的
✓ render dep-graph > 场景层不得依赖 RHI：数据不认识 GPU
✓ render dep-graph > 只有 renderer 层允许非空依赖集合
 Test Files  1 passed (1)
      Tests  4 passed (4)