docs(rendering): sync outline inputs and volumetric prewarm docs

docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md

@@ -10,6 +10,17 @@
 
 ## 概览
 
+## 2026-04-10 同步补充
+
+以下内容以当前 `BuiltinObjectIdOutlinePass.h/.cpp` 为准：
+
+- `Render(...)` 的输入不再是裸 `objectIdTextureView` 指针，而是
+  [ObjectIdOutlinePassInputs](../ObjectIdOutlinePassInputs/ObjectIdOutlinePassInputs.md)；
+  这让调用方可以同时声明 object-id 纹理在进入 pass 前的资源状态。
+- `EnsureInitialized(...)` / `CreateResources(...)` 现在按 backend、目标颜色格式和目标 `sampleCount` 重新建资源；当 surface 配置变化时会销毁旧的 pipeline / descriptor 重新创建。
+- viewport / scissor 已经按 `surface.GetRenderArea()` 取值，不再固定覆盖整张 surface。
+- 当 `surface.IsAutoTransitionEnabled()` 为 `true` 时，pass 会把目标颜色从 `surface.GetColorStateAfter()` 切到 `RenderTarget`，并把 object-id 纹理从 `inputs.objectIdTextureState` 切到 `PixelShaderResource`，结束后再恢复。
+
 `BuiltinObjectIdOutlinePass` 处在“object-id 已经生成，但主场景也已经画完”的阶段。它本身不负责提取可见物体，也不负责生成 object-id 纹理，而是消费这些上游结果：
 
 - object-id 纹理通常来自 `BuiltinObjectIdPass`。

docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/Render.md

@@ -1,5 +1,23 @@
 # BuiltinObjectIdOutlinePass::Render
 
+> 2026-04-10 同步：当前签名与语义如下；若下文旧段落仍出现旧的 `objectIdTextureView` 单参数写法，请以这里为准。
+
+```cpp
+bool Render(
+    const RenderContext& renderContext,
+    const RenderSurface& surface,
+    const ObjectIdOutlinePassInputs& inputs,
+    const std::vector<uint64_t>& selectedObjectIds,
+    const ObjectIdOutlineStyle& style = {});
+```
+
+## 当前语义更新
+
+- object-id 输入纹理由 [ObjectIdOutlinePassInputs](../ObjectIdOutlinePassInputs/ObjectIdOutlinePassInputs.md) 描述，同时显式携带进入 pass 前的资源状态。
+- `EnsureInitialized(...)` 现在按 backend、目标颜色格式和目标 `sampleCount` 重新建资源；surface 变化时会销毁旧的 pipeline / descriptor 再创建。
+- viewport 和 scissor 取自 `surface.GetRenderArea()`，不再固定使用整张 surface。
+- 当 `surface.IsAutoTransitionEnabled()` 为 `true` 时，会把目标颜色从 `surface.GetColorStateAfter()` 切到 `RenderTarget`，并把 `inputs.objectIdTextureView` 从 `inputs.objectIdTextureState` 切到 `PixelShaderResource`，结束后再恢复。
+
 **命名空间**: `XCEngine::Rendering::Passes`
 
 **类型**: `method`

docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md

@@ -10,6 +10,15 @@
 
 ## 概览
 
+## 2026-04-10 同步补充
+
+以下内容以当前 `BuiltinVolumetricPass.h/.cpp` 为准：
+
+- 新增了公开预热接口 [PrepareVolumeResources](PrepareVolumeResources.md)，用于在真正 `Execute(...)` 之前把 cube proxy mesh 和可见 `NanoVDB` volume 的 GPU 资源准备好。
+- pipeline cache key 现在显式包含目标 surface 的 `sampleCount` 与 `sampleQuality`，不再只按 render state、shader、format 和 keyword 签名区分。
+- `Execute(...)` 仍要求 surface 具备“单颜色附件 + depth 附件”，但 viewport / scissor 现在按 `surface.GetRenderArea()` 生效。
+- volume 字段的真实上传与缓存复用由 `RenderResourceCache` 负责；`BuiltinVolumetricPass` 自己不做 legacy fallback。
+
 `BuiltinVolumetricPass` 是当前体积渲染链路的核心执行器。
 它继承自 `RenderPass`，但和普通 mesh pass 相比有几处明显特点：
 
@@ -50,6 +59,7 @@
 | [BuildInputLayout](BuildInputLayout.md) | 返回体积 pass 使用的顶点布局 |
 | [GetName](GetName.md) | 返回 pass 名称 |
 | [Initialize](Initialize.md) | 预热 builtin cube mesh 等资源 |
+| [PrepareVolumeResources](PrepareVolumeResources.md) | 预热可见体渲染所需的 mesh / volume GPU 资源 |
 | [Execute](Execute.md) | 绘制所有可见体积 |
 | [Shutdown](Shutdown.md) | 销毁缓存的 RHI 资源 |
 

docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Execute.md

