xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): expand fence and framebuffer docs

Browse Source
This commit is contained in:
ssdfasd
2026-03-27 22:48:58 +08:00
parent 14e9190a35
commit 0c8a3e90ec
39 changed files with 398 additions and 730 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/api/XCEngine/RHI/D3D12/D3D12Fence/Constructor.md
View File

@@ -1,28 +1,18 @@
# D3D12Fence::D3D12Fence() # D3D12Fence::D3D12Fence
构造对象。
```cpp ```cpp
D3D12Fence(); D3D12Fence();
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 构造一个空 fence 对象。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 仅把内部 event 句柄初始化为 `nullptr`。
- 不创建原生 fence。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Fence.h>
void Example() {
XCEngine::RHI::D3D12Fence object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Fence.md) - [Initialize](Initialize.md)
- [返回模块目录](../D3D12.md)

51
docs/api/XCEngine/RHI/D3D12/D3D12Fence/D3D12Fence.md
View File

@@ -6,34 +6,43 @@
**头文件**: `XCEngine/RHI/D3D12/D3D12Fence.h` **头文件**: `XCEngine/RHI/D3D12/D3D12Fence.h`
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Fence` public API。 **描述**: D3D12 后端的 fence 封装，持有一个 `ID3D12Fence` 和一个 Win32 event，用于 GPU / CPU 同步。
## 概述 ## 概述
`D3D12Fence.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 和 OpenGL 的模拟方案不同，D3D12 有原生 fence 机制。`D3D12Fence` 基本上是一个轻量封装:
## 声明概览 - `ID3D12Fence`
- 一个 `CreateEvent()` 创建的 Win32 event
| 声明 | 类型 | 说明 | 这让它既能参与命令队列信号链路，也能在 CPU 端通过 `SetEventOnCompletion()` 阻塞等待。
|------|------|------|
| `D3D12Fence` | `class` | 继承自 `RHIFence` 的公开声明。 |
## 公共方法 ## 当前实现的真实行为
| 方法 | 描述 | - [`Initialize`](Initialize.md) 会创建 fence 和 event。
|------|------| - [`Wait`](Wait.md) 通过 `SetEventOnCompletion()` + `WaitForSingleObject()` 等待 GPU 达到目标值。
| [D3D12Fence()](Constructor.md) | 构造对象。 | - [`Signal`](Signal.md) 直接调用 `ID3D12Fence::Signal()`，这是 CPU 侧 signal，不是命令队列 signal。
| [~D3D12Fence()](Destructor.md) | 销毁对象并释放相关资源。 | - 真正用于“让 GPU queue signal 某个 fence 值”的常见路径，是 [`D3D12CommandQueue::Signal`](../D3D12CommandQueue/Signal.md)。
| [Initialize](Initialize.md) | 初始化内部状态。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | ## 设计含义
| [Signal](Signal.md) | 公开方法，详见头文件声明。 |
| [Wait](Wait.md) | 公开方法，详见头文件声明。 | - 这与商业引擎常见的做法一致: fence 对象负责同步原语本身，命令队列负责把 GPU 执行进度写入 fence。
| [GetCompletedValue](GetCompletedValue.md) | 获取相关状态或对象。 | - 单独暴露 `Signal()` 让测试和 CPU 驱动流程也能直接推进 fence 值。
| [GetEventHandle](GetEventHandle.md) | 获取相关状态或对象。 |
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | ## 当前限制
| [GetFence](GetFence.md) | 获取相关状态或对象。 |
- `Signal()` 并不等价于“GPU 已执行到这里”，除非它是由命令队列调用底层 queue signal 完成的。
- 如果 `CreateFence()` 成功但 `CreateEvent()` 失败，`Initialize()` 会返回 `false`。
## 重点方法
- [Initialize](Initialize.md)
- [Signal](Signal.md)
- [Wait](Wait.md)
- [GetCompletedValue](GetCompletedValue.md)
- [GetFence](GetFence.md)
## 相关文档 ## 相关文档
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录 - [D3D12](../D3D12.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [D3D12CommandQueue](../D3D12CommandQueue/D3D12CommandQueue.md)

25
docs/api/XCEngine/RHI/D3D12/D3D12Fence/Destructor.md
View File

@@ -1,29 +1,18 @@
# D3D12Fence::~D3D12Fence() # D3D12Fence::~D3D12Fence
销毁对象并释放相关资源。
```cpp ```cpp
~D3D12Fence() override; ~D3D12Fence() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 销毁 fence 对象并释放其原生资源。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 析构函数调用 [`Shutdown`](Shutdown.md)。
- 会关闭 Win32 event 并释放 `ID3D12Fence`。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Fence.h>
void Example() {
XCEngine::RHI::D3D12Fence object;
// 对象离开作用域时会自动触发析构。
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Fence.md) - [Shutdown](Shutdown.md)
- [返回模块目录](../D3D12.md)

24
docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetCompletedValue.md
View File

@@ -1,30 +1,18 @@
# D3D12Fence::GetCompletedValue # D3D12Fence::GetCompletedValue
获取相关状态或对象。
```cpp ```cpp
uint64_t GetCompletedValue() const override; uint64_t GetCompletedValue() const override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 查询底层 D3D12 fence 当前已完成到的值。
**返回：** `uint64_t` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 直接返回 `m_fence->GetCompletedValue()`。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Fence.h>
void Example() {
XCEngine::RHI::D3D12Fence object;
// 根据上下文补齐参数后调用 D3D12Fence::GetCompletedValue(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Fence.md) - [Wait](Wait.md)
- [返回模块目录](../D3D12.md) - [Signal](Signal.md)

23
docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetEventHandle.md
View File

@@ -1,30 +1,21 @@
# D3D12Fence::GetEventHandle # D3D12Fence::GetEventHandle
获取相关状态或对象。
```cpp ```cpp
void* GetEventHandle(); void* GetEventHandle();
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回 fence 内部持有的 Win32 event 句柄。
**返回：** `void*` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 返回 `HANDLE`，以 `void*` 形式暴露。
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12Fence.h>
void Example() { - 该句柄主要用于需要直接与 Win32 等待 API 交互的场景。
XCEngine::RHI::D3D12Fence object;
// 根据上下文补齐参数后调用 D3D12Fence::GetEventHandle(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Fence.md) - [Wait](Wait.md)
- [返回模块目录](../D3D12.md)

24
docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetFence.md
View File

@@ -1,30 +1,22 @@
# D3D12Fence::GetFence # D3D12Fence::GetFence
获取相关状态或对象。
```cpp ```cpp
ID3D12Fence* GetFence() const; ID3D12Fence* GetFence() const;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 以强类型方式返回底层 `ID3D12Fence` 指针。
**返回：** `ID3D12Fence*` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 返回 `m_fence.Get()`。
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12Fence.h>
void Example() { - 这是 `D3D12CommandQueue::Signal()` 等底层桥接代码使用的主要接口。
XCEngine::RHI::D3D12Fence object;
// 根据上下文补齐参数后调用 D3D12Fence::GetFence(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Fence.md) - [GetNativeHandle](GetNativeHandle.md)
- [返回模块目录](../D3D12.md) - [D3D12CommandQueue::Signal](../D3D12CommandQueue/Signal.md)

23
docs/api/XCEngine/RHI/D3D12/D3D12Fence/GetNativeHandle.md
View File

@@ -1,30 +1,17 @@
# D3D12Fence::GetNativeHandle # D3D12Fence::GetNativeHandle
获取相关状态或对象。
```cpp ```cpp
void* GetNativeHandle() override; void* GetNativeHandle() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回原生 `ID3D12Fence*`。
**返回：** `void*` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 以 `void*` 形式返回 `m_fence.Get()`。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Fence.h>
void Example() {
XCEngine::RHI::D3D12Fence object;
// 根据上下文补齐参数后调用 D3D12Fence::GetNativeHandle(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Fence.md) - [GetFence](GetFence.md)
- [返回模块目录](../D3D12.md)

37
docs/api/XCEngine/RHI/D3D12/D3D12Fence/Initialize.md
View File

@@ -1,32 +1,33 @@
# D3D12Fence::Initialize # D3D12Fence::Initialize
初始化内部状态。
```cpp ```cpp
bool Initialize(ID3D12Device* device, uint64_t initialValue = 0); bool Initialize(ID3D12Device* device, uint64_t initialValue = 0);
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 创建原生 `ID3D12Fence` 与等待用的 Win32 event。
- `device` - 参数语义详见头文件声明。
- `initialValue` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 前置条件
**示例：** - `device` 必须有效。
```cpp ## 参数
#include <XCEngine/RHI/D3D12/D3D12Fence.h>
void Example() { - `device`: 用于创建 fence 的 D3D12 设备。
XCEngine::RHI::D3D12Fence object; - `initialValue`: fence 初始值。
// 根据上下文补齐参数后调用 D3D12Fence::Initialize(...)。
(void)object; ## 返回值
}
``` - fence 和 event 都创建成功时返回 `true`。
- 任一环节失败时返回 `false`。
## 当前实现行为
- 调用 `device->CreateFence(initialValue, D3D12_FENCE_FLAG_NONE, ...)`。
- 再调用 `CreateEvent(nullptr, FALSE, FALSE, nullptr)` 创建自动复位 event。
## 相关文档 ## 相关文档
- [返回类总览](D3D12Fence.md) - [Wait](Wait.md)
- [返回模块目录](../D3D12.md) - [GetEventHandle](GetEventHandle.md)

24
docs/api/XCEngine/RHI/D3D12/D3D12Fence/Shutdown.md
View File

@@ -1,30 +1,18 @@
# D3D12Fence::Shutdown # D3D12Fence::Shutdown
关闭并清理内部状态。
```cpp ```cpp
void Shutdown() override; void Shutdown() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 释放 fence 的 Win32 event 和原生 `ID3D12Fence`。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 如果 event 存在，则调用 `CloseHandle()`。
- 然后 `m_fence.Reset()` 释放 COM 对象。
```cpp
#include <XCEngine/RHI/D3D12/D3D12Fence.h>
void Example() {
XCEngine::RHI::D3D12Fence object;
// 根据上下文补齐参数后调用 D3D12Fence::Shutdown(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Fence.md) - [Destructor](Destructor.md)
- [返回模块目录](../D3D12.md)

40
docs/api/XCEngine/RHI/D3D12/D3D12Fence/Signal.md
View File

@@ -1,43 +1,25 @@
# D3D12Fence::Signal # D3D12Fence::Signal
公开方法，详见头文件声明。
该方法在 `XCEngine/RHI/D3D12/D3D12Fence.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void Signal() override; void Signal() override;
```
**参数：** 无。
**返回：** `void` - 无返回值。
## 重载 2: 声明
```cpp
void Signal(uint64_t value) override; void Signal(uint64_t value) override;
``` ```
**参数：** ## 作用
- `value` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 直接在 fence 对象上写入一个新值。
**示例：** ## 当前实现行为
```cpp - 无参版本等价于 `Signal(1)`。
#include <XCEngine/RHI/D3D12/D3D12Fence.h> - 有参版本直接调用 `m_fence->Signal(value)`。
void Example() { ## 重要区别
XCEngine::RHI::D3D12Fence object;
// 根据上下文补齐参数后调用 D3D12Fence::Signal(...)。 - 这是 `ID3D12Fence` 自身的 CPU 侧 signal。
(void)object; - 如果你想表达“某条 GPU 命令队列在执行到某个位置后 signal fence”，应使用 [`D3D12CommandQueue::Signal`](../D3D12CommandQueue/Signal.md)。
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Fence.md) - [Wait](Wait.md)
- [返回模块目录](../D3D12.md) - [GetCompletedValue](GetCompletedValue.md)

26
docs/api/XCEngine/RHI/D3D12/D3D12Fence/Wait.md
View File

@@ -1,31 +1,23 @@
# D3D12Fence::Wait # D3D12Fence::Wait
公开方法，详见头文件声明。
```cpp ```cpp
void Wait(uint64_t value) override; void Wait(uint64_t value) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Fence.h`，当前页面用于固定 `D3D12Fence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 阻塞当前 CPU 线程，直到 fence 完成值达到指定阈值。
- `value` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `value`: 目标 fence 值。
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12Fence.h>
void Example() { - 如果 `GetCompletedValue() >= value`，立即返回。
XCEngine::RHI::D3D12Fence object; - 否则调用 `SetEventOnCompletion(value, m_eventHandle)`，再 `WaitForSingleObject(m_eventHandle, INFINITE)`。
// 根据上下文补齐参数后调用 D3D12Fence::Wait(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12Fence.md) - [GetCompletedValue](GetCompletedValue.md)
- [返回模块目录](../D3D12.md) - [GetEventHandle](GetEventHandle.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Constructor.md
View File

@@ -1,28 +1,18 @@
# OpenGLFence::OpenGLFence() # OpenGLFence::OpenGLFence
构造对象。
```cpp ```cpp
OpenGLFence(); OpenGLFence();
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 构造一个空 fence 对象。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 不创建 `GLsync`。
- `m_signaledValue` 与 `m_completedValue` 初始化为 `0`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
void Example() {
XCEngine::RHI::OpenGLFence object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFence.md) - [Initialize](Initialize.md)
- [返回模块目录](../OpenGL.md)

25
docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Destructor.md
View File

@@ -1,29 +1,18 @@
# OpenGLFence::~OpenGLFence() # OpenGLFence::~OpenGLFence
销毁对象并释放相关资源。
```cpp ```cpp
~OpenGLFence() override; ~OpenGLFence() override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 销毁 fence 并释放内部 `GLsync`。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 析构函数调用 [`Shutdown`](Shutdown.md)。
- 如果内部仍持有 sync，会执行 `glDeleteSync()`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
void Example() {
XCEngine::RHI::OpenGLFence object;
// 对象离开作用域时会自动触发析构。
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFence.md) - [Shutdown](Shutdown.md)
- [返回模块目录](../OpenGL.md)

26
docs/api/XCEngine/RHI/OpenGL/OpenGLFence/GetCompletedValue.md
View File

@@ -1,30 +1,24 @@
# OpenGLFence::GetCompletedValue # OpenGLFence::GetCompletedValue
获取相关状态或对象。
```cpp ```cpp
uint64_t GetCompletedValue() const override; uint64_t GetCompletedValue() const override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 查询 fence 当前已完成到哪个值。
**返回：** `uint64_t` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 如果没有活动中的 `GLsync`，返回 `m_completedValue`。
- 如果 `GLsync` 已被驱动标记为 `GL_SIGNALED`，返回 `m_signaledValue`。
- 否则返回 `m_completedValue`。
```cpp ## 当前实现行为
#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
void Example() { - 该函数会查询 `GL_SYNC_STATUS`，但不会主动删除 sync，也不会把 `m_completedValue` 写回最新值。
XCEngine::RHI::OpenGLFence object;
// 根据上下文补齐参数后调用 OpenGLFence::GetCompletedValue(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFence.md) - [Wait](Wait.md)
- [返回模块目录](../OpenGL.md) - [Signal](Signal.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLFence/GetNativeHandle.md
View File

@@ -1,30 +1,22 @@
# OpenGLFence::GetNativeHandle # OpenGLFence::GetNativeHandle
获取相关状态或对象。
```cpp ```cpp
void* GetNativeHandle() override; void* GetNativeHandle() override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回底层 `GLsync` 句柄。
**返回：** `void*` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 返回内部 `GLsync`，以 `void*` 形式暴露。
```cpp ## 当前实现行为
#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
void Example() { - 如果当前还没有 sync，会立即调用 `glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0)` 创建一个新的。
XCEngine::RHI::OpenGLFence object; - 因此它不是纯 getter，而是带副作用的懒初始化接口。
// 根据上下文补齐参数后调用 OpenGLFence::GetNativeHandle(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFence.md) - [Signal](Signal.md)
- [返回模块目录](../OpenGL.md)

30
docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Initialize.md
View File

@@ -1,31 +1,27 @@
# OpenGLFence::Initialize # OpenGLFence::Initialize
初始化内部状态。
```cpp ```cpp
bool Initialize(uint64_t initialValue = 0); bool Initialize(uint64_t initialValue = 0);
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 初始化 CPU 侧 fence 计数状态。
- `initialValue` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 参数
**示例：** - `initialValue`: 初始 signaled / completed 值。
```cpp ## 返回值
#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
void Example() { - 当前实现始终返回 `true`。
XCEngine::RHI::OpenGLFence object;
// 根据上下文补齐参数后调用 OpenGLFence::Initialize(...)。 ## 当前实现行为
(void)object;
} - 不会立即创建 `GLsync`。
``` - 仅把 `m_signaledValue` 和 `m_completedValue` 设为 `initialValue`。
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFence.md) - [Signal](Signal.md)
- [返回模块目录](../OpenGL.md) - [GetCompletedValue](GetCompletedValue.md)

52
docs/api/XCEngine/RHI/OpenGL/OpenGLFence/OpenGLFence.md
View File

@@ -6,32 +6,46 @@
**头文件**: `XCEngine/RHI/OpenGL/OpenGLFence.h` **头文件**: `XCEngine/RHI/OpenGL/OpenGLFence.h`
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLFence` public API。 **描述**: OpenGL 后端的同步对象封装，使用单个 `GLsync` 配合 CPU 侧计数值模拟 timeline 风格的 fence 接口。
## 概述 ## 概述
`OpenGLFence.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 OpenGL 没有 D3D12 那种原生 timeline fence 接口，更多是一次性的 `GLsync` 栅栏。`OpenGLFence` 的实现方式，是把:
## 声明概览 - 一个可被替换的 `GLsync`
- 一个“最近 signal 的值”
- 一个“最近确认完成的值”
| 声明 | 类型 | 说明 | 组合起来，向 RHI 暴露出近似 timeline fence 的 API 形状。
|------|------|------|
| `OpenGLFence` | `class` | 继承自 `RHIFence` 的公开声明。 |
## 公共方法 这类适配在跨后端引擎里很常见，但要明确一点: 它的接口看起来像 timeline fence，不代表底层语义真的和 D3D12 / Vulkan 完全一致。
| 方法 | 描述 | ## 当前实现的真实行为
|------|------|
| [OpenGLFence()](Constructor.md) | 构造对象。 | - 对象内部同一时间只维护一个 `GLsync`。
| [~OpenGLFence()](Destructor.md) | 销毁对象并释放相关资源。 | - 每次 [`Signal`](Signal.md) 新值时，如果旧 `GLsync` 还存在，会先等待并删除旧同步对象。
| [Initialize](Initialize.md) | 初始化内部状态。 | - [`Wait`](Wait.md) 等待成功后，会把 `m_completedValue` 直接更新为当前 `m_signaledValue`。
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | - [`GetNativeHandle`](GetNativeHandle.md) 在还没有 sync 时会懒创建一个新的 `GLsync`。
| [Signal](Signal.md) | 公开方法，详见头文件声明。 |
| [Wait](Wait.md) | 公开方法，详见头文件声明。 | ## 设计取舍
| [GetCompletedValue](GetCompletedValue.md) | 获取相关状态或对象。 |
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | - 这种实现足够支撑当前引擎的基础“提交后等待完成”流程。
- 代价是它不能同时保留多段独立的 in-flight timeline 历史。
## 当前限制
- 不是严格意义上的 timeline fence。
- 如果通过 [`OpenGLDevice::CreateFence`](../OpenGLDevice/CreateFence.md) 创建，`initialValue > 0` 当前只会被折叠成 `1`，不会保留原始数值。
- `GetNativeHandle()` 本身带有副作用: 可能会额外插入新的 `GLsync`。
## 重点方法
- [Initialize](Initialize.md)
- [Signal](Signal.md)
- [Wait](Wait.md)
- [GetCompletedValue](GetCompletedValue.md)
## 相关文档 ## 相关文档
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 - [OpenGL](../OpenGL.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [OpenGLCommandQueue](../OpenGLCommandQueue/OpenGLCommandQueue.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Shutdown.md
View File

@@ -1,30 +1,18 @@
# OpenGLFence::Shutdown # OpenGLFence::Shutdown
关闭并清理内部状态。
```cpp ```cpp
void Shutdown() override; void Shutdown() override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 释放内部同步对象并重置计数状态。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 如果 `m_sync` 存在，则调用 `glDeleteSync()` 并清空指针。
- 把 `m_signaledValue` 和 `m_completedValue` 都重置为 `0`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
void Example() {
XCEngine::RHI::OpenGLFence object;
// 根据上下文补齐参数后调用 OpenGLFence::Shutdown(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFence.md) - [Destructor](Destructor.md)
- [返回模块目录](../OpenGL.md)

42
docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Signal.md
View File

@@ -1,43 +1,27 @@
# OpenGLFence::Signal # OpenGLFence::Signal
公开方法，详见头文件声明。
该方法在 `XCEngine/RHI/OpenGL/OpenGLFence.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void Signal() override; void Signal() override;
```
**参数：** 无。
**返回：** `void` - 无返回值。
## 重载 2: 声明
```cpp
void Signal(uint64_t value) override; void Signal(uint64_t value) override;
``` ```
**参数：** ## 作用
- `value` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 插入一条新的 OpenGL 同步点，并记录对应的 fence 值。
**示例：** ## 当前实现行为
```cpp - 无参版本等价于 `Signal(1)`。
#include <XCEngine/RHI/OpenGL/OpenGLFence.h> - 如果旧 `GLsync` 还存在，会先等待它完成并删除，再创建新的 `GLsync`。
- 在创建新 sync 前会先调用 `glFlush()`。
- `m_signaledValue` 被更新为传入值。
void Example() { ## 当前限制
XCEngine::RHI::OpenGLFence object;
// 根据上下文补齐参数后调用 OpenGLFence::Signal(...)。 - 不强制值单调递增。
(void)object; - 因为旧 sync 会被替换，它不能保留多段未完成 timeline 的历史。
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFence.md) - [Wait](Wait.md)
- [返回模块目录](../OpenGL.md) - [GetCompletedValue](GetCompletedValue.md)

32
docs/api/XCEngine/RHI/OpenGL/OpenGLFence/Wait.md
View File

@@ -1,31 +1,29 @@
# OpenGLFence::Wait # OpenGLFence::Wait
公开方法，详见头文件声明。
```cpp ```cpp
void Wait(uint64_t value) override; void Wait(uint64_t value) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFence.h`，当前页面用于固定 `OpenGLFence` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 在 CPU 侧等待 fence 达到指定值。
- `value` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `value`: 希望等待到的 fence 值。
```cpp ## 当前实现行为
#include <XCEngine/RHI/OpenGL/OpenGLFence.h>
void Example() { - 如果 `m_completedValue >= value`，直接返回。
XCEngine::RHI::OpenGLFence object; - 如果内部存在 `GLsync`，会调用 `glClientWaitSync(..., GL_TIMEOUT_IGNORED)` 阻塞等待，然后删除该 sync。
// 根据上下文补齐参数后调用 OpenGLFence::Wait(...)。 - 等待结束后，把 `m_completedValue` 更新为当前 `m_signaledValue`。
(void)object;
} ## 当前限制
```
- 它并不会验证“当前 signaled 值是否真的大于等于请求值”。
- 这再次说明它是“单 sync + 计数缓存”的模拟方案，而不是真 timeline fence。
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFence.md) - [Signal](Signal.md)
- [返回模块目录](../OpenGL.md) - [GetCompletedValue](GetCompletedValue.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Bind.md
View File

@@ -1,30 +1,18 @@
# OpenGLFramebuffer::Bind # OpenGLFramebuffer::Bind
公开方法，详见头文件声明。
```cpp ```cpp
void Bind(); void Bind();
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 把当前 FBO 绑定到 `GL_FRAMEBUFFER`。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, m_framebuffer)`。
- 不区分 `READ_FRAMEBUFFER` 与 `DRAW_FRAMEBUFFER`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::Bind(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [Unbind](Unbind.md)
- [返回模块目录](../OpenGL.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/BindFramebuffer.md
View File

@@ -1,31 +1,17 @@
# OpenGLFramebuffer::BindFramebuffer # OpenGLFramebuffer::BindFramebuffer
公开方法，详见头文件声明。
```cpp ```cpp
static void BindFramebuffer(unsigned int framebuffer); static void BindFramebuffer(unsigned int framebuffer);
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 静态辅助函数，把任意 framebuffer id 绑定到 `GL_FRAMEBUFFER`。
- `framebuffer` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, framebuffer)`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::BindFramebuffer(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [UnbindFramebuffer](UnbindFramebuffer.md)
- [返回模块目录](../OpenGL.md)

32
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearColor.md
View File

@@ -1,35 +1,25 @@
# OpenGLFramebuffer::ClearColor # OpenGLFramebuffer::ClearColor
清空内部数据。
```cpp ```cpp
void ClearColor(int attachmentIndex, float r, float g, float b, float a); void ClearColor(int attachmentIndex, float r, float g, float b, float a);
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 清除指定颜色附件。
- `attachmentIndex` - 参数语义详见头文件声明。
- `r` - 参数语义详见头文件声明。
- `g` - 参数语义详见头文件声明。
- `b` - 参数语义详见头文件声明。
- `a` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `attachmentIndex`: 颜色附件序号。
- `r` / `g` / `b` / `a`: 清除颜色。
```cpp ## 当前实现行为
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() { - 先绑定当前 FBO。
XCEngine::RHI::OpenGLFramebuffer object; - 调用 `glClearBufferfv(GL_COLOR, attachmentIndex, &r)` 执行清除。
// 根据上下文补齐参数后调用 OpenGLFramebuffer::ClearColor(...)。 - 不恢复之前的 framebuffer 绑定状态。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [ClearDepth](ClearDepth.md)
- [返回模块目录](../OpenGL.md) - [ClearDepthStencil](ClearDepthStencil.md)

25
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepth.md
View File

@@ -1,31 +1,18 @@
# OpenGLFramebuffer::ClearDepth # OpenGLFramebuffer::ClearDepth
清空内部数据。
```cpp ```cpp
void ClearDepth(float depth); void ClearDepth(float depth);
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 清除当前 framebuffer 的深度附件。
- `depth` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 先绑定当前 FBO。
- 调用 `glClearDepth(depth)`，随后执行 `glClear(GL_DEPTH_BUFFER_BIT)`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::ClearDepth(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [ClearDepthStencil](ClearDepthStencil.md)
- [返回模块目录](../OpenGL.md)

28
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearDepthStencil.md
View File

@@ -1,32 +1,20 @@
# OpenGLFramebuffer::ClearDepthStencil # OpenGLFramebuffer::ClearDepthStencil
清空内部数据。
```cpp ```cpp
void ClearDepthStencil(float depth, uint8_t stencil); void ClearDepthStencil(float depth, uint8_t stencil);
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 同时清除深度和模板附件。
- `depth` - 参数语义详见头文件声明。
- `stencil` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 先绑定当前 FBO。
- 设置 `glClearDepth(depth)` 与 `glClearStencil(stencil)`。
```cpp - 调用 `glClear(GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT)`。
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::ClearDepthStencil(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [ClearDepth](ClearDepth.md)
- [返回模块目录](../OpenGL.md) - [ClearStencil](ClearStencil.md)

25
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/ClearStencil.md
View File

@@ -1,31 +1,18 @@
# OpenGLFramebuffer::ClearStencil # OpenGLFramebuffer::ClearStencil
清空内部数据。
```cpp ```cpp
void ClearStencil(uint8_t stencil); void ClearStencil(uint8_t stencil);
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 清除当前 framebuffer 的模板附件。
- `stencil` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 先绑定当前 FBO。
- 调用 `glClearStencil(stencil)`，随后执行 `glClear(GL_STENCIL_BUFFER_BIT)`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::ClearStencil(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [ClearDepthStencil](ClearDepthStencil.md)
- [返回模块目录](../OpenGL.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Constructor.md
View File

@@ -1,28 +1,18 @@
# OpenGLFramebuffer::OpenGLFramebuffer() # OpenGLFramebuffer::OpenGLFramebuffer
构造对象。
```cpp ```cpp
OpenGLFramebuffer(); OpenGLFramebuffer();
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 构造一个空 FBO 包装对象。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 把 framebuffer id、宽高和 sample 数初始化为 `0 / 0 / 1`。
- 不创建真实 OpenGL framebuffer。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [Initialize](Initialize.md)
- [返回模块目录](../OpenGL.md)

25
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Destructor.md
View File

@@ -1,29 +1,18 @@
# OpenGLFramebuffer::~OpenGLFramebuffer() # OpenGLFramebuffer::~OpenGLFramebuffer
销毁对象并释放相关资源。
```cpp ```cpp
~OpenGLFramebuffer() override; ~OpenGLFramebuffer() override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 销毁对象并释放内部 FBO。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 析构函数调用 [`Shutdown`](Shutdown.md)。
- 如果已经创建过 framebuffer，会执行 `glDeleteFramebuffers()`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 对象离开作用域时会自动触发析构。
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [Shutdown](Shutdown.md)
- [返回模块目录](../OpenGL.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetFramebuffer.md
View File

@@ -1,30 +1,18 @@
# OpenGLFramebuffer::GetFramebuffer # OpenGLFramebuffer::GetFramebuffer
获取相关状态或对象。
```cpp ```cpp
unsigned int GetFramebuffer() const; unsigned int GetFramebuffer() const;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回内部保存的 OpenGL framebuffer id。
**返回：** `unsigned int` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 返回 `m_framebuffer`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::GetFramebuffer(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [GetNativeHandle](GetNativeHandle.md)
- [返回模块目录](../OpenGL.md) - [BindFramebuffer](BindFramebuffer.md)

23
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetHeight.md
View File

@@ -1,30 +1,17 @@
# OpenGLFramebuffer::GetHeight # OpenGLFramebuffer::GetHeight
获取相关状态或对象。
```cpp ```cpp
uint32_t GetHeight() const override; uint32_t GetHeight() const override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回 framebuffer 的逻辑高度。
**返回：** `uint32_t` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 返回内部记录的 `m_height`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::GetHeight(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [GetWidth](GetWidth.md)
- [返回模块目录](../OpenGL.md)

23
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetNativeHandle.md
View File

@@ -1,30 +1,17 @@
# OpenGLFramebuffer::GetNativeHandle # OpenGLFramebuffer::GetNativeHandle
获取相关状态或对象。
```cpp ```cpp
void* GetNativeHandle() override; void* GetNativeHandle() override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回原生 OpenGL framebuffer id。
**返回：** `void*` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - 返回 `m_framebuffer`，以 `void*` 形式暴露。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::GetNativeHandle(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [GetFramebuffer](GetFramebuffer.md)
- [返回模块目录](../OpenGL.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/GetWidth.md
View File

@@ -1,30 +1,18 @@
# OpenGLFramebuffer::GetWidth # OpenGLFramebuffer::GetWidth
获取相关状态或对象。
```cpp ```cpp
uint32_t GetWidth() const override; uint32_t GetWidth() const override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 返回 framebuffer 的逻辑宽度。
**返回：** `uint32_t` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 返回内部记录的 `m_width`。
- 该值来自初始化参数，而不是运行时向 OpenGL 查询。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::GetWidth(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [GetHeight](GetHeight.md)
- [返回模块目录](../OpenGL.md)

62
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Initialize.md
View File

@@ -1,49 +1,47 @@
# OpenGLFramebuffer::Initialize # OpenGLFramebuffer::Initialize
初始化内部状态。
该方法在 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
bool Initialize(const FramebufferDesc& desc); bool Initialize(const FramebufferDesc& desc);
bool Initialize(
RHIRenderPass* renderPass,
uint32_t width,
uint32_t height,
uint32_t colorAttachmentCount,
RHIResourceView** colorAttachments,
RHIResourceView* depthStencilAttachment) override;
``` ```
**参数：** ## 作用
- `desc` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 创建并填充一个 OpenGL framebuffer object。
## 重载 2: 声明 ## 当前实现行为
```cpp ### `Initialize(const FramebufferDesc& desc)`
bool Initialize(class RHIRenderPass* renderPass, uint32_t width, uint32_t height, uint32_t colorAttachmentCount, RHIResourceView** colorAttachments, RHIResourceView* depthStencilAttachment) override;
```
**参数：** - 复制 `FramebufferDesc` 到内部成员。
- `renderPass` - 参数语义详见头文件声明。 - 创建 FBO 并附着最多 `16` 个颜色附件。
- `width` - 参数语义详见头文件声明。 - 根据 depth / stencil 附件类型选择合适的 attachment point。
- `height` - 参数语义详见头文件声明。 - 如果没有颜色附件，会把 `glDrawBuffer` 和 `glReadBuffer` 设为 `GL_NONE`。
- `colorAttachmentCount` - 参数语义详见头文件声明。 - 调用 `glCheckFramebufferStatus(GL_FRAMEBUFFER)` 验证完整性。
- `colorAttachments` - 参数语义详见头文件声明。
- `depthStencilAttachment` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ### `Initialize(RHIRenderPass*, ...)`
**示例：** - 当前忽略 `renderPass` 参数。
- 从 `OpenGLResourceView::GetFramebufferAttachment()` 提取附件信息。
- 同样创建 FBO、设置 draw buffer，并检查完整性。
```cpp ## 返回值
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() { - FBO 完整时返回 `true`。
XCEngine::RHI::OpenGLFramebuffer object; - `glCheckFramebufferStatus()` 不是 `GL_FRAMEBUFFER_COMPLETE` 时返回 `false`。
// 根据上下文补齐参数后调用 OpenGLFramebuffer::Initialize(...)。
(void)object; ## 当前限制
}
``` - 创建失败时不会在函数内部立即删除刚生成的 FBO id，通常由后续析构统一释放。
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [IsValid](IsValid.md)
- [返回模块目录](../OpenGL.md) - [GetFramebuffer](GetFramebuffer.md)

23
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/IsValid.md
View File

@@ -1,30 +1,21 @@
# OpenGLFramebuffer::IsValid # OpenGLFramebuffer::IsValid
查询当前状态。
```cpp ```cpp
bool IsValid() const override; bool IsValid() const override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 判断当前对象是否持有非零 FBO id。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `m_framebuffer != 0` 时返回 `true`。
```cpp ## 当前实现行为
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() { - 这是一个轻量检查，不会再次执行 `glCheckFramebufferStatus()`。
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::IsValid(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [Initialize](Initialize.md)
- [返回模块目录](../OpenGL.md)

70
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/OpenGLFramebuffer.md
View File

@@ -6,44 +6,52 @@
**头文件**: `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h` **头文件**: `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLFramebuffer` public API。 **描述**: OpenGL 后端的 framebuffer 对象封装，用于把颜色、深度、模板附件组织成一个可绑定的 FBO。
## 概述 ## 概述
`OpenGLFramebuffer.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 和 Vulkan / D3D12 的 render pass + framebuffer 分层不同，OpenGL 更偏向直接操作 framebuffer object。`OpenGLFramebuffer` 的职责，是把引擎内部的附件描述或资源视图组合成一个实际的 FBO，并提供基础的绑定与清屏操作。
## 声明概览 它可以理解为 OpenGL 后端里的“附件包”:
| 声明 | 类型 | 说明 | - 你先描述要挂哪些 texture / layer / mip。
|------|------|------| - 它负责创建 FBO、附着附件并检查完整性。
| `FramebufferAttachmentType` | `enum class` | 头文件中的公开声明。 | - 命令列表或截图逻辑再在这个 FBO 上执行绘制、清理和 blit。
| `FramebufferAttachment` | `struct` | 头文件中的公开声明。 |
| `FramebufferDesc` | `struct` | 头文件中的公开声明。 |
| `OpenGLFramebuffer` | `class` | 继承自 `RHIFramebuffer` 的公开声明。 |
## 公共方法 ## 当前实现的真实行为
| 方法 | 描述 | ### 两种初始化路径
|------|------|
| [OpenGLFramebuffer()](Constructor.md) | 构造对象。 | - [`Initialize(const FramebufferDesc&)`](Initialize.md) 直接按 `FramebufferDesc` 组装附件。
| [~OpenGLFramebuffer()](Destructor.md) | 销毁对象并释放相关资源。 | - [`Initialize(RHIRenderPass*, ...)`](Initialize.md) 从 `RHIResourceView` 数组提取附件信息。
| [Initialize](Initialize.md) | 初始化内部状态。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | ### 附件绑定策略
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
| [GetWidth](GetWidth.md) | 获取相关状态或对象。 | - 最多处理 `16` 个颜色附件。
| [GetHeight](GetHeight.md) | 获取相关状态或对象。 | - 根据 attachment 的 target / layer / mip，选择 `glFramebufferTexture1D`、`glFramebufferTexture2D`、`glFramebufferTextureLayer` 或 `glFramebufferTexture`。
| [IsValid](IsValid.md) | 查询当前状态。 | - 深度附件如果标记为 `DepthStencil`，会绑定到 `GL_DEPTH_STENCIL_ATTACHMENT`。
| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 | ### render pass 参数
| [ClearColor](ClearColor.md) | 清空内部数据。 |
| [ClearDepth](ClearDepth.md) | 清空内部数据。 | - `Initialize(RHIRenderPass*, ...)` 当前会忽略 `renderPass` 本身。
| [ClearStencil](ClearStencil.md) | 清空内部数据。 | - 也就是说，这个类在 OpenGL 后端更接近“附件集合对象”，而不是对 Vulkan / D3D12 render pass 语义的完全镜像。
| [ClearDepthStencil](ClearDepthStencil.md) | 清空内部数据。 |
| [GetFramebuffer](GetFramebuffer.md) | 获取相关状态或对象。 | ## 当前限制
| [BindFramebuffer](BindFramebuffer.md) | 公开方法，详见头文件声明。 |
| [UnbindFramebuffer](UnbindFramebuffer.md) | 公开方法，详见头文件声明。 | - `Clear*()` 系列函数会直接修改当前 FBO 绑定状态，不会恢复之前的 framebuffer。
- `IsValid()` 只检查 FBO id 是否非零，不会再次验证完整性。
- 创建失败时返回 `false`，但由调用方或析构来最终清理对象。
## 重点方法
- [Initialize](Initialize.md)
- [Bind](Bind.md)
- [ClearColor](ClearColor.md)
- [ClearDepthStencil](ClearDepthStencil.md)
- [GetFramebuffer](GetFramebuffer.md)
## 相关文档 ## 相关文档
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 - [OpenGL](../OpenGL.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Shutdown.md
View File

@@ -1,30 +1,18 @@
# OpenGLFramebuffer::Shutdown # OpenGLFramebuffer::Shutdown
关闭并清理内部状态。
```cpp ```cpp
void Shutdown() override; void Shutdown() override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 删除内部 framebuffer object 并重置尺寸状态。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 如果 `m_framebuffer != 0`，调用 `glDeleteFramebuffers()`。
- 把宽高重置为 `0`，sample 数重置为 `1`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::Shutdown(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [Destructor](Destructor.md)
- [返回模块目录](../OpenGL.md)

23
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/Unbind.md
View File

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

23
docs/api/XCEngine/RHI/OpenGL/OpenGLFramebuffer/UnbindFramebuffer.md
View File

@@ -1,30 +1,17 @@
# OpenGLFramebuffer::UnbindFramebuffer # OpenGLFramebuffer::UnbindFramebuffer
公开方法，详见头文件声明。
```cpp ```cpp
static void UnbindFramebuffer(); static void UnbindFramebuffer();
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`，当前页面用于固定 `OpenGLFramebuffer` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 静态辅助函数，把 `GL_FRAMEBUFFER` 解绑回默认 framebuffer。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLFramebuffer.h>
void Example() {
XCEngine::RHI::OpenGLFramebuffer object;
// 根据上下文补齐参数后调用 OpenGLFramebuffer::UnbindFramebuffer(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLFramebuffer.md) - [BindFramebuffer](BindFramebuffer.md)
- [返回模块目录](../OpenGL.md)

2
docs/api/_meta/rebuild-status.md
View File

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