diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetDepthStateAfter.md b/docs/api/XCEngine/Rendering/RenderSurface/GetDepthStateAfter.md
new file mode 100644
index 00000000..10cbe5bd
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/RenderSurface/GetDepthStateAfter.md
@@ -0,0 +1,33 @@
+# RenderSurface::GetDepthStateAfter
+
+返回深度附件在本次渲染结束后预期应处于的状态。
+```cpp
+RHI::ResourceStates GetDepthStateAfter() const;
+```
+
+## 返回值
+
+- 返回内部保存的深度附件“结束状态”；默认值是 `DepthWrite`。
+
+## 当前语义
+
+- 这个返回值描述的是阶段性契约，不是对 GPU 实际状态的即时查询。
+- 当 [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) 为 `true` 时，多个 builtin 渲染路径会在结束 render pass 后把深度附件切回这个状态。
+- `SceneRenderer` 在派生 fullscreen surface 时会继续保留这份深度 after 状态，使后续阶段仍能沿用同一份资源状态约定。
+
+## 调用方影响
+
+- 如果后续 pass 依赖深度纹理以 `PixelShaderResource` 等状态被采样，调用方应显式把这个返回值对应的 setter 配置成匹配状态。
+- 默认值 `DepthWrite` 适合“本阶段前后都继续作为深度写入目标”的简单场景。
+
+## 测试覆盖
+
+- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
+- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
+
+## 相关文档
+
+- [RenderSurface](RenderSurface.md)
+- [SetDepthStateAfter](SetDepthStateAfter.md)
+- [GetDepthStateBefore](GetDepthStateBefore.md)
+- [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md)
diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetDepthStateBefore.md b/docs/api/XCEngine/Rendering/RenderSurface/GetDepthStateBefore.md
new file mode 100644
index 00000000..e5a01921
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/RenderSurface/GetDepthStateBefore.md
@@ -0,0 +1,33 @@
+# RenderSurface::GetDepthStateBefore
+
+返回深度附件进入本次渲染前预期所处的状态。
+```cpp
+RHI::ResourceStates GetDepthStateBefore() const;
+```
+
+## 返回值
+
+- 返回内部保存的深度附件“起始状态”；默认值是 `DepthWrite`。
+
+## 当前语义
+
+- 这不是逐资源的真实状态查询，而是 `RenderSurface` 暴露给调用方和 builtin pass 的契约值。
+- 当 [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) 为 `true` 时，主场景、depth-style 与 object-id 这些路径会把它作为深度附件进入本次 pass 前的 barrier 来源状态。
+- `SceneRenderer` 在复用深度附件构造 fullscreen 阶段 surface 时，也会保留这个值。
+
+## 调用方影响
+
+- 如果调用方关闭自动状态切换，就必须自己保证深度附件真的处于这里声明的状态。
+- 这个值通常和 [GetDepthStateAfter](GetDepthStateAfter.md) 配对出现，用来描述同一块深度资源在本阶段前后的状态约定。
+
+## 测试覆盖
+
+- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
+- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
+
+## 相关文档
+
+- [RenderSurface](RenderSurface.md)
+- [SetDepthStateBefore](SetDepthStateBefore.md)
+- [GetDepthStateAfter](GetDepthStateAfter.md)
+- [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md)
diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetSampleCount.md b/docs/api/XCEngine/Rendering/RenderSurface/GetSampleCount.md
new file mode 100644
index 00000000..403bcb9e
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/RenderSurface/GetSampleCount.md
@@ -0,0 +1,28 @@
+# RenderSurface::GetSampleCount
+
+返回当前 surface 的 sample count。
+```cpp
+uint32_t GetSampleCount() const;
+```
+
+## 返回值
+
+- 返回内部保存的采样数；默认值是 `1`。
+
+## 当前语义
+
+- 这个值会被 `RenderSurfacePipelineUtils` 消费并写入图形管线描述。
+- `SceneRenderer` 也会用它判断主场景输出是否仍满足 fullscreen post-process / final-output 所要求的单采样约束。
+- 如果调用方此前通过 [SetSampleDesc](SetSampleDesc.md) 传入了 `0`，这里返回的仍会是规范化后的 `1`。
+
+## 测试覆盖
+
+- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
+- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
+
+## 相关文档
+
+- [RenderSurface](RenderSurface.md)
+- [SetSampleDesc](SetSampleDesc.md)
+- [GetSampleQuality](GetSampleQuality.md)
+- [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md)
diff --git a/docs/api/XCEngine/Rendering/RenderSurface/GetSampleQuality.md b/docs/api/XCEngine/Rendering/RenderSurface/GetSampleQuality.md
new file mode 100644
index 00000000..599674ff
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/RenderSurface/GetSampleQuality.md
@@ -0,0 +1,33 @@
+# RenderSurface::GetSampleQuality
+
+返回当前 surface 的 sample quality。
+```cpp
+uint32_t GetSampleQuality() const;
+```
+
+## 返回值
+
+- 返回内部保存的 quality 值；默认值是 `0`。
+
+## 当前语义
+
+- 这个值会被 `RenderSurfacePipelineUtils` 继续写入 `GraphicsPipelineDesc.sampleQuality`。
+- 当前实现保证单采样 surface 的 quality 总是 `0`；只有多采样时这里才可能返回调用方显式设置的非零值。
+- `CameraRenderRequest` 的 surface 合法性检查也依赖“单采样时 quality 必须为 `0`”这条约束。
+
+## 调用方影响
+
+- 如果后端只识别 `sampleCount`，调用方仍可以保留统一的 `RenderSurface` 描述，而把 `sampleQuality` 当作由具体 RHI 选择性消费的附加信息。
+- 对 fullscreen post-process / final-output 链路而言，`sampleCount == 1 && sampleQuality == 0` 才是当前允许的输入形态。
+
+## 测试覆盖
+
+- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
+- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
+
+## 相关文档
+
+- [RenderSurface](RenderSurface.md)
+- [SetSampleDesc](SetSampleDesc.md)
+- [GetSampleCount](GetSampleCount.md)
+- [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md)
diff --git a/docs/api/XCEngine/Rendering/RenderSurface/RenderSurface.md b/docs/api/XCEngine/Rendering/RenderSurface/RenderSurface.md
index 6cdef26e..bd1b46bc 100644
--- a/docs/api/XCEngine/Rendering/RenderSurface/RenderSurface.md
+++ b/docs/api/XCEngine/Rendering/RenderSurface/RenderSurface.md
@@ -6,31 +6,33 @@
 
 **头文件**: `XCEngine/Rendering/RenderSurface.h`
 
