docs(api): deepen D3D12 query heap and shader docs
This commit is contained in:
@@ -1,28 +1,20 @@
|
||||
# D3D12QueryHeap::D3D12QueryHeap()
|
||||
|
||||
构造对象。
|
||||
# D3D12QueryHeap::D3D12QueryHeap
|
||||
|
||||
```cpp
|
||||
D3D12QueryHeap();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
构造一个空的 D3D12 query heap 包装对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12QueryHeap object;
|
||||
}
|
||||
```
|
||||
- `m_type` 初始化为 `QueryType::Timestamp`
|
||||
- `m_count` 初始化为 `0`
|
||||
- `m_queryHeap` 为空
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12QueryHeap.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [D3D12QueryHeap](D3D12QueryHeap.md)
|
||||
|
||||
@@ -6,32 +6,78 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/D3D12/D3D12QueryHeap.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12QueryHeap` public API。
|
||||
**描述**: D3D12 后端的 query heap 包装，负责创建并保存 `ID3D12QueryHeap`，供命令列表执行 `BeginQuery`、`EndQuery` 和 `ResolveQueryData`。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`D3D12QueryHeap.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`D3D12QueryHeap` 是当前后端里比较薄的一层资源包装。
|
||||
|
||||
## 声明概览
|
||||
它主要做三件事：
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `D3D12QueryHeap` | `class` | 头文件中的公开声明。 |
|
||||
- 根据 [QueryType](../../RHITypes/RHITypes.md) 创建一个 `ID3D12QueryHeap`
|
||||
- 记录 query 类型和数量
|
||||
- 把原生 query heap 暴露给 [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) 这类低层调用方
|
||||
|
||||
## 公共方法
|
||||
它当前不负责这些事情：
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [D3D12QueryHeap()](Constructor.md) | 构造对象。 |
|
||||
| [~D3D12QueryHeap()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [Initialize](Initialize.md) | 初始化内部状态。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [GetQueryHeap](GetQueryHeap.md) | 获取相关状态或对象。 |
|
||||
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
|
||||
| [GetType](GetType.md) | 获取相关状态或对象。 |
|
||||
| [GetCount](GetCount.md) | 获取相关状态或对象。 |
|
||||
- 不分配结果缓冲区
|
||||
- 不封装 `ResolveQueryData(...)` 的结果读取
|
||||
- 不维护 query 槽位分配策略
|
||||
- 不做 query 生命周期调度
|
||||
|
||||
## 设计定位
|
||||
|
||||
这类对象在商业级引擎里通常只是 query 系统的一小部分。完整方案往往还会包含：
|
||||
|
||||
- 结果缓冲与 readback 管理
|
||||
- 时间戳校准与频率换算
|
||||
- query 池复用
|
||||
- frame graph / profiler 集成
|
||||
|
||||
当前 XCEngine 处于更早期、更基础的阶段，因此 `D3D12QueryHeap` 只先承担“创建原生 heap 并把它暴露出来”的职责。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- 构造后默认类型为 `QueryType::Timestamp`，数量为 `0`
|
||||
- [Initialize](Initialize.md) 成功后持有一个 `ID3D12QueryHeap`
|
||||
- [Shutdown](Shutdown.md) 释放 COM 对象并把类型、数量复位
|
||||
- 析构时自动调用 [Shutdown](Shutdown.md)
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
- `Initialize()` 根据 `QueryType` 选择 `D3D12_QUERY_HEAP_DESC::Type`
|
||||
- `desc.NodeMask` 当前固定写成 `0`
|
||||
- [Initialize](Initialize.md) 不读取 [QueryHeapDesc](../../RHITypes/RHITypes.md) 里的 `nodeMask`
|
||||
- 不对 `device == nullptr` 或 `count == 0` 做前置保护，完全依赖 `CreateQueryHeap(...)` 的返回结果
|
||||
- [GetNativeHandle](GetNativeHandle.md) 和 [GetQueryHeap](GetQueryHeap.md) 返回的是同一个原生指针
|
||||
|
||||
## 使用方式
|
||||
|
||||
当前典型调用链大致如下：
|
||||
|
||||
1. [D3D12Device](../D3D12Device/D3D12Device.md) 通过 `CreateQueryHeap(desc)` 创建对象
|
||||
2. 调用方取出原生 `ID3D12QueryHeap*`
|
||||
3. [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) 调用 `BeginQuery(...)`、`EndQuery(...)`、`ResolveQueryData(...)`
|
||||
4. 结果写入单独的 buffer，再由上层自己处理读回
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 只封装 heap，不封装 query 结果读取链路
|
||||
- 不支持 node mask 透传
|
||||
- 没有 query index 分配器
|
||||
- 没有线程安全保证
|
||||
- 当前工程里几乎没有直接针对它的单元测试覆盖
|
||||
|
||||
## 关键方法
|
||||
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetQueryHeap](GetQueryHeap.md)
|
||||
- [GetType](GetType.md)
|
||||
- [GetCount](GetCount.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
|
||||
- [API 总索引](../../../../main.md) - 返回顶层索引
|
||||
- [D3D12](../D3D12.md)
|
||||
- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
|
||||
- [D3D12Device](../D3D12Device/D3D12Device.md)
|
||||
|
||||
@@ -1,29 +1,19 @@
|
||||
# D3D12QueryHeap::~D3D12QueryHeap()
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
# D3D12QueryHeap::~D3D12QueryHeap
|
||||
|
||||
```cpp
|
||||
~D3D12QueryHeap();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
销毁 query heap 对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12QueryHeap object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- 析构函数内部直接调用 [Shutdown](Shutdown.md)
|
||||
- 会释放持有的 `ID3D12QueryHeap`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12QueryHeap.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [D3D12QueryHeap](D3D12QueryHeap.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# D3D12QueryHeap::GetCount
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
uint32_t GetCount() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前 query heap 可容纳的 query 槽位数量。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12QueryHeap object;
|
||||
// 根据上下文补齐参数后调用 D3D12QueryHeap::GetCount(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 成功初始化后返回最后一次 [Initialize](Initialize.md) 传入的 `count`
|
||||
- [Shutdown](Shutdown.md) 之后返回 `0`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12QueryHeap.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetType](GetType.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# D3D12QueryHeap::GetNativeHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
void* GetNativeHandle() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回 query heap 的原生句柄表示。
|
||||
|
||||
**返回：** `void*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12QueryHeap object;
|
||||
// 根据上下文补齐参数后调用 D3D12QueryHeap::GetNativeHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 直接返回 `m_queryHeap.Get()`
|
||||
- 与 [GetQueryHeap](GetQueryHeap.md) 返回的是同一个底层对象，只是类型被擦成了 `void*`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12QueryHeap.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetQueryHeap](GetQueryHeap.md)
|
||||
- [D3D12QueryHeap](D3D12QueryHeap.md)
|
||||
|
||||
@@ -1,30 +1,27 @@
|
||||
# D3D12QueryHeap::GetQueryHeap
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
ID3D12QueryHeap* GetQueryHeap() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回原生 `ID3D12QueryHeap*`。
|
||||
|
||||
**返回：** `ID3D12QueryHeap*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_queryHeap.Get()`
|
||||
- 不做空指针保护
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
|
||||
## 使用场景
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12QueryHeap object;
|
||||
// 根据上下文补齐参数后调用 D3D12QueryHeap::GetQueryHeap(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这是给低层 D3D12 调用方用的接口，例如命令列表需要它来执行：
|
||||
|
||||
- `BeginQuery(...)`
|
||||
- `EndQuery(...)`
|
||||
- `ResolveQueryData(...)`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12QueryHeap.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetNativeHandle](GetNativeHandle.md)
|
||||
- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
|
||||
|
||||
@@ -1,30 +1,19 @@
|
||||
# D3D12QueryHeap::GetType
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
QueryType GetType() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前 query heap 记录的 query 类型。
|
||||
|
||||
**返回：** `QueryType` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12QueryHeap object;
|
||||
// 根据上下文补齐参数后调用 D3D12QueryHeap::GetType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 成功初始化后返回最后一次 [Initialize](Initialize.md) 传入的类型
|
||||
- [Shutdown](Shutdown.md) 之后恢复为 `QueryType::Timestamp`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12QueryHeap.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetCount](GetCount.md)
|
||||
|
||||
@@ -1,33 +1,46 @@
|
||||
# D3D12QueryHeap::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
|
||||
```cpp
|
||||
bool Initialize(ID3D12Device* device, QueryType type, uint32_t count);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `device` - 参数语义详见头文件声明。
|
||||
- `type` - 参数语义详见头文件声明。
|
||||
- `count` - 参数语义详见头文件声明。
|
||||
创建原生 `ID3D12QueryHeap`。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 构造一个 `D3D12_QUERY_HEAP_DESC`
|
||||
- `desc.Count = count`
|
||||
- `desc.NodeMask = 0`
|
||||
- 根据 `type` 选择：
|
||||
- `QueryType::Timestamp` -> `D3D12_QUERY_HEAP_TYPE_TIMESTAMP`
|
||||
- `QueryType::Occlusion` -> `D3D12_QUERY_HEAP_TYPE_OCCLUSION`
|
||||
- `QueryType::PipelineStatistics` -> `D3D12_QUERY_HEAP_TYPE_PIPELINE_STATISTICS`
|
||||
- 调用 `device->CreateQueryHeap(...)`
|
||||
- 成功后缓存 `m_type` 和 `m_count`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
|
||||
## 重要说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12QueryHeap object;
|
||||
// 根据上下文补齐参数后调用 D3D12QueryHeap::Initialize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这里虽然在设备层有 [QueryHeapDesc](../../RHITypes/RHITypes.md) 抽象，但当前真正落到实现时，只使用了：
|
||||
|
||||
- `queryType`
|
||||
- `count`
|
||||
|
||||
`nodeMask` 当前没有被透传。
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 不检查 `device` 是否为空
|
||||
- 不检查 `count` 是否为 `0`
|
||||
- 不支持多节点配置
|
||||
|
||||
## 使用建议
|
||||
|
||||
如果你正在设计 profiler 或 occlusion 系统，应该把它理解成“原生 query heap 句柄创建器”，而不是完整的 query 子系统入口。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12QueryHeap.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetQueryHeap](GetQueryHeap.md)
|
||||
- [GetType](GetType.md)
|
||||
- [GetCount](GetCount.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# D3D12QueryHeap::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
|
||||
```cpp
|
||||
void Shutdown();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
释放原生 query heap 并复位本地状态。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- `m_queryHeap.Reset()`
|
||||
- `m_type = QueryType::Timestamp`
|
||||
- `m_count = 0`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12QueryHeap object;
|
||||
// 根据上下文补齐参数后调用 D3D12QueryHeap::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
当前类只持有一个 COM 对象，因此清理逻辑比较直接。它不会处理任何与 query 结果 buffer 相关的清理，因为那部分不属于这个类。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12QueryHeap.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [Destructor](Destructor.md)
|
||||
|
||||
@@ -1,34 +1,38 @@
|
||||
# D3D12Shader::Compile
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
|
||||
```cpp
|
||||
bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `sourceData` - 参数语义详见头文件声明。
|
||||
- `sourceSize` - 参数语义详见头文件声明。
|
||||
- `entryPoint` - 参数语义详见头文件声明。
|
||||
- `target` - 参数语义详见头文件声明。
|
||||
从内存中的 HLSL 源码编译 shader。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 调用 `D3DCompile(...)`
|
||||
- 编译标志同样固定为 `D3DCOMPILE_DEBUG | D3DCOMPILE_SKIP_OPTIMIZATION`
|
||||
- 不提供文件名、宏或 include handler
|
||||
- 失败时如果 `m_error` 非空，只调用 `OutputDebugStringA(errorMsg)`，不会像 [CompileFromFile](CompileFromFile.md) 一样写到 `stderr`
|
||||
- 成功后按 `target` 推断类型
|
||||
- 把 `m_uniformsCached` 设为 `false`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 使用场景
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::Compile(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这个重载主要服务于：
|
||||
|
||||
- [D3D12Device](../D3D12Device/D3D12Device.md) 的内存源码编译路径
|
||||
- 单元测试里的内嵌 HLSL 字符串
|
||||
- 运行时生成 shader 文本的实验性场景
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 仍然是 FXC 路径
|
||||
- 没有源码来源名，编译报错定位体验弱于文件编译
|
||||
- 类型推断依赖 `target` 字符串，而不是字节码内容
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [CompileFromFile](CompileFromFile.md)
|
||||
- [GetBytecode](GetBytecode.md)
|
||||
- [GetType](GetType.md)
|
||||
|
||||
@@ -1,33 +1,44 @@
|
||||
# D3D12Shader::CompileFromFile
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
|
||||
```cpp
|
||||
bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `filePath` - 参数语义详见头文件声明。
|
||||
- `entryPoint` - 参数语义详见头文件声明。
|
||||
- `target` - 参数语义详见头文件声明。
|
||||
从 HLSL 文件编译 shader。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 调用 `D3DCompileFromFile(...)`
|
||||
- 编译标志固定为 `D3DCOMPILE_DEBUG | D3DCOMPILE_SKIP_OPTIMIZATION`
|
||||
- 不传入自定义宏、include handler 或效果框架参数
|
||||
- 如果失败且 `m_error` 非空：
|
||||
- 调用 `OutputDebugStringA(errorMsg)`
|
||||
- 调用 `fprintf(stderr, "[SHADER ERROR] %s\n", errorMsg)`
|
||||
- 如果成功，则根据 `target` 推断 shader 类型
|
||||
- 最后把 `m_uniformsCached` 设为 `false`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 类型推断规则
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::CompileFromFile(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `target` 包含 `vs_` -> `ShaderType::Vertex`
|
||||
- `target` 包含 `ps_` -> `ShaderType::Fragment`
|
||||
- `target` 包含 `gs_` -> `ShaderType::Geometry`
|
||||
- `target` 包含 `cs_` -> `ShaderType::Compute`
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 不支持 DXC
|
||||
- 不支持 include 搜索策略定制
|
||||
- 不支持宏变体
|
||||
- 如果 `target` 不匹配已知前缀，类型不会进入“未知”，而是保留旧值
|
||||
|
||||
## 使用建议
|
||||
|
||||
这是当前 D3D12 后端最常见的编译入口。测试和集成样例大量通过它把 `.hlsl` 文件转成可直接用于 PSO 的字节码。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Compile](Compile.md)
|
||||
- [GetD3D12Bytecode](GetD3D12Bytecode.md)
|
||||
- [GetType](GetType.md)
|
||||
|
||||
@@ -1,28 +1,25 @@
|
||||
# D3D12Shader::D3D12Shader()
|
||||
|
||||
构造对象。
|
||||
# D3D12Shader::D3D12Shader
|
||||
|
||||
```cpp
|
||||
D3D12Shader();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
构造一个空的 D3D12 shader 对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- `m_type` 初始化为 `ShaderType::Vertex`
|
||||
- `m_uniformsCached` 初始化为 `false`
|
||||
- 字节码和错误 blob 为空
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
}
|
||||
```
|
||||
默认类型是 `Vertex` 只是一个初始值，不代表对象已经包含可用的顶点着色器字节码。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [CompileFromFile](CompileFromFile.md)
|
||||
- [Compile](Compile.md)
|
||||
- [D3D12Shader](D3D12Shader.md)
|
||||
|
||||
@@ -6,38 +6,102 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/D3D12/D3D12Shader.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Shader` public API。
|
||||
**描述**: D3D12 后端的 HLSL 编译结果包装，负责保存 FXC 生成的字节码，并提供轻量级的 shader 反射信息访问。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`D3D12Shader.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`D3D12Shader` 是当前 D3D12 后端里最核心的“编译期资源”之一。
|
||||
|
||||
## 声明概览
|
||||
它承担的职责包括：
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `D3D12Shader` | `class` | 继承自 `RHIShader` 的公开声明。 |
|
||||
- 通过 `D3DCompileFromFile(...)` 或 `D3DCompile(...)` 编译 HLSL
|
||||
- 保存编译得到的 `ID3DBlob`
|
||||
- 根据 profile 推断 shader 类型
|
||||
- 在需要时用 `D3DReflect(...)` 延迟反射出一组简化后的 `UniformInfo`
|
||||
|
||||
## 公共方法
|
||||
它当前不承担这些职责：
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [D3D12Shader()](Constructor.md) | 构造对象。 |
|
||||
| [~D3D12Shader()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [CompileFromFile](CompileFromFile.md) | 公开方法，详见头文件声明。 |
|
||||
| [Compile](Compile.md) | 公开方法，详见头文件声明。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [GetD3D12Bytecode](GetD3D12Bytecode.md) | 获取相关状态或对象。 |
|
||||
| [GetBytecode](GetBytecode.md) | 获取相关状态或对象。 |
|
||||
| [GetBytecodeSize](GetBytecodeSize.md) | 获取相关状态或对象。 |
|
||||
| [GetType](GetType.md) | 获取相关状态或对象。 |
|
||||
| [GetInputLayout](GetInputLayout.md) | 获取相关状态或对象。 |
|
||||
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
|
||||
| [IsValid](IsValid.md) | 查询当前状态。 |
|
||||
| [GetUniformInfos](GetUniformInfos.md) | 获取相关状态或对象。 |
|
||||
| [GetUniformInfo](GetUniformInfo.md) | 获取相关状态或对象。 |
|
||||
- 不使用 DXC / DXIL 编译链
|
||||
- 不管理 root signature
|
||||
- 不自动生成输入布局
|
||||
- 不暴露完整反射结果对象
|
||||
- 不缓存编译宏、include handler 或编译配置对象
|
||||
|
||||
## 设计定位
|
||||
|
||||
从商业级引擎角度看，shader 系统通常会拆成三层：
|
||||
|
||||
- 源文件与变体管理
|
||||
- 编译产物缓存
|
||||
- 运行时反射和资源绑定元数据
|
||||
|
||||
当前 `D3D12Shader` 主要覆盖了中间这一层，并且只提供了一个相对轻量的反射侧出口。它的目标是先让测试、示例和 PSO 创建链路跑通，而不是一步到位做成完整的 shader pipeline。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- 构造后默认 `m_type = ShaderType::Vertex`
|
||||
- [CompileFromFile](CompileFromFile.md) 或 [Compile](Compile.md) 成功后持有编译字节码
|
||||
- [GetUniformInfos](GetUniformInfos.md) / [GetUniformInfo](GetUniformInfo.md) 会在首次访问时触发延迟反射
|
||||
- [Shutdown](Shutdown.md) 释放字节码和错误 blob，并清空缓存的 uniform 信息
|
||||
- 析构时自动调用 [Shutdown](Shutdown.md)
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
- 编译后端使用的是 `D3DCompile*`，也就是 FXC 路径，而不是 DXC
|
||||
- 编译标志固定为 `D3DCOMPILE_DEBUG | D3DCOMPILE_SKIP_OPTIMIZATION`
|
||||
- 类型判断完全依赖 `target` 字符串里是否包含 `vs_`、`ps_`、`gs_`、`cs_`
|
||||
- 如果 `target` 不匹配上述前缀，`m_type` 会保持之前的值
|
||||
- [GetNativeHandle](GetNativeHandle.md) 返回的是 `ID3DBlob*`
|
||||
- [GetD3D12Bytecode](GetD3D12Bytecode.md) 返回的 `D3D12_SHADER_BYTECODE` 内部指针直接指向 `m_bytecode` 的内存
|
||||
- [GetInputLayout](GetInputLayout.md) 当前基本只是返回一个内部缓存字段，但这份字段没有在编译过程中自动填充
|
||||
- `UniformInfo` 反射是延迟执行的，但实现只提取了简化信息，不是完整反射模型
|
||||
|
||||
## 反射部分需要特别注意
|
||||
|
||||
当前 `CacheUniformInfos()` 只是一个“够用就好”的实现，存在几个重要限制：
|
||||
|
||||
- 只遍历 `BoundResources`
|
||||
- `info.arraySize` 当前取自 `bindDesc.NumSamples`，而不是资源绑定数组长度
|
||||
- 常量缓冲大小通过 `GetConstantBufferByIndex(bindDesc.BindPoint)` 查询，这隐含了“bind point 恰好等于 reflection constant-buffer index”的假设
|
||||
- `info.offset` 没有被填充，保持默认值
|
||||
|
||||
这意味着它更适合作为调试和轻量查询接口，而不是高可靠的绑定布局真相来源。
|
||||
|
||||
## 为什么这样设计
|
||||
|
||||
这套设计明显偏向“快速建立可工作的 D3D12 编译链路”：
|
||||
|
||||
- 集成测试和样例可以直接从 HLSL 文件生成字节码
|
||||
- pipeline state 能直接拿到 `D3D12_SHADER_BYTECODE`
|
||||
- 调用方还能通过简化反射读到资源绑定名称和槽位
|
||||
|
||||
代价是：
|
||||
|
||||
- 编译链现代化程度不高
|
||||
- 反射信息不够完整
|
||||
- 文档必须把“哪些数据是可靠的、哪些只是近似或当前实现细节”写清楚
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 没有 DXC 支持
|
||||
- 没有 include handler、自定义宏或多变体编译支持
|
||||
- 不自动生成输入布局
|
||||
- `GetType()` 在 `Shutdown()` 后不会恢复到“未知状态”，而是保留之前的类型值
|
||||
- `UniformInfo` 中的数组大小和部分常量缓冲尺寸信息在复杂 shader 下可能不准确
|
||||
- 当前工程里没有直接针对 D3D12 反射细节的专门单元测试
|
||||
|
||||
## 关键方法
|
||||
|
||||
- [CompileFromFile](CompileFromFile.md)
|
||||
- [Compile](Compile.md)
|
||||
- [GetD3D12Bytecode](GetD3D12Bytecode.md)
|
||||
- [GetUniformInfos](GetUniformInfos.md)
|
||||
- [GetUniformInfo](GetUniformInfo.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
|
||||
- [API 总索引](../../../../main.md) - 返回顶层索引
|
||||
- [D3D12](../D3D12.md)
|
||||
- [D3D12Device](../D3D12Device/D3D12Device.md)
|
||||
- [D3D12PipelineState](../D3D12PipelineState/D3D12PipelineState.md)
|
||||
- [RHIShader](../../RHIShader/RHIShader.md)
|
||||
|
||||
@@ -1,29 +1,19 @@
|
||||
# D3D12Shader::~D3D12Shader()
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
# D3D12Shader::~D3D12Shader
|
||||
|
||||
```cpp
|
||||
~D3D12Shader() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
销毁 shader 对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- 析构函数内部直接调用 [Shutdown](Shutdown.md)
|
||||
- 会释放字节码 blob、错误 blob 和缓存的反射结果
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [D3D12Shader](D3D12Shader.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# D3D12Shader::GetBytecode
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const void* GetBytecode() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回原始编译字节码缓冲的起始地址。
|
||||
|
||||
**返回：** `const void*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_bytecode` 有效，返回 `m_bytecode->GetBufferPointer()`
|
||||
- 否则返回 `nullptr`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::GetBytecode(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
如果你要构建 D3D12 PSO，优先使用 [GetD3D12Bytecode](GetD3D12Bytecode.md)。这个接口更适合调试、日志和外部序列化类场景。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetBytecodeSize](GetBytecodeSize.md)
|
||||
- [GetD3D12Bytecode](GetD3D12Bytecode.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# D3D12Shader::GetBytecodeSize
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
size_t GetBytecodeSize() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前编译字节码的大小。
|
||||
|
||||
**返回：** `size_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_bytecode` 有效，返回 `m_bytecode->GetBufferSize()`
|
||||
- 否则返回 `0`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 使用场景
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::GetBytecodeSize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
集成测试和调试输出里常用它来确认 shader 是否成功编译并生成了非零字节码。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetBytecode](GetBytecode.md)
|
||||
- [IsValid](IsValid.md)
|
||||
|
||||
@@ -1,30 +1,30 @@
|
||||
# D3D12Shader::GetD3D12Bytecode
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const D3D12_SHADER_BYTECODE GetD3D12Bytecode() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回可以直接提交给 D3D12 PSO 创建接口的 `D3D12_SHADER_BYTECODE` 结构。
|
||||
|
||||
**返回：** `const D3D12_SHADER_BYTECODE` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_bytecode` 有效：
|
||||
- `pShaderBytecode = m_bytecode->GetBufferPointer()`
|
||||
- `BytecodeLength = m_bytecode->GetBufferSize()`
|
||||
- 如果无效，返回零初始化结构
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 使用场景
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::GetD3D12Bytecode(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这是 `D3D12PipelineState` 和 D3D12 集成样例最重要的接口之一，因为 `CreateGraphicsPipelineState(...)` / `CreateComputePipelineState(...)` 直接需要它。
|
||||
|
||||
## 注意事项
|
||||
|
||||
返回的是一个按值复制的结构体，但里面的指针仍然指向当前对象持有的 blob 内存。调用方必须保证 shader 对象在 PSO 使用该字节码期间仍然有效。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetBytecode](GetBytecode.md)
|
||||
- [GetBytecodeSize](GetBytecodeSize.md)
|
||||
- [D3D12PipelineState](../D3D12PipelineState/D3D12PipelineState.md)
|
||||
|
||||
@@ -1,30 +1,28 @@
|
||||
# D3D12Shader::GetInputLayout
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const InputLayoutDesc& GetInputLayout() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前 shader 对象内部保存的输入布局描述。
|
||||
|
||||
**返回：** `const InputLayoutDesc&` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_inputLayout`
|
||||
- 当前编译路径不会自动填充它
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 正确认识
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::GetInputLayout(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这意味着对当前 D3D12 后端来说，[GetInputLayout](GetInputLayout.md) 不是一个可靠的“从 shader 自动反射出顶点输入布局”的接口。
|
||||
|
||||
实际图形 PSO 的输入布局更多来自：
|
||||
|
||||
- [GraphicsPipelineDesc](../../RHITypes/RHITypes.md) 里的显式 `inputLayout`
|
||||
- [D3D12PipelineState](../D3D12PipelineState/D3D12PipelineState.md) 的配置
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [D3D12PipelineState](../D3D12PipelineState/D3D12PipelineState.md)
|
||||
- [D3D12Shader](D3D12Shader.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# D3D12Shader::GetNativeHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
void* GetNativeHandle() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回 shader 的原生句柄表示。
|
||||
|
||||
**返回：** `void*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 返回 `m_bytecode.Get()`
|
||||
- 也就是 `ID3DBlob*`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::GetNativeHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这不是某种“可直接绑定的 D3D12 shader 对象句柄”。D3D12 图形与计算着色器真正进入管线的方式，仍然是通过字节码构造 PSO。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetD3D12Bytecode](GetD3D12Bytecode.md)
|
||||
- [IsValid](IsValid.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# D3D12Shader::GetType
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
ShaderType GetType() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前对象记录的 shader 类型。
|
||||
|
||||
**返回：** `ShaderType` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_type`
|
||||
- 它由 [CompileFromFile](CompileFromFile.md) / [Compile](Compile.md) 根据 `target` 字符串更新
|
||||
- [Shutdown](Shutdown.md) 不会重置它
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::GetType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这个返回值反映的是“最近一次成功匹配到的 profile 前缀”，不是对字节码内容做实时解析得到的结论。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [CompileFromFile](CompileFromFile.md)
|
||||
- [Compile](Compile.md)
|
||||
- [IsValid](IsValid.md)
|
||||
|
||||
@@ -1,31 +1,26 @@
|
||||
# D3D12Shader::GetUniformInfo
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const UniformInfo* GetUniformInfo(const char* name) const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `name` - 参数语义详见头文件声明。
|
||||
按名称查找一条简化的资源绑定信息。
|
||||
|
||||
**返回：** `const UniformInfo*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 会先确保 [GetUniformInfos](GetUniformInfos.md) 的缓存已经建立
|
||||
- 对 `m_uniformInfos` 做线性遍历
|
||||
- 找到同名项就返回其地址
|
||||
- 否则返回 `nullptr`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::GetUniformInfo(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这是线性查找，不是哈希表查找
|
||||
- 返回的是内部缓存元素指针，只有在对象仍然有效且缓存未被清空时才可靠
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetUniformInfos](GetUniformInfos.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,30 +1,42 @@
|
||||
# D3D12Shader::GetUniformInfos
|
||||
|
||||
获取相关状态或对象。
|
||||
|
||||
```cpp
|
||||
const std::vector<UniformInfo>& GetUniformInfos() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前 shader 的简化资源绑定信息列表。
|
||||
|
||||
**返回：** `const std::vector<UniformInfo>&` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 首次调用时会触发内部 `CacheUniformInfos()`
|
||||
- `CacheUniformInfos()` 使用 `D3DReflect(...)` 获取 shader reflection
|
||||
- 遍历 `shaderDesc.BoundResources`
|
||||
- 为每个绑定资源生成一个 `UniformInfo`
|
||||
- 后续调用直接返回缓存结果
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 当前反射内容
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::GetUniformInfos(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
每条 `UniformInfo` 至少会尝试填这些字段：
|
||||
|
||||
- `name`
|
||||
- `bindPoint`
|
||||
- `type`
|
||||
- `size`
|
||||
- `arraySize`
|
||||
|
||||
但需要注意：
|
||||
|
||||
- `arraySize` 当前来自 `bindDesc.NumSamples`
|
||||
- `offset` 没有被填充
|
||||
- 常量缓冲 `size` 的查询实现比较脆弱
|
||||
|
||||
## 使用建议
|
||||
|
||||
把它当成“当前 shader 里有哪些绑定资源的大概清单”是合理的；把它当成完整、严格、可直接驱动绑定系统的元数据来源则不够安全。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetUniformInfo](GetUniformInfo.md)
|
||||
- [D3D12Shader](D3D12Shader.md)
|
||||
|
||||
@@ -1,30 +1,26 @@
|
||||
# D3D12Shader::IsValid
|
||||
|
||||
查询当前状态。
|
||||
|
||||
```cpp
|
||||
bool IsValid() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
判断当前 shader 是否持有有效字节码。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 判断条件只有一个：`m_bytecode != nullptr`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 这意味着什么
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::IsValid(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
只要 blob 存在，它就会返回 `true`。这个接口不检查：
|
||||
|
||||
- shader 类型是否符合当前用途
|
||||
- 反射信息是否成功缓存
|
||||
- 输入布局是否存在
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [GetNativeHandle](GetNativeHandle.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -1,30 +1,34 @@
|
||||
# D3D12Shader::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
|
||||
```cpp
|
||||
void Shutdown() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
释放编译结果和反射缓存。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- `m_bytecode.Reset()`
|
||||
- `m_error.Reset()`
|
||||
- `m_uniformInfos.clear()`
|
||||
- `m_uniformsCached = false`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/D3D12/D3D12Shader.h>
|
||||
## 重要说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::D3D12Shader object;
|
||||
// 根据上下文补齐参数后调用 D3D12Shader::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
当前实现不会重置：
|
||||
|
||||
- `m_type`
|
||||
- `m_inputLayout`
|
||||
|
||||
因此在 [Shutdown](Shutdown.md) 之后：
|
||||
|
||||
- [IsValid](IsValid.md) 会变成 `false`
|
||||
- 但 [GetType](GetType.md) 仍然可能返回上一次编译留下的 shader 类型
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](D3D12Shader.md)
|
||||
- [返回模块目录](../D3D12.md)
|
||||
- [IsValid](IsValid.md)
|
||||
- [GetType](GetType.md)
|
||||
- [Destructor](Destructor.md)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# API 文档重构状态
|
||||
|
||||
**生成时间**: `2026-03-28 00:24:57`
|
||||
**生成时间**: `2026-03-28 00:40:20`
|
||||
|
||||
**来源**: `docs/api/_tools/audit_api_docs.py`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user