@@ -4,6 +4,11 @@
 bool Execute(const RenderPassContext& context) override;
 ```
 
+## 2026-04-10 更新
+
+- `Execute(...)` 现在依赖 surface 的 `renderArea`、`sampleCount` 和 `sampleQuality` 契约；这些字段会进入 pipeline 选择与 viewport/scissor 设置。
+- volume 数据上传不是在这里兜底完成的；更推荐在前置阶段调用 [PrepareVolumeResources](PrepareVolumeResources.md) 先把 mesh / volume cache 预热好。
+
 把 `context.sceneData.visibleVolumes` 中的体积绘制到当前 render target。
 
 ## 当前实现流程

docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Initialize.md

@@ -4,6 +4,11 @@
 bool Initialize(const RenderContext& context) override;
 ```
 
+## 2026-04-10 更新
+
+- `Initialize(...)` 当前仍只是进入内部 `EnsureInitialized(...)`，重点是预热 builtin cube mesh 等基础资源。
+- 可见 volume 的 GPU 资源预热已经拆到 [PrepareVolumeResources](PrepareVolumeResources.md)；如果要在真正绘制前确保 `NanoVDB` 数据和 SRV 就绪，应调用那个入口。
+
 预热体积 pass 依赖的基础资源。
 
 ## 当前行为

docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/PrepareVolumeResources.md

@@ -0,0 +1,27 @@
+# BuiltinVolumetricPass::PrepareVolumeResources
+
+```cpp
+bool PrepareVolumeResources(
+    const RenderContext& context,
+    const RenderSceneData& sceneData);
+```
+
+在真正 `Execute(...)` 之前预热体渲染依赖的 mesh / volume GPU 资源。
+
+## 当前行为
+
+- 会先确保 builtin cube mesh 的基础资源已经初始化完成。
+- 当 `sceneData.visibleVolumes` 非空时，会先通过 `RenderResourceCache` 取到 cube proxy mesh 的缓存视图。
+- 遍历可见体积时，只会继续处理同时满足以下条件的项：
+  - `volumeField != nullptr`
+  - `material != nullptr`
+  - `volumeField->GetStorageKind() == VolumeStorageKind::NanoVDB`
+- 对于满足条件的体积，会调用 `RenderResourceCache::GetOrCreateVolumeField(...)` 预热 volume SRV；如果缓存创建失败，返回 `false`。
+- 如果没有可见体积，或所有可见体积都被过滤掉，函数仍然可以返回 `true`。
+
+## 相关文档
+
+- [BuiltinVolumetricPass](BuiltinVolumetricPass.md)
+- [Initialize](Initialize.md)
+- [Execute](Execute.md)
+- [VisibleVolumeItem](../../FrameData/VisibleVolumeItem/VisibleVolumeItem.md)

docs/api/XCEngine/Rendering/Passes/ObjectIdOutlinePassInputs/ObjectIdOutlinePassInputs.md

@@ -0,0 +1,27 @@
+# ObjectIdOutlinePassInputs
+
+**命名空间**: `XCEngine::Rendering::Passes`
+
+**类型**: `struct`
+
+**头文件**: `XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h`
+
+**描述**: object-id outline pass 的输入纹理描述，指定 object-id 视图及其进入 pass 前的资源状态。
+
+## 字段
+
+| 字段 | 说明 |
+|------|------|
+| `objectIdTextureView` | object-id 纹理视图。 |
+| `objectIdTextureState` | object-id 纹理在进入 pass 前的资源状态。 |
+
+## 当前作用
+
+- 为 `BuiltinObjectIdOutlinePass::Render(...)` 提供 object-id SRV 与恢复状态信息。
+- 当 surface 开启自动状态切换时，`objectIdTextureState` 会被当作进入 pass 前的原始状态，用于从/恢复到 `PixelShaderResource`。
+
+## 相关文档
+
+- [BuiltinObjectIdOutlinePass](../BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)
+- [Render](../BuiltinObjectIdOutlinePass/Render.md)
+- [ObjectIdOutlineStyle](../ObjectIdOutlineStyle/ObjectIdOutlineStyle.md)

docs/api/XCEngine/Rendering/RenderSurface/SetAutoTransitionEnabled.md

@@ -6,6 +6,15 @@
 void SetAutoTransitionEnabled(bool enabled);
 ```
 
+## 2026-04-10 更新
+
+- 当前这个开关不再只服务少数颜色路径；多条 Rendering pass 都会在它为 `true` 时按 `RenderSurface` 上记录的约定插入 barrier。
+- 自动切换涉及的不只是 color，部分 pass 也会读取
+  [GetDepthStateBefore](GetDepthStateBefore.md) /
+  [GetDepthStateAfter](GetDepthStateAfter.md)
+  来接管 depth 附件。
+- `RenderSurface` 自身并不执行 barrier；它只保存契约。真正的状态切换仍发生在具体 pass 的执行路径里。
+
 ## 参数
 
 - `enabled` - `true` 表示允许读取 `colorStateBefore / colorStateAfter` 并自动插入颜色附件 barrier；`false` 表示由调用方或 pass 自己管理。