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

docs: update RHI API docs

Browse Source
This commit is contained in:
ssdfasd
2026-03-20 02:35:45 +08:00
parent ea756c0177
commit 070b444f8f
501 changed files with 13493 additions and 2022 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/api/rhi/shader/bind.md
View File

@@ -4,17 +4,37 @@
virtual void Bind() = 0;
```
绑定着色器到管线。
绑定着色器到渲染管线。
将当前着色器实例设置为活跃状态，使其参与后续的渲染操作。绑定后，着色器的 uniform 参数和资源将供 GPU 使用。
**线程安全：** ❌（需要在渲染线程调用）
**复杂度：** O(1)
**示例：**
```cpp
vs->Bind();
ps->Bind();
RHIShader* vertexShader = device->CreateShader();
RHIShader* fragmentShader = device->CreateShader();
vertexShader->CompileFromFile(L"shaders/vertex.cso", "VSMain", "vs_5_0");
fragmentShader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0");
vertexShader->Bind();
fragmentShader->Bind();
// 设置 uniform
float modelMatrix[16] = { /* 4x4 矩阵数据 */ };
vertexShader->SetMat4("u_modelViewProj", modelMatrix);
// 执行渲染...
vertexShader->Unbind();
fragmentShader->Unbind();
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`Unbind`](unbind.md) - 解绑着色器

29
docs/api/rhi/shader/compile-from-file.md
View File

@@ -4,23 +4,36 @@
virtual bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) = 0;
```
从文件编译着色器。
从文件加载并编译着色器。
从指定的文件路径读取着色器代码并编译为 GPU 可执行的着色器程序。该方法支持各种着色器目标平台（如 D3D12 的 `vs_5_0`、`ps_5_0` 等，或 Vulkan 的 SPIR-V）。
**参数：**
- `filePath` - 着色器源文件路径
- `entryPoint` - 入口点函数名
- `target` - 编译目标（如 `"vs_6_0"`, `"ps_6_0"`）
- `filePath` - 着色器文件路径（宽字符字符串，支持 Unicode 路径）
- `entryPoint` - 着色器入口点函数名称（如 `"VSMain"`、`"PSMain"`）
- `target` - 着色器目标配置文件（如 `"vs_5_0"`、`"ps_5_0"`、`"spv"`）
**返回：** 成功返回 `true`，失败返回 `false`
**返回：** 编译成功返回 `true`，失败返回 `false`
**复杂度：** O(n) - 取决于着色器代码复杂度
**线程安全：** ❌（多线程同时编译同一着色器可能导致未定义行为）
**复杂度：** O(n)，其中 n 为着色器代码行数
**示例：**
```cpp
shader->CompileFromFile(L"shaders/vertex.hlsl", "main", "vs_6_0");
RHIShader* vertexShader = device->CreateShader();
if (vertexShader->CompileFromFile(L"shaders/vertex.cso", "VSMain", "vs_5_0")) {
vertexShader->Bind();
// 使用着色器...
} else {
printf("Vertex shader compilation failed!\n");
}
vertexShader->Shutdown();
device->DestroyShader(vertexShader);
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`Compile`](compile.md) - 从内存数据编译着色器

35
docs/api/rhi/shader/compile.md
View File

@@ -4,18 +4,37 @@
virtual bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) = 0;
```
从内存编译着色器。
从内存数据编译着色器。
将已加载到内存中的着色器代码编译为 GPU 可执行的着色器程序。适用于从资源包、网络或自定义加载器获取着色器代码的场景。
**参数：**
- `sourceData` - 着色器源代码指针
- `sourceSize` - 源代码大小
- `entryPoint` - 入口点函数名
- `target` - 编译目标
- `sourceData` - 指向着色器源代码或字节码的指针
- `sourceSize` - 源数据大小（字节数）
- `entryPoint` - 着色器入口点函数名称
- `target` - 着色器目标配置文件
**返回：** 成功返回 `true`，失败返回 `false`
**返回：** 编译成功返回 `true`，失败返回 `false`
**复杂度：** O(n)
**线程安全：** ❌（多线程同时编译同一着色器可能导致未定义行为）
**复杂度：** O(n)，其中 n 为着色器代码行数
**示例：**
```cpp
std::vector<char> shaderBytes = LoadShaderFromResource("vertex_shader");
if (!shaderBytes.empty()) {
RHIShader* shader = device->CreateShader();
if (shader->Compile(shaderBytes.data(), shaderBytes.size(), "VSMain", "vs_5_0")) {
shader->Bind();
// 使用着色器...
}
shader->Shutdown();
}
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`CompileFromFile`](compile-from-file.md) - 从文件编译着色器