-**描述**: 描述当前渲染目标表面，包括尺寸、颜色/深度附件、自定义渲染区域、清屏色覆盖和颜色附件自动状态切换策略。
+**描述**: 描述当前渲染目标表面，包括尺寸、颜色/深度附件、自定义渲染区域、清屏覆盖、自动状态切换，以及与管线创建对齐的 sample 描述。
 
 ## 概述
 
-`RenderSurface` 的作用，是把“这一帧到底往哪里画”从具体 swap chain 或 framebuffer 管理逻辑里抽离出来。
+`RenderSurface` 把“这一次渲染要写到哪里、写之前/写之后资源预期处于什么状态”从具体 swap chain、framebuffer 和缓存分配逻辑里抽离出来，变成 `Planning`、`Execution`、builtin pass 与 editor overlay 都能复用的统一协议对象。
 
 当前它负责描述：
 
-- 宽高
-- 一组颜色附件
-- 一个深度附件
-- 可选自定义 render area
-- 可选清屏色覆盖
-- 颜色附件渲染前后状态
-- 是否自动执行颜色附件状态切换
+- 宽高。
+- 一组颜色附件。
+- 一个可选深度附件。
+- 一个可选自定义 render area。
+- 一个可选清屏颜色覆盖。
+- 颜色附件共享的 before / after 状态。
+- 深度附件共享的 before / after 状态。
+- 是否由渲染路径自动执行颜色/深度附件状态切换。
+- 当前 surface 的 MSAA `sampleCount` / `sampleQuality`。
 
-这类抽象很符合商业引擎里 render target / render surface 的常见分层，因为同一条渲染管线不应该只会往窗口 back buffer 画。
+`RenderSurface` 自己不拥有 GPU 资源，也不验证附件尺寸、资源类型或 sample 描述是否真实匹配；它只是把这组约束交给调用方和具体渲染路径消费。
 
 ## 当前实现边界
 
-- 当前只为颜色附件维护统一的 `stateBefore` / `stateAfter`，不是每个附件单独配置。
-- 自动状态切换当前只处理颜色附件，不处理深度附件。
-- 自定义 render area 会在设置时和取回时都被夹到当前 surface 尺寸范围内。
-- 当前不会校验附件数量、附件尺寸与 `RenderSurface` 宽高是否匹配。
-- 当前没有 load/store action、MSAA resolve、mip slice 或 array slice 等更丰富的 surface 配置。
+- 颜色附件仍只有一组统一的 `colorStateBefore` / `colorStateAfter`，深度附件也只有一组统一的 `depthStateBefore` / `depthStateAfter`；它不是逐 attachment 的精细状态表。
+- 当 [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) 为 `true` 时，`BuiltinForwardPipeline`、`BuiltinDepthStylePassBase`、`BuiltinObjectIdPass`、`BuiltinInfiniteGridPass` 等路径都会消费这些 before / after 状态；关闭自动切换后，`RenderSurface` 只保留契约信息，不会主动纠正真实 GPU 状态。
+- [SetSampleDesc](SetSampleDesc.md) 会把 `sampleCount == 0` 规范化为单采样 `1, 0`；只有 `sampleCount > 1` 时 `sampleQuality` 才保留调用方传入值。
+- `SceneRenderer` 当前要求 fullscreen post-process / final-output 链路的主场景 surface 为单采样，因此多重采样主表面不会进入这两段 fullscreen 阶段。
+- 当前没有 load/store action、resolve target、mip slice、array slice 等更细粒度的 surface 配置。
 
 ## 公开方法
 
