docs: 重构 API 文档结构并修正源码准确性
- 重组文档目录结构: 每个模块的概述页移动到模块子目录 - 重命名 index.md 为 main.md - 修正所有模块文档中的错误: - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式 - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节 - core: 修复 types 链接错误 - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI - memory: 修复头文件路径, malloc vs operator new, 新增方法文档 - resources: 修复 Shader/Texture 链接错误 - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接 - 验证: fix_links.py 确认 0 个断裂引用
This commit is contained in:
150
docs/api/resources/shader/shader.md
Normal file
150
docs/api/resources/shader/shader.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Shader
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 着色器资源类，管理着色器源码、编译后的二进制和 uniform/attribute 信息。
|
||||
|
||||
## 概述
|
||||
|
||||
`Shader` 是 XCEngine 中的着色器资源类，继承自 `IResource`。它管理着色器源码、编译后的二进制数据、着色器类型、语言类型、uniform 列表和 attribute 列表，并持有对应的 RHI 着色器资源指针。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/Shader.h>
|
||||
```
|
||||
|
||||
## 枚举类型
|
||||
|
||||
### ShaderType
|
||||
|
||||
着色器类型枚举。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `Vertex` | 顶点着色器 |
|
||||
| `Fragment` | 片元着色器 |
|
||||
| `Geometry` | 几何着色器 |
|
||||
| `Compute` | 计算着色器 |
|
||||
| `Hull` | Hull 着色器（曲面细分控制） |
|
||||
| `Domain` | Domain 着色器（曲面细分评估） |
|
||||
|
||||
### ShaderLanguage
|
||||
|
||||
着色器语言枚举。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `GLSL` | OpenGL Shading Language |
|
||||
| `HLSL` | High-Level Shading Language |
|
||||
| `SPIRV` | SPIR-V 二进制格式 |
|
||||
|
||||
## 结构体
|
||||
|
||||
### ShaderUniform
|
||||
|
||||
Uniform 变量描述。
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `name` | `Containers::String` | Uniform 名称 |
|
||||
| `location` | `Core::uint32` | 位置/绑定点 |
|
||||
| `size` | `Core::uint32` | 大小（字节） |
|
||||
| `type` | `Core::uint32` | 类型标识 |
|
||||
|
||||
### ShaderAttribute
|
||||
|
||||
顶点属性描述。
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `name` | `Containers::String` | 属性名称 |
|
||||
| `location` | `Core::uint32` | 位置索引 |
|
||||
| `size` | `Core::uint32` | 大小（字节） |
|
||||
| `type` | `Core::uint32` | 类型标识 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 基础属性
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `ResourceType GetType() const` | 返回 `ResourceType::Shader` |
|
||||
| `const Containers::String& GetName() const` | 获取着色器名称 |
|
||||
| `const Containers::String& GetPath() const` | 获取着色器路径 |
|
||||
| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
|
||||
| `bool IsValid() const` | 检查着色器是否有效 |
|
||||
| `size_t GetMemorySize() const` | 获取内存大小 |
|
||||
| `void Release()` | 释放着色器引用 |
|
||||
|
||||
### 类型与语言
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetShaderType(ShaderType type)` | 设置着色器类型 |
|
||||
| `ShaderType GetShaderType() const` | 获取着色器类型 |
|
||||
| `void SetShaderLanguage(ShaderLanguage lang)` | 设置着色器语言 |
|
||||
| `ShaderLanguage GetShaderLanguage() const` | 获取着色器语言 |
|
||||
|
||||
### 源码与编译
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetSourceCode(const Containers::String& source)` | 设置源码 |
|
||||
| `const Containers::String& GetSourceCode() const` | 获取源码 |
|
||||
| `void SetCompiledBinary(const Containers::Array<Core::uint8>& binary)` | 设置编译后二进制 |
|
||||
| `const Containers::Array<Core::uint8>& GetCompiledBinary() const` | 获取编译后二进制 |
|
||||
|
||||
### Uniform 和 Attribute
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void AddUniform(const ShaderUniform& uniform)` | 添加 Uniform 描述 |
|
||||
| `const Containers::Array<ShaderUniform>& GetUniforms() const` | 获取 Uniform 列表 |
|
||||
| `void AddAttribute(const ShaderAttribute& attribute)` | 添加 Attribute 描述 |
|
||||
| `const Containers::Array<ShaderAttribute>& GetAttributes() const` | 获取 Attribute 列表 |
|
||||
|
||||
### RHI 资源
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `class IRHIShader* GetRHIResource() const` | 获取 RHI 着色器资源 |
|
||||
| `void SetRHIResource(class IRHIShader* resource)` | 设置 RHI 着色器资源 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 加载着色器
|
||||
ResourceHandle<Shader> vs = ResourceManager::Get().Load<Shader>("shaders/vertex.glsl");
|
||||
ResourceHandle<Shader> fs = ResourceManager::Get().Load<Shader>("shaders/fragment.glsl");
|
||||
|
||||
// 设置类型
|
||||
vs->SetShaderType(ShaderType::Vertex);
|
||||
fs->SetShaderType(ShaderType::Fragment);
|
||||
|
||||
// 设置语言
|
||||
vs->SetShaderLanguage(ShaderLanguage::GLSL);
|
||||
|
||||
// 设置编译后二进制
|
||||
vs->SetCompiledBinary(compiledSpirv);
|
||||
|
||||
// 添加 Uniform
|
||||
ShaderUniform uniform;
|
||||
uniform.name = "modelMatrix";
|
||||
uniform.location = 0;
|
||||
uniform.size = sizeof(float) * 16;
|
||||
uniform.type = 0;
|
||||
vs->AddUniform(uniform);
|
||||
|
||||
// 访问 RHI 资源
|
||||
RHIShader* rhiShader = vs->GetRHIResource();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResource](../iresource/iresource.md) - 资源基类
|
||||
- [RHIShader](../../rhi/shader/shader.md) - RHI 着色器接口
|
||||
- [Material](../material/material.md) - 材质资源
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
Reference in New Issue
Block a user