docs(api): deepen OpenGL pipeline state docs

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Apply.md

@@ -1,30 +1,27 @@
-# OpenGLPipelineState::Apply
-
-公开方法，详见头文件声明。
+# OpenGLPipelineState::Apply()
 
 ```cpp
 void Apply();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把当前缓存的 OpenGL 状态批量应用到上下文。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 顺序调用 [ApplyDepthStencil](ApplyDepthStencil.md)
+- 再调用 [ApplyBlend](ApplyBlend.md)
+- 最后调用 [ApplyRasterizer](ApplyRasterizer.md)
+- 不会调用 [ApplyViewport](ApplyViewport.md)
+- 不会调用 [ApplyScissor](ApplyScissor.md)
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::Apply(...)。
-    (void)object;
-}
-```
+当前 `Apply()` 只覆盖“最接近 PSO 固定功能状态”的部分。viewport / scissor 仍更常由命令列表直接下发，所以没有被纳入默认应用链。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [ApplyViewport](ApplyViewport.md)
+- [ApplyScissor](ApplyScissor.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/ApplyBlend.md

@@ -1,30 +1,28 @@
-# OpenGLPipelineState::ApplyBlend
-
-公开方法，详见头文件声明。
+# OpenGLPipelineState::ApplyBlend()
 
 ```cpp
 void ApplyBlend();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把当前缓存的混合状态写入 OpenGL。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 若 `m_glBlendState.blendEnable` 为真：
+  - `glEnable(GL_BLEND)`
+  - `glBlendFuncSeparate(...)`
+  - `glBlendEquationSeparate(...)`
+  - `glColorMask(...)`
+- 否则只执行 `glDisable(GL_BLEND)`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 需要特别注意
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::ApplyBlend(...)。
-    (void)object;
-}
-```
+- 当前实现不会调用 `glBlendColor`，所以 `blendFactor[4]` 只是被缓存，没有真正生效
+- 当混合关闭时，也不会显式恢复 `glColorMask`
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetBlendState](SetBlendState.md)
+- [Apply](Apply.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/ApplyDepthStencil.md

@@ -1,30 +1,32 @@
-# OpenGLPipelineState::ApplyDepthStencil
-
-公开方法，详见头文件声明。
+# OpenGLPipelineState::ApplyDepthStencil()
 
 ```cpp
 void ApplyDepthStencil();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把当前缓存的深度/模板状态写入 OpenGL。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 根据 `depthTestEnable` 开关 `GL_DEPTH_TEST`
+- 根据 `depthWriteEnable` 设置 `glDepthMask`
+- 使用 `depthFunc` 调用 `glDepthFunc`
+- 若 `stencilEnable` 为真：
+  - `glEnable(GL_STENCIL_TEST)`
+  - `glStencilMask(stencilWriteMask)`
+  - `glStencilFunc(stencilFunc, stencilRef, stencilReadMask)`
+  - `glStencilOp(stencilFailOp, stencilDepthFailOp, stencilDepthPassOp)`
+- 否则关闭 `GL_STENCIL_TEST`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 需要特别注意
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::ApplyDepthStencil(...)。
-    (void)object;
-}
-```
+- 当前只应用一套模板函数/操作，没有区分 front/back face
+- `stencilRef` 只有 OpenGL 专用状态路径会直接控制；RHI 描述版本不会给它赋新值
+- `depthBoundsEnable` 在这里没有实现
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetDepthStencilState](SetDepthStencilState.md)
+- [Apply](Apply.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/ApplyRasterizer.md

@@ -1,30 +1,28 @@
-# OpenGLPipelineState::ApplyRasterizer
-
-公开方法，详见头文件声明。
+# OpenGLPipelineState::ApplyRasterizer()
 
 ```cpp
 void ApplyRasterizer();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把当前缓存的光栅化相关状态写入 OpenGL。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 根据 `cullFaceEnable` 开关 `GL_CULL_FACE`
+- 若启用剔除，设置 `glCullFace(...)` 与 `glFrontFace(...)`
+- 通过 `glPolygonMode(GL_FRONT_AND_BACK, ...)` 设置填充模式
+- 根据 `multisampleEnable` 开关 `GL_MULTISAMPLE`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 需要特别注意
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::ApplyRasterizer(...)。
-    (void)object;
-}
-```
+- 当前不会处理 polygon offset
+- 不会应用 `depthClipEnable`
+- 不会应用 `sampleAlphaToCoverageEnable`
+- `scissorTestEnable` 虽然会被缓存，但不在这里生效
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetRasterizerState](SetRasterizerState.md)
+- [ApplyScissor](ApplyScissor.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/ApplyScissor.md

@@ -1,30 +1,25 @@
-# OpenGLPipelineState::ApplyScissor
-
-公开方法，详见头文件声明。
+# OpenGLPipelineState::ApplyScissor()
 
 ```cpp
 void ApplyScissor();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把缓存的裁剪矩形写入 OpenGL。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 若 `m_scissorState.enable` 为真：
+  - `glEnable(GL_SCISSOR_TEST)`
+  - `glScissor(x, y, width, height)`
+- 否则关闭 `GL_SCISSOR_TEST`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::ApplyScissor(...)。
-    (void)object;
-}
-```
+scissor 在当前后端里与“光栅化状态对象”是松耦合的。`Bind()` 默认不会调用这个方法，因此它更像一项可选的附加状态。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetScissor](SetScissor.md)
+- [Bind](Bind.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/ApplyViewport.md

@@ -1,30 +1,24 @@
-# OpenGLPipelineState::ApplyViewport
-
-公开方法，详见头文件声明。
+# OpenGLPipelineState::ApplyViewport()
 
 ```cpp
 void ApplyViewport();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+把缓存的 viewport 状态写入 OpenGL。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 调用 `glViewport(x, y, width, height)`
+- 调用 `glDepthRange(minDepth, maxDepth)`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::ApplyViewport(...)。
-    (void)object;
-}
-```
+- [Bind](Bind.md) 默认不会调用这个方法
+- 因此仅调用 `SetViewport()` 只会更新缓存，不会立即影响上下文
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetViewport](SetViewport.md)
+- [Bind](Bind.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/AttachShader.md

@@ -1,31 +1,25 @@
-# OpenGLPipelineState::AttachShader
-
-公开方法，详见头文件声明。
+# OpenGLPipelineState::AttachShader()
 
 ```cpp
 void AttachShader(unsigned int program);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `program` - 参数语义详见头文件声明。
+把一个外部 graphics program 直接附着到当前管线状态对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 把 `m_program` 设为传入的 `program`
+- 把 `m_programAttached` 设为 `true`
+- 立即执行 `glUseProgram(program)`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::AttachShader(...)。
-    (void)object;
-}
-```
+这是一个明显的 OpenGL 后端快捷入口，适合测试、样例或手工 program 管理路径。相比之下，正式的设备创建流程更推荐走 [SetOwnedGraphicsShader](SetOwnedGraphicsShader.md)。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetProgram](SetProgram.md)
+- [DetachShader](DetachShader.md)
+- [Bind](Bind.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Bind.md

@@ -1,4 +1,4 @@
-# OpenGLPipelineState::Bind
+# OpenGLPipelineState::Bind()
 
 ```cpp
 void Bind() override;
@@ -6,22 +6,22 @@ void Bind() override;
 
 ## 作用
 
-把当前 `OpenGLPipelineState` 缓存的 program 和渲染状态应用到活动 OpenGL 上下文。
+把当前管线状态对象的 program 与固定功能状态应用到上下文。
 
 ## 当前实现行为
 
-- 若存在 compute program，优先 `glUseProgram(m_computeProgram)`
-- 否则若绑定了 graphics program，则 `glUseProgram(m_program)`
-- 之后调用 `Apply()`：
-  - `ApplyDepthStencil()`
-  - `ApplyBlend()`
-  - `ApplyRasterizer()`
+- 若 [HasComputeShader](HasComputeShader.md) 为真，优先 `glUseProgram(m_computeProgram)`
+- 否则若 `m_programAttached` 且 `m_program != 0`，则 `glUseProgram(m_program)`
+- 然后调用 [Apply](Apply.md)
 
-## 注意事项
+## 需要特别注意
 
-当前 `Bind()` 不会自动调用 `ApplyViewport()` 和 `ApplyScissor()`。
+- Compute program 的优先级高于 graphics program
+- 默认不会调用 [ApplyViewport](ApplyViewport.md) 和 [ApplyScissor](ApplyScissor.md)
+- 它不会验证 program 与当前输入布局、render target、sample count 是否匹配
 
 ## 相关文档
 
+- [Unbind](Unbind.md)
+- [Apply](Apply.md)
 - [SetComputeShader](SetComputeShader.md)
-- [OpenGLCommandList::SetPipelineState](../OpenGLCommandList/SetPipelineState.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Clear.md

@@ -1,31 +1,21 @@
-# OpenGLPipelineState::Clear
-
-清空内部数据。
+# OpenGLPipelineState::Clear()
 
 ```cpp
 void Clear(unsigned int buffers);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `buffers` - 参数语义详见头文件声明。
+按给定缓冲位掩码执行 `glClear`。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::Clear(...)。
-    (void)object;
-}
-```
+- 把 `buffers` 通过 `ToOpenGLClearBuffer(buffers)` 转成 OpenGL 清除标志
+- 直接调用 `glClear(...)`
+- 不绑定 FBO
+- 不检查 clear color / depth / stencil 是否已经预先设置
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetClearColor](SetClearColor.md)
+- [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Constructor.md

@@ -1,28 +1,20 @@
 # OpenGLPipelineState::OpenGLPipelineState()
 
-构造对象。
-
 ```cpp
 OpenGLPipelineState();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 OpenGL 管线状态容器。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-}