26
docs/api/rhi/shader/get-native-handle.md
View File

@@ -4,12 +4,32 @@
virtual void* GetNativeHandle() = 0;
```
获取原生 API 句柄。
获取原生图形 API 句柄。
**返回：** 原生着色器句柄
返回底层图形 API（如 D3D12、Vulkan）的原生着色器对象指针。用于需要直接访问底层 API 的高级场景，或与外部库互操作。
**返回：** 指向原生着色器对象的指针，类型取决于具体实现（如 D3D12: `ID3DBlob*`，Vulkan: `VkShaderModule`）
**线程安全：** ❌（访问底层资源，非线程安全）
**复杂度：** O(1)
**示例：**
```cpp
RHIShader* shader = device->CreateShader();
shader->CompileFromFile(L"shaders/compute.cso", "CSMain", "cs_5_0");
void* nativeHandle = shader->GetNativeHandle();
#ifdef XCENGINE_D3D12
ID3DBlob* d3dBlob = static_cast<ID3DBlob*>(nativeHandle);
// 使用 D3D12 API...
#elif defined(XCENGINE_VULKAN)
VkShaderModule vkModule = reinterpret_cast<VkShaderModule>(nativeHandle);
// 使用 Vulkan API...
#endif
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览

29
docs/api/rhi/shader/get-type.md
View File