@@ -51,28 +53,35 @@
 | [GetRenderArea](GetRenderArea.md) | 获取当前实际生效的渲染区域。 |
 | [GetRenderAreaWidth](GetRenderAreaWidth.md) | 获取当前渲染区域宽度。 |
 | [GetRenderAreaHeight](GetRenderAreaHeight.md) | 获取当前渲染区域高度。 |
-| [SetClearColorOverride](SetClearColorOverride.md) | 设置清屏色覆盖。 |
-| [ClearClearColorOverride](ClearClearColorOverride.md) | 清除清屏色覆盖。 |
-| [HasClearColorOverride](HasClearColorOverride.md) | 判断是否启用了清屏色覆盖。 |
-| [GetClearColorOverride](GetClearColorOverride.md) | 获取清屏色覆盖值。 |
-| [SetAutoTransitionEnabled](SetAutoTransitionEnabled.md) | 设置是否自动切换颜色附件状态。 |
-| [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) | 查询是否自动切换颜色附件状态。 |
+| [SetClearColorOverride](SetClearColorOverride.md) | 设置清屏颜色覆盖。 |
+| [ClearClearColorOverride](ClearClearColorOverride.md) | 清除清屏颜色覆盖。 |
+| [HasClearColorOverride](HasClearColorOverride.md) | 判断是否启用了清屏颜色覆盖。 |
+| [GetClearColorOverride](GetClearColorOverride.md) | 获取清屏颜色覆盖值。 |
+| [SetAutoTransitionEnabled](SetAutoTransitionEnabled.md) | 设置是否自动切换附件状态。 |
+| [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) | 查询是否自动切换附件状态。 |
 | [SetColorStateBefore](SetColorStateBefore.md) | 设置渲染前颜色附件状态。 |
 | [GetColorStateBefore](GetColorStateBefore.md) | 获取渲染前颜色附件状态。 |
 | [SetColorStateAfter](SetColorStateAfter.md) | 设置渲染后颜色附件状态。 |
 | [GetColorStateAfter](GetColorStateAfter.md) | 获取渲染后颜色附件状态。 |
+| [SetDepthStateBefore](SetDepthStateBefore.md) | 设置渲染前深度附件状态。 |
+| [GetDepthStateBefore](GetDepthStateBefore.md) | 获取渲染前深度附件状态。 |
+| [SetDepthStateAfter](SetDepthStateAfter.md) | 设置渲染后深度附件状态。 |
+| [GetDepthStateAfter](GetDepthStateAfter.md) | 获取渲染后深度附件状态。 |
+| [SetSampleDesc](SetSampleDesc.md) | 设置 sample count / quality。 |
+| [GetSampleCount](GetSampleCount.md) | 获取 sample count。 |
+| [GetSampleQuality](GetSampleQuality.md) | 获取 sample quality。 |
 
 ## 设计说明
 
-把 surface 做成独立对象，而不是让 pipeline 直接吃裸 `RHIResourceView*`，好处很明确：
+把 `RenderSurface` 做成独立对象的价值在当前重构后的渲染链路里更直接：
 
-- 目标尺寸和附件集合可以一起传递。
-- 清屏策略和资源状态策略可以挂在目标上，而不是散落在调用点。
-- 同一条管线更容易复用于 back buffer、离屏纹理和 editor preview surface。
+- `SceneRenderer` 可以在构造 post-process / final-output request 时复制颜色/深度附件约束、sample 描述和 render area，而不必重新展开 swap chain 细节。
+- `BuiltinForwardPipeline` 与多个 builtin pass 可以从同一份 surface 描述中同时解析附件格式、状态切换与 sample 描述，避免每个调用点重复拼装 `GraphicsPipelineDesc` 前置条件。
+- Editor overlay、selection outline、object-id 等附加阶段可以复用主场景输出的深度/颜色状态约定，而不需要各自发明一套 surface 协议。
 
 ## 相关文档
 
 - [当前模块](../Rendering.md)
 - [RenderContext](../RenderContext/RenderContext.md)
