docs(rendering): refine selection and object id pass docs

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

@@ -12,20 +12,20 @@
 
 `BuiltinObjectIdPass` 可以理解成主场景渲染旁边的一条辅助输出路径：
 
-- 主颜色目标仍由当前 `RenderPipeline` 负责。
+- 主颜色目标仍由当前 `RenderPipeline` 负责
-- object-id 目标由这条 pass 用单独 shader 再画一遍可见物体。
+- object-id 目标由这条 pass 用单独 shader 再画一遍可见物体
-- 每个物体的 `GameObject::GetID()` 会被编码成 RGBA 颜色写入目标纹理。
+- 每个物体的 `GameObject::GetID()` 会被编码成 RGBA 颜色写入目标纹理
 
 这样后续只要采样这张 object-id 纹理，就能做选中描边、拾取或调试显示，而不必回读主颜色缓冲。
 
 ## 当前实现流程
 
-1. 校验 `RenderContext`、颜色附件、深度附件和 `RenderSurface` 的 render area。
+1. 校验 `RenderContext`、单颜色附件、深度附件和 `RenderSurface` 的 render area。
-2. 惰性创建 pipeline layout、pipeline state 和 builtin object-id shader。
+2. 按当前 backend、surface 格式和采样描述惰性创建或重建 pipeline layout、pipeline state 与 builtin object-id shader。
-3. 如果 `RenderSurface` 开启自动状态切换，先把颜色附件切到 `RenderTarget`。
+3. 如果 `RenderSurface` 开启自动状态切换，则先把颜色附件切到 `RenderTarget`，把深度附件切到 `DepthWrite`。
-4. 清空 object-id 颜色目标为全零。
+4. 清空当前 render area 范围内的 object-id 颜色目标和深度目标。
 5. 遍历 `RenderSceneData::visibleItems`，按物体 ID 建立或复用常量缓冲并发出 draw call。
-6. 若开启自动状态切换，再把颜色附件切回 `surface.GetColorStateAfter()`。
+6. 若开启自动状态切换，再把颜色附件和深度附件恢复到 `surface` 记录的 after 状态。
 
 ## 关键实现细节
 

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

