docs: expand render surface docs

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

@@ -0,0 +1,24 @@
+# RenderSurface::GetRenderArea
+
+获取当前实际生效的渲染区域。
+
+```cpp
+Math::RectInt GetRenderArea() const;
+```
+
+## 返回值
+
+- 如果没有启用自定义 render area，返回 `(0, 0, width, height)`
+- 如果启用了自定义 render area，返回经过当前 surface 尺寸再次夹取后的矩形
+
+## 行为说明
+
+当前实现即使在 `SetRenderArea(...)` 时已经做过一次夹取，取回时也会再次调用内部 `ClampRenderArea(...)`。这保证了在 `SetSize(...)` 之后，返回值仍然不会越界。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [SetRenderArea](SetRenderArea.md)
+- [HasCustomRenderArea](HasCustomRenderArea.md)
+- [GetRenderAreaWidth](GetRenderAreaWidth.md)
+- [GetRenderAreaHeight](GetRenderAreaHeight.md)

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

@@ -0,0 +1,21 @@
+# RenderSurface::GetRenderAreaHeight
+
+获取当前渲染区域高度。
+
+```cpp
+uint32_t GetRenderAreaHeight() const;
+```
+
+## 返回值
+
+- 当前 `GetRenderArea().height` 的非负版本
+
+## 行为说明
+
+当前实现会先取 `GetRenderArea()`，再对 `height` 做 `max(height, 0)`，最后转成 `uint32_t`。因此它反映的是当前实际生效 render area 的稳定高度。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [GetRenderArea](GetRenderArea.md)
+- [GetRenderAreaWidth](GetRenderAreaWidth.md)

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

@@ -0,0 +1,21 @@
+# RenderSurface::GetRenderAreaWidth
+
+获取当前渲染区域宽度。
+
+```cpp
+uint32_t GetRenderAreaWidth() const;
+```
+
+## 返回值
+
+- 当前 `GetRenderArea().width` 的非负版本
+
+## 行为说明
+
+当前实现会先取 `GetRenderArea()`，再对 `width` 做 `max(width, 0)`，最后转成 `uint32_t`。因此即使内部矩形来源异常，返回值也不会出现负数。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [GetRenderArea](GetRenderArea.md)
+- [GetRenderAreaHeight](GetRenderAreaHeight.md)

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

@@ -0,0 +1,19 @@
+# RenderSurface::HasCustomRenderArea
+
+判断当前是否启用了自定义渲染区域。
+
+```cpp
+bool HasCustomRenderArea() const;
+```
+
+## 返回值
+
+- `true`：当前 `GetRenderArea()` 使用的是显式设置过的 render area
+- `false`：当前 `GetRenderArea()` 会退回到整张 surface
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [SetRenderArea](SetRenderArea.md)
+- [ResetRenderArea](ResetRenderArea.md)
+- [GetRenderArea](GetRenderArea.md)

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

@@ -6,7 +6,7 @@
 
 **头文件**: `XCEngine/Rendering/RenderSurface.h`
 
-**描述**: 描述当前渲染目标表面，包括尺寸、颜色附件、深度附件、清屏色覆盖和颜色附件自动状态切换策略。
+**描述**: 描述当前渲染目标表面，包括尺寸、颜色/深度附件、自定义渲染区域、清屏色覆盖和颜色附件自动状态切换策略。
 
 ## 概述
 
@@ -17,6 +17,7 @@
 - 宽高
 - 一组颜色附件
 - 一个深度附件
+- 可选自定义 render area
 - 可选清屏色覆盖
 - 颜色附件渲染前后状态
 - 是否自动执行颜色附件状态切换
@@ -27,6 +28,7 @@
 
 - 当前只为颜色附件维护统一的 `stateBefore` / `stateAfter`，不是每个附件单独配置。
 - 自动状态切换当前只处理颜色附件，不处理深度附件。