-```
+- 把 `m_program` 置为 `0`
+- 把 `m_programAttached` 置为 `false`
+- 其余成员依赖类内默认初始化，例如 `m_computeProgram = 0`
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [SetOwnedGraphicsShader](SetOwnedGraphicsShader.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Destructor.md

@@ -1,29 +1,24 @@
 # OpenGLPipelineState::~OpenGLPipelineState()
 
-销毁对象并释放相关资源。
-
 ```cpp
 ~OpenGLPipelineState() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+析构当前管线状态对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 析构函数本身是空实现
+- 如果对象拥有 `m_graphicsShader`，其 `unique_ptr` 会在成员析构阶段自动释放
+- 不会主动调用 [Shutdown](Shutdown.md)
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+这说明当前类的“显式清理”语义主要由 `Shutdown()` 承担，而不是由析构函数强制兜底。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [Shutdown](Shutdown.md)
+- [SetOwnedGraphicsShader](SetOwnedGraphicsShader.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/DetachShader.md

@@ -1,30 +1,21 @@
-# OpenGLPipelineState::DetachShader
-
-公开方法，详见头文件声明。
+# OpenGLPipelineState::DetachShader()
 
 ```cpp
 void DetachShader();
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+断开当前 graphics program 绑定。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::DetachShader(...)。
-    (void)object;
-}
-```
+- 把 `m_program` 置为 `0`
+- 把 `m_programAttached` 置为 `false`
+- 立即执行 `glUseProgram(0)`
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [AttachShader](AttachShader.md)
+- [SetOwnedGraphicsShader](SetOwnedGraphicsShader.md)
+- [Bind](Bind.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/EnsureValid.md

@@ -1,30 +1,22 @@
-# OpenGLPipelineState::EnsureValid
-
-公开方法，详见头文件声明。
+# OpenGLPipelineState::EnsureValid()
 
 ```cpp
 void EnsureValid() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+为统一 RHI 接口保留的验证入口。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 空实现
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::EnsureValid(...)。
-    (void)object;
-}
-```
+当前 OpenGL 后端没有像 D3D12/Vulkan 那样构建严格的 PSO 校验阶段，所以这里没有执行任何额外逻辑。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [IsValid](IsValid.md)
+- [OpenGLPipelineState](OpenGLPipelineState.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetComputeShader.md

@@ -1,30 +1,19 @@
-# OpenGLPipelineState::GetComputeShader
-
-获取相关状态或对象。
+# OpenGLPipelineState::GetComputeShader()
 
 ```cpp
 RHIShader* GetComputeShader() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前缓存的 compute shader 指针。
 
-**返回：** `RHIShader*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::GetComputeShader(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_computeShader`
+- 当前对象不拥有这块资源
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetComputeShader](SetComputeShader.md)
+- [HasComputeShader](HasComputeShader.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetHash.md

@@ -1,30 +1,24 @@
-# OpenGLPipelineState::GetHash
-
-获取相关状态或对象。
+# OpenGLPipelineState::GetHash()
 
 ```cpp
 PipelineStateHash GetHash() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回管线状态哈希。
 
-**返回：** `PipelineStateHash` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 创建一个默认初始化的 `PipelineStateHash`
+- 直接返回该零值结构
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::GetHash(...)。
-    (void)object;
-}
-```
+当前实现没有真正把 blend / depth / rasterizer / input layout 等状态编码进哈希，所以它更像占位接口，而不是可用于缓存键的稳定结果。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetRenderTargetFormats](SetRenderTargetFormats.md)
+- [SetSampleCount](SetSampleCount.md)
+- [OpenGLPipelineState](OpenGLPipelineState.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetNativeHandle.md

@@ -1,30 +1,23 @@
-# OpenGLPipelineState::GetNativeHandle
-
-获取相关状态或对象。
+# OpenGLPipelineState::GetNativeHandle()
 
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+以统一句柄形式返回当前 graphics program。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 把 `m_program` 转成 `uintptr_t`
+- 再转成 `void*` 返回
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 需要特别注意
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::GetNativeHandle(...)。
-    (void)object;
-}
-```
+如果当前对象只配置了 compute program，`GetNativeHandle()` 仍然只看 `m_program`，因此返回值可能是空，而不是 `m_computeProgram`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [GetProgram](GetProgram.md)
+- [SetComputeShader](SetComputeShader.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetOpenGLBlendState.md

@@ -1,30 +1,18 @@
-# OpenGLPipelineState::GetOpenGLBlendState
-
-获取相关状态或对象。
+# OpenGLPipelineState::GetOpenGLBlendState()
 
 ```cpp
 const OpenGLBlendState& GetOpenGLBlendState() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前缓存的 OpenGL 专用混合状态结构。
 
-**返回：** `const OpenGLBlendState&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::GetOpenGLBlendState(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_glBlendState` 的常量引用
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetBlendState](SetBlendState.md)
+- [ApplyBlend](ApplyBlend.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetOpenGLDepthStencilState.md

@@ -1,30 +1,18 @@
-# OpenGLPipelineState::GetOpenGLDepthStencilState
-
-获取相关状态或对象。
+# OpenGLPipelineState::GetOpenGLDepthStencilState()
 
 ```cpp
 const OpenGLDepthStencilState& GetOpenGLDepthStencilState() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前缓存的 OpenGL 专用深度/模板状态结构。
 
-**返回：** `const OpenGLDepthStencilState&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::GetOpenGLDepthStencilState(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_glDepthStencilState` 的常量引用
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetDepthStencilState](SetDepthStencilState.md)
+- [ApplyDepthStencil](ApplyDepthStencil.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetOpenGLRasterizerState.md

@@ -1,30 +1,18 @@
-# OpenGLPipelineState::GetOpenGLRasterizerState
-
-获取相关状态或对象。
+# OpenGLPipelineState::GetOpenGLRasterizerState()
 
 ```cpp
 const OpenGLRasterizerState& GetOpenGLRasterizerState() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前缓存的 OpenGL 专用光栅化状态结构。
 
-**返回：** `const OpenGLRasterizerState&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::GetOpenGLRasterizerState(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_glRasterizerState` 的常量引用
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetRasterizerState](SetRasterizerState.md)
+- [ApplyRasterizer](ApplyRasterizer.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetProgram.md

@@ -1,30 +1,22 @@
-# OpenGLPipelineState::GetProgram
-
-获取相关状态或对象。
+# OpenGLPipelineState::GetProgram()
 
 ```cpp
 unsigned int GetProgram() const;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 graphics program ID。
 
-**返回：** `unsigned int` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_program`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::GetProgram(...)。
-    (void)object;
-}
-```
+这个方法不返回 `m_computeProgram`。如果当前对象主要承载 compute pipeline，请结合 [HasComputeShader](HasComputeShader.md) 与 [GetComputeShader](GetComputeShader.md) 理解其语义。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetProgram](SetProgram.md)
+- [GetNativeHandle](GetNativeHandle.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetType.md

@@ -1,30 +1,23 @@
-# OpenGLPipelineState::GetType
-
-获取相关状态或对象。
+# OpenGLPipelineState::GetType()
 
 ```cpp
 PipelineType GetType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象被视为 graphics 还是 compute pipeline。
 
-**返回：** `PipelineType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 若 [HasComputeShader](HasComputeShader.md) 为真，返回 `PipelineType::Compute`
+- 否则返回 `PipelineType::Graphics`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::GetType(...)。
-    (void)object;
-}
-```
+它只取决于 `m_computeProgram != 0`，不验证 graphics program 是否也同时存在。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [HasComputeShader](HasComputeShader.md)
+- [SetComputeShader](SetComputeShader.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/HasComputeShader.md

@@ -1,30 +1,18 @@
-# OpenGLPipelineState::HasComputeShader
-
-判断是否具备指定状态或能力。
+# OpenGLPipelineState::HasComputeShader()
 
 ```cpp
 bool HasComputeShader() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+判断当前对象是否记录了一个非零的 compute program。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::HasComputeShader(...)。
-    (void)object;
-}
-```
+- 直接检查 `m_computeProgram != 0`
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetComputeShader](SetComputeShader.md)
+- [GetType](GetType.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/IsValid.md

@@ -1,30 +1,22 @@
-# OpenGLPipelineState::IsValid
-
-查询当前状态。
+# OpenGLPipelineState::IsValid()
 
 ```cpp
 bool IsValid() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前管线状态对象是否“有效”。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 永远返回 `true`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::IsValid(...)。
-    (void)object;
-}
-```
+这再次强调了当前类不是预编译 PSO，而是一个运行时状态容器。它没有做严格的创建期校验，因此“有效性”只是一种接口占位。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [EnsureValid](EnsureValid.md)
+- [OpenGLPipelineState](OpenGLPipelineState.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/OpenGLPipelineState.md

@@ -6,46 +6,69 @@
 
 **头文件**: `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`
 
-**描述**: OpenGL 后端的 CPU 侧管线状态容器；它不是原生 GPU pipeline object，而是在 `Bind()` 时把缓存状态应用到当前上下文。
+**描述**: OpenGL 后端的 CPU 侧管线状态容器；它统一了跨后端 PSO 概念，但真实行为仍然是“在绑定时把缓存状态写回 OpenGL 上下文”。
 
 ## 概览
 
-在 D3D12/Vulkan 里，pipeline state 更接近“预烘焙对象”。而在当前 OpenGL 后端里，`OpenGLPipelineState` 更像一个状态包，里面存的是：
+`OpenGLPipelineState` 和 D3D12/Vulkan 的原生 PSO 有本质区别。显式 API 的 PSO 更像“预编译、不可变的 GPU 对象”；当前 OpenGL 实现则是一个运行时状态包，里面保存的是：
 
-- 光栅化状态
+- graphics program 或 compute program 句柄
+- 输入布局描述
+- 深度/模板状态
 - 混合状态
-- 深度模板状态
-- 输入布局
-- 绑定的 graphics program 或 compute program
+- 光栅化状态
+- viewport / scissor / clear color 等附加缓存
+
+真正的 OpenGL 调用发生在 [Bind](Bind.md) 和各个 `Apply*` 方法里，而不是在对象创建时一次性固化。
 
 ## 当前实现的真实行为
 
-- `Bind()`：
-  - 若存在 compute shader，调用 `glUseProgram(m_computeProgram)`
-  - 否则若绑定了 graphics program，则调用 `glUseProgram(m_program)`
-  - 然后执行 `Apply()`，应用深度模板、混合、光栅化状态
-- `Unbind()` 会 `glUseProgram(0)`
-- `IsValid()` 永远返回 `true`
-- `EnsureValid()` 当前为空实现
-- `SetComputeShader()` 只是缓存 shader 指针并记录 program id
-- `SetRenderTargetFormats()`、`SetSampleCount()`、`GetHash()` 当前基本是占位或空实现
+- [Bind](Bind.md) 会优先绑定 compute program，否则绑定 graphics program
+- `Bind()` 之后只会调用 [Apply](Apply.md)，即深度/模板、混合、光栅化三类状态
+- [ApplyViewport](ApplyViewport.md) 与 [ApplyScissor](ApplyScissor.md) 需要单独调用
+- [SetRenderTargetFormats](SetRenderTargetFormats.md)、[SetSampleCount](SetSampleCount.md)、[GetHash](GetHash.md) 目前基本是占位实现
+- [IsValid](IsValid.md) 永远返回 `true`
+- [EnsureValid](EnsureValid.md) 为空实现
+- [GetNativeHandle](GetNativeHandle.md) 只返回 graphics `m_program`
+
+## 设计背景
+
+商业引擎在做 OpenGL 后端时，通常不会试图伪造一套完全等价于 D3D12/Vulkan 的原生 PSO，而是会保留一个“高层 PSO 接口 + 低层状态写回器”的折中结构。当前实现就属于这一类设计：
+
+- 高层渲染代码仍可依赖统一的 `RHIPipelineState`
+- OpenGL 后端把真实成本集中到绑定阶段
+- 这样既保留了跨后端 API 一致性，也避免在 OpenGL 上硬造不存在的驱动对象
+
+这和 Unity、Unreal 等商业引擎在老式状态机 API 上常用的策略是一致的：抽象层保持现代接口形状，后端实现接受状态机现实。
+
+## 生命周期
+
+- [OpenGLPipelineState()](Constructor.md) 初始化为空容器
+- 上层通过 [SetInputLayout](SetInputLayout.md)、[SetBlendState](SetBlendState.md)、[SetDepthStencilState](SetDepthStencilState.md)、[SetRasterizerState](SetRasterizerState.md) 等接口缓存状态
+- 设备创建 graphics pipeline 时，会通过 [SetOwnedGraphicsShader](SetOwnedGraphicsShader.md) 把编译好的 `OpenGLShader` 交给它管理
+- 命令提交阶段由 [Bind](Bind.md) 把状态真正写入 OpenGL
+- [Shutdown](Shutdown.md) 释放自有 graphics shader，并重置程序句柄与标记位
 
 ## 重要限制
 
-- 这不是 OpenGL 原生对象，不要把它理解成可脱离上下文独立执行的 pipeline
-- `Bind()` 当前不会自动调用 `ApplyViewport()` 和 `ApplyScissor()`
-- 因此 viewport / scissor 更常由命令列表直接设置
+- 不是原生 OpenGL pipeline object
+- 不是不可变对象，状态可以随时被覆盖
+- 不自动应用 viewport / scissor
+- 部分 RHI 描述字段只被缓存，没有进入真实 OpenGL 调用
+- 没有稳定的 hash 和严格的创建期验证
 
-## 设计说明
-
-这种做法的好处是容易把跨后端 PSO 概念统一起来；代价是它无法像显式 API 那样把“状态已经完全固化”这件事表达得很强。
-
-## 重点公共方法
+## 关键方法
 
 - [Bind](Bind.md)
+- [Apply](Apply.md)
 - [SetComputeShader](SetComputeShader.md)
+- [SetOwnedGraphicsShader](SetOwnedGraphicsShader.md)
+- [SetBlendState](SetBlendState.md)
+- [SetDepthStencilState](SetDepthStencilState.md)
+- [SetRasterizerState](SetRasterizerState.md)
 
 ## 相关文档
 
-- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
 - [OpenGLShader](../OpenGLShader/OpenGLShader.md)
+- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
+- [OpenGLDevice](../OpenGLDevice/OpenGLDevice.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetBlendState.md

@@ -1,44 +1,41 @@
-# OpenGLPipelineState::SetBlendState
+# OpenGLPipelineState::SetBlendState()
 
-设置相关状态或配置。
+```cpp
+void SetBlendState(const BlendDesc& state) override;
+void SetBlendState(const OpenGLBlendState& state);
+```
 
-该方法在 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
+## 作用
 
-## 重载 1: 声明
+缓存混合状态。
+
+## 重载 1: RHI 描述
 
 ```cpp
 void SetBlendState(const BlendDesc& state) override;
 ```
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+### 当前实现行为
 
-**返回：** `void` - 无返回值。
+- 把 `state` 整体缓存到 `m_blendDesc`
+- 同步写入 `m_glBlendState`
+- 复制 `blendFactor[4]`
 
-## 重载 2: 声明
+## 重载 2: OpenGL 专用状态
 
 ```cpp
 void SetBlendState(const OpenGLBlendState& state);
 ```
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+### 当前实现行为
 
-**返回：** `void` - 无返回值。
+- 直接覆盖 `m_glBlendState`
 
-**示例：**
+## 需要特别注意
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetBlendState(...)。
-    (void)object;
-}
-```
+虽然 blend factor 会被缓存，但 [ApplyBlend](ApplyBlend.md) 当前不会调用 `glBlendColor`。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [ApplyBlend](ApplyBlend.md)
+- [GetOpenGLBlendState](GetOpenGLBlendState.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetClearColor.md

@@ -1,34 +1,23 @@
-# OpenGLPipelineState::SetClearColor
-
-设置相关状态或配置。
+# OpenGLPipelineState::SetClearColor()
 
 ```cpp
 void SetClearColor(float r, float g, float b, float a);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `r` - 参数语义详见头文件声明。
-- `g` - 参数语义详见头文件声明。
-- `b` - 参数语义详见头文件声明。
-- `a` - 参数语义详见头文件声明。
+缓存并立即设置 OpenGL clear color。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 把四个分量写入 `m_clearColor`
+- 立即调用 `glClearColor(r, g, b, a)`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetClearColor(...)。
-    (void)object;
-}
-```
+这不是纯缓存接口，而是“缓存 + 立刻写状态”的混合接口。它很符合当前后端务实的状态机风格，但也意味着调用它会立即影响当前上下文。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [Clear](Clear.md)
+- [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetComputeShader.md

@@ -1,4 +1,4 @@
-# OpenGLPipelineState::SetComputeShader
+# OpenGLPipelineState::SetComputeShader()
 
 ```cpp
 void SetComputeShader(RHIShader* shader) override;
@@ -6,19 +6,23 @@ void SetComputeShader(RHIShader* shader) override;
 
 ## 作用
 
-把一个 compute shader 绑定为当前 PSO 的 compute program 来源。
+把一个 shader 作为当前 compute pipeline 的程序来源。
 
 ## 当前实现行为
 
-- 缓存 `m_computeShader`
-- 若 `shader != nullptr`，则把 `m_computeProgram` 设为该 `OpenGLShader` 的 program id
-- 若 `shader == nullptr`，则清空 `m_computeProgram`
+- 把 `shader` 缓存到 `m_computeShader`
+- 若 `shader != nullptr`：
+  - 直接 `static_cast<OpenGLShader*>(shader)`
+  - 把其 `GetID()` 结果写入 `m_computeProgram`
+- 若 `shader == nullptr`，则把 `m_computeProgram` 置为 `0`
 
-## 设计说明
+## 需要特别注意
 
-这里并不会重新编译或链接 shader；它只是引用已有 `OpenGLShader`。
+- 没有运行时类型检查
+- 也不验证这个 `OpenGLShader` 是否真的是 compute program
 
 ## 相关文档
 
+- [HasComputeShader](HasComputeShader.md)
+- [GetComputeShader](GetComputeShader.md)
 - [Bind](Bind.md)
-- [OpenGLShader](../OpenGLShader/OpenGLShader.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetDepthStencilState.md

@@ -1,44 +1,49 @@
-# OpenGLPipelineState::SetDepthStencilState
+# OpenGLPipelineState::SetDepthStencilState()
 
-设置相关状态或配置。
+```cpp
+void SetDepthStencilState(const DepthStencilStateDesc& state) override;
+void SetDepthStencilState(const OpenGLDepthStencilState& state);
+```
 
-该方法在 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
+## 作用
 
-## 重载 1: 声明
+缓存深度/模板状态。
+
+## 重载 1: RHI 描述
 
 ```cpp
 void SetDepthStencilState(const DepthStencilStateDesc& state) override;
 ```
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+### 当前实现行为
 
-**返回：** `void` - 无返回值。
+- 把 `state` 缓存到 `m_depthStencilDesc`
+- 同步写入 `m_glDepthStencilState`
+- 会映射：
+  - `depthTestEnable`
+  - `depthWriteEnable`
+  - `depthFunc`
+  - `stencilEnable`
+  - `stencilReadMask`
+  - `stencilWriteMask`
+  - `front.func/failOp/depthFailOp/passOp`
 
-## 重载 2: 声明
+### 注意事项
+
+- back face 模板配置当前不会进入 `m_glDepthStencilState`
+- `stencilRef` 也不会从这条路径写入
+
+## 重载 2: OpenGL 专用状态
 
 ```cpp
 void SetDepthStencilState(const OpenGLDepthStencilState& state);
 ```
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+### 当前实现行为
 
-**返回：** `void` - 无返回值。
-
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetDepthStencilState(...)。
-    (void)object;
-}
-```
+- 直接覆盖 `m_glDepthStencilState`
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [ApplyDepthStencil](ApplyDepthStencil.md)
+- [GetOpenGLDepthStencilState](GetOpenGLDepthStencilState.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetInputLayout.md

@@ -1,31 +1,23 @@
-# OpenGLPipelineState::SetInputLayout
-
-设置相关状态或配置。
+# OpenGLPipelineState::SetInputLayout()
 
 ```cpp
 void SetInputLayout(const InputLayoutDesc& layout) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `layout` - 参数语义详见头文件声明。
+缓存输入布局描述。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 直接把 `layout` 复制到 `m_inputLayoutDesc`
+- 不会立刻调用任何 OpenGL 顶点属性接口
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetInputLayout(...)。
-    (void)object;
-}
-```
+在当前后端里，真正的顶点属性绑定更多由 `OpenGLVertexArray` / 命令列表路径处理，所以这里保留的是“统一 PSO 视角下的布局描述”，而不是立即生效的 VAO 配置。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetTopology](SetTopology.md)
+- [OpenGLVertexArray](../OpenGLVertexArray/OpenGLVertexArray.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetOwnedGraphicsShader.md

@@ -1,31 +1,25 @@
-# OpenGLPipelineState::SetOwnedGraphicsShader
-
-设置相关状态或配置。
+# OpenGLPipelineState::SetOwnedGraphicsShader()
 
 ```cpp
-void SetOwnedGraphicsShader(std::unique_ptr<class OpenGLShader> shader);
+void SetOwnedGraphicsShader(std::unique_ptr<OpenGLShader> shader);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `shader` - 参数语义详见头文件声明。
+把一个 graphics shader program 的所有权交给当前对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 把 `shader` 移入 `m_graphicsShader`
+- 若非空，调用 [SetProgram](SetProgram.md) 使用其 program ID
+- 若为空，调用 [DetachShader](DetachShader.md)
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetOwnedGraphicsShader(...)。
-    (void)object;
-}
-```
+`OpenGLDevice::CreatePipelineState(...)` 走的就是这条路径。也就是说，设备创建 graphics pipeline 时，真正被拥有和释放的是 `OpenGLShader`，而不是单独的 raw program ID。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetProgram](SetProgram.md)
+- [Shutdown](Shutdown.md)
+- [OpenGLShader](../OpenGLShader/OpenGLShader.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetProgram.md

@@ -1,31 +1,20 @@
-# OpenGLPipelineState::SetProgram
-
-设置相关状态或配置。
+# OpenGLPipelineState::SetProgram()
 
 ```cpp
 void SetProgram(unsigned int program);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `program` - 参数语义详见头文件声明。
+记录当前 graphics program。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetProgram(...)。
-    (void)object;
-}
-```
+- 把 `m_program` 设为 `program`
+- 把 `m_programAttached` 设为 `(program != 0)`
+- 不会调用 `glUseProgram`
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [AttachShader](AttachShader.md)
+- [GetProgram](GetProgram.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetRasterizerState.md

@@ -1,44 +1,50 @@
-# OpenGLPipelineState::SetRasterizerState
+# OpenGLPipelineState::SetRasterizerState()
 
-设置相关状态或配置。
+```cpp
+void SetRasterizerState(const RasterizerDesc& state) override;
+void SetRasterizerState(const OpenGLRasterizerState& state);
+```
 
-该方法在 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
+## 作用
 
-## 重载 1: 声明
+缓存光栅化状态。
+
+## 重载 1: RHI 描述
 
 ```cpp
 void SetRasterizerState(const RasterizerDesc& state) override;
 ```
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+### 当前实现行为
 
-**返回：** `void` - 无返回值。
+- 把 `state` 缓存到 `m_rasterizerDesc`
+- 同步写入 `m_glRasterizerState`
+- 会映射：
+  - `cullMode`
+  - `frontFace`
+  - `fillMode`
+  - `depthClipEnable`
+  - `scissorTestEnable`
+  - `multisampleEnable`
+  - `slopeScaledDepthBias -> polygonOffsetFactor`
+  - `depthBiasClamp -> polygonOffsetUnits`
 
-## 重载 2: 声明
+### 注意事项
+
+- `depthBias` 当前没有进入 OpenGL 专用状态
+- `antialiasedLineEnable` 也没有被消费
+
+## 重载 2: OpenGL 专用状态
 
 ```cpp
 void SetRasterizerState(const OpenGLRasterizerState& state);
 ```
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+### 当前实现行为
 
-**返回：** `void` - 无返回值。
-
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetRasterizerState(...)。
-    (void)object;
-}
-```
+- 直接覆盖 `m_glRasterizerState`
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [ApplyRasterizer](ApplyRasterizer.md)
+- [GetOpenGLRasterizerState](GetOpenGLRasterizerState.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetRenderTargetFormats.md

@@ -1,33 +1,25 @@
-# OpenGLPipelineState::SetRenderTargetFormats
-
-设置相关状态或配置。
+# OpenGLPipelineState::SetRenderTargetFormats()
 
 ```cpp
-void SetRenderTargetFormats(uint32_t count, const uint32_t* formats, uint32_t depthFormat) override;
+void SetRenderTargetFormats(uint32_t count,
+                            const uint32_t* formats,
+                            uint32_t depthFormat) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `count` - 参数语义详见头文件声明。
-- `formats` - 参数语义详见头文件声明。
-- `depthFormat` - 参数语义详见头文件声明。
+为统一 RHI 接口预留 render target / depth format 描述入口。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 空实现
+- `count`、`formats`、`depthFormat` 当前都不会被记录
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetRenderTargetFormats(...)。
-    (void)object;
-}
-```
+这意味着当前 OpenGL pipeline state 不会基于目标格式做任何兼容性判断或 program 变体区分。
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetSampleCount](SetSampleCount.md)
+- [GetHash](GetHash.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetSampleCount.md

@@ -1,31 +1,19 @@
-# OpenGLPipelineState::SetSampleCount
-
-设置相关状态或配置。
+# OpenGLPipelineState::SetSampleCount()
 
 ```cpp
 void SetSampleCount(uint32_t count) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `count` - 参数语义详见头文件声明。
+为统一 RHI 接口预留采样数设置入口。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetSampleCount(...)。
-    (void)object;
-}
-```
+- 空实现
+- `count` 当前不会被缓存，也不会驱动 `GL_MULTISAMPLE` 之外的任何行为
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetRenderTargetFormats](SetRenderTargetFormats.md)
+- [ApplyRasterizer](ApplyRasterizer.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetScissor.md

@@ -1,31 +1,19 @@
-# OpenGLPipelineState::SetScissor
-
-设置相关状态或配置。
+# OpenGLPipelineState::SetScissor()
 
 ```cpp
 void SetScissor(const ScissorState& state);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+缓存 scissor 状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetScissor(...)。
-    (void)object;
-}
-```
+- 直接把 `state` 复制到 `m_scissorState`
+- 不立即调用 OpenGL
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [ApplyScissor](ApplyScissor.md)
+- [Bind](Bind.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetTopology.md

@@ -1,31 +1,19 @@
-# OpenGLPipelineState::SetTopology
-
-设置相关状态或配置。
+# OpenGLPipelineState::SetTopology()
 
 ```cpp
 void SetTopology(uint32_t topologyType) override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `topologyType` - 参数语义详见头文件声明。
+缓存图元拓扑类型。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetTopology(...)。
-    (void)object;
-}
-```
+- 直接把 `topologyType` 写入 `m_topologyType`
+- 不会立即调用 OpenGL 绘制模式相关接口
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetInputLayout](SetInputLayout.md)
+- [GetHash](GetHash.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetViewport.md

@@ -1,31 +1,19 @@
-# OpenGLPipelineState::SetViewport
-
-设置相关状态或配置。
+# OpenGLPipelineState::SetViewport()
 
 ```cpp
 void SetViewport(const ViewportState& state);
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+缓存 viewport 状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::SetViewport(...)。
-    (void)object;
-}
-```
+- 直接把 `state` 复制到 `m_viewportState`
+- 不立即调用 OpenGL
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [ApplyViewport](ApplyViewport.md)
+- [Bind](Bind.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Shutdown.md

@@ -1,30 +1,28 @@
-# OpenGLPipelineState::Shutdown
-
-关闭并清理内部状态。
+# OpenGLPipelineState::Shutdown()
 
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放当前对象拥有的 graphics shader，并重置程序与标记位。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- `m_graphicsShader.reset()`
+- 把 `m_program` 置为 `0`
+- 把 `m_computeProgram` 置为 `0`
+- 把 `m_computeShader` 置为 `nullptr`
+- 把 `m_programAttached` 置为 `false`
 
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
+## 需要特别注意
 
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::Shutdown(...)。
-    (void)object;
-}
-```
+- 不会清空 `m_inputLayoutDesc`、`m_blendDesc`、`m_depthStencilDesc`、`m_rasterizerDesc`
+- 不会重置 OpenGL 专用状态结构
+- 若 graphics program 不是通过 `m_graphicsShader` 拥有，而是外部 raw program 方式附着，这里不会负责删除那个外部 program
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [SetOwnedGraphicsShader](SetOwnedGraphicsShader.md)
+- [Destructor](Destructor.md)

docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Unbind.md

@@ -1,30 +1,19 @@
-# OpenGLPipelineState::Unbind
-
-公开方法，详见头文件声明。
+# OpenGLPipelineState::Unbind()
 
 ```cpp
 void Unbind() override;
 ```
 
-该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+解绑当前 program。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
-
-void Example() {
-    XCEngine::RHI::OpenGLPipelineState object;
-    // 根据上下文补齐参数后调用 OpenGLPipelineState::Unbind(...)。
-    (void)object;
-}
-```
+- 直接调用 `glUseProgram(0)`
+- 不回滚 blend / depth / rasterizer / viewport / scissor 状态
 
 ## 相关文档
 
-- [返回类总览](OpenGLPipelineState.md)
-- [返回模块目录](../OpenGL.md)
+- [Bind](Bind.md)
+- [DetachShader](DetachShader.md)

docs/api/_meta/rebuild-status.md

@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-28 01:09:27`
+**生成时间**: `2026-03-28 01:17:27`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`