docs(api): expand OpenGL view and D3D12 texture docs
This commit is contained in:
@@ -1,28 +1,28 @@
|
||||
# D3D12Texture::D3D12Texture()
|
||||
|
||||
构造对象。
|
||||
# D3D12Texture::D3D12Texture
|
||||
|
||||
```cpp
|
||||
D3D12Texture();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
构造一个空的 D3D12 纹理对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 构造函数本身没有显式逻辑。
|
||||
- 依赖类内默认值完成初始化:
|
||||
- `m_state = ResourceStates::Common`
|
||||
- `m_format = Format::Unknown`
|
||||
- `m_textureType = TextureType::Texture2D`
|
||||
- `m_name` 为空字符串
|
||||
- `m_ownsResource = false`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
}
|
||||
```
|
||||
- 构造后必须调用某个初始化函数，或者通过 `D3D12Device::CreateTexture()` 获取已初始化实例。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [D3D12Texture](D3D12Texture.md)
|
||||
|
||||
@@ -6,50 +6,85 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/D3D12/D3D12Texture.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Texture` public API。
|
||||
**描述**: D3D12 后端的纹理资源封装，持有 `ID3D12Resource` 并附带一层引擎侧格式、类型和状态元数据。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`D3D12Texture.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`D3D12Texture` 是 `XCEngine` 在 D3D12 后端中对纹理资源的基础封装。它承担两层职责:
|
||||
|
||||
## 声明概览
|
||||
- 管理一个 `ID3D12Resource`
|
||||
- 维护 RHI 层需要的 `Format`、`TextureType`、`ResourceStates`、名称和拥有权标记
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `D3D12Texture` | `class` | 继承自 `RHITexture` 的公开声明。 |
|
||||
这类封装在商业级引擎里很常见，因为上层系统需要统一的纹理抽象，而 D3D12 原生资源对象本身并不会替你维护这些跨模块元数据。
|
||||
|
||||
## 公共方法
|
||||
## 设计定位
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [D3D12Texture()](Constructor.md) | 构造对象。 |
|
||||
| [~D3D12Texture()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [Initialize](Initialize.md) | 初始化内部状态。 |
|
||||
| [InitializeFromExisting](InitializeFromExisting.md) | 初始化内部状态。 |
|
||||
| [InitializeFromData](InitializeFromData.md) | 初始化内部状态。 |
|
||||
| [InitializeDepthStencil](InitializeDepthStencil.md) | 初始化内部状态。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [GetResource](GetResource.md) | 获取相关状态或对象。 |
|
||||
| [GetDesc](GetDesc.md) | 获取相关状态或对象。 |
|
||||
| [GetWidth](GetWidth.md) | 获取相关状态或对象。 |
|
||||
| [GetHeight](GetHeight.md) | 获取相关状态或对象。 |
|
||||
| [GetDepth](GetDepth.md) | 获取相关状态或对象。 |
|
||||
| [GetMipLevels](GetMipLevels.md) | 获取相关状态或对象。 |
|
||||
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
|
||||
| [GetState](GetState.md) | 获取相关状态或对象。 |
|
||||
| [SetState](SetState.md) | 设置相关状态或配置。 |
|
||||
| [GetGPUAddress](GetGPUAddress.md) | 获取相关状态或对象。 |
|
||||
| [GetSize](GetSize.md) | 获取相关状态或对象。 |
|
||||
| [GetName](GetName.md) | 获取相关状态或对象。 |
|
||||
| [SetName](SetName.md) | 设置相关状态或配置。 |
|
||||
| [GetArraySize](GetArraySize.md) | 获取相关状态或对象。 |
|
||||
| [GetFormat](GetFormat.md) | 获取相关状态或对象。 |
|
||||
| [GetTextureType](GetTextureType.md) | 获取相关状态或对象。 |
|
||||
| [SetFormat](SetFormat.md) | 设置相关状态或配置。 |
|
||||
| [SetTextureType](SetTextureType.md) | 设置相关状态或配置。 |
|
||||
| [OwnsResource](OwnsResource.md) | 公开方法，详见头文件声明。 |
|
||||
`D3D12Texture` 不是一个“自动把所有状态都维护正确”的智能对象。当前实现更接近:
|
||||
|
||||
- 一个资源句柄封装器
|
||||
- 加上一些便于 RHI 使用的缓存字段
|
||||
|
||||
因此你需要分清两件事:
|
||||
|
||||
- 资源对象真正的 D3D12 创建参数是什么
|
||||
- 引擎侧 `m_state` / `m_format` / `m_textureType` 当前是否已经同步更新
|
||||
|
||||
这也是本页重点要讲清楚的地方。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- 构造后为空对象。
|
||||
- 可以通过以下路径获得资源:
|
||||
- [Initialize](Initialize.md) 创建默认堆纹理
|
||||
- [InitializeFromExisting](InitializeFromExisting.md) 包装已有资源
|
||||
- [InitializeFromData](InitializeFromData.md) 创建 2D 纹理并上传初始数据
|
||||
- [InitializeDepthStencil](InitializeDepthStencil.md) 创建深度纹理
|
||||
- [Shutdown](Shutdown.md) 会 `Reset()` 内部 `ComPtr`，并复位大部分元数据。
|
||||
- 析构时自动调用 `Shutdown()`。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 当前实现没有锁。
|
||||
- D3D12 资源对象本身支持跨线程引用，但该封装里的引擎侧元数据不是并发安全接口；通常仍应在资源创建/管理线程中维护。
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
- [Initialize](Initialize.md) 会创建 committed resource，但不会把 `m_state` 更新为传入的 `initialState`。
|
||||
- [InitializeDepthStencil](InitializeDepthStencil.md) 也会创建处于 `D3D12_RESOURCE_STATE_DEPTH_WRITE` 的资源，但不会同步修改 `m_state`。
|
||||
- `D3D12Device::CreateTexture()` 会在某些路径上补做 `SetFormat()`、`SetTextureType()`、`SetState()`，所以工厂路径比手工直接调初始化函数更完整。
|
||||
- [InitializeFromExisting](InitializeFromExisting.md) 即使传入 `nullptr` 也返回 `true`。
|
||||
- [OwnsResource](OwnsResource.md) 当前只是标记，不会改变 `Shutdown()` 的实际释放行为。
|
||||
- [SetName](SetName.md) 只设置引擎侧字符串，不会调用 `ID3D12Object::SetName()`。
|
||||
|
||||
## 为什么这样设计
|
||||
|
||||
这种实现很像很多引擎早期或中期阶段的 D3D12 资源层:
|
||||
|
||||
- 先保证资源能被统一创建和访问
|
||||
- 再逐步把状态跟踪、调试命名、子资源语义等能力补齐
|
||||
|
||||
它的好处是实现简单、上层可用。
|
||||
它的代价是文档必须把“哪些字段只是缓存、哪些行为依赖外部调用者补齐”写得非常明确，否则调用方很容易误判资源状态。
|
||||
|
||||
## 当前限制
|
||||
|
||||
- `GetDesc()` 和 `GetGPUAddress()` 没有空指针保护。
|
||||
- `GetSize()` 只是近似值，不是显存占用。
|
||||
- `GetDepth()` 与 [GetArraySize](GetArraySize.md) 都读取 `DepthOrArraySize`，语义上需要由调用方自己区分“深度纹理”还是“数组纹理”。
|
||||
- `OwnsResource` 不控制 `Shutdown()` 是否释放 `ComPtr`。
|
||||
- `SetName()` 不会把名称写入 D3D12 调试层对象。
|
||||
|
||||
## 关键方法
|
||||
|
||||
- [Initialize](Initialize.md)
|
||||
- [InitializeFromData](InitializeFromData.md)
|
||||
- [InitializeDepthStencil](InitializeDepthStencil.md)
|
||||
- [InitializeFromExisting](InitializeFromExisting.md)
|
||||
- [SetState](SetState.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
|
||||
- [API 总索引](../../../../main.md) - 返回顶层索引
|
||||
- [D3D12](../D3D12.md)
|
||||
- [D3D12Device](../D3D12Device/D3D12Device.md)
|
||||
- [D3D12ResourceView](../D3D12ResourceView/D3D12ResourceView.md)
|
||||
|
||||
@@ -1,29 +1,19 @@
|
||||
# D3D12Texture::~D3D12Texture()
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
# D3D12Texture::~D3D12Texture
|
||||
|
||||
```cpp
|
||||
~D3D12Texture() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
销毁对象并释放内部 `ID3D12Resource` 引用。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- 析构函数内部调用 [Shutdown](Shutdown.md)。
|
||||
- 不会根据 [OwnsResource](OwnsResource.md) 的值改变行为；只要 `m_resource` 非空，`ComPtr::Reset()` 就会释放当前引用。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [OwnsResource](OwnsResource.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# D3D12Texture::GetArraySize
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetArraySize() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回纹理数组大小。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_resource` 有效，直接返回 `GetDesc().DepthOrArraySize`。
|
||||
- 这意味着:
|
||||
- 对数组纹理，它表示数组层数
|
||||
- 对 3D 纹理，它实际上会返回深度
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetArraySize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 该接口没有额外区分资源维度，调用前应结合 [GetTextureType](GetTextureType.md) 判断语义。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetDepth](GetDepth.md)
|
||||
- [GetTextureType](GetTextureType.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# D3D12Texture::GetDepth
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetDepth() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回纹理深度值。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_resource` 有效，返回 `GetDesc().DepthOrArraySize`。
|
||||
- 对 3D 纹理这是“深度”。
|
||||
- 对 2D array / cube array 纹理，这个值实际上是数组层数。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetDepth(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 该方法沿用了统一 `RHITexture` 接口，但在 D3D12 里它与 [GetArraySize](GetArraySize.md) 共享同一底层字段。
|
||||
- 调用方必须结合纹理类型理解这个返回值。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetArraySize](GetArraySize.md)
|
||||
- [GetTextureType](GetTextureType.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# D3D12Texture::GetDesc
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
D3D12_RESOURCE_DESC GetDesc() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回底层 `ID3D12Resource` 的资源描述。
|
||||
|
||||
**返回：** `D3D12_RESOURCE_DESC` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接调用 `m_resource->GetDesc()`。
|
||||
- 这里没有空指针保护。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetDesc(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 仅在资源已成功初始化后调用。
|
||||
- 如果对象可能处于未初始化或 `Shutdown()` 后状态，应先通过 [GetResource](GetResource.md) 判空。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetResource](GetResource.md)
|
||||
- [GetSize](GetSize.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# D3D12Texture::GetFormat
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
Format GetFormat() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该纹理的引擎侧格式。
|
||||
|
||||
**返回：** `Format` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_format != Format::Unknown`，优先返回缓存值。
|
||||
- 否则如果 `m_resource` 有效，动态从 `GetDesc().Format` 转换得到。
|
||||
- 两者都不可用时返回 `Format::Unknown`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetFormat(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这解释了为什么工厂路径常常在创建完成后还会显式调用 [SetFormat](SetFormat.md): 它希望引擎侧元数据保持明确，不完全依赖运行时推导。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [SetFormat](SetFormat.md)
|
||||
- [InitializeFromExisting](InitializeFromExisting.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# D3D12Texture::GetGPUAddress
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint64_t GetGPUAddress() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回底层资源的 GPU 虚拟地址。
|
||||
|
||||
**返回：** `uint64_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接调用 `m_resource->GetGPUVirtualAddress()`。
|
||||
- 这里没有空指针保护。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetGPUAddress(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 对大多数纹理资源来说，这个值通常没有 buffer 那样稳定明确的使用场景；它只是原样暴露底层接口结果。
|
||||
- 使用前必须确保资源已初始化。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetResource](GetResource.md)
|
||||
- [GetDesc](GetDesc.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# D3D12Texture::GetHeight
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetHeight() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回纹理高度。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetHeight(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果 `m_resource` 有效，返回 `GetDesc().Height`。
|
||||
- 否则返回 `0`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetWidth](GetWidth.md)
|
||||
- [GetDesc](GetDesc.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# D3D12Texture::GetMipLevels
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetMipLevels() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回纹理的 mip 级别数量。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetMipLevels(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果 `m_resource` 有效，返回 `GetDesc().MipLevels`。
|
||||
- 否则返回 `0`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [InitializeFromData](InitializeFromData.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# D3D12Texture::GetName
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const std::string& GetName() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该纹理保存的引擎侧名称。
|
||||
|
||||
**返回：** `const std::string&` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回成员 `m_name`。
|
||||
- 名称来源于 [SetName](SetName.md)，不是从 `ID3D12Resource` 反查。
|
||||
- [Shutdown](Shutdown.md) 不会清空这个字段。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetName(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 该字段更适合引擎内部调试、日志和文档语义，不代表 D3D12 调试层一定能看到同名对象。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [SetName](SetName.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# D3D12Texture::GetNativeHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
void* GetNativeHandle() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回底层原生资源句柄。
|
||||
|
||||
**返回：** `void*` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_resource.Get()`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetNativeHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这是一个非常薄的包装，不做类型转换之外的额外处理。
|
||||
- 对 D3D12 调试或底层扩展代码来说，它是访问原生 `ID3D12Resource*` 的直接入口。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetResource](GetResource.md)
|
||||
- [InitializeFromExisting](InitializeFromExisting.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# D3D12Texture::GetResource
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
ID3D12Resource* GetResource() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回底层 `ID3D12Resource*`。
|
||||
|
||||
**返回：** `ID3D12Resource*` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetResource(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 资源已初始化时返回有效指针。
|
||||
- 否则返回 `nullptr`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetNativeHandle](GetNativeHandle.md)
|
||||
- [GetDesc](GetDesc.md)
|
||||
|
||||
@@ -1,30 +1,29 @@
|
||||
# D3D12Texture::GetSize
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
size_t GetSize() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回一个近似的资源尺寸值。
|
||||
|
||||
**返回：** `size_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接计算 `GetDesc().Width * GetDesc().Height * GetDesc().DepthOrArraySize`。
|
||||
- 不考虑:
|
||||
- 像素格式字节数
|
||||
- mip 链
|
||||
- 对齐填充
|
||||
- MSAA
|
||||
- 压缩格式
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetSize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这个接口不能当作显存占用统计。
|
||||
- 如果你需要准确显存大小，应另行基于 footprint 或分配器信息计算。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetDesc](GetDesc.md)
|
||||
- [InitializeFromData](InitializeFromData.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# D3D12Texture::GetState
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
ResourceStates GetState() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回引擎侧缓存的资源状态。
|
||||
|
||||
**返回：** `ResourceStates` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回成员 `m_state`。
|
||||
- 这个字段不是所有初始化函数都会自动维护。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetState(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 不要想当然地把 `GetState()` 等同于“底层 D3D12 资源当前真实状态”。
|
||||
- 在手工初始化资源后，通常需要结合 [SetState](SetState.md) 或设备工厂路径显式同步。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [SetState](SetState.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# D3D12Texture::GetTextureType
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
TextureType GetTextureType() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回纹理类型。
|
||||
|
||||
**返回：** `TextureType` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetTextureType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 直接返回缓存的 `m_textureType`。
|
||||
- 该字段可能来自初始化函数的资源维度推导，也可能由工厂路径通过 [SetTextureType](SetTextureType.md) 手工覆盖。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [SetTextureType](SetTextureType.md)
|
||||
- [GetArraySize](GetArraySize.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# D3D12Texture::GetWidth
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetWidth() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回纹理宽度。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::GetWidth(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果 `m_resource` 有效，返回 `GetDesc().Width`。
|
||||
- 否则返回 `0`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetHeight](GetHeight.md)
|
||||
- [GetDesc](GetDesc.md)
|
||||
|
||||
@@ -1,33 +1,42 @@
|
||||
# D3D12Texture::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool Initialize(ID3D12Device* device, const D3D12_RESOURCE_DESC& desc, D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON);
|
||||
bool Initialize(
|
||||
ID3D12Device* device,
|
||||
const D3D12_RESOURCE_DESC& desc,
|
||||
D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `device` - 参数语义详见头文件声明。
|
||||
- `desc` - 参数语义详见头文件声明。
|
||||
- `initialState` - 参数语义详见头文件声明。
|
||||
创建一个默认堆 committed texture 资源。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 前置条件
|
||||
|
||||
**示例：**
|
||||
- `device` 必须有效。
|
||||
- `desc` 必须描述一个合法的纹理资源。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::Initialize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `CreateCommittedResource()` 成功时返回 `true`。
|
||||
- 失败时返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 使用 `D3D12_HEAP_TYPE_DEFAULT` 创建 committed resource。
|
||||
- `pOptimizedClearValue` 当前固定为 `nullptr`。
|
||||
- 创建成功后:
|
||||
- 从 `desc.Format` 推导并缓存 `m_format`
|
||||
- 从 `desc.Dimension` 推导并缓存 `m_textureType`
|
||||
- 设置 `m_ownsResource = true`
|
||||
- 不会把 `m_state` 更新为传入的 `initialState`。
|
||||
|
||||
## 设计说明
|
||||
|
||||
- 当前实现把“真实创建状态”和“引擎侧状态缓存”分开了。
|
||||
- 因此如果你直接调用这个接口而不是通过设备工厂，后续可能还需要显式 [SetState](SetState.md)。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [SetState](SetState.md)
|
||||
- [../D3D12Device/CreateTexture.md](../D3D12Device/CreateTexture.md)
|
||||
|
||||
@@ -1,34 +1,41 @@
|
||||
# D3D12Texture::InitializeDepthStencil
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeDepthStencil(ID3D12Device* device, uint32_t width, uint32_t height, DXGI_FORMAT format = DXGI_FORMAT_D24_UNORM_S8_UINT);
|
||||
bool InitializeDepthStencil(
|
||||
ID3D12Device* device,
|
||||
uint32_t width,
|
||||
uint32_t height,
|
||||
DXGI_FORMAT format = DXGI_FORMAT_D24_UNORM_S8_UINT);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `device` - 参数语义详见头文件声明。
|
||||
- `width` - 参数语义详见头文件声明。
|
||||
- `height` - 参数语义详见头文件声明。
|
||||
- `format` - 参数语义详见头文件声明。
|
||||
创建一个用于深度/模板用途的 2D 纹理。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 资源创建成功时返回 `true`。
|
||||
- 失败时返回 `false`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::InitializeDepthStencil(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 构造一个 `D3D12_RESOURCE_FLAG_ALLOW_DEPTH_STENCIL` 的 2D 纹理描述。
|
||||
- 使用默认堆创建资源。
|
||||
- 传入优化 clear value:
|
||||
- `Depth = 1.0f`
|
||||
- `Stencil = 0`
|
||||
- 真实初始状态是 `D3D12_RESOURCE_STATE_DEPTH_WRITE`。
|
||||
- 成功后仅设置:
|
||||
- `m_format`
|
||||
- `m_textureType = TextureType::Texture2D`
|
||||
- `m_ownsResource = true`
|
||||
|
||||
## 重要限制
|
||||
|
||||
- 该函数不会把 `m_state` 同步为 `ResourceStates::DepthWrite`。
|
||||
- 设备工厂路径会在创建成功后额外调用 `SetState(ResourceStates::DepthWrite)`；如果你直接使用本函数，需要自己补这一步。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetState](GetState.md)
|
||||
- [SetState](SetState.md)
|
||||
|
||||
@@ -1,38 +1,50 @@
|
||||
# D3D12Texture::InitializeFromData
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeFromData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, const void* pixelData, uint32_t width, uint32_t height, DXGI_FORMAT format, uint32_t rowPitch = 0, ComPtr<ID3D12Resource>* uploadBuffer = nullptr);
|
||||
bool InitializeFromData(
|
||||
ID3D12Device* device,
|
||||
ID3D12GraphicsCommandList* commandList,
|
||||
const void* pixelData,
|
||||
uint32_t width,
|
||||
uint32_t height,
|
||||
DXGI_FORMAT format,
|
||||
uint32_t rowPitch = 0,
|
||||
ComPtr<ID3D12Resource>* uploadBuffer = nullptr);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `device` - 参数语义详见头文件声明。
|
||||
- `commandList` - 参数语义详见头文件声明。
|
||||
- `pixelData` - 参数语义详见头文件声明。
|
||||
- `width` - 参数语义详见头文件声明。
|
||||
- `height` - 参数语义详见头文件声明。
|
||||
- `format` - 参数语义详见头文件声明。
|
||||
- `rowPitch` - 参数语义详见头文件声明。
|
||||
- `uploadBuffer` - 参数语义详见头文件声明。
|
||||
创建一个带初始像素数据的 2D 纹理，并录制上传拷贝命令。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 前置条件
|
||||
|
||||
**示例：**
|
||||
- `device`、`commandList` 和 `pixelData` 必须有效。
|
||||
- 当前实现只覆盖 2D、单 mip、单数组层纹理上传。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::InitializeFromData(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 创建资源并成功写入上传命令时返回 `true`。
|
||||
- 任一步骤失败时返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 创建一个默认堆 2D 纹理，初始状态固定为 `D3D12_RESOURCE_STATE_COPY_DEST`。
|
||||
- 计算 copyable footprint。
|
||||
- 创建一个 upload heap buffer。
|
||||
- 逐行把 `pixelData` 拷贝到上传缓冲:
|
||||
- `sourceRowPitch` 使用传入 `rowPitch`
|
||||
- 如果 `rowPitch == 0`，退回到 footprint 的 `rowSizeInBytes`
|
||||
- 录制 `CopyTextureRegion()`。
|
||||
- 录制从 `COPY_DEST` 到 `PIXEL_SHADER_RESOURCE` 的 transition barrier。
|
||||
- 把 `m_state` 设置为 `ResourceStates::PixelShaderResource`。
|
||||
- 如果提供 `uploadBuffer` 输出参数，返回上传缓冲资源给调用方。
|
||||
|
||||
## 重要限制
|
||||
|
||||
- 该函数只负责“录制命令”，不负责关闭命令列表、提交队列或等待完成。
|
||||
- 当前实现固定创建 `MipLevels = 1`、`DepthOrArraySize = 1` 的 2D 纹理。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [../D3D12Device/CreateTexture.md](../D3D12Device/CreateTexture.md)
|
||||
|
||||
@@ -1,32 +1,39 @@
|
||||
# D3D12Texture::InitializeFromExisting
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeFromExisting(ID3D12Resource* resource, bool ownsResource = false);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `resource` - 参数语义详见头文件声明。
|
||||
- `ownsResource` - 参数语义详见头文件声明。
|
||||
用一个已经存在的 `ID3D12Resource` 初始化当前对象。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 参数说明
|
||||
|
||||
**示例：**
|
||||
- `resource`: 需要包装的已有资源。
|
||||
- `ownsResource`: 引擎侧拥有权标记。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::InitializeFromExisting(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 当前实现始终返回 `true`，即使 `resource == nullptr`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 把 `resource` 赋给内部 `ComPtr`。
|
||||
- 如果资源非空，则根据 `GetDesc()` 推导 `m_format` 和 `m_textureType`。
|
||||
- 无论资源是否为空，都会保存 `m_ownsResource = ownsResource`。
|
||||
- 不会修改 `m_state`。
|
||||
|
||||
## 重要限制
|
||||
|
||||
- 传入空资源不会报错，这意味着调用方必须自行验证结果是否可用。
|
||||
- `ownsResource` 当前只是一个标记，不会阻止 [Shutdown](Shutdown.md) 调用 `ComPtr::Reset()`。
|
||||
|
||||
## 典型场景
|
||||
|
||||
- swap chain back buffer 包装就是这条路径，代码里会以 `ownsResource = false` 的方式接入已有资源。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [OwnsResource](OwnsResource.md)
|
||||
- [GetResource](GetResource.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# D3D12Texture::OwnsResource
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
|
||||
```cpp
|
||||
bool OwnsResource() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前对象记录的拥有权标记。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回成员 `m_ownsResource`。
|
||||
- 该标记由初始化函数写入，但当前不会改变 [Shutdown](Shutdown.md) 或析构的实际释放策略。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::OwnsResource(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 把它理解为“引擎层的语义标签”更准确，而不是严格的 RAII 控制位。
|
||||
- 如果你需要真正区分谁应该释放底层资源，当前代码还需要更明确的生命周期约束。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [InitializeFromExisting](InitializeFromExisting.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,31 +1,24 @@
|
||||
# D3D12Texture::SetFormat
|
||||
|
||||
设置相关状态或配置。
|
||||
|
||||
```cpp
|
||||
void SetFormat(Format format);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `format` - 参数语义详见头文件声明。
|
||||
手工覆盖该纹理的引擎侧格式缓存。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接把 `m_format` 设为传入值。
|
||||
- 不修改底层 `ID3D12Resource` 的真实格式。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::SetFormat(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 该接口主要用于设备工厂在创建完成后把 RHI 层的逻辑格式同步到对象。
|
||||
- 如果传入值与底层资源真实格式不一致，后续文档、调试和 view 创建逻辑都可能被误导。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetFormat](GetFormat.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,31 +1,23 @@
|
||||
# D3D12Texture::SetName
|
||||
|
||||
设置相关状态或配置。
|
||||
|
||||
```cpp
|
||||
void SetName(const std::string& name) override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `name` - 参数语义详见头文件声明。
|
||||
设置该纹理的引擎侧名称。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 只把 `name` 保存到 `m_name`。
|
||||
- 不会调用 `ID3D12Object::SetName()`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::SetName(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果你希望在 PIX、D3D12 debug layer 或图形调试器里看到资源名称，当前实现还不够，需要额外把名字写入原生对象。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetName](GetName.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,31 +1,24 @@
|
||||
# D3D12Texture::SetState
|
||||
|
||||
设置相关状态或配置。
|
||||
|
||||
```cpp
|
||||
void SetState(ResourceStates state) override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `state` - 参数语义详见头文件声明。
|
||||
手工更新引擎侧缓存的资源状态。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接把 `m_state` 设为传入值。
|
||||
- 不会自动向命令列表插入 barrier，也不会验证底层资源是否真的处于该状态。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::SetState(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这是一个“状态缓存同步接口”，不是 barrier 接口。
|
||||
- 调用方应确保真实的 D3D12 资源转换已经发生，否则 `GetState()` 只会成为错误的本地记录。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetState](GetState.md)
|
||||
- [InitializeDepthStencil](InitializeDepthStencil.md)
|
||||
|
||||
@@ -1,31 +1,24 @@
|
||||
# D3D12Texture::SetTextureType
|
||||
|
||||
设置相关状态或配置。
|
||||
|
||||
```cpp
|
||||
void SetTextureType(TextureType type);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `type` - 参数语义详见头文件声明。
|
||||
手工覆盖纹理类型缓存。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接把 `m_textureType` 设为传入值。
|
||||
- 不会修改底层资源描述。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::SetTextureType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 该接口通常由设备工厂在完成资源创建后补写逻辑类型。
|
||||
- 如果传入值与底层 `D3D12_RESOURCE_DESC::Dimension` 不一致，后续解释 `DepthOrArraySize` 等字段时会产生歧义。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetTextureType](GetTextureType.md)
|
||||
- [GetDepth](GetDepth.md)
|
||||
|
||||
@@ -1,30 +1,28 @@
|
||||
# D3D12Texture::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
|
||||
```cpp
|
||||
void Shutdown() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Texture.h`，当前页面用于固定 `D3D12Texture` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
释放内部资源引用，并把对象恢复到基础空状态。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 调用 `m_resource.Reset()`。
|
||||
- 把 `m_state` 设回 `ResourceStates::Common`。
|
||||
- 把 `m_format` 设回 `Format::Unknown`。
|
||||
- 把 `m_textureType` 设回 `TextureType::Texture2D`。
|
||||
- 把 `m_ownsResource` 设回 `false`。
|
||||
- 不会清空 `m_name`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Texture object;
|
||||
// 根据上下文补齐参数后调用 D3D12Texture::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 如果你依赖 `GetName()` 做日志或调试，注意 `Shutdown()` 后名称仍然保留。
|
||||
- 即使 `OwnsResource()` 先前为 `false`，这里仍然会释放当前 `ComPtr` 引用。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Texture.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [OwnsResource](OwnsResource.md)
|
||||
- [GetName](GetName.md)
|
||||
|
||||
@@ -1,28 +1,28 @@
|
||||
# OpenGLRenderPass::OpenGLRenderPass()
|
||||
|
||||
构造对象。
|
||||
# OpenGLRenderPass::OpenGLRenderPass
|
||||
|
||||
```cpp
|
||||
OpenGLRenderPass();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
构造一个空的 `OpenGLRenderPass` 对象，不分配任何 OpenGL 驱动资源。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 该构造函数本身没有显式逻辑。
|
||||
- 成员采用类内默认值初始化:
|
||||
- `m_colorAttachmentCount = 0`
|
||||
- `m_colorAttachments` 为空
|
||||
- `m_hasDepthStencil = false`
|
||||
- 真实的附件描述复制发生在 [Initialize](Initialize.md)，而不是构造阶段。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderPass object;
|
||||
}
|
||||
```
|
||||
- 构造后应尽快调用 [Initialize](Initialize.md) 写入附件元数据。
|
||||
- 如果只是通过 `RHIDevice::CreateRenderPass()` 获取实例，通常不需要直接关心该构造函数。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderPass.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [OpenGLRenderPass](OpenGLRenderPass.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,29 +1,24 @@
|
||||
# OpenGLRenderPass::~OpenGLRenderPass()
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
# OpenGLRenderPass::~OpenGLRenderPass
|
||||
|
||||
```cpp
|
||||
~OpenGLRenderPass() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
销毁 `OpenGLRenderPass`，并释放其内部保存的附件描述数据。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 析构函数唯一动作是调用 [Shutdown](Shutdown.md)。
|
||||
- 不会删除任何 OpenGL 原生对象，因为该类型当前不持有 FBO、render pass 或其他驱动句柄。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderPass object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- 如果对象已经显式调用过 `Shutdown()`，析构时再次调用也是安全的。
|
||||
- 该析构主要负责清空 CPU 侧元数据，不承担 GPU 资源释放职责。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderPass.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [OpenGLRenderPass](OpenGLRenderPass.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,30 +1,29 @@
|
||||
# OpenGLRenderPass::GetColorAttachmentCount
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetColorAttachmentCount() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前 render pass 记录的颜色附件数量。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 返回 `Initialize()` 时写入的 `colorAttachmentCount`。
|
||||
- 在 [Shutdown](Shutdown.md) 之后返回 `0`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderPass object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderPass::GetColorAttachmentCount(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这是一个纯粹的轻量 getter，直接返回 `m_colorAttachmentCount`。
|
||||
- 该值表示“元数据中声明的颜色附件数”，不是当前帧实际绑定到 OpenGL FBO 的附件数。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 在 OpenGL 后端中，这个数量主要被命令列表用于解释 clear / load 语义。
|
||||
- 如果需要知道真正的附件绑定结果，应查看 framebuffer 或命令列表的绑定流程，而不是仅依赖该值。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderPass.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetColorAttachments](GetColorAttachments.md)
|
||||
|
||||
@@ -1,30 +1,29 @@
|
||||
# OpenGLRenderPass::GetColorAttachments
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const AttachmentDesc* GetColorAttachments() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回内部保存的颜色附件描述数组首地址。
|
||||
|
||||
**返回：** `const AttachmentDesc*` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 返回 `std::vector<AttachmentDesc>` 内部缓冲区的起始指针。
|
||||
- 当颜色附件数量为 `0` 时，返回值没有实际使用意义，应结合 [GetColorAttachmentCount](GetColorAttachmentCount.md) 一起判断。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderPass object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderPass::GetColorAttachments(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `Initialize()` 会把输入数组逐项复制到 `m_colorAttachments`，因此返回的是内部副本，不依赖外部数组生命周期。
|
||||
- 该数组仅保存 `AttachmentDesc` 元数据，不代表 OpenGL 已经创建了同名原生对象。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 调用方应在对象生命周期内使用该指针，不要在 `Shutdown()` 或析构后继续缓存。
|
||||
- 在 OpenGL 后端里，这些描述主要用于 [OpenGLCommandList::BeginRenderPass](../OpenGLCommandList/BeginRenderPass.md) 决定是否清屏。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderPass.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetColorAttachmentCount](GetColorAttachmentCount.md)
|
||||
- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
|
||||
|
||||
@@ -1,30 +1,30 @@
|
||||
# OpenGLRenderPass::GetDepthStencilAttachment
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const AttachmentDesc* GetDepthStencilAttachment() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回深度/模板附件的描述信息。
|
||||
|
||||
**返回：** `const AttachmentDesc*` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 如果初始化时提供了 `depthStencilAttachment`，返回内部保存对象的地址。
|
||||
- 如果没有深度/模板附件，返回 `nullptr`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderPass object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderPass::GetDepthStencilAttachment(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 返回值受 `m_hasDepthStencil` 控制，而不是根据格式字段动态推断。
|
||||
- `Initialize()` 会复制一份 `AttachmentDesc`，因此不依赖外部描述结构体的存活时间。
|
||||
- `Shutdown()` 会把 `m_hasDepthStencil` 复位为 `false`，之后该方法重新返回 `nullptr`。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 使用前应始终判空。
|
||||
- 当前 OpenGL 后端主要把这里的 `loadOp` / `stencilLoadOp` 用于 `BeginRenderPass()` 的清除逻辑。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderPass.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetNativeHandle](GetNativeHandle.md)
|
||||
|
||||
@@ -1,30 +1,28 @@
|
||||
# OpenGLRenderPass::GetNativeHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
void* GetNativeHandle() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
暴露底层原生句柄。
|
||||
|
||||
**返回：** `void*` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 当前实现始终返回 `nullptr`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderPass object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderPass::GetNativeHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这不是延迟创建接口，也不会尝试生成任何 OpenGL 对象。
|
||||
- 该返回结果与测试保持一致: `tests/RHI/unit/test_render_pass.cpp` 明确校验 `GetNativeHandle() == nullptr`。
|
||||
|
||||
## 设计说明
|
||||
|
||||
- 这恰好体现了当前 OpenGL 后端的真实情况: `OpenGLRenderPass` 只是附件元数据容器，不对应独立的 OpenGL driver object。
|
||||
- 真正的绑定和清除逻辑发生在命令列表与 framebuffer 协作阶段，而不是在 render pass 本身。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderPass.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [OpenGLRenderPass](OpenGLRenderPass.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,33 +1,53 @@
|
||||
# OpenGLRenderPass::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool Initialize(uint32_t colorAttachmentCount, const AttachmentDesc* colorAttachments, const AttachmentDesc* depthStencilAttachment) override;
|
||||
bool Initialize(
|
||||
uint32_t colorAttachmentCount,
|
||||
const AttachmentDesc* colorAttachments,
|
||||
const AttachmentDesc* depthStencilAttachment) override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `colorAttachmentCount` - 参数语义详见头文件声明。
|
||||
- `colorAttachments` - 参数语义详见头文件声明。
|
||||
- `depthStencilAttachment` - 参数语义详见头文件声明。
|
||||
把 RHI 层传入的附件描述复制到 `OpenGLRenderPass` 内部，供后续命令列表解释 load/store 语义。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 前置条件
|
||||
|
||||
**示例：**
|
||||
- `colorAttachmentCount > 0` 时，`colorAttachments` 应指向至少同样长度的数组。
|
||||
- 该接口不做 OpenGL 上下文校验，因为当前实现不直接调用任何 GL API。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
|
||||
## 参数说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderPass object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderPass::Initialize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `colorAttachmentCount`: 颜色附件数量。
|
||||
- `colorAttachments`: 颜色附件描述数组。
|
||||
- `depthStencilAttachment`: 可选的深度/模板附件描述。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 当前实现恒定返回 `true`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 把 `colorAttachmentCount` 保存到 `m_colorAttachmentCount`。
|
||||
- 调整 `m_colorAttachments` 大小，并逐项复制传入的颜色附件描述。
|
||||
- 如果 `depthStencilAttachment != nullptr`:
|
||||
- 设置 `m_hasDepthStencil = true`
|
||||
- 复制一份 `AttachmentDesc` 到 `m_depthStencilAttachment`
|
||||
- 否则仅把 `m_hasDepthStencil` 设为 `false`。
|
||||
- 不创建任何 OpenGL render pass 或 framebuffer 句柄。
|
||||
|
||||
## 设计说明
|
||||
|
||||
- 这和 Vulkan/D3D12 中“render pass 可能对应更强的后端对象”不同。
|
||||
- 在当前 OpenGL 后端中，render pass 的职责更接近“本次渲染阶段的附件契约说明书”，命令列表只用它来判断哪些附件需要清除。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 不要把 `true` 解释为“GPU 资源创建成功”；它仅表示元数据复制完成。
|
||||
- 如果你需要真正的附件绑定结果，应关注 framebuffer 创建和 `BeginRenderPass()` 的运行时行为。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderPass.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [OpenGLRenderPass](OpenGLRenderPass.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [../OpenGLCommandList/BeginRenderPass.md](../OpenGLCommandList/BeginRenderPass.md)
|
||||
|
||||
@@ -6,32 +6,73 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLRenderPass` public API。
|
||||
**描述**: OpenGL 后端的 render pass 元数据对象，用来保存附件描述并驱动命令列表的清除行为。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`OpenGLRenderPass.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`OpenGLRenderPass` 的名字很容易让人联想到 Vulkan 或现代显式图形 API 中的“原生 render pass 对象”，但当前实现并不是这样。
|
||||
|
||||
## 声明概览
|
||||
在 `XCEngine` 的 OpenGL 后端里，这个类型更接近一份 CPU 侧描述数据:
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `OpenGLRenderPass` | `class` | 继承自 `RHIRenderPass` 的公开声明。 |
|
||||
- 记录颜色附件数量和对应的 `AttachmentDesc`
|
||||
- 可选地记录一个深度/模板附件描述
|
||||
- 在命令列表开始渲染阶段时，为 clear/load 逻辑提供依据
|
||||
|
||||
## 公共方法
|
||||
它本身不创建 OpenGL driver object，也不负责保存 framebuffer。
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [OpenGLRenderPass()](Constructor.md) | 构造对象。 |
|
||||
| [~OpenGLRenderPass()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [Initialize](Initialize.md) | 初始化内部状态。 |
|
||||
| [GetColorAttachmentCount](GetColorAttachmentCount.md) | 获取相关状态或对象。 |
|
||||
| [GetColorAttachments](GetColorAttachments.md) | 获取相关状态或对象。 |
|
||||
| [GetDepthStencilAttachment](GetDepthStencilAttachment.md) | 获取相关状态或对象。 |
|
||||
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
|
||||
## 为什么这样设计
|
||||
|
||||
这种做法是跨后端 RHI 很常见的折中方案:
|
||||
|
||||
- 在 Vulkan / D3D12 侧，render pass 往往有更强的显式契约意义。
|
||||
- 在 OpenGL 侧，很多行为最终还是通过“绑定 framebuffer 然后执行 clear / draw”来完成。
|
||||
- 因此引擎保留统一的 `RHIRenderPass` 抽象，但允许 OpenGL 后端把它退化为元数据容器。
|
||||
|
||||
这样做的好处是:
|
||||
|
||||
- 上层渲染代码仍然能保持一致的 `BeginRenderPass()` 调用序列。
|
||||
- 文档和接口可以保留“附件装载/清除策略”的设计概念。
|
||||
|
||||
代价是:
|
||||
|
||||
- `OpenGLRenderPass` 不能像 D3D12/Vulkan 那样被理解为强语义的后端对象。
|
||||
- `GetNativeHandle()` 没有可返回的原生句柄。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- 构造后对象为空，只保存默认状态。
|
||||
- 调用 [Initialize](Initialize.md) 后复制附件描述。
|
||||
- 调用 [Shutdown](Shutdown.md) 或析构后，内部数组和标志被清空。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 当前实现没有任何锁。
|
||||
- 应把它视为渲染设备初始化线程或渲染线程中的普通 RHI 对象，不应在多线程下并发初始化和销毁。
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
- 只保存 `AttachmentDesc` 副本，不创建原生对象。
|
||||
- [GetNativeHandle](GetNativeHandle.md) 始终返回 `nullptr`。
|
||||
- [OpenGLCommandList::BeginRenderPass](../OpenGLCommandList/BeginRenderPass.md) 会读取这些附件描述:
|
||||
- 对颜色附件执行 `glClearBufferfv(GL_COLOR, ...)`
|
||||
- 对深度附件执行 `glClearBufferfv(GL_DEPTH, ...)`
|
||||
- 对模板附件执行 `glClearBufferfv(GL_STENCIL, ...)`
|
||||
- `tests/RHI/unit/test_render_pass.cpp` 验证了附件计数、深度附件访问、`Shutdown()` 复位和空 native handle 等行为。
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 不保存 store-op 的完整后端语义；当前实现重点在 clear/load。
|
||||
- 不对应独立的 OpenGL 原生对象，因此无法像 Vulkan render pass 那样参与更细粒度的兼容性分析。
|
||||
|
||||
## 关键方法
|
||||
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetColorAttachments](GetColorAttachments.md)
|
||||
- [GetDepthStencilAttachment](GetDepthStencilAttachment.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
|
||||
- [API 总索引](../../../../main.md) - 返回顶层索引
|
||||
- [OpenGL](../OpenGL.md)
|
||||
- [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md)
|
||||
- [OpenGLCommandList::BeginRenderPass](../OpenGLCommandList/BeginRenderPass.md)
|
||||
|
||||
@@ -1,30 +1,26 @@
|
||||
# OpenGLRenderPass::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
|
||||
```cpp
|
||||
void Shutdown() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderPass.h`，当前页面用于固定 `OpenGLRenderPass` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
清空 `OpenGLRenderPass` 当前保存的附件元数据。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 清空 `m_colorAttachments`。
|
||||
- 把 `m_colorAttachmentCount` 设回 `0`。
|
||||
- 把 `m_hasDepthStencil` 设回 `false`。
|
||||
- 不会主动修改 `m_depthStencilAttachment` 的历史内容，但由于 `m_hasDepthStencil` 被清零，后续接口不会再把它暴露出去。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderPass.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderPass object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderPass::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 可以安全重复调用；测试中也覆盖了 double shutdown 的路径。
|
||||
- 调用后，之前通过 `GetColorAttachments()` 或 `GetDepthStencilAttachment()` 获取的指针都不应继续使用。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderPass.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [OpenGLRenderPass](OpenGLRenderPass.md)
|
||||
- [Destructor](Destructor.md)
|
||||
|
||||
@@ -1,46 +1,36 @@
|
||||
# OpenGLRenderTargetView::Bind
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
|
||||
该方法在 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
|
||||
|
||||
## 重载 1: 声明
|
||||
|
||||
```cpp
|
||||
void Bind(unsigned int slot = 0);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `slot` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
## 重载 2: 声明
|
||||
|
||||
```cpp
|
||||
void Bind(unsigned int count, const unsigned int* framebuffers, const int* drawBuffers);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `count` - 参数语义详见头文件声明。
|
||||
- `framebuffers` - 参数语义详见头文件声明。
|
||||
- `drawBuffers` - 参数语义详见头文件声明。
|
||||
## 作用
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
把一个或多个 framebuffer 绑定到当前 OpenGL 上下文。
|
||||
|
||||
**示例：**
|
||||
## 当前实现行为
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
### `Bind(unsigned int slot = 0)`
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::Bind(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 直接执行 `glBindFramebuffer(GL_FRAMEBUFFER, m_framebuffer)`。
|
||||
- `slot` 参数当前被忽略，只是为了维持接口形状。
|
||||
|
||||
### `Bind(unsigned int count, const unsigned int* framebuffers, const int* drawBuffers)`
|
||||
|
||||
- 当 `count == 1` 时，只绑定 `framebuffers[0]`。
|
||||
- 当 `count > 1` 时:
|
||||
- 先绑定默认 framebuffer `0`
|
||||
- 然后循环绑定每个 framebuffer
|
||||
- 每次调用 `glDrawBuffers(1, &drawBuffers[i])`
|
||||
- 这种“逐个绑定并切换 draw buffer”的行为更像旧式辅助函数，并不是现代 MRT 绑定的理想抽象。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 单目标渲染时优先使用无参版本，它的行为最直接。
|
||||
- 多渲染目标场景更推荐走 [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md) 或 [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md) 的新路径。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [OpenGLRenderTargetView](OpenGLRenderTargetView.md)
|
||||
- [Unbind](Unbind.md)
|
||||
|
||||
@@ -1,31 +1,27 @@
|
||||
# OpenGLRenderTargetView::BindFramebuffer
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
|
||||
```cpp
|
||||
static void BindFramebuffer(unsigned int framebuffer);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `framebuffer` - 参数语义详见头文件声明。
|
||||
静态绑定指定的 framebuffer。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 参数说明
|
||||
|
||||
**示例：**
|
||||
- `framebuffer`: 需要绑定的 OpenGL framebuffer id。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::BindFramebuffer(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 仅执行 `glBindFramebuffer(GL_FRAMEBUFFER, framebuffer)`。
|
||||
- 不校验 `framebuffer` 是否有效，也不保存之前的绑定状态。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 这是一个极薄的静态包装，适合在工具代码或测试代码中直接切换 FBO。
|
||||
- 如果你需要面向 RHI 抽象层的绑定流程，更推荐使用 [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md) 或命令列表接口。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [UnbindFramebuffer](UnbindFramebuffer.md)
|
||||
|
||||
@@ -1,52 +1,39 @@
|
||||
# OpenGLRenderTargetView::Clear
|
||||
|
||||
清空内部数据。
|
||||
|
||||
该方法在 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
|
||||
|
||||
## 重载 1: 声明
|
||||
|
||||
```cpp
|
||||
void Clear(float r, float g, float b, float a);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `r` - 参数语义详见头文件声明。
|
||||
- `g` - 参数语义详见头文件声明。
|
||||
- `b` - 参数语义详见头文件声明。
|
||||
- `a` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
## 重载 2: 声明
|
||||
|
||||
```cpp
|
||||
void Clear(float r, float g, float b, float a, float depth, uint8_t stencil);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `r` - 参数语义详见头文件声明。
|
||||
- `g` - 参数语义详见头文件声明。
|
||||
- `b` - 参数语义详见头文件声明。
|
||||
- `a` - 参数语义详见头文件声明。
|
||||
- `depth` - 参数语义详见头文件声明。
|
||||
- `stencil` - 参数语义详见头文件声明。
|
||||
## 作用
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
清除当前 `OpenGLRenderTargetView` 关联的 framebuffer。
|
||||
|
||||
**示例：**
|
||||
## 当前实现行为
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
### `Clear(float r, float g, float b, float a)`
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::Clear(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 绑定 `m_framebuffer`。
|
||||
- 调用 `glClearColor(r, g, b, a)`。
|
||||
- 调用 `glClear(GL_COLOR_BUFFER_BIT)`。
|
||||
|
||||
### `Clear(float r, float g, float b, float a, float depth, uint8_t stencil)`
|
||||
|
||||
- 绑定 `m_framebuffer`。
|
||||
- 依次设置颜色、深度和模板清除值。
|
||||
- 调用 `glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT)`。
|
||||
|
||||
## 重要限制
|
||||
|
||||
- 两个重载都不会恢复清除前的 framebuffer 绑定状态。
|
||||
- 该类型本身只附加颜色附件；如果 framebuffer 实际没有深度/模板附件，第二个重载里的深度/模板清除并不代表一定存在有效目标。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 在显式命令列表体系下，更推荐通过 render pass + framebuffer 的组合表达清除意图。
|
||||
- 如果直接调用该接口，调用方应自己管理前后绑定状态。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Bind](Bind.md)
|
||||
- [OpenGLRenderTargetView](OpenGLRenderTargetView.md)
|
||||
|
||||
@@ -1,28 +1,30 @@
|
||||
# OpenGLRenderTargetView::OpenGLRenderTargetView()
|
||||
|
||||
构造对象。
|
||||
# OpenGLRenderTargetView::OpenGLRenderTargetView
|
||||
|
||||
```cpp
|
||||
OpenGLRenderTargetView();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
构造一个空的 render target view 辅助对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 使用默认值初始化:
|
||||
- `m_texture = 0`
|
||||
- `m_framebuffer = 0`
|
||||
- `m_mipLevel = 0`
|
||||
- `m_width = 0`
|
||||
- `m_height = 0`
|
||||
- `m_type = RenderTargetType::Texture2D`
|
||||
- 不执行任何 OpenGL 调用。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
}
|
||||
```
|
||||
- 构造后应调用 [Initialize](Initialize.md) 或 [InitializeCubemap](InitializeCubemap.md)。
|
||||
- 不要把默认的 `m_width` / `m_height` 视为纹理真实尺寸，它们在当前实现中不会被后续初始化更新。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [OpenGLRenderTargetView](OpenGLRenderTargetView.md)
|
||||
|
||||
@@ -1,29 +1,24 @@
|
||||
# OpenGLRenderTargetView::~OpenGLRenderTargetView()
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
# OpenGLRenderTargetView::~OpenGLRenderTargetView
|
||||
|
||||
```cpp
|
||||
~OpenGLRenderTargetView();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
销毁对象并删除它创建的 framebuffer。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 析构函数内部调用 [Shutdown](Shutdown.md)。
|
||||
- 会删除 `m_framebuffer`，并在 `m_framebuffers` 非空时批量删除其中保存的 framebuffer id。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- 如果对象已经手动 `Shutdown()` 过，析构再次调用也是安全的。
|
||||
- 该析构不会删除关联的纹理对象，只删除本类型自己创建的 FBO。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [GetTexture](GetTexture.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# OpenGLRenderTargetView::GetFramebuffer
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
unsigned int GetFramebuffer() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该对象内部管理的 framebuffer id。
|
||||
|
||||
**返回：** `unsigned int` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 初始化成功后返回非零 FBO id。
|
||||
- 构造后、初始化失败后或 `Shutdown()` 之后返回 `0`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::GetFramebuffer(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这是直接返回成员变量的轻量 getter。
|
||||
- 返回的是该辅助类自己创建的独立 FBO，不是引擎新路径中 `OpenGLFramebuffer` 对象的句柄。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Bind](Bind.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# OpenGLRenderTargetView::GetHeight
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
int GetHeight() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回对象记录的高度值。
|
||||
|
||||
**返回：** `int` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 当前实现始终返回成员 `m_height`。
|
||||
- 但 `Initialize()` 和 `InitializeCubemap()` 都没有给 `m_height` 赋值，因此它通常保持构造时的 `0`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::GetHeight(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 不要依赖该方法获取真实纹理尺寸。
|
||||
- 如果你需要宽高，应直接查询创建该 view 的纹理对象，或使用更新后的 framebuffer / resource view 路径。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetWidth](GetWidth.md)
|
||||
- [OpenGLRenderTargetView](OpenGLRenderTargetView.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# OpenGLRenderTargetView::GetMipLevel
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
int GetMipLevel() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前绑定到该 RTV 的 mip 级别。
|
||||
|
||||
**返回：** `int` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 返回最近一次 `Initialize()` / `InitializeCubemap()` 保存到 `m_mipLevel` 的值。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::GetMipLevel(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这是直接返回成员变量的 getter。
|
||||
- 单元测试 `tests/RHI/OpenGL/unit/test_render_target_view.cpp` 会校验 2D 初始化后的 mip 值。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [InitializeCubemap](InitializeCubemap.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# OpenGLRenderTargetView::GetTexture
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
unsigned int GetTexture() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 当前关联的纹理 id。
|
||||
|
||||
**返回：** `unsigned int` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 返回 `m_texture`。
|
||||
- 在尚未初始化时通常为 `0`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::GetTexture(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 该值在 `Initialize()` / `InitializeCubemap()` 时写入。
|
||||
- 该接口只暴露原生纹理 id，不提供纹理对象本身的生命周期管理。
|
||||
- 单元测试会校验返回值与初始化时传入的纹理 id 一致。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetFramebuffer](GetFramebuffer.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# OpenGLRenderTargetView::GetWidth
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
int GetWidth() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回对象记录的宽度值。
|
||||
|
||||
**返回：** `int` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 当前实现始终返回成员 `m_width`。
|
||||
- 但 `Initialize()` 和 `InitializeCubemap()` 没有更新该成员，因此通常仍为 `0`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::GetWidth(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 该返回值目前更像占位字段，不应被当作可靠尺寸来源。
|
||||
- 实际渲染尺寸应以纹理描述或上层 framebuffer 配置为准。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetHeight](GetHeight.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,46 +1,57 @@
|
||||
# OpenGLRenderTargetView::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
该方法在 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
|
||||
|
||||
## 重载 1: 声明
|
||||
|
||||
```cpp
|
||||
bool Initialize(unsigned int texture, const OpenGLRenderTargetViewDesc& desc);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `texture` - 参数语义详见头文件声明。
|
||||
- `desc` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
|
||||
## 重载 2: 声明
|
||||
|
||||
```cpp
|
||||
bool Initialize(unsigned int texture, int mipLevel = 0);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `texture` - 参数语义详见头文件声明。
|
||||
- `mipLevel` - 参数语义详见头文件声明。
|
||||
## 作用
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
为给定纹理创建一个独立的 framebuffer，并把一个颜色附件绑定到 `GL_COLOR_ATTACHMENT0`。
|
||||
|
||||
**示例：**
|
||||
## 参数说明
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
- `texture`: OpenGL 纹理 id。
|
||||
- `desc`: 旧式 RTV 描述结构，指定纹理类型、mip、数组层或立方体面。
|
||||
- `mipLevel`: `Texture2D` 简化重载使用的 mip 级别。
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::Initialize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
## 返回值
|
||||
|
||||
- framebuffer 完整时返回 `true`。
|
||||
- `glCheckFramebufferStatus(GL_FRAMEBUFFER) != GL_FRAMEBUFFER_COMPLETE` 时返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
### `Initialize(unsigned int texture, const OpenGLRenderTargetViewDesc& desc)`
|
||||
|
||||
- 保存 `m_texture`、`m_mipLevel` 和 `m_type`。
|
||||
- 调用 `glGenFramebuffers()` 创建独立 FBO。
|
||||
- 把目标附件固定绑定到 `GL_COLOR_ATTACHMENT0`。
|
||||
- 根据 `desc.type` 选择不同附着路径:
|
||||
- `Texture2D`: `glFramebufferTexture2D`
|
||||
- `Texture2DArray`: `glFramebufferTextureLayer`
|
||||
- `Texture3D`: `glFramebufferTextureLayer`
|
||||
- `TextureCube`: `glFramebufferTexture2D(GL_TEXTURE_CUBE_MAP_POSITIVE_X + desc.baseArraySlice, ...)`
|
||||
- `TextureCubeArray`: `glFramebufferTextureLayer`
|
||||
- 完成后检查 FBO 完整性，并在退出前解绑 `GL_FRAMEBUFFER`。
|
||||
|
||||
### `Initialize(unsigned int texture, int mipLevel = 0)`
|
||||
|
||||
- 构造一个 `Texture2D` 的默认描述。
|
||||
- 然后转调主重载。
|
||||
|
||||
## 重要限制
|
||||
|
||||
- 该类型只处理单颜色附件。
|
||||
- 即使初始化成功，`m_width` / `m_height` 仍不会被写入。
|
||||
- 初始化失败时，函数会解绑 framebuffer 并返回 `false`，但已经创建出的 FBO id 仍依赖后续 `Shutdown()` 统一删除。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 在现代 RHI 流程中，更推荐使用 [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md) 与 [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md) 的组合。
|
||||
- 该类更适合兼容旧路径、快速工具渲染或测试。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [InitializeCubemap](InitializeCubemap.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,33 +1,36 @@
|
||||
# OpenGLRenderTargetView::InitializeCubemap
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeCubemap(unsigned int cubemap, int face, int mipLevel = 0);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `cubemap` - 参数语义详见头文件声明。
|
||||
- `face` - 参数语义详见头文件声明。
|
||||
- `mipLevel` - 参数语义详见头文件声明。
|
||||
为立方体贴图的单个面创建一个颜色渲染目标。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 参数说明
|
||||
|
||||
**示例：**
|
||||
- `cubemap`: 立方体贴图的 OpenGL 纹理 id。
|
||||
- `face`: 立方体面索引，会直接映射到 `GL_TEXTURE_CUBE_MAP_POSITIVE_X + face`。
|
||||
- `mipLevel`: 需要附着的 mip 级别。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::InitializeCubemap(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- framebuffer 完整时返回 `true`，否则返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 保存 `m_texture`、`m_mipLevel` 和 `m_type = RenderTargetType::TextureCube`。
|
||||
- 创建独立 FBO。
|
||||
- 使用 `glFramebufferTexture2D` 把指定 cube face 绑定到 `GL_COLOR_ATTACHMENT0`。
|
||||
- 检查 FBO 完整性后解绑 `GL_FRAMEBUFFER`。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- `face` 参数当前不会额外校验范围，调用方应确保它位于立方体面的有效区间。
|
||||
- 如果你需要表达 cubemap array 或多附件渲染，建议改用新路径，而不是继续扩展这个旧辅助类。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetMipLevel](GetMipLevel.md)
|
||||
|
||||
@@ -6,41 +6,66 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLRenderTargetView` public API。
|
||||
**描述**: 旧式 OpenGL 颜色渲染目标辅助类，内部为单个纹理附件创建独立 framebuffer。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`OpenGLRenderTargetView.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`OpenGLRenderTargetView` 来自较早的 OpenGL 封装路径。它的核心思路非常直接:
|
||||
|
||||
## 声明概览
|
||||
- 接收一个已经存在的纹理 id
|
||||
- 创建一个专属 framebuffer
|
||||
- 把该纹理的某个 mip、数组层或 cubemap face 附着到 `GL_COLOR_ATTACHMENT0`
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `RenderTargetType` | `enum class` | 头文件中的公开声明。 |
|
||||
| `OpenGLRenderTargetViewDesc` | `struct` | 头文件中的公开声明。 |
|
||||
| `OpenGLRenderTargetView` | `class` | 头文件中的公开声明。 |
|
||||
这和现代显式图形 API 中的 render-target view 概念有相似之处，但在当前引擎里，它已经与更新的 `OpenGLFramebuffer + OpenGLResourceView` 方案产生职责重叠。
|
||||
|
||||
## 公共方法
|
||||
## 设计定位
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [OpenGLRenderTargetView()](Constructor.md) | 构造对象。 |
|
||||
| [~OpenGLRenderTargetView()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [Initialize](Initialize.md) | 初始化内部状态。 |
|
||||
| [InitializeCubemap](InitializeCubemap.md) | 初始化内部状态。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
|
||||
| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 |
|
||||
| [Clear](Clear.md) | 清空内部数据。 |
|
||||
| [GetFramebuffer](GetFramebuffer.md) | 获取相关状态或对象。 |
|
||||
| [GetTexture](GetTexture.md) | 获取相关状态或对象。 |
|
||||
| [GetMipLevel](GetMipLevel.md) | 获取相关状态或对象。 |
|
||||
| [GetWidth](GetWidth.md) | 获取相关状态或对象。 |
|
||||
| [GetHeight](GetHeight.md) | 获取相关状态或对象。 |
|
||||
| [BindFramebuffer](BindFramebuffer.md) | 公开方法，详见头文件声明。 |
|
||||
| [UnbindFramebuffer](UnbindFramebuffer.md) | 公开方法，详见头文件声明。 |
|
||||
可以把这个类理解成“快速创建单附件 FBO 的旧工具层”。
|
||||
|
||||
它的优点是:
|
||||
|
||||
- 实现非常直观
|
||||
- 测试与工具代码里使用成本低
|
||||
- 不需要先构造更完整的 framebuffer 描述
|
||||
|
||||
它的缺点也很明显:
|
||||
|
||||
- 只覆盖单颜色附件路径
|
||||
- 没有和统一的 descriptor / framebuffer 体系深度融合
|
||||
- `GetWidth()` / `GetHeight()` 这类字段没有真正维护
|
||||
|
||||
如果你在构建商业级渲染架构，新的 `OpenGLFramebuffer` / `OpenGLResourceView` 路径更接近统一 RHI 的长期方案。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- 构造时不创建任何 OpenGL 对象。
|
||||
- `Initialize()` / `InitializeCubemap()` 成功后持有一个独立 FBO。
|
||||
- `Shutdown()` 或析构时删除该 FBO。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 当前实现没有同步保护。
|
||||
- 所有调用都应视为依赖当前 OpenGL 上下文，通常应在拥有该上下文的渲染线程执行。
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
- 只操作颜色附件，不直接表达深度/模板附件创建。
|
||||
- `Bind(slot)` 的 `slot` 参数被忽略。
|
||||
- 多 framebuffer 的 `Bind(count, ...)` 是一套明显偏旧的辅助逻辑，不等价于现代 MRT 抽象。
|
||||
- `Clear()` 不会恢复之前的 framebuffer 绑定。
|
||||
- `GetWidth()` / `GetHeight()` 当前基本恒为 `0`。
|
||||
- 单元测试 `tests/RHI/OpenGL/unit/test_render_target_view.cpp` 只覆盖了初始化、绑定/解绑、纹理 id 和 mip 访问这些基础能力。
|
||||
|
||||
## 关键方法
|
||||
|
||||
- [Initialize](Initialize.md)
|
||||
- [InitializeCubemap](InitializeCubemap.md)
|
||||
- [Bind](Bind.md)
|
||||
- [Clear](Clear.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
|
||||
- [API 总索引](../../../../main.md) - 返回顶层索引
|
||||
- [OpenGL](../OpenGL.md)
|
||||
- [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md)
|
||||
- [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# OpenGLRenderTargetView::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
|
||||
```cpp
|
||||
void Shutdown();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
删除该对象创建的 framebuffer，并清理批量 framebuffer 缓存。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_framebuffer != 0`，调用 `glDeleteFramebuffers(1, &m_framebuffer)`，然后把它重置为 `0`。
|
||||
- 如果 `m_framebuffers` 非空，调用 `glDeleteFramebuffers(count, data)` 后清空数组。
|
||||
- 不会重置 `m_texture`、`m_mipLevel`、`m_width`、`m_height` 或 `m_type`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 调用后，`GetFramebuffer()` 会变成 `0`，但 `GetTexture()` 仍可能返回旧值，因为纹理句柄没有被清空。
|
||||
- 如果你依赖“完全复位”的对象状态，应该销毁对象并重新构造，而不是只依赖 `Shutdown()`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Destructor](Destructor.md)
|
||||
- [GetFramebuffer](GetFramebuffer.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# OpenGLRenderTargetView::Unbind
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
|
||||
```cpp
|
||||
void Unbind();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
解绑当前 framebuffer，恢复到默认 framebuffer `0`。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::Unbind(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 直接执行 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
|
||||
- 不恢复 draw buffer、viewport 或其他状态。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Bind](Bind.md)
|
||||
- [UnbindFramebuffer](UnbindFramebuffer.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# OpenGLRenderTargetView::UnbindFramebuffer
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
|
||||
```cpp
|
||||
static void UnbindFramebuffer();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h`，当前页面用于固定 `OpenGLRenderTargetView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
静态解绑当前 framebuffer。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLRenderTargetView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLRenderTargetView::UnbindFramebuffer(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 仅执行 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
|
||||
- 行为与实例方法 [Unbind](Unbind.md) 一致，只是无需依赖对象实例。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLRenderTargetView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [BindFramebuffer](BindFramebuffer.md)
|
||||
- [Unbind](Unbind.md)
|
||||
|
||||
@@ -1,28 +1,32 @@
|
||||
# OpenGLResourceView::OpenGLResourceView()
|
||||
|
||||
构造对象。
|
||||
# OpenGLResourceView::OpenGLResourceView
|
||||
|
||||
```cpp
|
||||
OpenGLResourceView();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
构造一个空的统一资源视图对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 构造函数会设置一组默认值:
|
||||
- `m_viewType = ResourceViewType::RenderTarget`
|
||||
- `m_format = Format::Unknown`
|
||||
- `m_dimension = ResourceViewDimension::Unknown`
|
||||
- `m_framebufferID = 0`
|
||||
- `m_textureUnit = -1`
|
||||
- `m_bindingPoint = -1`
|
||||
- 各类对象指针为空
|
||||
- buffer 相关缓存为 `0`
|
||||
- 不执行任何 OpenGL 调用。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
}
|
||||
```
|
||||
- 构造后对象还没有实际资源语义，必须调用某个 `InitializeAs...` 方法。
|
||||
- 不应把默认的 `RenderTarget` 类型误认为对象已经是一个可用 RTV。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetViewType](GetViewType.md)
|
||||
- [IsValid](IsValid.md)
|
||||
|
||||
@@ -1,29 +1,20 @@
|
||||
# OpenGLResourceView::~OpenGLResourceView()
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
# OpenGLResourceView::~OpenGLResourceView
|
||||
|
||||
```cpp
|
||||
~OpenGLResourceView() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
销毁 `OpenGLResourceView`，并释放它占用的纹理单元或 UBO 绑定点。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- 析构函数内部调用 [Shutdown](Shutdown.md)。
|
||||
- 如果该 view 曾经作为 UAV 或常量缓冲视图分配过绑定资源，析构时会一并释放。
|
||||
- 不会销毁底层纹理、缓冲区或 framebuffer 对象本身，这些资源由外部对象拥有。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [OpenGLResourceView](OpenGLResourceView.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# OpenGLResourceView::GetBindingPoint
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
int32_t GetBindingPoint() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 占用的 uniform buffer 绑定点。
|
||||
|
||||
**返回：** `int32_t` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 对常量缓冲视图返回有效绑定点编号。
|
||||
- 对其他 view 类型通常返回构造默认值 `-1`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetBindingPoint(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 仅 [InitializeAsConstantBuffer](InitializeAsConstantBuffer.md) 会写入该字段。
|
||||
- `Shutdown()` 释放绑定点后会把它重置为 `-1`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [InitializeAsConstantBuffer](InitializeAsConstantBuffer.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# OpenGLResourceView::GetBuffer
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
unsigned int GetBuffer() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 关联的 OpenGL buffer id。
|
||||
|
||||
**返回：** `unsigned int` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_buffer` 有效，返回其 `GetID()`。
|
||||
- 否则返回 `0`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetBuffer(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 顶点缓冲、索引缓冲和常量缓冲视图都会使用该接口暴露底层 buffer id。
|
||||
- 该接口不区分 buffer 的用途，调用方应结合 [GetViewType](GetViewType.md) 判断具体语义。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetViewType](GetViewType.md)
|
||||
- [GetNativeHandle](GetNativeHandle.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# OpenGLResourceView::GetBufferOffset
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint64_t GetBufferOffset() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 记录的缓冲区偏移。
|
||||
|
||||
**返回：** `uint64_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 仅 [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md) 和 [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md) 会把 `desc.bufferLocation` 写入该字段。
|
||||
- 常量缓冲视图当前不会把偏移保存在这里，因此 CBV 场景下通常仍为 `0`。
|
||||
- `Shutdown()` 会把它重置为 `0`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetBufferOffset(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 在命令列表里，该值会参与顶点/索引缓冲绑定偏移计算。
|
||||
- 不要假设它能反映 `BindBufferRange` 式的常量缓冲区范围信息；当前实现并没有做到这一层。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)
|
||||
- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)
|
||||
|
||||
@@ -1,30 +1,20 @@
|
||||
# OpenGLResourceView::GetBufferSize
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetBufferSize() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 缓存的缓冲区大小。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetBufferSize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 顶点缓冲和索引缓冲初始化时，都会把 `buffer->GetSize()` 的完整结果写入该字段。
|
||||
- 这意味着它表示“底层缓冲总大小”，不是“从偏移开始的剩余可见范围”。
|
||||
- 对常量缓冲或纹理类 view，该值通常保持为 `0`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)
|
||||
- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)
|
||||
|
||||
@@ -1,30 +1,27 @@
|
||||
# OpenGLResourceView::GetBufferStride
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetBufferStride() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 记录的元素步长。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 顶点缓冲视图:
|
||||
- 如果 `desc.structureByteStride > 0`，优先使用它。
|
||||
- 否则退回到底层 `buffer->GetStride()`。
|
||||
- 索引缓冲视图使用 `buffer->GetStride()`。
|
||||
- 其他类型通常保持为 `0`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetBufferStride(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `OpenGLCommandList::SetVertexBuffers()` 会用这个值推导 `glVertexAttribPointer` 的步长。
|
||||
- 对索引缓冲来说，真正的索引类型仍由 [GetFormat](GetFormat.md) 决定。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md)
|
||||
- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)
|
||||
|
||||
@@ -1,30 +1,20 @@
|
||||
# OpenGLResourceView::GetDimension
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
ResourceViewDimension GetDimension() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 当前记录的维度信息。
|
||||
|
||||
**返回：** `ResourceViewDimension` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetDimension(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 纹理类 view 会直接采用 `ResourceViewDesc::dimension`。
|
||||
- 顶点缓冲、索引缓冲和常量缓冲视图会把它设置为 `ResourceViewDimension::Buffer`。
|
||||
- 构造后默认值为 `ResourceViewDimension::Unknown`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)
|
||||
- [InitializeAsShaderResource](InitializeAsShaderResource.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# OpenGLResourceView::GetFormat
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
Format GetFormat() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 记录的格式。
|
||||
|
||||
**返回：** `Format` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 纹理类 view 优先使用 `ResourceViewDesc::format`，如果未显式指定则退回到底层纹理格式。
|
||||
- 索引缓冲视图会使用 `desc.format`，未指定时默认 `Format::R32_UInt`。
|
||||
- 顶点缓冲和常量缓冲视图当前固定保存为 `Format::Unknown`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetFormat(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 在 OpenGL 后端中，这个格式更多是引擎侧元数据，不总能一一对应到真正的 OpenGL view format 对象。
|
||||
- 对索引缓冲场景，该值会影响命令列表选择 `GL_UNSIGNED_SHORT` 或 `GL_UNSIGNED_INT` 等索引类型。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md)
|
||||
- [GetNativeHandle](GetNativeHandle.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# OpenGLResourceView::GetFramebuffer
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
unsigned int GetFramebuffer() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 关联的 framebuffer id。
|
||||
|
||||
**返回：** `unsigned int` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_framebuffer` 有效，返回 `m_framebuffer->GetFramebuffer()`。
|
||||
- 否则返回 `0`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetFramebuffer(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 该接口主要对渲染目标视图和深度/模板视图有意义。
|
||||
- 它通过 `m_framebuffer` 指针查询当前 id，而不是直接返回缓存的 `m_framebufferID`。
|
||||
- `IsValid()` 对 RTV/DSV 的校验使用的是 `m_framebufferID != 0`，这两个接口的来源略有差异，但在正常生命周期里应保持一致。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)
|
||||
- [InitializeAsDepthStencil](InitializeAsDepthStencil.md)
|
||||
|
||||
@@ -1,30 +1,31 @@
|
||||
# OpenGLResourceView::GetFramebufferAttachment
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const FramebufferAttachment& GetFramebufferAttachment() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 缓存的 framebuffer 附件描述。
|
||||
|
||||
**返回：** `const FramebufferAttachment&` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 仅渲染目标和深度/模板视图会在初始化时填充这个结构。
|
||||
- 缓存内容包括:
|
||||
- 纹理 id
|
||||
- 目标 `GLenum`
|
||||
- mip 级别
|
||||
- layer
|
||||
- 附件类型
|
||||
- 格式
|
||||
- `Shutdown()` 会把它重置为默认值。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetFramebufferAttachment(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `OpenGLFramebuffer` 的统一初始化路径会消费该结构来重新组装 FBO。
|
||||
- 对 buffer 类 view，这个结构没有实际意义。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)
|
||||
- [InitializeAsDepthStencil](InitializeAsDepthStencil.md)
|
||||
|
||||
@@ -1,30 +1,31 @@
|
||||
# OpenGLResourceView::GetNativeHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
void* GetNativeHandle() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 对应的底层原生句柄。
|
||||
|
||||
**返回：** `void*` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 顶点缓冲 / 索引缓冲 / 常量缓冲视图: 返回底层 buffer id。
|
||||
- 渲染目标 / 深度模板视图: 返回 framebuffer id。
|
||||
- SRV / UAV: 返回底层纹理 id。
|
||||
- 未知类型: 返回 `nullptr`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetNativeHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这个接口不会创建任何新的 OpenGL 对象，只是根据 `m_viewType` 把已有 id 转成 `void*`。
|
||||
- 它暴露的是“当前这类 view 在 OpenGL 下最接近原生句柄的对象”，但不同 view 类型的含义完全不同。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 调用方不能把不同 `ResourceViewType` 返回的句柄当作同一种资源解释。
|
||||
- 如果需要稳定地按类型访问资源，应优先使用 [GetTexture](GetTexture.md)、[GetBuffer](GetBuffer.md)、[GetFramebuffer](GetFramebuffer.md) 这类显式接口。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetViewType](GetViewType.md)
|
||||
- [IsValid](IsValid.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# OpenGLResourceView::GetTexture
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
unsigned int GetTexture() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 关联的 OpenGL 纹理 id。
|
||||
|
||||
**返回：** `unsigned int` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_texture` 有效，返回其 `GetID()`。
|
||||
- 否则返回 `0`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetTexture(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 该接口对 RTV、DSV、SRV、UAV 都有意义。
|
||||
- 顶点/索引/常量缓冲视图通常返回 `0`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetTextureResource](GetTextureResource.md)
|
||||
- [GetTextureUnit](GetTextureUnit.md)
|
||||
|
||||
@@ -1,30 +1,29 @@
|
||||
# OpenGLResourceView::GetTextureResource
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const OpenGLTexture* GetTextureResource() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回底层 `OpenGLTexture` 对象指针。
|
||||
|
||||
**返回：** `const OpenGLTexture*` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- 如果该 view 基于纹理创建，返回对应的 `OpenGLTexture*`。
|
||||
- 否则返回 `nullptr`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetTextureResource(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `OpenGLCommandList::TransitionBarrier()` 会通过该接口拿到纹理对象并更新其引擎侧状态。
|
||||
- `OpenGLCommandList::SetRenderTargets()` 也会读取这里的纹理宽高和纹理 id 来组装组合 framebuffer。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 这是比 [GetTexture](GetTexture.md) 更强的接口，因为它暴露了纹理对象本身。
|
||||
- 调用方不拥有返回对象的生命周期，不应自行销毁。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetTexture](GetTexture.md)
|
||||
- [../OpenGLTexture/OpenGLTexture.md](../OpenGLTexture/OpenGLTexture.md)
|
||||
|
||||
@@ -1,30 +1,20 @@
|
||||
# OpenGLResourceView::GetTextureUnit
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
int32_t GetTextureUnit() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该 view 占用的纹理单元编号。
|
||||
|
||||
**返回：** `int32_t` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetTextureUnit(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 对 UAV，返回通过 `OpenGLTextureUnitAllocator` 分配到的 unit。
|
||||
- 对 SRV，当前仍为 `-1`，因为初始化时不会分配纹理单元。
|
||||
- 其他类型通常也返回 `-1`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [InitializeAsShaderResource](InitializeAsShaderResource.md)
|
||||
- [InitializeAsUnorderedAccess](InitializeAsUnorderedAccess.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# OpenGLResourceView::GetViewType
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
ResourceViewType GetViewType() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回该对象当前表示的 view 类型。
|
||||
|
||||
**返回：** `ResourceViewType` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 构造时默认值是 `ResourceViewType::RenderTarget`。
|
||||
- 各种 `InitializeAs...` 方法会把它改写为对应类型。
|
||||
- 这意味着“尚未初始化的对象”在类型上看起来像 RTV，但 [IsValid](IsValid.md) 仍会返回 `false`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::GetViewType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 不应只依赖 `GetViewType()` 判断对象是否可用，必须与 `IsValid()` 结合。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [IsValid](IsValid.md)
|
||||
- [OpenGLResourceView](OpenGLResourceView.md)
|
||||
|
||||
@@ -1,33 +1,39 @@
|
||||
# OpenGLResourceView::InitializeAsConstantBuffer
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeAsConstantBuffer( OpenGLBuffer* buffer, const ResourceViewDesc& desc, OpenGLUniformBufferManager* manager);
|
||||
bool InitializeAsConstantBuffer(
|
||||
OpenGLBuffer* buffer,
|
||||
const ResourceViewDesc& desc,
|
||||
OpenGLUniformBufferManager* manager);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `buffer` - 参数语义详见头文件声明。
|
||||
- `desc` - 参数语义详见头文件声明。
|
||||
- `manager` - 参数语义详见头文件声明。
|
||||
把当前对象初始化为常量缓冲视图，并分配一个 uniform buffer 绑定点。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 前置条件
|
||||
|
||||
**示例：**
|
||||
- `buffer` 和 `manager` 不能为空。
|
||||
- `manager` 内必须还有可用绑定点。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsConstantBuffer(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 初始化成功返回 `true`。
|
||||
- 参数为空或分配绑定点失败时返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 通过 `manager->Allocate()` 申请一个 binding point。
|
||||
- 把 view 类型设置为 `ConstantBuffer`，维度设置为 `Buffer`。
|
||||
- 保存 `m_buffer`、`m_bindingPoint` 和 `m_uniformBufferManager`。
|
||||
- 调用 `manager->BindBuffer(bindingPoint, buffer, 0, desc.bufferLocation)`。
|
||||
|
||||
## 重要限制
|
||||
|
||||
- 当前 `OpenGLUniformBufferManager::BindBuffer()` 实际使用的是 `glBindBufferBase`，会忽略传入的 offset 和 size。
|
||||
- 因此这个“常量缓冲视图”目前更像“为整块 UBO 绑定一个槽位”，而不是支持任意范围的 CBV。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetBindingPoint](GetBindingPoint.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,33 +1,45 @@
|
||||
# OpenGLResourceView::InitializeAsDepthStencil
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeAsDepthStencil( OpenGLTexture* texture, const ResourceViewDesc& desc, OpenGLFramebuffer* framebuffer);
|
||||
bool InitializeAsDepthStencil(
|
||||
OpenGLTexture* texture,
|
||||
const ResourceViewDesc& desc,
|
||||
OpenGLFramebuffer* framebuffer);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `texture` - 参数语义详见头文件声明。
|
||||
- `desc` - 参数语义详见头文件声明。
|
||||
- `framebuffer` - 参数语义详见头文件声明。
|
||||
把当前对象初始化为深度/模板视图，并缓存该附件在 framebuffer 中的附着信息。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 前置条件
|
||||
|
||||
**示例：**
|
||||
- `texture` 和 `framebuffer` 都不能为空。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsDepthStencil(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 参数有效时返回 `true`，否则返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 设置 `m_viewType = DepthStencil`。
|
||||
- 解析格式:
|
||||
- 如果 `desc.format` 非零，优先使用它。
|
||||
- 否则退回到底层纹理格式。
|
||||
- 记录 `m_dimension`、`m_texture`、`m_framebuffer` 和 `m_framebufferID`。
|
||||
- 填充 `m_framebufferAttachment`:
|
||||
- 纹理 id
|
||||
- 目标类型
|
||||
- mip 级别
|
||||
- layer
|
||||
- 附件类型为 `Depth` 或 `DepthStencil`
|
||||
- 格式
|
||||
|
||||
## 设计说明
|
||||
|
||||
- 这里不会创建新的 OpenGL depth-stencil view 对象。
|
||||
- 它做的是把“统一 RHI 视图语义”映射为“现有 framebuffer + 附件元数据”的组合。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetFramebufferAttachment](GetFramebufferAttachment.md)
|
||||
- [GetFramebuffer](GetFramebuffer.md)
|
||||
|
||||
@@ -1,32 +1,38 @@
|
||||
# OpenGLResourceView::InitializeAsIndexBuffer
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeAsIndexBuffer( OpenGLBuffer* buffer, const ResourceViewDesc& desc);
|
||||
bool InitializeAsIndexBuffer(
|
||||
OpenGLBuffer* buffer,
|
||||
const ResourceViewDesc& desc);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `buffer` - 参数语义详见头文件声明。
|
||||
- `desc` - 参数语义详见头文件声明。
|
||||
把当前对象初始化为索引缓冲视图。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 前置条件
|
||||
|
||||
**示例：**
|
||||
- `buffer` 不能为空。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsIndexBuffer(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 成功返回 `true`，参数为空时返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 设置 `m_viewType = IndexBuffer`。
|
||||
- 如果 `desc.format` 已指定，使用该格式；否则默认 `Format::R32_UInt`。
|
||||
- 维度固定为 `Buffer`。
|
||||
- 记录 `m_buffer`、`m_bufferOffset = desc.bufferLocation`。
|
||||
- `m_bufferSize` 保存整个缓冲区大小。
|
||||
- `m_bufferStride` 使用底层 `buffer->GetStride()`。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 命令列表真正的索引类型解析依赖这个 view 保存的格式。
|
||||
- 如果底层缓冲实际是 16 位索引，文档化和创建时应明确设置正确格式，避免默认退回 32 位。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetFormat](GetFormat.md)
|
||||
- [GetBufferOffset](GetBufferOffset.md)
|
||||
|
||||
@@ -1,33 +1,42 @@
|
||||
# OpenGLResourceView::InitializeAsRenderTarget
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeAsRenderTarget( OpenGLTexture* texture, const ResourceViewDesc& desc, OpenGLFramebuffer* framebuffer);
|
||||
bool InitializeAsRenderTarget(
|
||||
OpenGLTexture* texture,
|
||||
const ResourceViewDesc& desc,
|
||||
OpenGLFramebuffer* framebuffer);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `texture` - 参数语义详见头文件声明。
|
||||
- `desc` - 参数语义详见头文件声明。
|
||||
- `framebuffer` - 参数语义详见头文件声明。
|
||||
把当前对象初始化为颜色渲染目标视图，并缓存它在 framebuffer 中的附着方式。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 前置条件
|
||||
|
||||
**示例：**
|
||||
- `texture` 和 `framebuffer` 都不能为空。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsRenderTarget(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 参数有效时返回 `true`，否则返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 设置 `m_viewType = RenderTarget`。
|
||||
- 解析 view 格式，优先使用 `desc.format`，否则沿用纹理格式。
|
||||
- 保存 `m_dimension`、`m_texture`、`m_framebuffer` 和 `m_framebufferID`。
|
||||
- 解析附件目标:
|
||||
- `Texture1D` -> `GL_TEXTURE_1D`
|
||||
- `Texture2D` -> `GL_TEXTURE_2D`
|
||||
- `TextureCube` -> `GL_TEXTURE_CUBE_MAP_POSITIVE_X + face`
|
||||
- `Texture2DArray` / `Texture3D` / `TextureCubeArray` -> 通过 layer 表达
|
||||
- 填充 `FramebufferAttachment`，并把附件类型标为 `Color`。
|
||||
|
||||
## 设计说明
|
||||
|
||||
- 该接口不创建新的 OpenGL RTV 对象。
|
||||
- 它更像“把一个纹理附件映射为统一 RHI 颜色视图，并缓存后续组装 FBO 所需的元数据”。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetFramebufferAttachment](GetFramebufferAttachment.md)
|
||||
- [GetTextureResource](GetTextureResource.md)
|
||||
|
||||
@@ -1,33 +1,38 @@
|
||||
# OpenGLResourceView::InitializeAsShaderResource
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeAsShaderResource( OpenGLTexture* texture, const ResourceViewDesc& desc, OpenGLTextureUnitAllocator* allocator);
|
||||
bool InitializeAsShaderResource(
|
||||
OpenGLTexture* texture,
|
||||
const ResourceViewDesc& desc,
|
||||
OpenGLTextureUnitAllocator* allocator);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `texture` - 参数语义详见头文件声明。
|
||||
- `desc` - 参数语义详见头文件声明。
|
||||
- `allocator` - 参数语义详见头文件声明。
|
||||
把当前对象初始化为着色器资源视图。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 前置条件
|
||||
|
||||
**示例：**
|
||||
- `texture` 不能为空。
|
||||
- `allocator` 可以为空；当前实现不会立即从中分配纹理单元。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsShaderResource(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `texture` 有效时返回 `true`，否则返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 设置 `m_viewType = ShaderResource`。
|
||||
- 保存格式、维度和底层纹理指针。
|
||||
- 把 `m_textureUnit` 设为 `-1`。
|
||||
- 仅保存 `m_textureUnitAllocator` 指针，不进行 `Allocate()`。
|
||||
|
||||
## 设计说明
|
||||
|
||||
- 这说明当前 OpenGL SRV 只是“纹理资源的只读视图元数据”。
|
||||
- 真正把纹理绑定到某个 texture unit 的时机，不是在这个初始化函数里。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetTextureUnit](GetTextureUnit.md)
|
||||
- [InitializeAsUnorderedAccess](InitializeAsUnorderedAccess.md)
|
||||
|
||||
@@ -1,33 +1,46 @@
|
||||
# OpenGLResourceView::InitializeAsUnorderedAccess
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeAsUnorderedAccess( OpenGLTexture* texture, const ResourceViewDesc& desc, OpenGLTextureUnitAllocator* allocator);
|
||||
bool InitializeAsUnorderedAccess(
|
||||
OpenGLTexture* texture,
|
||||
const ResourceViewDesc& desc,
|
||||
OpenGLTextureUnitAllocator* allocator);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `texture` - 参数语义详见头文件声明。
|
||||
- `desc` - 参数语义详见头文件声明。
|
||||
- `allocator` - 参数语义详见头文件声明。
|
||||
把当前对象初始化为无序访问视图，并立即把纹理绑定为 image 资源。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 前置条件
|
||||
|
||||
**示例：**
|
||||
- `texture` 和 `allocator` 都不能为空。
|
||||
- 分配器必须仍有可用纹理单元。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsUnorderedAccess(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 初始化成功返回 `true`。
|
||||
- 参数无效或 `Allocate()` 失败时返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 先通过 `allocator->Allocate()` 申请一个 texture unit。
|
||||
- 保存 view 类型、格式、维度、纹理指针和分配到的 unit。
|
||||
- 立即执行:
|
||||
- `glActiveTexture(GL_TEXTURE0 + unit)`
|
||||
- `glBindTexture(textureType, textureID)`
|
||||
- `glBindImageTexture(unit, textureID, 0, GL_FALSE, 0, GL_READ_WRITE, GL_RGBA8)`
|
||||
|
||||
## 重要限制
|
||||
|
||||
- image 绑定固定使用:
|
||||
- mip `0`
|
||||
- `layered = GL_FALSE`
|
||||
- layer `0`
|
||||
- 访问模式 `GL_READ_WRITE`
|
||||
- 格式 `GL_RGBA8`
|
||||
- 也就是说，当前实现并没有把 `ResourceViewDesc` 中的 mip、层、格式完整映射到 image view 语义。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetTextureUnit](GetTextureUnit.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,32 +1,39 @@
|
||||
# OpenGLResourceView::InitializeAsVertexBuffer
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool InitializeAsVertexBuffer( OpenGLBuffer* buffer, const ResourceViewDesc& desc);
|
||||
bool InitializeAsVertexBuffer(
|
||||
OpenGLBuffer* buffer,
|
||||
const ResourceViewDesc& desc);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `buffer` - 参数语义详见头文件声明。
|
||||
- `desc` - 参数语义详见头文件声明。
|
||||
把当前对象初始化为顶点缓冲视图。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 前置条件
|
||||
|
||||
**示例：**
|
||||
- `buffer` 不能为空。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::InitializeAsVertexBuffer(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 成功返回 `true`，参数为空时返回 `false`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 设置 `m_viewType = VertexBuffer`。
|
||||
- 格式固定保存为 `Format::Unknown`。
|
||||
- 维度设为 `Buffer`。
|
||||
- 记录底层 buffer 指针。
|
||||
- `m_bufferOffset = desc.bufferLocation`。
|
||||
- `m_bufferSize = buffer->GetSize()`。
|
||||
- `m_bufferStride` 优先使用 `desc.structureByteStride`，否则使用底层 buffer 自身 stride。
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 这个 view 不会创建额外的 OpenGL descriptor 对象。
|
||||
- 命令列表真正设置顶点属性时，会把这里缓存的偏移和步长与输入布局拼接起来。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetBufferStride](GetBufferStride.md)
|
||||
- [GetBufferOffset](GetBufferOffset.md)
|
||||
|
||||
@@ -1,30 +1,28 @@
|
||||
# OpenGLResourceView::IsValid
|
||||
|
||||
查询当前状态。
|
||||
|
||||
```cpp
|
||||
bool IsValid() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
检查该 view 在当前类型下是否拥有可用的底层资源。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 顶点缓冲 / 索引缓冲: `m_buffer != nullptr && m_buffer->GetID() != 0`
|
||||
- 渲染目标 / 深度模板: `m_framebufferID != 0`
|
||||
- SRV: `m_texture != nullptr && m_texture->GetID() != 0`
|
||||
- UAV: `m_texture != nullptr && m_textureUnit >= 0`
|
||||
- 常量缓冲: `m_buffer != nullptr && m_bindingPoint >= 0`
|
||||
- 其他情况返回 `false`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::IsValid(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这是比 [GetViewType](GetViewType.md) 更可靠的可用性判断。
|
||||
- 对 UAV 和 CBV 来说，可用性的关键不仅是底层资源存在，还包括绑定资源是否成功分配。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetViewType](GetViewType.md)
|
||||
- [GetNativeHandle](GetNativeHandle.md)
|
||||
|
||||
@@ -6,49 +6,84 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/OpenGL/OpenGLResourceView.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLResourceView` public API。
|
||||
**描述**: OpenGL 后端统一资源视图对象，把 RHI 层的多种 view 语义映射为纹理、缓冲区、framebuffer 及其绑定元数据。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`OpenGLResourceView.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
在 D3D12 / Vulkan 里，resource view 往往会自然让人想到独立的 descriptor 或 view object。OpenGL 不是这套模型，它更多依赖:
|
||||
|
||||
## 声明概览
|
||||
- 纹理对象本身
|
||||
- buffer 对象本身
|
||||
- framebuffer 绑定关系
|
||||
- texture unit / image unit / uniform buffer binding point
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `OpenGLResourceView` | `class` | 继承自 `RHIResourceView` 的公开声明。 |
|
||||
`OpenGLResourceView` 的职责，就是把这些分散的 OpenGL 机制整理成统一的 RHI 视图对象，让上层仍然可以用 `RenderTargetView`、`ShaderResourceView`、`ConstantBufferView` 这类抽象去表达渲染意图。
|
||||
|
||||
## 公共方法
|
||||
## 设计定位
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [OpenGLResourceView()](Constructor.md) | 构造对象。 |
|
||||
| [~OpenGLResourceView()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
|
||||
| [IsValid](IsValid.md) | 查询当前状态。 |
|
||||
| [InitializeAsRenderTarget](InitializeAsRenderTarget.md) | 初始化内部状态。 |
|
||||
| [InitializeAsDepthStencil](InitializeAsDepthStencil.md) | 初始化内部状态。 |
|
||||
| [InitializeAsShaderResource](InitializeAsShaderResource.md) | 初始化内部状态。 |
|
||||
| [InitializeAsUnorderedAccess](InitializeAsUnorderedAccess.md) | 初始化内部状态。 |
|
||||
| [InitializeAsConstantBuffer](InitializeAsConstantBuffer.md) | 初始化内部状态。 |
|
||||
| [InitializeAsVertexBuffer](InitializeAsVertexBuffer.md) | 初始化内部状态。 |
|
||||
| [InitializeAsIndexBuffer](InitializeAsIndexBuffer.md) | 初始化内部状态。 |
|
||||
| [GetViewType](GetViewType.md) | 获取相关状态或对象。 |
|
||||
| [GetDimension](GetDimension.md) | 获取相关状态或对象。 |
|
||||
| [GetFormat](GetFormat.md) | 获取相关状态或对象。 |
|
||||
| [GetFramebuffer](GetFramebuffer.md) | 获取相关状态或对象。 |
|
||||
| [GetTextureUnit](GetTextureUnit.md) | 获取相关状态或对象。 |
|
||||
| [GetBindingPoint](GetBindingPoint.md) | 获取相关状态或对象。 |
|
||||
| [GetTexture](GetTexture.md) | 获取相关状态或对象。 |
|
||||
| [GetBuffer](GetBuffer.md) | 获取相关状态或对象。 |
|
||||
| [GetBufferOffset](GetBufferOffset.md) | 获取相关状态或对象。 |
|
||||
| [GetBufferSize](GetBufferSize.md) | 获取相关状态或对象。 |
|
||||
| [GetBufferStride](GetBufferStride.md) | 获取相关状态或对象。 |
|
||||
| [GetFramebufferAttachment](GetFramebufferAttachment.md) | 获取相关状态或对象。 |
|
||||
| [GetTextureResource](GetTextureResource.md) | 获取相关状态或对象。 |
|
||||
它不是“单一原生句柄的薄封装”，而是一个多态视图元数据对象:
|
||||
|
||||
- RTV / DSV: 依赖现有 framebuffer，并缓存附件信息
|
||||
- SRV: 仅保存纹理和格式信息，不立即分配纹理单元
|
||||
- UAV: 分配纹理单元，并立刻绑定 image texture
|
||||
- CBV: 分配 uniform buffer binding point
|
||||
- VB / IB: 只保存 buffer、偏移、步长和格式
|
||||
|
||||
这种设计的好处是跨后端接口统一，代价是 `GetNativeHandle()` 的真实含义会随着 `ResourceViewType` 改变。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- 构造时对象为空，但默认 `m_viewType` 会被初始化成 `RenderTarget`。
|
||||
- 调用某个 `InitializeAs...` 方法后进入对应视图模式。
|
||||
- [Shutdown](Shutdown.md) 会释放它占用的 texture unit 或 binding point，并清空缓存元数据。
|
||||
- 析构时自动调用 `Shutdown()`。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 当前实现没有锁。
|
||||
- 由于涉及 OpenGL 资源和绑定点分配器，应视为依赖渲染线程 / OpenGL 上下文的对象，不适合跨线程并发读写。
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
- RTV / DSV 不创建独立 OpenGL view object，而是引用已有 `OpenGLFramebuffer` 并缓存 `FramebufferAttachment`。
|
||||
- SRV 当前只是只读纹理视图元数据，不会立即占用 texture unit。
|
||||
- UAV 会直接调用 `glBindImageTexture()`，但当前绑定参数是硬编码的 `GL_RGBA8 + mip0 + layer0 + read_write`。
|
||||
- CBV 通过 `OpenGLUniformBufferManager` 分配绑定点，但当前底层使用 `glBindBufferBase`，不支持范围绑定。
|
||||
- VB / IB 不创建额外对象，只把 buffer 信息缓存起来供命令列表消费。
|
||||
- `OpenGLCommandList` 会真实使用这些信息:
|
||||
- `TransitionBarrier()` 通过 [GetTextureResource](GetTextureResource.md) 更新纹理状态
|
||||
- `SetRenderTargets()` 通过 framebuffer attachment 重新组装 FBO
|
||||
- `SetVertexBuffers()` / `SetIndexBuffer()` 读取偏移、步长和格式
|
||||
|
||||
## 为什么这样设计
|
||||
|
||||
这和商业引擎里常见的“跨后端统一资源视图层”是一致的思路:
|
||||
|
||||
- 上层系统可以统一讨论 SRV / UAV / RTV / DSV / CBV
|
||||
- 底层后端各自用最接近自己的机制去实现
|
||||
|
||||
对使用者来说，重要的不是假设所有后端都拥有完全对称的 view 模型，而是清楚知道当前 OpenGL 后端真正落到了哪一层。这个页面就是为了把这种边界说清楚。
|
||||
|
||||
## 当前限制
|
||||
|
||||
- `GetNativeHandle()` 不是统一类型句柄。
|
||||
- SRV 不负责即时分配 texture unit。
|
||||
- UAV 的 image 绑定参数是简化实现，不足以覆盖完整 typed / layered image view 需求。
|
||||
- CBV 没有实现真正的 offset/size range 绑定。
|
||||
- 构造后的默认 `GetViewType()` 是 `RenderTarget`，但对象并不有效。
|
||||
|
||||
## 关键方法
|
||||
|
||||
- [InitializeAsRenderTarget](InitializeAsRenderTarget.md)
|
||||
- [InitializeAsShaderResource](InitializeAsShaderResource.md)
|
||||
- [InitializeAsUnorderedAccess](InitializeAsUnorderedAccess.md)
|
||||
- [InitializeAsConstantBuffer](InitializeAsConstantBuffer.md)
|
||||
- [IsValid](IsValid.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
|
||||
- [API 总索引](../../../../main.md) - 返回顶层索引
|
||||
- [OpenGL](../OpenGL.md)
|
||||
- [OpenGLFramebuffer](../OpenGLFramebuffer/OpenGLFramebuffer.md)
|
||||
- [OpenGLTextureUnitAllocator](../OpenGLTextureUnitAllocator/OpenGLTextureUnitAllocator.md)
|
||||
- [OpenGLUniformBufferManager](../OpenGLUniformBufferManager/OpenGLUniformBufferManager.md)
|
||||
|
||||
@@ -1,30 +1,32 @@
|
||||
# OpenGLResourceView::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
|
||||
```cpp
|
||||
void Shutdown() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLResourceView.h`，当前页面用于固定 `OpenGLResourceView` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
释放该 view 占用的绑定资源，并清空内部缓存状态。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_textureUnit >= 0` 且存在分配器:
|
||||
- 调用 `UnbindTexture(m_textureUnit)`
|
||||
- 调用 `Free(m_textureUnit)`
|
||||
- 把 `m_textureUnit` 设为 `-1`
|
||||
- 如果 `m_bindingPoint >= 0` 且存在 UBO 管理器:
|
||||
- 调用 `UnbindBuffer(m_bindingPoint)`
|
||||
- 调用 `Free(m_bindingPoint)`
|
||||
- 把 `m_bindingPoint` 设为 `-1`
|
||||
- 清空 framebuffer、纹理、buffer、附件信息和缓存的偏移/大小/步长。
|
||||
- 不会重置 `m_viewType`、`m_format` 和 `m_dimension`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLResourceView.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLResourceView object;
|
||||
// 根据上下文补齐参数后调用 OpenGLResourceView::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 调用后即使某些元数据字段仍保留旧值，也不应再把对象视为有效视图；应以 [IsValid](IsValid.md) 为准。
|
||||
- 由于 `m_viewType` 不复位，调试时不要只看类型字段判断是否完成清理。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLResourceView.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Destructor](Destructor.md)
|
||||
- [IsValid](IsValid.md)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# API 文档重构状态
|
||||
|
||||
**生成时间**: `2026-03-27 22:48:36`
|
||||
**生成时间**: `2026-03-27 23:33:00`
|
||||
|
||||
**来源**: `docs/api/_tools/audit_api_docs.py`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user