+- 自定义 render area 会在设置时和取回时都被夹到当前 surface 尺寸范围内。
 - 当前不会校验附件数量、附件尺寸与 `RenderSurface` 宽高是否匹配。
 - 当前没有 load/store action、MSAA resolve、mip slice 或 array slice 等更丰富的 surface 配置。
 
@@ -43,6 +45,12 @@
 | [GetColorAttachments](GetColorAttachments.md) | 获取颜色附件数组。 |
 | [SetDepthAttachment](SetDepthAttachment.md) | 设置深度附件。 |
 | [GetDepthAttachment](GetDepthAttachment.md) | 获取深度附件。 |
+| [SetRenderArea](SetRenderArea.md) | 设置自定义渲染区域。 |
+| [ResetRenderArea](ResetRenderArea.md) | 清除自定义渲染区域。 |
+| [HasCustomRenderArea](HasCustomRenderArea.md) | 判断是否启用了自定义渲染区域。 |
+| [GetRenderArea](GetRenderArea.md) | 获取当前实际生效的渲染区域。 |
+| [GetRenderAreaWidth](GetRenderAreaWidth.md) | 获取当前渲染区域宽度。 |
+| [GetRenderAreaHeight](GetRenderAreaHeight.md) | 获取当前渲染区域高度。 |
 | [SetClearColorOverride](SetClearColorOverride.md) | 设置清屏色覆盖。 |
 | [ClearClearColorOverride](ClearClearColorOverride.md) | 清除清屏色覆盖。 |
 | [HasClearColorOverride](HasClearColorOverride.md) | 判断是否启用了清屏色覆盖。 |

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

@@ -0,0 +1,23 @@
+# RenderSurface::ResetRenderArea
+
+清除自定义渲染区域。
+
+```cpp
+void ResetRenderArea();
+```
+
+## 行为说明
+
+当前实现会：
+
+- 把 `m_hasCustomRenderArea` 设回 `false`
+- 把内部缓存的 `m_renderArea` 重置为空矩形
+
+重置后，`GetRenderArea()` 会重新回到“整张 surface”的默认语义。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [SetRenderArea](SetRenderArea.md)
+- [HasCustomRenderArea](HasCustomRenderArea.md)
+- [GetRenderArea](GetRenderArea.md)

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

@@ -0,0 +1,28 @@
+# RenderSurface::SetRenderArea
+
+设置自定义渲染区域。
+
+```cpp
+void SetRenderArea(const Math::RectInt& renderArea);
+```
+
+## 参数
+
+- `renderArea` - 期望使用的渲染矩形。
+
+## 行为说明
+
+当前实现不会原样保存传入矩形，而是先根据 surface 的 `width / height` 做一次边界夹取：
+
+- `x / y` 会被夹到 `[0, width/height]`
+- 负的 `width / height` 会按 `0` 处理
+- 右边界和下边界也不会超过当前 surface 尺寸
+
+设置完成后，`HasCustomRenderArea()` 会变为 `true`。
+
+## 相关文档
+
+- [返回类型总览](RenderSurface.md)
+- [ResetRenderArea](ResetRenderArea.md)
+- [HasCustomRenderArea](HasCustomRenderArea.md)
+- [GetRenderArea](GetRenderArea.md)

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

@@ -13,10 +13,14 @@ void SetSize(uint32_t width, uint32_t height);
 
 ## 行为说明
 
-当前实现只会更新内部记录的宽高，不会同步修改附件对象本身。
+当前实现会更新内部记录的宽高，但不会同步修改附件对象本身。
+
+如果当前已经启用了自定义 render area，`SetSize(...)` 还会把现有 `m_renderArea` 重新夹到新的 surface 尺寸范围内，避免保留越界区域。
 
 ## 相关文档
 
 - [返回类型总览](RenderSurface.md)
 - [GetWidth](GetWidth.md)
 - [GetHeight](GetHeight.md)
+- [SetRenderArea](SetRenderArea.md)
+- [GetRenderArea](GetRenderArea.md)