-- [RenderPipeline](../RenderPipeline/RenderPipeline.md)
+- [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md)
 - [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetDepthStateAfter.md b/docs/api/XCEngine/Rendering/RenderSurface/SetDepthStateAfter.md
new file mode 100644
index 00000000..632b8049
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/RenderSurface/SetDepthStateAfter.md
@@ -0,0 +1,28 @@
+# RenderSurface::SetDepthStateAfter
+
+设置深度附件在本次渲染结束后预期应回到的统一状态。
+```cpp
+void SetDepthStateAfter(RHI::ResourceStates state);
+```
+
+## 参数
+
+- `state` - 调用方希望深度附件在本阶段结束后处于的资源状态。
+
+## 当前语义
+
+- 这个值只写入 `RenderSurface` 内部，不会主动触发过渡。
+- 当 [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) 为 `true` 时，`BuiltinForwardPipeline`、`BuiltinDepthStylePassBase`、`BuiltinObjectIdPass` 等路径会在绘制结束后把深度附件从 `DepthWrite` 切回这里声明的状态。
+- 一些 post-scene / overlay 路径会把它当作“主场景阶段结束后的深度基线状态”继续消费。
+
+## 测试覆盖
+
+- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
+- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
+
+## 相关文档
+
+- [RenderSurface](RenderSurface.md)
+- [GetDepthStateAfter](GetDepthStateAfter.md)
+- [SetDepthStateBefore](SetDepthStateBefore.md)
+- [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md)
diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetDepthStateBefore.md b/docs/api/XCEngine/Rendering/RenderSurface/SetDepthStateBefore.md
new file mode 100644
index 00000000..25974598
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/RenderSurface/SetDepthStateBefore.md
@@ -0,0 +1,28 @@
+# RenderSurface::SetDepthStateBefore
+
+设置深度附件在本次渲染开始前预期所处的统一状态。
+```cpp
+void SetDepthStateBefore(RHI::ResourceStates state);
+```
+
+## 参数
+
+- `state` - 调用方认为当前深度附件进入本次 pass 前所处的资源状态。
+
+## 当前语义
+
+- 这个值只写入 `RenderSurface` 自身，不会立即发出 barrier。
+- 当 [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md) 为 `true` 时，`BuiltinForwardPipeline`、`BuiltinDepthStylePassBase`、`BuiltinObjectIdPass` 等路径会把它作为深度附件进入 `DepthWrite` 前的来源状态。
+- `SceneRenderer` 在为 post-process / final-output 构造派生 `RenderSurface` 时，会继续复制这份深度 before 状态。
+
+## 测试覆盖
+
+- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
+- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
+
+## 相关文档
+
+- [RenderSurface](RenderSurface.md)
+- [GetDepthStateBefore](GetDepthStateBefore.md)
+- [SetDepthStateAfter](SetDepthStateAfter.md)
+- [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md)
diff --git a/docs/api/XCEngine/Rendering/RenderSurface/SetSampleDesc.md b/docs/api/XCEngine/Rendering/RenderSurface/SetSampleDesc.md
new file mode 100644
index 00000000..af0088ca
--- /dev/null
+++ b/docs/api/XCEngine/Rendering/RenderSurface/SetSampleDesc.md
@@ -0,0 +1,30 @@
+# RenderSurface::SetSampleDesc
+
+设置当前 surface 的 sample count 和 sample quality。
+```cpp
+void SetSampleDesc(uint32_t sampleCount, uint32_t sampleQuality = 0);
+```
+
+## 参数
+
+- `sampleCount` - 期望的采样数；传入 `0` 时当前实现会规范化成单采样。
+- `sampleQuality` - 当 `sampleCount > 1` 时保留的 quality 值；单采样时会被重置成 `0`。
+
+## 当前语义
+
+- 实现会把 `sampleCount == 0` 规范化为 `1`。
+- 只有 `sampleCount > 1` 时，`sampleQuality` 才保留调用方传入值；否则内部强制存成 `0`。
+- `RenderSurfacePipelineUtils` 会把这组值写入 `GraphicsPipelineDesc.sampleCount` / `sampleQuality`。
+- `SceneRenderer` 当前要求 fullscreen post-process / final-output 链路的主场景输出为单采样，因此多采样主 surface 会跳过这两段 fullscreen 阶段。
+
+## 测试覆盖
+
+- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp`
+- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
+
+## 相关文档
+
+- [RenderSurface](RenderSurface.md)
+- [GetSampleCount](GetSampleCount.md)
+- [GetSampleQuality](GetSampleQuality.md)
+- [CameraRenderRequest](../Planning/CameraRenderRequest/CameraRenderRequest.md)