@@ -6,10 +6,35 @@ virtual ShaderType GetType() const = 0;
获取着色器类型。
**返回：** 着色器类型枚举值
返回该着色器实例的类型，类型由 `ShaderType` 枚举定义，包括顶点着色器、像素着色器、几何着色器、计算着色器等。
**返回：** `ShaderType` 枚举值，表示着色器类型
**线程安全：** ✅（只读操作）
**复杂度：** O(1)
**示例：**
```cpp
RHIShader* shader = device->CreateShader();
shader->CompileFromFile(L"shaders/vertex.cso", "VSMain", "vs_5_0");
ShaderType type = shader->GetType();
switch (type) {
case ShaderType::Vertex:
printf("This is a vertex shader\n");
break;
case ShaderType::Fragment:
printf("This is a fragment shader\n");
break;
default:
printf("Other shader type\n");
break;
}
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`ShaderType`](./shader.md#公共属性) - 着色器类型枚举定义

27
docs/api/rhi/shader/is-valid.md
View File

@@ -4,12 +4,33 @@
virtual bool IsValid() const = 0;
```
检查着色器是否有效（已成功编译）。
检查着色器是否有效。
**返回：** 有效返回 `true`，无效返回 `false`
验证着色器是否已成功编译并可以用于渲染。应在调用 `Bind()` 之前使用此方法确保着色器可用。
**返回：** 着色器有效返回 `true`，无效返回 `false`
**线程安全：** ✅（只读操作）
**复杂度：** O(1)
**示例：**
```cpp
RHIShader* shader = device->CreateShader();
if (shader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0")) {
if (shader->IsValid()) {
shader->Bind();
// 渲染...
shader->Unbind();
} else {
printf("Shader is not valid!\n");
}
}
shader->Shutdown();
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`Bind`](bind.md) - 绑定着色器

34
docs/api/rhi/shader/set-float.md
View File

@@ -4,14 +4,38 @@
virtual void SetFloat(const char* name, float value) = 0;
```
设置浮点 uniform。
设置浮点数 uniform 变量。
通过名称查找并设置着色器中的单精度浮点数 uniform 变量。常见用途包括设置时间值、透明度、缩放因子等。
**参数：**
- `name` - uniform 变量名
- `value` - 浮点值
- `name` - uniform 变量名称
- `value` - 要设置的浮点数值
**复杂度：** O(1)
**线程安全：** ❌（需要在渲染线程调用）
**复杂度：** O(1)（通常为哈希表查找）
**示例：**
```cpp
RHIShader* shader = device->CreateShader();
shader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0");
shader->Bind();
// 设置时间
shader->SetFloat("u_time", elapsedTime);
// 设置透明度
shader->SetFloat("u_alpha", 0.5f);
// 设置雾的起始距离
shader->SetFloat("u_fogStart", 10.0f);
shader->SetFloat("u_fogEnd", 100.0f);
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`SetInt`](set-int.md) - 设置整数 uniform
- [`SetVec3`](set-vec3.md) - 设置三维向量 uniform

33
docs/api/rhi/shader/set-int.md
View File

@@ -4,14 +4,37 @@
virtual void SetInt(const char* name, int value) = 0;
```
设置整数 uniform。
设置整数 uniform 变量。
通过名称查找并设置着色器中的整数 uniform 变量。常见用途包括设置布尔值、纹理采样索引、渲染模式标志等。
**参数：**
- `name` - uniform 变量名
- `value` - 整数值
- `name` - uniform 变量名称（需与着色器代码中的变量名一致）
- `value` - 要设置的整数值
**复杂度：** O(1)
**线程安全：** ❌（需要在渲染线程调用）
**复杂度：** O(1)（通常为哈希表查找）
**示例：**
```cpp
RHIShader* shader = device->CreateShader();
shader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0");
shader->Bind();
// 设置纹理是否启用
shader->SetInt("u_texEnabled", 1);
// 设置渲染模式
shader->SetInt("u_renderMode", 2);
// 设置阴影开关
shader->SetInt("u_shadowEnabled", 0);
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`SetFloat`](set-float.md) - 设置浮点数 uniform
- [`SetVec3`](set-vec3.md) - 设置三维向量 uniform

32
docs/api/rhi/shader/set-mat4.md
View File

@@ -4,14 +4,36 @@
virtual void SetMat4(const char* name, const float* value) = 0;
```
设置 4x4 矩阵 uniform。
设置 4x4 矩阵 uniform 变量。
通过名称查找并设置着色器中的 4x4 变换矩阵 uniform 变量。常见用途包括设置模型矩阵、视图矩阵、投影矩阵及其组合（MVP）、法线矩阵等。
**参数：**
- `name` - uniform 变量名
- `value` - 矩阵数据指针（16 个 float）
- `name` - uniform 变量名称
- `value` - 指向 16 个 float 元素的数组指针
**复杂度：** O(1)
**线程安全：** ❌（需要在渲染线程调用）
**复杂度：** O(1)（通常为哈希表查找）
**示例：**
```cpp
RHIShader* shader = device->CreateShader();
shader->CompileFromFile(L"shaders/vertex.cso", "VSMain", "vs_5_0");
shader->Bind();
// 设置变换矩阵
float modelMatrix[16] = { /* 4x4 模型矩阵数据 */ };
float viewMatrix[16] = { /* 4x4 视图矩阵数据 */ };
float projMatrix[16] = { /* 4x4 投影矩阵数据 */ };
shader->SetMat4("u_model", modelMatrix);
shader->SetMat4("u_view", viewMatrix);
shader->SetMat4("u_proj", projMatrix);
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`SetVec4`](set-vec4.md) - 设置四维向量 uniform

35
docs/api/rhi/shader/set-vec3.md
View File

@@ -4,14 +4,39 @@
virtual void SetVec3(const char* name, float x, float y, float z) = 0;
```
设置三维向量 uniform。
设置三维向量 uniform 变量。
通过名称查找并设置着色器中的三维向量 uniform 变量。常见用途包括设置位置、法线、方向、光照方向、颜色等。
**参数：**
- `name` - uniform 变量名
- `x, y, z` - 向量分量
- `name` - uniform 变量名称
- `x` - 向量的 X 分量
- `y` - 向量的 Y 分量
- `z` - 向量的 Z 分量
**复杂度：** O(1)
**线程安全：** ❌（需要在渲染线程调用）
**复杂度：** O(1)（通常为哈希表查找）
**示例：**
```cpp
RHIShader* shader = device->CreateShader();
shader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0");
shader->Bind();
// 设置光照方向
shader->SetVec3("u_lightDir", 0.5f, 1.0f, 0.3f);
// 设置相机位置
shader->SetVec3("u_cameraPos", camera.x, camera.y, camera.z);
// 设置材质颜色
shader->SetVec3("u_baseColor", 1.0f, 0.8f, 0.6f);
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`SetFloat`](set-float.md) - 设置浮点数 uniform
- [`SetVec4`](set-vec4.md) - 设置四维向量 uniform

36
docs/api/rhi/shader/set-vec4.md
View File

@@ -4,14 +4,40 @@
virtual void SetVec4(const char* name, float x, float y, float z, float w) = 0;
```
设置四维向量 uniform。
设置四维向量 uniform 变量。
通过名称查找并设置着色器中的四维向量 uniform 变量。常见用途包括设置齐次坐标、颜色（带透明度）、平面方程等。
**参数：**
- `name` - uniform 变量名
- `x, y, z, w` - 向量分量
- `name` - uniform 变量名称
- `x` - 向量的 X 分量
- `y` - 向量的 Y 分量
- `z` - 向量的 Z 分量
- `w` - 向量的 W 分量（齐次坐标或透明度）
**复杂度：** O(1)
**线程安全：** ❌（需要在渲染线程调用）
**复杂度：** O(1)（通常为哈希表查找）
**示例：**
```cpp
RHIShader* shader = device->CreateShader();
shader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0");
shader->Bind();
// 设置带透明度的颜色
shader->SetVec4("u_color", 1.0f, 0.0f, 0.0f, 0.8f);
// 设置平面方程 (ax + by + cz + d = 0)
shader->SetVec4("u_clipPlane", 0.0f, 1.0f, 0.0f, 0.0f);
// 设置纹理坐标变换
shader->SetVec4("u_texOffset", 0.1f, 0.1f, 2.0f, 2.0f);
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`SetVec3`](set-vec3.md) - 设置三维向量 uniform
- [`SetMat4`](set-mat4.md) - 设置 4x4 矩阵 uniform

68
docs/api/rhi/shader/shader.md
View File

@@ -4,27 +4,44 @@
**类型**: `class` (abstract)
**描述**: GPU 着色器资源抽象接口，用于管理着色器代码的编译和绑定。
**头文件**: `XCEngine/RHI/RHIShader.h`
**描述**: 着色器接口，管理 GPU 着色器程序
## 概述
`RHIShader` 是 XCEngine RHI 模块中的抽象着色器接口类，定义了 GPU 着色器程序的标准 API。该类是所有具体着色器实现（如 D3D12Shader、VulkanShader 等）的基类，提供了统一的着色器编译、绑定和参数设置接口。
设计目的：
- 提供跨平台的着色器抽象
- 统一着色器资源管理和绑定流程
- 简化渲染管线中着色器的使用
## 公共方法
| 方法 | 描述 |
|------|------|
| [`CompileFromFile`](compile-from-file.md) | 从文件编译着色器 |
| [`Compile`](compile.md) | 从源码编译着色器 |
| [`Compile`](compile.md) | 从内存数据编译着色器 |
| [`GetType`](get-type.md) | 获取着色器类型 |
| [`IsValid`](is-valid.md) | 检查着色器是否有效 |
| [`Bind`](bind.md) | 绑定着色器 |
| [`Bind`](bind.md) | 绑定着色器到渲染管线 |
| [`Unbind`](unbind.md) | 解绑着色器 |
| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 |
| [`SetInt`](set-int.md) | 设置整数 uniform |
| [`SetFloat`](set-float.md) | 设置浮点数 uniform |
| [`SetVec3`](set-vec3.md) | 设置 vec3 uniform |
| [`SetVec4`](set-vec4.md) | 设置 vec4 uniform |
| [`SetMat4`](set-mat4.md) | 设置 mat4 uniform |
| [`Shutdown`](shutdown.md) | 关闭并释放资源 |
| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 |
| [`SetVec3`](set-vec3.md) | 设置三维向量 uniform |
| [`SetVec4`](set-vec4.md) | 设置四维向量 uniform |
| [`SetMat4`](set-mat4.md) | 设置 4x4 矩阵 uniform |
| [`Shutdown`](shutdown.md) | 释放着色器资源 |
## 着色器类型 (ShaderType)
## 公共属性
| 属性 | 类型 | 描述 |
|------|------|------|
| `ShaderType` | `enum` | 着色器类型枚举 |
### ShaderType 枚举值
| 枚举值 | 描述 |
|--------|------|
@@ -43,13 +60,36 @@
## 使用示例
```cpp
RHIShader* vs = device->CompileShader({});
vs->CompileFromFile(L"shaders/vertex.hlsl", "main", "vs_6_0");
vs->SetMat4("modelMatrix", modelMatrix);
vs->Bind();
#include "XCEngine/RHI/RHIShader.h"
#include "XCEngine/RHI/RHIDevice.h"
using namespace XCEngine::RHI;
// 通过 RHIDevice 编译着色器
ShaderCompileDesc vsDesc;
vsDesc.fileName = L"shaders/vertex.cso";
vsDesc.entryPoint = "VSMain";
vsDesc.profile = "vs_5_0";
RHIShader* vertexShader = device->CompileShader(vsDesc);
if (vertexShader && vertexShader->IsValid()) {
vertexShader->Bind();
// 设置 uniform 参数
float modelMatrix[16] = { /* 4x4 模型矩阵数据 */ };
vertexShader->SetMat4("u_modelMatrix", modelMatrix);
// 渲染...
vertexShader->Unbind();
}
if (vertexShader) {
vertexShader->Shutdown();
delete vertexShader;
}
```
## 相关文档
- [../rhi/rhi.md](../rhi.md) - RHI 模块总览
- [RHI 模块总览](../rhi.md) - RHI 模块总览
- [RHIDevice](../device/device.md) - 创建设备

21
docs/api/rhi/shader/shutdown.md
View File

@@ -6,8 +6,27 @@ virtual void Shutdown() = 0;
释放着色器资源。
销毁着色器并释放关联的 GPU 资源。调用此方法后，着色器实例将变为无效状态，不应再被使用。通常在渲染系统关闭或切换渲染设备时调用。
**线程安全：** ❌（需要在渲染线程调用，且调用后不能在其他线程访问）
**复杂度：** O(1)
**示例：**
```cpp
RHIShader* shader = device->CreateShader();
if (shader->CompileFromFile(L"shaders/vertex.cso", "VSMain", "vs_5_0")) {
shader->Bind();
// 使用着色器...
shader->Unbind();
}
shader->Shutdown();
// shader 现在已无效，不能再使用
device->DestroyShader(shader);
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览

19
docs/api/rhi/shader/unbind.md
View File

@@ -6,8 +6,25 @@ virtual void Unbind() = 0;
解绑着色器。
将当前着色器从渲染管线中移除，终止其参与后续渲染操作。通常在切换渲染状态或结束特定渲染 Pass 时调用。
**线程安全：** ❌（需要在渲染线程调用）
**复杂度：** O(1)
**示例：**
```cpp
shader->Bind();
// 渲染使用该着色器的物体...
shader->Unbind();
// 切换到其他着色器
otherShader->Bind();
// ...
```
## 相关文档
- [RHIShader 总览](shader.md) - 返回类总览
- [RHIShader](shader.md) - 返回类总览
- [`Bind`](bind.md) - 绑定着色器