# Shader 统一预编译缓存并入 Library 正式方案

文档日期：2026-04-11

## 1. 目标

把 shader 的预编译结果正式并入现有 `Library/Artifacts` 体系，不再允许出现：

1. project shader 走 `Library`，builtin shader 走裸加载。
2. 运行时每次开编辑器都重新现场编译重 shader。
3. 只修 D3D12，一到 Vulkan / OpenGL 又退回运行时临时编译。

本轮正式目标：

1. builtin shader 与 project shader 统一走同一个 artifact 产物格式。
2. `ShaderStageVariant` 保持现有 authoring / runtime 变体模型不变，不扩成“每后端一个 variant”。
3. 每个 variant 可以携带“按后端区分的已编译 payload”。
4. D3D12 / Vulkan / OpenGL 运行时优先消费 artifact 中的 payload，只有 miss 时才 fallback 到现场编译。

## 2. 架构原则

### 2.1 唯一正式缓存位置

唯一正式 shader 预编译缓存位置是：

`project/Library/Artifacts/.../main.xcshader`

不新增独立 runtime cache 目录，不做旁路缓存。

### 2.2 builtin shader 也必须纳入 Library

外部标识仍然保持：

`builtin://shaders/...`

但在有 project root 时，真实加载路径应优先变成：

`Library/Artifacts/.../main.xcshader`

这样 builtin shader 与普通 `Assets/*.shader` 在缓存语义上完全一致。

### 2.3 不改变现有 variant 选择逻辑

现有很多代码和测试都依赖：

1. authoring variant 可以是 `Generic`
2. 运行时按 backend 查找时先找精确 backend，再回退 `Generic`

因此不把一个 `Generic` variant 展开成三份后端 variant，而是让一个 variant 内部携带：

1. 旧字段 `compiledBinary`
2. 新字段 `backendCompiledBinaries`

## 3. 数据模型

### 3.1 运行时 compile desc

`RHI::ShaderCompileDesc` 新增：

1. `compiledBinaryBackend`
2. `compiledBinary`

含义：

1. source / fileName 仍然描述“可回退到现场编译的输入”
2. compiledBinary 描述“当前后端可直接消费的已编译 payload”

### 3.2 shader variant

`Resources::ShaderStageVariant` 支持：

1. `GetCompiledBinaryForBackend(...)`
2. `SetCompiledBinaryForBackend(...)`

语义：

1. backend-specific variant 可以继续把本后端 payload 放在旧 `compiledBinary`
2. `Generic` variant 的 D3D12 / Vulkan / OpenGL payload 放在 `backendCompiledBinaries`

### 3.3 artifact schema

shader artifact schema 升级为 `6`，`ShaderVariantArtifactHeader` 新增：

1. `backendCompiledBinaryCount`

并追加 `ShaderBackendCompiledBinaryArtifactHeader + payload` 序列。

## 4. 导入阶段

导入 `.shader` 时：

1. 先用 `ShaderLoader` 生成现有 authoring/runtime variant。
2. 对每个 pass / variant 生成运行时 compile desc。
3. 按目标后端尝试预编译：
   - D3D12：生成 DXBC
   - Vulkan：生成 Vulkan SPIR-V
   - OpenGL：生成 OpenGL-target SPIR-V
4. 把结果写回 variant。
5. 最终统一写入 `main.xcshader` artifact。

后端目标规则：

1. `Generic` variant 预编译到 D3D12 / Vulkan / OpenGL
2. backend-specific variant 只预编译自己的 backend

失败策略：

1. 预编译失败不阻断 import
2. artifact 仍然照常生成
3. 运行时保持 fallback 能力
4. 日志明确记录 pass / stage / backend / reason

## 5. builtin shader 接入方式

### 5.1 ResourceManager

`ResourceManager::LoadResource(...)` 在 shader + builtin path 情况下：

1. 解析到真实 builtin shader 资产路径
2. 在当前 project 的 `Library` 中确保对应 artifact
3. 真正加载 artifact
4. 资源对外 path 仍然恢复成 `builtin://...`

### 5.2 AssetDatabase

由于 builtin shader 资产位于 project root 外部：

1. 允许绝对路径解析成相对 project root 的 `../engine/...`
2. 这些外部 source record 不写 `.meta`
3. 使用 synthetic GUID / synthetic meta hash
4. `Refresh()` 时显式扫描 builtin shader 资产，避免下次启动把 builtin artifact 当 orphan 清掉

## 6. 运行时消费

### 6.1 D3D12

1. `D3D12Shader` 增加 `InitializeFromBytecode(...)`
2. `CompileD3D12Shader(...)` 优先命中 `compiledBinaryBackend == D3D12`
3. miss 时才走 `D3DCompile(...)`
4. `CreateShader(...)` 统一复用这条逻辑

### 6.2 Vulkan

1. `CompileSpirvShader(...)` 支持直接消费 `compiledBinaryBackend == Vulkan`
2. `VulkanDevice / VulkanPipelineState` 通过既有 `CompileVulkanShader(...)` 自动命中缓存 payload

### 6.3 OpenGL

1. 若命中 `compiledBinaryBackend == OpenGL`
2. 则把该 payload 作为 SPIR-V 输入
3. 继续走现有 `SPIR-V -> GLSL` 转译路径
4. 原始 HLSL source 仍保留给 sampler/texture 绑定推导逻辑使用

## 7. 验收标准

### 7.1 工程标准

1. `shader_tests` 全绿
2. `XCEditor` 能完整编译通过

### 7.2 行为标准

1. shader artifact roundtrip 后不丢失 backend payload
2. builtin shader 与 project shader 都能命中 `Library/Artifacts`
3. D3D12 / Vulkan / OpenGL 运行时在 payload 存在时不再重复现场编译

### 7.3 性能标准

1. 影响 NanoVDB 首帧的 volumetric shader 不再在每次启动时重编
2. editor 打开主场景时，shader stall 不再成为 `SceneReady` 的主瓶颈

## 8. 后续扩展

后续若继续做：

1. import-time completeness 标记
2. 运行时回写 artifact
3. PSO cache blob
4. 更完整的 shader compile telemetry

都必须建立在本方案之上，不允许再引入平行缓存体系。