@@ -11,18 +11,19 @@ bool Render(
 
 当前实现会：
 
-1. 校验 `context`、颜色附件、深度附件和 `surface.GetRenderArea()`。
+1. 校验 `context`、单颜色附件、深度附件和 `surface.GetRenderArea()`。
-2. 调用惰性初始化，必要时创建 shader、pipeline layout 和 pipeline state。
+2. 调用惰性初始化，必要时按当前 backend、surface 格式与采样描述创建或重建 shader、pipeline layout 和 pipeline state。
-3. 如果 `surface` 开启自动状态切换，把第一个颜色附件切到 `RenderTarget`。
+3. 如果 `surface` 开启自动状态切换，把第一个颜色附件切到 `RenderTarget`，同时把深度附件切到 `DepthWrite`。
-4. 把当前 render area 清成全零 object-id 颜色。
+4. 把当前 render area 清成全零 object-id 颜色，并把深度清到默认值。
 5. 遍历 `sceneData.visibleItems`，为每个 `gameObject` 编码 object-id 并发出 draw call。
-6. 如果开启自动状态切换，再把颜色附件切回 `surface.GetColorStateAfter()`。
+6. 如果开启自动状态切换，再把颜色附件切回 `surface.GetColorStateAfter()`，把深度附件切回 `surface.GetDepthStateAfter()`。
 
 ## 当前细节
 
 - viewport 与 scissor 使用 `surface.GetRenderArea()`，不是整张 surface。
 - 每个 object ID 会缓存一套独立常量 descriptor set。
 - section mesh 会按 `VisibleRenderItem::sectionIndex` 绘制对应 section；否则退回整 mesh。
+- 当前自动状态切换会同时消费 `RenderSurface` 的颜色和深度 before/after 状态。
 
 ## 返回值
 

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

@@ -17,14 +17,16 @@
 
 它不是 `RenderPass` 子类，而是一个自管理资源的独立 helper。
 
+当前接口已经把输入纹理打包为 [SelectionOutlinePassInputs](../SelectionOutlinePassInputs/SelectionOutlinePassInputs.md)，并允许调用方显式声明 selection mask 与 depth 在进入本 pass 前的资源状态。
+
 ## 当前执行流程
 
-1. [Render](Render.md) 校验 render context、mask view、depth view 和 surface
+1. [Render](Render.md) 校验 render context、输入纹理、单颜色目标和有效 render area
 2. `EnsureInitialized(...)` 按后端、render target 格式和采样数准备 pipeline 资源
 3. 写入 outline 常量
 4. 更新 selection mask / depth 的 SRV 绑定
-5. 视情况做资源状态切换
+5. 若目标 `surface` 开启自动状态切换，则按 `SelectionOutlinePassInputs` 提供的状态把输入切到 `PixelShaderResource`，并在结束后恢复
-6. 绘制一次全屏三角形并恢复资源状态
+6. 绘制一次全屏三角形并结束 render pass
 
 ## 关键资源
 
@@ -34,6 +36,7 @@
 | `m_constantPool` / `m_constantSet` | outline 常量缓冲 |
 | `m_texturePool` / `m_textureSet` | selection mask 与 depth SRV |
 | `m_shaderPath` | 当前使用的 selection-outline shader 路径 |
+| `m_renderTargetFormat` / `m_renderTargetSampleCount` | 当前缓存资源所对应的目标格式与采样数 |
 
 ## 当前实现边界
 
@@ -41,16 +44,18 @@
 - 当前不写深度
 - 输出样式由 [SelectionOutlineStyle](../SelectionOutlineStyle/SelectionOutlineStyle.md) 控制
 - 输入纹理来源由 [SelectionOutlinePassInputs](../SelectionOutlinePassInputs/SelectionOutlinePassInputs.md) 描述
+- 当 `surface.IsAutoTransitionEnabled()` 为 `false` 时，调用方需要自己保证目标与输入纹理已经处于正确状态
+- 当前不再硬编码限制为 `D3D12`；只要配置 shader 在当前 backend 上存在兼容 graphics variant，即可创建资源并执行
 
 ## 公开方法
 
 | 方法 | 说明 |
 |------|------|
-| [Constructor](Constructor.md) | 创建 pass，可注入 shader 路径 |
+| [Constructor](Constructor.md) | 创建 pass，可注入 shader 路径。 |
-| [SetShaderPath](SetShaderPath.md) | 更新 shader 路径并清空已创建资源 |
+| [SetShaderPath](SetShaderPath.md) | 更新 shader 路径并清空已创建资源。 |
-| [GetShaderPath](GetShaderPath.md) | 返回当前 shader 路径 |
+| [GetShaderPath](GetShaderPath.md) | 返回当前 shader 路径。 |
-| [Render](Render.md) | 执行全屏描边合成 |
+| [Render](Render.md) | 执行全屏描边合成。 |
-| [Shutdown](Shutdown.md) | 销毁内部 RHI 资源 |
+| [Shutdown](Shutdown.md) | 销毁内部 RHI 资源。 |
 
 ## 相关文档
 

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

@@ -12,13 +12,20 @@ bool Render(
 
 ## 当前实现流程
 
-1. 校验 render context、mask/depth 纹理与 surface
+1. 校验 `renderContext`、`inputs.selectionMaskTextureView`、`inputs.depthTextureView`。
-2. `EnsureInitialized(...)`
+2. 要求 `surface` 具备单个有效颜色附件，以及有效的 `renderArea`。
-3. 构建 `OutlineConstants`
+3. 调用 `EnsureInitialized(renderContext, surface)`；如果后端、render target format 或 sample count 变化，会重建内部 pipeline 资源。
-4. 写入常量并更新两个 SRV
+4. 构建 `OutlineConstants`，并把 selection mask / depth 两个 SRV 写入纹理 descriptor set。
-5. 自动状态切换开启时，把目标切到 `RenderTarget`、输入切到 `PixelShaderResource`
+5. 若 `surface.IsAutoTransitionEnabled()` 为 `true`，则把目标切到 `RenderTarget`，同时把两个输入纹理按 `SelectionOutlinePassInputs` 提供的状态切到 `PixelShaderResource`。
-6. 绑定两个 descriptor set，执行一次 `Draw(3, 1, 0, 0)`
+6. 使用 `surface.GetRenderArea()` 设置 viewport / scissor，执行一次 `Draw(3, 1, 0, 0)`。
-7. 恢复资源状态
+7. 结束 render pass，并在自动状态切换开启时恢复目标与输入纹理状态。
+
+## 关键语义
+
+- 输入结构显式携带了 selection mask 与 depth 纹理的进入状态，因此本 pass 可以在自动状态切换模式下自行恢复它们。
+- 当前只写 `surface` 的第一个颜色附件，不写深度。
+- 当自动状态切换关闭时，调用方必须自己保证输出目标和两个输入纹理已经处于正确状态。
+- 这条路径当前会按目标格式和采样数缓存/重建 pipeline 资源。
 
 ## 相关文档