diff --git a/docs/api/containers/array/array.md b/docs/api/containers/array/array.md new file mode 100644 index 00000000..b3d33e0e --- /dev/null +++ b/docs/api/containers/array/array.md @@ -0,0 +1,94 @@ +# Array + +**命名空间**: `XCEngine::Containers` + +**类型**: `class` (template) + +**描述**: 模板动态数组容器，提供自动扩容的数组实现。 + +## 概述 + +`Array` 是一个模板动态数组容器，提供了类似 `std::vector` 的功能，但针对游戏引擎进行了优化。 + +## 类型别名 + +| 别名 | 类型 | 描述 | +|------|------|------| +| `Iterator` | `T*` | 迭代器类型 | +| `ConstIterator` | `const T*` | 常量迭代器类型 | + +## 公共方法 + +### 构造/析构 + +| 方法 | 描述 | +|------|------| +| [Constructor](constructor.md) | 构造数组实例 | +| [Copy/Move Constructor](copy-move-constructor.md) | 拷贝或移动构造 | +| [Destructor](destructor.md) | 析构函数 | +| [operator=](operator-assign.md) | 赋值运算符 | + +### 元素访问 + +| 方法 | 描述 | +|------|------| +| [operator[]](./operator-subscript.md) | 下标访问 | +| [Data](data.md) | 获取原始数据指针 | +| [Front/Back](front-back.md) | 获取首/尾元素引用 | + +### 容量管理 + +| 方法 | 描述 | +|------|------| +| [Size/Capacity/Empty](size.md) | 获取尺寸信息 | +| [Clear](clear.md) | 清空所有元素 | +| [Reserve](reserve.md) | 预留容量 | +| [Resize](resize.md) | 调整大小 | + +### 元素操作 + +| 方法 | 描述 | +|------|------| +| [PushBack](pushback.md) | 尾部添加（拷贝/移动） | +| [EmplaceBack](emplaceback.md) | 就地构造尾部添加 | +| [PopBack](popback.md) | 尾部移除 | + +### 迭代器 + +| 方法 | 描述 | +|------|------| +| [begin/end](iterator.md) | 获取迭代器 | + +### 内存分配器 + +| 方法 | 描述 | +|------|------| +| [SetAllocator](setallocator.md) | 设置内存分配器 | + +## 使用示例 + +```cpp +#include + +// 基本用法 +Containers::Array arr; +arr.PushBack(1); +arr.PushBack(2); +arr.PushBack(3); + +// 使用 initializer_list +Containers::Array arr2 = {1, 2, 3, 4, 5}; + +// 迭代 +for (auto& elem : arr) { + printf("%d\n", elem); +} + +// 使用 EmplaceBack +arr.EmplaceBack(4); +``` + +## 相关文档 + +- [HashMap](../hashmap/hashmap.md) - 哈希表容器 +- [Memory 模块](../../memory/memory.md) - 内存分配器 diff --git a/docs/api/containers/array/clear.md b/docs/api/containers/array/clear.md new file mode 100644 index 00000000..d0b59aee --- /dev/null +++ b/docs/api/containers/array/clear.md @@ -0,0 +1,36 @@ +# Array::Clear() + +```cpp +void Clear(); +``` + +清空数组中的所有元素。 + +**行为：** +- 调用所有元素的析构函数 +- 将 `Size()` 设为 0 +- **不释放底层内存**，`Capacity()` 保持不变 + +**线程安全：** ❌ 清空期间不可并发访问 + +**示例：** + +```cpp +Containers::Array arr = {1, 2, 3, 4, 5}; + +arr.Size(); // 5 +arr.Capacity(); // 8（假设自动扩容到 8） + +arr.Clear(); + +arr.Size(); // 0 +arr.Capacity(); // 8（内存未被释放） + +// 可继续添加元素，不会重新分配内存 +arr.PushBack(10); +arr.PushBack(20); +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/constructor.md b/docs/api/containers/array/constructor.md new file mode 100644 index 00000000..421f4855 --- /dev/null +++ b/docs/api/containers/array/constructor.md @@ -0,0 +1,44 @@ +# Array::Array() + +```cpp +Array() = default; +explicit Array(size_t capacity); +Array(size_t count, const T& value); +Array(std::initializer_list init); +``` + +构造一个 `Array` 实例。 + +**默认构造**：构造空数组，不分配内存。 + +**容量构造**：预分配指定容量的内存，但不设置元素数量。适用于已知大致元素数量时减少重新分配。 + +**数量构造**：创建 `count` 个元素，每个元素都是 `value` 的拷贝。使用拷贝构造，不调用默认构造。 + +**初始化列表构造**：使用 C++ initializer_list 语法创建数组。 + +**参数：** +- `capacity` - 预分配的容量大小 +- `count` - 元素数量 +- `value` - 每个元素的初始值 +- `init` - initializer_list 初始化列表 + +**示例：** + +```cpp +// 默认构造 +Containers::Array arr1; + +// 预分配容量（不设置元素） +Containers::Array arr2(100); + +// 创建 10 个元素，初始值为 42 +Containers::Array arr3(10, 42); + +// 使用 initializer_list +Containers::Array arr4 = {1, 2, 3, 4, 5}; +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/copy-move-constructor.md b/docs/api/containers/array/copy-move-constructor.md new file mode 100644 index 00000000..4811dc76 --- /dev/null +++ b/docs/api/containers/array/copy-move-constructor.md @@ -0,0 +1,44 @@ +# Array::Array() - 拷贝/移动构造 + +```cpp +Array(const Array& other); +Array(Array&& other) noexcept; +``` + +拷贝或移动构造一个新数组。 + +**拷贝构造：** +- 分配与 `other` 相同容量的内存 +- 拷贝 `other` 中所有元素 + +**移动构造：** +- 接管 `other` 的所有资源（数据指针、容量、大小） +- 将 `other` 置为空状态（`m_data = nullptr, m_size = 0, m_capacity = 0`） +- 不拷贝、不移动任何元素数据，性能 O(1) + +**参数：** +- `other` - 源数组 + +**异常：** +- 拷贝构造：元素拷贝可能抛出异常 +- 移动构造：`noexcept`，不抛出异常 + +**线程安全：** ❌ 构造期间不可并发访问 + +**示例：** + +```cpp +Containers::Array arr1 = {1, 2, 3}; + +// 拷贝构造 +Containers::Array arr2(arr1); // arr2 = {1, 2, 3} + +// 移动构造 +Containers::Array arr3(std::move(arr1)); +// arr3 = {1, 2, 3} +// arr1 现在为空，Size() == 0 +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/data.md b/docs/api/containers/array/data.md new file mode 100644 index 00000000..8cd2afbf --- /dev/null +++ b/docs/api/containers/array/data.md @@ -0,0 +1,30 @@ +# Array::Data() + +```cpp +T* Data(); +const T* Data() const; +``` + +获取指向底层数组数据的原始指针。 + +**用途：** 用于与 C 风格 API 或需要直接访问内存的场景（如与 GPU 通信）。 + +**返回：** 指向底层连续内存块的指针。如果数组为空，返回 `nullptr`。 + +**复杂度：** O(1) + +**示例：** + +```cpp +Containers::Array arr = {1.0f, 2.0f, 3.0f}; + +float* raw = arr.Data(); +size_t count = arr.Size(); + +// 可用于与 C API 交互 +// memcpy(dst, arr.Data(), arr.Size() * sizeof(float)); +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/destructor.md b/docs/api/containers/array/destructor.md new file mode 100644 index 00000000..34cce96e --- /dev/null +++ b/docs/api/containers/array/destructor.md @@ -0,0 +1,28 @@ +# Array::~Array() + +```cpp +~Array(); +``` + +销毁数组，释放所有已分配的元素并释放内存。 + +**行为：** +- 调用所有元素的析构函数 +- 释放底层数据缓冲区内存 + +**注意：** 使用 RAII 模式，无需手动调用析构。 + +**线程安全：** ❌ 析构期间不可并发访问 + +**示例：** + +```cpp +{ + Containers::Array arr = {1, 2, 3}; + // 使用 arr... +} // arr 在此自动销毁，析构函数被调用 +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/emplaceback.md b/docs/api/containers/array/emplaceback.md new file mode 100644 index 00000000..d1e3e2b6 --- /dev/null +++ b/docs/api/containers/array/emplaceback.md @@ -0,0 +1,47 @@ +# Array::EmplaceBack() + +```cpp +template +T& EmplaceBack(Args&&... args); +``` + +在数组末尾就地构造一个元素，直接在内存中构造，不产生临时对象。 + +**优势：** +- 避免拷贝或移动开销 +- 直接在底层缓冲区末尾构造元素 +- 参数完美转发，支持任意构造参数 + +**参数：** +- `args` - 转发给 `T` 构造函数的参数包 + +**返回：** 新构造元素的引用 + +**复杂度：** 均摊 O(1) + +**线程安全：** ❌ 操作期间不可并发访问 + +**示例：** + +```cpp +struct Vertex { + float x, y, z; + Vertex(float x_, float y_, float z_) : x(x_), y(y_), z(z_) {} +}; + +Containers::Array vertices; + +// EmplaceBack 直接构造，不产生临时 Vertex 对象 +vertices.EmplaceBack(1.0f, 2.0f, 3.0f); +vertices.EmplaceBack(4.0f, 5.0f, 6.0f); + +// 对比 PushBack（需要先构造临时对象） +Vertex v(7.0f, 8.0f, 9.0f); +vertices.PushBack(v); // 产生拷贝或移动 + +// EmplaceBack 更高效，始终优先使用 +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/front-back.md b/docs/api/containers/array/front-back.md new file mode 100644 index 00000000..e37d697d --- /dev/null +++ b/docs/api/containers/array/front-back.md @@ -0,0 +1,38 @@ +# Array::Front() / Back() + +```cpp +T& Front(); +const T& Front() const; +T& Back(); +const T& Back() const; +``` + +获取数组首尾元素的引用。 + +**Front()：** 返回第一个元素（`index == 0`）的引用。 + +**Back()：** 返回最后一个元素（`index == Size() - 1`）的引用。 + +**前置条件：** 数组必须非空，否则行为未定义。 + +**返回：** 首/尾元素的引用 + +**复杂度：** O(1) + +**线程安全：** ❌ 访问期间不可并发修改 + +**示例：** + +```cpp +Containers::Array arr = {10, 20, 30}; + +int& first = arr.Front(); // first == 10 +int& last = arr.Back(); // last == 30 + +arr.Front() = 5; // arr 现在是 {5, 20, 30} +arr.Back() = 100; // arr 现在是 {5, 20, 100} +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/iterator.md b/docs/api/containers/array/iterator.md new file mode 100644 index 00000000..e5d6364f --- /dev/null +++ b/docs/api/containers/array/iterator.md @@ -0,0 +1,45 @@ +# Array::begin() / end() + +```cpp +Iterator begin(); +Iterator end(); +ConstIterator begin() const; +ConstIterator end() const; +``` + +获取数组的迭代器，用于范围遍历。 + +**begin()：** 返回指向第一个元素的迭代器。如果数组为空，返回值等于 `end()`。 + +**end()：** 返回指向"最后一个元素之后"位置的迭代器（哨兵）。这是一个越界位置，不可解引用。 + +**迭代器类型：** `Iterator = T*`（原始指针），因此支持指针算术运算。 + +**复杂度：** O(1) + +**线程安全：** ❌ 迭代期间不可并发修改数组 + +**示例：** + +```cpp +Containers::Array arr = {10, 20, 30, 40, 50}; + +// 范围 for 循环（推荐） +for (int val : arr) { + printf("%d\n", val); +} + +// 手动迭代器 +for (auto it = arr.begin(); it != arr.end(); ++it) { + printf("%d\n", *it); +} + +// 指针算术（因为迭代器就是指针） +int* ptr = arr.begin(); +ptr += 2; // 指向第三个元素 +*ptr; // 30 +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/operator-assign.md b/docs/api/containers/array/operator-assign.md new file mode 100644 index 00000000..84f9bc9e --- /dev/null +++ b/docs/api/containers/array/operator-assign.md @@ -0,0 +1,44 @@ +# Array::operator= + +```cpp +Array& operator=(const Array& other); +Array& operator=(Array&& other) noexcept; +``` + +赋值运算符，用另一个数组的内容替换当前数组的内容。 + +**拷贝赋值（`=`）：** +- 先销毁当前所有元素 +- 分配与 `other` 相同大小的内存 +- 拷贝 `other` 中所有元素 + +**移动赋值（`=`）：** +- 先销毁当前所有元素 +- 接管 `other` 的所有资源（数据指针、容量） +- 将 `other` 置为空状态 + +**参数：** +- `other` - 源数组 + +**返回：** 引用自身（`*this`） + +**异常：** +- 拷贝赋值：`other` 元素拷贝可能抛出异常 + +**线程安全：** ❌ 赋值期间不可并发访问 + +**示例：** + +```cpp +Containers::Array arr1 = {1, 2, 3}; +Containers::Array arr2; + +arr2 = arr1; // 拷贝赋值，arr2 现在是 {1, 2, 3} + +Containers::Array arr3 = {4, 5}; +arr2 = std::move(arr3); // 移动赋值，arr2 现在是 {4, 5}，arr3 为空 +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/operator-subscript.md b/docs/api/containers/array/operator-subscript.md new file mode 100644 index 00000000..7f74e53c --- /dev/null +++ b/docs/api/containers/array/operator-subscript.md @@ -0,0 +1,39 @@ +# Array::operator[] + +```cpp +T& operator[](size_t index); +const T& operator[](size_t index) const; +``` + +按下标访问数组元素，不进行边界检查。 + +**行为：** +- 返回指定索引处元素的引用 +- 不进行下标越界检查，性能最优 +- 可用于读取和修改元素（非常量版本） + +**参数：** +- `index` - 元素下标，从 0 开始 + +**返回：** 元素的引用（常量版本返回常量引用） + +**复杂度：** O(1) + +**线程安全：** ❌ 访问元素期间不可并发修改 + +**注意：** 不会进行边界检查。如果 `index >= Size()`，行为未定义。如需边界检查，请使用 `At()` 方法（如果存在）或自行检查。 + +**示例：** + +```cpp +Containers::Array arr = {10, 20, 30}; + +int first = arr[0]; // first == 10 +int last = arr[2]; // last == 30 + +arr[1] = 25; // arr 现在是 {10, 25, 30} +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/popback.md b/docs/api/containers/array/popback.md new file mode 100644 index 00000000..8762a6f3 --- /dev/null +++ b/docs/api/containers/array/popback.md @@ -0,0 +1,38 @@ +# Array::PopBack() + +```cpp +void PopBack(); +``` + +移除数组末尾的元素，并调用其析构函数。 + +**前置条件：** 数组必须非空（`Size() > 0`）。如果数组为空，行为未定义。 + +**行为：** +- 将 `Size()` 减 1 +- 调用被移除元素的析构函数 +- **不释放底层内存** + +**线程安全：** ❌ 操作期间不可并发访问 + +**示例：** + +```cpp +Containers::Array arr = {10, 20, 30, 40, 50}; + +arr.Size(); // 5 + +arr.PopBack(); // 移除 50 + +arr.Size(); // 4 +// arr = {10, 20, 30, 40} + +arr.PopBack(); +arr.PopBack(); +// arr = {10, 20} +// Capacity() 仍为之前的值（如 8） +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/pushback.md b/docs/api/containers/array/pushback.md new file mode 100644 index 00000000..741ad851 --- /dev/null +++ b/docs/api/containers/array/pushback.md @@ -0,0 +1,43 @@ +# Array::PushBack() + +```cpp +void PushBack(const T& value); +void PushBack(T&& value); +``` + +在数组末尾添加一个元素。 + +**拷贝版本（`const T&`）：** +- 如果容量不足（`Size() >= Capacity()`），先扩容（容量翻倍） +- 在末尾位置拷贝构造 `value` + +**移动版本（`T&&`）：** +- 行为同拷贝版本，但使用移动构造 +- 适用于临时对象或右值，避免拷贝开销 + +**参数：** +- `value` - 要添加的元素（拷贝或移动） + +**复杂度：** 均摊 O(1)。每次添加的摊销成本为常数，因为扩容是翻倍策略。 + +**线程安全：** ❌ 操作期间不可并发访问 + +**示例：** + +```cpp +Containers::Array arr; + +// 拷贝添加 +std::string s = "hello"; +arr.PushBack(s); // s 被拷贝 + +// 移动添加（更高效） +arr.PushBack(std::string("world")); // 直接移动构造 + +// 临时对象会被隐式移动 +arr.PushBack("temporary"); // 字符串字面量构造后移动 +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/reserve.md b/docs/api/containers/array/reserve.md new file mode 100644 index 00000000..310263f2 --- /dev/null +++ b/docs/api/containers/array/reserve.md @@ -0,0 +1,39 @@ +# Array::Reserve() + +```cpp +void Reserve(size_t capacity); +``` + +预分配底层内存容量，确保能容纳至少 `capacity` 个元素而不重新分配。 + +**行为：** +- 如果 `capacity > Capacity()`，分配新的内存（容量翻倍策略） +- 如果 `capacity <= Capacity()`，什么都不做 +- 不改变 `Size()` + +**参数：** +- `capacity` - 目标容量 + +**用途：** 当已知大致元素数量时，提前分配可以避免多次重新分配带来的性能开销和迭代器失效。 + +**复杂度：** O(n)，其中 n 为当前元素数量（需要拷贝现有元素到新内存） + +**线程安全：** ❌ 操作期间不可并发访问 + +**示例：** + +```cpp +Containers::Array arr; + +// 预分配 1000 个元素的容量 +arr.Reserve(1000); + +// 之后添加 500 个元素不会触发重新分配 +for (int i = 0; i < 500; ++i) { + arr.PushBack(i); +} +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/resize.md b/docs/api/containers/array/resize.md new file mode 100644 index 00000000..f29d109b --- /dev/null +++ b/docs/api/containers/array/resize.md @@ -0,0 +1,46 @@ +# Array::Resize() + +```cpp +void Resize(size_t newSize); +void Resize(size_t newSize, const T& value); +``` + +调整数组大小。 + +**Resize(newSize)：** +- 如果 `newSize > Size()`：在末尾构造 `newSize - Size()` 个默认构造的元素 +- 如果 `newSize < Size()`：销毁末尾多出的元素 +- 如果 `newSize == Size()`：什么都不做 + +**Resize(newSize, value)：** +- 行为同上述，但扩展时使用 `value` 拷贝构造新元素，而非默认构造 + +**参数：** +- `newSize` - 新的元素数量 +- `value` - 扩展时用作填充值的元素 + +**复杂度：** O(n)，涉及元素构造/析构和可能的内存重新分配 + +**线程安全：** ❌ 操作期间不可并发访问 + +**示例：** + +```cpp +Containers::Array arr = {1, 2, 3}; + +// 扩展到 5 个元素，新元素默认构造为 0 +arr.Resize(5); +// arr = {1, 2, 3, 0, 0} + +// 缩减到 2 个元素 +arr.Resize(2); +// arr = {1, 2} + +// 扩展到 4 个，填充为 -1 +arr.Resize(4, -1); +// arr = {1, 2, -1, -1} +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/setallocator.md b/docs/api/containers/array/setallocator.md new file mode 100644 index 00000000..798b7a55 --- /dev/null +++ b/docs/api/containers/array/setallocator.md @@ -0,0 +1,38 @@ +# Array::SetAllocator() + +```cpp +void SetAllocator(Memory::IAllocator* allocator); +``` + +设置数组使用的内存分配器。 + +**用途：** 允许自定义内存分配策略，如使用对象池、固定大小分配器或调试分配器。 + +**参数：** +- `allocator` - 指向 `Memory::IAllocator` 接口的指针。如果为 `nullptr`，使用默认 `::operator new/delete`。 + +**注意：** +- 如果数组已有元素，设置新的分配器后，**不会**迁移现有元素 +- 仅影响后续的内存分配操作 +- 通常在构造后立即调用，或在数组为空时调用 + +**线程安全：** ❌ 操作期间不可并发访问 + +**示例：** + +```cpp +// 使用线性分配器（适合帧分配） +auto* linear = new Memory::LinearAllocator(1024 * 1024); + +Containers::Array arr; +arr.SetAllocator(linear); + +// 使用内存池分配器 +auto* pool = new Memory::PoolAllocator(sizeof(MyObject), 100); +Containers::Array objects; +objects.SetAllocator(pool); +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/array/size.md b/docs/api/containers/array/size.md new file mode 100644 index 00000000..1077f299 --- /dev/null +++ b/docs/api/containers/array/size.md @@ -0,0 +1,47 @@ +# Array::Size() / Capacity() / Empty() + +```cpp +size_t Size() const; +size_t Capacity() const; +bool Empty() const; +``` + +获取数组的尺寸信息。 + +**Size()：** 返回数组中的实际元素数量。 + +**Capacity()：** 返回底层内存缓冲区能容纳的元素数量，不一定等于 `Size()`。 + +**Empty()：** 返回数组是否为空（`Size() == 0`）。等价于 `Size() == 0`，但更语义化。 + +**返回：** +- `Size()` - 元素数量 +- `Capacity()` - 底层缓冲区容量 +- `Empty()` - 是否为空 + +**复杂度：** O(1) + +**示例：** + +```cpp +Containers::Array arr; + +arr.Size(); // 0 +arr.Capacity(); // 0 +arr.Empty(); // true + +arr.PushBack(1); +arr.PushBack(2); + +arr.Size(); // 2 +arr.Capacity(); // 4（自动扩容） +arr.Empty(); // false + +arr.Reserve(100); +arr.Size(); // 2（元素数量不变） +arr.Capacity(); // 100（容量增加） +``` + +## 相关文档 + +- [Array 总览](array.md) - 返回类总览 diff --git a/docs/api/containers/container-array.md b/docs/api/containers/container-array.md deleted file mode 100644 index f7065635..00000000 --- a/docs/api/containers/container-array.md +++ /dev/null @@ -1,116 +0,0 @@ -# Array - -**命名空间**: `XCEngine::Containers` - -**类型**: `class` (template) - -**描述**: 模板动态数组容器，提供自动扩容的数组实现。 - -## 概述 - -`Array` 是一个模板动态数组容器，提供了类似 `std::vector` 的功能，但针对游戏引擎进行了优化。 - -## 类型别名 - -| 别名 | 类型 | 描述 | -|------|------|------| -| `Iterator` | `T*` | 迭代器类型 | -| `ConstIterator` | `const T*` | 常量迭代器类型 | - -## 公共方法 - -### 构造/析构 - -| 方法 | 描述 | -|------|------| -| `Array() = default` | 默认构造函数 | -| `explicit Array(size_t capacity)` | 指定容量的构造函数 | -| `Array(size_t count, const T& value)` | 初始化列表构造函数 | -| `Array(std::initializer_list init)` | initializer_list 构造 | -| `~Array()` | 析构函数 | - -### 拷贝/移动构造 - -| 方法 | 描述 | -|------|------| -| `Array(const Array& other)` | 拷贝构造函数 | -| `Array(Array&& other) noexcept` | 移动构造函数 | -| `Array& operator=(const Array& other)` | 拷贝赋值运算符 | -| `Array& operator=(Array&& other) noexcept` | 移动赋值运算符 | - -### 元素访问 - -| 方法 | 描述 | -|------|------| -| `T& operator[](size_t index)` | 下标访问 | -| `const T& operator[](size_t index) const` | 常量下标访问 | -| `T* Data()` | 获取原始数据指针 | -| `const T* Data() const` | 获取常量数据指针 | -| `T& Front()` | 获取第一个元素 | -| `const T& Front() const` | 获取常量第一个元素 | -| `T& Back()` | 获取最后一个元素 | -| `const T& Back() const` | 获取常量最后一个元素 | - -### 容量管理 - -| 方法 | 描述 | -|------|------| -| `size_t Size() const` | 获取元素数量 | -| `size_t Capacity() const` | 获取容量 | -| `bool Empty() const` | 检查是否为空 | -| `void Clear()` | 清空所有元素 | -| `void Reserve(size_t capacity)` | 预留容量 | -| `void Resize(size_t newSize)` | 调整大小 | -| `void Resize(size_t newSize, const T& value)` | 调整大小并填充默认值 | - -### 元素操作 - -| 方法 | 描述 | -|------|------| -| `void PushBack(const T& value)` | 尾部添加（拷贝） | -| `void PushBack(T&& value)` | 尾部添加（移动） | -| `T& EmplaceBack(Args&&... args)` | 就地构造尾部添加 | -| `void PopBack()` | 尾部移除 | - -### 迭代器 - -| 方法 | 描述 | -|------|------| -| `Iterator begin()` | 获取开始迭代器 | -| `Iterator end()` | 获取结束迭代器 | -| `ConstIterator begin() const` | 获取常量开始迭代器 | -| `ConstIterator end() const` | 获取常量结束迭代器 | - -### 内存分配器 - -| 方法 | 描述 | -|------|------| -| `void SetAllocator(Memory::IAllocator* allocator)` | 设置内存分配器 | - -## 使用示例 - -```cpp -#include - -// 基本用法 -Containers::Array arr; -arr.PushBack(1); -arr.PushBack(2); -arr.PushBack(3); - -// 使用 initializer_list -Containers::Array arr2 = {1, 2, 3, 4, 5}; - -// 迭代 -for (auto& elem : arr) { - printf("%d\n", elem); -} - -// 使用 EmplaceBack -arr.EmplaceBack(4); -``` - -## 相关文档 - -- [HashMap](./container-hashmap.md) - 哈希表容器 -- [Memory 模块](../memory/memory-overview.md) - 内存分配器 diff --git a/docs/api/containers/container-hashmap.md b/docs/api/containers/container-hashmap.md deleted file mode 100644 index 424620f4..00000000 --- a/docs/api/containers/container-hashmap.md +++ /dev/null @@ -1,137 +0,0 @@ -# HashMap - -**命名空间**: `XCEngine::Containers` - -**类型**: `class` (template) - -**描述**: 模板哈希表容器，提供键值对存储和快速查找。 - -## 概述 - -`HashMap` 是一个模板哈希表容器，实现了分离链接法的哈希表，支持键值对的插入、查找和删除操作。 - -## 公共类型 - -### Pair - -| 成员 | 类型 | 描述 | -|------|------|------| -| `first` | `Key` | 键 | -| `second` | `Value` | 值 | - -### 迭代器 - -| 别名 | 类型 | 描述 | -|------|------|------| -| `Iterator` | `typename Array::Iterator` | 迭代器类型 | -| `ConstIterator` | `typename Array::ConstIterator` | 常量迭代器类型 | - -## 公共方法 - -### 构造/析构 - -| 方法 | 描述 | -|------|------| -| `HashMap()` | 默认构造（16 个桶） | -| `explicit HashMap(size_t bucketCount, Memory::IAllocator* allocator = nullptr)` | 指定桶数量和分配器 | -| `~HashMap()` | 析构函数 | - -### 拷贝/移动构造 - -| 方法 | 描述 | -|------|------| -| `HashMap(const HashMap& other)` | 拷贝构造 | -| `HashMap(HashMap&& other) noexcept` | 移动构造 | -| `HashMap& operator=(const HashMap& other)` | 拷贝赋值 | -| `HashMap& operator=(HashMap&& other) noexcept` | 移动赋值 | - -### 元素访问 - -| 方法 | 描述 | -|------|------| -| `Value& operator[](const Key& key)` | 下标访问（不存在时插入） | - -### 查找 - -| 方法 | 描述 | -|------|------| -| `Value* Find(const Key& key)` | 查找键对应的值指针 | -| `const Value* Find(const Key& key) const` | 常量查找 | -| `bool Contains(const Key& key) const` | 检查是否包含键 | - -### 插入/删除 - -| 方法 | 描述 | -|------|------| -| `bool Insert(const Key& key, const Value& value)` | 插入（拷贝值） | -| `bool Insert(const Key& key, Value&& value)` | 插入（移动值） | -| `bool Insert(Pair&& pair)` | 插入（移动键值对） | -| `bool Erase(const Key& key)` | 删除键对应的元素 | -| `void Clear()` | 清空所有元素 | - -### 容量 - -| 方法 | 描述 | -|------|------| -| `size_t Size() const` | 获取元素数量 | -| `bool Empty() const` | 检查是否为空 | - -### 迭代器 - -| 方法 | 描述 | -|------|------| -| `Iterator begin()` | 获取开始迭代器 | -| `Iterator end()` | 获取结束迭代器 | -| `ConstIterator begin() const` | 获取常量开始迭代器 | -| `ConstIterator end() const` | 获取常量结束迭代器 | - -### 内存分配器 - -| 方法 | 描述 | -|------|------| -| `void SetAllocator(Memory::IAllocator* allocator)` | 设置内存分配器 | - -## 实现细节 - -| 常量/成员 | 类型 | 描述 | -|------|------|------| -| `DefaultBucketCount` | `static constexpr size_t` | 默认桶数量（16） | -| `m_loadFactor` | `float` | 负载因子阈值（0.75） | - -## 使用示例 - -```cpp -#include - -// 基本用法 -Containers::HashMap map; -map.Insert("one", 1); -map.Insert("two", 2); - -// 使用下标访问 -map["three"] = 3; - -// 查找 -int* val = map.Find("one"); -if (val) { - printf("Found: %d\n", *val); -} - -// 使用 Contains -if (map.Contains("two")) { - printf("two exists\n"); -} - -// 删除 -map.Erase("one"); - -// 迭代 -for (auto& pair : map) { - printf("%s: %d\n", pair.first.CStr(), pair.second); -} -``` - -## 相关文档 - -- [Array](./container-array.md) - 动态数组 -- [Memory 模块](../memory/memory-overview.md) - 内存分配器 diff --git a/docs/api/containers/container-string.md b/docs/api/containers/container-string.md deleted file mode 100644 index 949abe72..00000000 --- a/docs/api/containers/container-string.md +++ /dev/null @@ -1,132 +0,0 @@ -# String - -**命名空间**: `XCEngine::Containers` - -**类型**: `class` - -**描述**: 动态字符串类，提供 UTF-8 编码的字符串操作。 - -## 概述 - -`String` 是一个自定义动态字符串类，提供常见的字符串操作功能，支持拷贝构造、移动构造和多种字符串操作方法。 - -## 类型别名 - -| 别名 | 类型 | 描述 | -|------|------|------| -| `SizeType` | `size_t` | 大小类型 | - -## 常量 - -| 常量 | 值 | 描述 | -|------|-----|------| -| `static constexpr SizeType npos` | `static_cast(-1)` | 无效位置标识 | - -## 公共方法 - -### 构造/析构 - -| 方法 | 描述 | -|------|------| -| `String()` | 默认构造空字符串 | -| `String(const char* str)` | 从 C 字符串构造 | -| `String(const char* str, SizeType len)` | 从指定长度的 C 字符串构造 | -| `String(const String& other)` | 拷贝构造 | -| `String(String&& other) noexcept` | 移动构造 | -| `~String()` | 析构函数 | - -### 赋值运算符 - -| 方法 | 描述 | -|------|------| -| `String& operator=(const String& other)` | 拷贝赋值 | -| `String& operator=(String&& other) noexcept` | 移动赋值 | -| `String& operator=(const char* str)` | C 字符串赋值 | - -### 连接运算符 - -| 方法 | 描述 | -|------|------| -| `String& operator+=(const String& other)` | 追加字符串 | -| `String& operator+=(const char* str)` | 追加 C 字符串 | -| `String& operator+=(char c)` | 追加字符 | - -### 字符串操作 - -| 方法 | 描述 | -|------|------| -| `String Substring(SizeType pos, SizeType len = npos) const` | 获取子串 | -| `String Trim() const` | 去除首尾空白 | -| `String ToLower() const` | 转换为小写 | -| `String ToUpper() const` | 转换为大写 | -| `SizeType Find(const char* str, SizeType pos = 0) const` | 查找子串位置 | -| `bool StartsWith(const String& prefix) const` | 检查是否以指定前缀开头 | -| `bool StartsWith(const char* prefix) const` | 检查是否以指定前缀开头 | -| `bool EndsWith(const String& suffix) const` | 检查是否以指定后缀结尾 | -| `bool EndsWith(const char* suffix) const` | 检查是否以指定后缀结尾 | - -### 元素访问 - -| 方法 | 描述 | -|------|------| -| `const char* CStr() const` | 获取 C 字符串指针 | -| `SizeType Length() const` | 获取字符串长度 | -| `SizeType Capacity() const` | 获取容量 | -| `bool Empty() const` | 检查是否为空 | -| `char& operator[](SizeType index)` | 下标访问 | -| `const char& operator[](SizeType index) const` | 常量下标访问 | - -### 容量管理 - -| 方法 | 描述 | -|------|------| -| `void Clear()` | 清空字符串 | -| `void Reserve(SizeType capacity)` | 预留容量 | -| `void Resize(SizeType newSize)` | 调整大小 | -| `void Resize(SizeType newSize, char fillChar)` | 调整大小并填充 | - -## 友元函数 - -| 函数 | 描述 | -|------|------| -| `operator+(const String& lhs, const String& rhs)` | 字符串连接 | -| `operator==(const String& lhs, const String& rhs)` | 相等比较 | -| `operator!=(const String& lhs, const String& rhs)` | 不等比较 | - -## std::hash 特化 - -```cpp -namespace std { - template<> - struct hash { - size_t operator()(const XCEngine::Containers::String& str) const noexcept; - }; -} -``` - -## 使用示例 - -```cpp -#include - -// 基本用法 -Containers::String str = "Hello"; -str += ", World!"; - -// 字符串操作 -Containers::String sub = str.Substring(0, 5); // "Hello" -bool hasPrefix = str.StartsWith("Hello"); -bool hasSuffix = str.EndsWith("!"); - -// 查找 -SizeType pos = str.Find("World"); // 返回 7 - -// 转换 -Containers::String upper = str.ToUpper(); -Containers::String lower = str.ToLower(); -``` - -## 相关文档 - -- [Array](./container-array.md) - 动态数组 -- [HashMap](./container-hashmap.md) - 哈希表 diff --git a/docs/api/containers/container-overview.md b/docs/api/containers/containers.md similarity index 79% rename from docs/api/containers/container-overview.md rename to docs/api/containers/containers.md index ab5ba066..c6d5dc30 100644 --- a/docs/api/containers/container-overview.md +++ b/docs/api/containers/containers.md @@ -16,9 +16,9 @@ Containers 模块提供了图形引擎常用的数据结构，包括动态数组 | 组件 | 文件 | 描述 | |------|------|------| -| [Array](./container-array.md) | `Array.h` | 模板动态数组，支持自动扩容 | -| [String](./container-string.md) | `String.h` | 动态字符串类 | -| [HashMap](./container-hashmap.md) | `HashMap.h` | 模板哈希表 | +| [Array](array/array.md) | `Array.h` | 模板动态数组，支持自动扩容 | +| [String](string/string.md) | `String.h` | 动态字符串类 | +| [HashMap](hashmap/hashmap.md) | `HashMap.h` | 模板哈希表 | ## 设计特点 @@ -52,4 +52,4 @@ int* value = map.Find("key1"); ## 相关文档 -- [Memory 模块](../memory/memory-overview.md) - 内存分配器接口 +- [Memory 模块](../memory/memory.md) - 内存分配器接口 diff --git a/docs/api/containers/hashmap/clear.md b/docs/api/containers/hashmap/clear.md new file mode 100644 index 00000000..fc8facda --- /dev/null +++ b/docs/api/containers/hashmap/clear.md @@ -0,0 +1,34 @@ +# HashMap::Clear + +```cpp +void Clear(); +``` + +清空哈希表中的所有元素，将元素数量置为 0。桶的数量保持不变。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(m_bucketCount)，需要清空所有桶 + +**示例：** + +```cpp +XCEngine::Containers::HashMap map; +map.Insert(1, "one"); +map.Insert(2, "two"); +map.Insert(3, "three"); + +std::cout << "Size before clear: " << map.Size() << std::endl; // 输出 3 + +map.Clear(); + +std::cout << "Size after clear: " << map.Size() << std::endl; // 输出 0 +std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "yes" +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 +- [Erase](erase.md) - 删除单个元素 diff --git a/docs/api/containers/hashmap/constructor.md b/docs/api/containers/hashmap/constructor.md new file mode 100644 index 00000000..6930a52a --- /dev/null +++ b/docs/api/containers/hashmap/constructor.md @@ -0,0 +1,31 @@ +# HashMap::HashMap + +```cpp +HashMap(); +explicit HashMap(size_t bucketCount, Memory::IAllocator* allocator = nullptr); +``` + +构造哈希表实例。 + +**参数：** +- `bucketCount` - 初始桶的数量，默认为 16。若传入 0，则自动调整为 16。 +- `allocator` - 内存分配器指针，默认为 `nullptr`（使用默认分配器）。 + +**返回：** 无 + +**复杂度：** O(bucketCount)，需要初始化所有桶 + +**示例：** + +```cpp +XCEngine::Containers::HashMap map1; + +XCEngine::Containers::HashMap map2(32); + +auto customAllocator = XCEngine::Memory::GetDefaultAllocator(); +XCEngine::Containers::HashMap map3(64, customAllocator); +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 diff --git a/docs/api/containers/hashmap/contains.md b/docs/api/containers/hashmap/contains.md new file mode 100644 index 00000000..ff0f5dba --- /dev/null +++ b/docs/api/containers/hashmap/contains.md @@ -0,0 +1,35 @@ +# HashMap::Contains + +```cpp +bool Contains(const Key& key) const; +``` + +检查哈希表中是否包含指定的键。 + +**参数：** +- `key` - 要检查的键 + +**返回：** 如果键存在返回 `true`，否则返回 `false`。 + +**复杂度：** O(1) 平均，最坏 O(n) + +**示例：** + +```cpp +XCEngine::Containers::HashMap map; +map.Insert(1, "one"); +map.Insert(2, "two"); + +if (map.Contains(1)) { + std::cout << "Key 1 exists" << std::endl; // 输出 "Key 1 exists" +} + +if (!map.Contains(99)) { + std::cout << "Key 99 does not exist" << std::endl; // 输出 "Key 99 does not exist" +} +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 +- [Find](find.md) - 查找键对应的值 diff --git a/docs/api/containers/hashmap/copy-move.md b/docs/api/containers/hashmap/copy-move.md new file mode 100644 index 00000000..86364468 --- /dev/null +++ b/docs/api/containers/hashmap/copy-move.md @@ -0,0 +1,34 @@ +# HashMap::Copy/Move 构造 + +```cpp +HashMap(const HashMap& other); +HashMap(HashMap&& other) noexcept; +``` + +拷贝构造和移动构造。 + +**参数：** +- `other` - 源哈希表（拷贝版本为 `const` 引用，移动版本为右值引用） + +**返回：** 无（构造函数） + +**复杂度：** +- 拷贝构造：O(m_bucketCount + other.m_size) +- 移动构造：O(1)，直接接管源对象的内部资源 + +**示例：** + +```cpp +XCEngine::Containers::HashMap map1; +map1.Insert(1, "hello"); +map1.Insert(2, "world"); + +XCEngine::Containers::HashMap map2(map1); // 拷贝构造 + +XCEngine::Containers::HashMap map3(std::move(map1)); // 移动构造，map1 在此调用后状态不确定 +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 +- [operator=](operator-assign.md) - 赋值运算符 diff --git a/docs/api/containers/hashmap/destructor.md b/docs/api/containers/hashmap/destructor.md new file mode 100644 index 00000000..1274b167 --- /dev/null +++ b/docs/api/containers/hashmap/destructor.md @@ -0,0 +1,27 @@ +# HashMap::~HashMap + +```cpp +~HashMap(); +``` + +析构函数，清空所有元素并释放资源。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n)，需要清空所有桶中的元素 + +**示例：** + +```cpp +{ + XCEngine::Containers::HashMap map; + map.Insert(1, "hello"); + map.Insert(2, "world"); +} // map 在此自动析构，所有资源被正确释放 +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 diff --git a/docs/api/containers/hashmap/erase.md b/docs/api/containers/hashmap/erase.md new file mode 100644 index 00000000..02df0ead --- /dev/null +++ b/docs/api/containers/hashmap/erase.md @@ -0,0 +1,37 @@ +# HashMap::Erase + +```cpp +bool Erase(const Key& key); +``` + +删除指定键对应的元素。 + +**参数：** +- `key` - 要删除的键 + +**返回：** 如果元素被删除返回 `true`，如果键不存在返回 `false`。 + +**复杂度：** O(1) 平均，最坏 O(n) + +**示例：** + +```cpp +XCEngine::Containers::HashMap map; +map.Insert(1, "one"); +map.Insert(2, "two"); +map.Insert(3, "three"); + +bool erased = map.Erase(2); // 返回 true + +if (!map.Contains(2)) { + std::cout << "Key 2 removed" << std::endl; // 输出 "Key 2 removed" +} + +bool notErased = map.Erase(99); // 返回 false，键不存在 +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 +- [Insert](insert.md) - 插入键值对 +- [Clear](clear.md) - 清空所有元素 diff --git a/docs/api/containers/hashmap/find.md b/docs/api/containers/hashmap/find.md new file mode 100644 index 00000000..5f6c78f7 --- /dev/null +++ b/docs/api/containers/hashmap/find.md @@ -0,0 +1,39 @@ +# HashMap::Find + +```cpp +Value* Find(const Key& key); +const Value* Find(const Key& key) const; +``` + +根据键查找对应的值指针。 + +**参数：** +- `key` - 要查找的键 + +**返回：** 如果找到，返回指向值的指针；否则返回 `nullptr`。 + +**复杂度：** O(1) 平均，最坏 O(n)（同一桶中有多个键发生哈希冲突） + +**示例：** + +```cpp +XCEngine::Containers::HashMap map; +map.Insert(1, "one"); +map.Insert(2, "two"); + +const char* value1 = map.Find(1); +if (value1) { + std::cout << "Found: " << value1 << std::endl; // 输出 "Found: one" +} + +const char* value2 = map.Find(99); +if (!value2) { + std::cout << "Not found" << std::endl; // 输出 "Not found" +} +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 +- [Contains](contains.md) - 检查是否包含键 +- [operator[]](./operator-subscript.md) - 下标访问 diff --git a/docs/api/containers/hashmap/hashmap.md b/docs/api/containers/hashmap/hashmap.md new file mode 100644 index 00000000..071a2e16 --- /dev/null +++ b/docs/api/containers/hashmap/hashmap.md @@ -0,0 +1,112 @@ +# HashMap + +**命名空间**: `XCEngine::Containers` + +**类型**: `class` (template) + +**描述**: 模板哈希表容器，提供键值对存储和快速查找。 + +## 概述 + +`HashMap` 是一个模板哈希表容器，实现了分离链接法的哈希表，支持键值对的插入、查找和删除操作。 + +## 公共类型 + +### Pair + +| 成员 | 类型 | 描述 | +|------|------|------| +| `first` | `Key` | 键 | +| `second` | `Value` | 值 | + +### 迭代器 + +| 别名 | 类型 | 描述 | +|------|------|------| +| `Iterator` | `typename Array::Iterator` | 迭代器类型 | +| `ConstIterator` | `typename Array::ConstIterator` | 常量迭代器类型 | + +## 公共方法 + +### 构造/析构 + +| 方法 | 描述 | +|------|------| +| [Constructor](constructor.md) | 构造哈希表实例 | +| [Destructor](destructor.md) | 析构函数 | +| [operator=](operator-assign.md) | 赋值运算符 | +| [Copy/Move](copy-move.md) | 拷贝/移动构造 | + +### 元素访问 + +| 方法 | 描述 | +|------|------| +| [operator[]](./operator-subscript.md) | 下标访问（不存在时插入） | + +### 查找 + +| 方法 | 描述 | +|------|------| +| [Find](find.md) | 查找键对应的值指针 | +| [Contains](contains.md) | 检查是否包含键 | + +### 插入/删除 + +| 方法 | 描述 | +|------|------| +| [Insert](insert.md) | 插入键值对 | +| [Erase](erase.md) | 删除键对应的元素 | +| [Clear](clear.md) | 清空所有元素 | + +### 容量 + +| 方法 | 描述 | +|------|------| +| [Size/Empty](size.md) | 获取元素数量 | + +### 迭代器 + +| 方法 | 描述 | +|------|------| +| [begin/end](iterator.md) | 获取迭代器 | + +### 内存分配器 + +| 方法 | 描述 | +|------|------| +| [SetAllocator](setallocator.md) | 设置内存分配器 | + +## 使用示例 + +```cpp +#include "Containers/HashMap.h" +#include + +int main() { + XCEngine::Containers::HashMap map; + + map.Insert(1, "one"); + map.Insert(2, "two"); + map.Insert(3, "three"); + + if (const char* value = map.Find(1)) { + std::cout << "Key 1: " << value << std::endl; + } + + std::cout << "Size: " << map.Size() << std::endl; + + for (auto it = map.begin(); it != map.end(); ++it) { + std::cout << it->first << " -> " << it->second << std::endl; + } + + map.Erase(2); + std::cout << "Contains 2: " << (map.Contains(2) ? "yes" : "no") << std::endl; + + return 0; +} +``` + +## 相关文档 + +- [Array](../array/array.md) - 动态数组 +- [Memory 模块](../../memory/memory.md) - 内存分配器 diff --git a/docs/api/containers/hashmap/insert.md b/docs/api/containers/hashmap/insert.md new file mode 100644 index 00000000..ad582ac2 --- /dev/null +++ b/docs/api/containers/hashmap/insert.md @@ -0,0 +1,38 @@ +# HashMap::Insert + +```cpp +bool Insert(const Key& key, const Value& value); +bool Insert(const Key& key, Value&& value); +bool Insert(Pair&& pair); +``` + +插入键值对。如果键已存在，则更新其值并返回 `false`；否则插入新元素并返回 `true`。 + +**参数：** +- `key` - 要插入的键 +- `value` - 要插入的值（const 版本为拷贝，&& 版本为移动） +- `pair` - 包含键值对的 `Pair` 结构（右值） + +**返回：** 如果插入成功（键不存在）返回 `true`，如果键已存在（更新值）返回 `false`。 + +**复杂度：** O(1) 平均，最坏 O(n)（包括可能的 rehash） + +**示例：** + +```cpp +XCEngine::Containers::HashMap map; + +bool inserted1 = map.Insert(1, "one"); // 返回 true +bool inserted2 = map.Insert(1, "ONE"); // 返回 false，更新现有值 + +bool inserted3 = map.Insert(2, std::string("two")); // 移动语义版本 + +XCEngine::Containers::HashMap::Pair p{3, "three"}; +bool inserted4 = map.Insert(std::move(p)); // Pair 移动版本 +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 +- [operator[]](./operator-subscript.md) - 下标访问（总是插入） +- [Erase](erase.md) - 删除键对应的元素 diff --git a/docs/api/containers/hashmap/iterator.md b/docs/api/containers/hashmap/iterator.md new file mode 100644 index 00000000..49311178 --- /dev/null +++ b/docs/api/containers/hashmap/iterator.md @@ -0,0 +1,44 @@ +# HashMap::begin / end + +```cpp +Iterator begin(); +Iterator end(); +ConstIterator begin() const; +ConstIterator end() const; +``` + +获取哈希表的迭代器。迭代器遍历所有桶中的元素。 + +**参数：** 无 + +**返回：** 返回指向第一个元素和末尾（最后一个元素之后）位置的迭代器。 + +**复杂度：** O(1) + +**示例：** + +```cpp +XCEngine::Containers::HashMap map; +map.Insert(1, "one"); +map.Insert(2, "two"); +map.Insert(3, "three"); + +for (auto it = map.begin(); it != map.end(); ++it) { + std::cout << it->first << " -> " << it->second << std::endl; +} +// 输出顺序不确定，取决于哈希桶的内部布局 + +// 范围 for 循环（需要 C++20 或手动实现 begin/end） +for (auto& [key, value] : map) { + std::cout << key << " -> " << value << std::endl; +} + +// 常量迭代器 +for (auto it = map.cbegin(); it != map.cend(); ++it) { + std::cout << it->first << " -> " << it->second << std::endl; +} +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 diff --git a/docs/api/containers/hashmap/operator-assign.md b/docs/api/containers/hashmap/operator-assign.md new file mode 100644 index 00000000..d439ab96 --- /dev/null +++ b/docs/api/containers/hashmap/operator-assign.md @@ -0,0 +1,36 @@ +# HashMap::operator= + +```cpp +HashMap& operator=(const HashMap& other); +HashMap& operator=(HashMap&& other) noexcept; +``` + +赋值运算符，用另一个 HashMap 的内容替换当前内容。 + +**参数：** +- `other` - 源哈希表（拷贝版本为 `const` 引用，移动版本为右值引用） + +**返回：** 对当前对象的引用 (`*this`) + +**复杂度：** +- 拷贝赋值：O(m_bucketCount + other.m_size) +- 移动赋值：O(m_size)，需要先清空当前内容 + +**示例：** + +```cpp +XCEngine::Containers::HashMap map1; +map1.Insert(1, "one"); +map1.Insert(2, "two"); + +XCEngine::Containers::HashMap map2; +map2 = map1; // 拷贝赋值 + +XCEngine::Containers::HashMap map3; +map3 = std::move(map1); // 移动赋值，map1 在此调用后状态不确定 +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 +- [Copy/Move](copy-move.md) - 拷贝/移动构造 diff --git a/docs/api/containers/hashmap/operator-subscript.md b/docs/api/containers/hashmap/operator-subscript.md new file mode 100644 index 00000000..6f771571 --- /dev/null +++ b/docs/api/containers/hashmap/operator-subscript.md @@ -0,0 +1,33 @@ +# HashMap::operator[] + +```cpp +Value& operator[](const Key& key); +``` + +按下标访问键对应的值。如果键不存在，则插入一个默认构造的值并返回引用。 + +**参数：** +- `key` - 要访问的键 + +**返回：** 对应值的引用。如果键不存在，则返回一个默认构造的 `Value` 的引用。 + +**复杂度：** O(1) 平均，最坏 O(n)（发生 rehash 时） + +**示例：** + +```cpp +XCEngine::Containers::HashMap map; + +map[1] = "one"; // 插入键 1，值 "one" +map[2] = "two"; // 插入键 2，值 "two" + +std::string& value = map[1]; // 获取键 1 对应的值，结果为 "one" + +map[3]; // 插入键 3，值为 std::string 的默认构造值 +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 +- [Find](find.md) - 查找键对应的值（不插入） +- [Insert](insert.md) - 插入键值对（不覆盖已存在的键） diff --git a/docs/api/containers/hashmap/setallocator.md b/docs/api/containers/hashmap/setallocator.md new file mode 100644 index 00000000..641cf959 --- /dev/null +++ b/docs/api/containers/hashmap/setallocator.md @@ -0,0 +1,28 @@ +# HashMap::SetAllocator + +```cpp +void SetAllocator(Memory::IAllocator* allocator); +``` + +设置哈希表的内存分配器。 + +**参数：** +- `allocator` - 内存分配器指针，可以为 `nullptr`（使用默认分配器） + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +XCEngine::Containers::HashMap map; + +auto customAllocator = XCEngine::Memory::GetDefaultAllocator(); +map.SetAllocator(customAllocator); +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 +- [Memory 模块](../../memory/memory.md) - 内存分配器 diff --git a/docs/api/containers/hashmap/size.md b/docs/api/containers/hashmap/size.md new file mode 100644 index 00000000..40b40be2 --- /dev/null +++ b/docs/api/containers/hashmap/size.md @@ -0,0 +1,35 @@ +# HashMap::Size / Empty + +```cpp +size_t Size() const; +bool Empty() const; +``` + +获取哈希表的元素数量或判断是否为空。 + +**参数：** 无 + +**返回：** +- `Size()` - 返回元素数量 +- `Empty()` - 容器为空返回 `true`，否则返回 `false` + +**复杂度：** O(1) + +**示例：** + +```cpp +XCEngine::Containers::HashMap map; + +std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "yes" +std::cout << "Size: " << map.Size() << std::endl; // 输出 0 + +map.Insert(1, "one"); +map.Insert(2, "two"); + +std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "no" +std::cout << "Size: " << map.Size() << std::endl; // 输出 2 +``` + +## 相关文档 + +- [HashMap 总览](hashmap.md) - 返回类总览 diff --git a/docs/api/containers/string/clear.md b/docs/api/containers/string/clear.md new file mode 100644 index 00000000..af9c064c --- /dev/null +++ b/docs/api/containers/string/clear.md @@ -0,0 +1,39 @@ +# String::Clear + +```cpp +void Clear(); +``` + +清空字符串内容，将长度设为 0，但不释放已分配的内存。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s("Hello World"); + std::cout << "Before clear - Length: " << s.Length() + << ", Capacity: " << s.Capacity() << std::endl; + // 输出: Before clear - Length: 11, Capacity: 12 + + s.Clear(); + std::cout << "After clear - Length: " << s.Length() + << ", Capacity: " << s.Capacity() << std::endl; + // 输出: After clear - Length: 0, Capacity: 12 + std::cout << "Empty: " << s.Empty() << std::endl; // 输出: Empty: 1 + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 +- [Reserve / Resize](reserve-resize.md) - 内存管理 diff --git a/docs/api/containers/string/constructor.md b/docs/api/containers/string/constructor.md new file mode 100644 index 00000000..52905e01 --- /dev/null +++ b/docs/api/containers/string/constructor.md @@ -0,0 +1,49 @@ +# String::String + +```cpp +String(); +String(const char* str); +String(const char* str, SizeType len); +String(const char* str, size_t len); // alias +String(const String& other); +String(String&& other) noexcept; +``` + +构造 String 对象。提供多种构造方式以适应不同的使用场景。 + +**参数：** +- `str` - 以 null 结尾的 C 字符串 +- `len` - 要复制的字符数量 +- `other` - 另一个 String 对象（用于拷贝构造或移动构造） + +**返回：** 无 + +**复杂度：** +- 默认构造：O(1) +- 从 `const char*` 构造：O(n)，其中 n 为字符串长度 +- 拷贝构造：O(n) +- 移动构造：O(1) + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s1; // 默认构造 + XCEngine::Containers::String s2("hello"); // 从 C 字符串构造 + XCEngine::Containers::String s3("world", 3); // 从 C 字符串前 n 个字符构造 + XCEngine::Containers::String s4(s2); // 拷贝构造 + XCEngine::Containers::String s5(std::move(s4)); // 移动构造 + + std::cout << s2.CStr() << std::endl; // 输出: hello + std::cout << s3.CStr() << std::endl; // 输出: wor + std::cout << s4.CStr() << std::endl; // 输出: hello + std::cout << s5.CStr() << std::endl; // 输出: hello + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 diff --git a/docs/api/containers/string/cstr.md b/docs/api/containers/string/cstr.md new file mode 100644 index 00000000..70729622 --- /dev/null +++ b/docs/api/containers/string/cstr.md @@ -0,0 +1,36 @@ +# String::CStr + +```cpp +const char* CStr() const; +``` + +返回指向以 null 结尾的 C 字符串的指针。 + +**参数：** 无 + +**返回：** 指向内部字符数组的指针，以 null 结尾 + +**复杂度：** O(1) + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include +#include + +int main() { + XCEngine::Containers::String s("Hello World"); + + const char* cstr = s.CStr(); + std::cout << cstr << std::endl; // 输出: Hello World + + std::cout << "Length: " << std::strlen(cstr) << std::endl; // 输出: Length: 11 + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 +- [Length](size.md) - 获取长度 diff --git a/docs/api/containers/string/destructor.md b/docs/api/containers/string/destructor.md new file mode 100644 index 00000000..49375c9e --- /dev/null +++ b/docs/api/containers/string/destructor.md @@ -0,0 +1,31 @@ +# String::~String + +```cpp +~String(); +``` + +销毁 String 对象，释放所有动态分配的内存。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" + +int main() { + { + XCEngine::Containers::String s("hello"); + // s 在作用域结束时自动销毁 + } + // 内存已释放 + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 diff --git a/docs/api/containers/string/ends-with.md b/docs/api/containers/string/ends-with.md new file mode 100644 index 00000000..aabe335e --- /dev/null +++ b/docs/api/containers/string/ends-with.md @@ -0,0 +1,39 @@ +# String::EndsWith + +```cpp +bool EndsWith(const String& suffix) const; +bool EndsWith(const char* suffix) const; +``` + +检查字符串是否以指定的后缀结尾。 + +**参数：** +- `suffix` - 要检查的后缀（String 或 const char*） + +**返回：** 如果字符串以指定后缀结尾则返回 `true`，否则返回 `false` + +**复杂度：** O(n)，其中 n 为后缀长度 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s("Hello World"); + + std::cout << std::boolalpha; + std::cout << s.EndsWith("World") << std::endl; // 输出: true + std::cout << s.EndsWith(XCEngine::Containers::String("World")) << std::endl; // 输出: true + std::cout << s.EndsWith("Hello") << std::endl; // 输出: false + std::cout << s.EndsWith("") << std::endl; // 输出: true + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 +- [StartsWith](starts-with.md) - 检查前缀 +- [Find](find.md) - 查找子串 diff --git a/docs/api/containers/string/find.md b/docs/api/containers/string/find.md new file mode 100644 index 00000000..652e3d85 --- /dev/null +++ b/docs/api/containers/string/find.md @@ -0,0 +1,47 @@ +# String::Find + +```cpp +SizeType Find(const char* str, SizeType pos = 0) const; +``` + +在字符串中查找子串 `str`，从位置 `pos` 开始搜索。 + +**参数：** +- `str` - 要查找的以 null 结尾的 C 字符串 +- `pos` - 开始搜索的位置，默认为 0 + +**返回：** 子串首次出现的起始位置；如果未找到，返回 `String::npos` + +**复杂度：** O(n * m)，其中 n 为原字符串长度，m 为要查找的字符串长度 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s("Hello World, Hello Universe"); + + XCEngine::Containers::String::SizeType pos1 = s.Find("World"); + std::cout << "Found at: " << pos1 << std::endl; // 输出: Found at: 6 + + XCEngine::Containers::String::SizeType pos2 = s.Find("Hello", 0); + std::cout << "First 'Hello' at: " << pos2 << std::endl; // 输出: First 'Hello' at: 0 + + XCEngine::Containers::String::SizeType pos3 = s.Find("Hello", 7); + std::cout << "Second 'Hello' at: " << pos3 << std::endl; // 输出: Second 'Hello' at: 13 + + XCEngine::Containers::String::SizeType pos4 = s.Find("NotFound"); + if (pos4 == XCEngine::Containers::String::npos) { + std::cout << "Not found" << std::endl; // 输出: Not found + } + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 +- [StartsWith](starts-with.md) - 检查前缀 +- [EndsWith](ends-with.md) - 检查后缀 diff --git a/docs/api/containers/string/operator-assign.md b/docs/api/containers/string/operator-assign.md new file mode 100644 index 00000000..e6bd49a2 --- /dev/null +++ b/docs/api/containers/string/operator-assign.md @@ -0,0 +1,47 @@ +# String::operator= + +```cpp +String& operator=(const String& other); +String& operator=(String&& other) noexcept; +String& operator=(const char* str); +``` + +将新的值赋给 String 对象，替换原有的内容。 + +**参数：** +- `other` - 另一个 String 对象（拷贝赋值或移动赋值） +- `str` - 以 null 结尾的 C 字符串 + +**返回：** `*this`，支持链式调用 + +**复杂度：** +- 拷贝赋值：O(n)，n 为 other 的长度 +- 移动赋值：O(1) +- 从 `const char*` 赋值：O(n)，n 为 str 的长度 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s1; + XCEngine::Containers::String s2("hello"); + + s1 = s2; // 拷贝赋值 + std::cout << s1.CStr() << std::endl; // 输出: hello + + s1 = "world"; // 从 const char* 赋值 + std::cout << s1.CStr() << std::endl; // 输出: world + + XCEngine::Containers::String s3("moved"); + s1 = std::move(s3); // 移动赋值 + std::cout << s1.CStr() << std::endl; // 输出: moved + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 diff --git a/docs/api/containers/string/operator-equal.md b/docs/api/containers/string/operator-equal.md new file mode 100644 index 00000000..5d998d50 --- /dev/null +++ b/docs/api/containers/string/operator-equal.md @@ -0,0 +1,43 @@ +# operator== / operator!= + +```cpp +inline bool operator==(const String& lhs, const String& rhs); +inline bool operator!=(const String& lhs, const String& rhs); +``` + +判断两个字符串是否相等或不相等。 + +**operator==：** 比较两个字符串的长度是否相等，以及内容是否相同。 + +**operator!=：** 相当于 `!(lhs == rhs)`。 + +**参数：** +- `lhs` - 左侧字符串 +- `rhs` - 右侧字符串 + +**返回：** 布尔值，表示比较结果 + +**复杂度：** O(n)，其中 n 为字符串长度 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s1("Hello"); + XCEngine::Containers::String s2("Hello"); + XCEngine::Containers::String s3("World"); + + std::cout << std::boolalpha; + std::cout << (s1 == s2) << std::endl; // 输出: true + std::cout << (s1 == s3) << std::endl; // 输出: false + std::cout << (s1 != s3) << std::endl; // 输出: true + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 diff --git a/docs/api/containers/string/operator-plus-assign.md b/docs/api/containers/string/operator-plus-assign.md new file mode 100644 index 00000000..53c3377a --- /dev/null +++ b/docs/api/containers/string/operator-plus-assign.md @@ -0,0 +1,43 @@ +# String::operator+= + +```cpp +String& operator+=(const String& other); +String& operator+=(const char* str); +String& operator+=(char c); +``` + +将指定的内容追加到当前 String 的末尾。 + +**参数：** +- `other` - 要追加的 String 对象 +- `str` - 要追加的以 null 结尾的 C 字符串 +- `c` - 要追加的单个字符 + +**返回：** `*this`，支持链式调用 + +**复杂度：** O(n)，其中 n 为被追加内容的长度。可能会触发重新分配，但均摊复杂度为 O(1)。 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s("Hello"); + + s += XCEngine::Containers::String(" World"); // 追加 String + std::cout << s.CStr() << std::endl; // 输出: Hello World + + s += "!"; // 追加 const char* + std::cout << s.CStr() << std::endl; // 输出: Hello World! + + s += '?'; // 追加 char + std::cout << s.CStr() << std::endl; // 输出: Hello World!? + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 diff --git a/docs/api/containers/string/operator-plus.md b/docs/api/containers/string/operator-plus.md new file mode 100644 index 00000000..8e261efd --- /dev/null +++ b/docs/api/containers/string/operator-plus.md @@ -0,0 +1,39 @@ +# operator+ + +```cpp +inline String operator+(const String& lhs, const String& rhs); +``` + +将两个 String 对象连接，返回一个新的 String 对象。 + +**参数：** +- `lhs` - 左侧的 String 对象 +- `rhs` - 右侧的 String 对象 + +**返回：** 新的 String 对象，内容为 lhs 和 rhs 的拼接 + +**复杂度：** O(n + m)，其中 n 和 m 分别为 lhs 和 rhs 的长度 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s1("Hello"); + XCEngine::Containers::String s2(" World"); + XCEngine::Containers::String s3 = s1 + s2; + + std::cout << s3.CStr() << std::endl; // 输出: Hello World + + XCEngine::Containers::String s4 = XCEngine::Containers::String("Foo") + "Bar"; + std::cout << s4.CStr() << std::endl; // 输出: FooBar + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 +- [operator+=](operator-plus-assign.md) - 追加操作 diff --git a/docs/api/containers/string/operator-subscript.md b/docs/api/containers/string/operator-subscript.md new file mode 100644 index 00000000..bb010214 --- /dev/null +++ b/docs/api/containers/string/operator-subscript.md @@ -0,0 +1,51 @@ +# String::operator[] + +```cpp +char& operator[](SizeType index); +const char& operator[](SizeType index) const; +``` + +通过索引访问字符串中的字符。 + +**参数：** +- `index` - 要访问的字符位置（从 0 开始） + +**返回：** 位置 `index` 处字符的引用（可写或只读） + +**复杂度：** O(1) + +**注意：** 不进行边界检查。调用者需确保 `index < Length()`。 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s("Hello"); + + // 只读访问 + for (XCEngine::Containers::String::SizeType i = 0; i < s.Length(); ++i) { + std::cout << s[i]; + } + std::cout << std::endl; // 输出: Hello + + // 可写访问 + s[0] = 'J'; + s[1] = 'a'; + s[4] = '!'; + std::cout << s.CStr() << std::endl; // 输出: Jallo! + + // const 版本 + const XCEngine::Containers::String& cs = s; + char first = cs[0]; + std::cout << "First char: " << first << std::endl; // 输出: First char: J + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 +- [Length](size.md) - 获取长度 diff --git a/docs/api/containers/string/reserve-resize.md b/docs/api/containers/string/reserve-resize.md new file mode 100644 index 00000000..fb2a87c7 --- /dev/null +++ b/docs/api/containers/string/reserve-resize.md @@ -0,0 +1,51 @@ +# String::Reserve / Resize + +```cpp +void Reserve(SizeType capacity); +void Resize(SizeType newSize); +void Resize(SizeType newSize, char fillChar); +``` + +管理字符串的内存和大小。 + +**参数：** +- `capacity` - 要预留的最小容量 +- `newSize` - 新的字符串长度 +- `fillChar` - 当扩展字符串时用于填充新增位置的字符，默认为 '\0' + +**返回：** 无 + +**复杂度：** +- `Reserve`：最坏 O(n)，仅在需要扩展容量时复制数据 +- `Resize`：O(n)，当 newSize > Length 时可能需要扩展 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s("Hi"); + + // Reserve - 预分配内存 + s.Reserve(100); + std::cout << "After Reserve(100), Capacity: " << s.Capacity() << std::endl; + // 输出: After Reserve(100), Capacity: 100 + + // Resize - 缩短字符串 + s.Resize(1); + std::cout << "After Resize(1): " << s.CStr() << std::endl; // 输出: H + + // Resize - 扩展字符串，用 'X' 填充 + s.Resize(5, 'X'); + std::cout << "After Resize(5, 'X'): " << s.CStr() << std::endl; // 输出: HXXXX + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 +- [Length / Capacity](size.md) - 获取长度和容量 +- [Clear](clear.md) - 清空字符串 diff --git a/docs/api/containers/string/size.md b/docs/api/containers/string/size.md new file mode 100644 index 00000000..90847229 --- /dev/null +++ b/docs/api/containers/string/size.md @@ -0,0 +1,44 @@ +# String::Length / Capacity / Empty + +```cpp +SizeType Length() const; +SizeType Capacity() const; +bool Empty() const; +``` + +获取字符串的长度、容量和判空状态。 + +**参数：** 无 + +**返回：** +- `Length()` - 返回字符串的字符数（不包括终止 null 字符） +- `Capacity()` - 返回已分配的存储容量 +- `Empty()` - 如果字符串为空则返回 `true` + +**复杂度：** 均为 O(1) + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s1; + std::cout << "Empty: " << s1.Empty() << std::endl; // 输出: Empty: 1 + + XCEngine::Containers::String s2("Hello"); + std::cout << "Length: " << s2.Length() << std::endl; // 输出: Length: 5 + std::cout << "Capacity: " << s2.Capacity() << std::endl; // 输出: Capacity: 6 或更大 + + s2.Reserve(100); + std::cout << "After Reserve(100), Capacity: " << s2.Capacity() << std::endl; // 输出: 100 + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 +- [CStr](cstr.md) - 获取 C 字符串 +- [Reserve / Resize](reserve-resize.md) - 内存管理 diff --git a/docs/api/containers/string/starts-with.md b/docs/api/containers/string/starts-with.md new file mode 100644 index 00000000..1ee0447a --- /dev/null +++ b/docs/api/containers/string/starts-with.md @@ -0,0 +1,39 @@ +# String::StartsWith + +```cpp +bool StartsWith(const String& prefix) const; +bool StartsWith(const char* prefix) const; +``` + +检查字符串是否以指定的前缀开头。 + +**参数：** +- `prefix` - 要检查的前缀（String 或 const char*） + +**返回：** 如果字符串以指定前缀开头则返回 `true`，否则返回 `false` + +**复杂度：** O(n)，其中 n 为前缀长度 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s("Hello World"); + + std::cout << std::boolalpha; + std::cout << s.StartsWith("Hello") << std::endl; // 输出: true + std::cout << s.StartsWith(XCEngine::Containers::String("Hello")) << std::endl; // 输出: true + std::cout << s.StartsWith("World") << std::endl; // 输出: false + std::cout << s.StartsWith("") << std::endl; // 输出: true + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 +- [EndsWith](ends-with.md) - 检查后缀 +- [Find](find.md) - 查找子串 diff --git a/docs/api/containers/string/string.md b/docs/api/containers/string/string.md new file mode 100644 index 00000000..92fd01f6 --- /dev/null +++ b/docs/api/containers/string/string.md @@ -0,0 +1,132 @@ +# String + +**命名空间**: `XCEngine::Containers` + +**类型**: `class` + +**描述**: 动态字符串类，提供 UTF-8 编码的字符串操作。 + +## 概述 + +`String` 是一个自定义动态字符串类，提供常见的字符串操作功能，支持拷贝构造、移动构造和多种字符串操作方法。 + +## 类型别名 + +| 别名 | 类型 | 描述 | +|------|------|------| +| `SizeType` | `size_t` | 大小类型 | + +## 常量 + +| 常量 | 值 | 描述 | +|------|-----|------| +| `static constexpr SizeType npos` | `static_cast(-1)` | 无效位置标识 | + +## 公共方法 + +### 构造/析构 + +| 方法 | 描述 | +|------|------| +| [Constructor](constructor.md) | 构造字符串实例 | +| [Destructor](destructor.md) | 析构函数 | +| [operator=](operator-assign.md) | 赋值运算符 | + +### 连接运算符 + +| 方法 | 描述 | +|------|------| +| [operator+=](operator-plus-assign.md) | 追加字符串/字符 | +| [operator+](operator-plus.md) | 字符串连接 | + +### 比较运算符 + +| 方法 | 描述 | +|------|------| +| [operator==](operator-equal.md) | 判断两个字符串是否相等 | +| [operator!=](operator-equal.md) | 判断两个字符串是否不相等 | + +### 字符串操作 + +| 方法 | 描述 | +|------|------| +| [Substring](substring.md) | 获取子串 | +| [Trim](trim.md) | 去除首尾空白 | +| [ToLower/ToUpper](to-lower-upper.md) | 大小写转换 | +| [Find](find.md) | 查找子串位置 | +| [StartsWith](starts-with.md) | 检查前缀 | +| [EndsWith](ends-with.md) | 检查后缀 | + +### 元素访问 + +| 方法 | 描述 | +|------|------| +| [CStr](cstr.md) | 获取 C 字符串指针 | +| [Length/Capacity/Empty](size.md) | 获取尺寸信息 | +| [operator[]](./operator-subscript.md) | 下标访问 | + +### 容量管理 + +| 方法 | 描述 | +|------|------| +| [Clear](clear.md) | 清空字符串 | +| [Reserve/Resize](reserve-resize.md) | 预留/调整容量 | + +## std::hash 特化 + +```cpp +namespace std { + template<> + struct hash { + size_t operator()(const XCEngine::Containers::String& str) const noexcept; + }; +} +``` + +提供了 `std::hash` 特化，使 `String` 可以作为 unordered_map 或 unordered_set 的键使用。 + +**实现算法：** DJB hash (Daniel J. Bernstein hash) + +**算法细节：** +- 初始值：5381 +- 对每个字符：`hash = hash * 33 + c`（等价于 `(hash << 5) + hash + c`） + +**示例：** +```cpp +#include +#include + +int main() { + std::unordered_map map; + map["key1"] = 100; + map["key2"] = 200; + return 0; +} +``` + +## 使用示例 + +```cpp +#include + +// 基本用法 +Containers::String str = "Hello"; +str += ", World!"; + +// 字符串操作 +Containers::String sub = str.Substring(0, 5); // "Hello" +bool hasPrefix = str.StartsWith("Hello"); +bool hasSuffix = str.EndsWith("!"); + +// 查找 +SizeType pos = str.Find("World"); // 返回 7 + +// 转换 +Containers::String upper = str.ToUpper(); +Containers::String lower = str.ToLower(); +``` + +## 相关文档 + +- [Array](../array/array.md) - 动态数组 +- [HashMap](../hashmap/hashmap.md) - 哈希表 diff --git a/docs/api/containers/string/substring.md b/docs/api/containers/string/substring.md new file mode 100644 index 00000000..9b479eba --- /dev/null +++ b/docs/api/containers/string/substring.md @@ -0,0 +1,43 @@ +# String::Substring + +```cpp +String Substring(SizeType pos, SizeType len = npos) const; +``` + +返回从位置 `pos` 开始、长度为 `len` 的子字符串。如果 `len` 省略或为 `npos`，则返回从 `pos` 到字符串末尾的所有字符。 + +**参数：** +- `pos` - 子字符串的起始位置（从 0 开始） +- `len` - 子字符串的长度，默认为 `npos`（即到字符串末尾） + +**返回：** 新的 String 对象，包含指定的子字符串 + +**复杂度：** O(n)，其中 n 为子字符串的长度 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s("Hello World"); + + XCEngine::Containers::String sub1 = s.Substring(6); // 从位置6到末尾 + std::cout << sub1.CStr() << std::endl; // 输出: World + + XCEngine::Containers::String sub2 = s.Substring(6, 5); // 从位置6开始，长度5 + std::cout << sub2.CStr() << std::endl; // 输出: World + + XCEngine::Containers::String sub3 = s.Substring(0, 5); // 从位置0开始，长度5 + std::cout << sub3.CStr() << std::endl; // 输出: Hello + + XCEngine::Containers::String sub4 = s.Substring(6, 100); // len超过剩余长度，自动截断 + std::cout << sub4.CStr() << std::endl; // 输出: World + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 diff --git a/docs/api/containers/string/to-lower-upper.md b/docs/api/containers/string/to-lower-upper.md new file mode 100644 index 00000000..8ad2d583 --- /dev/null +++ b/docs/api/containers/string/to-lower-upper.md @@ -0,0 +1,36 @@ +# String::ToLower / ToUpper + +```cpp +String ToLower() const; +String ToUpper() const; +``` + +将字符串转换为小写/大写形式，返回一个新的 String 对象，原字符串不变。 + +**参数：** 无 + +**返回：** 转换后的新 String 对象 + +**复杂度：** O(n)，其中 n 为字符串长度 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s("Hello World 123"); + + XCEngine::Containers::String lower = s.ToLower(); + std::cout << lower.CStr() << std::endl; // 输出: hello world 123 + + XCEngine::Containers::String upper = s.ToUpper(); + std::cout << upper.CStr() << std::endl; // 输出: HELLO WORLD 123 + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 diff --git a/docs/api/containers/string/trim.md b/docs/api/containers/string/trim.md new file mode 100644 index 00000000..c0bbd6b8 --- /dev/null +++ b/docs/api/containers/string/trim.md @@ -0,0 +1,35 @@ +# String::Trim + +```cpp +String Trim() const; +``` + +移除字符串两端的空白字符（包括空格、制表符、换行符等 isspace 识别的字符），返回一个新的 String 对象，原字符串不变。 + +**参数：** 无 + +**返回：** 去除两端空白后的新 String 对象 + +**复杂度：** O(n)，其中 n 为字符串长度 + +**示例：** +```cpp +#include "XCEngine/Containers/String.h" +#include + +int main() { + XCEngine::Containers::String s(" Hello World "); + + XCEngine::Containers::String trimmed = s.Trim(); + std::cout << "\"" << trimmed.CStr() << "\"" << std::endl; // 输出: "Hello World" + + XCEngine::Containers::String s2("\t\n test \t\n"); + std::cout << "\"" << s2.Trim().CStr() << "\"" << std::endl; // 输出: "test" + + return 0; +} +``` + +## 相关文档 + +- [String 总览](string.md) - 返回类总览 diff --git a/docs/api/core/core-overview.md b/docs/api/core/core.md similarity index 75% rename from docs/api/core/core-overview.md rename to docs/api/core/core.md index 6977936a..026effff 100644 --- a/docs/api/core/core-overview.md +++ b/docs/api/core/core.md @@ -16,26 +16,26 @@ Core 模块包含了引擎所需的基础类型和工具，是其他所有模块 | 组件 | 文件 | 描述 | |------|------|------| -| [Types](./core-types.md) | `Types.h` | 类型别名定义 | +| [Types](types/types.md) | `Types.h` | 类型别名定义 | ### 智能指针 | 组件 | 文件 | 描述 | |------|------|------| -| [SmartPtr](./core-smartptr.md) | `SmartPtr.h` | 智能指针别名和工厂函数 | -| [RefCounted](./core-refcounted.md) | `RefCounted.h` | 引用计数基类 | +| [SmartPtr](smartptr/smartptr.md) | `SmartPtr.h` | 智能指针别名和工厂函数 | +| [RefCounted](refcounted/refcounted.md) | `RefCounted.h` | 引用计数基类 | ### 事件系统 | 组件 | 文件 | 描述 | |------|------|------| -| [Event](./core-event.md) | `Event.h` | 事件系统模板 | +| [Event](event/event.md) | `Event.h` | 事件系统模板 | ### 文件操作 | 组件 | 文件 | 描述 | |------|------|------| -| [FileWriter](./core-filewriter.md) | `FileWriter.h` | 文件写入工具 | +| [FileWriter](filewriter/filewriter.md) | `FileWriter.h` | 文件写入工具 | ## 类型别名 @@ -90,5 +90,5 @@ myEvent.Invoke(42, 3.14f); ## 相关文档 -- [Containers 模块](../containers/container-overview.md) - 容器类型 -- [Memory 模块](../memory/memory-overview.md) - 内存管理 +- [Containers 模块](../containers/containers.md) - 容器类型 +- [Memory 模块](../memory/memory.md) - 内存管理 diff --git a/docs/api/core/event/Clear.md b/docs/api/core/event/Clear.md new file mode 100644 index 00000000..51affc0d --- /dev/null +++ b/docs/api/core/event/Clear.md @@ -0,0 +1,37 @@ +# Event::Clear + +```cpp +void Clear(); +``` + +清空所有订阅。 + +**描述** + +移除所有已订阅的回调，清空事件。线程安全。 + +**复杂度：** O(n) 其中 n 为订阅数量 + +**示例：** + +```cpp +#include + +Event event; + +// 订阅多个回调 +event.Subscribe([](int v) { }); +event.Subscribe([](int v) { }); +event.Subscribe([](int v) { }); + +// 清空所有订阅 +event.Clear(); + +// 触发（无回调被执行） +event.Invoke(42); +``` + +## 相关文档 + +- [Event 总览](event.md) - 返回类总览 +- [Unsubscribe](Unsubscribe.md) - 退订单个事件 diff --git a/docs/api/core/event/Invoke.md b/docs/api/core/event/Invoke.md new file mode 100644 index 00000000..51936ce2 --- /dev/null +++ b/docs/api/core/event/Invoke.md @@ -0,0 +1,43 @@ +# Event::Invoke + +```cpp +void Invoke(Args... args); +``` + +调用所有订阅的回调。 + +**描述** + +依次调用所有已订阅的回调函数。在调用前会自动处理待退订的回调。回调是在锁外执行的，因此可以在回调中安全地进行订阅/退订操作。线程安全。 + +**参数：** +- `args` - 传递给回调的参数 + +**复杂度：** O(n) 其中 n 为订阅数量 + +**示例：** + +```cpp +#include + +// 无参数事件 +Event<> frameEndEvent; +frameEndEvent.Subscribe([]() { + printf("Frame ended\n"); +}); + +// 带参数事件 +Event playerDiedEvent; +playerDiedEvent.Subscribe([](int playerId, const char* reason) { + printf("Player %d died: %s\n", playerId, reason); +}); + +// 触发事件 +frameEndEvent.Invoke(); +playerDiedEvent.Invoke(1, "fell off a cliff"); +``` + +## 相关文档 + +- [Event 总览](event.md) - 返回类总览 +- [Subscribe](Subscribe.md) - 订阅事件 diff --git a/docs/api/core/event/ProcessUnsubscribes.md b/docs/api/core/event/ProcessUnsubscribes.md new file mode 100644 index 00000000..fdca8fc9 --- /dev/null +++ b/docs/api/core/event/ProcessUnsubscribes.md @@ -0,0 +1,37 @@ +# Event::ProcessUnsubscribes + +```cpp +void ProcessUnsubscribes(); +``` + +处理积压的退订请求。 + +**描述** + +手动处理待退订的回调，将其从订阅列表中移除。通常不需要手动调用，`Invoke` 会自动处理退订。但在某些场景下可能需要主动调用。 + +**复杂度：** O(n) 其中 n 为待退订数量 + +**示例：** + +```cpp +#include + +Event event; + +// 订阅 +uint64_t id = event.Subscribe([](int value) { }); + +// 退订请求入队 +event.Unsubscribe(id); + +// 主动处理退订 +event.ProcessUnsubscribes(); + +// 此时事件列表中已无该回调 +``` + +## 相关文档 + +- [Event 总览](event.md) - 返回类总览 +- [Unsubscribe](Unsubscribe.md) - 退订事件 diff --git a/docs/api/core/event/Subscribe.md b/docs/api/core/event/Subscribe.md new file mode 100644 index 00000000..85b79400 --- /dev/null +++ b/docs/api/core/event/Subscribe.md @@ -0,0 +1,48 @@ +# Event::Subscribe + +```cpp +uint64_t Subscribe(Callback callback); +``` + +订阅事件回调。 + +**描述** + +将回调函数添加到事件订阅列表中，并返回一个唯一的订阅 ID。该 ID 可用于后续退订。线程安全，可在任意线程调用。 + +**参数：** +- `callback` - 要订阅的回调函数，类型为 `std::function` + +**返回：** `uint64_t` - 订阅 ID，用于退订 + +**复杂度：** O(1) amortized + +**示例：** + +```cpp +#include + +// 定义事件 +Event damageEvent; + +// 订阅多个回调 +uint64_t id1 = damageEvent.Subscribe([](int damage, float time) { + printf("Damage taken: %d at time %f\n", damage, time); +}); + +uint64_t id2 = damageEvent.Subscribe([](int damage, float time) { + // 记录伤害日志 +}); + +// 使用 lambda 表达式 +auto callback = [](int damage, float time) { + // 处理伤害 +}; +uint64_t id3 = damageEvent.Subscribe(callback); +``` + +## 相关文档 + +- [Event 总览](event.md) - 返回类总览 +- [Unsubscribe](Unsubscribe.md) - 退订事件 +- [Invoke](Invoke.md) - 触发事件 diff --git a/docs/api/core/event/Unsubscribe.md b/docs/api/core/event/Unsubscribe.md new file mode 100644 index 00000000..78411391 --- /dev/null +++ b/docs/api/core/event/Unsubscribe.md @@ -0,0 +1,41 @@ +# Event::Unsubscribe + +```cpp +void Unsubscribe(uint64_t id); +``` + +退订事件。 + +**描述** + +将指定 ID 的回调从订阅列表中移除。退订是延迟生效的，在调用 `Invoke` 时会一并处理待退订的回调。线程安全，可在任意线程调用。 + +**参数：** +- `id` - 订阅时返回的 ID + +**复杂度：** O(n) 在 Invoke 时处理 + +**示例：** + +```cpp +#include + +Event someEvent; + +// 订阅 +uint64_t id = someEvent.Subscribe([](int value) { + printf("Value: %d\n", value); +}); + +// 退订 +someEvent.Unsubscribe(id); + +// 触发（已退订的回调不会被调用） +someEvent.Invoke(42); +``` + +## 相关文档 + +- [Event 总览](event.md) - 返回类总览 +- [Subscribe](Subscribe.md) - 订阅事件 +- [ProcessUnsubscribes](ProcessUnsubscribes.md) - 手动处理退订 diff --git a/docs/api/core/event/begin.md b/docs/api/core/event/begin.md new file mode 100644 index 00000000..95818d9b --- /dev/null +++ b/docs/api/core/event/begin.md @@ -0,0 +1,35 @@ +# Event::begin + +```cpp +Iterator begin(); +``` + +获取开始迭代器。 + +**描述** + +返回订阅列表的开始迭代器，用于范围for循环遍历所有订阅的回调。 + +**返回：** `Iterator` - 指向第一个监听器的迭代器 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Event event; +event.Subscribe([](int v) { printf("Callback 1: %d\n", v); }); +event.Subscribe([](int v) { printf("Callback 2: %d\n", v); }); + +// 遍历所有订阅 +for (auto& [id, callback] : event) { + callback(100); +} +``` + +## 相关文档 + +- [Event 总览](event.md) - 返回类总览 +- [end](end.md) - 获取结束迭代器 diff --git a/docs/api/core/event/end.md b/docs/api/core/event/end.md new file mode 100644 index 00000000..18cf0b73 --- /dev/null +++ b/docs/api/core/event/end.md @@ -0,0 +1,34 @@ +# Event::end + +```cpp +Iterator end(); +``` + +获取结束迭代器。 + +**描述** + +返回订阅列表的结束迭代器，用于范围for循环遍历所有订阅的回调。 + +**返回：** `Iterator` - 指向末尾的迭代器 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Event event; +event.Subscribe([](int v) { printf("Callback: %d\n", v); }); + +// 遍历所有订阅 +for (auto& [id, callback] : event) { + callback(42); +} +``` + +## 相关文档 + +- [Event 总览](event.md) - 返回类总览 +- [begin](begin.md) - 获取开始迭代器 diff --git a/docs/api/core/core-event.md b/docs/api/core/event/event.md similarity index 78% rename from docs/api/core/core-event.md rename to docs/api/core/event/event.md index 4997f7bc..22ebc699 100644 --- a/docs/api/core/core-event.md +++ b/docs/api/core/event/event.md @@ -48,6 +48,18 @@ | `Iterator begin()` | 获取开始迭代器 | | `Iterator end()` | 获取结束迭代器 | +## 方法列表 + +| 方法 | 描述 | +|------|------| +| [Subscribe](Subscribe.md) | 订阅事件回调 | +| [Unsubscribe](Unsubscribe.md) | 退订事件 | +| [ProcessUnsubscribes](ProcessUnsubscribes.md) | 处理积压的退订请求 | +| [Invoke](Invoke.md) | 调用所有订阅的回调 | +| [Clear](Clear.md) | 清空所有订阅 | +| [begin](begin.md) | 获取开始迭代器 | +| [end](end.md) | 获取结束迭代器 | + ## 使用示例 ```cpp @@ -74,4 +86,4 @@ frameStartEvent.Clear(); ## 相关文档 -- [Core 模块概览](./core-overview.md) - Core 模块总览 +- [Core 模块总览](../core.md) - 返回模块总览 diff --git a/docs/api/core/filewriter/Close.md b/docs/api/core/filewriter/Close.md new file mode 100644 index 00000000..e3458c7b --- /dev/null +++ b/docs/api/core/filewriter/Close.md @@ -0,0 +1,38 @@ +# FileWriter::Close + +```cpp +void Close(); +``` + +关闭文件。 + +**描述** + +关闭当前打开的文件。如果文件未打开，则什么都不做。析构函数会自动调用此方法。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +FileWriter writer; + +if (writer.Open("data.txt")) { + writer.Write("Some data\n"); + writer.Flush(); + writer.Close(); +} + +// 文件已关闭，可再次打开其他文件 +if (writer.Open("other.txt")) { + writer.Write("New content\n"); +} +// 析构时自动关闭 +``` + +## 相关文档 + +- [FileWriter 总览](filewriter.md) - 返回类总览 +- [Open](Open.md) - 打开文件 diff --git a/docs/api/core/filewriter/Flush.md b/docs/api/core/filewriter/Flush.md new file mode 100644 index 00000000..d93fdec1 --- /dev/null +++ b/docs/api/core/filewriter/Flush.md @@ -0,0 +1,42 @@ +# FileWriter::Flush + +```cpp +bool Flush(); +``` + +刷新缓冲区。 + +**描述** + +将缓冲区中的数据强制写入磁盘，确保数据持久化。在写入大量数据后应调用此方法以确保数据已保存。 + +**返回：** `bool` - 是否刷新成功 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +FileWriter writer("output.txt"); +if (writer.IsOpen()) { + // 写入大量数据 + for (int i = 0; i < 1000; i++) { + writer.Write("Line "); + writer.Write(std::to_string(i).c_str()); + writer.Write("\n"); + } + + // 刷新确保数据写入磁盘 + writer.Flush(); + + // 数据已安全保存 + writer.Close(); +} +``` + +## 相关文档 + +- [FileWriter 总览](filewriter.md) - 返回类总览 +- [Write](Write.md) - 写入数据 diff --git a/docs/api/core/filewriter/IsOpen.md b/docs/api/core/filewriter/IsOpen.md new file mode 100644 index 00000000..6280eb3b --- /dev/null +++ b/docs/api/core/filewriter/IsOpen.md @@ -0,0 +1,41 @@ +# FileWriter::IsOpen + +```cpp +bool IsOpen() const; +``` + +检查文件是否已打开。 + +**描述** + +返回文件是否已成功打开并可用于写入。 + +**返回：** `bool` - 文件是否已打开 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +FileWriter writer1; +if (writer1.IsOpen()) { + // 不会执行 + writer1.Write("test"); +} + +// 打开文件 +FileWriter writer2("output.txt"); +if (writer2.IsOpen()) { + printf("File opened successfully\n"); + writer2.Write("Content"); +} else { + printf("Failed to open file\n"); +} +``` + +## 相关文档 + +- [FileWriter 总览](filewriter.md) - 返回类总览 +- [Open](Open.md) - 打开文件 diff --git a/docs/api/core/filewriter/Open.md b/docs/api/core/filewriter/Open.md new file mode 100644 index 00000000..3ecae4e8 --- /dev/null +++ b/docs/api/core/filewriter/Open.md @@ -0,0 +1,51 @@ +# FileWriter::Open + +```cpp +bool Open(const char* filePath, bool append = false); +``` + +打开文件。 + +**描述** + +打开指定路径的文件，准备写入。如果之前已打开文件，会先关闭。返回是否成功打开文件。 + +**参数：** +- `filePath` - 要打开的文件路径 +- `append` - 是否以追加模式打开，默认为覆盖模式 + +**返回：** `bool` - 是否成功打开 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +FileWriter writer; + +// 打开文件（覆盖模式） +if (writer.Open("output.txt")) { + writer.Write("Hello\n"); + writer.Close(); +} + +// 打开文件（追加模式） +if (writer.Open("log.txt", true)) { + writer.Write("Another line\n"); + writer.Flush(); +} + +// 检查是否成功 +FileWriter writer2; +if (!writer2.Open("/invalid/path/file.txt")) { + printf("Failed to open file\n"); +} +``` + +## 相关文档 + +- [FileWriter 总览](filewriter.md) - 返回类总览 +- [Close](Close.md) - 关闭文件 +- [IsOpen](IsOpen.md) - 检查文件状态 diff --git a/docs/api/core/filewriter/Write.md b/docs/api/core/filewriter/Write.md new file mode 100644 index 00000000..1ffe2221 --- /dev/null +++ b/docs/api/core/filewriter/Write.md @@ -0,0 +1,46 @@ +# FileWriter::Write + +```cpp +bool Write(const char* data, size_t length); +bool Write(const Containers::String& str); +``` + +写入数据到文件。 + +**描述** + +将数据写入文件。如果文件未打开，操作会失败。 + +**参数：** +- `data` - 要写入的字符数据 +- `length` - 要写入的字节数 +- `str` - 要写入的 String 对象 + +**返回：** `bool` - 是否写入成功 + +**复杂度：** O(n) 其中 n 为写入的字节数 + +**示例：** + +```cpp +#include +#include + +FileWriter writer("output.txt"); +if (writer.IsOpen()) { + // 写入原始字符数组 + writer.Write("Hello, World!", 13); + writer.Write("\n", 1); + + // 写入 String + Containers::String message = "This is a test string"; + writer.Write(message); + + writer.Flush(); +} +``` + +## 相关文档 + +- [FileWriter 总览](filewriter.md) - 返回类总览 +- [Flush](Flush.md) - 刷新缓冲区 diff --git a/docs/api/core/core-filewriter.md b/docs/api/core/filewriter/filewriter.md similarity index 79% rename from docs/api/core/core-filewriter.md rename to docs/api/core/filewriter/filewriter.md index 628055d3..dde20fb4 100644 --- a/docs/api/core/core-filewriter.md +++ b/docs/api/core/filewriter/filewriter.md @@ -36,6 +36,17 @@ | `bool Write(const Containers::String& str)` | 写入 String 内容 | | `bool Flush()` | 刷新缓冲区，确保数据写入磁盘 | +## 方法列表 + +| 方法 | 描述 | +|------|------| +| [FileWriter](FileWriter.md) | 构造函数 | +| [Open](Open.md) | 打开文件 | +| [Close](Close.md) | 关闭文件 | +| [IsOpen](IsOpen.md) | 检查文件是否已打开 | +| [Write](Write.md) | 写入数据 | +| [Flush](Flush.md) | 刷新缓冲区 | + ## 使用示例 ```cpp @@ -71,5 +82,6 @@ writer3.Write(content); ## 相关文档 -- [Logger](../debug/debug-logger.md) - 日志系统 -- [FileLogSink](../debug/debug-filelogsink.md) - 文件日志输出 +- [Core 模块总览](../core.md) - 返回模块总览 +- [Logger](../../debug/logger/logger.md) - 日志系统 +- [FileLogSink](../../debug/filelogsink/filelogsink.md) - 文件日志输出 diff --git a/docs/api/core/refcounted/AddRef.md b/docs/api/core/refcounted/AddRef.md new file mode 100644 index 00000000..8e1972b1 --- /dev/null +++ b/docs/api/core/refcounted/AddRef.md @@ -0,0 +1,40 @@ +# RefCounted::AddRef + +```cpp +void AddRef(); +``` + +增加引用计数。 + +**描述** + +原子地增加引用计数。在复制 `RefCounted` 指针或传递引用时调用此方法。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyObject : public RefCounted { +public: + void DoSomething() { /* ... */ } +}; + +// 创建对象（构造时 refCount = 1） +MyObject* obj = new MyObject(); + +// 手动增加引用 +obj->AddRef(); // refCount = 2 +obj->AddRef(); // refCount = 3 + +// 需要释放额外的引用 +obj->Release(); // refCount = 2 +obj->Release(); // refCount = 1 +``` + +## 相关文档 + +- [RefCounted 总览](refcounted.md) - 返回类总览 +- [Release](Release.md) - 减少引用计数 diff --git a/docs/api/core/refcounted/GetRefCount.md b/docs/api/core/refcounted/GetRefCount.md new file mode 100644 index 00000000..16c69a0d --- /dev/null +++ b/docs/api/core/refcounted/GetRefCount.md @@ -0,0 +1,43 @@ +# RefCounted::GetRefCount + +```cpp +uint32_t GetRefCount() const; +``` + +获取当前引用计数。 + +**描述** + +返回当前的引用计数值。由于使用 `std::atomic` 实现，因此是线程安全的。 + +**返回：** `uint32_t` - 当前引用计数 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyObject : public RefCounted { +public: + void Debug() { + printf("RefCount: %u\n", GetRefCount()); + } +}; + +MyObject* obj = new MyObject(); +printf("After create: %u\n", obj->GetRefCount()); // 1 + +obj->AddRef(); +printf("After AddRef: %u\n", obj->GetRefCount()); // 2 + +obj->Release(); +printf("After Release: %u\n", obj->GetRefCount()); // 1 +``` + +## 相关文档 + +- [RefCounted 总览](refcounted.md) - 返回类总览 +- [AddRef](AddRef.md) - 增加引用计数 +- [Release](Release.md) - 减少引用计数 diff --git a/docs/api/core/refcounted/Release.md b/docs/api/core/refcounted/Release.md new file mode 100644 index 00000000..a3ac6763 --- /dev/null +++ b/docs/api/core/refcounted/Release.md @@ -0,0 +1,39 @@ +# RefCounted::Release + +```cpp +void Release(); +``` + +减少引用计数。 + +**描述** + +原子地减少引用计数。当引用计数归零时，对象会自动 `delete this`。这是实现自动内存管理的关键方法。 + +**复杂度：** O(1)（归零时为 O(n)，n 为对象大小） + +**示例：** + +```cpp +#include + +class MyObject : public RefCounted { +public: + void DoSomething() { /* ... */ } +}; + +// 创建对象（构造时 refCount = 1） +MyObject* obj = new MyObject(); + +// 手动增加引用 +obj->AddRef(); // refCount = 2 + +// 释放引用 +obj->Release(); // refCount = 1 +obj->Release(); // refCount = 0, 对象被自动 delete +``` + +## 相关文档 + +- [RefCounted 总览](refcounted.md) - 返回类总览 +- [AddRef](AddRef.md) - 增加引用计数 diff --git a/docs/api/core/core-refcounted.md b/docs/api/core/refcounted/refcounted.md similarity index 76% rename from docs/api/core/core-refcounted.md rename to docs/api/core/refcounted/refcounted.md index 17012ab1..3701bfd6 100644 --- a/docs/api/core/core-refcounted.md +++ b/docs/api/core/refcounted/refcounted.md @@ -27,6 +27,15 @@ | `void Release()` | 减少引用计数（归零时自动 delete this） | | `uint32_t GetRefCount() const` | 获取当前引用计数 | +## 方法列表 + +| 方法 | 描述 | +|------|------| +| [RefCounted](RefCounted.md) | 构造函数 | +| [AddRef](AddRef.md) | 增加引用计数 | +| [Release](Release.md) | 减少引用计数 | +| [GetRefCount](GetRefCount.md) | 获取当前引用计数 | + ## 使用示例 ```cpp @@ -47,4 +56,5 @@ obj->Release(); // refCount = 0, 自动 delete ## 相关文档 -- [SmartPtr](./core-smartptr.md) - 智能指针 +- [Core 模块总览](../core.md) - 返回模块总览 +- [SmartPtr](../smartptr/smartptr.md) - 智能指针 diff --git a/docs/api/core/smartptr/MakeRef.md b/docs/api/core/smartptr/MakeRef.md new file mode 100644 index 00000000..a361213b --- /dev/null +++ b/docs/api/core/smartptr/MakeRef.md @@ -0,0 +1,51 @@ +# SmartPtr::MakeRef + +```cpp +template +Ref MakeRef(Args&&... args); +``` + +创建共享指针的工厂函数。 + +**描述** + +`MakeRef` 是创建 `Ref` 的工厂函数，使用完美转发将参数传递给 `T` 的构造函数。相比直接使用 `std::make_shared`，代码更简洁。 + +**模板参数：** +- `T` - 被创建对象的类型 +- `Args` - 构造函数的参数类型 + +**参数：** +- `args` - 转发给 T 构造函数的参数 + +**返回：** `Ref` - 新创建的共享指针 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyClass { +public: + MyClass(int a, int b) : m_a(a), m_b(b) {} + int GetSum() const { return m_a + m_b; } +private: + int m_a, m_b; +}; + +// 创建共享指针 +Core::Ref ref = Core::MakeRef(10, 20); +printf("Sum: %d\n", ref->GetSum()); + +// 使用 lambda +Core::Ref> callback = Core::MakeRef>([]() { + printf("Callback invoked!\n"); +}); +``` + +## 相关文档 + +- [SmartPtr 总览](smartptr.md) - 返回类总览 +- [Ref](Ref.md) - Ref 类型说明 diff --git a/docs/api/core/smartptr/MakeUnique.md b/docs/api/core/smartptr/MakeUnique.md new file mode 100644 index 00000000..699012e0 --- /dev/null +++ b/docs/api/core/smartptr/MakeUnique.md @@ -0,0 +1,49 @@ +# SmartPtr::MakeUnique + +```cpp +template +UniqueRef MakeUnique(Args&&... args); +``` + +创建独占指针的工厂函数。 + +**描述** + +`MakeUnique` 是创建 `UniqueRef` 的工厂函数，使用完美转发将参数传递给 `T` 的构造函数。相比直接使用 `std::make_unique`，代码更简洁。 + +**模板参数：** +- `T` - 被创建对象的类型 +- `Args` - 构造函数的参数类型 + +**参数：** +- `args` - 转发给 T 构造函数的参数 + +**返回：** `UniqueRef` - 新创建的独占指针 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyClass { +public: + MyClass(int value) : m_value(value) {} + int GetValue() const { return m_value; } +private: + int m_value; +}; + +// 创建独占指针 +Core::UniqueRef unique = Core::MakeUnique(42); +printf("Value: %d\n", unique->GetValue()); + +// 转移所有权 +Core::UniqueRef moved = Core::MakeUnique(100); +``` + +## 相关文档 + +- [SmartPtr 总览](smartptr.md) - 返回类总览 +- [UniqueRef](UniqueRef.md) - UniqueRef 类型说明 diff --git a/docs/api/core/smartptr/Ref.md b/docs/api/core/smartptr/Ref.md new file mode 100644 index 00000000..1f7721e3 --- /dev/null +++ b/docs/api/core/smartptr/Ref.md @@ -0,0 +1,40 @@ +# SmartPtr::Ref + +```cpp +template +using Ref = std::shared_ptr; +``` + +共享引用智能指针类型别名。 + +**描述** + +`Ref` 是 `std::shared_ptr` 的类型别名，提供共享所有权的智能指针。多个 `Ref` 可以指向同一个对象，通过引用计数管理生命周期。当最后一个 `Ref` 被销毁时，对象会被自动删除。 + +**模板参数：** +- `T` - 被托管对象的类型 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyClass { +public: + void DoSomething() { /* ... */ } +}; + +Core::Ref ref1 = Core::MakeRef(); +Core::Ref ref2 = ref1; // 共享所有权 + +if (ref1) { + ref1->DoSomething(); +} +``` + +## 相关文档 + +- [SmartPtr 总览](smartptr.md) - 返回类总览 +- [MakeRef](MakeRef.md) - 创建 Ref 的工厂函数 diff --git a/docs/api/core/smartptr/UniqueRef.md b/docs/api/core/smartptr/UniqueRef.md new file mode 100644 index 00000000..c25dea40 --- /dev/null +++ b/docs/api/core/smartptr/UniqueRef.md @@ -0,0 +1,46 @@ +# SmartPtr::UniqueRef + +```cpp +template +using UniqueRef = std::unique_ptr; +``` + +独占所有权的智能指针类型别名。 + +**描述** + +`UniqueRef` 是 `std::unique_ptr` 的类型别名，提供独占所有权的智能指针。每个对象只能有一个 `UniqueRef` 持有，当 `UniqueRef` 被销毁时，对象会被自动删除。不能复制，只能移动。 + +**模板参数：** +- `T` - 被托管对象的类型 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyClass { +public: + void DoSomething() { /* ... */ } +}; + +Core::UniqueRef unique = Core::MakeUnique(); + +if (unique) { + unique->DoSomething(); +} + +// 自定义删除器 +Core::UniqueRef + file(fopen("test.txt", "r"), &fclose); + +// 转移所有权 +Core::UniqueRef moved = std::move(unique); +``` + +## 相关文档 + +- [SmartPtr 总览](smartptr.md) - 返回类总览 +- [MakeUnique](MakeUnique.md) - 创建 UniqueRef 的工厂函数 diff --git a/docs/api/core/core-smartptr.md b/docs/api/core/smartptr/smartptr.md similarity index 73% rename from docs/api/core/core-smartptr.md rename to docs/api/core/smartptr/smartptr.md index e06efca1..0faf47e6 100644 --- a/docs/api/core/core-smartptr.md +++ b/docs/api/core/smartptr/smartptr.md @@ -24,6 +24,15 @@ | `Core::MakeRef(Args&&... args)` | `Ref` | 创建共享指针 | | `Core::MakeUnique(Args&&... args)` | `UniqueRef` | 创建独占指针 | +## 方法列表 + +| 方法 | 描述 | +|------|------| +| [Ref](Ref.md) | `std::shared_ptr` 类型别名 | +| [UniqueRef](UniqueRef.md) | `std::unique_ptr` 类型别名 | +| [MakeRef](MakeRef.md) | 创建共享指针的工厂函数 | +| [MakeUnique](MakeUnique.md) | 创建独占指针的工厂函数 | + ## 使用示例 ```cpp @@ -50,5 +59,6 @@ Core::UniqueRef ## 相关文档 -- [RefCounted](./core-refcounted.md) - 引用计数基类 -- [Types](./core-types.md) - 类型别名 +- [Core 模块总览](../core.md) - 返回模块总览 +- [RefCounted](../refcounted/refcounted.md) - 引用计数基类 +- [Types](../../rhi/types/types.md) - 类型别名 diff --git a/docs/api/core/types/byte.md b/docs/api/core/types/byte.md new file mode 100644 index 00000000..eff9330d --- /dev/null +++ b/docs/api/core/types/byte.md @@ -0,0 +1,30 @@ +# Types::byte + +```cpp +using byte = uint8_t; +``` + +字节类型别名，对应 `uint8_t` 类型。 + +**描述** + +`byte` 是 1 字节无符号整数类型，专门用于表示原始字节数据。语义上比 `uint8` 更清晰，适用于二进制数据、内存缓冲区等场景。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Core::byte header[4] = {0x00, 0x01, 0x02, 0x03}; +Core::byte flags = 0b11001010; + +// 内存缓冲区 +Core::byte* buffer = new Core::byte[1024]; +``` + +## 相关文档 + +- [Types 总览](types.md) - 返回类型总览 +- [uint8](uint8.md) - 底层类型 diff --git a/docs/api/core/types/int16.md b/docs/api/core/types/int16.md new file mode 100644 index 00000000..fc666edd --- /dev/null +++ b/docs/api/core/types/int16.md @@ -0,0 +1,27 @@ +# Types::int16 + +```cpp +using int16 = int16_t; +``` + +16位有符号整数类型别名，对应 C++ 标准库的 `int16_t` 类型。 + +**描述** + +`int16` 是 16 位（2 字节）有符号整数类型，范围为 -32,768 到 32,767。该类型别名确保跨平台一致性。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Core::int16 shortValue = -10000; +Core::int16 maxValue = 32767; +``` + +## 相关文档 + +- [Types 总览](types.md) - 返回类型总览 +- [uint16](uint16.md) - 对应的无符号类型 diff --git a/docs/api/core/types/int32.md b/docs/api/core/types/int32.md new file mode 100644 index 00000000..9c4aeb3f --- /dev/null +++ b/docs/api/core/types/int32.md @@ -0,0 +1,30 @@ +# Types::int32 + +```cpp +using int32 = int32_t; +``` + +32位有符号整数类型别名，对应 C++ 标准库的 `int32_t` 类型。 + +**描述** + +`int32` 是 32 位（4 字节）有符号整数类型，范围为 -2,147,483,648 到 2,147,483,647。该类型别名确保跨平台一致性，是最常用的整数类型。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Core::int32 score = 1000000; +Core::int32 negative = -500000; + +// 函数参数类型 +void SetHealth(Core::int32 health); +``` + +## 相关文档 + +- [Types 总览](types.md) - 返回类型总览 +- [uint32](uint32.md) - 对应的无符号类型 diff --git a/docs/api/core/types/int64.md b/docs/api/core/types/int64.md new file mode 100644 index 00000000..7d80c404 --- /dev/null +++ b/docs/api/core/types/int64.md @@ -0,0 +1,30 @@ +# Types::int64 + +```cpp +using int64 = int64_t; +``` + +64位有符号整数类型别名，对应 C++ 标准库的 `int64_t` 类型。 + +**描述** + +`int64` 是 64 位（8 字节）有符号整数类型，范围为 -9,223,372,036,854,775,808 到 9,223,372,036,854,775,807。该类型别名用于需要大范围整数的场景，如时间戳、大文件大小等。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Core::int64 largeNumber = 9223372036854775807LL; +Core::int64 fileSize = 1099511627776LL; // 1TB + +// 时间戳（毫秒） +Core::int64 timestamp = 1700000000000LL; +``` + +## 相关文档 + +- [Types 总览](types.md) - 返回类型总览 +- [uint64](uint64.md) - 对应的无符号类型 diff --git a/docs/api/core/types/int8.md b/docs/api/core/types/int8.md new file mode 100644 index 00000000..348d020b --- /dev/null +++ b/docs/api/core/types/int8.md @@ -0,0 +1,28 @@ +# Types::int8 + +```cpp +using int8 = int8_t; +``` + +8位有符号整数类型别名，对应 C++ 标准库的 `int8_t` 类型。 + +**描述** + +`int8` 是 8 位（1 字节）有符号整数类型，范围为 -128 到 127。该类型别名确保跨平台一致性。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Core::int8 signedByte = -50; +Core::int8 maxValue = 127; +Core::int8 minValue = -128; +``` + +## 相关文档 + +- [Types 总览](types.md) - 返回类型总览 +- [uint8](uint8.md) - 对应的无符号类型 diff --git a/docs/api/core/core-types.md b/docs/api/core/types/types.md similarity index 63% rename from docs/api/core/core-types.md rename to docs/api/core/types/types.md index 864c23c0..1b621c3f 100644 --- a/docs/api/core/core-types.md +++ b/docs/api/core/types/types.md @@ -26,6 +26,20 @@ | `uint64` | `uint64_t` | 64位无符号整数 | | `byte` | `uint8_t` | 字节类型 | +## 方法列表 + +| 方法 | 描述 | +|------|------| +| [int8](int8.md) | 8位有符号整数类型别名 | +| [int16](int16.md) | 16位有符号整数类型别名 | +| [int32](int32.md) | 32位有符号整数类型别名 | +| [int64](int64.md) | 64位有符号整数类型别名 | +| [uint8](uint8.md) | 8位无符号整数类型别名 | +| [uint16](uint16.md) | 16位无符号整数类型别名 | +| [uint32](uint32.md) | 32位无符号整数类型别名 | +| [uint64](uint64.md) | 64位无符号整数类型别名 | +| [byte](byte.md) | 字节类型别名 | + ## 使用示例 ```cpp @@ -45,5 +59,5 @@ void ProcessData(Core::uint32 size, const Core::int8* data); ## 相关文档 -- [SmartPtr](./core-smartptr.md) - 智能指针 -- [RefCounted](./core-refcounted.md) - 引用计数基类 +- [Core 模块总览](../core.md) - 返回模块总览 +- [SmartPtr](../smartptr/smartptr.md) - 智能指针 diff --git a/docs/api/core/types/uint16.md b/docs/api/core/types/uint16.md new file mode 100644 index 00000000..3b4a42bc --- /dev/null +++ b/docs/api/core/types/uint16.md @@ -0,0 +1,30 @@ +# Types::uint16 + +```cpp +using uint16 = uint16_t; +``` + +16位无符号整数类型别名，对应 C++ 标准库的 `uint16_t` 类型。 + +**描述** + +`uint16` 是 16 位（2 字节）无符号整数类型，范围为 0 到 65,535。常用于 Unicode 字符、端口号等场景。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Core::uint16 port = 8080; +Core::uint16 maxConnections = 65535; + +// Unicode 字符 +Core::uint16 unicodeChar = 0x4E2D; +``` + +## 相关文档 + +- [Types 总览](types.md) - 返回类型总览 +- [int16](int16.md) - 对应的有符号类型 diff --git a/docs/api/core/types/uint32.md b/docs/api/core/types/uint32.md new file mode 100644 index 00000000..4caae087 --- /dev/null +++ b/docs/api/core/types/uint32.md @@ -0,0 +1,30 @@ +# Types::uint32 + +```cpp +using uint32 = uint32_t; +``` + +32位无符号整数类型别名，对应 C++ 标准库的 `uint32_t` 类型。 + +**描述** + +`uint32` 是 32 位（4 字节）无符号整数类型，范围为 0 到 4,294,967,295。常用于 ID、计数、大小等场景。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Core::uint32 entityId = 1000000; +Core::uint32 maxItems = 4294967295U; + +// 数组大小 +Core::uint32 arraySize = 1000; +``` + +## 相关文档 + +- [Types 总览](types.md) - 返回类型总览 +- [int32](int32.md) - 对应的有符号类型 diff --git a/docs/api/core/types/uint64.md b/docs/api/core/types/uint64.md new file mode 100644 index 00000000..ab23116c --- /dev/null +++ b/docs/api/core/types/uint64.md @@ -0,0 +1,30 @@ +# Types::uint64 + +```cpp +using uint64 = uint64_t; +``` + +64位无符号整数类型别名，对应 C++ 标准库的 `uint64_t` 类型。 + +**描述** + +`uint64` 是 64 位（8 字节）无符号整数类型，范围为 0 到 18,446,744,073,709,551,615。用于需要极大整数范围的场景，如大文件大小、精确时间等。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Core::uint64 largeFileSize = 1099511627776ULL; // 1TB +Core::uint64 maxValue = 18446744073709551615ULL; + +// 高精度时间戳（微秒） +Core::uint64 microseconds = 1700000000000000ULL; +``` + +## 相关文档 + +- [Types 总览](types.md) - 返回类型总览 +- [int64](int64.md) - 对应的有符号类型 diff --git a/docs/api/core/types/uint8.md b/docs/api/core/types/uint8.md new file mode 100644 index 00000000..6b55bc5f --- /dev/null +++ b/docs/api/core/types/uint8.md @@ -0,0 +1,30 @@ +# Types::uint8 + +```cpp +using uint8 = uint8_t; +``` + +8位无符号整数类型别名，对应 C++ 标准库的 `uint8_t` 类型。 + +**描述** + +`uint8` 是 8 位（1 字节）无符号整数类型，范围为 0 到 255。常用于字节数据、颜色分量（RGB）等场景。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +Core::uint8 flags = 0xFF; +Core::uint8 red = 255; + +// 字节数组 +Core::uint8 buffer[256]; +``` + +## 相关文档 + +- [Types 总览](types.md) - 返回类型总览 +- [int8](int8.md) - 对应的有符号类型 diff --git a/docs/api/debug/consolelogsink/consolelogsink.md b/docs/api/debug/consolelogsink/consolelogsink.md new file mode 100644 index 00000000..74f3f045 --- /dev/null +++ b/docs/api/debug/consolelogsink/consolelogsink.md @@ -0,0 +1,20 @@ +# ConsoleLogSink::ConsoleLogSink + +```cpp +ConsoleLogSink() +``` + +默认构造函数。创建一个 `ConsoleLogSink` 实例，默认启用彩色输出，最小日志级别为 `Verbose`。 + +**复杂度：** O(1) + +**示例：** + +```cpp +auto sink = std::make_unique(); +XCEngine::Debug::Logger::Get().AddSink(std::move(sink)); +``` + +## 相关文档 + +- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览 diff --git a/docs/api/debug/consolelogsink/flush.md b/docs/api/debug/consolelogsink/flush.md new file mode 100644 index 00000000..bccfde91 --- /dev/null +++ b/docs/api/debug/consolelogsink/flush.md @@ -0,0 +1,22 @@ +# ConsoleLogSink::Flush + +```cpp +void Flush() override +``` + +刷新标准输出流（stdout），调用 `fflush(stdout)` 确保所有待输出的日志内容立即显示在控制台上。 + +**复杂度：** O(1) + +**示例：** + +```cpp +auto sink = std::make_unique(); +XCEngine::Debug::Logger::Get().AddSink(std::move(sink)); +// 在程序异常退出前确保日志已输出 +XCEngine::Debug::Logger::Get().Flush(); +``` + +## 相关文档 + +- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览 diff --git a/docs/api/debug/consolelogsink/log.md b/docs/api/debug/consolelogsink/log.md new file mode 100644 index 00000000..44f6af57 --- /dev/null +++ b/docs/api/debug/consolelogsink/log.md @@ -0,0 +1,25 @@ +# ConsoleLogSink::Log + +```cpp +void Log(const LogEntry& entry) override +``` + +将日志输出到控制台。根据 `LogEntry` 的级别和分类格式化输出内容，并根据 `m_colorOutput` 设置决定是否使用 Windows 控制台颜色 API。如果日志级别低于设置的最小级别，则不输出。 + +**参数：** +- `entry` - 日志条目 + +**复杂度：** O(1) + +**示例：** + +```cpp +auto sink = std::make_unique(); +// Log 方法由 Logger 在内部调用，用户无需直接调用 +XCEngine::Debug::Logger::Get().AddSink(std::move(sink)); +XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Hello console"); +``` + +## 相关文档 + +- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览 diff --git a/docs/api/debug/consolelogsink/setcoloroutput.md b/docs/api/debug/consolelogsink/setcoloroutput.md new file mode 100644 index 00000000..1bea3754 --- /dev/null +++ b/docs/api/debug/consolelogsink/setcoloroutput.md @@ -0,0 +1,24 @@ +# ConsoleLogSink::SetColorOutput + +```cpp +void SetColorOutput(bool enable) +``` + +启用或禁用控制台彩色输出。启用后，不同日志级别使用 Windows 控制台颜色 API 输出，便于快速区分日志类型。 + +**参数：** +- `enable` - true 启用彩色输出，false 禁用 + +**复杂度：** O(1) + +**示例：** + +```cpp +auto sink = std::make_unique(); +sink->SetColorOutput(false); // 禁用颜色（适合日志文件或 CI 环境） +XCEngine::Debug::Logger::Get().AddSink(std::move(sink)); +``` + +## 相关文档 + +- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览 diff --git a/docs/api/debug/consolelogsink/setminimumlevel.md b/docs/api/debug/consolelogsink/setminimumlevel.md new file mode 100644 index 00000000..8b64fa10 --- /dev/null +++ b/docs/api/debug/consolelogsink/setminimumlevel.md @@ -0,0 +1,24 @@ +# ConsoleLogSink::SetMinimumLevel + +```cpp +void SetMinimumLevel(LogLevel level) +``` + +设置该 Sink 的最小输出级别。此设置仅影响当前 Sink，不会影响 Logger 的全局级别过滤。 + +**参数：** +- `level` - 最小日志级别 + +**复杂度：** O(1) + +**示例：** + +```cpp +auto sink = std::make_unique(); +sink->SetMinimumLevel(XCEngine::Debug::LogLevel::Warning); // 控制台只显示警告及以上 +XCEngine::Debug::Logger::Get().AddSink(std::move(sink)); +``` + +## 相关文档 + +- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览 diff --git a/docs/api/debug/consolelogsink/~consolelogsink.md b/docs/api/debug/consolelogsink/~consolelogsink.md new file mode 100644 index 00000000..802c70e5 --- /dev/null +++ b/docs/api/debug/consolelogsink/~consolelogsink.md @@ -0,0 +1,13 @@ +# ConsoleLogSink::~ConsoleLogSink + +```cpp +~ConsoleLogSink() override +``` + +析构函数。销毁 `ConsoleLogSink` 实例，释放相关资源。 + +**复杂度：** O(1) + +## 相关文档 + +- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览 diff --git a/docs/api/debug/debug-consolelogsink.md b/docs/api/debug/debug-consolelogsink.md deleted file mode 100644 index f78f1138..00000000 --- a/docs/api/debug/debug-consolelogsink.md +++ /dev/null @@ -1,52 +0,0 @@ -# ConsoleLogSink - -**命名空间**: `XCEngine::Debug` - -**类型**: `class` - -**描述**: 控制台日志输出槽，将日志输出到标准控制台，支持彩色输出。 - -## 概述 - -`ConsoleLogSink` 是 `ILogSink` 的控制台实现。它将日志输出到 stdout/stderr，支持按日志级别设置不同颜色。 - -## 公共方法 - -### 构造/析构 - -| 方法 | 描述 | -|------|------| -| `ConsoleLogSink()` | 默认构造函数 | -| `~ConsoleLogSink()` | 析构函数 | - -### ILogSink 实现 - -| 方法 | 描述 | -|------|------| -| `void Log(const LogEntry& entry) override` | 输出日志到控制台 | -| `void Flush() override` | 刷新标准输出流 | - -### 配置 - -| 方法 | 描述 | -|------|------| -| `void SetColorOutput(bool enable)` | 启用/禁用彩色输出 | -| `void SetMinimumLevel(LogLevel level)` | 设置最小输出级别 | - -## 使用示例 - -```cpp -// 创建并配置 -auto sink = std::make_unique(); -sink->SetColorOutput(true); -sink->SetMinimumLevel(LogLevel::Debug); - -// 添加到 Logger -Logger::Get().AddSink(std::move(sink)); -``` - -## 相关文档 - -- [Logger](./debug-logger.md) - 日志记录器 -- [ILogSink](./debug-ilogsink.md) - 日志输出接口 -- [FileLogSink](./debug-filelogsink.md) - 文件输出 diff --git a/docs/api/debug/debug-filelogsink.md b/docs/api/debug/debug-filelogsink.md deleted file mode 100644 index c7566966..00000000 --- a/docs/api/debug/debug-filelogsink.md +++ /dev/null @@ -1,47 +0,0 @@ -# FileLogSink - -**命名空间**: `XCEngine::Debug` - -**类型**: `class` - -**描述**: 文件日志输出槽，将日志持久化到磁盘文件。 - -## 概述 - -`FileLogSink` 是 `ILogSink` 的文件实现。它使用 `FileWriter` 将日志追加写入文件，支持自动换行和缓冲区刷新。 - -## 公共方法 - -### 构造/析构 - -| 方法 | 描述 | -|------|------| -| `FileLogSink(const Containers::String& filePath)` | 构造函数，指定文件路径 | -| `~FileLogSink()` | 析构函数 | - -### ILogSink 实现 - -| 方法 | 描述 | -|------|------| -| `void Log(const LogEntry& entry) override` | 将日志追加写入文件 | -| `void Flush() override` | 刷新文件缓冲区 | - -## 使用示例 - -```cpp -// 创建文件日志输出 -auto fileSink = std::make_unique("logs/app.log"); - -// 添加到 Logger -Logger::Get().AddSink(std::move(fileSink)); - -// 日志将自动写入文件 -XE_LOG(LogCategory::General, LogLevel::Info, "Game started"); -``` - -## 相关文档 - -- [Logger](./debug-logger.md) - 日志记录器 -- [ILogSink](./debug-ilogsink.md) - 日志输出接口 -- [ConsoleLogSink](./debug-consolelogsink.md) - 控制台输出 -- [Core/FileWriter](../core/core-filewriter.md) - 文件写入工具 diff --git a/docs/api/debug/debug-overview.md b/docs/api/debug/debug.md similarity index 69% rename from docs/api/debug/debug-overview.md rename to docs/api/debug/debug.md index 3bf23e15..a5823a54 100644 --- a/docs/api/debug/debug-overview.md +++ b/docs/api/debug/debug.md @@ -16,19 +16,19 @@ Debug 模块提供了一套完整的调试工具，包括日志系统和性能 | 组件 | 文件 | 描述 | |------|------|------| -| [Logger](./debug-logger.md) | `Logger.h` | 日志记录器 | -| [ILogSink](./debug-ilogsink.md) | `ILogSink.h` | 日志输出接口 | -| [ConsoleLogSink](./debug-consolelogsink.md) | `ConsoleLogSink.h` | 控制台输出 | -| [FileLogSink](./debug-filelogsink.md) | `FileLogSink.h` | 文件输出 | -| [LogLevel](./debug-loglevel.md) | `LogLevel.h` | 日志级别枚举 | -| [LogCategory](./debug-logcategory.md) | `LogCategory.h` | 日志分类枚举 | -| [LogEntry](./debug-logentry.md) | `LogEntry.h` | 日志条目结构 | +| [Logger](logger/logger.md) | `Logger.h` | 日志记录器 | +| [ILogSink](ilogsink/ilogsink.md) | `ILogSink.h` | 日志输出接口 | +| [ConsoleLogSink](consolelogsink/consolelogsink.md) | `ConsoleLogSink.h` | 控制台输出 | +| [FileLogSink](filelogsink/filelogsink.md) | `FileLogSink.h` | 文件输出 | +| [LogLevel](loglevel/loglevel.md) | `LogLevel.h` | 日志级别枚举 | +| [LogCategory](logcategory/logcategory.md) | `LogCategory.h` | 日志分类枚举 | +| [LogEntry](logentry/logentry.md) | `LogEntry.h` | 日志条目结构 | ### 性能分析 | 组件 | 文件 | 描述 | |------|------|------| -| [Profiler](./debug-profiler.md) | `Profiler.h` | 性能分析器 | +| [Profiler](profiler/profiler.md) | `Profiler.h` | 性能分析器 | ## 日志级别 @@ -80,4 +80,4 @@ if (condition) { ## 相关文档 -- [Profiler](./debug-profiler.md) - 性能分析器 +- [Profiler](profiler/profiler.md) - 性能分析器 diff --git a/docs/api/debug/filelogsink/filelogsink.md b/docs/api/debug/filelogsink/filelogsink.md new file mode 100644 index 00000000..2bec430c --- /dev/null +++ b/docs/api/debug/filelogsink/filelogsink.md @@ -0,0 +1,23 @@ +# FileLogSink::FileLogSink + +```cpp +FileLogSink(const Containers::String& filePath) +``` + +构造函数，打开指定路径的文件用于日志写入。如果文件已存在，则追加写入；如果不存在，则创建新文件。 + +**参数：** +- `filePath` - 日志文件路径 + +**复杂度：** O(1) + +**示例：** + +```cpp +auto fileSink = std::make_unique("logs/engine.log"); +XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink)); +``` + +## 相关文档 + +- [FileLogSink 总览](filelogsink.md) - 返回类总览 diff --git a/docs/api/debug/filelogsink/flush.md b/docs/api/debug/filelogsink/flush.md new file mode 100644 index 00000000..7dd078a4 --- /dev/null +++ b/docs/api/debug/filelogsink/flush.md @@ -0,0 +1,24 @@ +# FileLogSink::Flush + +```cpp +void Flush() override +``` + +刷新文件缓冲区，调用底层 `FileWriter` 的 flush 方法确保所有待写入的日志数据已实际写入磁盘。 + +**复杂度：** O(1) + +**示例：** + +```cpp +auto fileSink = std::make_unique("logs/app.log"); +XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink)); +// 关键操作后立即刷新 +XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Checkpoint saved"); +// 确保写入磁盘 +XCEngine::Debug::Logger::Get().Flush(); +``` + +## 相关文档 + +- [FileLogSink 总览](filelogsink.md) - 返回类总览 diff --git a/docs/api/debug/filelogsink/log.md b/docs/api/debug/filelogsink/log.md new file mode 100644 index 00000000..91563a9e --- /dev/null +++ b/docs/api/debug/filelogsink/log.md @@ -0,0 +1,25 @@ +# FileLogSink::Log + +```cpp +void Log(const LogEntry& entry) override +``` + +将日志条目追加写入文件。根据 `LogEntry` 的各字段格式化日志行，包括时间戳、级别、分类、消息，并追加到文件末尾。 + +**参数：** +- `entry` - 日志条目 + +**复杂度：** O(m)，m 为消息长度 + +**示例：** + +```cpp +auto fileSink = std::make_unique("logs/app.log"); +XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink)); +// Log 方法由 Logger 在内部调用 +XCEngine::Debug::Logger::Get().Error(XCEngine::Debug::LogCategory::FileSystem, "File not found"); +``` + +## 相关文档 + +- [FileLogSink 总览](filelogsink.md) - 返回类总览 diff --git a/docs/api/debug/filelogsink/~filelogsink.md b/docs/api/debug/filelogsink/~filelogsink.md new file mode 100644 index 00000000..17d32059 --- /dev/null +++ b/docs/api/debug/filelogsink/~filelogsink.md @@ -0,0 +1,13 @@ +# FileLogSink::~FileLogSink + +```cpp +~FileLogSink() override +``` + +析构函数。销毁 `FileLogSink` 实例，调用 `Flush()` 确保所有日志数据写入文件，然后关闭文件句柄。 + +**复杂度：** O(1) + +## 相关文档 + +- [FileLogSink 总览](filelogsink.md) - 返回类总览 diff --git a/docs/api/debug/ilogsink/flush.md b/docs/api/debug/ilogsink/flush.md new file mode 100644 index 00000000..f088ee9a --- /dev/null +++ b/docs/api/debug/ilogsink/flush.md @@ -0,0 +1,32 @@ +# ILogSink::Flush + +```cpp +virtual void Flush() = 0 +``` + +刷新输出缓冲区，确保所有待写入的日志数据已实际写入目标介质。对于文件类 Sink，应调用底层文件系统的 flush；对于网络类 Sink，应发送缓冲区中的数据。 + +**复杂度：** O(1) + +**示例：** + +```cpp +class BufferedLogSink : public XCEngine::Debug::ILogSink { +private: + std::string m_buffer; +public: + void Log(const XCEngine::Debug::LogEntry& entry) override { + m_buffer += entry.message.CStr(); + m_buffer += "\n"; + } + void Flush() override { + // 将缓冲区数据写入目标 + writeToDestination(m_buffer); + m_buffer.clear(); + } +}; +``` + +## 相关文档 + +- [ILogSink 总览](ilogsink.md) - 返回类总览 diff --git a/docs/api/debug/debug-ilogsink.md b/docs/api/debug/ilogsink/ilogsink.md similarity index 68% rename from docs/api/debug/debug-ilogsink.md rename to docs/api/debug/ilogsink/ilogsink.md index f2b35229..839144f5 100644 --- a/docs/api/debug/debug-ilogsink.md +++ b/docs/api/debug/ilogsink/ilogsink.md @@ -14,8 +14,8 @@ | 方法 | 描述 | |------|------| -| `virtual void Log(const LogEntry& entry) = 0` | 输出单条日志 | -| `virtual void Flush() = 0` | 刷新缓冲区，确保日志写入 | +| `virtual void Log(const LogEntry& entry) = 0` | [输出单条日志](log.md) | +| `virtual void Flush() = 0` | [刷新缓冲区，确保日志写入](flush.md) | ## 使用示例 @@ -23,7 +23,6 @@ class CustomLogSink : public ILogSink { public: void Log(const LogEntry& entry) override { - // 自定义日志输出逻辑 printf("[%s] %s: %s\n", LogLevelToString(entry.level), LogCategoryToString(entry.category), @@ -31,17 +30,16 @@ public: } void Flush() override { - // 刷新缓冲区 fflush(stdout); } }; -// 注册自定义 Sink Logger::Get().AddSink(std::make_unique()); ``` ## 相关文档 -- [Logger](./debug-logger.md) - 日志记录器 -- [ConsoleLogSink](./debug-consolelogsink.md) - 控制台输出 -- [FileLogSink](./debug-filelogsink.md) - 文件输出 +- [Debug 模块总览](../debug.md) - 返回模块总览 +- [Logger](../logger/logger.md) - 日志记录器 +- [ConsoleLogSink](../consolelogsink/consolelogsink.md) - 控制台输出 +- [FileLogSink](../filelogsink/filelogsink.md) - 文件输出 diff --git a/docs/api/debug/ilogsink/log.md b/docs/api/debug/ilogsink/log.md new file mode 100644 index 00000000..52aa91c0 --- /dev/null +++ b/docs/api/debug/ilogsink/log.md @@ -0,0 +1,29 @@ +# ILogSink::Log + +```cpp +virtual void Log(const LogEntry& entry) = 0 +``` + +输出单条日志到目标介质。`Logger` 在每次日志记录时调用此方法，将包含完整日志信息的 `LogEntry` 传入。派生类需要实现具体的输出逻辑。 + +**参数：** +- `entry` - 日志条目，包含级别、分类、消息、时间戳、线程 ID 等完整信息 + +**复杂度：** O(1) + +**示例：** + +```cpp +class NetworkLogSink : public XCEngine::Debug::ILogSink { +public: + void Log(const XCEngine::Debug::LogEntry& entry) override { + // 将日志发送到远程服务器 + sendToServer(entry.message.CStr()); + } + void Flush() override { } +}; +``` + +## 相关文档 + +- [ILogSink 总览](ilogsink.md) - 返回类总览 diff --git a/docs/api/debug/debug-logcategory.md b/docs/api/debug/logcategory/logcategory.md similarity index 77% rename from docs/api/debug/debug-logcategory.md rename to docs/api/debug/logcategory/logcategory.md index aa5ee886..9932fa86 100644 --- a/docs/api/debug/debug-logcategory.md +++ b/docs/api/debug/logcategory/logcategory.md @@ -29,18 +29,16 @@ | 函数 | 描述 | |------|------| -| `const char* LogCategoryToString(LogCategory category)` | 将日志分类转换为字符串 | +| `const char* LogCategoryToString(LogCategory category)` | [将日志分类转换为字符串](logcategorytostring.md) | ## 使用示例 ```cpp -// 禁用网络日志 Logger::Get().SetCategoryEnabled(LogCategory::Network, false); - -// 输出分类日志 XE_LOG(LogCategory::Rendering, LogLevel::Info, "Draw call submitted"); ``` ## 相关文档 -- [Logger](./debug-logger.md) - 日志记录器 +- [Debug 模块总览](../debug.md) - 返回模块总览 +- [Logger](../logger/logger.md) - 日志记录器 diff --git a/docs/api/debug/logcategory/logcategorytostring.md b/docs/api/debug/logcategory/logcategorytostring.md new file mode 100644 index 00000000..01b9a97c --- /dev/null +++ b/docs/api/debug/logcategory/logcategorytostring.md @@ -0,0 +1,28 @@ +# LogCategoryToString + +```cpp +const char* LogCategoryToString(LogCategory category) +``` + +将 `LogCategory` 枚举值转换为可读字符串。 + +**参数：** +- `category` - 日志分类 + +**返回：** 对应分类的字符串（"General", "Rendering", "Physics" 等） + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +XCEngine::Debug::LogCategory cat = XCEngine::Debug::LogCategory::Rendering; +const char* str = XCEngine::Debug::LogCategoryToString(cat); +// str == "Rendering" +``` + +## 相关文档 + +- [LogCategory 总览](logcategory.md) - 返回类总览 diff --git a/docs/api/debug/debug-logentry.md b/docs/api/debug/logentry/logentry.md similarity index 82% rename from docs/api/debug/debug-logentry.md rename to docs/api/debug/logentry/logentry.md index a8834b8c..ae2e3839 100644 --- a/docs/api/debug/debug-logentry.md +++ b/docs/api/debug/logentry/logentry.md @@ -20,13 +20,12 @@ | `file` | `Containers::String` | 源代码文件路径 | | `line` | `int32_t` | 源代码行号 | | `function` | `Containers::String` | 函数名称 | -| `timestamp` | `uint64_t` | 时间戳（毫秒） | +| `timestamp` | `uint64_t` | 时间戳（秒，Unix 时间戳） | | `threadId` | `uint32_t` | 线程 ID | ## 使用示例 ```cpp -// 实现自定义 Sink 时访问 LogEntry class MySink : public ILogSink { public: void Log(const LogEntry& entry) override { @@ -37,12 +36,12 @@ public: LogLevelToString(entry.level), entry.message.CStr()); } - void Flush() override { } }; ``` ## 相关文档 -- [ILogSink](./debug-ilogsink.md) - 日志输出接口 -- [Logger](./debug-logger.md) - 日志记录器 +- [Debug 模块总览](../debug.md) - 返回模块总览 +- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口 +- [Logger](../logger/logger.md) - 日志记录器 diff --git a/docs/api/debug/logger/addsink.md b/docs/api/debug/logger/addsink.md new file mode 100644 index 00000000..e04eb90d --- /dev/null +++ b/docs/api/debug/logger/addsink.md @@ -0,0 +1,27 @@ +# Logger::AddSink + +```cpp +void AddSink(std::unique_ptr sink) +``` + +向日志系统添加一个输出目标（Sink）。Logger 持有 Sink 的所有权，传入的 `unique_ptr` 被移动到内部容器中。每次日志记录时，所有已注册的 Sink 的 `Log` 方法都会被调用。 + +**参数：** +- `sink` - 要添加的日志输出目标，使用 `std::unique_ptr` 包装 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +XCEngine::Debug::Logger::Get().Initialize(); +XCEngine::Debug::Logger::Get().AddSink(std::make_unique()); +XCEngine::Debug::Logger::Get().AddSink(std::make_unique("app.log")); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 +- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口 diff --git a/docs/api/debug/logger/debug.md b/docs/api/debug/logger/debug.md new file mode 100644 index 00000000..cec3a9cd --- /dev/null +++ b/docs/api/debug/logger/debug.md @@ -0,0 +1,30 @@ +# Logger::Debug + +```cpp +void Debug(LogCategory category, const Containers::String& message) +``` + +记录一条 Debug（1 级）日志。Debug 级别用于一般调试信息，比 Verbose 简洁但比 Info 详细。 + +**参数：** +- `category` - 日志分类 +- `message` - 日志消息内容 + +**返回：** 无 + +**复杂度：** O(n)，n 为注册的 Sink 数量 + +**示例：** + +```cpp +#include + +XCEngine::Debug::Logger::Get().Debug( + XCEngine::Debug::LogCategory::Rendering, + "Draw call batch size: 512" +); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 diff --git a/docs/api/debug/logger/error.md b/docs/api/debug/logger/error.md new file mode 100644 index 00000000..3dcdc5ea --- /dev/null +++ b/docs/api/debug/logger/error.md @@ -0,0 +1,30 @@ +# Logger::Error + +```cpp +void Error(LogCategory category, const Containers::String& message) +``` + +记录一条 Error（4 级）日志。Error 级别用于表示程序执行中发生的错误，如文件读取失败、网络连接中断等。程序通常可以继续运行但功能可能受限。 + +**参数：** +- `category` - 日志分类 +- `message` - 日志消息内容 + +**返回：** 无 + +**复杂度：** O(n)，n 为注册的 Sink 数量 + +**示例：** + +```cpp +#include + +XCEngine::Debug::Logger::Get().Error( + XCEngine::Debug::LogCategory::Network, + "Failed to connect to game server" +); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 diff --git a/docs/api/debug/logger/fatal.md b/docs/api/debug/logger/fatal.md new file mode 100644 index 00000000..fa2fed01 --- /dev/null +++ b/docs/api/debug/logger/fatal.md @@ -0,0 +1,30 @@ +# Logger::Fatal + +```cpp +void Fatal(LogCategory category, const Containers::String& message) +``` + +记录一条 Fatal（5 级）日志。Fatal 级别用于表示不可恢复的严重错误，通常意味着程序即将终止。此方法可能在记录日志后触发程序中断。 + +**参数：** +- `category` - 日志分类 +- `message` - 日志消息内容 + +**返回：** 无 + +**复杂度：** O(n)，n 为注册的 Sink 数量 + +**示例：** + +```cpp +#include + +XCEngine::Debug::Logger::Get().Fatal( + XCEngine::Debug::LogCategory::General, + "Out of memory - cannot continue" +); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 diff --git a/docs/api/debug/logger/get.md b/docs/api/debug/logger/get.md new file mode 100644 index 00000000..19b348c0 --- /dev/null +++ b/docs/api/debug/logger/get.md @@ -0,0 +1,22 @@ +# Logger::Get + +```cpp +static Logger& Get() +``` + +获取 `Logger` 单例实例。Logger 使用局部静态变量实现 Meyers' Singleton，确保线程安全且只初始化一次。 + +**返回：** `Logger&` - 全局日志记录器实例的引用 + +**复杂度：** O(1) + +**示例：** + +```cpp +XCEngine::Debug::Logger& logger = XCEngine::Debug::Logger::Get(); +logger.Initialize(); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 diff --git a/docs/api/debug/logger/info.md b/docs/api/debug/logger/info.md new file mode 100644 index 00000000..74292e68 --- /dev/null +++ b/docs/api/debug/logger/info.md @@ -0,0 +1,30 @@ +# Logger::Info + +```cpp +void Info(LogCategory category, const Containers::String& message) +``` + +记录一条 Info（2 级）日志。Info 级别用于一般性信息，如启动提示、配置加载等用户可见的正常运行消息。 + +**参数：** +- `category` - 日志分类 +- `message` - 日志消息内容 + +**返回：** 无 + +**复杂度：** O(n)，n 为注册的 Sink 数量 + +**示例：** + +```cpp +#include + +XCEngine::Debug::Logger::Get().Info( + XCEngine::Debug::LogCategory::General, + "Application initialized successfully" +); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 diff --git a/docs/api/debug/logger/initialize.md b/docs/api/debug/logger/initialize.md new file mode 100644 index 00000000..7841377b --- /dev/null +++ b/docs/api/debug/logger/initialize.md @@ -0,0 +1,28 @@ +# Logger::Initialize + +```cpp +void Initialize() +``` + +初始化日志系统。在首次使用日志功能前必须调用。初始化内部状态标志，确保日志系统已准备好工作。 + +**注意：** 默认最小日志级别为 `Verbose`，所有日志分类默认启用，这些是类成员变量的默认值，不需要在此方法中设置。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +int main() { + XCEngine::Debug::Logger::Get().Initialize(); + XCEngine::Debug::Logger::Get().AddSink(std::make_unique()); + XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Application started"); + return 0; +} +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 diff --git a/docs/api/debug/logger/log.md b/docs/api/debug/logger/log.md new file mode 100644 index 00000000..8a74bae7 --- /dev/null +++ b/docs/api/debug/logger/log.md @@ -0,0 +1,45 @@ +# Logger::Log + +```cpp +void Log(LogLevel level, LogCategory category, + const Containers::String& message, const char* file = nullptr, + int32_t line = 0, const char* function = nullptr) +``` + +通用日志记录方法。根据设置的最小日志级别和分类开关决定是否输出，然后将日志分发给所有已注册的 Sink。如果日志级别低于最小级别或分类被禁用，则不输出。 + +**参数：** +- `level` - 日志级别（Verbose, Debug, Info, Warning, Error, Fatal） +- `category` - 日志分类（General, Rendering, Physics 等） +- `message` - 日志消息内容 +- `file` - 源代码文件路径（可选，默认 nullptr） +- `line` - 源代码行号（可选，默认 0） +- `function` - 函数名称（可选，默认 nullptr） + +**返回：** 无 + +**复杂度：** O(n)，n 为注册的 Sink 数量 + +**示例：** + +```cpp +#include + +XCEngine::Debug::Logger::Get().Log( + XCEngine::Debug::LogLevel::Error, + XCEngine::Debug::LogCategory::FileSystem, + "Failed to open config file", + __FILE__, + __LINE__, + __FUNCTION__ +); + +// 推荐使用 XE_LOG 宏自动填充位置信息 +XE_LOG(XCEngine::Debug::LogCategory::General, XCEngine::Debug::LogLevel::Info, "Initialized"); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 +- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举 +- [LogCategory](../logcategory/logcategory.md) - 日志分类枚举 diff --git a/docs/api/debug/debug-logger.md b/docs/api/debug/logger/logger.md similarity index 58% rename from docs/api/debug/debug-logger.md rename to docs/api/debug/logger/logger.md index 0224a852..b81031be 100644 --- a/docs/api/debug/debug-logger.md +++ b/docs/api/debug/logger/logger.md @@ -24,34 +24,34 @@ | 方法 | 描述 | |------|------| -| `void Initialize()` | 初始化日志系统 | -| `void Shutdown()` | 关闭日志系统 | +| `void Initialize()` | [初始化日志系统](initialize.md) | +| `void Shutdown()` | [关闭日志系统](shutdown.md) | ### Sink 管理 | 方法 | 描述 | |------|------| -| `void AddSink(std::unique_ptr sink)` | 添加日志输出目标 | -| `void RemoveSink(ILogSink* sink)` | 移除日志输出目标 | +| `void AddSink(std::unique_ptr sink)` | [添加日志输出目标](addsink.md) | +| `void RemoveSink(ILogSink* sink)` | [移除日志输出目标](removesink.md) | ### 日志记录 | 方法 | 描述 | |------|------| -| `void Log(LogLevel level, LogCategory category, const Containers::String& message, const char* file = nullptr, int32_t line = 0, const char* function = nullptr)` | 通用日志记录 | -| `void Verbose(LogCategory category, const Containers::String& message)` | Verbose 级别日志 | -| `void Debug(LogCategory category, const Containers::String& message)` | Debug 级别日志 | -| `void Info(LogCategory category, const Containers::String& message)` | Info 级别日志 | -| `void Warning(LogCategory category, const Containers::String& message)` | Warning 级别日志 | -| `void Error(LogCategory category, const Containers::String& message)` | Error 级别日志 | -| `void Fatal(LogCategory category, const Containers::String& message)` | Fatal 级别日志 | +| `void Log(...)` | [通用日志记录](log.md) | +| `void Verbose(...)` | [Verbose 级别日志](verbose.md) | +| `void Debug(...)` | [Debug 级别日志](debug.md) | +| `void Info(...)` | [Info 级别日志](info.md) | +| `void Warning(...)` | [Warning 级别日志](warning.md) | +| `void Error(...)` | [Error 级别日志](error.md) | +| `void Fatal(...)` | [Fatal 级别日志](fatal.md) | ### 配置 | 方法 | 描述 | |------|------| -| `void SetMinimumLevel(LogLevel level)` | 设置最小日志级别 | -| `void SetCategoryEnabled(LogCategory category, bool enabled)` | 开启/关闭指定分类 | +| `void SetMinimumLevel(...)` | [设置最小日志级别](setminimumlevel.md) | +| `void SetCategoryEnabled(...)` | [开启/关闭指定分类](setcategoryenabled.md) | ## 宏定义 @@ -102,7 +102,8 @@ XE_ASSERT(ptr != nullptr, "Pointer must not be null"); ## 相关文档 -- [ILogSink](./debug-ilogsink.md) - 日志输出接口 -- [ConsoleLogSink](./debug-consolelogsink.md) - 控制台输出 -- [FileLogSink](./debug-filelogsink.md) - 文件输出 -- [LogLevel](./debug-loglevel.md) - 日志级别枚举 +- [Debug 模块总览](../debug.md) - 返回模块总览 +- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口 +- [ConsoleLogSink](../consolelogsink/consolelogsink.md) - 控制台输出 +- [FileLogSink](../filelogsink/filelogsink.md) - 文件输出 +- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举 diff --git a/docs/api/debug/logger/removesink.md b/docs/api/debug/logger/removesink.md new file mode 100644 index 00000000..bc81dabd --- /dev/null +++ b/docs/api/debug/logger/removesink.md @@ -0,0 +1,29 @@ +# Logger::RemoveSink + +```cpp +void RemoveSink(ILogSink* sink) +``` + +从日志系统移除指定的输出目标。通过指针查找并移除对应的 Sink，Logger 不再向该目标发送日志。 + +**参数：** +- `sink` - 要移除的日志输出目标指针 + +**复杂度：** O(n)，n 为注册的 Sink 数量 + +**示例：** + +```cpp +#include + +auto fileSink = std::make_unique("app.log"); +XCEngine::Debug::FileLogSink* rawPtr = fileSink.get(); +XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink)); +// 稍后移除 +XCEngine::Debug::Logger::Get().RemoveSink(rawPtr); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 +- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口 diff --git a/docs/api/debug/logger/setcategoryenabled.md b/docs/api/debug/logger/setcategoryenabled.md new file mode 100644 index 00000000..9f6b5122 --- /dev/null +++ b/docs/api/debug/logger/setcategoryenabled.md @@ -0,0 +1,36 @@ +# Logger::SetCategoryEnabled + +```cpp +void SetCategoryEnabled(LogCategory category, bool enabled) +``` + +启用或禁用指定分类的日志输出。当分类被禁用时，该分类的所有日志都不会分发给 Sink，但级别过滤仍然适用。 + +**参数：** +- `category` - 要设置的日志分类 +- `enabled` - true 表示启用，false 表示禁用 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +// 禁用网络模块日志（减少日志噪音） +XCEngine::Debug::Logger::Get().SetCategoryEnabled( + XCEngine::Debug::LogCategory::Network, + false +); + +// 稍后重新启用 +XCEngine::Debug::Logger::Get().SetCategoryEnabled( + XCEngine::Debug::LogCategory::Network, + true +); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 +- [LogCategory](../logcategory/logcategory.md) - 日志分类枚举 diff --git a/docs/api/debug/logger/setminimumlevel.md b/docs/api/debug/logger/setminimumlevel.md new file mode 100644 index 00000000..175fe78d --- /dev/null +++ b/docs/api/debug/logger/setminimumlevel.md @@ -0,0 +1,30 @@ +# Logger::SetMinimumLevel + +```cpp +void SetMinimumLevel(LogLevel level) +``` + +设置日志系统的最小输出级别。所有低于该级别的日志将被过滤，不会分发给任何 Sink。 + +**参数：** +- `level` - 最小日志级别 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +// 只输出 Warning 及以上级别的日志 +XCEngine::Debug::Logger::Get().SetMinimumLevel(XCEngine::Debug::LogLevel::Warning); + +// Verbose 和 Debug 级别的日志将被过滤 +XCEngine::Debug::Logger::Get().Verbose(XCEngine::Debug::LogCategory::General, "This will not be logged"); +XCEngine::Debug::Logger::Get().Warning(XCEngine::Debug::LogCategory::General, "This will be logged"); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 +- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举 diff --git a/docs/api/debug/logger/shutdown.md b/docs/api/debug/logger/shutdown.md new file mode 100644 index 00000000..79cc35b4 --- /dev/null +++ b/docs/api/debug/logger/shutdown.md @@ -0,0 +1,26 @@ +# Logger::Shutdown + +```cpp +void Shutdown() +``` + +关闭日志系统。移除所有注册的 Sink，刷新缓冲区并重置内部状态。在程序退出前调用，确保所有日志数据已写入输出目标。 + +**复杂度：** O(n)，n 为注册的 Sink 数量 + +**示例：** + +```cpp +#include + +int main() { + XCEngine::Debug::Logger::Get().Initialize(); + // ... 应用逻辑 ... + XCEngine::Debug::Logger::Get().Shutdown(); + return 0; +} +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 diff --git a/docs/api/debug/logger/verbose.md b/docs/api/debug/logger/verbose.md new file mode 100644 index 00000000..9ef925b0 --- /dev/null +++ b/docs/api/debug/logger/verbose.md @@ -0,0 +1,30 @@ +# Logger::Verbose + +```cpp +void Verbose(LogCategory category, const Containers::String& message) +``` + +记录一条 Verbose（0 级）日志。Verbose 是最详细的日志级别，用于输出大量调试细节。 + +**参数：** +- `category` - 日志分类 +- `message` - 日志消息内容 + +**返回：** 无 + +**复杂度：** O(n)，n 为注册的 Sink 数量 + +**示例：** + +```cpp +#include + +XCEngine::Debug::Logger::Get().Verbose( + XCEngine::Debug::LogCategory::Memory, + "Memory pool fragmentation: 12.5%" +); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 diff --git a/docs/api/debug/logger/warning.md b/docs/api/debug/logger/warning.md new file mode 100644 index 00000000..f7e7efc2 --- /dev/null +++ b/docs/api/debug/logger/warning.md @@ -0,0 +1,30 @@ +# Logger::Warning + +```cpp +void Warning(LogCategory category, const Containers::String& message) +``` + +记录一条 Warning（3 级）日志。Warning 级别用于指示潜在问题但程序仍可继续运行的情况，如资源即将耗尽、配置值超出建议范围等。 + +**参数：** +- `category` - 日志分类 +- `message` - 日志消息内容 + +**返回：** 无 + +**复杂度：** O(n)，n 为注册的 Sink 数量 + +**示例：** + +```cpp +#include + +XCEngine::Debug::Logger::Get().Warning( + XCEngine::Debug::LogCategory::Memory, + "Memory usage exceeds 80% of available heap" +); +``` + +## 相关文档 + +- [Logger 总览](logger.md) - 返回类总览 diff --git a/docs/api/debug/debug-loglevel.md b/docs/api/debug/loglevel/loglevel.md similarity index 77% rename from docs/api/debug/debug-loglevel.md rename to docs/api/debug/loglevel/loglevel.md index 84b844c5..eda973be 100644 --- a/docs/api/debug/debug-loglevel.md +++ b/docs/api/debug/loglevel/loglevel.md @@ -25,16 +25,16 @@ | 函数 | 描述 | |------|------| -| `const char* LogLevelToString(LogLevel level)` | 将日志级别转换为字符串 | +| `const char* LogLevelToString(LogLevel level)` | [将日志级别转换为字符串](logleveltostring.md) | ## 使用示例 ```cpp -// 设置最小日志级别 Logger::Get().SetMinimumLevel(LogLevel::Warning); // 只有 Warning、Error、Fatal 级别的日志会被输出 ``` ## 相关文档 -- [Logger](./debug-logger.md) - 日志记录器 +- [Debug 模块总览](../debug.md) - 返回模块总览 +- [Logger](../logger/logger.md) - 日志记录器 diff --git a/docs/api/debug/loglevel/logleveltostring.md b/docs/api/debug/loglevel/logleveltostring.md new file mode 100644 index 00000000..8a76a352 --- /dev/null +++ b/docs/api/debug/loglevel/logleveltostring.md @@ -0,0 +1,28 @@ +# LogLevelToString + +```cpp +const char* LogLevelToString(LogLevel level) +``` + +将 `LogLevel` 枚举值转换为可读字符串。 + +**参数：** +- `level` - 日志级别 + +**返回：** 对应级别的字符串（"VERBOSE", "DEBUG", "INFO", "WARNING", "ERROR", "FATAL"） + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +XCEngine::Debug::LogLevel level = XCEngine::Debug::LogLevel::Error; +const char* str = XCEngine::Debug::LogLevelToString(level); +// str == "Error" +``` + +## 相关文档 + +- [LogLevel 总览](loglevel.md) - 返回类总览 diff --git a/docs/api/debug/profiler/beginframe.md b/docs/api/debug/profiler/beginframe.md new file mode 100644 index 00000000..109142d0 --- /dev/null +++ b/docs/api/debug/profiler/beginframe.md @@ -0,0 +1,26 @@ +# Profiler::BeginFrame + +```cpp +void BeginFrame() +``` + +开始一帧的性能分析。记录当前帧的起始时间戳，用于计算帧级别的性能指标。应在每帧渲染开始时调用。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +void GameLoop() { + XCEngine::Debug::Profiler::Get().BeginFrame(); + Update(); + Render(); + XCEngine::Debug::Profiler::Get().EndFrame(); +} +``` + +## 相关文档 + +- [Profiler 总览](profiler.md) - 返回类总览 diff --git a/docs/api/debug/profiler/beginprofile.md b/docs/api/debug/profiler/beginprofile.md new file mode 100644 index 00000000..0203a51b --- /dev/null +++ b/docs/api/debug/profiler/beginprofile.md @@ -0,0 +1,36 @@ +# Profiler::BeginProfile + +```cpp +void BeginProfile(const char* name) +``` + +开始一个性能分析块。将分析节点压入栈中并记录开始时间。每次调用 `BeginProfile` 应与一次 `EndProfile` 配对使用。 + +**参数：** +- `name` - 分析块的名称，用于在导出结果中标识 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +void ProcessMesh() { + XCEngine::Debug::Profiler::Get().BeginProfile("ProcessMesh"); + + XCEngine::Debug::Profiler::Get().BeginProfile("ComputeVertices"); + ComputeVertices(); + XCEngine::Debug::Profiler::Get().EndProfile(); + + XCEngine::Debug::Profiler::Get().BeginProfile("ComputeIndices"); + ComputeIndices(); + XCEngine::Debug::Profiler::Get().EndProfile(); + + XCEngine::Debug::Profiler::Get().EndProfile(); +} +``` + +## 相关文档 + +- [Profiler 总览](profiler.md) - 返回类总览 diff --git a/docs/api/debug/profiler/endframe.md b/docs/api/debug/profiler/endframe.md new file mode 100644 index 00000000..d9e208b8 --- /dev/null +++ b/docs/api/debug/profiler/endframe.md @@ -0,0 +1,26 @@ +# Profiler::EndFrame + +```cpp +void EndFrame() +``` + +结束一帧的性能分析。记录当前帧的结束时间，计算帧耗时并可用于帧率统计。应在每帧渲染结束时调用。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +void GameLoop() { + XCEngine::Debug::Profiler::Get().BeginFrame(); + Update(); + Render(); + XCEngine::Debug::Profiler::Get().EndFrame(); +} +``` + +## 相关文档 + +- [Profiler 总览](profiler.md) - 返回类总览 diff --git a/docs/api/debug/profiler/endprofile.md b/docs/api/debug/profiler/endprofile.md new file mode 100644 index 00000000..c231a29b --- /dev/null +++ b/docs/api/debug/profiler/endprofile.md @@ -0,0 +1,25 @@ +# Profiler::EndProfile + +```cpp +void EndProfile() +``` + +结束当前性能分析块。从栈顶弹出分析节点并计算持续时间（endTime - startTime），将结果保存到样本列表中。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +void RenderPipeline() { + XCEngine::Debug::Profiler::Get().BeginProfile("RenderPipeline"); + // ... 渲染逻辑 ... + XCEngine::Debug::Profiler::Get().EndProfile(); +} +``` + +## 相关文档 + +- [Profiler 总览](profiler.md) - 返回类总览 diff --git a/docs/api/debug/profiler/exportchrometracing.md b/docs/api/debug/profiler/exportchrometracing.md new file mode 100644 index 00000000..f0f7829a --- /dev/null +++ b/docs/api/debug/profiler/exportchrometracing.md @@ -0,0 +1,45 @@ +# Profiler::ExportChromeTracing + +```cpp +void ExportChromeTracing(const Containers::String& filePath) +``` + +**状态：** 此方法目前为空实现，暂未功能。 + +将收集的性能数据导出为 Chrome Tracing JSON 格式。导出的文件可通过 Chrome 浏览器打开（地址栏输入 `chrome://tracing` 并加载文件）进行可视化分析。 + +**参数：** +- `filePath` - 输出文件路径 + +**复杂度：** O(n)，n 为记录的样本数量 + +**示例：** + +```cpp +#include + +XCEngine::Debug::Profiler::Get().Initialize(); + +void RenderFrame() { + XCEngine::Debug::Profiler::Get().BeginFrame(); + XE_PROFILE_FUNCTION(); + + XE_PROFILE_BEGIN("UpdateScene"); + UpdateScene(); + XE_PROFILE_END(); + + XE_PROFILE_BEGIN("DrawScene"); + DrawScene(); + XE_PROFILE_END(); + + XCEngine::Debug::Profiler::Get().EndFrame(); +} + +// 运行一段时间后导出 +XCEngine::Debug::Profiler::Get().ExportChromeTracing("trace.json"); +XCEngine::Debug::Profiler::Get().Shutdown(); +``` + +## 相关文档 + +- [Profiler 总览](profiler.md) - 返回类总览 diff --git a/docs/api/debug/profiler/get.md b/docs/api/debug/profiler/get.md new file mode 100644 index 00000000..7ee09d69 --- /dev/null +++ b/docs/api/debug/profiler/get.md @@ -0,0 +1,22 @@ +# Profiler::Get + +```cpp +static Profiler& Get() +``` + +获取 `Profiler` 单例实例。Profiler 使用局部静态变量实现 Meyers' Singleton，确保线程安全且只初始化一次。 + +**返回：** `Profiler&` - 全局性能分析器实例的引用 + +**复杂度：** O(1) + +**示例：** + +```cpp +XCEngine::Debug::Profiler& profiler = XCEngine::Debug::Profiler::Get(); +profiler.Initialize(); +``` + +## 相关文档 + +- [Profiler 总览](profiler.md) - 返回类总览 diff --git a/docs/api/debug/profiler/initialize.md b/docs/api/debug/profiler/initialize.md new file mode 100644 index 00000000..eb9dcef7 --- /dev/null +++ b/docs/api/debug/profiler/initialize.md @@ -0,0 +1,30 @@ +# Profiler::Initialize + +```cpp +void Initialize() +``` + +初始化性能分析器。在首次使用性能分析功能前必须调用。初始化内部状态标志，确保分析器已准备好工作。 + +**注意：** 帧计时器等数据结构在首次 BeginFrame 时自动初始化。 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +int main() { + XCEngine::Debug::Profiler::Get().Initialize(); + XCEngine::Debug::Profiler::Get().BeginFrame(); + // ... 性能测量 ... + XCEngine::Debug::Profiler::Get().EndFrame(); + XCEngine::Debug::Profiler::Get().Shutdown(); + return 0; +} +``` + +## 相关文档 + +- [Profiler 总览](profiler.md) - 返回类总览 diff --git a/docs/api/debug/profiler/markevent.md b/docs/api/debug/profiler/markevent.md new file mode 100644 index 00000000..b1c73252 --- /dev/null +++ b/docs/api/debug/profiler/markevent.md @@ -0,0 +1,36 @@ +# Profiler::MarkEvent + +```cpp +void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId) +``` + +**状态：** 此方法目前为空实现，暂未功能。 + +在指定时间点标记一个事件。用于记录离散的瞬时事件，如 GPU 命令提交、状态切换等，通常用于多线程性能分析。 + +**参数：** +- `name` - 事件名称 +- `timestamp` - 事件发生的时间戳（微秒） +- `threadId` - 事件所属的线程 ID + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +// 在多线程场景中标记事件 +void WorkerThread() { + uint32_t tid = GetCurrentThreadId(); + uint64_t ts = GetTickCount(); + + XCEngine::Debug::Profiler::Get().MarkEvent("TaskStarted", ts, tid); + DoWork(); + XCEngine::Debug::Profiler::Get().MarkEvent("TaskCompleted", GetTickCount(), tid); +} +``` + +## 相关文档 + +- [Profiler 总览](profiler.md) - 返回类总览 diff --git a/docs/api/debug/debug-profiler.md b/docs/api/debug/profiler/profiler.md similarity index 71% rename from docs/api/debug/debug-profiler.md rename to docs/api/debug/profiler/profiler.md index 34bac893..50469d7a 100644 --- a/docs/api/debug/debug-profiler.md +++ b/docs/api/debug/profiler/profiler.md @@ -22,35 +22,35 @@ | 方法 | 描述 | |------|------| -| `void Initialize()` | 初始化性能分析器 | -| `void Shutdown()` | 关闭性能分析器 | +| `void Initialize()` | [初始化性能分析器](initialize.md) | +| `void Shutdown()` | [关闭性能分析器](shutdown.md) | ### 性能测量 | 方法 | 描述 | |------|------| -| `void BeginProfile(const char* name)` | 开始一个性能分析块 | -| `void EndProfile()` | 结束当前性能分析块 | +| `void BeginProfile(const char* name)` | [开始一个性能分析块](beginprofile.md) | +| `void EndProfile()` | [结束当前性能分析块](endprofile.md) | ### 帧管理 | 方法 | 描述 | |------|------| -| `void BeginFrame()` | 开始一帧的分析 | -| `void EndFrame()` | 结束一帧的分析 | +| `void BeginFrame()` | [开始一帧的分析](beginframe.md) | +| `void EndFrame()` | [结束一帧的分析](endframe.md) | ### 事件标记 | 方法 | 描述 | |------|------| -| `void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId)` | 标记一个事件点 | -| `void SetMarker(const char* name, uint32_t color)` | 设置帧标记 | +| `void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId)` | [标记一个事件点](markevent.md) | +| `void SetMarker(const char* name, uint32_t color)` | [设置帧标记](setmarker.md) | ### 导出 | 方法 | 描述 | |------|------| -| `void ExportChromeTracing(const Containers::String& filePath)` | 导出为 Chrome Tracing JSON 格式 | +| `void ExportChromeTracing(const Containers::String& filePath)` | [导出为 Chrome Tracing JSON 格式](exportchrometracing.md) | ## 宏定义 @@ -81,10 +81,8 @@ ## 使用示例 ```cpp -// 初始化 Profiler::Get().Initialize(); -// 使用宏自动管理生命周期 void RenderFrame() { XE_PROFILE_FUNCTION(); @@ -101,17 +99,14 @@ void RenderFrame() { } } -// 帧管理 Profiler::Get().BeginFrame(); // ... 渲染帧 ... Profiler::Get().EndFrame(); - -// 导出 Chrome Tracing 格式 Profiler::Get().ExportChromeTracing("profile.json"); - Profiler::Get().Shutdown(); ``` ## 相关文档 -- [Logger](./debug-logger.md) - 日志记录器 +- [Debug 模块总览](../debug.md) - 返回模块总览 +- [Logger](../logger/logger.md) - 日志记录器 diff --git a/docs/api/debug/profiler/setmarker.md b/docs/api/debug/profiler/setmarker.md new file mode 100644 index 00000000..a9610c8c --- /dev/null +++ b/docs/api/debug/profiler/setmarker.md @@ -0,0 +1,33 @@ +# Profiler::SetMarker + +```cpp +void SetMarker(const char* name, uint32_t color) +``` + +**状态：** 此方法目前为空实现，暂未功能。 + +在 Chrome Tracing 时间线上设置一个标记点，用于标记特定位置或状态。标记会显示为一条垂直线，便于在性能图中定位关键事件。 + +**参数：** +- `name` - 标记名称 +- `color` - 标记颜色（ABGR 格式） + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +void OnVBlank() { + XCEngine::Debug::Profiler::Get().SetMarker("VBlank", 0xFF00FF00); // 绿色 +} + +void OnRenderComplete() { + XCEngine::Debug::Profiler::Get().SetMarker("FrameRendered", 0xFFFF0000); // 红色 +} +``` + +## 相关文档 + +- [Profiler 总览](profiler.md) - 返回类总览 diff --git a/docs/api/debug/profiler/shutdown.md b/docs/api/debug/profiler/shutdown.md new file mode 100644 index 00000000..8d01e540 --- /dev/null +++ b/docs/api/debug/profiler/shutdown.md @@ -0,0 +1,22 @@ +# Profiler::Shutdown + +```cpp +void Shutdown() +``` + +关闭性能分析器。清理内部数据结构，停止所有活动分析块，重置状态。在程序退出前调用。 + +**复杂度：** O(1) + +**示例：** + +```cpp +XCEngine::Debug::Profiler::Get().Initialize(); +// ... 使用 Profiler ... +XCEngine::Debug::Profiler::Get().ExportChromeTracing("profile.json"); +XCEngine::Debug::Profiler::Get().Shutdown(); +``` + +## 相关文档 + +- [Profiler 总览](profiler.md) - 返回类总览 diff --git a/docs/api/fix_links.py b/docs/api/fix_links.py new file mode 100644 index 00000000..36867eae --- /dev/null +++ b/docs/api/fix_links.py @@ -0,0 +1,238 @@ +#!/usr/bin/env python3 +""" +Fix broken cross-references in API documentation. +""" + +import os +import re +from pathlib import Path + +API_DOCS_ROOT = Path(r"D:\Xuanchi\Main\XCEngine\docs\api") + + +def normalize_path(path_str): + """Remove duplicate path segments like ./module/./module/.""" + parts = [] + for part in path_str.replace("\\", "/").split("/"): + if part == "." or part == "": + continue + parts.append(part) + return "/".join(parts) + + +def resolve_reference(current_file, ref_path): + """Resolve a reference path relative to current file and check if it exists.""" + current_file = Path(current_file) + parent_dir = current_file.parent + + # Normalize the reference path + normalized_ref = normalize_path(ref_path) + + # Try to resolve the path + resolved = (parent_dir / normalized_ref).resolve() + + # Also try with normalized path + resolved2 = (parent_dir / ref_path.replace("\\", "/")).resolve() + + return resolved, resolved2 + + +def get_relative_path(from_file, to_file): + """Get correct relative path from one file to another.""" + from_file = Path(from_file) + to_file = Path(to_file) + + # Get common prefix + from_parts = from_file.parts + to_parts = to_file.parts + + # Find common prefix length + common_len = 0 + for i in range(min(len(from_parts), len(to_parts))): + if from_parts[i] == to_parts[i]: + common_len = i + 1 + else: + break + + # Build relative path + up_count = len(from_parts) - common_len - 1 # -1 for the filename + parts = [".."] * up_count + list(to_parts[common_len:]) + + return "/".join(parts) + + +def find_file_by_name(target_name, base_dir): + """Find a file with given name in the base directory.""" + base_dir = Path(base_dir) + api_docs = API_DOCS_ROOT + + # Search for the file + pattern = f"**/{target_name}" + matches = list(api_docs.glob(pattern)) + + # Filter for exact filename match + for match in matches: + if match.name == target_name: + return match + + return None + + +def fix_links_in_file(file_path, verbose=True): + """Analyze and fix links in a single file.""" + file_path = Path(file_path) + + if not file_path.exists(): + return [] + + with open(file_path, "r", encoding="utf-8") as f: + content = f.read() + + original_content = content + fixes = [] + + # Find all markdown links: [text](path) + link_pattern = r"\[([^\]]*)\]\(([^)]+\.md)\)" + + def replace_link(match): + link_text = match.group(1) + link_path = match.group(2) + + # Skip external links + if link_path.startswith("http://") or link_path.startswith("https://"): + return match.group(0) + + # Skip anchor links + if link_path.startswith("#"): + return match.group(0) + + # Normalize the path + normalized = normalize_path(link_path) + + # Try to resolve the target file + parent_dir = file_path.parent + + # Try the exact path first + target_path = parent_dir / link_path.replace("\\", "/") + target_exists = target_path.exists() + + if not target_exists: + # Try normalized path + target_path = parent_dir / normalized + target_exists = target_path.exists() + + if not target_exists: + # Try to find the file elsewhere + # Get just the filename + filename = Path(normalized).name + + # Try to find it + found = find_file_by_name(filename, API_DOCS_ROOT) + if found: + # Calculate correct relative path + correct_rel = get_relative_path(file_path, found) + if correct_rel != normalized: + fixes.append( + { + "file": file_path, + "line": content[: match.start()].count("\n") + 1, + "old": link_path, + "new": correct_rel, + "target": found, + } + ) + return f"[{link_text}]({correct_rel})" + else: + fixes.append( + { + "file": file_path, + "line": content[: match.start()].count("\n") + 1, + "old": link_path, + "new": None, + "target": None, + "error": "Target file not found", + } + ) + return match.group(0) + elif normalized != link_path: + # Path has duplicate segments that need fixing + fixes.append( + { + "file": file_path, + "line": content[: match.start()].count("\n") + 1, + "old": link_path, + "new": normalized, + "target": target_path, + } + ) + return f"[{link_text}]({normalized})" + + return match.group(0) + + new_content = re.sub(link_pattern, replace_link, content) + + if new_content != original_content: + with open(file_path, "w", encoding="utf-8") as f: + f.write(new_content) + + return fixes + + +def main(): + print("=" * 70) + print("API Documentation Cross-Reference Fixer") + print("=" * 70) + + # Collect all markdown files + md_files = list(API_DOCS_ROOT.glob("**/*.md")) + print(f"\nFound {len(md_files)} markdown files in {API_DOCS_ROOT}") + + all_fixes = [] + broken_refs = [] + + for md_file in md_files: + fixes = fix_links_in_file(md_file, verbose=False) + for fix in fixes: + if fix.get("error"): + broken_refs.append(fix) + else: + all_fixes.append(fix) + + print(f"\n{'=' * 70}") + print("FIXES APPLIED:") + print("=" * 70) + + if all_fixes: + for fix in all_fixes: + rel_file = fix["file"].relative_to(API_DOCS_ROOT) + print(f"\n File: {rel_file}") + print(f" Line: {fix['line']}") + print(f" Old: {fix['old']}") + print(f" New: {fix['new']}") + else: + print("\n No fixes needed.") + + print(f"\n{'=' * 70}") + print("BROKEN REFERENCES (target files don't exist):") + print("=" * 70) + + if broken_refs: + for ref in broken_refs: + rel_file = ref["file"].relative_to(API_DOCS_ROOT) + print(f"\n File: {rel_file}") + print(f" Line: {ref['line']}") + print(f" Broken ref: {ref['old']}") + else: + print("\n No broken references found.") + + print(f"\n{'=' * 70}") + print(f"SUMMARY:") + print(f" Total fixes applied: {len(all_fixes)}") + print(f" Broken references: {len(broken_refs)}") + print("=" * 70) + + return len(all_fixes), len(broken_refs) + + +if __name__ == "__main__": + main() diff --git a/docs/api/index.md b/docs/api/main.md similarity index 66% rename from docs/api/index.md rename to docs/api/main.md index a6e448cc..6d5f9650 100644 --- a/docs/api/index.md +++ b/docs/api/main.md @@ -8,16 +8,16 @@ | 模块 | 文档目录 | 描述 | |------|----------|------| -| **RHI** | [rhi/](./rhi/rhi-overview.md) | 渲染硬件接口抽象层 | -| **D3D12** | [rhi/d3d12/](./rhi/d3d12/d3d12-overview.md) | DirectX 12 后端实现 | -| **OpenGL** | [rhi/opengl/](./rhi/opengl/opengl-overview.md) | OpenGL 后端实现 | -| **Containers** | [containers/](./containers/container-overview.md) | 容器数据结构 | -| **Memory** | [memory/](./memory/memory-overview.md) | 内存管理 | -| **Threading** | [threading/](./threading/threading-overview.md) | 多线程和任务系统 | -| **Core** | [core/](./core/core-overview.md) | 核心基础类型 | -| **Debug** | [debug/](./debug/debug-overview.md) | 调试和日志 | -| **Math** | [math/](./math/math-overview.md) | 数学库 | -| **Resources** | [resources/](./resources/resources-overview.md) | 资源管理系统 | +| **RHI** | [rhi/](rhi/rhi.md) | 渲染硬件接口抽象层 | +| **D3D12** | [rhi/d3d12/](rhi/d3d12/overview.md) | DirectX 12 后端实现 | +| **OpenGL** | [rhi/opengl/](rhi/opengl/overview.md) | OpenGL 后端实现 | +| **Containers** | [containers/](containers/containers.md) | 容器数据结构 | +| **Memory** | [memory/](memory/memory.md) | 内存管理 | +| **Threading** | [threading/](threading/threading.md) | 多线程和任务系统 | +| **Core** | [core/](core/core.md) | 核心基础类型 | +| **Debug** | [debug/](debug/debug.md) | 调试和日志 | +| **Math** | [math/](math/math.md) | 数学库 | +| **Resources** | [resources/](resources/resources.md) | 资源管理系统 | --- diff --git a/docs/api/math/aabb/aabb.md b/docs/api/math/aabb/aabb.md new file mode 100644 index 00000000..b72251e2 --- /dev/null +++ b/docs/api/math/aabb/aabb.md @@ -0,0 +1,43 @@ +# AABB / OBB + +轴对齐包围盒 (AABB) 和有向包围盒 (OBB)。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## AABB + +`AABB` 在 Math 库中通过 `Bounds` 类型实现，参见 [./bounds/bounds.md](../bounds/bounds.md)。 + +## OBB - 有向包围盒 + +OBB 是可以任意方向旋转的包围盒。 + +```cpp +struct OBB { + Vector3 center; + Vector3 extents; + Matrix4 transform; +}; +``` + +### 构造函数 + +- `OBB()` - 默认构造 +- `OBB(const Vector3& center, const Vector3& extents)` - 从中心和半长构造 + +### 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [GetAxis(index)](obb-getaxis.md) | `Vector3` | 获取局部轴 | +| [GetMin()](obb-getmin.md) | `Vector3` | 局部空间最小点 | +| [GetMax()](obb-getmax.md) | `Vector3` | 局部空间最大点 | +| [Contains(point)](obb-contains.md) | `bool` | 点是否在 OBB 内 | +| [Intersects(OBB)](obb-intersects-obb.md) | `bool` | 与另一个 OBB 相交 | +| [Intersects(Sphere)](obb-intersects-sphere.md) | `bool` | 与球体相交 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/aabb/obb-contains.md b/docs/api/math/aabb/obb-contains.md new file mode 100644 index 00000000..9aee18e0 --- /dev/null +++ b/docs/api/math/aabb/obb-contains.md @@ -0,0 +1,20 @@ +# OBB::Contains + +```cpp +bool Contains(const Vector3& point) const +``` + +检测点是否在 OBB 内。 + +**参数：** +- `point` - 要检测的点 + +**返回：** `bool` - true 表示点在 OBB 内 + +**复杂度：** O(1) + +**示例：** + +```cpp +if (obb.Contains(point)) { /* inside */ } +``` diff --git a/docs/api/math/aabb/obb-getaxis.md b/docs/api/math/aabb/obb-getaxis.md new file mode 100644 index 00000000..c438abcc --- /dev/null +++ b/docs/api/math/aabb/obb-getaxis.md @@ -0,0 +1,20 @@ +# OBB::GetAxis + +```cpp +Vector3 GetAxis(int index) const +``` + +获取 OBB 的局部轴。 + +**参数：** +- `index` - 轴索引 (0=X, 1=Y, 2=Z) + +**返回：** `Vector3` - 对应的局部轴 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 xAxis = obb.GetAxis(0); +``` diff --git a/docs/api/math/aabb/obb-getmax.md b/docs/api/math/aabb/obb-getmax.md new file mode 100644 index 00000000..04e56e81 --- /dev/null +++ b/docs/api/math/aabb/obb-getmax.md @@ -0,0 +1,17 @@ +# OBB::GetMax + +```cpp +Vector3 GetMax() const +``` + +获取局部空间最大点。 + +**返回：** `Vector3` - center + extents + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 max = obb.GetMax(); +``` diff --git a/docs/api/math/aabb/obb-getmin.md b/docs/api/math/aabb/obb-getmin.md new file mode 100644 index 00000000..34d1bf14 --- /dev/null +++ b/docs/api/math/aabb/obb-getmin.md @@ -0,0 +1,17 @@ +# OBB::GetMin + +```cpp +Vector3 GetMin() const +``` + +获取局部空间最小点。 + +**返回：** `Vector3` - center - extents + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 min = obb.GetMin(); +``` diff --git a/docs/api/math/aabb/obb-intersects-obb.md b/docs/api/math/aabb/obb-intersects-obb.md new file mode 100644 index 00000000..fb06b8a1 --- /dev/null +++ b/docs/api/math/aabb/obb-intersects-obb.md @@ -0,0 +1,25 @@ +# OBB::Intersects(OBB) + +```cpp +bool Intersects(const OBB& other) const; +``` + +判断两个 OBB 是否相交（SAT 分离轴定理）。 + +**返回：** 两包围盒是否相交 + +**复杂度：** O(1) + +**示例：** + +```cpp +OBB a(centerA, extentsA); +OBB b(centerB, extentsB); +if (a.Intersects(b)) { + // 两包围盒相交 +} +``` + +## 相关文档 + +- [AABB 总览](aabb.md) - 返回 AABB 概览 diff --git a/docs/api/math/aabb/obb-intersects-sphere.md b/docs/api/math/aabb/obb-intersects-sphere.md new file mode 100644 index 00000000..57071efc --- /dev/null +++ b/docs/api/math/aabb/obb-intersects-sphere.md @@ -0,0 +1,28 @@ +# OBB::Intersects(Sphere) + +```cpp +bool Intersects(const Sphere& sphere) const; +``` + +判断 OBB 与球体是否相交。 + +**参数：** +- `sphere` - 球体 + +**返回：** OBB 与球体是否相交 + +**复杂度：** O(1) + +**示例：** + +```cpp +OBB obb(center, extents); +Sphere s(sphereCenter, radius); +if (obb.Intersects(s)) { + // OBB 与球体相交 +} +``` + +## 相关文档 + +- [AABB 总览](aabb.md) - 返回 AABB 概览 diff --git a/docs/api/math/bounds/bounds.md b/docs/api/math/bounds/bounds.md new file mode 100644 index 00000000..ba8aaf29 --- /dev/null +++ b/docs/api/math/bounds/bounds.md @@ -0,0 +1,40 @@ +# Bounds + +轴对齐包围盒 (AABB)，中心-范围表示。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Bounds { + Vector3 center = Vector3::Zero(); + Vector3 extents = Vector3::Zero(); +}; +``` + +## 构造函数 + +- `Bounds()` - 默认构造 +- `Bounds(const Vector3& center, const Vector3& size)` - 从中心和大小构造 + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [GetMin()](getmin.md) | `Vector3` | 最小点 | +| [GetMax()](getmax.md) | 最大点 | +| [SetMinMax(min, max)](setminmax.md) | `void` | 从最小/最大点设置 | +| [Contains(point)](contains.md) | `bool` | 点是否在盒内 | +| [Intersects(other)](intersects.md) | `bool` | 与另一个 Bounds 相交 | +| [Encapsulate(point)](encapsulate.md) | `void` | 扩展包含点 | +| [Encapsulate(bounds)](encapsulate-bounds.md) | `void` | 扩展包含另一个 Bounds | +| [Expand(amount)](expand.md) | `void` | 扩展包围盒 | +| [GetClosestPoint(point)](getclosestpoint.md) | `Vector3` | 盒上最接近的点 | +| [GetVolume()](getvolume.md) | `float` | 体积 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/bounds/contains.md b/docs/api/math/bounds/contains.md new file mode 100644 index 00000000..12cb6eff --- /dev/null +++ b/docs/api/math/bounds/contains.md @@ -0,0 +1,20 @@ +# Bounds::Contains + +```cpp +bool Contains(const Vector3& point) const +``` + +检测点是否在包围盒内。 + +**参数：** +- `point` - 要检测的点 + +**返回：** `bool` - true 表示点在盒内 + +**复杂度：** O(1) + +**示例：** + +```cpp +if (bounds.Contains(point)) { /* inside */ } +``` diff --git a/docs/api/math/bounds/encapsulate-bounds.md b/docs/api/math/bounds/encapsulate-bounds.md new file mode 100644 index 00000000..b6286108 --- /dev/null +++ b/docs/api/math/bounds/encapsulate-bounds.md @@ -0,0 +1,18 @@ +# Bounds::Encapsulate (Bounds) + +```cpp +void Encapsulate(const Bounds& bounds) +``` + +扩展包围盒以包含另一个 Bounds。 + +**参数：** +- `bounds` - 要包含的 Bounds + +**复杂度：** O(1) + +**示例：** + +```cpp +bounds.Encapsulate(otherBounds); +``` diff --git a/docs/api/math/bounds/encapsulate.md b/docs/api/math/bounds/encapsulate.md new file mode 100644 index 00000000..5a18ed31 --- /dev/null +++ b/docs/api/math/bounds/encapsulate.md @@ -0,0 +1,21 @@ +# Bounds::Encapsulate + +```cpp +void Encapsulate(const Vector3& point) +void Encapsulate(const Bounds& bounds) +``` + +扩展包围盒以包含点或另一个 Bounds。 + +**参数：** +- `point` - 要包含的点 +- `bounds` - 要包含的 Bounds + +**复杂度：** O(1) + +**示例：** + +```cpp +bounds.Encapsulate(point); +bounds.Encapsulate(otherBounds); +``` diff --git a/docs/api/math/bounds/expand.md b/docs/api/math/bounds/expand.md new file mode 100644 index 00000000..e9f1458f --- /dev/null +++ b/docs/api/math/bounds/expand.md @@ -0,0 +1,19 @@ +# Bounds::Expand + +```cpp +void Expand(float amount) +void Expand(const Vector3& amount) +``` + +扩展包围盒。 + +**参数：** +- `amount` - 扩展量（各方向或统一） + +**复杂度：** O(1) + +**示例：** + +```cpp +bounds.Expand(1.0f); +``` diff --git a/docs/api/math/bounds/getclosestpoint.md b/docs/api/math/bounds/getclosestpoint.md new file mode 100644 index 00000000..96202ce5 --- /dev/null +++ b/docs/api/math/bounds/getclosestpoint.md @@ -0,0 +1,20 @@ +# Bounds::GetClosestPoint + +```cpp +Vector3 GetClosestPoint(const Vector3& point) const +``` + +获取包围盒上最接近给定点的点。 + +**参数：** +- `point` - 参考点 + +**返回：** `Vector3` - 盒上最接近的点 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 closest = bounds.GetClosestPoint(point); +``` diff --git a/docs/api/math/bounds/getmax.md b/docs/api/math/bounds/getmax.md new file mode 100644 index 00000000..c41e81d7 --- /dev/null +++ b/docs/api/math/bounds/getmax.md @@ -0,0 +1,17 @@ +# Bounds::GetMax + +```cpp +Vector3 GetMax() const +``` + +获取包围盒的最大点。 + +**返回：** `Vector3` - center + extents + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 max = bounds.GetMax(); +``` diff --git a/docs/api/math/bounds/getmin.md b/docs/api/math/bounds/getmin.md new file mode 100644 index 00000000..facd7fff --- /dev/null +++ b/docs/api/math/bounds/getmin.md @@ -0,0 +1,17 @@ +# Bounds::GetMin + +```cpp +Vector3 GetMin() const +``` + +获取包围盒的最小点。 + +**返回：** `Vector3` - center - extents + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 min = bounds.GetMin(); +``` diff --git a/docs/api/math/bounds/getvolume.md b/docs/api/math/bounds/getvolume.md new file mode 100644 index 00000000..32ad29fe --- /dev/null +++ b/docs/api/math/bounds/getvolume.md @@ -0,0 +1,17 @@ +# Bounds::GetVolume + +```cpp +float GetVolume() const +``` + +计算包围盒的体积。 + +**返回：** `float` - 体积 + +**复杂度：** O(1) + +**示例：** + +```cpp +float vol = bounds.GetVolume(); +``` diff --git a/docs/api/math/bounds/intersects.md b/docs/api/math/bounds/intersects.md new file mode 100644 index 00000000..2bbb642d --- /dev/null +++ b/docs/api/math/bounds/intersects.md @@ -0,0 +1,20 @@ +# Bounds::Intersects + +```cpp +bool Intersects(const Bounds& other) const +``` + +检测两个 Bounds 是否相交。 + +**参数：** +- `other` - 另一个 Bounds + +**返回：** `bool` - true 表示相交 + +**复杂度：** O(1) + +**示例：** + +```cpp +if (bounds.Intersects(other)) { /* collision */ } +``` diff --git a/docs/api/math/bounds/setminmax.md b/docs/api/math/bounds/setminmax.md new file mode 100644 index 00000000..f575367b --- /dev/null +++ b/docs/api/math/bounds/setminmax.md @@ -0,0 +1,19 @@ +# Bounds::SetMinMax + +```cpp +void SetMinMax(const Vector3& min, const Vector3& max) +``` + +从最小/最大点设置包围盒。 + +**参数：** +- `min` - 最小点 +- `max` - 最大点 + +**复杂度：** O(1) + +**示例：** + +```cpp +bounds.SetMinMax(minPoint, maxPoint); +``` diff --git a/docs/api/math/box/box.md b/docs/api/math/box/box.md new file mode 100644 index 00000000..a19d049c --- /dev/null +++ b/docs/api/math/box/box.md @@ -0,0 +1,37 @@ +# Box + +带变换的有向包围盒 (OBB) 结构体。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Box { + Vector3 center = Vector3::Zero(); + Vector3 extents = Vector3::Zero(); + Matrix4x4 transform = Matrix4x4::Identity(); +}; +``` + +## 构造函数 + +- `Box()` - 默认构造 +- `Box(const Vector3& center, const Vector3& extents)` - 从中心和半长构造 + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [GetMin()](getmin.md) | `Vector3` | 局部空间最小点 | +| [GetMax()](getmax.md) | `Vector3` | 局部空间最大点 | +| [Contains(point)](contains.md) | `bool` | 点是否在盒内 | +| [Intersects(Sphere)](intersects.md) | `bool` | 与球体相交 | +| [Intersects(Box)](intersects-box.md) | `bool` | 与另一个 OBB 相交 | +| [Intersects(Ray, t)](intersects-ray.md) | `bool` | 与射线相交 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/box/contains.md b/docs/api/math/box/contains.md new file mode 100644 index 00000000..3bac9af7 --- /dev/null +++ b/docs/api/math/box/contains.md @@ -0,0 +1,20 @@ +# Box::Contains + +```cpp +bool Contains(const Vector3& point) const +``` + +检测点是否在盒内。 + +**参数：** +- `point` - 要检测的点 + +**返回：** `bool` - true 表示点在盒内 + +**复杂度：** O(1) + +**示例：** + +```cpp +if (box.Contains(point)) { /* inside */ } +``` diff --git a/docs/api/math/box/getmax.md b/docs/api/math/box/getmax.md new file mode 100644 index 00000000..364e463f --- /dev/null +++ b/docs/api/math/box/getmax.md @@ -0,0 +1,17 @@ +# Box::GetMax + +```cpp +Vector3 GetMax() const +``` + +获取局部空间最大点。 + +**返回：** `Vector3` - (+extents) + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 max = box.GetMax(); +``` diff --git a/docs/api/math/box/getmin.md b/docs/api/math/box/getmin.md new file mode 100644 index 00000000..6b338b9c --- /dev/null +++ b/docs/api/math/box/getmin.md @@ -0,0 +1,17 @@ +# Box::GetMin + +```cpp +Vector3 GetMin() const +``` + +获取局部空间最小点。 + +**返回：** `Vector3` - (-extents) + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 min = box.GetMin(); +``` diff --git a/docs/api/math/box/intersects-box.md b/docs/api/math/box/intersects-box.md new file mode 100644 index 00000000..9fea4a61 --- /dev/null +++ b/docs/api/math/box/intersects-box.md @@ -0,0 +1,20 @@ +# Box::Intersects (Box) + +```cpp +bool Intersects(const Box& other) const +``` + +检测两个 OBB 是否相交（使用 SAT 算法）。 + +**参数：** +- `other` - 另一个 OBB + +**返回：** `bool` - true 表示相交 + +**复杂度：** O(1) + +**示例：** + +```cpp +if (box.Intersects(otherBox)) { /* collision */ } +``` diff --git a/docs/api/math/box/intersects-ray.md b/docs/api/math/box/intersects-ray.md new file mode 100644 index 00000000..7a4c05a7 --- /dev/null +++ b/docs/api/math/box/intersects-ray.md @@ -0,0 +1,24 @@ +# Box::Intersects (Ray) + +```cpp +bool Intersects(const Ray& ray, float& t) const +``` + +检测盒是否与射线相交。 + +**参数：** +- `ray` - 射线 +- `t` - 输出交点距离 + +**返回：** `bool` - true 表示相交 + +**复杂度：** O(1) + +**示例：** + +```cpp +float t; +if (box.Intersects(ray, t)) { + Vector3 hit = ray.GetPoint(t); +} +``` diff --git a/docs/api/math/box/intersects.md b/docs/api/math/box/intersects.md new file mode 100644 index 00000000..d536651c --- /dev/null +++ b/docs/api/math/box/intersects.md @@ -0,0 +1,20 @@ +# Box::Intersects + +```cpp +bool Intersects(const Sphere& sphere) const +``` + +检测盒是否与球体相交。 + +**参数：** +- `sphere` - 球体 + +**返回：** `bool` - true 表示相交 + +**复杂度：** O(1) + +**示例：** + +```cpp +if (box.Intersects(sphere)) { /* collision */ } +``` diff --git a/docs/api/math/color/black.md b/docs/api/math/color/black.md new file mode 100644 index 00000000..002486ca --- /dev/null +++ b/docs/api/math/color/black.md @@ -0,0 +1,11 @@ +# Color::Black + +```cpp +static Color Black() +``` + +返回黑色 (0, 0, 0, 1)。 + +**返回：** `Color` + +**示例：** `Color c = Color::Black();` diff --git a/docs/api/math/color/blue.md b/docs/api/math/color/blue.md new file mode 100644 index 00000000..382790f6 --- /dev/null +++ b/docs/api/math/color/blue.md @@ -0,0 +1,11 @@ +# Color::Blue + +```cpp +static Color Blue() +``` + +返回蓝色 (0, 0, 1, 1)。 + +**返回：** `Color` + +**示例：** `Color c = Color::Blue();` diff --git a/docs/api/math/color/clear.md b/docs/api/math/color/clear.md new file mode 100644 index 00000000..ff5fc2f7 --- /dev/null +++ b/docs/api/math/color/clear.md @@ -0,0 +1,11 @@ +# Color::Clear + +```cpp +static Color Clear() +``` + +返回透明黑色 (0, 0, 0, 0)。 + +**返回：** `Color` + +**示例：** `Color c = Color::Clear();` diff --git a/docs/api/math/color/color.md b/docs/api/math/color/color.md new file mode 100644 index 00000000..ff46d6c0 --- /dev/null +++ b/docs/api/math/color/color.md @@ -0,0 +1,59 @@ +# Color + +颜色结构体，支持 RGBA 浮点分量。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Color { + float r = 1.0f; + float g = 1.0f; + float b = 1.0f; + float a = 1.0f; +}; +``` + +## 静态工厂方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [White()](white.md) | `Color` | (1, 1, 1, 1) | +| [Black()](black.md) | `Color` | (0, 0, 0, 1) | +| [Red()](red.md) | `Color` | (1, 0, 0, 1) | +| [Green()](green.md) | `Color` | (0, 1, 0, 1) | +| [Blue()](blue.md) | `Color` | (0, 0, 1, 1) | +| [Yellow()](yellow.md) | `Color` | (1, 1, 0, 1) | +| [Cyan()](cyan.md) | `Color` | (0, 1, 1, 1) | +| [Magenta()](magenta.md) | `Color` | (1, 0, 1, 1) | +| [Clear()](clear.md) | `Color` | (0, 0, 0, 0)，透明黑 | + +## 静态方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Lerp(a, b, t)](lerp.md) | `Color` | 颜色线性插值 | + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [ToRGBA()](torgba.md) | `uint32_t` | 转换为 32-bit RGBA (0xRRGGBBAA) | +| [ToVector3()](tovector3.md) | `Vector3` | 转换为 RGB (丢弃 alpha) | +| [ToVector4()](tovector4.md) | `Vector4` | 转换为 RGBA | + +## 运算符 + +| 运算符 | 描述 | +|--------|------| +| `operator+(Color, Color)` | 颜色相加 | +| `operator-(Color, Color)` | 颜色相减 | +| `operator*(Color, float)` | 颜色乘以标量 | +| `operator/(Color, float)` | 颜色除以标量 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/color/cyan.md b/docs/api/math/color/cyan.md new file mode 100644 index 00000000..e8051908 --- /dev/null +++ b/docs/api/math/color/cyan.md @@ -0,0 +1,11 @@ +# Color::Cyan + +```cpp +static Color Cyan() +``` + +返回青色 (0, 1, 1, 1)。 + +**返回：** `Color` + +**示例：** `Color c = Color::Cyan();` diff --git a/docs/api/math/color/green.md b/docs/api/math/color/green.md new file mode 100644 index 00000000..009484b5 --- /dev/null +++ b/docs/api/math/color/green.md @@ -0,0 +1,11 @@ +# Color::Green + +```cpp +static Color Green() +``` + +返回绿色 (0, 1, 0, 1)。 + +**返回：** `Color` + +**示例：** `Color c = Color::Green();` diff --git a/docs/api/math/color/lerp.md b/docs/api/math/color/lerp.md new file mode 100644 index 00000000..82f35745 --- /dev/null +++ b/docs/api/math/color/lerp.md @@ -0,0 +1,22 @@ +# Color::Lerp + +```cpp +static Color Lerp(const Color& a, const Color& b, float t) +``` + +在两个颜色之间进行线性插值。 + +**参数：** +- `a` - 起始颜色 +- `b` - 结束颜色 +- `t` - 插值因子 (0-1) + +**返回：** `Color` - 插值结果 + +**复杂度：** O(1) + +**示例：** + +```cpp +Color lerped = Color::Lerp(Color::Red(), Color::Blue(), 0.5f); +``` diff --git a/docs/api/math/color/magenta.md b/docs/api/math/color/magenta.md new file mode 100644 index 00000000..68b10816 --- /dev/null +++ b/docs/api/math/color/magenta.md @@ -0,0 +1,11 @@ +# Color::Magenta + +```cpp +static Color Magenta() +``` + +返回品红色 (1, 0, 1, 1)。 + +**返回：** `Color` + +**示例：** `Color c = Color::Magenta();` diff --git a/docs/api/math/color/red.md b/docs/api/math/color/red.md new file mode 100644 index 00000000..ea81800b --- /dev/null +++ b/docs/api/math/color/red.md @@ -0,0 +1,11 @@ +# Color::Red + +```cpp +static Color Red() +``` + +返回红色 (1, 0, 0, 1)。 + +**返回：** `Color` + +**示例：** `Color c = Color::Red();` diff --git a/docs/api/math/color/torgba.md b/docs/api/math/color/torgba.md new file mode 100644 index 00000000..ce9f5efe --- /dev/null +++ b/docs/api/math/color/torgba.md @@ -0,0 +1,18 @@ +# Color::ToRGBA + +```cpp +uint32_t ToRGBA() const +``` + +将颜色转换为 32-bit RGBA 整数格式。 + +**返回：** `uint32_t` - RGBA 值 (0xRRGGBBAA) + +**复杂度：** O(1) + +**示例：** + +```cpp +Color c(1.0f, 0.0f, 0.0f, 1.0f); +uint32_t rgba = c.ToRGBA(); +``` diff --git a/docs/api/math/color/tovector3.md b/docs/api/math/color/tovector3.md new file mode 100644 index 00000000..ea9b3be1 --- /dev/null +++ b/docs/api/math/color/tovector3.md @@ -0,0 +1,17 @@ +# Color::ToVector3 + +```cpp +Vector3 ToVector3() const +``` + +将颜色转换为 Vector3（丢弃 alpha）。 + +**返回：** `Vector3` - RGB 值 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 rgb = Color::Red().ToVector3(); +``` diff --git a/docs/api/math/color/tovector4.md b/docs/api/math/color/tovector4.md new file mode 100644 index 00000000..d7bfdd3a --- /dev/null +++ b/docs/api/math/color/tovector4.md @@ -0,0 +1,17 @@ +# Color::ToVector4 + +```cpp +Vector4 ToVector4() const +``` + +将颜色转换为 Vector4。 + +**返回：** `Vector4` - RGBA 值 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector4 rgba = Color::Red().ToVector4(); +``` diff --git a/docs/api/math/color/white.md b/docs/api/math/color/white.md new file mode 100644 index 00000000..5247210f --- /dev/null +++ b/docs/api/math/color/white.md @@ -0,0 +1,11 @@ +# Color::White + +```cpp +static Color White() +``` + +返回白色 (1, 1, 1, 1)。 + +**返回：** `Color` + +**示例：** `Color c = Color::White();` diff --git a/docs/api/math/color/yellow.md b/docs/api/math/color/yellow.md new file mode 100644 index 00000000..46a349f0 --- /dev/null +++ b/docs/api/math/color/yellow.md @@ -0,0 +1,11 @@ +# Color::Yellow + +```cpp +static Color Yellow() +``` + +返回黄色 (1, 1, 0, 1)。 + +**返回：** `Color` + +**示例：** `Color c = Color::Yellow();` diff --git a/docs/api/math/frustum/contains-bounds.md b/docs/api/math/frustum/contains-bounds.md new file mode 100644 index 00000000..8a0da23e --- /dev/null +++ b/docs/api/math/frustum/contains-bounds.md @@ -0,0 +1,25 @@ +# Frustum::Contains (bounds) + +```cpp +bool Contains(const Bounds& bounds) const +``` + +检测轴对齐包围盒是否完全在视锥体内。 + +**参数：** +- `bounds` - 要检测的轴对齐包围盒 + +**返回：** `bool` - Bounds 完全在视锥内返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +Frustum frustum = camera.CalculateFrustum(); +Bounds objectBounds = object.GetWorldBounds(); +if (frustum.Contains(objectBounds)) { + // 包围盒完全在视锥内，需要渲染 + Render(object); +} +``` diff --git a/docs/api/math/frustum/contains-point.md b/docs/api/math/frustum/contains-point.md new file mode 100644 index 00000000..d72ee37c --- /dev/null +++ b/docs/api/math/frustum/contains-point.md @@ -0,0 +1,24 @@ +# Frustum::Contains (point) + +```cpp +bool Contains(const Vector3& point) const +``` + +检测点是否在视锥体内。 + +**参数：** +- `point` - 要检测的世界空间点 + +**返回：** `bool` - 点在视锥内返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +Frustum frustum = camera.CalculateFrustum(); +Vector3 point = object.GetPosition(); +if (frustum.Contains(point)) { + // 点在视锥内 +} +``` diff --git a/docs/api/math/frustum/contains-sphere.md b/docs/api/math/frustum/contains-sphere.md new file mode 100644 index 00000000..569522bc --- /dev/null +++ b/docs/api/math/frustum/contains-sphere.md @@ -0,0 +1,24 @@ +# Frustum::Contains (sphere) + +```cpp +bool Contains(const Sphere& sphere) const +``` + +检测球体是否完全在视锥体内。 + +**参数：** +- `sphere` - 要检测的球体 + +**返回：** `bool` - 球体完全在视锥内返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +Frustum frustum = camera.CalculateFrustum(); +Sphere collider = object.GetBoundingSphere(); +if (frustum.Contains(collider)) { + // 球体完全在视锥内 +} +``` diff --git a/docs/api/math/frustum/frustum.md b/docs/api/math/frustum/frustum.md new file mode 100644 index 00000000..cd24d4b0 --- /dev/null +++ b/docs/api/math/frustum/frustum.md @@ -0,0 +1,45 @@ +# Frustum + +视锥体，用于视锥剔除。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 类定义 + +```cpp +class Frustum { +public: + Plane planes[6]; + + enum class PlaneIndex { + Left = 0, + Right = 1, + Bottom = 2, + Top = 3, + Near = 4, + Far = 5 + }; + + bool Contains(const Vector3& point) const; + bool Contains(const Sphere& sphere) const; + bool Contains(const Bounds& bounds) const; + bool Intersects(const Bounds& bounds) const; + bool Intersects(const Sphere& sphere) const; +}; +``` + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Contains(point)](contains-point.md) | `bool` | 点是否在视锥内 | +| [Contains(sphere)](contains-sphere.md) | `bool` | 球体是否完全在视锥内 | +| [Contains(bounds)](contains-bounds.md) | `bool` | Bounds 是否完全在视锥内 | +| [Intersects(bounds)](intersects-bounds.md) | `bool` | Bounds 是否与视锥相交 | +| [Intersects(sphere)](intersects-sphere.md) | `bool` | 球体是否与视锥相交 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/frustum/intersects-bounds.md b/docs/api/math/frustum/intersects-bounds.md new file mode 100644 index 00000000..d4be8707 --- /dev/null +++ b/docs/api/math/frustum/intersects-bounds.md @@ -0,0 +1,26 @@ +# Frustum::Intersects (bounds) + +```cpp +bool Intersects(const Bounds& bounds) const +``` + +检测轴对齐包围盒是否与视锥体相交。 + +**参数：** +- `bounds` - 要检测的轴对齐包围盒 + +**返回：** `bool` - 与视锥相交返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +Frustum frustum = camera.CalculateFrustum(); +for (const auto& object : sceneObjects) { + if (frustum.Intersects(object.bounds)) { + // 物体与视锥相交，需要渲染 + Render(object); + } +} +``` diff --git a/docs/api/math/frustum/intersects-sphere.md b/docs/api/math/frustum/intersects-sphere.md new file mode 100644 index 00000000..363b2ecb --- /dev/null +++ b/docs/api/math/frustum/intersects-sphere.md @@ -0,0 +1,25 @@ +# Frustum::Intersects (sphere) + +```cpp +bool Intersects(const Sphere& sphere) const +``` + +检测球体是否与视锥体相交。 + +**参数：** +- `sphere` - 要检测的球体 + +**返回：** `bool` - 与视锥相交返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +Frustum frustum = camera.CalculateFrustum(); +Sphere collider = object.GetBoundingSphere(); +if (frustum.Intersects(collider)) { + // 球体与视锥相交 + Render(object); +} +``` diff --git a/docs/api/math/h/deg-to-rad.md b/docs/api/math/h/deg-to-rad.md new file mode 100644 index 00000000..9e18d430 --- /dev/null +++ b/docs/api/math/h/deg-to-rad.md @@ -0,0 +1,20 @@ +# Math::DEG_TO_RAD + +```cpp +constexpr float DEG_TO_RAD = Math::PI / 180.0f; +``` + +`DEG_TO_RAD` 是角度转弧度的转换系数。1 度等于 `PI / 180` 弧度，约等于 0.01745329251994329577。使用该常量将角度值乘以 `DEG_TO_RAD` 即可得到对应的弧度值。 + +**示例：** + +```cpp +#include + +float angleDegrees = 90.0f; +float angleRadians = angleDegrees * Math::DEG_TO_RAD; +``` + +## 相关文档 + +- [Math 总览](h.md) - 返回 Math 概览 diff --git a/docs/api/math/h/degrees.md b/docs/api/math/h/degrees.md new file mode 100644 index 00000000..2d2c2e6c --- /dev/null +++ b/docs/api/math/h/degrees.md @@ -0,0 +1,20 @@ +# Math::Degrees + +```cpp +float Degrees(float radians); +``` + +`Degrees` 函数将弧度值转换为角度值。转换公式为：`角度 = 弧度 * (180 / PI)`。该函数是 `Radians` 函数的逆函数，常用于将三角函数的返回值或物理引擎中的弧度值转换为人机界面友好的角度值。 + +**示例：** + +```cpp +#include + +float radians = Math::HALF_PI; +float degrees = Math::Degrees(radians); +``` + +## 相关文档 + +- [Math 总览](h.md) - 返回 Math 概览 diff --git a/docs/api/math/h/epsilon.md b/docs/api/math/h/epsilon.md new file mode 100644 index 00000000..0720ef65 --- /dev/null +++ b/docs/api/math/h/epsilon.md @@ -0,0 +1,23 @@ +# Math::EPSILON + +```cpp +constexpr float EPSILON = 1e-6f; +``` + +`EPSILON` 是一个非常小的浮点数常量，值为 0.000001。该常量主要用于浮点数比较，由于浮点数精度问题，直接使用 `==` 比较浮点数可能产生错误结果，此时应使用 `EPSILON` 进行容差比较。例如判断两个浮点数是否相等，可以检查它们的差的绝对值是否小于 `EPSILON`。 + +**示例：** + +```cpp +#include + +float a = 0.1f + 0.2f; +float b = 0.3f; +if (Math::Abs(a - b) < Math::EPSILON) { + // a 和 b 可以视为相等 +} +``` + +## 相关文档 + +- [Math 总览](h.md) - 返回 Math 概览 diff --git a/docs/api/math/h/float-max.md b/docs/api/math/h/float-max.md new file mode 100644 index 00000000..510b187f --- /dev/null +++ b/docs/api/math/h/float-max.md @@ -0,0 +1,19 @@ +# Math::FLOAT_MAX + +```cpp +constexpr float FLOAT_MAX = 3.402823466e+38f; +``` + +`FLOAT_MAX` 是 IEEE 754 单精度浮点数能表示的最大正有限值，约为 3.402823466e+38。该常量常用于初始化变量为最大值、在搜索算法中作为上界、或在需要表示"无穷大"但又不想引入 `INFINITY` 的场景中使用。 + +**示例：** + +```cpp +#include + +float maxDistance = Math::FLOAT_MAX; +``` + +## 相关文档 + +- [Math 总览](h.md) - 返回 Math 概览 diff --git a/docs/api/math/h/h.md b/docs/api/math/h/h.md new file mode 100644 index 00000000..08f84b44 --- /dev/null +++ b/docs/api/math/h/h.md @@ -0,0 +1,54 @@ +# Math + +**命名空间**: `XCEngine::Math` + +**类型**: `header` + +**描述**: 数学库常量和辅助函数头文件。 + +## 概述 + +`Math.h` 提供了图形引擎常用的数学常量和辅助函数，包括圆周率、角度转换、浮点精度等基础常量，以及角度弧度转换等常用函数。 + +## 常量 + +| 常量 | 值 | 描述 | +|------|-----|------| +| [PI](pi.md) | 3.14159265358979323846f | 圆周率 | +| [TWO_PI](two-pi.md) | 6.28318530717958647692f | 2π | +| [HALF_PI](half-pi.md) | 1.57079632679489661923f | π/2 | +| [DEG_TO_RAD](deg-to-rad.md) | PI / 180.0f | 度到弧度 | +| [RAD_TO_DEG](rad-to-deg.md) | 180.0f / PI | 弧度到度 | +| [EPSILON](epsilon.md) | 1e-6f | 浮点精度 | +| [FLOAT_MAX](float-max.md) | 3.402823466e+38f | 浮点最大值 | + +## 辅助函数 + +| 函数 | 描述 | +|------|------| +| [Radians](radians.md) | 度转弧度 | +| [Degrees](degrees.md) | 弧度转度 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Math; + +// 使用常量 +float angle = 90.0f * DEG_TO_RAD; // 90度转弧度 + +// 使用函数 +float rad = Radians(180.0f); // 180度 -> π 弧度 +float deg = Degrees(Math::PI); // π 弧度 -> 180度 + +// 比较浮点数 +if (fabsf(a - b) < EPSILON) { + // 认为 a 和 b 相等 +} +``` + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/h/half-pi.md b/docs/api/math/h/half-pi.md new file mode 100644 index 00000000..2a6f8cdf --- /dev/null +++ b/docs/api/math/h/half-pi.md @@ -0,0 +1,19 @@ +# Math::HALF_PI + +```cpp +constexpr float HALF_PI = 1.57079632679489661923f; +``` + +`HALF_PI` 是圆周率除以 2，即 90 度对应的弧度值，约为 1.57079632679489661923。该常量常用于角度与弧度的转换、四分之一圆周计算等场景。 + +**示例：** + +```cpp +#include + +float ninetyDegreesRadians = Math::HALF_PI; +``` + +## 相关文档 + +- [Math 总览](h.md) - 返回 Math 概览 diff --git a/docs/api/math/h/pi.md b/docs/api/math/h/pi.md new file mode 100644 index 00000000..a40653ab --- /dev/null +++ b/docs/api/math/h/pi.md @@ -0,0 +1,22 @@ +# Math::PI + +```cpp +constexpr float PI = 3.14159265358979323846f; +``` + +圆周率常量，精确到 float 能表示的最高精度。 + +**用途：** 用于三角函数计算、弧度角度转换、圆形/弧度相关计算。 + +**示例：** + +```cpp +#include + +float circumference = 2.0f * Math::PI * radius; +float area = Math::PI * radius * radius; +``` + +## 相关文档 + +- [Math 总览](h.md) - 返回 Math 概览 diff --git a/docs/api/math/h/rad-to-deg.md b/docs/api/math/h/rad-to-deg.md new file mode 100644 index 00000000..ab50c13c --- /dev/null +++ b/docs/api/math/h/rad-to-deg.md @@ -0,0 +1,20 @@ +# Math::RAD_TO_DEG + +```cpp +constexpr float RAD_TO_DEG = 180.0f / Math::PI; +``` + +`RAD_TO_DEG` 是弧度转角度的转换系数。1 弧度等于 `180 / PI` 度，约等于 57.29577951308232087685。使用该常量将弧度值乘以 `RAD_TO_DEG` 即可得到对应的角度值。 + +**示例：** + +```cpp +#include + +float radians = Math::HALF_PI; +float degrees = radians * Math::RAD_TO_DEG; +``` + +## 相关文档 + +- [Math 总览](h.md) - 返回 Math 概览 diff --git a/docs/api/math/h/radians.md b/docs/api/math/h/radians.md new file mode 100644 index 00000000..a1c70771 --- /dev/null +++ b/docs/api/math/h/radians.md @@ -0,0 +1,20 @@ +# Math::Radians + +```cpp +float Radians(float degrees); +``` + +`Radians` 函数将角度值转换为弧度值。转换公式为：`弧度 = 角度 * (PI / 180)`。该函数是 `Degrees` 函数的逆函数，常用于将 UI 输入的角度值或游戏中的角度值转换为三角函数所需的弧度值。 + +**示例：** + +```cpp +#include + +float degrees = 90.0f; +float radians = Math::Radians(degrees); +``` + +## 相关文档 + +- [Math 总览](h.md) - 返回 Math 概览 diff --git a/docs/api/math/h/two-pi.md b/docs/api/math/h/two-pi.md new file mode 100644 index 00000000..1efd8bc2 --- /dev/null +++ b/docs/api/math/h/two-pi.md @@ -0,0 +1,19 @@ +# Math::TWO_PI + +```cpp +constexpr float TWO_PI = 6.28318530717958647692f; +``` + +`TWO_PI` 是圆周率的两倍，即完整的圆周长对应的弧度值，约为 6.28318530717958647692。该常量常用于需要完整圆周旋转的场景，例如角度归一化、三角函数周期计算、圆形运动等。 + +**示例：** + +```cpp +#include + +float fullCircleRadians = Math::TWO_PI; +``` + +## 相关文档 + +- [Math 总览](h.md) - 返回 Math 概览 diff --git a/docs/api/math/math-aabb.md b/docs/api/math/math-aabb.md deleted file mode 100644 index b93c00ec..00000000 --- a/docs/api/math/math-aabb.md +++ /dev/null @@ -1,67 +0,0 @@ -# AABB / OBB - -轴对齐包围盒 (AABB) 和有向包围盒 (OBB)。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## AABB - 轴对齐包围盒 - -`AABB` 在 Math 库中通过 `Bounds` 类型实现，参见 [math-bounds.md](math-bounds.md)。 - -## OBB - 有向包围盒 - -OBB 是可以任意方向旋转的包围盒。 - -```cpp -struct OBB { - Vector3 center; - Vector3 extents; // 半长 - Matrix4 transform; // 变换矩阵 -}; -``` - -### 构造函数 - -- `OBB()` - 默认构造 -- `OBB(const Vector3& center, const Vector3& extents)` - 从中心和半长构造 - -### 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `GetAxis(index)` | `Vector3` | 获取局部轴 (0=X, 1=Y, 2=Z) | -| `GetMin()` | `Vector3` | 局部空间最小点 | -| `GetMax()` | `Vector3` | 局部空间最大点 | -| `Contains(point)` | `bool` | 点是否在 OBB 内 | -| `Intersects(OBB)` | `bool` | 与另一个 OBB 相交 (SAT) | -| `Intersects(Sphere)` | `bool` | 与球体相交 | - -## 备注 - -- AABB 与轴对齐，检测简单但可能不够紧凑 -- OBB 可旋转，检测使用分离轴定理 (SAT) -- OBB 适合动态旋转的物体 - -## 使用示例 - -```cpp -// OBB -OBB obb; -obb.center = Vector3(0.0f); -obb.extents = Vector3(1.0f); -obb.transform = Matrix4::TRS(pos, rot, scale); - -Vector3 localAxis = obb.GetAxis(0); - -if (obb.Contains(point)) { ... } -if (obb.Intersects(otherOBB)) { ... } -if (obb.Intersects(sphere)) { ... } -``` diff --git a/docs/api/math/math-bounds.md b/docs/api/math/math-bounds.md deleted file mode 100644 index 530ab804..00000000 --- a/docs/api/math/math-bounds.md +++ /dev/null @@ -1,61 +0,0 @@ -# Bounds - -轴对齐包围盒 (AABB)，中心-范围表示。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 结构体定义 - -```cpp -struct Bounds { - Vector3 center = Vector3::Zero(); - Vector3 extents = Vector3::Zero(); // 半长，不是最大点 -}; -``` - -## 构造函数 - -- `Bounds()` - 默认构造 -- `Bounds(const Vector3& center, const Vector3& size)` - 从中心和大小构造 - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `GetMin()` | `Vector3` | 最小点: `center - extents` | -| `GetMax()` | `Vector3` | 最大点: `center + extents` | -| `SetMinMax(min, max)` | `void` | 从最小/最大点设置 | -| `Contains(point)` | `bool` | 点是否在盒内 | -| `Intersects(other)` | `bool` | 与另一个 Bounds 相交 | -| `Encapsulate(point)` | `void` | 扩展包含点 | -| `Encapsulate(bounds)` | `void` | 扩展包含另一个 Bounds | -| `Expand(amount)` | `void` | 各方向扩展 amount | -| `Expand(amount)` | `void` | 按 Vector3 扩展 | -| `GetClosestPoint(point)` | `Vector3` | 盒上最接近给定点的点 | -| `GetVolume()` | `float` | 体积 | - -## 使用示例 - -```cpp -Bounds bounds(center, extents); - -// 包含点 -if (bounds.Contains(point)) { ... } - -// 扩展包围盒 -bounds.Encapsulate(newPoint); - -// 相交检测 -if (bounds.Intersects(other)) { ... } - -// 设置 -bounds.SetMinMax(minPoint, maxPoint); -``` diff --git a/docs/api/math/math-box.md b/docs/api/math/math-box.md deleted file mode 100644 index 8eb7748c..00000000 --- a/docs/api/math/math-box.md +++ /dev/null @@ -1,63 +0,0 @@ -# Box - -带变换的有向包围盒 (OBB) 结构体。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 结构体定义 - -```cpp -struct Box { - Vector3 center = Vector3::Zero(); - Vector3 extents = Vector3::Zero(); // 半长 - Matrix4x4 transform = Matrix4x4::Identity(); -}; -``` - -OBB 由中心点、半长向量和变换矩阵定义。 - -## 构造函数 - -- `Box()` - 默认构造 -- `Box(const Vector3& center, const Vector3& extents)` - 从中心和半长构造 - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `GetMin()` | `Vector3` | 局部空间最小点 (-extents) | -| `GetMax()` | `Vector3` | 局部空间最大点 (+extents) | -| `Contains(point)` | `bool` | 点是否在盒内（变换到局部空间检测） | -| `Intersects(Sphere)` | `bool` | 与球体相交 | -| `Intersects(Box)` | `bool` | 与另一个 OBB 相交（SAT 算法） | -| `Intersects(Ray, t)` | `bool` | 与射线相交，输出距离 t | - -## 使用示例 - -```cpp -Box box(Vector3(0.0f), Vector3(1.0f)); // 2x2x2 盒子 -box.transform = Matrix4::TRS(position, rotation, scale); - -// 点检测 -if (box.Contains(testPoint)) { ... } - -// 球体相交 -if (box.Intersects(sphere)) { ... } - -// OBB 相交 -if (box.Intersects(otherBox)) { ... } - -// 射线相交 -float t; -if (box.Intersects(ray, t)) { - Vector3 hit = ray.GetPoint(t); -} -``` diff --git a/docs/api/math/math-color.md b/docs/api/math/math-color.md deleted file mode 100644 index 983513a3..00000000 --- a/docs/api/math/math-color.md +++ /dev/null @@ -1,72 +0,0 @@ -# Color - -颜色结构体，支持 RGBA 浮点分量。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 结构体定义 - -```cpp -struct Color { - float r = 1.0f; - float g = 1.0f; - float b = 1.0f; - float a = 1.0f; -}; -``` - -分量范围: 0.0f ~ 1.0f - -## 静态工厂方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `White()` | `Color` | (1, 1, 1, 1) | -| `Black()` | `Color` | (0, 0, 0, 1) | -| `Red()` | `Color` | (1, 0, 0, 1) | -| `Green()` | `Color` | (0, 1, 0, 1) | -| `Blue()` | `Color` | (0, 0, 1, 1) | -| `Yellow()` | `Color` | (1, 1, 0, 1) | -| `Cyan()` | `Color` | (0, 1, 1, 1) | -| `Magenta()` | `Color` | (1, 0, 1, 1) | -| `Clear()` | `Color` | (0, 0, 0, 0)，透明黑 | - -## 静态方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Lerp(a, b, t)` | `Color` | 颜色线性插值 | - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `ToRGBA()` | `uint32_t` | 转换为 32-bit RGBA (0xAABBGGRR) | -| `ToVector3()` | `Vector3` | 转换为 RGB (丢弃 alpha) | -| `ToVector4()` | `Vector4` | 转换为 RGBA | - -## 运算符 - -| 运算符 | 描述 | -|--------|------| -| `operator+(Color, Color)` | 颜色相加 | -| `operator-(Color, Color)` | 颜色相减 | -| `operator*(Color, float)` | 颜色乘以标量 | -| `operator/(Color, float)` | 颜色除以标量 | - -## 使用示例 - -```cpp -Color red = Color::Red(); -Color lerped = Color::Lerp(red, Color::Blue(), 0.5f); -uint32_t rgba = lerped.ToRGBA(); -Vector4 v4 = lerped.ToVector4(); -``` diff --git a/docs/api/math/math-frustum.md b/docs/api/math/math-frustum.md deleted file mode 100644 index e261e57e..00000000 --- a/docs/api/math/math-frustum.md +++ /dev/null @@ -1,61 +0,0 @@ -# Frustum - -视锥体，用于视锥剔除。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 结构体定义 - -```cpp -class Frustum { -public: - Plane planes[6]; // 6 个裁剪平面 - - enum class PlaneIndex { - Left = 0, - Right = 1, - Bottom = 2, - Top = 3, - Near = 4, - Far = 5 - }; -}; -``` - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Contains(point)` | `bool` | 点是否在视锥内 | -| `Contains(Sphere)` | `bool` | 球体是否在视锥内 | -| `Contains(Bounds)` | `bool` | Bounds 是否在视锥内 | -| `Intersects(Bounds)` | `bool` | Bounds 是否与视锥相交 | -| `Intersects(Sphere)` | `bool` | 球体是否与视锥相交 | - -## 使用示例 - -```cpp -Frustum frustum; -// 需要从相机矩阵构建视锥平面 - -// 视锥剔除 -for (const auto& object : objects) { - if (frustum.Contains(object.bounds)) { - // 物体在视锥内，渲染 - Render(object); - } -} - -// 或使用相交检测 -if (frustum.Intersects(bounds)) { - Render(object); -} -``` diff --git a/docs/api/math/math-h.md b/docs/api/math/math-h.md deleted file mode 100644 index 2a7a232b..00000000 --- a/docs/api/math/math-h.md +++ /dev/null @@ -1,51 +0,0 @@ -# Math - 数学常量 - -数学库全局常量和辅助函数。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 数学常量 - -| 常量 | 值 | 描述 | -|------|-----|------| -| `PI` | 3.14159265358979323846f | 圆周率 | -| `TWO_PI` | 6.28318530717958647692f | 2π | -| `HALF_PI` | 1.57079632679489661923f | π/2 | -| `DEG_TO_RAD` | PI / 180.0f | 度转弧度 | -| `RAD_TO_DEG` | 180.0f / PI | 弧度转度 | -| `EPSILON` | 1e-6f | 浮点比较容差 | -| `FLOAT_MAX` | 3.402823466e+38f | float 最大值 | - -## 辅助函数 - -| 函数 | 返回值 | 描述 | -|------|--------|------| -| `Radians(degrees)` | `float` | 度转弧度 | -| `Degrees(radians)` | `float` | 弧度转度 | - -## 使用示例 - -```cpp -using namespace XCEngine::Math; - -float radians = 90.0f * DEG_TO_RAD; // 90度 -> 弧度 -float degrees = PI * RAD_TO_DEG; // 弧度 -> 度 -float rad2 = Radians(45.0f); // 使用函数 - -// 浮点比较 -if (std::abs(a - b) < EPSILON) { - // a 和 b 相等 -} - -// 三角函数（来自 ） -float sinVal = std::sin(angle); -float cosVal = std::cos(angle); -``` diff --git a/docs/api/math/math-matrix3.md b/docs/api/math/math-matrix3.md deleted file mode 100644 index 669e5a3d..00000000 --- a/docs/api/math/math-matrix3.md +++ /dev/null @@ -1,69 +0,0 @@ -# Matrix3 / Matrix3x3 - -3x3 矩阵结构体，用于表示 3D 旋转和缩放变换。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 类型别名 - -```cpp -using Matrix3 = Matrix3x3; -``` - -## 存储方式 - -行优先存储 (row-major)： -``` -m[row][col] -m[0][0] m[0][1] m[0][2] -m[1][0] m[1][1] m[1][2] -m[2][0] m[2][1] m[2][2] -``` - -## 构造函数 - -- 默认构造函数初始化为零矩阵 - -## 静态工厂方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Identity()` | `Matrix3` | 单位矩阵 | -| `Zero()` | `Matrix3` | 零矩阵 | -| `RotationX(float radians)` | `Matrix3` | X 轴旋转矩阵 | -| `RotationY(float radians)` | `Matrix3` | Y 轴旋转矩阵 | -| `RotationZ(float radians)` | `Matrix3` | Z 轴旋转矩阵 | -| `Scale(const Vector3& scale)` | `Matrix3` | 缩放矩阵 | - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Transpose()` | `Matrix3` | 转置矩阵 | -| `Inverse()` | `Matrix3` | 逆矩阵 | -| `Determinant()` | `float` | 行列式 | - -## 运算符 - -| 运算符 | 描述 | -|--------|------| -| `operator*(Matrix3, Matrix3)` | 矩阵乘法 | -| `operator*(Matrix3, Vector3)` | 矩阵-向量乘法 | - -## 使用示例 - -```cpp -Matrix3 rotX = Matrix3::RotationX(Math::HALF_PI); -Matrix3 rotY = Matrix3::RotationY(0.0f); -Matrix3 scale = Matrix3::Scale(Vector3(2.0f, 2.0f, 2.0f)); -Matrix3 combined = rotX * scale; -Vector3 transformed = combined * Vector3(1.0f, 0.0f, 0.0f); -``` diff --git a/docs/api/math/math-matrix4.md b/docs/api/math/math-matrix4.md deleted file mode 100644 index 750e32e2..00000000 --- a/docs/api/math/math-matrix4.md +++ /dev/null @@ -1,101 +0,0 @@ -# Matrix4 / Matrix4x4 - -4x4 矩阵结构体，用于表示完整的 3D 变换（平移、旋转、缩放）、视图和投影变换。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 类型别名 - -```cpp -using Matrix4 = Matrix4x4; -``` - -## 存储方式 - -行优先存储 (row-major)： -``` -m[0][0] m[0][1] m[0][2] m[0][3] -m[1][0] m[1][1] m[1][2] m[1][3] -m[2][0] m[2][1] m[2][2] m[2][3] -m[3][0] m[3][1] m[3][2] m[3][3] -``` - -## 静态工厂方法 - -### 基础变换 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Identity()` | `Matrix4` | 单位矩阵 | -| `Zero()` | `Matrix4` | 零矩阵 | -| `Translation(const Vector3& v)` | `Matrix4` | 平移矩阵 | -| `Scale(const Vector3& v)` | `Matrix4` | 缩放矩阵 | -| `Rotation(const Quaternion& q)` | `Matrix4` | 旋转矩阵（四元数） | -| `TRS(translation, rotation, scale)` | `Matrix4` | 完整变换 | - -### 旋转 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `RotationX(float radians)` | `Matrix4` | X 轴旋转 | -| `RotationY(float radians)` | `Matrix4` | Y 轴旋转 | -| `RotationZ(float radians)` | `Matrix4` | Z 轴旋转 | - -### 相机变换 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `LookAt(eye, target, up)` | `Matrix4` | 视图矩阵 | -| `Perspective(fov, aspect, near, far)` | `Matrix4` | 透视投影 | -| `Orthographic(left, right, bottom, top, near, far)` | `Matrix4` | 正交投影 | - -## 实例方法 - -### 乘法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `operator*(Matrix4, Matrix4)` | `Matrix4` | 矩阵乘法 | -| `operator*(Matrix4, Vector4)` | `Vector4` | 矩阵-向量乘法 | -| `MultiplyPoint(v)` | `Vector3` | 点变换（带平移） | -| `MultiplyVector(v)` | `Vector3` | 方向变换（不带平移） | - -### 分解 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Transpose()` | `Matrix4` | 转置矩阵 | -| `Inverse()` | `Matrix4` | 逆矩阵 | -| `Determinant()` | `float` | 行列式 | -| `GetTranslation()` | `Vector3` | 获取平移分量 | -| `GetRotation()` | `Quaternion` | 获取旋转分量 | -| `GetScale()` | `Vector3` | 获取缩放分量 | -| `Decompose(translation, rotation, scale)` | `void` | 分解所有分量 | - -## 使用示例 - -```cpp -// MVP 矩阵 -Matrix4 model = Matrix4::TRS(position, rotation, scale); -Matrix4 view = Matrix4::LookAt(cameraPos, target, Vector3::Up()); -Matrix4 proj = Matrix4::Perspective(45.0f * DEG_TO_RAD, aspect, 0.1f, 100.0f); -Matrix4 mvp = proj * view * model; - -// 变换点 -Vector3 worldPos = model.MultiplyPoint(localPos); -Vector3 worldDir = model.MultiplyVector(localDir); - -// 分解矩阵 -Vector3 translation; -Quaternion rotation; -Vector3 scale; -model.Decompose(translation, rotation, scale); -``` diff --git a/docs/api/math/math-plane.md b/docs/api/math/math-plane.md deleted file mode 100644 index da1a90b6..00000000 --- a/docs/api/math/math-plane.md +++ /dev/null @@ -1,66 +0,0 @@ -# Plane - -3D 平面结构体，由法线和距离表示。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 结构体定义 - -```cpp -struct Plane { - Vector3 normal = Vector3::Up(); // 单位法线 - float distance = 0.0f; // 原点到平面的有符号距离 -}; -``` - -平面方程: `dot(normal, X) + distance = 0` - -## 构造函数 - -- `Plane()` - 默认构造 (y=0 平面) -- `Plane(const Vector3& normal, float distance)` - 从法线和距离构造 - -## 静态工厂方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `FromPoints(a, b, c)` | `Plane` | 从三个不共线点创建 | - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `GetDistanceToPoint(point)` | `float` | 点到平面的有符号距离 | -| `GetClosestPoint(point)` | `Vector3` | 平面上最接近给定点的点 | -| `GetSide(point)` | `bool` | 点在平面的哪一侧 (true=正面) | -| `Intersects(Sphere)` | `bool` | 与球体相交 | - -## 使用示例 - -```cpp -// 创建平面 -Plane floor; -floor.normal = Vector3::Up(); -floor.distance = 0.0f; // y=0 平面 - -// 或者从三点创建 -Plane plane = Plane::FromPoints(p0, p1, p2); - -// 检测点在哪侧 -bool above = floor.GetSide(point); -float signedDist = floor.GetDistanceToPoint(point); - -// 投影点到平面 -Vector3 closest = floor.GetClosestPoint(point); - -// 平面相交检测 -if (plane.Intersects(sphere)) { ... } -``` diff --git a/docs/api/math/math-quaternion.md b/docs/api/math/math-quaternion.md deleted file mode 100644 index 182c5a1a..00000000 --- a/docs/api/math/math-quaternion.md +++ /dev/null @@ -1,86 +0,0 @@ -# Quaternion - -四元数结构体，用于表示 3D 旋转，避免欧拉角的万向锁问题。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 结构体定义 - -```cpp -struct Quaternion { - float x = 0.0f; - float y = 0.0f; - float z = 0.0f; - float w = 1.0f; // w 是标量分量 -}; -``` - -四元数格式: `(x, y, z, w)` = `(vec, w)` - -## 静态工厂方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Identity()` | `Quaternion` | 返回 (0, 0, 0, 1)，恒等旋转 | -| `FromAxisAngle(axis, radians)` | `Quaternion` | 从轴角创建 | -| `FromEulerAngles(pitch, yaw, roll)` | `Quaternion` | 从欧拉角创建（弧度） | -| `FromEulerAngles(euler)` | `Quaternion` | 从 Vector3 欧拉角创建 | -| `FromRotationMatrix(matrix)` | `Quaternion` | 从旋转矩阵创建 | -| `Slerp(a, b, t)` | `Quaternion` | 球面线性插值 | -| `LookRotation(forward, up)` | `Quaternion` | 看向方向 | - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `ToEulerAngles()` | `Vector3` | 转换为欧拉角（弧度） | -| `ToMatrix4x4()` | `Matrix4` | 转换为 4x4 旋转矩阵 | -| `Inverse()` | `Quaternion` | 共轭/逆四元数 | -| `Dot(other)` | `float` | 点积 | -| `Magnitude()` | `float` | 模长 | -| `Normalized()` | `Quaternion` | 归一化 | -| `Normalize(q)` | `Quaternion` | 归一化（静态） | - -## 运算符 - -| 运算符 | 描述 | -|--------|------| -| `operator*(Quaternion, Quaternion)` | 组合旋转 | - -## 与 Vector3 的乘法 - -```cpp -Vector3 operator*(const Quaternion& q, const Vector3& v); -``` -用四元数旋转向量。 - -## 使用示例 - -```cpp -// 创建旋转 -Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f); - -// 组合旋转 -Quaternion combined = rot1 * rot2; - -// 球面插值 -Quaternion lerped = Quaternion::Slerp(rot1, rot2, 0.5f); - -// 旋转向量 -Vector3 rotated = rot * Vector3::Forward(); - -// 转换 -Vector3 euler = rot.ToEulerAngles(); -Matrix4 mat = rot.ToMatrix4x4(); - -// 看向目标 -Quaternion lookAt = Quaternion::LookRotation(target - position); -``` diff --git a/docs/api/math/math-ray.md b/docs/api/math/math-ray.md deleted file mode 100644 index 93f42f47..00000000 --- a/docs/api/math/math-ray.md +++ /dev/null @@ -1,58 +0,0 @@ -# Ray - -3D 射线结构体，用于光线投射和拾取。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 结构体定义 - -```cpp -struct Ray { - Vector3 origin; // 射线起点 - Vector3 direction; // 归一化方向 -}; -``` - -## 构造函数 - -- `Ray()` - 默认构造 -- `Ray(const Vector3& origin, const Vector3& direction)` - 从点和方向构造 - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `GetPoint(t)` | `Vector3` | 获取射线上 t 距离处的点: `origin + direction * t` | - -## 相交检测 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Intersects(Sphere, t)` | `bool` | 与球体相交，输出距离 t | -| `Intersects(Box, t)` | `bool` | 与 AABB 相交，输出距离 t | -| `Intersects(Plane, t)` | `bool` | 与平面相交，输出距离 t | - -## 使用示例 - -```cpp -Ray ray(cameraPosition, rayDirection); - -// 与球体相交 -float t; -if (ray.Intersects(sphere, t)) { - Vector3 hitPoint = ray.GetPoint(t); -} - -// 与平面相交 -if (ray.Intersects(plane, t)) { - Vector3 hitPoint = ray.GetPoint(t); -} -``` diff --git a/docs/api/math/math-rect.md b/docs/api/math/math-rect.md deleted file mode 100644 index 38ca88e2..00000000 --- a/docs/api/math/math-rect.md +++ /dev/null @@ -1,137 +0,0 @@ -# Rect / RectInt / Viewport - -2D 矩形和视口结构体。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - ---- - -## Rect - 浮点矩形 - -```cpp -struct Rect { - float x = 0.0f; // 左边界 - float y = 0.0f; // 上边界 - float width = 0.0f; - float height = 0.0f; -}; -``` - -### 构造 - -- `Rect(float x, float y, float w, float h)` - -### 边界访问 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `GetLeft()` | `float` | x | -| `GetRight()` | `float` | x + width | -| `GetTop()` | `float` | y | -| `GetBottom()` | `float` | y + height | -| `GetPosition()` | `Vector2` | (x, y) | -| `GetSize()` | `Vector2` | (width, height) | -| `GetCenter()` | `Vector2` | 中心点 | - -### 检测方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Contains(px, py)` | `bool` | 点是否在矩形内 | -| `Contains(point)` | `bool` | Vector2 点检测 | -| `Intersects(other)` | `bool` | 与另一矩形相交 | - -### 静态方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Intersect(a, b)` | `Rect` | 两矩形交集 | -| `Union(a, b)` | `Rect` | 两矩形并集 | - -### 设置方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Set(x, y, w, h)` | `void` | 设置所有值 | -| `SetPosition(x, y)` | `void` | 设置位置 | -| `SetPosition(Vector2)` | `void` | 设置位置 | - ---- - -## RectInt - 整数矩形 - -```cpp -struct RectInt { - int32_t x = 0; - int32_t y = 0; - int32_t width = 0; - int32_t height = 0; -}; -``` - -与 Rect 类似，但使用 int32_t 类型。 - -### 边界访问 - -`GetLeft/Right/Top/Bottom/GetPosition/GetSize/GetCenter` - 返回 int32_t 或 Vector2。 - -### 检测 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Contains(px, py)` | `bool` | 整数点检测 | -| `Intersects(other)` | `bool` | 相交检测 | - ---- - -## Viewport - 视口 - -用于渲染视口和屏幕映射。 - -```cpp -struct Viewport { - float x = 0.0f; - float y = 0.0f; - float width = 0.0f; - float height = 0.0f; - float minDepth = 0.0f; - float maxDepth = 1.0f; -}; -``` - -### 构造 - -- `Viewport(float x, float y, float w, float h)` -- `Viewport(float x, float y, float w, float h, float minD, float maxD)` - -### 方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `GetAspectRatio()` | `float` | 宽高比 (width/height) | -| `GetRect()` | `Rect` | 转换为 Rect | - ---- - -## 使用示例 - -```cpp -// Rect -Rect screenRect(0.0f, 0.0f, 1920.0f, 1080.0f); -if (screenRect.Contains(mouseX, mouseY)) { ... } - -// 矩形相交 -Rect overlap = Rect::Intersect(rectA, rectB); - -// Viewport -Viewport viewport(0, 0, 1920, 1080); -float aspect = viewport.GetAspectRatio(); // 16:9 = 1.78 -``` diff --git a/docs/api/math/math-sphere.md b/docs/api/math/math-sphere.md deleted file mode 100644 index 7438bcf9..00000000 --- a/docs/api/math/math-sphere.md +++ /dev/null @@ -1,47 +0,0 @@ -# Sphere - -3D 球体结构体。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 结构体定义 - -```cpp -struct Sphere { - Vector3 center = Vector3::Zero(); - float radius = 0.0f; -}; -``` - -## 构造函数 - -- `Sphere()` - 默认构造 -- `Sphere(const Vector3& center, float radius)` - 从中心和半径构造 - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Contains(point)` | `bool` | 点是否在球体内（包括表面） | -| `Intersects(other)` | `bool` | 与另一个球体是否相交 | - -## 使用示例 - -```cpp -Sphere sphere(Vector3(0.0f, 0.0f, 0.0f), 1.0f); - -// 检测点 -if (sphere.Contains(Vector3(0.5f, 0.0f, 0.0f))) { ... } - -// 检测球体相交 -Sphere other(Vector3(1.0f, 0.0f, 0.0f), 1.0f); -if (sphere.Intersects(other)) { ... } -``` diff --git a/docs/api/math/math-transform.md b/docs/api/math/math-transform.md deleted file mode 100644 index db5262bb..00000000 --- a/docs/api/math/math-transform.md +++ /dev/null @@ -1,67 +0,0 @@ -# Transform - -3D 变换结构体，包含位置、旋转和缩放，用于层次化变换。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## Space 枚举 - -```cpp -enum class Space { Self, World }; -``` - -## 结构体定义 - -```cpp -struct Transform { - Vector3 position = Vector3::Zero(); - Quaternion rotation = Quaternion::Identity(); - Vector3 scale = Vector3::One(); -}; -``` - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `ToMatrix()` | `Matrix4` | 转换为 4x4 变换矩阵 | -| `Inverse()` | `Transform` | 逆变换 | -| `operator*(Transform, Transform)` | `Transform` | 组合变换 | - -### 空间变换 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `TransformPoint(point)` | `Vector3` | 变换点（带平移） | -| `TransformDirection(direction)` | `Vector3` | 变换方向（不带平移） | -| `InverseTransformPoint(point)` | `Vector3` | 逆变换点 | -| `InverseTransformDirection(direction)` | `Vector3` | 逆变换方向 | - -## 使用示例 - -```cpp -Transform world; -world.position = Vector3(10.0f, 0.0f, 0.0f); -world.rotation = Quaternion::Identity(); -world.scale = Vector3::One(); - -Matrix4 matrix = world.ToMatrix(); - -// 组合父子变换 -Transform parent, child; -parent.position = Vector3(5.0f, 0.0f, 0.0f); -child.position = Vector3(2.0f, 0.0f, 0.0f); -Transform worldTransform = parent * child; - -// 变换点 -Vector3 localPos(1.0f, 0.0f, 0.0f); -Vector3 worldPos = world.TransformPoint(localPos); -``` diff --git a/docs/api/math/math-vector2.md b/docs/api/math/math-vector2.md deleted file mode 100644 index fbff215c..00000000 --- a/docs/api/math/math-vector2.md +++ /dev/null @@ -1,68 +0,0 @@ -# Vector2 - -2D 向量结构体，用于表示 2D 空间中的点、方向或颜色。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 结构体定义 - -```cpp -struct Vector2 { - float x = 0.0f; - float y = 0.0f; -}; -``` - -## 静态工厂方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Zero()` | `Vector2` | 返回 (0, 0) | -| `One()` | `Vector2` | 返回 (1, 1) | -| `Up()` | `Vector2` | 返回 (0, 1)，上方向 | -| `Down()` | `Vector2` | 返回 (0, -1)，下方向 | -| `Right()` | `Vector2` | 返回 (1, 0)，右方向 | -| `Left()` | `Vector2` | 返回 (-1, 0)，左方向 | - -## 静态数学方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Dot(a, b)` | `float` | 点积 | -| `Cross(a, b)` | `float` | 2D 叉积（返回标量） | -| `Normalize(v)` | `Vector2` | 归一化向量 | -| `Magnitude(v)` | `float` | 向量长度 | -| `SqrMagnitude(v)` | `float` | 长度平方（更快） | -| `Lerp(a, b, t)` | `Vector2` | 线性插值 | -| `MoveTowards(current, target, maxDistance)` | `Vector2` | 朝目标移动 | - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Magnitude()` | `float` | 获取向量长度 | -| `SqrMagnitude()` | `float` | 获取长度平方 | -| `Normalized()` | `Vector2` | 获取归一化副本 | - -## 运算符 - -- 算术: `+`, `-`, `*` (scalar), `/` (scalar) -- 复合赋值: `+=`, `-=`, `*=`, `/=` -- 比较: `==`, `!=` - -## 使用示例 - -```cpp -Vector2 pos(5.0f, 3.0f); -Vector2 dir = Vector2::Normalize(pos); -float len = pos.Magnitude(); -Vector2 lerped = Vector2::Lerp(pos, Vector2::Zero(), 0.5f); -``` diff --git a/docs/api/math/math-vector3.md b/docs/api/math/math-vector3.md deleted file mode 100644 index 4e714d0f..00000000 --- a/docs/api/math/math-vector3.md +++ /dev/null @@ -1,84 +0,0 @@ -# Vector3 - -3D 向量结构体，用于表示 3D 空间中的点、方向、颜色或法线。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` - -## 结构体定义 - -```cpp -struct Vector3 { - float x = 0.0f; - float y = 0.0f; - float z = 0.0f; -}; -``` - -## 静态工厂方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Zero()` | `Vector3` | 返回 (0, 0, 0) | -| `One()` | `Vector3` | 返回 (1, 1, 1) | -| `Forward()` | `Vector3` | 返回 (0, 0, 1)，前方向（Z+） | -| `Back()` | `Vector3` | 返回 (0, 0, -1)，后方向 | -| `Up()` | `Vector3` | 返回 (0, 1, 0)，上方向 | -| `Down()` | `Vector3` | 返回 (0, -1, 0)，下方向 | -| `Right()` | `Vector3` | 返回 (1, 0, 0)，右方向 | -| `Left()` | `Vector3` | 返回 (-1, 0, 0)，左方向 | - -## 静态数学方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Dot(a, b)` | `float` | 点积 | -| `Cross(a, b)` | `Vector3` | 叉积（垂直于 a 和 b） | -| `Normalize(v)` | `Vector3` | 归一化向量 | -| `Magnitude(v)` | `float` | 向量长度 | -| `SqrMagnitude(v)` | `float` | 长度平方 | -| `Lerp(a, b, t)` | `Vector3` | 线性插值 | -| `MoveTowards(current, target, maxDistance)` | `Vector3` | 朝目标移动 | -| `Project(vector, onNormal)` | `Vector3` | 投影到法线上 | -| `ProjectOnPlane(vector, planeNormal)` | `Vector3` | 投影到平面上 | -| `Angle(from, to)` | `float` | 两向量夹角（度） | -| `Reflect(inDirection, inNormal)` | `Vector3` | 反射 | - -## 实例方法 - -| 方法 | 返回值 | 描述 | -|------|--------|------| -| `Magnitude()` | `float` | 获取向量长度 | -| `SqrMagnitude()` | `float` | 获取长度平方 | -| `Normalized()` | `Vector3` | 获取归一化副本 | - -## 运算符 - -- 算术: `+`, `-`, `*` (scalar/memberwise), `/` (scalar/memberwise) -- 复合赋值: `+=`, `-=`, `*=`, `/=` -- 下标: `operator[]` (0=x, 1=y, 2=z) -- 比较: `==`, `!=` - -## 与 Quaternion 的乘法 - -```cpp -Vector3 operator*(const Quaternion& q, const Vector3& v); -``` -用四元数旋转向量。 - -## 使用示例 - -```cpp -Vector3 pos(1.0f, 2.0f, 3.0f); -Vector3 dir = Vector3::Normalize(pos); -float len = pos.Magnitude(); -Vector3 reflected = Vector3::Reflect(dir, Vector3::Up()); -float angle = Vector3::Angle(Vector3::Forward(), dir); -``` diff --git a/docs/api/math/math-overview.md b/docs/api/math/math.md similarity index 65% rename from docs/api/math/math-overview.md rename to docs/api/math/math.md index e01f87f5..acab94b0 100644 --- a/docs/api/math/math-overview.md +++ b/docs/api/math/math.md @@ -16,37 +16,37 @@ Math 模块提供了一套完整的图形数学库，包括向量、矩阵、四 | 组件 | 文件 | 描述 | |------|------|------| -| [Vector2](./math-vector2.md) | `Vector2.h` | 二维向量 | -| [Vector3](./math-vector3.md) | `Vector3.h` | 三维向量 | -| [Vector4](./math-vector4.md) | `Vector4.h` | 四维向量 | +| [Vector2](vector2/vector2.md) | `Vector2.h` | 二维向量 | +| [Vector3](vector3/vector3.md) | `Vector3.h` | 三维向量 | +| [Vector4](vector4/vector4.md) | `Vector4.h` | 四维向量 | ### 矩阵类型 | 组件 | 文件 | 描述 | |------|------|------| -| [Matrix3](./math-matrix3.md) | `Matrix3.h` | 3x3 矩阵 | -| [Matrix4](./math-matrix4.md) | `Matrix4.h` | 4x4 矩阵 | +| [Matrix3](matrix3/matrix3.md) | `Matrix3.h` | 3x3 矩阵 | +| [Matrix4](matrix4/matrix4.md) | `Matrix4.h` | 4x4 矩阵 | ### 旋转/变换 | 组件 | 文件 | 描述 | |------|------|------| -| [Quaternion](./math-quaternion.md) | `Quaternion.h` | 四元数 | -| [Transform](./math-transform.md) | `Transform.h` | 变换组件 | +| [Quaternion](quaternion/quaternion.md) | `Quaternion.h` | 四元数 | +| [Transform](transform/transform.md) | `Transform.h` | 变换组件 | ### 几何类型 | 组件 | 文件 | 描述 | |------|------|------| -| [Color](./math-color.md) | `Color.h` | 颜色 | -| [Ray](./math-ray.md) | `Ray.h` | 射线 | -| [Plane](./math-plane.md) | `Plane.h` | 平面 | -| [Sphere](./math-sphere.md) | `Sphere.h` | 球体 | -| [Box](./math-box.md) | `Box.h` | 盒子 | -| [Bounds](./math-bounds.md) | `Bounds.h` | 包围盒 | -| [AABB](./math-aabb.md) | `AABB.h` | 轴对齐包围盒 | -| [Frustum](./math-frustum.md) | `Frustum.h` | 视锥体 | -| [Rect](./math-rect.md) | `Rect.h` | 二维矩形 | +| [Color](color/color.md) | `Color.h` | 颜色 | +| [Ray](ray/ray.md) | `Ray.h` | 射线 | +| [Plane](plane/plane.md) | `Plane.h` | 平面 | +| [Sphere](sphere/sphere.md) | `Sphere.h` | 球体 | +| [Box](box/box.md) | `Box.h` | 盒子 | +| [Bounds](bounds/bounds.md) | `Bounds.h` | 包围盒 | +| [AABB](aabb/aabb.md) | `AABB.h` | 轴对齐包围盒 | +| [Frustum](frustum/frustum.md) | `Frustum.h` | 视锥体 | +| [Rect](rect/rect.md) | `Rect.h` | 二维矩形 | ## 常量定义 @@ -60,7 +60,7 @@ Math 模块提供了一套完整的图形数学库，包括向量、矩阵、四 | `EPSILON` | 1e-6f | 浮点精度 | | `FLOAT_MAX` | 3.402823466e+38f | 浮点最大值 | -详细文档: [Math.h - 常量和辅助函数](./math-h.md) +详细文档: [Math.h - 常量和辅助函数](h/h.md) ## 辅助函数 @@ -93,7 +93,7 @@ Matrix4 projection = Matrix4::Perspective(fov, aspect, near, far); Matrix4 mvp = projection * view * model; // 四元数运算 -Quaternion q1 = Quaternion::FromEuler(0, 90, 0); +Quaternion q1 = Quaternion::FromEulerAngles(0, 90 * DEG_TO_RAD, 0); Quaternion q2 = Quaternion::FromAxisAngle(Vector3::Up(), Math::Radians(45.0f)); Quaternion combined = q1 * q2; Vector3 rotated = q2 * Vector3::Forward(); diff --git a/docs/api/math/matrix3/determinant.md b/docs/api/math/matrix3/determinant.md new file mode 100644 index 00000000..6d237fa2 --- /dev/null +++ b/docs/api/math/matrix3/determinant.md @@ -0,0 +1,18 @@ +# Matrix3::Determinant + +```cpp +float Determinant() const +``` + +计算矩阵的行列式。 + +**返回：** `float` - 行列式值 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 mat = ...; +float det = mat.Determinant(); +``` diff --git a/docs/api/math/matrix3/identity.md b/docs/api/math/matrix3/identity.md new file mode 100644 index 00000000..e32fcfdb --- /dev/null +++ b/docs/api/math/matrix3/identity.md @@ -0,0 +1,17 @@ +# Matrix3::Identity + +```cpp +static Matrix3 Identity() +``` + +返回 3x3 单位矩阵。 + +**返回：** `Matrix3` - 单位矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 identity = Matrix3::Identity(); +``` diff --git a/docs/api/math/matrix3/inverse.md b/docs/api/math/matrix3/inverse.md new file mode 100644 index 00000000..3a3b05ce --- /dev/null +++ b/docs/api/math/matrix3/inverse.md @@ -0,0 +1,18 @@ +# Matrix3::Inverse + +```cpp +Matrix3 Inverse() const +``` + +返回矩阵的逆矩阵。 + +**返回：** `Matrix3` - 逆矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 mat = ...; +Matrix3 inv = mat.Inverse(); +``` diff --git a/docs/api/math/matrix3/matrix3.md b/docs/api/math/matrix3/matrix3.md new file mode 100644 index 00000000..ebeab7eb --- /dev/null +++ b/docs/api/math/matrix3/matrix3.md @@ -0,0 +1,57 @@ +# Matrix3 / Matrix3x3 + +3x3 矩阵结构体，用于表示 3D 旋转和缩放变换。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 类型别名 + +```cpp +using Matrix3 = Matrix3x3; +``` + +## 存储方式 + +行优先存储 (row-major)： +``` +m[row][col] +m[0][0] m[0][1] m[0][2] +m[1][0] m[1][1] m[1][2] +m[2][0] m[2][1] m[2][2] +``` + +## 构造函数 + +- 默认构造函数初始化为零矩阵 + +## 静态工厂方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Identity()](identity.md) | `Matrix3` | 单位矩阵 | +| [Zero()](zero.md) | `Matrix3` | 零矩阵 | +| [RotationX(radians)](rotationx.md) | `Matrix3` | X 轴旋转矩阵 | +| [RotationY(radians)](rotationy.md) | `Matrix3` | Y 轴旋转矩阵 | +| [RotationZ(radians)](rotationz.md) | `Matrix3` | Z 轴旋转矩阵 | +| [Scale(scale)](scale.md) | `Matrix3` | 缩放矩阵 | + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Transpose()](transpose.md) | `Matrix3` | 转置矩阵 | +| [Inverse()](inverse.md) | `Matrix3` | 逆矩阵 | +| [Determinant()](determinant.md) | `float` | 行列式 | + +## 运算符 + +| 运算符 | 描述 | +|--------|------| +| `operator*(Matrix3, Matrix3)` | 矩阵乘法 | +| `operator*(Matrix3, Vector3)` | 矩阵-向量乘法 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/matrix3/rotationx.md b/docs/api/math/matrix3/rotationx.md new file mode 100644 index 00000000..90888bb7 --- /dev/null +++ b/docs/api/math/matrix3/rotationx.md @@ -0,0 +1,20 @@ +# Matrix3::RotationX + +```cpp +static Matrix3 RotationX(float radians) +``` + +创建绕 X 轴旋转的矩阵。 + +**参数：** +- `radians` - 旋转角度（弧度） + +**返回：** `Matrix3` - 旋转矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 rotX = Matrix3::RotationX(Math::HALF_PI); +``` diff --git a/docs/api/math/matrix3/rotationy.md b/docs/api/math/matrix3/rotationy.md new file mode 100644 index 00000000..3874843a --- /dev/null +++ b/docs/api/math/matrix3/rotationy.md @@ -0,0 +1,20 @@ +# Matrix3::RotationY + +```cpp +static Matrix3 RotationY(float radians) +``` + +创建绕 Y 轴旋转的矩阵。 + +**参数：** +- `radians` - 旋转角度（弧度） + +**返回：** `Matrix3` - 旋转矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 rotY = Matrix3::RotationY(Math::HALF_PI); +``` diff --git a/docs/api/math/matrix3/rotationz.md b/docs/api/math/matrix3/rotationz.md new file mode 100644 index 00000000..2626ee4b --- /dev/null +++ b/docs/api/math/matrix3/rotationz.md @@ -0,0 +1,20 @@ +# Matrix3::RotationZ + +```cpp +static Matrix3 RotationZ(float radians) +``` + +创建绕 Z 轴旋转的矩阵。 + +**参数：** +- `radians` - 旋转角度（弧度） + +**返回：** `Matrix3` - 旋转矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 rotZ = Matrix3::RotationZ(Math::HALF_PI); +``` diff --git a/docs/api/math/matrix3/scale.md b/docs/api/math/matrix3/scale.md new file mode 100644 index 00000000..bcb6e7a8 --- /dev/null +++ b/docs/api/math/matrix3/scale.md @@ -0,0 +1,20 @@ +# Matrix3::Scale + +```cpp +static Matrix3 Scale(const Vector3& scale) +``` + +创建缩放矩阵。 + +**参数：** +- `scale` - 各轴缩放因子 + +**返回：** `Matrix3` - 缩放矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 scale = Matrix3::Scale(Vector3(2.0f, 2.0f, 2.0f)); +``` diff --git a/docs/api/math/matrix3/transpose.md b/docs/api/math/matrix3/transpose.md new file mode 100644 index 00000000..5c29068c --- /dev/null +++ b/docs/api/math/matrix3/transpose.md @@ -0,0 +1,18 @@ +# Matrix3::Transpose + +```cpp +Matrix3 Transpose() const +``` + +返回矩阵的转置。 + +**返回：** `Matrix3` - 转置矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 mat = ...; +Matrix3 transposed = mat.Transpose(); +``` diff --git a/docs/api/math/matrix3/zero.md b/docs/api/math/matrix3/zero.md new file mode 100644 index 00000000..45709046 --- /dev/null +++ b/docs/api/math/matrix3/zero.md @@ -0,0 +1,17 @@ +# Matrix3::Zero + +```cpp +static Matrix3 Zero() +``` + +返回零矩阵。 + +**返回：** `Matrix3` - 零矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix3 zero = Matrix3::Zero(); +``` diff --git a/docs/api/math/matrix4/decompose.md b/docs/api/math/matrix4/decompose.md new file mode 100644 index 00000000..3173c5c6 --- /dev/null +++ b/docs/api/math/matrix4/decompose.md @@ -0,0 +1,24 @@ +# Matrix4::Decompose + +```cpp +void Decompose(Vector3& translation, Quaternion& rotation, Vector3& scale) const +``` + +将矩阵分解为平移、旋转和缩放分量。 + +**参数：** +- `translation` - 输出平移向量 +- `rotation` - 输出旋转四元数 +- `scale` - 输出缩放向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 m = ...; +Vector3 translation; +Quaternion rotation; +Vector3 scale; +m.Decompose(translation, rotation, scale); +``` diff --git a/docs/api/math/matrix4/determinant.md b/docs/api/math/matrix4/determinant.md new file mode 100644 index 00000000..52ca8ac0 --- /dev/null +++ b/docs/api/math/matrix4/determinant.md @@ -0,0 +1,18 @@ +# Matrix4::Determinant + +```cpp +float Determinant() const +``` + +计算矩阵的行列式。 + +**返回：** `float` - 行列式值 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 m = ...; +float det = m.Determinant(); +``` diff --git a/docs/api/math/matrix4/getrotation.md b/docs/api/math/matrix4/getrotation.md new file mode 100644 index 00000000..720a7563 --- /dev/null +++ b/docs/api/math/matrix4/getrotation.md @@ -0,0 +1,18 @@ +# Matrix4::GetRotation + +```cpp +Quaternion GetRotation() const +``` + +从矩阵中提取旋转分量。 + +**返回：** `Quaternion` - 旋转四元数 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 m = ...; +Quaternion rotation = m.GetRotation(); +``` diff --git a/docs/api/math/matrix4/getscale.md b/docs/api/math/matrix4/getscale.md new file mode 100644 index 00000000..660ec649 --- /dev/null +++ b/docs/api/math/matrix4/getscale.md @@ -0,0 +1,18 @@ +# Matrix4::GetScale + +```cpp +Vector3 GetScale() const +``` + +从矩阵中提取缩放分量。 + +**返回：** `Vector3` - 缩放向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 m = ...; +Vector3 scale = m.GetScale(); +``` diff --git a/docs/api/math/matrix4/gettranslation.md b/docs/api/math/matrix4/gettranslation.md new file mode 100644 index 00000000..adede5d4 --- /dev/null +++ b/docs/api/math/matrix4/gettranslation.md @@ -0,0 +1,18 @@ +# Matrix4::GetTranslation + +```cpp +Vector3 GetTranslation() const +``` + +从矩阵中提取平移分量。 + +**返回：** `Vector3` - 平移向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 m = ...; +Vector3 translation = m.GetTranslation(); +``` diff --git a/docs/api/math/matrix4/identity.md b/docs/api/math/matrix4/identity.md new file mode 100644 index 00000000..5609574f --- /dev/null +++ b/docs/api/math/matrix4/identity.md @@ -0,0 +1,17 @@ +# Matrix4::Identity + +```cpp +static Matrix4 Identity() +``` + +返回 4x4 单位矩阵。 + +**返回：** `Matrix4` - 单位矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 identity = Matrix4::Identity(); +``` diff --git a/docs/api/math/matrix4/inverse.md b/docs/api/math/matrix4/inverse.md new file mode 100644 index 00000000..a0ce7f5f --- /dev/null +++ b/docs/api/math/matrix4/inverse.md @@ -0,0 +1,18 @@ +# Matrix4::Inverse + +```cpp +Matrix4 Inverse() const +``` + +返回矩阵的逆矩阵。 + +**返回：** `Matrix4` - 逆矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 m = ...; +Matrix4 inv = m.Inverse(); +``` diff --git a/docs/api/math/matrix4/lookat.md b/docs/api/math/matrix4/lookat.md new file mode 100644 index 00000000..d8e8d004 --- /dev/null +++ b/docs/api/math/matrix4/lookat.md @@ -0,0 +1,22 @@ +# Matrix4::LookAt + +```cpp +static Matrix4 LookAt(const Vector3& eye, const Vector3& target, const Vector3& up) +``` + +创建视图矩阵（观察矩阵）。 + +**参数：** +- `eye` - 相机位置 +- `target` - 观察目标点 +- `up` - 世界空间中的上方向 + +**返回：** `Matrix4` - 视图矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 view = Matrix4::LookAt(cameraPos, target, Vector3::Up()); +``` diff --git a/docs/api/math/matrix4/matrix4.md b/docs/api/math/matrix4/matrix4.md new file mode 100644 index 00000000..c5e90c6a --- /dev/null +++ b/docs/api/math/matrix4/matrix4.md @@ -0,0 +1,79 @@ +# Matrix4 / Matrix4x4 + +4x4 矩阵结构体，用于表示完整的 3D 变换（平移、旋转、缩放）、视图和投影变换。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 类型别名 + +```cpp +using Matrix4 = Matrix4x4; +``` + +## 存储方式 + +行优先存储 (row-major)： +``` +m[0][0] m[0][1] m[0][2] m[0][3] +m[1][0] m[1][1] m[1][2] m[1][3] +m[2][0] m[2][1] m[2][2] m[2][3] +m[3][0] m[3][1] m[3][2] m[3][3] +``` + +## 静态工厂方法 + +### 基础变换 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Identity()](identity.md) | `Matrix4` | 单位矩阵 | +| [Zero()](zero.md) | `Matrix4` | 零矩阵 | +| [Translation(v)](translation.md) | `Matrix4` | 平移矩阵 | +| [Scale(v)](scale.md) | `Matrix4` | 缩放矩阵 | +| [Rotation(q)](rotation.md) | `Matrix4` | 旋转矩阵（四元数） | +| [TRS(translation, rotation, scale)](trs.md) | `Matrix4` | 完整变换 | + +### 旋转 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [RotationX(radians)](rotationx.md) | `Matrix4` | X 轴旋转 | +| [RotationY(radians)](rotationy.md) | `Matrix4` | Y 轴旋转 | +| [RotationZ(radians)](rotationz.md) | `Matrix4` | Z 轴旋转 | + +### 相机变换 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [LookAt(eye, target, up)](lookat.md) | `Matrix4` | 视图矩阵 | +| [Perspective(fov, aspect, near, far)](perspective.md) | `Matrix4` | 透视投影 | +| [Orthographic(left, right, bottom, top, near, far)](orthographic.md) | `Matrix4` | 正交投影 | + +## 实例方法 + +### 乘法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| `operator*(Matrix4, Matrix4)` | `Matrix4` | 矩阵乘法 | +| `operator*(Matrix4, Vector4)` | `Vector4` | 矩阵-向量乘法 | +| [MultiplyPoint(v)](multiplypoint.md) | `Vector3` | 点变换（带平移） | +| [MultiplyVector(v)](multiplyvector.md) | `Vector3` | 方向变换（不带平移） | + +### 分解 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Transpose()](transpose.md) | `Matrix4` | 转置矩阵 | +| [Inverse()](inverse.md) | `Matrix4` | 逆矩阵 | +| [Determinant()](determinant.md) | `float` | 行列式 | +| [GetTranslation()](gettranslation.md) | `Vector3` | 获取平移分量 | +| [GetRotation()](getrotation.md) | `Quaternion` | 获取旋转分量 | +| [GetScale()](getscale.md) | `Vector3` | 获取缩放分量 | +| [Decompose(translation, rotation, scale)](decompose.md) | `void` | 分解所有分量 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/matrix4/multiplypoint.md b/docs/api/math/matrix4/multiplypoint.md new file mode 100644 index 00000000..059f1c9f --- /dev/null +++ b/docs/api/math/matrix4/multiplypoint.md @@ -0,0 +1,21 @@ +# Matrix4::MultiplyPoint + +```cpp +Vector3 MultiplyPoint(const Vector3& v) const +``` + +使用矩阵变换点（包含平移）。 + +**参数：** +- `v` - 要变换的点 + +**返回：** `Vector3` - 变换后的点 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 model = Matrix4::TRS(pos, rot, scale); +Vector3 worldPos = model.MultiplyPoint(localPos); +``` diff --git a/docs/api/math/matrix4/multiplyvector.md b/docs/api/math/matrix4/multiplyvector.md new file mode 100644 index 00000000..a0fa4f5b --- /dev/null +++ b/docs/api/math/matrix4/multiplyvector.md @@ -0,0 +1,21 @@ +# Matrix4::MultiplyVector + +```cpp +Vector3 MultiplyVector(const Vector3& v) const +``` + +使用矩阵变换方向向量（不包含平移）。 + +**参数：** +- `v` - 要变换的方向向量 + +**返回：** `Vector3` - 变换后的方向 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 model = Matrix4::TRS(pos, rot, scale); +Vector3 worldDir = model.MultiplyVector(localDir); +``` diff --git a/docs/api/math/matrix4/orthographic.md b/docs/api/math/matrix4/orthographic.md new file mode 100644 index 00000000..f8b156a8 --- /dev/null +++ b/docs/api/math/matrix4/orthographic.md @@ -0,0 +1,25 @@ +# Matrix4::Orthographic + +```cpp +static Matrix4 Orthographic(float left, float right, float bottom, float top, float near, float far) +``` + +创建正交投影矩阵。 + +**参数：** +- `left` - 左裁剪面 +- `right` - 右裁剪面 +- `bottom` - 下裁剪面 +- `top` - 上裁剪面 +- `near` - 近裁剪面距离 +- `far` - 远裁剪面距离 + +**返回：** `Matrix4` - 正交投影矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 ortho = Matrix4::Orthographic(-aspect, aspect, -1.0f, 1.0f, 0.1f, 100.0f); +``` diff --git a/docs/api/math/matrix4/perspective.md b/docs/api/math/matrix4/perspective.md new file mode 100644 index 00000000..8316a8c7 --- /dev/null +++ b/docs/api/math/matrix4/perspective.md @@ -0,0 +1,23 @@ +# Matrix4::Perspective + +```cpp +static Matrix4 Perspective(float fov, float aspect, float near, float far) +``` + +创建透视投影矩阵。 + +**参数：** +- `fov` - 垂直视野角度（弧度） +- `aspect` - 宽高比 +- `near` - 近裁剪面距离 +- `far` - 远裁剪面距离 + +**返回：** `Matrix4` - 透视投影矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 proj = Matrix4::Perspective(45.0f * DEG_TO_RAD, aspect, 0.1f, 100.0f); +``` diff --git a/docs/api/math/matrix4/rotation.md b/docs/api/math/matrix4/rotation.md new file mode 100644 index 00000000..b0b0b7b2 --- /dev/null +++ b/docs/api/math/matrix4/rotation.md @@ -0,0 +1,21 @@ +# Matrix4::Rotation + +```cpp +static Matrix4 Rotation(const Quaternion& q) +``` + +从四元数创建旋转矩阵。 + +**参数：** +- `q` - 四元数 + +**返回：** `Matrix4` - 旋转矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f); +Matrix4 rotation = Matrix4::Rotation(rot); +``` diff --git a/docs/api/math/matrix4/rotationx.md b/docs/api/math/matrix4/rotationx.md new file mode 100644 index 00000000..1cf1fc7e --- /dev/null +++ b/docs/api/math/matrix4/rotationx.md @@ -0,0 +1,20 @@ +# Matrix4::RotationX + +```cpp +static Matrix4 RotationX(float radians) +``` + +创建绕 X 轴旋转的矩阵。 + +**参数：** +- `radians` - 旋转角度（弧度） + +**返回：** `Matrix4` - 旋转矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 rotX = Matrix4::RotationX(Math::HALF_PI); +``` diff --git a/docs/api/math/matrix4/rotationy.md b/docs/api/math/matrix4/rotationy.md new file mode 100644 index 00000000..039c703d --- /dev/null +++ b/docs/api/math/matrix4/rotationy.md @@ -0,0 +1,20 @@ +# Matrix4::RotationY + +```cpp +static Matrix4 RotationY(float radians) +``` + +创建绕 Y 轴旋转的矩阵。 + +**参数：** +- `radians` - 旋转角度（弧度） + +**返回：** `Matrix4` - 旋转矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 rotY = Matrix4::RotationY(Math::HALF_PI); +``` diff --git a/docs/api/math/matrix4/rotationz.md b/docs/api/math/matrix4/rotationz.md new file mode 100644 index 00000000..67748363 --- /dev/null +++ b/docs/api/math/matrix4/rotationz.md @@ -0,0 +1,20 @@ +# Matrix4::RotationZ + +```cpp +static Matrix4 RotationZ(float radians) +``` + +创建绕 Z 轴旋转的矩阵。 + +**参数：** +- `radians` - 旋转角度（弧度） + +**返回：** `Matrix4` - 旋转矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 rotZ = Matrix4::RotationZ(Math::HALF_PI); +``` diff --git a/docs/api/math/matrix4/scale.md b/docs/api/math/matrix4/scale.md new file mode 100644 index 00000000..80477603 --- /dev/null +++ b/docs/api/math/matrix4/scale.md @@ -0,0 +1,20 @@ +# Matrix4::Scale + +```cpp +static Matrix4 Scale(const Vector3& v) +``` + +创建缩放矩阵。 + +**参数：** +- `v` - 各轴缩放因子 + +**返回：** `Matrix4` - 缩放矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 scale = Matrix4::Scale(Vector3(2.0f, 2.0f, 2.0f)); +``` diff --git a/docs/api/math/matrix4/translation.md b/docs/api/math/matrix4/translation.md new file mode 100644 index 00000000..8b8b3edb --- /dev/null +++ b/docs/api/math/matrix4/translation.md @@ -0,0 +1,20 @@ +# Matrix4::Translation + +```cpp +static Matrix4 Translation(const Vector3& v) +``` + +创建平移矩阵。 + +**参数：** +- `v` - 平移向量 + +**返回：** `Matrix4` - 平移矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 translation = Matrix4::Translation(Vector3(1.0f, 2.0f, 3.0f)); +``` diff --git a/docs/api/math/matrix4/transpose.md b/docs/api/math/matrix4/transpose.md new file mode 100644 index 00000000..ad490342 --- /dev/null +++ b/docs/api/math/matrix4/transpose.md @@ -0,0 +1,18 @@ +# Matrix4::Transpose + +```cpp +Matrix4 Transpose() const +``` + +返回矩阵的转置。 + +**返回：** `Matrix4` - 转置矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 m = ...; +Matrix4 transposed = m.Transpose(); +``` diff --git a/docs/api/math/matrix4/trs.md b/docs/api/math/matrix4/trs.md new file mode 100644 index 00000000..3d0a3348 --- /dev/null +++ b/docs/api/math/matrix4/trs.md @@ -0,0 +1,22 @@ +# Matrix4::TRS + +```cpp +static Matrix4 TRS(const Vector3& translation, const Quaternion& rotation, const Vector3& scale) +``` + +创建完整的 TRS（平移、旋转、缩放）变换矩阵。 + +**参数：** +- `translation` - 平移向量 +- `rotation` - 旋转四元数 +- `scale` - 缩放向量 + +**返回：** `Matrix4` - 组合变换矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 transform = Matrix4::TRS(position, rotation, Vector3::One()); +``` diff --git a/docs/api/math/matrix4/zero.md b/docs/api/math/matrix4/zero.md new file mode 100644 index 00000000..133c16d4 --- /dev/null +++ b/docs/api/math/matrix4/zero.md @@ -0,0 +1,17 @@ +# Matrix4::Zero + +```cpp +static Matrix4 Zero() +``` + +返回零矩阵。 + +**返回：** `Matrix4` - 零矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 zero = Matrix4::Zero(); +``` diff --git a/docs/api/math/plane/frompoints.md b/docs/api/math/plane/frompoints.md new file mode 100644 index 00000000..a9503a63 --- /dev/null +++ b/docs/api/math/plane/frompoints.md @@ -0,0 +1,22 @@ +# Plane::FromPoints + +```cpp +static Plane FromPoints(const Vector3& a, const Vector3& b, const Vector3& c) +``` + +从三个不共线点创建平面。 + +**参数：** +- `a` - 第一个点 +- `b` - 第二个点 +- `c` - 第三个点 + +**返回：** `Plane` - 由三点定义的平面 + +**复杂度：** O(1) + +**示例：** + +```cpp +Plane plane = Plane::FromPoints(p0, p1, p2); +``` diff --git a/docs/api/math/plane/getclosestpoint.md b/docs/api/math/plane/getclosestpoint.md new file mode 100644 index 00000000..17dfcc26 --- /dev/null +++ b/docs/api/math/plane/getclosestpoint.md @@ -0,0 +1,20 @@ +# Plane::GetClosestPoint + +```cpp +Vector3 GetClosestPoint(const Vector3& point) const +``` + +计算平面上最接近给定点的点。 + +**参数：** +- `point` - 参考点 + +**返回：** `Vector3` - 平面上最接近的点 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 closest = plane.GetClosestPoint(point); +``` diff --git a/docs/api/math/plane/getdistancetopoint.md b/docs/api/math/plane/getdistancetopoint.md new file mode 100644 index 00000000..6e797236 --- /dev/null +++ b/docs/api/math/plane/getdistancetopoint.md @@ -0,0 +1,20 @@ +# Plane::GetDistanceToPoint + +```cpp +float GetDistanceToPoint(const Vector3& point) const +``` + +计算点到平面的有符号距离。 + +**参数：** +- `point` - 要计算的点 + +**返回：** `float` - 有符号距离 + +**复杂度：** O(1) + +**示例：** + +```cpp +float dist = plane.GetDistanceToPoint(point); +``` diff --git a/docs/api/math/plane/getside.md b/docs/api/math/plane/getside.md new file mode 100644 index 00000000..b6948520 --- /dev/null +++ b/docs/api/math/plane/getside.md @@ -0,0 +1,20 @@ +# Plane::GetSide + +```cpp +bool GetSide(const Vector3& point) const +``` + +判断点在平面的哪一侧。 + +**参数：** +- `point` - 要测试的点 + +**返回：** `bool` - true 表示点在法线方向一侧 + +**复杂度：** O(1) + +**示例：** + +```cpp +if (plane.GetSide(point)) { /* point is on normal side */ } +``` diff --git a/docs/api/math/plane/intersects.md b/docs/api/math/plane/intersects.md new file mode 100644 index 00000000..03c88551 --- /dev/null +++ b/docs/api/math/plane/intersects.md @@ -0,0 +1,20 @@ +# Plane::Intersects + +```cpp +bool Intersects(const Sphere& sphere) const +``` + +检测平面是否与球体相交。 + +**参数：** +- `sphere` - 要检测的球体 + +**返回：** `bool` - true 表示相交 + +**复杂度：** O(1) + +**示例：** + +```cpp +if (plane.Intersects(sphere)) { /* collision */ } +``` diff --git a/docs/api/math/plane/plane.md b/docs/api/math/plane/plane.md new file mode 100644 index 00000000..89782320 --- /dev/null +++ b/docs/api/math/plane/plane.md @@ -0,0 +1,40 @@ +# Plane + +3D 平面结构体，由法线和距离表示。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Plane { + Vector3 normal = Vector3::Up(); + float distance = 0.0f; +}; +``` + +## 构造函数 + +- `Plane()` - 默认构造 (y=0 平面) +- `Plane(const Vector3& normal, float distance)` - 从法线和距离构造 + +## 静态工厂方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [FromPoints(a, b, c)](frompoints.md) | `Plane` | 从三个不共线点创建 | + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [GetDistanceToPoint(point)](getdistancetopoint.md) | `float` | 点到平面的有符号距离 | +| [GetClosestPoint(point)](getclosestpoint.md) | `Vector3` | 平面上最接近给定点的点 | +| [GetSide(point)](getside.md) | `bool` | 点在平面的哪一侧 | +| [Intersects(sphere)](intersects.md) | `bool` | 与球体相交 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/quaternion/dot.md b/docs/api/math/quaternion/dot.md new file mode 100644 index 00000000..8daf0d70 --- /dev/null +++ b/docs/api/math/quaternion/dot.md @@ -0,0 +1,20 @@ +# Quaternion::Dot + +```cpp +float Dot(const Quaternion& other) const +``` + +计算两个四元数的点积。 + +**参数：** +- `other` - 另一个四元数 + +**返回：** `float` - 点积结果 + +**复杂度：** O(1) + +**示例：** + +```cpp +float dot = quat1.Dot(quat2); +``` diff --git a/docs/api/math/quaternion/fromaxisangle.md b/docs/api/math/quaternion/fromaxisangle.md new file mode 100644 index 00000000..0db57dff --- /dev/null +++ b/docs/api/math/quaternion/fromaxisangle.md @@ -0,0 +1,21 @@ +# Quaternion::FromAxisAngle + +```cpp +static Quaternion FromAxisAngle(const Vector3& axis, float radians) +``` + +从轴角创建四元数。 + +**参数：** +- `axis` - 旋转轴（应为单位向量） +- `radians` - 旋转角度（弧度） + +**返回：** `Quaternion` - 表示旋转的四元数 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion rot = Quaternion::FromAxisAngle(Vector3::Up(), 90.0f * DEG_TO_RAD); +``` diff --git a/docs/api/math/quaternion/fromeulerangles.md b/docs/api/math/quaternion/fromeulerangles.md new file mode 100644 index 00000000..b3d3c3be --- /dev/null +++ b/docs/api/math/quaternion/fromeulerangles.md @@ -0,0 +1,25 @@ +# Quaternion::FromEulerAngles + +```cpp +static Quaternion FromEulerAngles(float pitch, float yaw, float roll) +static Quaternion FromEulerAngles(const Vector3& euler) +``` + +从欧拉角创建四元数。角度以弧度为单位。 + +**参数：** +- `pitch` - 俯仰角（X 轴旋转） +- `yaw` - 偏航角（Y 轴旋转） +- `roll` - 翻滚角（Z 轴旋转） +- `euler` - 欧拉角向量 (pitch, yaw, roll) + +**返回：** `Quaternion` - 表示旋转的四元数 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f); +Quaternion rot2 = Quaternion::FromEulerAngles(Vector3(0.0f, 90.0f * DEG_TO_RAD, 0.0f)); +``` diff --git a/docs/api/math/quaternion/fromrotationmatrix.md b/docs/api/math/quaternion/fromrotationmatrix.md new file mode 100644 index 00000000..82c45e53 --- /dev/null +++ b/docs/api/math/quaternion/fromrotationmatrix.md @@ -0,0 +1,21 @@ +# Quaternion::FromRotationMatrix + +```cpp +static Quaternion FromRotationMatrix(const Matrix4x4& matrix) +``` + +从旋转矩阵创建四元数。 + +**参数：** +- `matrix` - 旋转矩阵 + +**返回：** `Quaternion` - 表示相同旋转的四元数 + +**复杂度：** O(1) + +**示例：** + +```cpp +Matrix4 rotMat = Matrix4::RotationY(90.0f * DEG_TO_RAD); +Quaternion quat = Quaternion::FromRotationMatrix(rotMat); +``` diff --git a/docs/api/math/quaternion/identity.md b/docs/api/math/quaternion/identity.md new file mode 100644 index 00000000..965437a4 --- /dev/null +++ b/docs/api/math/quaternion/identity.md @@ -0,0 +1,17 @@ +# Quaternion::Identity + +```cpp +static Quaternion Identity() +``` + +返回恒等四元数（无旋转）。 + +**返回：** `Quaternion` - 值为 (0, 0, 0, 1) 的四元数 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion identity = Quaternion::Identity(); +``` diff --git a/docs/api/math/quaternion/inverse.md b/docs/api/math/quaternion/inverse.md new file mode 100644 index 00000000..a9e1aa9c --- /dev/null +++ b/docs/api/math/quaternion/inverse.md @@ -0,0 +1,17 @@ +# Quaternion::Inverse + +```cpp +Quaternion Inverse() const +``` + +返回四元数的逆（对于单位四元数就是共轭）。 + +**返回：** `Quaternion` - 逆四元数 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion inv = quat.Inverse(); +``` diff --git a/docs/api/math/quaternion/lookrotation.md b/docs/api/math/quaternion/lookrotation.md new file mode 100644 index 00000000..59de421f --- /dev/null +++ b/docs/api/math/quaternion/lookrotation.md @@ -0,0 +1,21 @@ +# Quaternion::LookRotation + +```cpp +static Quaternion LookRotation(const Vector3& forward, const Vector3& up = Vector3::Up()) +``` + +创建使 forward 方向朝向目标的旋转四元数。 + +**参数：** +- `forward` - 前方向向量 +- `up` - 上方向向量（默认 Y 轴向上） + +**返回：** `Quaternion` - 看向方向的旋转 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion lookAt = Quaternion::LookRotation(target - position); +``` diff --git a/docs/api/math/quaternion/magnitude.md b/docs/api/math/quaternion/magnitude.md new file mode 100644 index 00000000..a17b42bc --- /dev/null +++ b/docs/api/math/quaternion/magnitude.md @@ -0,0 +1,17 @@ +# Quaternion::Magnitude + +```cpp +float Magnitude() const +``` + +计算四元数的模长。 + +**返回：** `float` - 四元数的模长 + +**复杂度：** O(1) + +**示例：** + +```cpp +float mag = quat.Magnitude(); +``` diff --git a/docs/api/math/quaternion/normalized.md b/docs/api/math/quaternion/normalized.md new file mode 100644 index 00000000..a795631d --- /dev/null +++ b/docs/api/math/quaternion/normalized.md @@ -0,0 +1,19 @@ +# Quaternion::Normalized + +```cpp +Quaternion Normalized() const +Quaternion Normalize(const Quaternion& q) +``` + +归一化四元数。 + +**返回：** `Quaternion` - 归一化后的四元数 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion unit = quat.Normalized(); +Quaternion unit2 = Quaternion::Normalize(quat); +``` diff --git a/docs/api/math/quaternion/quaternion-multiply.md b/docs/api/math/quaternion/quaternion-multiply.md new file mode 100644 index 00000000..7dc4ebfb --- /dev/null +++ b/docs/api/math/quaternion/quaternion-multiply.md @@ -0,0 +1,23 @@ +# Quaternion * Vector3 + +```cpp +Vector3 operator*(const Quaternion& q, const Vector3& v) +``` + +用四元数旋转向量。 + +**参数：** +- `q` - 旋转四元数 +- `v` - 要旋转的向量 + +**返回：** `Vector3` - 旋转后的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f); +Vector3 forward = Vector3::Forward(); +Vector3 rotated = rot * forward; +``` diff --git a/docs/api/math/quaternion/quaternion.md b/docs/api/math/quaternion/quaternion.md new file mode 100644 index 00000000..98519c00 --- /dev/null +++ b/docs/api/math/quaternion/quaternion.md @@ -0,0 +1,56 @@ +# Quaternion + +四元数结构体，用于表示 3D 旋转，避免欧拉角的万向锁问题。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Quaternion { + float x = 0.0f; + float y = 0.0f; + float z = 0.0f; + float w = 1.0f; +}; +``` + +## 静态工厂方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Identity()](identity.md) | `Quaternion` | 返回 (0, 0, 0, 1)，恒等旋转 | +| [FromAxisAngle(axis, radians)](fromaxisangle.md) | `Quaternion` | 从轴角创建 | +| [FromEulerAngles(pitch, yaw, roll)](fromeulerangles.md) | `Quaternion` | 从欧拉角创建（弧度） | +| [FromEulerAngles(euler)](fromeulerangles.md) | `Quaternion` | 从 Vector3 欧拉角创建 | +| [FromRotationMatrix(matrix)](fromrotationmatrix.md) | `Quaternion` | 从旋转矩阵创建 | +| [Slerp(a, b, t)](slerp.md) | `Quaternion` | 球面线性插值 | +| [LookRotation(forward, up)](lookrotation.md) | `Quaternion` | 看向方向 | + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [ToEulerAngles()](toeulerangles.md) | `Vector3` | 转换为欧拉角（弧度） | +| [ToMatrix4x4()](tomatrix4x4.md) | `Matrix4` | 转换为 4x4 旋转矩阵 | +| [Inverse()](inverse.md) | `Quaternion` | 共轭/逆四元数 | +| [Dot(other)](dot.md) | `float` | 点积 | +| [Magnitude()](magnitude.md) | `float` | 模长 | +| [Normalized()](normalized.md) | `Quaternion` | 归一化 | +| [Normalize(q)](../vector2/normalize.md) | `Quaternion` | 归一化（静态） | + +## 运算符 + +| 运算符 | 描述 | +|--------|------| +| `operator*(Quaternion, Quaternion)` | 组合旋转 | + +## 与 Vector3 的乘法 + +[Vector3 * Quaternion](quaternion-multiply.md) - 用四元数旋转向量 + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/quaternion/slerp.md b/docs/api/math/quaternion/slerp.md new file mode 100644 index 00000000..a2e058fb --- /dev/null +++ b/docs/api/math/quaternion/slerp.md @@ -0,0 +1,22 @@ +# Quaternion::Slerp + +```cpp +static Quaternion Slerp(const Quaternion& a, const Quaternion& b, float t) +``` + +在两个四元数之间进行球面线性插值。 + +**参数：** +- `a` - 起始四元数 +- `b` - 结束四元数 +- `t` - 插值因子（0-1） + +**返回：** `Quaternion` - 插值结果 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion lerped = Quaternion::Slerp(rot1, rot2, 0.5f); +``` diff --git a/docs/api/math/quaternion/toeulerangles.md b/docs/api/math/quaternion/toeulerangles.md new file mode 100644 index 00000000..13ba405d --- /dev/null +++ b/docs/api/math/quaternion/toeulerangles.md @@ -0,0 +1,18 @@ +# Quaternion::ToEulerAngles + +```cpp +Vector3 ToEulerAngles() const +``` + +将四元数转换为欧拉角（弧度）。 + +**返回：** `Vector3` - 欧拉角 (pitch, yaw, roll) + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion rot = ...; +Vector3 euler = rot.ToEulerAngles(); +``` diff --git a/docs/api/math/quaternion/tomatrix4x4.md b/docs/api/math/quaternion/tomatrix4x4.md new file mode 100644 index 00000000..1e98b7fa --- /dev/null +++ b/docs/api/math/quaternion/tomatrix4x4.md @@ -0,0 +1,18 @@ +# Quaternion::ToMatrix4x4 + +```cpp +Matrix4x4 ToMatrix4x4() const +``` + +将四元数转换为 4x4 旋转矩阵。 + +**返回：** `Matrix4x4` - 旋转矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion rot = ...; +Matrix4 mat = rot.ToMatrix4x4(); +``` diff --git a/docs/api/math/ray/getpoint.md b/docs/api/math/ray/getpoint.md new file mode 100644 index 00000000..5860f771 --- /dev/null +++ b/docs/api/math/ray/getpoint.md @@ -0,0 +1,22 @@ +# Ray::GetPoint + +```cpp +Vector3 GetPoint(float t) const +``` + +获取射线上指定距离处的点。 + +**参数：** +- `t` - 沿射线方向的参数距离 + +**返回：** `Vector3` - 射线上的点 `origin + direction * t` + +**复杂度：** O(1) + +**示例：** + +```cpp +Ray ray(cameraPosition, mouseRayDir.Normalized()); +float t = 100.0f; +Vector3 point = ray.GetPoint(t); // 沿射线方向 100 单位处的点 +``` diff --git a/docs/api/math/ray/intersects-box.md b/docs/api/math/ray/intersects-box.md new file mode 100644 index 00000000..9a7fb9c3 --- /dev/null +++ b/docs/api/math/ray/intersects-box.md @@ -0,0 +1,27 @@ +# Ray::Intersects (box) + +```cpp +bool Intersects(const Box& box, float& t) const +``` + +检测射线是否与 OBB（有向包围盒）相交。 + +**参数：** +- `box` - 要检测的 OBB 盒体 +- `t` - 输出交点的参数距离 + +**返回：** `bool` - 相交返回 true，否则返回 false + +**复杂度：** O(1) + +**示例：** + +```cpp +Ray ray(cameraPosition, rayDirection); +Box colliderBox = object.GetWorldBox(); +float t; +if (ray.Intersects(colliderBox, t)) { + Vector3 hitPoint = ray.GetPoint(t); + // 处理命中 +} +``` diff --git a/docs/api/math/ray/intersects-plane.md b/docs/api/math/ray/intersects-plane.md new file mode 100644 index 00000000..9a2a91ee --- /dev/null +++ b/docs/api/math/ray/intersects-plane.md @@ -0,0 +1,27 @@ +# Ray::Intersects (plane) + +```cpp +bool Intersects(const Plane& plane, float& t) const +``` + +检测射线是否与平面相交。 + +**参数：** +- `plane` - 要检测的平面 +- `t` - 输出交点的参数距离 + +**返回：** `bool` - 相交返回 true（射线朝向平面），否则返回 false + +**复杂度：** O(1) + +**示例：** + +```cpp +Ray ray(cameraPosition, rayDirection); +Plane groundPlane = Plane::FromNormalAndPoint(Vector3::Up(), Vector3::Zero()); +float t; +if (ray.Intersects(groundPlane, t)) { + Vector3 hitPoint = ray.GetPoint(t); + // 射线命中地面 +} +``` diff --git a/docs/api/math/ray/intersects-sphere.md b/docs/api/math/ray/intersects-sphere.md new file mode 100644 index 00000000..400624c6 --- /dev/null +++ b/docs/api/math/ray/intersects-sphere.md @@ -0,0 +1,26 @@ +# Ray::Intersects (sphere) + +```cpp +bool Intersects(const Sphere& sphere, float& t) const +``` + +检测射线是否与球体相交。 + +**参数：** +- `sphere` - 要检测的球体 +- `t` - 输出最近交点的参数距离 + +**返回：** `bool` - 相交返回 true，否则返回 false + +**复杂度：** O(1) + +**示例：** + +```cpp +Ray ray(cameraPosition, rayDirection); +float t; +if (ray.Intersects(sphere, t)) { + Vector3 hitPoint = ray.GetPoint(t); + // 处理命中 +} +``` diff --git a/docs/api/math/ray/ray.md b/docs/api/math/ray/ray.md new file mode 100644 index 00000000..969d10e3 --- /dev/null +++ b/docs/api/math/ray/ray.md @@ -0,0 +1,44 @@ +# Ray + +3D 射线结构体，用于光线投射和拾取。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Ray { + Vector3 origin; // 射线起点 + Vector3 direction; // 归一化方向 + + Ray() = default; + Ray(const Vector3& origin, const Vector3& direction); + + Vector3 GetPoint(float t) const; + bool Intersects(const Sphere& sphere, float& t) const; + bool Intersects(const Box& box, float& t) const; + bool Intersects(const Plane& plane, float& t) const; +}; +``` + +## 构造函数 + +| 方法 | 描述 | +|------|------| +| `Ray()` | 默认构造 | +| `Ray(origin, direction)` | 从起点和方向构造 | + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [GetPoint(t)](getpoint.md) | `Vector3` | 获取射线上 t 距离处的点 | +| [Intersects(sphere, t)](intersects-sphere.md) | `bool` | 与球体相交，输出距离 t | +| [Intersects(box, t)](intersects-box.md) | `bool` | 与 OBB 相交，输出距离 t | +| [Intersects(plane, t)](intersects-plane.md) | `bool` | 与平面相交，输出距离 t | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/rect/contains-float.md b/docs/api/math/rect/contains-float.md new file mode 100644 index 00000000..f6e14885 --- /dev/null +++ b/docs/api/math/rect/contains-float.md @@ -0,0 +1,24 @@ +# Rect::Contains (float) + +```cpp +bool Contains(float px, float py) const +``` + +检测浮点坐标点是否在矩形内。 + +**参数：** +- `px` - 点的 x 坐标 +- `py` - 点的 y 坐标 + +**返回：** `bool` - 点在矩形内（包含边界）返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect screenRect(0.0f, 0.0f, 1920.0f, 1080.0f); +if (screenRect.Contains(mouseX, mouseY)) { + // 鼠标在屏幕矩形内 +} +``` diff --git a/docs/api/math/rect/contains-vector2.md b/docs/api/math/rect/contains-vector2.md new file mode 100644 index 00000000..69367899 --- /dev/null +++ b/docs/api/math/rect/contains-vector2.md @@ -0,0 +1,24 @@ +# Rect::Contains (Vector2) + +```cpp +bool Contains(const Vector2& point) const +``` + +检测 Vector2 点是否在矩形内。 + +**参数：** +- `point` - 要检测的二维点 + +**返回：** `bool` - 点在矩形内（包含边界）返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect(0.0f, 0.0f, 100.0f, 100.0f); +Vector2 point(50.0f, 50.0f); +if (rect.Contains(point)) { + // 点在矩形内 +} +``` diff --git a/docs/api/math/rect/getbottom.md b/docs/api/math/rect/getbottom.md new file mode 100644 index 00000000..090fe948 --- /dev/null +++ b/docs/api/math/rect/getbottom.md @@ -0,0 +1,18 @@ +# Rect::GetBottom + +```cpp +float GetBottom() const +``` + +获取矩形下边界。 + +**返回：** `float` - 下边界坐标 (y + height) + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect(10.0f, 20.0f, 100.0f, 50.0f); +float bottom = rect.GetBottom(); // 70.0f +``` diff --git a/docs/api/math/rect/getcenter.md b/docs/api/math/rect/getcenter.md new file mode 100644 index 00000000..7c31bb50 --- /dev/null +++ b/docs/api/math/rect/getcenter.md @@ -0,0 +1,18 @@ +# Rect::GetCenter + +```cpp +Vector2 GetCenter() const +``` + +获取矩形中心点。 + +**返回：** `Vector2` - 中心点坐标 + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect(10.0f, 20.0f, 100.0f, 50.0f); +Vector2 center = rect.GetCenter(); // (60.0f, 45.0f) +``` diff --git a/docs/api/math/rect/getleft.md b/docs/api/math/rect/getleft.md new file mode 100644 index 00000000..0c7ec2e5 --- /dev/null +++ b/docs/api/math/rect/getleft.md @@ -0,0 +1,18 @@ +# Rect::GetLeft + +```cpp +float GetLeft() const +``` + +获取矩形左边界。 + +**返回：** `float` - 左边界坐标 (x) + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect(10.0f, 20.0f, 100.0f, 50.0f); +float left = rect.GetLeft(); // 10.0f +``` diff --git a/docs/api/math/rect/getposition.md b/docs/api/math/rect/getposition.md new file mode 100644 index 00000000..09fa66b5 --- /dev/null +++ b/docs/api/math/rect/getposition.md @@ -0,0 +1,18 @@ +# Rect::GetPosition + +```cpp +Vector2 GetPosition() const +``` + +获取矩形左上角位置。 + +**返回：** `Vector2` - 位置向量 (x, y) + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect(10.0f, 20.0f, 100.0f, 50.0f); +Vector2 pos = rect.GetPosition(); // (10.0f, 20.0f) +``` diff --git a/docs/api/math/rect/getright.md b/docs/api/math/rect/getright.md new file mode 100644 index 00000000..f856094b --- /dev/null +++ b/docs/api/math/rect/getright.md @@ -0,0 +1,18 @@ +# Rect::GetRight + +```cpp +float GetRight() const +``` + +获取矩形右边界。 + +**返回：** `float` - 右边界坐标 (x + width) + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect(10.0f, 20.0f, 100.0f, 50.0f); +float right = rect.GetRight(); // 110.0f +``` diff --git a/docs/api/math/rect/getsize.md b/docs/api/math/rect/getsize.md new file mode 100644 index 00000000..76ff5223 --- /dev/null +++ b/docs/api/math/rect/getsize.md @@ -0,0 +1,18 @@ +# Rect::GetSize + +```cpp +Vector2 GetSize() const +``` + +获取矩形尺寸。 + +**返回：** `Vector2` - 尺寸向量 (width, height) + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect(10.0f, 20.0f, 100.0f, 50.0f); +Vector2 size = rect.GetSize(); // (100.0f, 50.0f) +``` diff --git a/docs/api/math/rect/gettop.md b/docs/api/math/rect/gettop.md new file mode 100644 index 00000000..93a370f9 --- /dev/null +++ b/docs/api/math/rect/gettop.md @@ -0,0 +1,18 @@ +# Rect::GetTop + +```cpp +float GetTop() const +``` + +获取矩形上边界。 + +**返回：** `float` - 上边界坐标 (y) + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect(10.0f, 20.0f, 100.0f, 50.0f); +float top = rect.GetTop(); // 20.0f +``` diff --git a/docs/api/math/rect/intersect.md b/docs/api/math/rect/intersect.md new file mode 100644 index 00000000..f3574fe1 --- /dev/null +++ b/docs/api/math/rect/intersect.md @@ -0,0 +1,23 @@ +# Rect::Intersect + +```cpp +static Rect Intersect(const Rect& a, const Rect& b) +``` + +计算两矩形的交集区域。 + +**参数：** +- `a` - 第一个矩形 +- `b` - 第二个矩形 + +**返回：** `Rect` - 两矩形的交集，若无交集则返回零尺寸矩形 + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rectA(0.0f, 0.0f, 100.0f, 100.0f); +Rect rectB(50.0f, 50.0f, 100.0f, 100.0f); +Rect overlap = Rect::Intersect(rectA, rectB); // (50, 50, 50, 50) +``` diff --git a/docs/api/math/rect/intersects.md b/docs/api/math/rect/intersects.md new file mode 100644 index 00000000..ffa50098 --- /dev/null +++ b/docs/api/math/rect/intersects.md @@ -0,0 +1,24 @@ +# Rect::Intersects + +```cpp +bool Intersects(const Rect& other) const +``` + +检测两矩形是否相交。 + +**参数：** +- `other` - 另一个矩形 + +**返回：** `bool` - 两矩形相交返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rectA(0.0f, 0.0f, 100.0f, 100.0f); +Rect rectB(50.0f, 50.0f, 100.0f, 100.0f); +if (rectA.Intersects(rectB)) { + // 两矩形相交 +} +``` diff --git a/docs/api/math/rect/rect-overview.md b/docs/api/math/rect/rect-overview.md new file mode 100644 index 00000000..9df7429f --- /dev/null +++ b/docs/api/math/rect/rect-overview.md @@ -0,0 +1,69 @@ +# Rect + +浮点矩形结构体，用于 2D 区域表示。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Rect { + float x = 0.0f; // 左边界 + float y = 0.0f; // 上边界 + float width = 0.0f; + float height = 0.0f; + + Rect() = default; + Rect(float x, float y, float w, float h) : x(x), y(y), width(w), height(h) {} +}; +``` + +## 构造函数 + +| 方法 | 描述 | +|------|------| +| `Rect()` | 默认构造，初始化为零 | +| `Rect(x, y, w, h)` | 从坐标和尺寸构造 | + +## 边界访问 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [GetLeft()](getleft.md) | `float` | 左边界 (x) | +| [GetRight()](getright.md) | `float` | 右边界 (x + width) | +| [GetTop()](gettop.md) | `float` | 上边界 (y) | +| [GetBottom()](getbottom.md) | `float` | 下边界 (y + height) | +| [GetPosition()](getposition.md) | `Vector2` | 左上角位置 (x, y) | +| [GetSize()](getsize.md) | `Vector2` | 尺寸 (width, height) | +| [GetCenter()](getcenter.md) | `Vector2` | 中心点 | + +## 检测方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Contains(px, py)](contains-float.md) | `bool` | 浮点坐标点检测 | +| [Contains(point)](contains-vector2.md) | `bool` | Vector2 点检测 | +| [Intersects(other)](intersects.md) | `bool` | 与另一矩形相交 | + +## 静态方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Intersect(a, b)](intersect.md) | `Rect` | 两矩形交集 | +| [Union(a, b)](union.md) | `Rect` | 两矩形并集 | + +## 设置方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Set(x, y, w, h)](set.md) | `void` | 设置所有值 | +| [SetPosition(x, y)](setposition-float.md) | `void` | 设置位置 | +| [SetPosition(position)](setposition-vector2.md) | `void` | 设置位置 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Rect 模块总览 +- [RectInt](rectint.md) - 整数矩形版本 +- [Viewport](viewport.md) - 渲染视口 diff --git a/docs/api/math/rect/rect.md b/docs/api/math/rect/rect.md new file mode 100644 index 00000000..055eacec --- /dev/null +++ b/docs/api/math/rect/rect.md @@ -0,0 +1,17 @@ +# Rect / RectInt / Viewport + +2D 矩形和视口结构体。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 目录 + +- [Rect](rect.md) - 浮点矩形 +- [RectInt](rectint.md) - 整数矩形 +- [Viewport](viewport.md) - 渲染视口 + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/rect/rectint-contains.md b/docs/api/math/rect/rectint-contains.md new file mode 100644 index 00000000..1c013828 --- /dev/null +++ b/docs/api/math/rect/rectint-contains.md @@ -0,0 +1,24 @@ +# RectInt::Contains + +```cpp +bool Contains(int32_t px, int32_t py) const +``` + +检测整数坐标点是否在矩形内。 + +**参数：** +- `px` - 点的 x 坐标 +- `py` - 点的 y 坐标 + +**返回：** `bool` - 点在矩形内（包含边界）返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +RectInt rect(0, 0, 1920, 1080); +if (rect.Contains(pixelX, pixelY)) { + // 像素在矩形内 +} +``` diff --git a/docs/api/math/rect/rectint-getbottom.md b/docs/api/math/rect/rectint-getbottom.md new file mode 100644 index 00000000..a9d9c9b8 --- /dev/null +++ b/docs/api/math/rect/rectint-getbottom.md @@ -0,0 +1,18 @@ +# RectInt::GetBottom + +```cpp +int32_t GetBottom() const +``` + +获取矩形下边界。 + +**返回：** `int32_t` - 下边界坐标 (y + height) + +**复杂度：** O(1) + +**示例：** + +```cpp +RectInt rect(10, 20, 100, 50); +int32_t bottom = rect.GetBottom(); // 70 +``` diff --git a/docs/api/math/rect/rectint-getcenter.md b/docs/api/math/rect/rectint-getcenter.md new file mode 100644 index 00000000..1cf06d54 --- /dev/null +++ b/docs/api/math/rect/rectint-getcenter.md @@ -0,0 +1,18 @@ +# RectInt::GetCenter + +```cpp +Vector2 GetCenter() const +``` + +获取矩形中心点（转换为浮点）。 + +**返回：** `Vector2` - 中心点坐标 + +**复杂度：** O(1) + +**示例：** + +```cpp +RectInt rect(10, 20, 100, 50); +Vector2 center = rect.GetCenter(); // (60.0f, 45.0f) +``` diff --git a/docs/api/math/rect/rectint-getleft.md b/docs/api/math/rect/rectint-getleft.md new file mode 100644 index 00000000..b83ec9fb --- /dev/null +++ b/docs/api/math/rect/rectint-getleft.md @@ -0,0 +1,18 @@ +# RectInt::GetLeft + +```cpp +int32_t GetLeft() const +``` + +获取矩形左边界。 + +**返回：** `int32_t` - 左边界坐标 (x) + +**复杂度：** O(1) + +**示例：** + +```cpp +RectInt rect(10, 20, 100, 50); +int32_t left = rect.GetLeft(); // 10 +``` diff --git a/docs/api/math/rect/rectint-getposition.md b/docs/api/math/rect/rectint-getposition.md new file mode 100644 index 00000000..a4094970 --- /dev/null +++ b/docs/api/math/rect/rectint-getposition.md @@ -0,0 +1,18 @@ +# RectInt::GetPosition + +```cpp +Vector2 GetPosition() const +``` + +获取矩形左上角位置（转换为浮点）。 + +**返回：** `Vector2` - 位置向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +RectInt rect(10, 20, 100, 50); +Vector2 pos = rect.GetPosition(); // (10.0f, 20.0f) +``` diff --git a/docs/api/math/rect/rectint-getright.md b/docs/api/math/rect/rectint-getright.md new file mode 100644 index 00000000..390ea845 --- /dev/null +++ b/docs/api/math/rect/rectint-getright.md @@ -0,0 +1,18 @@ +# RectInt::GetRight + +```cpp +int32_t GetRight() const +``` + +获取矩形右边界。 + +**返回：** `int32_t` - 右边界坐标 (x + width) + +**复杂度：** O(1) + +**示例：** + +```cpp +RectInt rect(10, 20, 100, 50); +int32_t right = rect.GetRight(); // 110 +``` diff --git a/docs/api/math/rect/rectint-getsize.md b/docs/api/math/rect/rectint-getsize.md new file mode 100644 index 00000000..f372cb7e --- /dev/null +++ b/docs/api/math/rect/rectint-getsize.md @@ -0,0 +1,18 @@ +# RectInt::GetSize + +```cpp +Vector2 GetSize() const +``` + +获取矩形尺寸（转换为浮点）。 + +**返回：** `Vector2` - 尺寸向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +RectInt rect(10, 20, 100, 50); +Vector2 size = rect.GetSize(); // (100.0f, 50.0f) +``` diff --git a/docs/api/math/rect/rectint-gettop.md b/docs/api/math/rect/rectint-gettop.md new file mode 100644 index 00000000..f25dec8c --- /dev/null +++ b/docs/api/math/rect/rectint-gettop.md @@ -0,0 +1,18 @@ +# RectInt::GetTop + +```cpp +int32_t GetTop() const +``` + +获取矩形上边界。 + +**返回：** `int32_t` - 上边界坐标 (y) + +**复杂度：** O(1) + +**示例：** + +```cpp +RectInt rect(10, 20, 100, 50); +int32_t top = rect.GetTop(); // 20 +``` diff --git a/docs/api/math/rect/rectint-intersects.md b/docs/api/math/rect/rectint-intersects.md new file mode 100644 index 00000000..dc57b5cf --- /dev/null +++ b/docs/api/math/rect/rectint-intersects.md @@ -0,0 +1,24 @@ +# RectInt::Intersects + +```cpp +bool Intersects(const RectInt& other) const +``` + +检测两整数矩形是否相交。 + +**参数：** +- `other` - 另一个整数矩形 + +**返回：** `bool` - 两矩形相交返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +RectInt rectA(0, 0, 100, 100); +RectInt rectB(50, 50, 100, 100); +if (rectA.Intersects(rectB)) { + // 两矩形相交 +} +``` diff --git a/docs/api/math/rect/rectint.md b/docs/api/math/rect/rectint.md new file mode 100644 index 00000000..dda9548d --- /dev/null +++ b/docs/api/math/rect/rectint.md @@ -0,0 +1,53 @@ +# RectInt + +整数矩形结构体，用于像素级 2D 区域表示。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct RectInt { + int32_t x = 0; + int32_t y = 0; + int32_t width = 0; + int32_t height = 0; + + RectInt() = default; + RectInt(int32_t x, int32_t y, int32_t w, int32_t h); +}; +``` + +## 构造函数 + +| 方法 | 描述 | +|------|------| +| `RectInt()` | 默认构造 | +| `RectInt(x, y, w, h)` | 从整数坐标和尺寸构造 | + +## 边界访问 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [GetLeft()](rectint-getleft.md) | `int32_t` | 左边界 | +| [GetRight()](rectint-getright.md) | `int32_t` | 右边界 | +| [GetTop()](rectint-gettop.md) | `int32_t` | 上边界 | +| [GetBottom()](rectint-getbottom.md) | `int32_t` | 下边界 | +| [GetPosition()](rectint-getposition.md) | `Vector2` | 位置（转换为浮点） | +| [GetSize()](rectint-getsize.md) | `Vector2` | 尺寸（转换为浮点） | +| [GetCenter()](rectint-getcenter.md) | `Vector2` | 中心点 | + +## 检测方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Contains(px, py)](rectint-contains.md) | `bool` | 整数坐标点检测 | +| [Intersects(other)](rectint-intersects.md) | `bool` | 与另一矩形相交 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Rect 模块总览 +- [Rect](rect-overview.md) - 浮点矩形版本 +- [Viewport](viewport.md) - 渲染视口 diff --git a/docs/api/math/rect/set.md b/docs/api/math/rect/set.md new file mode 100644 index 00000000..641000c7 --- /dev/null +++ b/docs/api/math/rect/set.md @@ -0,0 +1,24 @@ +# Rect::Set + +```cpp +void Set(float newX, float newY, float newWidth, float newHeight) +``` + +设置矩形所有属性。 + +**参数：** +- `newX` - 新的左边界 +- `newY` - 新的上边界 +- `newWidth` - 新的宽度 +- `newHeight` - 新的高度 + +**返回：** `void` + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect; +rect.Set(10.0f, 20.0f, 100.0f, 50.0f); +``` diff --git a/docs/api/math/rect/setposition-float.md b/docs/api/math/rect/setposition-float.md new file mode 100644 index 00000000..51f9695c --- /dev/null +++ b/docs/api/math/rect/setposition-float.md @@ -0,0 +1,22 @@ +# Rect::SetPosition (float) + +```cpp +void SetPosition(float newX, float newY) +``` + +设置矩形位置（保持尺寸不变）。 + +**参数：** +- `newX` - 新的左边界 +- `newY` - 新的上边界 + +**返回：** `void` + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect(0.0f, 0.0f, 100.0f, 50.0f); +rect.SetPosition(50.0f, 30.0f); // rect 现在为 (50, 30, 100, 50) +``` diff --git a/docs/api/math/rect/setposition-vector2.md b/docs/api/math/rect/setposition-vector2.md new file mode 100644 index 00000000..89f4020b --- /dev/null +++ b/docs/api/math/rect/setposition-vector2.md @@ -0,0 +1,21 @@ +# Rect::SetPosition (Vector2) + +```cpp +void SetPosition(const Vector2& position) +``` + +用 Vector2 设置矩形位置（保持尺寸不变）。 + +**参数：** +- `position` - 新的位置向量 + +**返回：** `void` + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rect(0.0f, 0.0f, 100.0f, 50.0f); +rect.SetPosition(Vector2(50.0f, 30.0f)); // rect 现在为 (50, 30, 100, 50) +``` diff --git a/docs/api/math/rect/union.md b/docs/api/math/rect/union.md new file mode 100644 index 00000000..acaca229 --- /dev/null +++ b/docs/api/math/rect/union.md @@ -0,0 +1,23 @@ +# Rect::Union + +```cpp +static Rect Union(const Rect& a, const Rect& b) +``` + +计算包含两矩形的最小矩形。 + +**参数：** +- `a` - 第一个矩形 +- `b` - 第二个矩形 + +**返回：** `Rect` - 包含两矩形的最小外接矩形 + +**复杂度：** O(1) + +**示例：** + +```cpp +Rect rectA(0.0f, 0.0f, 50.0f, 50.0f); +Rect rectB(100.0f, 100.0f, 50.0f, 50.0f); +Rect combined = Rect::Union(rectA, rectB); // (0, 0, 150, 150) +``` diff --git a/docs/api/math/rect/viewport-getaspectratio.md b/docs/api/math/rect/viewport-getaspectratio.md new file mode 100644 index 00000000..e1a9355f --- /dev/null +++ b/docs/api/math/rect/viewport-getaspectratio.md @@ -0,0 +1,18 @@ +# Viewport::GetAspectRatio + +```cpp +float GetAspectRatio() const +``` + +获取视口宽高比。 + +**返回：** `float` - 宽高比 (width / height)，height 为 0 时返回 0.0f + +**复杂度：** O(1) + +**示例：** + +```cpp +Viewport viewport(0, 0, 1920, 1080); +float aspect = viewport.GetAspectRatio(); // 1.777... (16:9) +``` diff --git a/docs/api/math/rect/viewport-getrect.md b/docs/api/math/rect/viewport-getrect.md new file mode 100644 index 00000000..274b8be1 --- /dev/null +++ b/docs/api/math/rect/viewport-getrect.md @@ -0,0 +1,18 @@ +# Viewport::GetRect + +```cpp +Rect GetRect() const +``` + +将视口转换为 Rect。 + +**返回：** `Rect` - 对应的矩形 (x, y, width, height)，不包含深度范围 + +**复杂度：** O(1) + +**示例：** + +```cpp +Viewport viewport(0, 0, 1920, 1080, 0.0f, 1.0f); +Rect rect = viewport.GetRect(); // (0, 0, 1920, 1080) +``` diff --git a/docs/api/math/rect/viewport.md b/docs/api/math/rect/viewport.md new file mode 100644 index 00000000..b3a45e0c --- /dev/null +++ b/docs/api/math/rect/viewport.md @@ -0,0 +1,45 @@ +# Viewport + +渲染视口结构体，用于屏幕到归一化坐标的映射。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Viewport { + float x = 0.0f; + float y = 0.0f; + float width = 0.0f; + float height = 0.0f; + float minDepth = 0.0f; + float maxDepth = 1.0f; + + Viewport() = default; + Viewport(float x, float y, float w, float h); + Viewport(float x, float y, float w, float h, float minD, float maxD); +}; +``` + +## 构造函数 + +| 方法 | 描述 | +|------|------| +| `Viewport()` | 默认构造 | +| `Viewport(x, y, w, h)` | 2D 视口 | +| `Viewport(x, y, w, h, minD, maxD)` | 带深度范围的 3D 视口 | + +## 方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [GetAspectRatio()](viewport-getaspectratio.md) | `float` | 宽高比 (width / height) | +| [GetRect()](viewport-getrect.md) | `Rect` | 转换为 Rect | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Rect 模块总览 +- [Rect](rect-overview.md) - 浮点矩形 +- [RectInt](rectint.md) - 整数矩形 diff --git a/docs/api/math/sphere/contains.md b/docs/api/math/sphere/contains.md new file mode 100644 index 00000000..6e69e32e --- /dev/null +++ b/docs/api/math/sphere/contains.md @@ -0,0 +1,20 @@ +# Sphere::Contains + +```cpp +bool Contains(const Vector3& point) const +``` + +检测点是否在球体内（包括表面）。 + +**参数：** +- `point` - 要检测的点 + +**返回：** `bool` - true 表示点在球体内 + +**复杂度：** O(1) + +**示例：** + +```cpp +if (sphere.Contains(point)) { /* point inside */ } +``` diff --git a/docs/api/math/sphere/intersects.md b/docs/api/math/sphere/intersects.md new file mode 100644 index 00000000..d3d5ad57 --- /dev/null +++ b/docs/api/math/sphere/intersects.md @@ -0,0 +1,20 @@ +# Sphere::Intersects + +```cpp +bool Intersects(const Sphere& other) const +``` + +检测两个球体是否相交。 + +**参数：** +- `other` - 另一个球体 + +**返回：** `bool` - true 表示相交 + +**复杂度：** O(1) + +**示例：** + +```cpp +if (sphere.Intersects(other)) { /* collision */ } +``` diff --git a/docs/api/math/sphere/sphere.md b/docs/api/math/sphere/sphere.md new file mode 100644 index 00000000..b0bd94c1 --- /dev/null +++ b/docs/api/math/sphere/sphere.md @@ -0,0 +1,32 @@ +# Sphere + +3D 球体结构体。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Sphere { + Vector3 center = Vector3::Zero(); + float radius = 0.0f; +}; +``` + +## 构造函数 + +- `Sphere()` - 默认构造 +- `Sphere(const Vector3& center, float radius)` - 从中心和半径构造 + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Contains(point)](contains.md) | `bool` | 点是否在球体内 | +| [Intersects(other)](intersects.md) | `bool` | 与另一个球体相交 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/transform/inverse.md b/docs/api/math/transform/inverse.md new file mode 100644 index 00000000..8b4de547 --- /dev/null +++ b/docs/api/math/transform/inverse.md @@ -0,0 +1,17 @@ +# Transform::Inverse + +```cpp +Transform Inverse() const +``` + +返回变换的逆。 + +**返回：** `Transform` - 逆变换 + +**复杂度：** O(1) + +**示例：** + +```cpp +Transform inv = transform.Inverse(); +``` diff --git a/docs/api/math/transform/inversetransformdirection.md b/docs/api/math/transform/inversetransformdirection.md new file mode 100644 index 00000000..38968c1c --- /dev/null +++ b/docs/api/math/transform/inversetransformdirection.md @@ -0,0 +1,21 @@ +# Transform::InverseTransformDirection + +```cpp +Vector3 InverseTransformDirection(const Vector3& direction) const +``` + +对方向进行逆变换（包含缩放处理）。 + +**参数：** +- `direction` - 世界空间中的方向 + +**返回：** `Vector3` - 局部空间中的方向 + +**复杂度：** O(1) + +**示例：** + +```cpp +Transform t; +Vector3 localDir = t.InverseTransformDirection(worldDir); +``` diff --git a/docs/api/math/transform/inversetransformpoint.md b/docs/api/math/transform/inversetransformpoint.md new file mode 100644 index 00000000..733b1738 --- /dev/null +++ b/docs/api/math/transform/inversetransformpoint.md @@ -0,0 +1,21 @@ +# Transform::InverseTransformPoint + +```cpp +Vector3 InverseTransformPoint(const Vector3& point) const +``` + +对点进行逆变换。 + +**参数：** +- `point` - 世界空间中的点 + +**返回：** `Vector3` - 局部空间中的点 + +**复杂度：** O(1) + +**示例：** + +```cpp +Transform t; +Vector3 localPos = t.InverseTransformPoint(worldPos); +``` diff --git a/docs/api/math/transform/tomatrix.md b/docs/api/math/transform/tomatrix.md new file mode 100644 index 00000000..cfa9edde --- /dev/null +++ b/docs/api/math/transform/tomatrix.md @@ -0,0 +1,19 @@ +# Transform::ToMatrix + +```cpp +Matrix4 ToMatrix() const +``` + +将变换转换为 4x4 变换矩阵。 + +**返回：** `Matrix4` - TRS 变换矩阵 + +**复杂度：** O(1) + +**示例：** + +```cpp +Transform t; +t.position = Vector3(1.0f, 2.0f, 3.0f); +Matrix4 matrix = t.ToMatrix(); +``` diff --git a/docs/api/math/transform/transform.md b/docs/api/math/transform/transform.md new file mode 100644 index 00000000..2519a2e4 --- /dev/null +++ b/docs/api/math/transform/transform.md @@ -0,0 +1,44 @@ +# Transform + +3D 变换结构体，包含位置、旋转和缩放，用于层次化变换。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## Space 枚举 + +```cpp +enum class Space { Self, World }; +``` + +## 结构体定义 + +```cpp +struct Transform { + Vector3 position = Vector3::Zero(); + Quaternion rotation = Quaternion::Identity(); + Vector3 scale = Vector3::One(); +}; +``` + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [ToMatrix()](tomatrix.md) | `Matrix4` | 转换为 4x4 变换矩阵 | +| [Inverse()](inverse.md) | `Transform` | 逆变换 | +| `operator*(Transform, Transform)` | `Transform` | 组合变换 | + +### 空间变换 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [TransformPoint(point)](transformpoint.md) | `Vector3` | 变换点（带平移） | +| [TransformDirection(direction)](transformdirection.md) | `Vector3` | 变换方向（包含旋转和缩放） | +| [InverseTransformPoint(point)](inversetransformpoint.md) | `Vector3` | 逆变换点 | +| [InverseTransformDirection(direction)](inversetransformdirection.md) | `Vector3` | 逆变换方向 | + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/transform/transformdirection.md b/docs/api/math/transform/transformdirection.md new file mode 100644 index 00000000..e371d00c --- /dev/null +++ b/docs/api/math/transform/transformdirection.md @@ -0,0 +1,22 @@ +# Transform::TransformDirection + +```cpp +Vector3 TransformDirection(const Vector3& direction) const +``` + +变换方向（仅旋转，包含缩放）。 + +**参数：** +- `direction` - 要变换的方向 + +**返回：** `Vector3` - 变换后的方向 + +**复杂度：** O(1) + +**示例：** + +```cpp +Transform t; +Vector3 localDir(1.0f, 0.0f, 0.0f); +Vector3 worldDir = t.TransformDirection(localDir); +``` diff --git a/docs/api/math/transform/transformpoint.md b/docs/api/math/transform/transformpoint.md new file mode 100644 index 00000000..46d9ec10 --- /dev/null +++ b/docs/api/math/transform/transformpoint.md @@ -0,0 +1,22 @@ +# Transform::TransformPoint + +```cpp +Vector3 TransformPoint(const Vector3& point) const +``` + +变换点（包含位置、旋转和缩放）。 + +**参数：** +- `point` - 要变换的点 + +**返回：** `Vector3` - 变换后的点 + +**复杂度：** O(1) + +**示例：** + +```cpp +Transform t; +Vector3 localPos(1.0f, 0.0f, 0.0f); +Vector3 worldPos = t.TransformPoint(localPos); +``` diff --git a/docs/api/math/vector2/cross.md b/docs/api/math/vector2/cross.md new file mode 100644 index 00000000..779916fb --- /dev/null +++ b/docs/api/math/vector2/cross.md @@ -0,0 +1,23 @@ +# Vector2::Cross + +```cpp +static float Cross(const Vector2& a, const Vector2& b) +``` + +计算两个 2D 向量的叉积（返回标量）。结果为正值表示 b 在 a 的逆时针方向。 + +**参数：** +- `a` - 第一个向量 +- `b` - 第二个向量 + +**返回：** `float` - 叉积结果 a.x * b.y - a.y * b.x + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 a(1.0f, 0.0f); +Vector2 b(0.0f, 1.0f); +float cross = Vector2::Cross(a, b); // 1.0f (逆时针) +``` diff --git a/docs/api/math/vector2/dot.md b/docs/api/math/vector2/dot.md new file mode 100644 index 00000000..d2159f50 --- /dev/null +++ b/docs/api/math/vector2/dot.md @@ -0,0 +1,23 @@ +# Vector2::Dot + +```cpp +static float Dot(const Vector2& a, const Vector2& b) +``` + +计算两个 2D 向量的点积。 + +**参数：** +- `a` - 第一个向量 +- `b` - 第二个向量 + +**返回：** `float` - 点积结果 a.x * b.x + a.y * b.y + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 a(1.0f, 0.0f); +Vector2 b(0.0f, 1.0f); +float dot = Vector2::Dot(a, b); // 0.0f +``` diff --git a/docs/api/math/vector2/down.md b/docs/api/math/vector2/down.md new file mode 100644 index 00000000..3481b338 --- /dev/null +++ b/docs/api/math/vector2/down.md @@ -0,0 +1,17 @@ +# Vector2::Down + +```cpp +static Vector2 Down() +``` + +返回下方向向量 (0, -1)。 + +**返回：** `Vector2` - 值为 (0, -1) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 down = Vector2::Down(); +``` diff --git a/docs/api/math/vector2/left.md b/docs/api/math/vector2/left.md new file mode 100644 index 00000000..692d318b --- /dev/null +++ b/docs/api/math/vector2/left.md @@ -0,0 +1,17 @@ +# Vector2::Left + +```cpp +static Vector2 Left() +``` + +返回左方向向量 (-1, 0)。 + +**返回：** `Vector2` - 值为 (-1, 0) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 left = Vector2::Left(); +``` diff --git a/docs/api/math/vector2/lerp.md b/docs/api/math/vector2/lerp.md new file mode 100644 index 00000000..08c66512 --- /dev/null +++ b/docs/api/math/vector2/lerp.md @@ -0,0 +1,24 @@ +# Vector2::Lerp + +```cpp +static Vector2 Lerp(const Vector2& a, const Vector2& b, float t) +``` + +在线性插值两个向量之间。参数 t 会在 [0, 1] 范围内被限制。 + +**参数：** +- `a` - 起始向量 +- `b` - 结束向量 +- `t` - 插值因子，0 返回 a，1 返回 b + +**返回：** `Vector2` - 插值结果 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 start(0.0f, 0.0f); +Vector2 end(10.0f, 10.0f); +Vector2 mid = Vector2::Lerp(start, end, 0.5f); // (5.0f, 5.0f) +``` diff --git a/docs/api/math/vector2/magnitude.md b/docs/api/math/vector2/magnitude.md new file mode 100644 index 00000000..227d3d31 --- /dev/null +++ b/docs/api/math/vector2/magnitude.md @@ -0,0 +1,25 @@ +# Vector2::Magnitude + +```cpp +static float Magnitude(const Vector2& v) +float Magnitude() const +``` + +计算向量的长度（欧几里得范数）。 + +**静态版本参数：** +- `v` - 要计算长度的向量 + +**实例版本：** 计算当前向量的长度。 + +**返回：** `float` - 向量长度 sqrt(x * x + y * y) + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 v(3.0f, 4.0f); +float len = v.Magnitude(); // 5.0f +float len2 = Vector2::Magnitude(v); // 5.0f +``` diff --git a/docs/api/math/vector2/movetowards.md b/docs/api/math/vector2/movetowards.md new file mode 100644 index 00000000..db0f47a6 --- /dev/null +++ b/docs/api/math/vector2/movetowards.md @@ -0,0 +1,24 @@ +# Vector2::MoveTowards + +```cpp +static Vector2 MoveTowards(const Vector2& current, const Vector2& target, float maxDistance) +``` + +将当前向量朝目标向量移动指定距离。如果距离已小于 maxDistance，则直接返回目标。 + +**参数：** +- `current` - 当前向量 +- `target` - 目标向量 +- `maxDistance` - 最大移动距离 + +**返回：** `Vector2` - 移动后的位置 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 current(0.0f, 0.0f); +Vector2 target(10.0f, 0.0f); +Vector2 moved = Vector2::MoveTowards(current, target, 3.0f); // (3.0f, 0.0f) +``` diff --git a/docs/api/math/vector2/normalize.md b/docs/api/math/vector2/normalize.md new file mode 100644 index 00000000..3df54f1b --- /dev/null +++ b/docs/api/math/vector2/normalize.md @@ -0,0 +1,20 @@ +# Vector2::Normalize + +```cpp +static Vector2 Normalize(const Vector2& v) +``` + +将向量归一化为单位长度。如果向量长度接近零，返回零向量。 + +**参数：** +- `v` - 要归一化的向量 + +**返回：** `Vector2` - 归一化后的单位向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 dir = Vector2::Normalize(Vector2(3.0f, 4.0f)); // (0.6f, 0.8f) +``` diff --git a/docs/api/math/vector2/normalized.md b/docs/api/math/vector2/normalized.md new file mode 100644 index 00000000..1e62dac1 --- /dev/null +++ b/docs/api/math/vector2/normalized.md @@ -0,0 +1,18 @@ +# Vector2::Normalized + +```cpp +Vector2 Normalized() const +``` + +返回当前向量的归一化副本（单位长度）。不修改原向量。 + +**返回：** `Vector2` - 归一化后的向量副本 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 v(3.0f, 4.0f); +Vector2 unit = v.Normalized(); // (0.6f, 0.8f), v 保持不变 +``` diff --git a/docs/api/math/vector2/one.md b/docs/api/math/vector2/one.md new file mode 100644 index 00000000..bbce99f6 --- /dev/null +++ b/docs/api/math/vector2/one.md @@ -0,0 +1,17 @@ +# Vector2::One + +```cpp +static Vector2 One() +``` + +返回单位向量 (1, 1)。 + +**返回：** `Vector2` - 值为 (1, 1) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 unit = Vector2::One(); +``` diff --git a/docs/api/math/vector2/right.md b/docs/api/math/vector2/right.md new file mode 100644 index 00000000..89a8561b --- /dev/null +++ b/docs/api/math/vector2/right.md @@ -0,0 +1,17 @@ +# Vector2::Right + +```cpp +static Vector2 Right() +``` + +返回右方向向量 (1, 0)。 + +**返回：** `Vector2` - 值为 (1, 0) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 right = Vector2::Right(); +``` diff --git a/docs/api/math/vector2/sqrmagnitude.md b/docs/api/math/vector2/sqrmagnitude.md new file mode 100644 index 00000000..15183a20 --- /dev/null +++ b/docs/api/math/vector2/sqrmagnitude.md @@ -0,0 +1,25 @@ +# Vector2::SqrMagnitude + +```cpp +static float SqrMagnitude(const Vector2& v) +float SqrMagnitude() const +``` + +计算向量长度的平方。比 Magnitude 更快，避免了开方运算。 + +**静态版本参数：** +- `v` - 要计算长度的向量 + +**实例版本：** 计算当前向量的长度平方。 + +**返回：** `float` - 向量长度平方 x * x + y * y + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 v(3.0f, 4.0f); +float sqlen = v.SqrMagnitude(); // 25.0f +float sqlen2 = Vector2::SqrMagnitude(v); // 25.0f +``` diff --git a/docs/api/math/vector2/up.md b/docs/api/math/vector2/up.md new file mode 100644 index 00000000..bf7c6975 --- /dev/null +++ b/docs/api/math/vector2/up.md @@ -0,0 +1,17 @@ +# Vector2::Up + +```cpp +static Vector2 Up() +``` + +返回上方向向量 (0, 1)。 + +**返回：** `Vector2` - 值为 (0, 1) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 up = Vector2::Up(); +``` diff --git a/docs/api/math/vector2/vector2.md b/docs/api/math/vector2/vector2.md new file mode 100644 index 00000000..95a904e9 --- /dev/null +++ b/docs/api/math/vector2/vector2.md @@ -0,0 +1,57 @@ +# Vector2 + +2D 向量结构体，用于表示 2D 空间中的点、方向或颜色。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Vector2 { + float x = 0.0f; + float y = 0.0f; +}; +``` + +## 静态工厂方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Zero()](zero.md) | `Vector2` | 返回 (0, 0) | +| [One()](one.md) | `Vector2` | 返回 (1, 1) | +| [Up()](up.md) | `Vector2` | 返回 (0, 1)，上方向 | +| [Down()](down.md) | `Vector2` | 返回 (0, -1)，下方向 | +| [Right()](right.md) | `Vector2` | 返回 (1, 0)，右方向 | +| [Left()](left.md) | `Vector2` | 返回 (-1, 0)，左方向 | + +## 静态数学方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Dot(a, b)](dot.md) | `float` | 点积 | +| [Cross(a, b)](cross.md) | `float` | 2D 叉积（返回标量） | +| [Normalize(v)](normalize.md) | `Vector2` | 归一化向量 | +| [Magnitude(v)](magnitude.md) | `float` | 向量长度 | +| [SqrMagnitude(v)](sqrmagnitude.md) | `float` | 长度平方（更快） | +| [Lerp(a, b, t)](lerp.md) | `Vector2` | 线性插值 | +| [MoveTowards(current, target, maxDistance)](movetowards.md) | `Vector2` | 朝目标移动 | + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Magnitude()](magnitude.md) | `float` | 获取向量长度 | +| [SqrMagnitude()](sqrmagnitude.md) | `float` | 获取长度平方 | +| [Normalized()](normalized.md) | `Vector2` | 获取归一化副本 | + +## 运算符 + +- 算术: `+`, `-`, `*` (scalar), `/` (scalar) +- 复合赋值: `+=`, `-=`, `*=`, `/=` +- 比较: `==`, `!=` + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/vector2/zero.md b/docs/api/math/vector2/zero.md new file mode 100644 index 00000000..72c11cda --- /dev/null +++ b/docs/api/math/vector2/zero.md @@ -0,0 +1,17 @@ +# Vector2::Zero + +```cpp +static Vector2 Zero() +``` + +返回零向量 (0, 0)。 + +**返回：** `Vector2` - 值为 (0, 0) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector2 origin = Vector2::Zero(); +``` diff --git a/docs/api/math/vector3/angle.md b/docs/api/math/vector3/angle.md new file mode 100644 index 00000000..b6cc2f2c --- /dev/null +++ b/docs/api/math/vector3/angle.md @@ -0,0 +1,23 @@ +# Vector3::Angle + +```cpp +static float Angle(const Vector3& from, const Vector3& to) +``` + +计算两个向量之间的夹角（以度为单位）。 + +**参数：** +- `from` - 起始向量 +- `to` - 目标向量 + +**返回：** `float` - 两向量之间的夹角（0-180度） + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 a(1.0f, 0.0f, 0.0f); +Vector3 b(0.0f, 1.0f, 0.0f); +float angle = Vector3::Angle(a, b); // 90.0f +``` diff --git a/docs/api/math/vector3/back.md b/docs/api/math/vector3/back.md new file mode 100644 index 00000000..f630c311 --- /dev/null +++ b/docs/api/math/vector3/back.md @@ -0,0 +1,17 @@ +# Vector3::Back + +```cpp +static Vector3 Back() +``` + +返回后方向向量 (0, 0, -1)。 + +**返回：** `Vector3` - 值为 (0, 0, -1) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 back = Vector3::Back(); +``` diff --git a/docs/api/math/vector3/cross.md b/docs/api/math/vector3/cross.md new file mode 100644 index 00000000..b7802671 --- /dev/null +++ b/docs/api/math/vector3/cross.md @@ -0,0 +1,23 @@ +# Vector3::Cross + +```cpp +static Vector3 Cross(const Vector3& a, const Vector3& b) +``` + +计算两个 3D 向量的叉积。结果向量同时垂直于 a 和 b。 + +**参数：** +- `a` - 第一个向量 +- `b` - 第二个向量 + +**返回：** `Vector3` - 叉积结果，垂直于 a 和 b 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 right(1.0f, 0.0f, 0.0f); +Vector3 up(0.0f, 1.0f, 0.0f); +Vector3 forward = Vector3::Cross(right, up); // (0, 0, 1) +``` diff --git a/docs/api/math/vector3/dot.md b/docs/api/math/vector3/dot.md new file mode 100644 index 00000000..91e0d8b3 --- /dev/null +++ b/docs/api/math/vector3/dot.md @@ -0,0 +1,23 @@ +# Vector3::Dot + +```cpp +static float Dot(const Vector3& a, const Vector3& b) +``` + +计算两个 3D 向量的点积。 + +**参数：** +- `a` - 第一个向量 +- `b` - 第二个向量 + +**返回：** `float` - 点积结果 a.x * b.x + a.y * b.y + a.z * b.z + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 a(1.0f, 0.0f, 0.0f); +Vector3 b(0.0f, 1.0f, 0.0f); +float dot = Vector3::Dot(a, b); // 0.0f +``` diff --git a/docs/api/math/vector3/down.md b/docs/api/math/vector3/down.md new file mode 100644 index 00000000..7b39dba4 --- /dev/null +++ b/docs/api/math/vector3/down.md @@ -0,0 +1,17 @@ +# Vector3::Down + +```cpp +static Vector3 Down() +``` + +返回下方向向量 (0, -1, 0)。 + +**返回：** `Vector3` - 值为 (0, -1, 0) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 down = Vector3::Down(); +``` diff --git a/docs/api/math/vector3/forward.md b/docs/api/math/vector3/forward.md new file mode 100644 index 00000000..ef19872b --- /dev/null +++ b/docs/api/math/vector3/forward.md @@ -0,0 +1,17 @@ +# Vector3::Forward + +```cpp +static Vector3 Forward() +``` + +返回前方向向量 (0, 0, 1)。 + +**返回：** `Vector3` - 值为 (0, 0, 1) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 forward = Vector3::Forward(); +``` diff --git a/docs/api/math/vector3/left.md b/docs/api/math/vector3/left.md new file mode 100644 index 00000000..b2f1173a --- /dev/null +++ b/docs/api/math/vector3/left.md @@ -0,0 +1,17 @@ +# Vector3::Left + +```cpp +static Vector3 Left() +``` + +返回左方向向量 (-1, 0, 0)。 + +**返回：** `Vector3` - 值为 (-1, 0, 0) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 left = Vector3::Left(); +``` diff --git a/docs/api/math/vector3/lerp.md b/docs/api/math/vector3/lerp.md new file mode 100644 index 00000000..dd59840e --- /dev/null +++ b/docs/api/math/vector3/lerp.md @@ -0,0 +1,24 @@ +# Vector3::Lerp + +```cpp +static Vector3 Lerp(const Vector3& a, const Vector3& b, float t) +``` + +在线性插值两个向量之间。参数 t 会在 [0, 1] 范围内被限制。 + +**参数：** +- `a` - 起始向量 +- `b` - 结束向量 +- `t` - 插值因子，0 返回 a，1 返回 b + +**返回：** `Vector3` - 插值结果 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 start(0.0f, 0.0f, 0.0f); +Vector3 end(10.0f, 10.0f, 10.0f); +Vector3 mid = Vector3::Lerp(start, end, 0.5f); // (5.0f, 5.0f, 5.0f) +``` diff --git a/docs/api/math/vector3/magnitude.md b/docs/api/math/vector3/magnitude.md new file mode 100644 index 00000000..c5c3e3fa --- /dev/null +++ b/docs/api/math/vector3/magnitude.md @@ -0,0 +1,25 @@ +# Vector3::Magnitude + +```cpp +static float Magnitude(const Vector3& v) +float Magnitude() const +``` + +计算向量的长度（欧几里得范数）。 + +**静态版本参数：** +- `v` - 要计算长度的向量 + +**实例版本：** 计算当前向量的长度。 + +**返回：** `float` - 向量长度 sqrt(x * x + y * y + z * z) + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(1.0f, 2.0f, 2.0f); +float len = v.Magnitude(); // 3.0f +float len2 = Vector3::Magnitude(v); // 3.0f +``` diff --git a/docs/api/math/vector3/movetowards.md b/docs/api/math/vector3/movetowards.md new file mode 100644 index 00000000..e1d3992d --- /dev/null +++ b/docs/api/math/vector3/movetowards.md @@ -0,0 +1,24 @@ +# Vector3::MoveTowards + +```cpp +static Vector3 MoveTowards(const Vector3& current, const Vector3& target, float maxDistance) +``` + +将当前向量朝目标向量移动指定距离。如果距离已小于 maxDistance，则直接返回目标。 + +**参数：** +- `current` - 当前向量 +- `target` - 目标向量 +- `maxDistance` - 最大移动距离 + +**返回：** `Vector3` - 移动后的位置 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 current(0.0f, 0.0f, 0.0f); +Vector3 target(10.0f, 0.0f, 0.0f); +Vector3 moved = Vector3::MoveTowards(current, target, 3.0f); // (3.0f, 0, 0) +``` diff --git a/docs/api/math/vector3/normalize.md b/docs/api/math/vector3/normalize.md new file mode 100644 index 00000000..b35d4365 --- /dev/null +++ b/docs/api/math/vector3/normalize.md @@ -0,0 +1,20 @@ +# Vector3::Normalize + +```cpp +static Vector3 Normalize(const Vector3& v) +``` + +将向量归一化为单位长度。如果向量长度接近零，返回零向量。 + +**参数：** +- `v` - 要归一化的向量 + +**返回：** `Vector3` - 归一化后的单位向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 dir = Vector3::Normalize(Vector3(3.0f, 4.0f, 0.0f)); // (0.6f, 0.8f, 0) +``` diff --git a/docs/api/math/vector3/normalized.md b/docs/api/math/vector3/normalized.md new file mode 100644 index 00000000..57f499d8 --- /dev/null +++ b/docs/api/math/vector3/normalized.md @@ -0,0 +1,18 @@ +# Vector3::Normalized + +```cpp +Vector3 Normalized() const +``` + +返回当前向量的归一化副本（单位长度）。不修改原向量。 + +**返回：** `Vector3` - 归一化后的向量副本 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(3.0f, 4.0f, 0.0f); +Vector3 unit = v.Normalized(); // (0.6f, 0.8f, 0), v 保持不变 +``` diff --git a/docs/api/math/vector3/one.md b/docs/api/math/vector3/one.md new file mode 100644 index 00000000..650c3d21 --- /dev/null +++ b/docs/api/math/vector3/one.md @@ -0,0 +1,17 @@ +# Vector3::One + +```cpp +static Vector3 One() +``` + +返回单位向量 (1, 1, 1)。 + +**返回：** `Vector3` - 值为 (1, 1, 1) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 unit = Vector3::One(); +``` diff --git a/docs/api/math/vector3/project.md b/docs/api/math/vector3/project.md new file mode 100644 index 00000000..dcff56cb --- /dev/null +++ b/docs/api/math/vector3/project.md @@ -0,0 +1,23 @@ +# Vector3::Project + +```cpp +static Vector3 Project(const Vector3& vector, const Vector3& onNormal) +``` + +将向量投影到法线向量上。 + +**参数：** +- `vector` - 要投影的向量 +- `onNormal` - 投影到的法线向量 + +**返回：** `Vector3` - 投影结果。如果法线长度为 0，返回零向量。 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(1.0f, 1.0f, 0.0f); +Vector3 normal(1.0f, 0.0f, 0.0f); +Vector3 projected = Vector3::Project(v, normal); // (1, 0, 0) +``` diff --git a/docs/api/math/vector3/projectonplane.md b/docs/api/math/vector3/projectonplane.md new file mode 100644 index 00000000..84747f04 --- /dev/null +++ b/docs/api/math/vector3/projectonplane.md @@ -0,0 +1,23 @@ +# Vector3::ProjectOnPlane + +```cpp +static Vector3 ProjectOnPlane(const Vector3& vector, const Vector3& planeNormal) +``` + +将向量投影到平面上（减去沿平面法线的分量）。 + +**参数：** +- `vector` - 要投影的向量 +- `planeNormal` - 平面法线 + +**返回：** `Vector3` - 平面上的投影向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(1.0f, 1.0f, 1.0f); +Vector3 normal(0.0f, 1.0f, 0.0f); // XZ 平面 +Vector3 projected = Vector3::ProjectOnPlane(v, normal); // (1, 0, 1) +``` diff --git a/docs/api/math/vector3/quaternion-multiply.md b/docs/api/math/vector3/quaternion-multiply.md new file mode 100644 index 00000000..d21f0da7 --- /dev/null +++ b/docs/api/math/vector3/quaternion-multiply.md @@ -0,0 +1,23 @@ +# Vector3 * Quaternion + +```cpp +Vector3 operator*(const Quaternion& q, const Vector3& v) +``` + +用四元数旋转向量。 + +**参数：** +- `q` - 旋转四元数 +- `v` - 要旋转的向量 + +**返回：** `Vector3` - 旋转后的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f); +Vector3 forward = Vector3::Forward(); +Vector3 rotated = rot * forward; // 绕 Y 轴旋转 90 度 +``` diff --git a/docs/api/math/vector3/reflect.md b/docs/api/math/vector3/reflect.md new file mode 100644 index 00000000..570be5f4 --- /dev/null +++ b/docs/api/math/vector3/reflect.md @@ -0,0 +1,23 @@ +# Vector3::Reflect + +```cpp +static Vector3 Reflect(const Vector3& inDirection, const Vector3& inNormal) +``` + +计算向量关于法线的反射方向。 + +**参数：** +- `inDirection` - 入射方向向量 +- `inNormal` - 反射表面的法线（应为单位向量） + +**返回：** `Vector3` - 反射方向 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 incoming(1.0f, -1.0f, 0.0f); +Vector3 normal(0.0f, 1.0f, 0.0f); +Vector3 reflected = Vector3::Reflect(incoming, normal); // (1, 1, 0) +``` diff --git a/docs/api/math/vector3/right.md b/docs/api/math/vector3/right.md new file mode 100644 index 00000000..7fe121b5 --- /dev/null +++ b/docs/api/math/vector3/right.md @@ -0,0 +1,17 @@ +# Vector3::Right + +```cpp +static Vector3 Right() +``` + +返回右方向向量 (1, 0, 0)。 + +**返回：** `Vector3` - 值为 (1, 0, 0) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 right = Vector3::Right(); +``` diff --git a/docs/api/math/vector3/sqrmagnitude.md b/docs/api/math/vector3/sqrmagnitude.md new file mode 100644 index 00000000..94e42d61 --- /dev/null +++ b/docs/api/math/vector3/sqrmagnitude.md @@ -0,0 +1,25 @@ +# Vector3::SqrMagnitude + +```cpp +static float SqrMagnitude(const Vector3& v) +float SqrMagnitude() const +``` + +计算向量长度的平方。比 Magnitude 更快，避免了开方运算。 + +**静态版本参数：** +- `v` - 要计算长度的向量 + +**实例版本：** 计算当前向量的长度平方。 + +**返回：** `float` - 向量长度平方 x * x + y * y + z * z + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 v(1.0f, 2.0f, 2.0f); +float sqlen = v.SqrMagnitude(); // 9.0f +float sqlen2 = Vector3::SqrMagnitude(v); // 9.0f +``` diff --git a/docs/api/math/vector3/up.md b/docs/api/math/vector3/up.md new file mode 100644 index 00000000..2ae2335a --- /dev/null +++ b/docs/api/math/vector3/up.md @@ -0,0 +1,17 @@ +# Vector3::Up + +```cpp +static Vector3 Up() +``` + +返回上方向向量 (0, 1, 0)。 + +**返回：** `Vector3` - 值为 (0, 1, 0) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 up = Vector3::Up(); +``` diff --git a/docs/api/math/vector3/vector3.md b/docs/api/math/vector3/vector3.md new file mode 100644 index 00000000..541a62b2 --- /dev/null +++ b/docs/api/math/vector3/vector3.md @@ -0,0 +1,69 @@ +# Vector3 + +3D 向量结构体，用于表示 3D 空间中的点、方向、颜色或法线。 + +**头文件：** `#include ` + +**命名空间：** `XCEngine::Math` + +## 结构体定义 + +```cpp +struct Vector3 { + float x = 0.0f; + float y = 0.0f; + float z = 0.0f; +}; +``` + +## 静态工厂方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Zero()](zero.md) | `Vector3` | 返回 (0, 0, 0) | +| [One()](one.md) | `Vector3` | 返回 (1, 1, 1) | +| [Forward()](forward.md) | `Vector3` | 返回 (0, 0, 1)，前方向（Z+） | +| [Back()](back.md) | `Vector3` | 返回 (0, 0, -1)，后方向 | +| [Up()](up.md) | `Vector3` | 返回 (0, 1, 0)，上方向 | +| [Down()](down.md) | `Vector3` | 返回 (0, -1, 0)，下方向 | +| [Right()](right.md) | `Vector3` | 返回 (1, 0, 0)，右方向 | +| [Left()](left.md) | `Vector3` | 返回 (-1, 0, 0)，左方向 | + +## 静态数学方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Dot(a, b)](dot.md) | `float` | 点积 | +| [Cross(a, b)](cross.md) | `Vector3` | 叉积（垂直于 a 和 b） | +| [Normalize(v)](normalize.md) | `Vector3` | 归一化向量 | +| [Magnitude(v)](magnitude.md) | `float` | 向量长度 | +| [SqrMagnitude(v)](sqrmagnitude.md) | `float` | 长度平方 | +| [Lerp(a, b, t)](lerp.md) | `Vector3` | 线性插值 | +| [MoveTowards(current, target, maxDistance)](movetowards.md) | `Vector3` | 朝目标移动 | +| [Project(vector, onNormal)](project.md) | `Vector3` | 投影到法线上 | +| [ProjectOnPlane(vector, planeNormal)](projectonplane.md) | `Vector3` | 投影到平面上 | +| [Angle(from, to)](angle.md) | `float` | 两向量夹角（度） | +| [Reflect(inDirection, inNormal)](reflect.md) | `Vector3` | 反射 | + +## 实例方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Magnitude()](magnitude.md) | `float` | 获取向量长度 | +| [SqrMagnitude()](sqrmagnitude.md) | `float` | 获取长度平方 | +| [Normalized()](normalized.md) | `Vector3` | 获取归一化副本 | + +## 运算符 + +- 算术: `+`, `-`, `*` (scalar/memberwise), `/` (scalar/memberwise) +- 复合赋值: `+=`, `-=`, `*=`, `/=` +- 下标: `operator[]` (0=x, 1=y, 2=z) +- 比较: `==`, `!=` + +## 与 Quaternion 的乘法 + +[Vector3 * Quaternion](quaternion-multiply.md) - 用四元数旋转向量 + +## 相关文档 + +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/vector3/zero.md b/docs/api/math/vector3/zero.md new file mode 100644 index 00000000..24770129 --- /dev/null +++ b/docs/api/math/vector3/zero.md @@ -0,0 +1,17 @@ +# Vector3::Zero + +```cpp +static Vector3 Zero() +``` + +返回零向量 (0, 0, 0)。 + +**返回：** `Vector3` - 值为 (0, 0, 0) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector3 origin = Vector3::Zero(); +``` diff --git a/docs/api/math/vector4/dot.md b/docs/api/math/vector4/dot.md new file mode 100644 index 00000000..0e848f6c --- /dev/null +++ b/docs/api/math/vector4/dot.md @@ -0,0 +1,23 @@ +# Vector4::Dot + +```cpp +static float Dot(const Vector4& a, const Vector4& b) +``` + +计算两个 4D 向量的点积。 + +**参数：** +- `a` - 第一个向量 +- `b` - 第二个向量 + +**返回：** `float` - 点积结果 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector4 a(1.0f, 2.0f, 3.0f, 4.0f); +Vector4 b(4.0f, 3.0f, 2.0f, 1.0f); +float dot = Vector4::Dot(a, b); // 20.0f +``` diff --git a/docs/api/math/vector4/one.md b/docs/api/math/vector4/one.md new file mode 100644 index 00000000..bbc06be3 --- /dev/null +++ b/docs/api/math/vector4/one.md @@ -0,0 +1,17 @@ +# Vector4::One + +```cpp +static Vector4 One() +``` + +返回单位向量 (1, 1, 1, 1)。 + +**返回：** `Vector4` - 值为 (1, 1, 1, 1) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector4 unit = Vector4::One(); +``` diff --git a/docs/api/math/vector4/project.md b/docs/api/math/vector4/project.md new file mode 100644 index 00000000..17b1420e --- /dev/null +++ b/docs/api/math/vector4/project.md @@ -0,0 +1,23 @@ +# Vector4::Project + +```cpp +static Vector4 Project(const Vector4& vector, const Vector4& onNormal) +``` + +将向量投影到法线向量上。 + +**参数：** +- `vector` - 要投影的向量 +- `onNormal` - 投影到的法线向量 + +**返回：** `Vector4` - 投影结果 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector4 v(1.0f, 1.0f, 1.0f, 1.0f); +Vector4 normal(1.0f, 0.0f, 0.0f, 0.0f); +Vector4 projected = Vector4::Project(v, normal); // (1, 0, 0, 0) +``` diff --git a/docs/api/math/vector4/tovector3.md b/docs/api/math/vector4/tovector3.md new file mode 100644 index 00000000..852cc56c --- /dev/null +++ b/docs/api/math/vector4/tovector3.md @@ -0,0 +1,18 @@ +# Vector4::ToVector3 + +```cpp +Vector3 ToVector3() const +``` + +将 Vector4 转换为 Vector3，丢弃 w 分量。 + +**返回：** `Vector3` - 转换后的 Vector3 (x, y, z) + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector4 pos4(1.0f, 2.0f, 3.0f, 1.0f); +Vector3 pos3 = pos4.ToVector3(); // (1, 2, 3) +``` diff --git a/docs/api/math/math-vector4.md b/docs/api/math/vector4/vector4.md similarity index 59% rename from docs/api/math/math-vector4.md rename to docs/api/math/vector4/vector4.md index 97b2b74c..cd02cc28 100644 --- a/docs/api/math/math-vector4.md +++ b/docs/api/math/vector4/vector4.md @@ -2,15 +2,9 @@ 4D 向量结构体，用于表示齐次坐标、颜色 (RGBA) 或 SIMD 操作。 -## 头文件 +**头文件：** `#include ` -```cpp -#include -``` - -## 命名空间 - -`XCEngine::Math` +**命名空间：** `XCEngine::Math` ## 结构体定义 @@ -23,7 +17,7 @@ struct Vector4 { }; ``` -## 构造方法 +## 构造函数 - `Vector4(float x, float y, float z, float w)` - 从四个分量构造 - `explicit Vector4(const Vector3& v, float w = 0.0f)` - 从 Vector3 构造 @@ -32,21 +26,21 @@ struct Vector4 { | 方法 | 返回值 | 描述 | |------|--------|------| -| `Zero()` | `Vector4` | 返回 (0, 0, 0, 0) | -| `One()` | `Vector4` | 返回 (1, 1, 1, 1) | +| [Zero()](zero.md) | `Vector4` | 返回 (0, 0, 0, 0) | +| [One()](one.md) | `Vector4` | 返回 (1, 1, 1, 1) | ## 静态数学方法 | 方法 | 返回值 | 描述 | |------|--------|------| -| `Dot(a, b)` | `float` | 4D 点积 | -| `Project(vector, onNormal)` | `Vector4` | 投影 | +| [Dot(a, b)](dot.md) | `float` | 4D 点积 | +| [Project(vector, onNormal)](project.md) | `Vector4` | 投影 | ## 实例方法 | 方法 | 返回值 | 描述 | |------|--------|------| -| `ToVector3()` | `Vector3` | 转换到 Vector3（丢弃 w） | +| [ToVector3()](tovector3.md) | `Vector3` | 转换到 Vector3（丢弃 w） | ## 运算符 @@ -54,9 +48,6 @@ struct Vector4 { - 下标: `operator[]` - 比较: `==`, `!=` -## 使用示例 +## 相关文档 -```cpp -Vector4 pos4(1.0f, 2.0f, 3.0f, 1.0f); -Vector3 pos3 = pos4.ToVector3(); -``` +- [Math 模块总览](../math.md) - 返回 Math 模块总览 diff --git a/docs/api/math/vector4/zero.md b/docs/api/math/vector4/zero.md new file mode 100644 index 00000000..89a11c13 --- /dev/null +++ b/docs/api/math/vector4/zero.md @@ -0,0 +1,17 @@ +# Vector4::Zero + +```cpp +static Vector4 Zero() +``` + +返回零向量 (0, 0, 0, 0)。 + +**返回：** `Vector4` - 值为 (0, 0, 0, 0) 的向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Vector4 origin = Vector4::Zero(); +``` diff --git a/docs/api/memory/allocator/allocate.md b/docs/api/memory/allocator/allocate.md new file mode 100644 index 00000000..9fd4b280 --- /dev/null +++ b/docs/api/memory/allocator/allocate.md @@ -0,0 +1,38 @@ +# IAllocator::Allocate + +```cpp +virtual void* Allocate(size_t size, size_t alignment = 0) = 0; +``` + +从分配器请求指定大小的内存块。如果 `alignment` 大于 0，则返回的地址将按该对齐值对齐。分配成功时返回有效指针，失败时返回 `nullptr` 或抛出异常（取决于具体实现）。 + +**参数：** +- `size` - 请求的字节数 +- `alignment` - 内存对齐要求，默认为 0（表示使用实现默认对齐） + +**返回：** 分配成功返回已分配内存块的指针，失败返回 `nullptr` + +**复杂度：** O(1)（固定块分配器）或 O(n)（需要搜索合适大小的块） + +**示例：** + +```cpp +#include + +class MyAllocator : public IAllocator { +public: + void* Allocate(size_t size, size_t alignment = 0) override { + // 使用系统 new 分配 + return ::operator new(size); + } + // ... 其他方法实现 +}; + +MyAllocator alloc; +void* ptr = alloc.Allocate(256); // 分配 256 字节 +void* aligned = alloc.Allocate(64, 16); // 分配 64 字节，16 字节对齐 +``` + +## 相关文档 + +- [IAllocator 总览](allocator.md) - 返回类总览 diff --git a/docs/api/memory/memory-allocator.md b/docs/api/memory/allocator/allocator.md similarity index 60% rename from docs/api/memory/memory-allocator.md rename to docs/api/memory/allocator/allocator.md index 2315db0b..5a9f19c2 100644 --- a/docs/api/memory/memory-allocator.md +++ b/docs/api/memory/allocator/allocator.md @@ -16,45 +16,42 @@ | 方法 | 描述 | |------|------| -| `virtual void* Allocate(size_t size, size_t alignment = 0)` | 分配内存 | -| `virtual void Free(void* ptr)` | 释放内存 | -| `virtual void* Reallocate(void* ptr, size_t newSize)` | 重新分配内存 | +| `Allocate` | 分配内存 | +| `Free` | 释放内存 | +| `Reallocate` | 重新分配内存 | ### 统计信息 | 方法 | 描述 | |------|------| -| `virtual size_t GetTotalAllocated() const` | 获取已分配总字节数 | -| `virtual size_t GetTotalFreed() const` | 获取已释放总字节数 | -| `virtual size_t GetPeakAllocated() const` | 获取峰值分配字节数 | -| `virtual size_t GetAllocationCount() const` | 获取分配次数 | +| `GetTotalAllocated` | 获取已分配总字节数 | +| `GetTotalFreed` | 获取已释放总字节数 | +| `GetPeakAllocated` | 获取峰值分配字节数 | +| `GetAllocationCount` | 获取分配次数 | ### 元信息 | 方法 | 描述 | |------|------| -| `virtual const char* GetName() const = 0` | 获取分配器名称 | +| `GetName` | 获取分配器名称 | ## 使用示例 ```cpp -#include +#include class MyAllocator : public IAllocator { public: void* Allocate(size_t size, size_t alignment = 0) override { - // 实现分配逻辑 return ::operator new(size); } void Free(void* ptr) override { - // 实现释放逻辑 ::operator delete(ptr); } void* Reallocate(void* ptr, size_t newSize) override { void* newPtr = Allocate(newSize); - // 拷贝旧数据... Free(ptr); return newPtr; } @@ -69,6 +66,7 @@ public: ## 相关文档 -- [MemoryManager](./memory-manager.md) - 内存管理器 -- [LinearAllocator](./memory-linear-allocator.md) - 线性分配器 -- [PoolAllocator](./memory-pool-allocator.md) - 内存池分配器 +- [Memory 模块总览](../memory.md) - 返回模块总览 +- [MemoryManager](../manager/manager.md) - 内存管理器 +- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器 +- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器 diff --git a/docs/api/memory/allocator/free.md b/docs/api/memory/allocator/free.md new file mode 100644 index 00000000..4b00fcd8 --- /dev/null +++ b/docs/api/memory/allocator/free.md @@ -0,0 +1,40 @@ +# IAllocator::Free + +```cpp +virtual void Free(void* ptr) = 0; +``` + +释放之前通过 `Allocate` 分配的内存块。如果 `ptr` 为 `nullptr`，则此调用无效果。部分分配器（如 LinearAllocator）可能不支持此操作。 + +**参数：** +- `ptr` - 指向要释放内存块的指针 + +**返回：** 无 + +**复杂度：** O(1)（固定块释放）或 O(n)（需要搜索） + +**示例：** + +```cpp +#include + +class MyAllocator : public IAllocator { +public: + void* Allocate(size_t size, size_t alignment = 0) override { + return ::operator new(size); + } + + void Free(void* ptr) override { + if (ptr) ::operator delete(ptr); + } + // ... 其他方法实现 +}; + +MyAllocator alloc; +void* ptr = alloc.Allocate(512); +alloc.Free(ptr); // 释放内存 +``` + +## 相关文档 + +- [IAllocator 总览](allocator.md) - 返回类总览 diff --git a/docs/api/memory/allocator/get-allocation-count.md b/docs/api/memory/allocator/get-allocation-count.md new file mode 100644 index 00000000..aad2f8e7 --- /dev/null +++ b/docs/api/memory/allocator/get-allocation-count.md @@ -0,0 +1,52 @@ +# IAllocator::GetAllocationCount + +```cpp +virtual size_t GetAllocationCount() const = 0; +``` + +返回当前处于已分配状态（未释放）的内存块数量。此方法用于监控活跃分配的数量。 + +**参数：** 无 + +**返回：** 当前已分配块的数量 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyAllocator : public IAllocator { + size_t m_count = 0; +public: + void* Allocate(size_t size, size_t alignment = 0) override { + ++m_count; + return ::operator new(size); + } + + void Free(void* ptr) override { + if (ptr) { + --m_count; + ::operator delete(ptr); + } + } + + void* Reallocate(void* ptr, size_t newSize) override { /* ... */ } + + size_t GetTotalAllocated() const override { return 0; } + size_t GetTotalFreed() const override { return 0; } + size_t GetPeakAllocated() const override { return 0; } + size_t GetAllocationCount() const override { return m_count; } + const char* GetName() const override { return "MyAllocator"; } +}; + +MyAllocator alloc; +alloc.Allocate(64); +alloc.Allocate(128); +size_t count = alloc.GetAllocationCount(); // 返回 2 +``` + +## 相关文档 + +- [IAllocator 总览](allocator.md) - 返回类总览 diff --git a/docs/api/memory/allocator/get-name.md b/docs/api/memory/allocator/get-name.md new file mode 100644 index 00000000..9b694f4d --- /dev/null +++ b/docs/api/memory/allocator/get-name.md @@ -0,0 +1,40 @@ +# IAllocator::GetName + +```cpp +virtual const char* GetName() const = 0; +``` + +返回分配器的名称字符串。此方法用于调试、日志记录和内存报告，帮助识别不同分配器的使用情况。 + +**参数：** 无 + +**返回：** 分配器的名称字符串 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyAllocator : public IAllocator { +public: + void* Allocate(size_t size, size_t alignment = 0) override { return ::operator new(size); } + void Free(void* ptr) override { if (ptr) ::operator delete(ptr); } + void* Reallocate(void* ptr, size_t newSize) override { /* ... */ } + + size_t GetTotalAllocated() const override { return 0; } + size_t GetTotalFreed() const override { return 0; } + size_t GetPeakAllocated() const override { return 0; } + size_t GetAllocationCount() const override { return 0; } + const char* GetName() const override { return "MyAllocator"; } +}; + +MyAllocator alloc; +const char* name = alloc.GetName(); // 返回 "MyAllocator" +printf("Allocator: %s\n", name); +``` + +## 相关文档 + +- [IAllocator 总览](allocator.md) - 返回类总览 diff --git a/docs/api/memory/allocator/get-peak-allocated.md b/docs/api/memory/allocator/get-peak-allocated.md new file mode 100644 index 00000000..7248497f --- /dev/null +++ b/docs/api/memory/allocator/get-peak-allocated.md @@ -0,0 +1,57 @@ +# IAllocator::GetPeakAllocated + +```cpp +virtual size_t GetPeakAllocated() const = 0; +``` + +返回此分配器自创建以来达到的峰值分配字节数。该值在每次分配后更新，用于监控内存使用高峰。 + +**参数：** 无 + +**返回：** 峰值分配字节数 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyAllocator : public IAllocator { + size_t m_peak = 0; + size_t m_current = 0; +public: + void* Allocate(size_t size, size_t alignment = 0) override { + void* ptr = ::operator new(size); + m_current += size; + if (m_current > m_peak) m_peak = m_current; + return ptr; + } + + void Free(void* ptr) override { + if (ptr) { + size_t size = 256; // 需要外部记录 + ::operator delete(ptr); + m_current -= size; + } + } + + void* Reallocate(void* ptr, size_t newSize) override { /* ... */ } + + size_t GetTotalAllocated() const override { return 0; } + size_t GetTotalFreed() const override { return 0; } + size_t GetPeakAllocated() const override { return m_peak; } + size_t GetAllocationCount() const override { return 0; } + const char* GetName() const override { return "MyAllocator"; } +}; + +MyAllocator alloc; +alloc.Allocate(100); +size_t peak1 = alloc.GetPeakAllocated(); // 100 +alloc.Allocate(50); +size_t peak2 = alloc.GetPeakAllocated(); // 150 +``` + +## 相关文档 + +- [IAllocator 总览](allocator.md) - 返回类总览 diff --git a/docs/api/memory/allocator/get-total-allocated.md b/docs/api/memory/allocator/get-total-allocated.md new file mode 100644 index 00000000..dea0d8ca --- /dev/null +++ b/docs/api/memory/allocator/get-total-allocated.md @@ -0,0 +1,50 @@ +# IAllocator::GetTotalAllocated + +```cpp +virtual size_t GetTotalAllocated() const = 0; +``` + +返回此分配器自创建以来累计分配的字节总数。这是一个只读查询操作，不会修改任何内部状态。 + +**参数：** 无 + +**返回：** 累计已分配的字节数 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyAllocator : public IAllocator { + size_t m_allocated = 0; +public: + void* Allocate(size_t size, size_t alignment = 0) override { + void* ptr = ::operator new(size); + m_allocated += size; + return ptr; + } + + void Free(void* ptr) override { + if (ptr) ::operator delete(ptr); + } + + void* Reallocate(void* ptr, size_t newSize) override { /* ... */ } + + size_t GetTotalAllocated() const override { return m_allocated; } + size_t GetTotalFreed() const override { return 0; } + size_t GetPeakAllocated() const override { return m_allocated; } + size_t GetAllocationCount() const override { return 0; } + const char* GetName() const override { return "MyAllocator"; } +}; + +MyAllocator alloc; +alloc.Allocate(100); +alloc.Allocate(200); +size_t total = alloc.GetTotalAllocated(); // 返回 300 +``` + +## 相关文档 + +- [IAllocator 总览](allocator.md) - 返回类总览 diff --git a/docs/api/memory/allocator/get-total-freed.md b/docs/api/memory/allocator/get-total-freed.md new file mode 100644 index 00000000..38a596ff --- /dev/null +++ b/docs/api/memory/allocator/get-total-freed.md @@ -0,0 +1,50 @@ +# IAllocator::GetTotalFreed + +```cpp +virtual size_t GetTotalFreed() const = 0; +``` + +返回此分配器自创建以来累计释放的字节总数。部分分配器（如 LinearAllocator）可能始终返回 0，因为它们不跟踪单个释放操作。 + +**参数：** 无 + +**返回：** 累计已释放的字节数 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +class MyAllocator : public IAllocator { + size_t m_freed = 0; +public: + void* Allocate(size_t size, size_t alignment = 0) override { return ::operator new(size); } + + void Free(void* ptr) override { + if (ptr) { + size_t size = 256; // 需要外部记录 + ::operator delete(ptr); + m_freed += size; + } + } + + void* Reallocate(void* ptr, size_t newSize) override { /* ... */ } + + size_t GetTotalAllocated() const override { return 0; } + size_t GetTotalFreed() const override { return m_freed; } + size_t GetPeakAllocated() const override { return 0; } + size_t GetAllocationCount() const override { return 0; } + const char* GetName() const override { return "MyAllocator"; } +}; + +MyAllocator alloc; +void* ptr = alloc.Allocate(128); +alloc.Free(ptr); +size_t freed = alloc.GetTotalFreed(); // 返回 128 +``` + +## 相关文档 + +- [IAllocator 总览](allocator.md) - 返回类总览 diff --git a/docs/api/memory/allocator/reallocate.md b/docs/api/memory/allocator/reallocate.md new file mode 100644 index 00000000..06d3d7a8 --- /dev/null +++ b/docs/api/memory/allocator/reallocate.md @@ -0,0 +1,55 @@ +# IAllocator::Reallocate + +```cpp +virtual void* Reallocate(void* ptr, size_t newSize) = 0; +``` + +调整已分配内存块的大小。如果 `ptr` 为 `nullptr`，行为等同于 `Allocate(newSize)`。如果 `newSize` 为 0，行为等同于 `Free(ptr)` 并返回 `nullptr`。如果分配器不支持重新分配，应返回 `nullptr` 并保持原内存不变。 + +**参数：** +- `ptr` - 指向现有内存块的指针 +- `newSize` - 新的字节大小 + +**返回：** 调整后的新内存块指针（可能与原指针不同） + +**复杂度：** O(n)，需要分配新内存并复制数据 + +**示例：** + +```cpp +#include + +class MyAllocator : public IAllocator { +public: + void* Allocate(size_t size, size_t alignment = 0) override { + return ::operator new(size); + } + + void Free(void* ptr) override { + if (ptr) ::operator delete(ptr); + } + + void* Reallocate(void* ptr, size_t newSize) override { + if (newSize == 0) { + Free(ptr); + return nullptr; + } + if (!ptr) return Allocate(newSize); + + size_t oldSize = /* 需要外部记录 */ 256; // 示例中硬编码 + void* newPtr = Allocate(newSize); + memcpy(newPtr, ptr, oldSize < newSize ? oldSize : newSize); + Free(ptr); + return newPtr; + } + // ... 其他方法实现 +}; + +MyAllocator alloc; +void* ptr = alloc.Allocate(128); +void* bigger = alloc.Reallocate(ptr, 256); // 扩展到 256 字节 +``` + +## 相关文档 + +- [IAllocator 总览](allocator.md) - 返回类总览 diff --git a/docs/api/memory/linear-allocator/allocate.md b/docs/api/memory/linear-allocator/allocate.md new file mode 100644 index 00000000..228dec23 --- /dev/null +++ b/docs/api/memory/linear-allocator/allocate.md @@ -0,0 +1,41 @@ +# LinearAllocator::Allocate + +```cpp +void* Allocate(size_t size, size_t alignment = 8) override; +``` + +在缓冲区的当前位置顺序分配内存。每次分配都会将内部偏移量向前推进（对齐后）。如果剩余空间不足，则分配失败返回 `nullptr`。默认对齐值为 8 字节。 + +**参数：** +- `size` - 请求的字节数 +- `alignment` - 内存对齐要求，默认为 8 字节 + +**返回：** 分配成功返回已对齐的指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +LinearAllocator allocator(1024); + +// 分配 256 字节（8 字节对齐） +void* ptr1 = allocator.Allocate(256); + +// 分配 128 字节（16 字节对齐） +void* ptr2 = allocator.Allocate(128, 16); + +// 分配 64 字节（默认 8 字节对齐） +void* ptr3 = allocator.Allocate(64); + +// 检查是否成功 +if (!ptr1) { + // 分配失败，缓冲区已满 +} +``` + +## 相关文档 + +- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 diff --git a/docs/api/memory/linear-allocator/clear.md b/docs/api/memory/linear-allocator/clear.md new file mode 100644 index 00000000..6a6f879c --- /dev/null +++ b/docs/api/memory/linear-allocator/clear.md @@ -0,0 +1,37 @@ +# LinearAllocator::Clear + +```cpp +void Clear(); +``` + +清空分配器，将内部偏移量重置为 0，所有已分配的内存被视为已释放。下一次 `Allocate` 将从缓冲区起始位置开始。此方法不实际释放或修改底层内存，适合作为帧分配器使用，每帧开始时调用 Clear 重置。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +LinearAllocator allocator(1024 * 1024); + +// 第一帧 +void* frame1_ptr = allocator.Allocate(256); +void* frame1_ptr2 = allocator.Allocate(128); +// ... 第一帧渲染逻辑 + +// 帧结束时清空 +allocator.Clear(); + +// 第二帧重新开始 +void* frame2_ptr = allocator.Allocate(256); +// 此时 frame1_ptr 已无效，但内存已被回收复用 +``` + +## 相关文档 + +- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 diff --git a/docs/api/memory/linear-allocator/free.md b/docs/api/memory/linear-allocator/free.md new file mode 100644 index 00000000..0b6e491c --- /dev/null +++ b/docs/api/memory/linear-allocator/free.md @@ -0,0 +1,35 @@ +# LinearAllocator::Free + +```cpp +void Free(void* ptr) override; +``` + +此方法对 LinearAllocator 无实际效果。线性分配器不支持单个内存块的释放，因为内存是顺序分配的，释放中间某块会破坏后续分配的完整性。需要释放所有内存时使用 `Clear()` 方法。 + +**参数：** +- `ptr` - 被忽略 + +**返回：** 无 + +**复杂度：** O(1)（空操作） + +**示例：** + +```cpp +#include + +LinearAllocator allocator(1024); +void* ptr = allocator.Allocate(256); +void* ptr2 = allocator.Allocate(128); + +// Free 实际上什么都不做 +allocator.Free(ptr); +allocator.Free(ptr2); + +// 如需释放所有内存，应使用 Clear +allocator.Clear(); +``` + +## 相关文档 + +- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 diff --git a/docs/api/memory/linear-allocator/get-capacity.md b/docs/api/memory/linear-allocator/get-capacity.md new file mode 100644 index 00000000..23fdbcfa --- /dev/null +++ b/docs/api/memory/linear-allocator/get-capacity.md @@ -0,0 +1,33 @@ +# LinearAllocator::GetCapacity + +```cpp +size_t GetCapacity() const; +``` + +返回分配器的总容量，即预分配缓冲区的大小。此值在构造时确定，之后保持不变。 + +**参数：** 无 + +**返回：** 总容量（字节数） + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +LinearAllocator allocator(1024 * 1024); // 1MB + +size_t capacity = allocator.GetCapacity(); // 1048576 + +allocator.Allocate(512); +allocator.Allocate(256); + +size_t used = allocator.GetUsedSize(); // 768 +size_t remaining = allocator.GetCapacity() - allocator.GetUsedSize(); // 1047808 +``` + +## 相关文档 + +- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 diff --git a/docs/api/memory/linear-allocator/get-marker.md b/docs/api/memory/linear-allocator/get-marker.md new file mode 100644 index 00000000..36fecb39 --- /dev/null +++ b/docs/api/memory/linear-allocator/get-marker.md @@ -0,0 +1,41 @@ +# LinearAllocator::GetMarker + +```cpp +void* GetMarker() const; +``` + +获取当前分配位置的标记。标记是一个指向当前偏移量的指针，可用于 `SetMarker` 恢复到该位置。此方法用于实现临时分配的撤销功能。 + +**参数：** 无 + +**返回：** 当前分配位置的指针标记 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +LinearAllocator allocator(1024); + +// 分配一些数据 +void* ptr1 = allocator.Allocate(128); + +// 保存标记（用于回滚点） +void* marker = allocator.GetMarker(); + +// 分配临时数据 +void* temp = allocator.Allocate(64); +void* temp2 = allocator.Allocate(32); + +// 临时数据用完了，恢复到标记位置 +allocator.SetMarker(marker); + +// 此时 temp 和 temp2 的内存已被回收 +// ptr1 仍然有效 +``` + +## 相关文档 + +- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 diff --git a/docs/api/memory/linear-allocator/get-used-size.md b/docs/api/memory/linear-allocator/get-used-size.md new file mode 100644 index 00000000..898859bb --- /dev/null +++ b/docs/api/memory/linear-allocator/get-used-size.md @@ -0,0 +1,39 @@ +# LinearAllocator::GetUsedSize + +```cpp +size_t GetUsedSize() const; +``` + +返回当前已使用的字节数，即内部偏移量的值。此值在 `Allocate` 后增加，在 `Clear` 或 `SetMarker` 后可能减少（取决于设置的目标位置）。 + +**参数：** 无 + +**返回：** 已使用的字节数 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +LinearAllocator allocator(1024); + +size_t before = allocator.GetUsedSize(); // 0 + +allocator.Allocate(128); +allocator.Allocate(256); + +size_t after = allocator.GetUsedSize(); // 384 + +void* marker = allocator.GetMarker(); +allocator.Allocate(64); +size_t with_temp = allocator.GetUsedSize(); // 448 + +allocator.SetMarker(marker); +size_t after_rollback = allocator.GetUsedSize(); // 384 +``` + +## 相关文档 + +- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 diff --git a/docs/api/memory/linear-allocator/linear-allocator.md b/docs/api/memory/linear-allocator/linear-allocator.md new file mode 100644 index 00000000..3e8c376b --- /dev/null +++ b/docs/api/memory/linear-allocator/linear-allocator.md @@ -0,0 +1,35 @@ +# LinearAllocator::LinearAllocator + +```cpp +explicit LinearAllocator(size_t size, IAllocator* parent = nullptr); +``` + +构造一个线性分配器，预分配指定大小的缓冲区。如果提供了 `parent` 分配器，则使用它分配底层缓冲区；否则使用系统默认分配（`_aligned_malloc`，8 字节对齐）。 + +**参数：** +- `size` - 预分配的缓冲区大小（字节数） +- `parent` - 父分配器，用于分配底层缓冲区，默认为 `nullptr`（使用系统分配） + +**返回：** 无 + +**复杂度：** O(n)，需要分配 `size` 大小的缓冲区 + +**示例：** + +```cpp +#include + +// 使用系统分配器创建 1MB 线性分配器 +LinearAllocator allocator1(1024 * 1024); + +// 使用指定的父分配器 +IAllocator* parent = MemoryManager::Get().GetSystemAllocator(); +LinearAllocator allocator2(1024 * 1024, parent); + +// 默认 8 字节对齐 +void* ptr = allocator1.Allocate(256); +``` + +## 相关文档 + +- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 diff --git a/docs/api/memory/linear-allocator/reallocate.md b/docs/api/memory/linear-allocator/reallocate.md new file mode 100644 index 00000000..caa48385 --- /dev/null +++ b/docs/api/memory/linear-allocator/reallocate.md @@ -0,0 +1,34 @@ +# LinearAllocator::Reallocate + +```cpp +void* Reallocate(void* ptr, size_t newSize) override; +``` + +在缓冲区当前位置分配新内存。此方法始终在缓冲区末尾分配新内存，而不是尝试调整现有块的大小。返回的指针可能与输入的 `ptr` 不同。如果剩余空间不足，返回 `nullptr` 且原指针保持不变。 + +**参数：** +- `ptr` - 被忽略（始终分配新内存） +- `newSize` - 新请求的字节数 + +**返回：** 分配成功返回新内存指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +LinearAllocator allocator(1024); +void* ptr1 = allocator.Allocate(128); + +// Reallocate 忽略原 ptr，在当前位置分配新内存 +void* ptr2 = allocator.Reallocate(ptr1, 256); + +// ptr1 和 ptr2 可能相同也可能不同 +// 都不会被释放，新内存始终在缓冲区末尾分配 +``` + +## 相关文档 + +- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 diff --git a/docs/api/memory/linear-allocator/set-marker.md b/docs/api/memory/linear-allocator/set-marker.md new file mode 100644 index 00000000..b2fa9371 --- /dev/null +++ b/docs/api/memory/linear-allocator/set-marker.md @@ -0,0 +1,41 @@ +# LinearAllocator::SetMarker + +```cpp +void SetMarker(void* marker); +``` + +恢复到之前通过 `GetMarker` 获取的标记位置。所有在标记之后的分配都将被丢弃，内部偏移量重置为该标记位置。此方法不会释放内存，只是移动偏移量指针。 + +**参数：** +- `marker` - 通过 `GetMarker` 获取的标记指针 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +LinearAllocator allocator(1024); + +// 基础数据 +void* base = allocator.Allocate(256); +void* marker = allocator.GetMarker(); + +// 可选的扩展数据 +void* ext1 = allocator.Allocate(64); +void* ext2 = allocator.Allocate(128); + +// 决定不使用扩展数据，回滚 +allocator.SetMarker(marker); + +// 扩展数据内存已被回收 +// 可以重新分配其他数据 +void* new_data = allocator.Allocate(128); +``` + +## 相关文档 + +- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 diff --git a/docs/api/memory/linear-allocator/~linear-allocator.md b/docs/api/memory/linear-allocator/~linear-allocator.md new file mode 100644 index 00000000..b7c2384c --- /dev/null +++ b/docs/api/memory/linear-allocator/~linear-allocator.md @@ -0,0 +1,29 @@ +# LinearAllocator::~LinearAllocator + +```cpp +~LinearAllocator() override; +``` + +销毁线性分配器，释放预分配的缓冲区。如果提供了 `parent` 分配器，则使用它释放缓冲区；否则使用系统默认释放（`::operator delete`）。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +{ + LinearAllocator allocator(1024 * 1024); + void* ptr = allocator.Allocate(256); + // ... 使用 allocator +} // 析构时自动释放 1MB 缓冲区 +``` + +## 相关文档 + +- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 diff --git a/docs/api/memory/manager/create-linear-allocator.md b/docs/api/memory/manager/create-linear-allocator.md new file mode 100644 index 00000000..2e6d7e3e --- /dev/null +++ b/docs/api/memory/manager/create-linear-allocator.md @@ -0,0 +1,32 @@ +# MemoryManager::CreateLinearAllocator + +```cpp +std::unique_ptr CreateLinearAllocator(size_t size); +``` + +创建并返回一个新的 LinearAllocator 实例，使用系统分配器作为底层。返回的 `unique_ptr` 管理分配器生命周期。 + +**参数：** +- `size` - 分配器缓冲区大小（字节） + +**返回：** LinearAllocator 的 unique_ptr + +**复杂度：** O(size) + +**示例：** + +```cpp +#include + +auto linear = MemoryManager::Get().CreateLinearAllocator(1024 * 1024); +void* ptr = linear->Allocate(256); +void* marker = linear->GetMarker(); +linear->Allocate(128); +linear->SetMarker(marker); +linear->Clear(); +``` + +## 相关文档 + +- [MemoryManager 总览](manager.md) - 返回类总览 +- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器 diff --git a/docs/api/memory/manager/create-pool-allocator.md b/docs/api/memory/manager/create-pool-allocator.md new file mode 100644 index 00000000..752a94e8 --- /dev/null +++ b/docs/api/memory/manager/create-pool-allocator.md @@ -0,0 +1,37 @@ +# MemoryManager::CreatePoolAllocator + +```cpp +std::unique_ptr CreatePoolAllocator(size_t blockSize, size_t count); +``` + +创建并返回一个新的 PoolAllocator 实例，使用系统分配器作为底层。返回的 `unique_ptr` 管理分配器生命周期。 + +**参数：** +- `blockSize` - 每个内存块的大小（字节） +- `count` - 内存池中块的数量 + +**返回：** PoolAllocator 的 unique_ptr + +**复杂度：** O(blockSize * count) + +**示例：** + +```cpp +#include + +struct Particle { + float x, y, z; + float life; +}; + +auto pool = MemoryManager::Get().CreatePoolAllocator(sizeof(Particle), 1000); +void* block = pool->Allocate(); +auto* p = new (block) Particle{1.0f, 2.0f, 3.0f, 5.0f}; +p->~Particle(); +pool->Free(block); +``` + +## 相关文档 + +- [MemoryManager 总览](manager.md) - 返回类总览 +- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器 diff --git a/docs/api/memory/manager/create-proxy-allocator.md b/docs/api/memory/manager/create-proxy-allocator.md new file mode 100644 index 00000000..de9bb5e5 --- /dev/null +++ b/docs/api/memory/manager/create-proxy-allocator.md @@ -0,0 +1,36 @@ +# MemoryManager::CreateProxyAllocator + +```cpp +std::unique_ptr CreateProxyAllocator(const char* name); +``` + +创建并返回一个新的 ProxyAllocator 实例，包装系统分配器并使用指定名称。返回的 `unique_ptr` 管理分配器生命周期。 + +**参数：** +- `name` - 代理分配器的名称 + +**返回：** ProxyAllocator 的 unique_ptr + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +auto proxy = MemoryManager::Get().CreateProxyAllocator("FrameData"); +void* ptr = proxy->Allocate(1024); +void* ptr2 = proxy->Allocate(512); + +const auto& stats = proxy->GetStats(); +printf("Peak: %zu bytes, Count: %zu\n", + stats.peakAllocated, stats.allocationCount); + +proxy->Free(ptr); +proxy->Free(ptr2); +``` + +## 相关文档 + +- [MemoryManager 总览](manager.md) - 返回类总览 +- [ProxyAllocator](../proxy-allocator/proxy-allocator.md) - 代理分配器 diff --git a/docs/api/memory/manager/dump-memory-leaks.md b/docs/api/memory/manager/dump-memory-leaks.md new file mode 100644 index 00000000..3ec9f1dc --- /dev/null +++ b/docs/api/memory/manager/dump-memory-leaks.md @@ -0,0 +1,31 @@ +# MemoryManager::DumpMemoryLeaks + +```cpp +void DumpMemoryLeaks(); +``` + +输出当前未释放的内存分配信息。如果启用了内存跟踪，此方法会遍历所有记录并报告疑似泄漏的分配。应在程序退出前调用，以便发现资源泄漏。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +#include + +MemoryManager::Get().Initialize(); + +// ... 程序运行 ... + +// 程序退出前检查泄漏 +MemoryManager::Get().DumpMemoryLeaks(); +MemoryManager::Get().Shutdown(); +``` + +## 相关文档 + +- [MemoryManager 总览](manager.md) - 返回类总览 diff --git a/docs/api/memory/manager/generate-memory-report.md b/docs/api/memory/manager/generate-memory-report.md new file mode 100644 index 00000000..b665957e --- /dev/null +++ b/docs/api/memory/manager/generate-memory-report.md @@ -0,0 +1,37 @@ +# MemoryManager::GenerateMemoryReport + +```cpp +void GenerateMemoryReport(); +``` + +生成并输出当前内存使用情况的详细报告。报告内容包括各分配器的统计信息、峰值使用量、分配次数等。应在启用内存跟踪后调用。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +#include + +MemoryManager::Get().Initialize(); + +auto proxy = MemoryManager::Get().CreateProxyAllocator("GameFrame"); +proxy->Allocate(1024 * 1024); +proxy->Allocate(512 * 1024); + +// 生成内存报告 +MemoryManager::Get().GenerateMemoryReport(); + +proxy->Free(proxy->Allocate(256 * 1024)); +MemoryManager::Get().GenerateMemoryReport(); + +MemoryManager::Get().Shutdown(); +``` + +## 相关文档 + +- [MemoryManager 总览](manager.md) - 返回类总览 diff --git a/docs/api/memory/manager/get-system-allocator.md b/docs/api/memory/manager/get-system-allocator.md new file mode 100644 index 00000000..34a3ebd4 --- /dev/null +++ b/docs/api/memory/manager/get-system-allocator.md @@ -0,0 +1,27 @@ +# MemoryManager::GetSystemAllocator + +```cpp +IAllocator* GetSystemAllocator(); +``` + +获取系统默认分配器。该分配器使用标准 C 库的 `std::malloc` 和平台特定的对齐分配函数（如 Windows 的 `_aligned_malloc`）作为后端，适用于通用内存分配场景。 + +**参数：** 无 + +**返回：** 系统分配器指针 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator(); +void* ptr = sysAlloc->Allocate(1024); +sysAlloc->Free(ptr); +``` + +## 相关文档 + +- [MemoryManager 总览](manager.md) - 返回类总览 diff --git a/docs/api/memory/manager/get.md b/docs/api/memory/manager/get.md new file mode 100644 index 00000000..c4eb11c5 --- /dev/null +++ b/docs/api/memory/manager/get.md @@ -0,0 +1,39 @@ +# MemoryManager::Get + +```cpp +static MemoryManager& Get(); +``` + +获取 MemoryManager 单例实例。如果尚未创建则内部构造。此方法是获取内存管理器实例的唯一途径。 + +**参数：** 无 + +**返回：** MemoryManager 单例引用 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +// 获取单例 +MemoryManager& manager = MemoryManager::Get(); + +// 初始化 +manager.Initialize(); + +// 访问系统分配器 +IAllocator* sysAlloc = manager.GetSystemAllocator(); + +// 关闭 +manager.Shutdown(); + +// 多次调用返回同一实例 +MemoryManager& manager2 = MemoryManager::Get(); +// manager == manager2 为 true +``` + +## 相关文档 + +- [MemoryManager 总览](manager.md) - 返回类总览 diff --git a/docs/api/memory/manager/initialize.md b/docs/api/memory/manager/initialize.md new file mode 100644 index 00000000..c95c0460 --- /dev/null +++ b/docs/api/memory/manager/initialize.md @@ -0,0 +1,33 @@ +# MemoryManager::Initialize + +```cpp +void Initialize(); +``` + +初始化内存管理器。创建系统默认分配器，设置内存跟踪标志。应在程序启动早期调用，且仅可调用一次。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +#include + +int main() { + // 程序启动时初始化 + MemoryManager::Get().Initialize(); + + // 使用内存系统... + + MemoryManager::Get().Shutdown(); + return 0; +} +``` + +## 相关文档 + +- [MemoryManager 总览](manager.md) - 返回类总览 diff --git a/docs/api/memory/memory-manager.md b/docs/api/memory/manager/manager.md similarity index 61% rename from docs/api/memory/memory-manager.md rename to docs/api/memory/manager/manager.md index aaa4999b..b11ef7a3 100644 --- a/docs/api/memory/memory-manager.md +++ b/docs/api/memory/manager/manager.md @@ -14,7 +14,7 @@ | 方法 | 描述 | |------|------| -| `static MemoryManager& Get()` | 获取单例实例 | +| `Get` | 获取单例实例 | ## 公共方法 @@ -22,30 +22,30 @@ | 方法 | 描述 | |------|------| -| `void Initialize()` | 初始化内存管理器 | -| `void Shutdown()` | 关闭内存管理器 | +| `Initialize` | 初始化内存管理器 | +| `Shutdown` | 关闭内存管理器 | ### 系统分配器 | 方法 | 描述 | |------|------| -| `IAllocator* GetSystemAllocator()` | 获取系统默认分配器 | +| `GetSystemAllocator` | 获取系统默认分配器 | ### 分配器创建 | 方法 | 描述 | |------|------| -| `std::unique_ptr CreateLinearAllocator(size_t size)` | 创建线性分配器 | -| `std::unique_ptr CreatePoolAllocator(size_t blockSize, size_t count)` | 创建内存池分配器 | -| `std::unique_ptr CreateProxyAllocator(const char* name)` | 创建代理分配器 | +| `CreateLinearAllocator` | 创建线性分配器 | +| `CreatePoolAllocator` | 创建内存池分配器 | +| `CreateProxyAllocator` | 创建代理分配器 | ### 内存管理 | 方法 | 描述 | |------|------| -| `void SetTrackAllocations(bool track)` | 设置是否跟踪分配 | -| `void DumpMemoryLeaks()` | 输出内存泄漏报告 | -| `void GenerateMemoryReport()` | 生成内存使用报告 | +| `SetTrackAllocations` | 设置是否跟踪分配 | +| `DumpMemoryLeaks` | 输出内存泄漏报告 | +| `GenerateMemoryReport` | 生成内存使用报告 | ## 宏定义 @@ -68,6 +68,8 @@ ## 使用示例 ```cpp +#include + // 初始化 MemoryManager::Get().Initialize(); @@ -93,7 +95,8 @@ MemoryManager::Get().Shutdown(); ## 相关文档 -- [IAllocator](./memory-allocator.md) - 分配器接口 -- [LinearAllocator](./memory-linear-allocator.md) - 线性分配器 -- [PoolAllocator](./memory-pool-allocator.md) - 内存池分配器 -- [ProxyAllocator](./memory-proxy-allocator.md) - 代理分配器 +- [Memory 模块总览](../memory.md) - 返回模块总览 +- [IAllocator](../allocator/allocator.md) - 分配器接口 +- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器 +- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器 +- [ProxyAllocator](../proxy-allocator/proxy-allocator.md) - 代理分配器 diff --git a/docs/api/memory/manager/set-track-allocations.md b/docs/api/memory/manager/set-track-allocations.md new file mode 100644 index 00000000..2b559995 --- /dev/null +++ b/docs/api/memory/manager/set-track-allocations.md @@ -0,0 +1,35 @@ +# MemoryManager::SetTrackAllocations + +```cpp +void SetTrackAllocations(bool track); +``` + +设置是否启用内存分配跟踪。启用后系统会记录所有分配操作，用于生成内存报告和泄漏检测。 + +**参数：** +- `track` - true 启用跟踪，false 禁用跟踪 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +MemoryManager::Get().Initialize(); + +// 禁用跟踪（提升性能） +MemoryManager::Get().SetTrackAllocations(false); + +// ... 大量内存操作 ... + +// 重新启用跟踪进行分析 +MemoryManager::Get().SetTrackAllocations(true); +MemoryManager::Get().GenerateMemoryReport(); +``` + +## 相关文档 + +- [MemoryManager 总览](manager.md) - 返回类总览 diff --git a/docs/api/memory/manager/shutdown.md b/docs/api/memory/manager/shutdown.md new file mode 100644 index 00000000..f631f5bc --- /dev/null +++ b/docs/api/memory/manager/shutdown.md @@ -0,0 +1,35 @@ +# MemoryManager::Shutdown + +```cpp +void Shutdown(); +``` + +关闭内存管理器。执行内存泄漏检测报告，释放系统分配器。应在程序退出前调用。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +#include + +int main() { + MemoryManager::Get().Initialize(); + + // ... 游戏主循环 ... + + // 程序退出前关闭 + MemoryManager::Get().DumpMemoryLeaks(); + MemoryManager::Get().Shutdown(); + + return 0; +} +``` + +## 相关文档 + +- [MemoryManager 总览](manager.md) - 返回类总览 diff --git a/docs/api/memory/memory-linear-allocator.md b/docs/api/memory/memory-linear-allocator.md deleted file mode 100644 index ccc1d8dc..00000000 --- a/docs/api/memory/memory-linear-allocator.md +++ /dev/null @@ -1,82 +0,0 @@ -# LinearAllocator - -**命名空间**: `XCEngine::Memory` - -**类型**: `class` - -**描述**: 线性分配器，提供顺序分配和一次性释放的内存管理，适用于帧分配和临时对象。 - -## 概述 - -`LinearAllocator` 以顺序方式分配内存，每次分配都紧接在上一次分配之后。它不支持单个内存块的释放，只能通过 `Clear()` 一次性清空所有内存。这使得它非常适合作为帧分配器，每帧开始时 Clear 即可。 - -## 公共方法 - -### 构造/析构 - -| 方法 | 描述 | -|------|------| -| `explicit LinearAllocator(size_t size, IAllocator* parent = nullptr)` | 构造函数，预分配指定大小的缓冲区 | -| `~LinearAllocator()` | 析构函数，释放所有内存 | - -### IAllocator 实现 - -| 方法 | 描述 | -|------|------| -| `void* Allocate(size_t size, size_t alignment = 8) override` | 顺序分配内存 | -| `void Free(void* ptr) override` | 空操作（不支持单个释放） | -| `void* Reallocate(void* ptr, size_t newSize) override` | 重新分配（总是分配新内存） | - -### 线性操作 - -| 方法 | 描述 | -|------|------| -| `void Clear()` | 清空所有分配，下一次分配从头开始 | -| `void* GetMarker() const` | 获取当前分配位置标记 | -| `void SetMarker(void* marker)` | 恢复到指定标记位置 | - -### 状态查询 - -| 方法 | 描述 | -|------|------| -| `size_t GetUsedSize() const` | 获取已使用的字节数 | -| `size_t GetCapacity() const` | 获取总容量 | - -### 统计 - -| 方法 | 描述 | -|------|------| -| `size_t GetTotalAllocated() const` | 返回已使用字节数 | -| `size_t GetTotalFreed() const` | 返回 0 | -| `size_t GetPeakAllocated() const` | 返回容量大小 | -| `size_t GetAllocationCount() const` | 返回 0 | - -## 使用示例 - -```cpp -// 创建 1MB 的线性分配器 -auto allocator = std::make_unique(1024 * 1024); - -// 分配临时内存 -void* ptr1 = allocator->Allocate(256); -void* ptr2 = allocator->Allocate(512); -void* ptr3 = allocator->Allocate(128); - -// 保存标记 -void* marker = allocator->GetMarker(); - -// 分配一些临时内存 -void* temp = allocator->Allocate(64); - -// 恢复到标记位置（释放 temp） -allocator->SetMarker(marker); - -// 每帧结束时清空 -allocator->Clear(); -``` - -## 相关文档 - -- [IAllocator](./memory-allocator.md) - 分配器接口 -- [PoolAllocator](./memory-pool-allocator.md) - 内存池分配器 -- [ProxyAllocator](./memory-proxy-allocator.md) - 代理分配器 diff --git a/docs/api/memory/memory-pool-allocator.md b/docs/api/memory/memory-pool-allocator.md deleted file mode 100644 index b3c84004..00000000 --- a/docs/api/memory/memory-pool-allocator.md +++ /dev/null @@ -1,75 +0,0 @@ -# PoolAllocator - -**命名空间**: `XCEngine::Memory` - -**类型**: `class` - -**描述**: 内存池分配器，为固定大小的对象提供高效分配，消除内存碎片。 - -## 概述 - -`PoolAllocator` 预分配一大块内存，并将其划分为等大小的内存块。它维护一个空闲块链表，分配时从链表中取出一块，释放时归还到链表。这使得分配和释放都是 O(1) 时间复杂度，非常适合需要频繁分配/释放同尺寸对象的场景（如对象池）。 - -## 公共方法 - -### 构造/析构 - -| 方法 | 描述 | -|------|------| -| `PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8)` | 构造函数 | -| `~PoolAllocator()` | 析构函数 | - -### IAllocator 实现 - -| 方法 | 描述 | -|------|------| -| `void* Allocate(size_t size, size_t alignment = 0) override` | 分配一个内存块（忽略 size 参数） | -| `void Free(void* ptr) override` | 释放内存块 | -| `void* Reallocate(void* ptr, size_t newSize) override` | 不支持，返回 nullptr | - -### 内存块管理 - -| 方法 | 描述 | -|------|------| -| `bool Contains(void* ptr) const` | 检查指针是否属于此池 | -| `size_t GetBlockSize() const` | 获取内存块大小 | -| `size_t GetFreeBlockCount() const` | 获取空闲块数量 | -| `size_t GetTotalBlockCount() const` | 获取总块数 | - -### 统计 - -| 方法 | 描述 | -|------|------| -| `size_t GetTotalAllocated() const` | 已分配的字节数 | -| `size_t GetTotalFreed() const` | 空闲块占用的字节数 | -| `size_t GetPeakAllocated() const` | 总块数乘以块大小 | -| `size_t GetAllocationCount() const` | 当前已分配块数 | - -## 使用示例 - -```cpp -// 创建一个能分配 100 个 64 字节块的内存池 -PoolAllocator pool(sizeof(MyObject), 100, alignof(MyObject)); - -// 分配（O(1)） -void* block = pool.Allocate(); -// 或者使用 Allocate(size) 但忽略 size -void* block2 = pool.Allocate(sizeof(MyObject)); - -// 检查空闲块 -printf("Free blocks: %zu\n", pool.GetFreeBlockCount()); - -// 释放（O(1)） -pool.Free(block2); - -// 检查指针是否属于此池 -if (pool.Contains(block)) { - // ... -} -``` - -## 相关文档 - -- [IAllocator](./memory-allocator.md) - 分配器接口 -- [LinearAllocator](./memory-linear-allocator.md) - 线性分配器 -- [ProxyAllocator](./memory-proxy-allocator.md) - 代理分配器 diff --git a/docs/api/memory/memory-proxy-allocator.md b/docs/api/memory/memory-proxy-allocator.md deleted file mode 100644 index 30ab1bab..00000000 --- a/docs/api/memory/memory-proxy-allocator.md +++ /dev/null @@ -1,71 +0,0 @@ -# ProxyAllocator - -**命名空间**: `XCEngine::Memory` - -**类型**: `class` - -**描述**: 代理分配器，包装另一个分配器并记录分配统计信息，用于内存跟踪和调试。 - -## 概述 - -`ProxyAllocator` 是对另一个分配器的包装，它将所有分配请求转发给底层分配器，同时记录分配统计信息。这对于分析内存使用模式和调试内存问题非常有用。 - -## 公共方法 - -### 构造 - -| 方法 | 描述 | -|------|------| -| `ProxyAllocator(IAllocator* underlying, const char* name)` | 构造函数，指定底层分配器和名称 | - -### IAllocator 实现 - -| 方法 | 描述 | -|------|------| -| `void* Allocate(size_t size, size_t alignment = 0) override` | 分配并统计 | -| `void Free(void* ptr) override` | 释放并统计 | -| `void* Reallocate(void* ptr, size_t newSize) override` | 重新分配并统计 | - -### 统计 - -| 方法 | 描述 | -|------|------| -| `size_t GetTotalAllocated() const override` | 总分配字节数 | -| `size_t GetTotalFreed() const override` | 总释放字节数 | -| `size_t GetPeakAllocated() const override` | 峰值分配字节数 | -| `size_t GetAllocationCount() const override` | 分配次数 | -| `const Stats& GetStats() const` | 获取详细统计信息 | - -## Stats 结构体 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `totalAllocated` | `size_t` | 累计分配字节数 | -| `totalFreed` | `size_t` | 累计释放字节数 | -| `peakAllocated` | `size_t` | 峰值分配字节数 | -| `allocationCount` | `size_t` | 分配次数 | -| `memoryOverhead` | `size_t` | 额外开销（字节） | - -## 使用示例 - -```cpp -// 包装系统分配器 -IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator(); -ProxyAllocator proxy(sysAlloc, "FrameData"); - -// 使用代理分配器 -void* ptr = proxy.Allocate(1024); - -// 获取统计 -const ProxyAllocator::Stats& stats = proxy.GetStats(); -printf("Total allocated: %zu bytes\n", stats.totalAllocated); -printf("Peak allocated: %zu bytes\n", stats.peakAllocated); -printf("Allocation count: %zu\n", stats.allocationCount); -printf("Current in use: %zu bytes\n", - stats.totalAllocated - stats.totalFreed); -``` - -## 相关文档 - -- [IAllocator](./memory-allocator.md) - 分配器接口 -- [MemoryManager](./memory-manager.md) - 内存管理器 diff --git a/docs/api/memory/memory-overview.md b/docs/api/memory/memory.md similarity index 71% rename from docs/api/memory/memory-overview.md rename to docs/api/memory/memory.md index 520f36e3..dae159f7 100644 --- a/docs/api/memory/memory-overview.md +++ b/docs/api/memory/memory.md @@ -16,21 +16,21 @@ Memory 模块提供了一套完整的内存管理解决方案，包括基础分 | 组件 | 文件 | 描述 | |------|------|------| -| [IAllocator](./memory-allocator.md) | `Allocator.h` | 内存分配器抽象接口 | +| [IAllocator](allocator/allocator.md) | `Allocator.h` | 内存分配器抽象接口 | ### 分配器实现 | 组件 | 文件 | 描述 | |------|------|------| -| [LinearAllocator](./memory-linear-allocator.md) | `LinearAllocator.h` | 线性分配器，适合帧分配 | -| [PoolAllocator](./memory-pool-allocator.md) | `PoolAllocator.h` | 内存池分配器，适合固定大小对象 | -| [ProxyAllocator](./memory-proxy-allocator.md) | `ProxyAllocator.h` | 代理分配器，用于统计和跟踪 | +| [LinearAllocator](linear-allocator/linear-allocator.md) | `LinearAllocator.h` | 线性分配器，适合帧分配 | +| [PoolAllocator](pool-allocator/pool-allocator.md) | `PoolAllocator.h` | 内存池分配器，适合固定大小对象 | +| [ProxyAllocator](proxy-allocator/proxy-allocator.md) | `ProxyAllocator.h` | 代理分配器，用于统计和跟踪 | ### 管理器 | 组件 | 文件 | 描述 | |------|------|------| -| [MemoryManager](./memory-manager.md) | `MemoryManager.h` | 全局内存管理器 | +| [MemoryManager](manager/manager.md) | `MemoryManager.h` | 全局内存管理器 | ## 分配器类型对比 @@ -69,4 +69,4 @@ XE_FREE(linearAlloc, ptr); ## 相关文档 -- [Containers 模块](../containers/container-overview.md) - 使用分配器的容器 +- [Containers 模块](../containers/containers.md) - 使用分配器的容器 diff --git a/docs/api/memory/pool-allocator/allocate.md b/docs/api/memory/pool-allocator/allocate.md new file mode 100644 index 00000000..dace6367 --- /dev/null +++ b/docs/api/memory/pool-allocator/allocate.md @@ -0,0 +1,37 @@ +# PoolAllocator::Allocate + +```cpp +void* Allocate(size_t size, size_t alignment = 0) override; +``` + +从内存池中分配一个空闲块。此方法忽略 `size` 参数，始终分配一个固定大小的块。如果池中没有空闲块，返回 `nullptr`。分配操作从空闲链表头部取出一个块。 + +**参数：** +- `size` - 被忽略（始终分配固定块大小） +- `alignment` - 被忽略（构造时确定） + +**返回：** 分配成功返回块指针，池空返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +PoolAllocator pool(sizeof(int) * 100, 50, alignof(int)); + +// 分配（忽略 size 参数） +void* block1 = pool.Allocate(1); // 分配 1 字节 +void* block2 = pool.Allocate(10000); // 也分配一块 + +if (block1 && block2) { + // 使用分配的内存块 + int* arr = static_cast(block1); + arr[0] = 42; +} +``` + +## 相关文档 + +- [PoolAllocator 总览](pool-allocator.md) - 返回类总览 diff --git a/docs/api/memory/pool-allocator/contains.md b/docs/api/memory/pool-allocator/contains.md new file mode 100644 index 00000000..0f078e1f --- /dev/null +++ b/docs/api/memory/pool-allocator/contains.md @@ -0,0 +1,38 @@ +# PoolAllocator::Contains + +```cpp +bool Contains(void* ptr) const; +``` + +检查给定的指针是否属于此内存池的地址范围。由于池在构造时预分配连续内存，可通过指针地址区间判断所有权。此方法用于调试和内存验证。 + +**参数：** +- `ptr` - 要检查的指针 + +**返回：** 指针属于此池返回 `true`，否则返回 `false` + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +PoolAllocator pool(sizeof(int), 100); + +void* inside = pool.Allocate(); +void* outside = ::operator new(sizeof(int)); + +if (pool.Contains(inside)) { + // inside 属于此内存池，可以安全 Free +} + +if (!pool.Contains(outside)) { + // outside 不属于此池，不能调用 pool.Free() + ::operator delete(outside); +} +``` + +## 相关文档 + +- [PoolAllocator 总览](pool-allocator.md) - 返回类总览 diff --git a/docs/api/memory/pool-allocator/free.md b/docs/api/memory/pool-allocator/free.md new file mode 100644 index 00000000..6e1849b5 --- /dev/null +++ b/docs/api/memory/pool-allocator/free.md @@ -0,0 +1,38 @@ +# PoolAllocator::Free + +```cpp +void Free(void* ptr) override; +``` + +将内存块归还到空闲链表中。如果 `ptr` 为 `nullptr` 则无效果。释放操作将块插入空闲链表头部。必须传入从此池分配的指针，传入外部指针会导致未定义行为。 + +**参数：** +- `ptr` - 指向要释放的内存块 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +PoolAllocator pool(sizeof(int), 100); + +void* block = pool.Allocate(); +if (block) { + int* num = static_cast(block); + *num = 123; + + pool.Free(block); // 归还到空闲链表 + block = nullptr; +} + +// 检查空闲块数量 +size_t freeCount = pool.GetFreeBlockCount(); +``` + +## 相关文档 + +- [PoolAllocator 总览](pool-allocator.md) - 返回类总览 diff --git a/docs/api/memory/pool-allocator/get-block-size.md b/docs/api/memory/pool-allocator/get-block-size.md new file mode 100644 index 00000000..65c9cead --- /dev/null +++ b/docs/api/memory/pool-allocator/get-block-size.md @@ -0,0 +1,31 @@ +# PoolAllocator::GetBlockSize + +```cpp +size_t GetBlockSize() const; +``` + +返回内存池中每个内存块的大小。此值在构造时确定，之后保持不变。 + +**参数：** 无 + +**返回：** 每个内存块的字节大小 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +PoolAllocator pool(sizeof(int) * 100, 50); + +size_t blockSize = pool.GetBlockSize(); // 400 字节 + +void* block = pool.Allocate(); +int* arr = static_cast(block); +// arr 指向的大小为 blockSize 字节的内存块 +``` + +## 相关文档 + +- [PoolAllocator 总览](pool-allocator.md) - 返回类总览 diff --git a/docs/api/memory/pool-allocator/get-free-block-count.md b/docs/api/memory/pool-allocator/get-free-block-count.md new file mode 100644 index 00000000..82ec3e92 --- /dev/null +++ b/docs/api/memory/pool-allocator/get-free-block-count.md @@ -0,0 +1,40 @@ +# PoolAllocator::GetFreeBlockCount + +```cpp +size_t GetFreeBlockCount() const; +``` + +返回当前空闲块的的数量。每次 `Allocate` 成功后减 1，每次 `Free` 后加 1。 + +**参数：** 无 + +**返回：** 当前可分配的空闲块数量 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +PoolAllocator pool(sizeof(int), 100); + +size_t initial = pool.GetFreeBlockCount(); // 100 + +void* blocks[10]; +for (int i = 0; i < 10; ++i) { + blocks[i] = pool.Allocate(); +} + +size_t after = pool.GetFreeBlockCount(); // 90 + +for (int i = 0; i < 5; ++i) { + pool.Free(blocks[i]); +} + +size_t final = pool.GetFreeBlockCount(); // 95 +``` + +## 相关文档 + +- [PoolAllocator 总览](pool-allocator.md) - 返回类总览 diff --git a/docs/api/memory/pool-allocator/get-total-block-count.md b/docs/api/memory/pool-allocator/get-total-block-count.md new file mode 100644 index 00000000..45800fc1 --- /dev/null +++ b/docs/api/memory/pool-allocator/get-total-block-count.md @@ -0,0 +1,34 @@ +# PoolAllocator::GetTotalBlockCount + +```cpp +size_t GetTotalBlockCount() const; +``` + +返回内存池中的总块数。此值在构造时确定，之后保持不变。 + +**参数：** 无 + +**返回：** 内存池的总块数 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +PoolAllocator pool(sizeof(int), 100); + +size_t total = pool.GetTotalBlockCount(); // 100 +size_t free = pool.GetFreeBlockCount(); // 100 + +void* block = pool.Allocate(); +size_t freeAfter = pool.GetFreeBlockCount(); // 99 + +pool.Free(block); +size_t freeRestored = pool.GetFreeBlockCount(); // 100 +``` + +## 相关文档 + +- [PoolAllocator 总览](pool-allocator.md) - 返回类总览 diff --git a/docs/api/memory/pool-allocator/pool-allocator.md b/docs/api/memory/pool-allocator/pool-allocator.md new file mode 100644 index 00000000..0c18964b --- /dev/null +++ b/docs/api/memory/pool-allocator/pool-allocator.md @@ -0,0 +1,44 @@ +# PoolAllocator::PoolAllocator / ~PoolAllocator + +```cpp +PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8); +~PoolAllocator() override; +``` + +构造内存池分配器，预分配 `poolSize` 个大小为 `blockSize` 字节的内存块。内存块按 `alignment` 对齐（默认 8 字节）。内部维护一个空闲块链表来管理分配。析构函数释放整个内存池。 + +**参数：** +- `blockSize` - 每个内存块的大小（字节） +- `poolSize` - 内存池中总块数 +- `alignment` - 对齐要求，默认为 8 + +**返回：** 无 + +**复杂度：** O(n)，需要预分配所有块 + +**示例：** + +```cpp +#include + +struct Particle { + float x, y, z; + float vx, vy, vz; + float life; +}; + +// 创建一个能容纳 1000 个 Particle 的内存池，16 字节对齐 +PoolAllocator pool(sizeof(Particle), 1000, alignof(Particle)); + +size_t blockSize = pool.GetBlockSize(); // sizeof(Particle) +size_t total = pool.GetTotalBlockCount(); // 1000 +size_t free = pool.GetFreeBlockCount(); // 1000 + +// 分配和释放 +void* block = pool.Allocate(); +pool.Free(block); +``` + +## 相关文档 + +- [PoolAllocator 总览](pool-allocator.md) - 返回类总览 diff --git a/docs/api/memory/pool-allocator/reallocate.md b/docs/api/memory/pool-allocator/reallocate.md new file mode 100644 index 00000000..069730e6 --- /dev/null +++ b/docs/api/memory/pool-allocator/reallocate.md @@ -0,0 +1,35 @@ +# PoolAllocator::Reallocate + +```cpp +void* Reallocate(void* ptr, size_t newSize) override; +``` + +内存池分配器不支持重新分配。此方法始终返回 `nullptr`，原内存块保持不变。 + +**参数：** +- `ptr` - 不被使用 +- `newSize` - 不被使用 + +**返回：** 始终返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +#include + +PoolAllocator pool(sizeof(int), 100); +void* block = pool.Allocate(); + +// Reallocate 不支持 +void* newBlock = pool.Reallocate(block, 256); +if (!newBlock) { + // 内存池不支持重新分配 + // 原 block 仍然有效 +} +``` + +## 相关文档 + +- [PoolAllocator 总览](pool-allocator.md) - 返回类总览 diff --git a/docs/api/memory/proxy-allocator/allocate.md b/docs/api/memory/proxy-allocator/allocate.md new file mode 100644 index 00000000..3973c371 --- /dev/null +++ b/docs/api/memory/proxy-allocator/allocate.md @@ -0,0 +1,37 @@ +# ProxyAllocator::Allocate + +```cpp +void* Allocate(size_t size, size_t alignment = 0) override; +``` + +分配内存并记录统计。调用转发到底层分配器，同时递增分配计数和总分配字节数，并更新峰值记录。 + +**参数：** +- `size` - 请求的字节数 +- `alignment` - 内存对齐要求 + +**返回：** 分配成功返回指针，失败返回 `nullptr` + +**复杂度：** O(1)（底层分配器复杂度 + 统计更新） + +**示例：** + +```cpp +#include +#include + +IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator(); +ProxyAllocator proxy(sysAlloc, "TrackedAlloc"); + +void* p1 = proxy.Allocate(100); +void* p2 = proxy.Allocate(200); +void* p3 = proxy.Allocate(300, 16); + +const auto& stats = proxy.GetStats(); +printf("Total: %zu, Peak: %zu, Count: %zu\n", + stats.totalAllocated, stats.peakAllocated, stats.allocationCount); +``` + +## 相关文档 + +- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览 diff --git a/docs/api/memory/proxy-allocator/free.md b/docs/api/memory/proxy-allocator/free.md new file mode 100644 index 00000000..0c575ff0 --- /dev/null +++ b/docs/api/memory/proxy-allocator/free.md @@ -0,0 +1,39 @@ +# ProxyAllocator::Free + +```cpp +void Free(void* ptr) override; +``` + +释放内存并记录统计。调用转发到底层分配器，同时更新统计信息：增加总释放计数（而非字节大小，因为 ProxyAllocator 不记录释放的字节数），并递减当前分配计数。 + +**参数：** +- `ptr` - 指向要释放的内存块 + +**返回：** 无 + +**复杂度：** O(1)（底层释放 + 统计更新） + +**示例：** + +```cpp +#include +#include + +IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator(); +ProxyAllocator proxy(sysAlloc, "TrackedAlloc"); + +void* p1 = proxy.Allocate(512); +void* p2 = proxy.Allocate(256); + +proxy.Free(p1); +proxy.Free(p2); + +const auto& stats = proxy.GetStats(); +printf("Total allocated: %zu, Total freed: %zu, Current: %zu\n", + stats.totalAllocated, stats.totalFreed, + stats.totalAllocated - stats.totalFreed); +``` + +## 相关文档 + +- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览 diff --git a/docs/api/memory/proxy-allocator/get-stats.md b/docs/api/memory/proxy-allocator/get-stats.md new file mode 100644 index 00000000..693041c7 --- /dev/null +++ b/docs/api/memory/proxy-allocator/get-stats.md @@ -0,0 +1,40 @@ +# ProxyAllocator::GetStats + +```cpp +const Stats& GetStats() const; +``` + +返回详细的统计信息结构体引用。包含累计分配、累计释放、峰值分配、分配次数和额外开销。返回 const 引用，无锁开销（内部已有互斥保护）。 + +**参数：** 无 + +**返回：** Stats 结构体 const 引用 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator(); +ProxyAllocator proxy(sysAlloc, "FrameData"); + +proxy.Allocate(1024); +proxy.Allocate(512); +proxy.Free(proxy.Allocate(256)); + +const ProxyAllocator::Stats& stats = proxy.GetStats(); +printf("Total allocated: %zu bytes\n", stats.totalAllocated); +printf("Total freed: %zu bytes\n", stats.totalFreed); +printf("Peak allocated: %zu bytes\n", stats.peakAllocated); +printf("Allocation count: %zu\n", stats.allocationCount); +printf("Memory overhead: %zu bytes\n", stats.memoryOverhead); +printf("Current in use: %zu bytes\n", + stats.totalAllocated - stats.totalFreed); +``` + +## 相关文档 + +- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览 diff --git a/docs/api/memory/proxy-allocator/proxy-allocator.md b/docs/api/memory/proxy-allocator/proxy-allocator.md new file mode 100644 index 00000000..fe8875b8 --- /dev/null +++ b/docs/api/memory/proxy-allocator/proxy-allocator.md @@ -0,0 +1,36 @@ +# ProxyAllocator::ProxyAllocator + +```cpp +ProxyAllocator(IAllocator* underlying, const char* name); +``` + +构造一个代理分配器，包装底层分配器并记录分配统计。所有 `Allocate`、`Free`、`Reallocate` 调用都会被转发到底层分配器，同时记录统计信息。名称用于日志和报告。 + +**参数：** +- `underlying` - 被包装的底层分配器，不能为 `nullptr` +- `name` - 代理分配器的名称字符串 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +#include +#include + +MemoryManager::Get().Initialize(); + +// 使用系统分配器作为底层 +IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator(); +ProxyAllocator proxy(sysAlloc, "TempAllocations"); + +// 通过代理分配 +void* ptr = proxy.Allocate(1024); +proxy.Free(ptr); +``` + +## 相关文档 + +- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览 diff --git a/docs/api/memory/proxy-allocator/reallocate.md b/docs/api/memory/proxy-allocator/reallocate.md new file mode 100644 index 00000000..80e44c34 --- /dev/null +++ b/docs/api/memory/proxy-allocator/reallocate.md @@ -0,0 +1,40 @@ +# ProxyAllocator::Reallocate + +```cpp +void* Reallocate(void* ptr, size_t newSize) override; +``` + +重新分配内存并记录统计。调用转发到底层分配器。此方法仅更新 totalAllocated 统计为新大小，不记录原内存的释放（这是简化实现）。如果底层分配失败返回 `nullptr`，但原指针仍然有效。 + +**参数：** +- `ptr` - 现有内存块指针 +- `newSize` - 新的字节大小 + +**返回：** 成功返回新指针，失败返回 `nullptr` + +**复杂度：** O(n)（底层分配器 + 数据复制） + +**示例：** + +```cpp +#include +#include + +IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator(); +ProxyAllocator proxy(sysAlloc, "TrackedAlloc"); + +void* p1 = proxy.Allocate(128); +void* p2 = proxy.Reallocate(p1, 256); + +if (p2) { + // 重新分配成功 + const auto& stats = proxy.GetStats(); + printf("Reallocated: %zu bytes total\n", stats.totalAllocated); +} else { + // 失败，p1 仍然有效 +} +``` + +## 相关文档 + +- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览 diff --git a/docs/api/resources/resources-asyncloader.md b/docs/api/resources/asyncloader/asyncloader.md similarity index 80% rename from docs/api/resources/resources-asyncloader.md rename to docs/api/resources/asyncloader/asyncloader.md index 2f66c585..8c939681 100644 --- a/docs/api/resources/resources-asyncloader.md +++ b/docs/api/resources/asyncloader/asyncloader.md @@ -28,6 +28,22 @@ | `settings` | `ImportSettings*` | 导入设置（可为 nullptr） | | `requestId` | `Core::uint64` | 请求唯一标识符 | +### 构造方法 + +| 方法 | 描述 | +|------|------| +| `LoadRequest()` | 默认构造 | +| `LoadRequest(const Containers::String& p, ResourceType t, std::function cb, ImportSettings* s = nullptr)` | 从参数构造 | +| `LoadRequest(LoadRequest&& other) noexcept` | 移动构造 | +| `LoadRequest(const LoadRequest&) = default` | 拷贝构造 | + +### 赋值 + +| 方法 | 描述 | +|------|------| +| `LoadRequest& operator=(LoadRequest&& other) noexcept` | 移动赋值 | +| `LoadRequest& operator=(const LoadRequest&) = default` | 拷贝赋值 | + ## 公共方法 ### 生命周期 @@ -95,5 +111,6 @@ AsyncLoader::Get().Shutdown(); ## 相关文档 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 -- [IResourceLoader](./resources-iloader.md) - 资源加载器接口 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [IResourceLoader](../iloader/iloader.md) - 资源加载器接口 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/asyncloader/cancelall.md b/docs/api/resources/asyncloader/cancelall.md new file mode 100644 index 00000000..8aa163da --- /dev/null +++ b/docs/api/resources/asyncloader/cancelall.md @@ -0,0 +1,26 @@ +# AsyncLoader::CancelAll + +```cpp +void CancelAll() +``` + +取消所有待处理的加载请求。清空待处理队列，不会触发任何回调。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +// 场景切换时取消所有加载请求 +void OnSceneChange() { + AsyncLoader::Get().CancelAll(); +} +``` + +## 相关文档 + +- [AsyncLoader 总览](asyncloader.md) - 返回类总览 diff --git a/docs/api/resources/asyncloader/getprogress.md b/docs/api/resources/asyncloader/getprogress.md new file mode 100644 index 00000000..3a8cc2b0 --- /dev/null +++ b/docs/api/resources/asyncloader/getprogress.md @@ -0,0 +1,24 @@ +# AsyncLoader::GetProgress + +```cpp +float GetProgress() const +``` + +获取整体加载进度。返回已完成加载数与总请求数的比值，范围 0.0f ~ 1.0f。 + +**参数：** 无 + +**返回：** 加载进度（0.0f ~ 1.0f） + +**复杂度：** O(1) + +**示例：** + +```cpp +float progress = AsyncLoader::Get().GetProgress(); +printf("Loading: %.1f%%\n", progress * 100.0f); +``` + +## 相关文档 + +- [AsyncLoader 总览](asyncloader.md) - 返回类总览 diff --git a/docs/api/resources/asyncloader/submit.md b/docs/api/resources/asyncloader/submit.md new file mode 100644 index 00000000..e05f329a --- /dev/null +++ b/docs/api/resources/asyncloader/submit.md @@ -0,0 +1,35 @@ +# AsyncLoader::Submit + +```cpp +void Submit(const Containers::String& path, ResourceType type, + std::function callback) +void Submit(const Containers::String& path, ResourceType type, ImportSettings* settings, + std::function callback) +``` + +提交异步加载请求。将请求加入待处理队列，由工作线程在后台执行加载。 + +**参数：** +- `path` - 资源路径 +- `type` - 资源类型 +- `settings` - 导入设置（可为 nullptr） +- `callback` - 加载完成回调 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +AsyncLoader::Get().Submit("textures/player.png", ResourceType::Texture, + [](LoadResult result) { + if (result.success) { + ResourceHandle tex(result.resource); + } + }); +``` + +## 相关文档 + +- [AsyncLoader 总览](asyncloader.md) - 返回类总览 diff --git a/docs/api/resources/asyncloader/update.md b/docs/api/resources/asyncloader/update.md new file mode 100644 index 00000000..946f7031 --- /dev/null +++ b/docs/api/resources/asyncloader/update.md @@ -0,0 +1,27 @@ +# AsyncLoader::Update + +```cpp +void Update() +``` + +更新函数，在主线程调用。处理完成的加载请求，将结果从完成队列取出并在主线程执行回调。必须在主线程调用以确保线程安全。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n)，n 为完成队列中的请求数 + +**示例：** + +```cpp +// 在主循环中调用 +while (running) { + AsyncLoader::Get().Update(); // 分发完成的加载回调 + RenderFrame(); +} +``` + +## 相关文档 + +- [AsyncLoader 总览](asyncloader.md) - 返回类总览 diff --git a/docs/api/resources/resources-audioclip.md b/docs/api/resources/audioclip/audioclip.md similarity index 94% rename from docs/api/resources/resources-audioclip.md rename to docs/api/resources/audioclip/audioclip.md index 700ce893..5aa7aa65 100644 --- a/docs/api/resources/resources-audioclip.md +++ b/docs/api/resources/audioclip/audioclip.md @@ -127,5 +127,6 @@ bool loop = sfx->IsLoop(); ## 相关文档 -- [IResource](./resources-iresource.md) - 资源基类 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 +- [IResource](../iresource/iresource.md) - 资源基类 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/audioclip/setaudiodata.md b/docs/api/resources/audioclip/setaudiodata.md new file mode 100644 index 00000000..e7d147f3 --- /dev/null +++ b/docs/api/resources/audioclip/setaudiodata.md @@ -0,0 +1,29 @@ +# AudioClip::SetAudioData + +```cpp +void SetAudioData(const Containers::Array& data) +``` + +设置音频原始样本数据。 + +**参数：** +- `data` - 音频数据字节数组 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +auto wavData = ResourceFileSystem::Get().ReadResource("sounds/explosion.wav"); +AudioClip* clip = new AudioClip(); +clip->SetAudioData(wavData); +clip->SetSampleRate(44100); +clip->SetChannels(2); +clip->SetBitsPerSample(16); +``` + +## 相关文档 + +- [AudioClip 总览](audioclip.md) - 返回类总览 diff --git a/docs/api/resources/dependencygraph/adddependency.md b/docs/api/resources/dependencygraph/adddependency.md new file mode 100644 index 00000000..301eccbb --- /dev/null +++ b/docs/api/resources/dependencygraph/adddependency.md @@ -0,0 +1,27 @@ +# ResourceDependencyGraph::AddDependency + +```cpp +void AddDependency(ResourceGUID owner, ResourceGUID dependency) +``` + +添加资源依赖关系。表示 `owner` 资源依赖 `dependency` 资源。依赖关系是单向的。 + +**参数：** +- `owner` - 拥有依赖关系的主体资源 +- `dependency` - 被依赖的资源 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +// Material 依赖 Texture 和 Shader +graph.AddDependency(materialGuid, textureGuid); +graph.AddDependency(materialGuid, shaderGuid); +``` + +## 相关文档 + +- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览 diff --git a/docs/api/resources/dependencygraph/addnode.md b/docs/api/resources/dependencygraph/addnode.md new file mode 100644 index 00000000..a8bd4ac6 --- /dev/null +++ b/docs/api/resources/dependencygraph/addnode.md @@ -0,0 +1,27 @@ +# ResourceDependencyGraph::AddNode + +```cpp +void AddNode(ResourceGUID guid, ResourceType type) +``` + +向依赖图中添加一个新节点。如果节点已存在则忽略。 + +**参数：** +- `guid` - 资源的全局唯一标识符 +- `type` - 资源类型 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceDependencyGraph graph; +graph.AddNode(textureGuid, ResourceType::Texture); +graph.AddNode(materialGuid, ResourceType::Material); +``` + +## 相关文档 + +- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览 diff --git a/docs/api/resources/resources-dependencygraph.md b/docs/api/resources/dependencygraph/dependencygraph.md similarity index 94% rename from docs/api/resources/resources-dependencygraph.md rename to docs/api/resources/dependencygraph/dependencygraph.md index f9141ba8..d45b9df8 100644 --- a/docs/api/resources/resources-dependencygraph.md +++ b/docs/api/resources/dependencygraph/dependencygraph.md @@ -10,6 +10,16 @@ `ResourceDependencyGraph` 维护了所有资源之间的依赖关系图。它支持添加/移除依赖节点、查询依赖关系、循环依赖检测、拓扑排序（用于正确的加载/卸载顺序）等功能。 +## DependencyNode 结构体 + +| 成员 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 资源全局唯一标识符 | +| `type` | `ResourceType` | 资源类型 | +| `dependencies` | `Containers::Array` | 此资源依赖的其他资源 | +| `dependents` | `Containers::Array` | 依赖此资源的其他资源 | +| `refCount` | `Core::uint32` | 引用计数 | + ## 公共方法 ### 节点管理 @@ -57,16 +67,6 @@ |------|------| | `void Clear()` | 清空所有节点和依赖关系 | -## DependencyNode 结构体 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `guid` | `ResourceGUID` | 资源全局唯一标识符 | -| `type` | `ResourceType` | 资源类型 | -| `dependencies` | `Containers::Array` | 此资源依赖的其他资源 | -| `dependents` | `Containers::Array` | 依赖此资源的其他资源 | -| `refCount` | `Core::uint32` | 引用计数 | - ## 使用示例 ```cpp @@ -106,5 +106,6 @@ graph.DecrementRefCount(guid); ## 相关文档 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 -- [ResourceHandle](./resources-resourcehandle.md) - 资源句柄 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/dependencygraph/getdependencies.md b/docs/api/resources/dependencygraph/getdependencies.md new file mode 100644 index 00000000..733fdd2e --- /dev/null +++ b/docs/api/resources/dependencygraph/getdependencies.md @@ -0,0 +1,25 @@ +# ResourceDependencyGraph::GetDependencies + +```cpp +Containers::Array GetDependencies(ResourceGUID guid) const +``` + +获取指定资源直接依赖的所有资源列表。不包含传递依赖。 + +**参数：** +- `guid` - 资源全局唯一标识符 + +**返回：** 直接依赖的 GUID 数组 + +**复杂度：** O(k)，k 为直接依赖数量 + +**示例：** + +```cpp +auto deps = graph.GetDependencies(materialGuid); +// 返回 Material 直接依赖的资源（Texture、Shader 等） +``` + +## 相关文档 + +- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览 diff --git a/docs/api/resources/dependencygraph/hascirculardependency.md b/docs/api/resources/dependencygraph/hascirculardependency.md new file mode 100644 index 00000000..b358cd76 --- /dev/null +++ b/docs/api/resources/dependencygraph/hascirculardependency.md @@ -0,0 +1,31 @@ +# ResourceDependencyGraph::HasCircularDependency + +```cpp +bool HasCircularDependency(ResourceGUID guid, Containers::Array& outCycle) const +``` + +检测是否存在以指定节点为起点的循环依赖。使用 DFS 遍历依赖图，检测回路。 + +**参数：** +- `guid` - 起始节点 +- `outCycle` - 输出参数，检测到的循环路径（包含形成环的节点 GUID） + +**返回：** 如果存在循环依赖则返回 true，否则返回 false + +**复杂度：** O(n + e) + +**示例：** + +```cpp +Containers::Array cycle; +if (graph.HasCircularDependency(guid, cycle)) { + printf("Circular dependency detected: "); + for (const auto& g : cycle) { + printf("%llu ", g.value); + } +} +``` + +## 相关文档 + +- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览 diff --git a/docs/api/resources/dependencygraph/topologicalsort.md b/docs/api/resources/dependencygraph/topologicalsort.md new file mode 100644 index 00000000..9a539adc --- /dev/null +++ b/docs/api/resources/dependencygraph/topologicalsort.md @@ -0,0 +1,28 @@ +# ResourceDependencyGraph::TopologicalSort + +```cpp +Containers::Array TopologicalSort() const +``` + +拓扑排序。按依赖顺序返回所有节点，确保被依赖的资源排在依赖者之前。用于确定正确的加载和卸载顺序。 + +**参数：** 无 + +**返回：** 按依赖顺序排序的 GUID 数组 + +**复杂度：** O(n + e)，n 为节点数，e 为边数 + +**示例：** + +```cpp +auto loadOrder = graph.TopologicalSort(); +// loadOrder[0] 是最底层依赖（如 Texture） +// loadOrder[last] 是最顶层资源（如 Material） +for (const auto& guid : loadOrder) { + ResourceManager::Get().Load(guid); +} +``` + +## 相关文档 + +- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览 diff --git a/docs/api/resources/filesystem/exists.md b/docs/api/resources/filesystem/exists.md new file mode 100644 index 00000000..aedf8184 --- /dev/null +++ b/docs/api/resources/filesystem/exists.md @@ -0,0 +1,26 @@ +# ResourceFileSystem::Exists + +```cpp +bool Exists(const Containers::String& relativePath) const +``` + +检查资源文件是否存在。优先在归档包中查找，其次在目录中查找。 + +**参数：** +- `relativePath` - 资源相对路径 + +**返回：** 如果存在则返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +if (ResourceFileSystem::Get().Exists("shaders/default.vert")) { + // 文件存在... +} +``` + +## 相关文档 + +- [ResourceFileSystem 总览](filesystem.md) - 返回类总览 diff --git a/docs/api/resources/resources-filesystem.md b/docs/api/resources/filesystem/filesystem.md similarity index 75% rename from docs/api/resources/resources-filesystem.md rename to docs/api/resources/filesystem/filesystem.md index 02f6ef79..6806bdac 100644 --- a/docs/api/resources/resources-filesystem.md +++ b/docs/api/resources/filesystem/filesystem.md @@ -10,6 +10,12 @@ `ResourceFileSystem` 实现了虚拟资源文件系统，支持从多个目录和归档包（如 `.zip`、`.pak`）中查找和读取资源。它通过 `IArchive` 接口支持不同的归档格式，并提供资源信息缓存。 +## 单例访问 + +| 方法 | 描述 | +|------|------| +| `static ResourceFileSystem& Get()` | 获取单例实例 | + ## IArchive 接口 抽象归档接口，用于封装单个归档包或目录的读取操作。 @@ -20,10 +26,10 @@ |------|------| | `virtual bool Open(const Containers::String& path)` | 打开归档 | | `virtual void Close()` | 关闭归档 | -| `virtual bool Read(fileName, buffer, size, offset)` | 从归档中读取文件 | -| `virtual size_t GetSize(fileName)` | 获取文件大小 | -| `virtual bool Exists(fileName)` | 检查文件是否存在 | -| `virtual void Enumerate(pattern, outFiles)` | 枚举匹配的文件 | +| `virtual bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const` | 从归档中读取文件 | +| `virtual size_t GetSize(const Containers::String& fileName) const` | 获取文件大小 | +| `virtual bool Exists(const Containers::String& fileName) const` | 检查文件是否存在 | +| `virtual void Enumerate(const Containers::String& pattern, Containers::Array& outFiles) const` | 枚举匹配的文件 | | `virtual bool IsValid() const` | 是否有效 | ## ResourceInfo 结构体 @@ -36,12 +42,6 @@ | `inArchive` | `bool` | 是否在归档包中 | | `archivePath` | `Containers::String` | 所属归档路径 | -## 单例访问 - -| 方法 | 描述 | -|------|------| -| `static ResourceFileSystem& Get()` | 获取单例实例 | - ## 公共方法 ### 生命周期 @@ -63,22 +63,20 @@ | 方法 | 描述 | |------|------| -| `bool FindResource(const Containers::String& relativePath, Containers::String& outAbsolutePath)` | 查找资源的绝对路径 | -| `bool Exists(const Containers::String& relativePath)` | 检查资源是否存在 | -| `Containers::Array ReadResource(const Containers::String& relativePath)` | 读取资源文件内容（字节数组） | +| `bool FindResource(const Containers::String& relativePath, Containers::String& outAbsolutePath) const` | 查找资源的绝对路径 | +| `bool Exists(const Containers::String& relativePath) const` | 检查资源是否存在 | +| `Containers::Array ReadResource(const Containers::String& relativePath) const` | 读取资源文件内容（字节数组） | ### 资源信息 | 方法 | 描述 | |------|------| -| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo)` | 获取资源信息 | -| `void EnumerateResources(const Containers::String& pattern, Containers::Array& outResources)` | 枚举匹配的资源 | +| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源信息 | +| `void EnumerateResources(const Containers::String& pattern, Containers::Array& outResources) const` | 枚举匹配的资源 | ## 使用示例 ```cpp -#include - // 初始化资源文件系统 ResourceFileSystem::Get().Initialize("resources/"); @@ -114,5 +112,6 @@ ResourceFileSystem::Get().Shutdown(); ## 相关文档 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 -- [IResourceLoader](./resources-iloader.md) - 资源加载器 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [IResourceLoader](../iloader/iloader.md) - 资源加载器 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/filesystem/initialize.md b/docs/api/resources/filesystem/initialize.md new file mode 100644 index 00000000..6ac2d768 --- /dev/null +++ b/docs/api/resources/filesystem/initialize.md @@ -0,0 +1,24 @@ +# ResourceFileSystem::Initialize + +```cpp +void Initialize(const Containers::String& rootPath) +``` + +初始化资源文件系统。设置资源根目录，准备虚拟文件系统。 + +**参数：** +- `rootPath` - 资源根目录路径 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceFileSystem::Get().Initialize("resources/"); +``` + +## 相关文档 + +- [ResourceFileSystem 总览](filesystem.md) - 返回类总览 diff --git a/docs/api/resources/filesystem/readresource.md b/docs/api/resources/filesystem/readresource.md new file mode 100644 index 00000000..fd9e0516 --- /dev/null +++ b/docs/api/resources/filesystem/readresource.md @@ -0,0 +1,27 @@ +# ResourceFileSystem::ReadResource + +```cpp +Containers::Array ReadResource(const Containers::String& relativePath) const +``` + +读取资源文件内容。优先从归档包中读取，其次从目录中查找。 + +**参数：** +- `relativePath` - 资源相对路径 + +**返回：** 文件内容的字节数组，读取失败返回空数组 + +**复杂度：** O(n)，n 为文件大小 + +**示例：** + +```cpp +auto data = ResourceFileSystem::Get().ReadResource("textures/player.png"); +if (!data.Empty()) { + // 使用数据... +} +``` + +## 相关文档 + +- [ResourceFileSystem 总览](filesystem.md) - 返回类总览 diff --git a/docs/api/resources/iloader/canload.md b/docs/api/resources/iloader/canload.md new file mode 100644 index 00000000..a2bf4a3a --- /dev/null +++ b/docs/api/resources/iloader/canload.md @@ -0,0 +1,31 @@ +# IResourceLoader::CanLoad + +```cpp +bool CanLoad(const Containers::String& path) const +``` + +检查此加载器是否能加载指定路径的资源。通过比对路径扩展名与支持列表判断。 + +**参数：** +- `path` - 资源路径 + +**返回：** 如果扩展名在支持列表中则返回 true + +**复杂度：** O(k)，k 为扩展名数量 + +**示例：** + +```cpp +bool TextureLoader::CanLoad(const Containers::String& path) const { + Containers::String ext = GetExtension(path); + auto supported = GetSupportedExtensions(); + for (const auto& s : supported) { + if (ext == s) return true; + } + return false; +} +``` + +## 相关文档 + +- [IResourceLoader 总览](iloader.md) - 返回类总览 diff --git a/docs/api/resources/iloader/getdefaultsettings.md b/docs/api/resources/iloader/getdefaultsettings.md new file mode 100644 index 00000000..60daecad --- /dev/null +++ b/docs/api/resources/iloader/getdefaultsettings.md @@ -0,0 +1,25 @@ +# IResourceLoader::GetDefaultSettings + +```cpp +ImportSettings* GetDefaultSettings() const = 0 +``` + +获取此加载器的默认导入设置。纯虚方法，子类返回其特有的默认设置实例。 + +**参数：** 无 + +**返回：** 默认 `ImportSettings` 指针，调用者不持有所有权 + +**复杂度：** O(1) + +**示例：** + +```cpp +ImportSettings* TextureLoader::GetDefaultSettings() const { + return new TextureImportSettings(); +} +``` + +## 相关文档 + +- [IResourceLoader 总览](iloader.md) - 返回类总览 diff --git a/docs/api/resources/iloader/getsupportedextensions.md b/docs/api/resources/iloader/getsupportedextensions.md new file mode 100644 index 00000000..11c796d7 --- /dev/null +++ b/docs/api/resources/iloader/getsupportedextensions.md @@ -0,0 +1,25 @@ +# IResourceLoader::GetSupportedExtensions + +```cpp +Containers::Array GetSupportedExtensions() const +``` + +获取此加载器支持的文件扩展名列表。用于 `CanLoad` 判断和编辑器中资源类型识别。 + +**参数：** 无 + +**返回：** 支持的扩展名数组（如 `{".png", ".jpg", ".bmp"}`） + +**复杂度：** O(1) + +**示例：** + +```cpp +Containers::Array TextureLoader::GetSupportedExtensions() const { + return {".png", ".jpg", ".jpeg", ".bmp", ".tga", ".dds"}; +} +``` + +## 相关文档 + +- [IResourceLoader 总览](iloader.md) - 返回类总览 diff --git a/docs/api/resources/iloader/iloader.md b/docs/api/resources/iloader/iloader.md new file mode 100644 index 00000000..d1f2880c --- /dev/null +++ b/docs/api/resources/iloader/iloader.md @@ -0,0 +1,115 @@ +# IResourceLoader + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` (abstract) + +**描述**: 资源加载器抽象接口，定义了资源加载的标准协议。每个资源类型需要提供对应的加载器实现。 + +## 概述 + +`IResourceLoader` 是资源加载系统的核心抽象接口。它定义了同步和异步加载资源的方法，以及资源类型的查询。`ResourceManager` 通过注册加载器来支持不同类型资源的加载。 + +## LoadResult 结构体 + +加载操作的返回值结构体。 + +```cpp +struct LoadResult { + IResource* resource = nullptr; + bool success = false; + Containers::String errorMessage; + LoadResult() = default; + explicit LoadResult(IResource* res) : resource(res), success(res != nullptr) {} + explicit LoadResult(const Containers::String& error) : success(false), errorMessage(error) {} + explicit LoadResult(bool inSuccess, const Containers::String& error = "") + : success(inSuccess), errorMessage(error) {} + operator bool() const { return success && resource != nullptr; } +}; +``` + +## 公共方法 + +### 资源信息 + +| 方法 | 描述 | +|------|------| +| `ResourceType GetResourceType() const` | 获取此加载器支持的资源类型 | +| `Containers::Array GetSupportedExtensions() const` | 获取支持的文件扩展名列表 | +| `bool CanLoad(const Containers::String& path) const` | 检查此加载器是否能加载指定路径 | +| `ImportSettings* GetDefaultSettings() const` | 获取默认导入设置 | + +### 同步加载 + +| 方法 | 描述 | +|------|------| +| `LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr)` | 同步加载资源 | + +### 异步加载 + +| 方法 | 描述 | +|------|------| +| `void LoadAsync(const Containers::String& path, const ImportSettings* settings, std::function callback)` | 异步加载资源（内部默认实现调用同步 Load） | + +### 辅助方法（受保护） + +| 方法 | 描述 | +|------|------| +| `static Containers::Array ReadFileData(const Containers::String& path)` | 读取文件数据 | +| `static Containers::String GetExtension(const Containers::String& path)` | 获取文件扩展名 | + +## 宏 + +### REGISTER_RESOURCE_LOADER + +自动注册加载器到 ResourceManager 的宏。 + +```cpp +REGISTER_RESOURCE_LOADER(TextureLoader) +``` + +## 使用示例 + +```cpp +class TextureLoader : public IResourceLoader { +public: + ResourceType GetResourceType() const override { + return ResourceType::Texture; + } + + Containers::Array GetSupportedExtensions() const override { + return {".png", ".jpg", ".jpeg", ".bmp", ".tga"}; + } + + bool CanLoad(const Containers::String& path) const override { + Containers::String ext = GetExtension(path); + return ext == ".png" || ext == ".jpg" || ext == ".bmp"; + } + + ImportSettings* GetDefaultSettings() const override { + return new TextureImportSettings(); + } + + LoadResult Load(const Containers::String& path, + const ImportSettings* settings = nullptr) override { + LoadResult result; + auto data = ReadFileData(path); + if (data.Empty()) { + return LoadResult("Failed to read file: " + path); + } + result.resource = new Texture(); + result.success = true; + return result; + } +}; + +// 注册加载器 +ResourceManager::Get().RegisterLoader(new TextureLoader()); +``` + +## 相关文档 + +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [AsyncLoader](../asyncloader/asyncloader.md) - 异步加载器 +- [ImportSettings](../importsettings/importsettings.md) - 导入设置 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/iloader/load.md b/docs/api/resources/iloader/load.md new file mode 100644 index 00000000..5151636d --- /dev/null +++ b/docs/api/resources/iloader/load.md @@ -0,0 +1,42 @@ +# IResourceLoader::Load + +```cpp +LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) +``` + +同步加载资源。纯虚方法，由具体加载器实现。从指定路径读取文件数据，解析为对应类型的资源对象。 + +**参数：** +- `path` - 资源文件路径 +- `settings` - 可选的导入设置，用于自定义加载行为 + +**返回：** `LoadResult`，包含加载结果（资源指针、是否成功、错误信息等） + +**复杂度：** O(n)，取决于文件大小 + +**示例：** + +```cpp +LoadResult TextureLoader::Load(const Containers::String& path, + const ImportSettings* settings) { + LoadResult result; + auto data = ReadFileData(path); + if (data.Empty()) { + result.errorMessage = "Failed to read file: " + path; + return result; + } + Texture* tex = new Texture(); + if (!tex->LoadFromData(data.Data(), data.Size(), settings)) { + delete tex; + result.errorMessage = "Failed to parse texture data"; + return result; + } + result.resource = tex; + result.success = true; + return result; +} +``` + +## 相关文档 + +- [IResourceLoader 总览](iloader.md) - 返回类总览 diff --git a/docs/api/resources/iloader/loadasync.md b/docs/api/resources/iloader/loadasync.md new file mode 100644 index 00000000..fb39b38a --- /dev/null +++ b/docs/api/resources/iloader/loadasync.md @@ -0,0 +1,34 @@ +# IResourceLoader::LoadAsync + +```cpp +void LoadAsync(const Containers::String& path, const ImportSettings* settings, + std::function callback) +``` + +异步加载资源。默认实现直接调用同步 `Load` 方法并在当前线程执行回调。子类可重写以实现真正的多线程异步加载。 + +**参数：** +- `path` - 资源路径 +- `settings` - 导入设置（可为 nullptr） +- `callback` - 加载完成回调函数 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +void AsyncTextureLoader::LoadAsync(const Containers::String& path, + const ImportSettings* settings, + std::function callback) { + std::thread([this, path, settings, callback]() { + LoadResult result = Load(path, settings); + callback(result); // 回调可在工作线程执行 + }).detach(); +} +``` + +## 相关文档 + +- [IResourceLoader 总览](iloader.md) - 返回类总览 diff --git a/docs/api/resources/resources-importsettings.md b/docs/api/resources/importsettings/importsettings.md similarity index 96% rename from docs/api/resources/resources-importsettings.md rename to docs/api/resources/importsettings/importsettings.md index 904833e6..9efbb0c1 100644 --- a/docs/api/resources/resources-importsettings.md +++ b/docs/api/resources/importsettings/importsettings.md @@ -135,7 +135,7 @@ // 纹理导入设置 TextureImportSettings texSettings; -texSettings.SetTextureType(RHI::TextureType::Texture2D); +texSettings.SetTextureType(TextureType::Texture2D); texSettings.SetGenerateMipmaps(true); texSettings.SetSRGB(true); texSettings.SetCompressionQuality(CompressionQuality::High); @@ -160,5 +160,6 @@ ResourceHandle mesh = ResourceManager::Get().Load("model.fbx", &mesh ## 相关文档 -- [IResourceLoader](./resources-iloader.md) - 资源加载器 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 +- [IResourceLoader](../iloader/iloader.md) - 资源加载器 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/iresource/initialize.md b/docs/api/resources/iresource/initialize.md new file mode 100644 index 00000000..641b9588 --- /dev/null +++ b/docs/api/resources/iresource/initialize.md @@ -0,0 +1,34 @@ +# IResource::Initialize + +```cpp +void Initialize(const ConstructParams& params) +``` + +使用构造参数初始化资源。将参数中的名称、路径、GUID 和内存大小写入对应成员变量，并将资源标记为有效状态。 + +**参数：** +- `params` - 包含资源名称、路径、GUID 和内存大小的构造参数结构体 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +class MyResource : public IResource { +public: + MyResource() { + ConstructParams params; + params.name = "player_texture"; + params.path = "textures/player.png"; + params.guid = ResourceGUID::Generate(params.path); + params.memorySize = 1024 * 1024; // 1MB + Initialize(params); + } +}; +``` + +## 相关文档 + +- [IResource 总览](iresource.md) - 返回类总览 diff --git a/docs/api/resources/resources-iresource.md b/docs/api/resources/iresource/iresource.md similarity index 89% rename from docs/api/resources/resources-iresource.md rename to docs/api/resources/iresource/iresource.md index c78d93dd..9f70ed30 100644 --- a/docs/api/resources/resources-iresource.md +++ b/docs/api/resources/iresource/iresource.md @@ -74,6 +74,7 @@ public: ## 相关文档 -- [ResourceHandle](./resources-resourcehandle.md) - 资源句柄 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 -- [ResourceTypes](./resources-resourcetypes.md) - 资源类型定义 +- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/iresource/release.md b/docs/api/resources/iresource/release.md new file mode 100644 index 00000000..2969aa27 --- /dev/null +++ b/docs/api/resources/iresource/release.md @@ -0,0 +1,33 @@ +# IResource::Release + +```cpp +virtual void Release() = 0 +``` + +释放资源引用。纯虚方法，由具体资源类实现，用于执行资源特有的清理逻辑（如释放 GPU 资源、释放内存等）。在 `ResourceHandle` 析构或调用 `Reset()` 时会自动触发。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) 或 O(n)，取决于具体实现 + +**示例：** + +```cpp +class Texture : public IResource { +public: + void Release() override { + if (m_rhiTexture) { + m_rhiTexture->Release(); + m_rhiTexture = nullptr; + } + m_pixelData.Clear(); + m_isValid = false; + } +}; +``` + +## 相关文档 + +- [IResource 总览](iresource.md) - 返回类总览 diff --git a/docs/api/resources/iresource/setinvalid.md b/docs/api/resources/iresource/setinvalid.md new file mode 100644 index 00000000..4b0530e4 --- /dev/null +++ b/docs/api/resources/iresource/setinvalid.md @@ -0,0 +1,28 @@ +# IResource::SetInvalid + +```cpp +void SetInvalid() +``` + +将资源标记为无效状态。此方法用于在加载失败或资源损坏时将 `m_isValid` 设为 false，之后调用 `IsValid()` 将返回 false。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +void LoadFailed() { + texture->SetInvalid(); + if (!texture->IsValid()) { + // 处理资源无效情况 + } +} +``` + +## 相关文档 + +- [IResource 总览](iresource.md) - 返回类总览 diff --git a/docs/api/resources/resources-material.md b/docs/api/resources/material/material.md similarity index 95% rename from docs/api/resources/resources-material.md rename to docs/api/resources/material/material.md index e28bb612..80bb3391 100644 --- a/docs/api/resources/resources-material.md +++ b/docs/api/resources/material/material.md @@ -141,6 +141,7 @@ auto cbData = mat->GetConstantBufferData(); ## 相关文档 -- [IResource](./resources-iresource.md) - 资源基类 -- [Shader](./resources-shader.md) - 着色器资源 -- [Texture](./resources-texture.md) - 纹理资源 +- [IResource](../iresource/iresource.md) - 资源基类 +- [Shader](../shader/shader.md) - 着色器资源 +- [Texture](../texture/texture.md) - 纹理资源 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/material/setfloat.md b/docs/api/resources/material/setfloat.md new file mode 100644 index 00000000..a7bf8906 --- /dev/null +++ b/docs/api/resources/material/setfloat.md @@ -0,0 +1,27 @@ +# Material::SetFloat + +```cpp +void SetFloat(const Containers::String& name, float value) +``` + +设置材质浮点属性。 + +**参数：** +- `name` - 属性名称 +- `value` - 属性值 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +mat->SetFloat("roughness", 0.5f); +mat->SetFloat("metallic", 0.0f); +mat->SetFloat("emissionStrength", 2.0f); +``` + +## 相关文档 + +- [Material 总览](material.md) - 返回类总览 diff --git a/docs/api/resources/material/setshader.md b/docs/api/resources/material/setshader.md new file mode 100644 index 00000000..d3adf4dd --- /dev/null +++ b/docs/api/resources/material/setshader.md @@ -0,0 +1,26 @@ +# Material::SetShader + +```cpp +void SetShader(const ResourceHandle& shader) +``` + +设置材质使用的着色器。 + +**参数：** +- `shader` - 着色器资源句柄 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle vs = ResourceManager::Get().Load("shaders/vertex.glsl"); +ResourceHandle fs = ResourceManager::Get().Load("shaders/fragment.glsl"); +mat->SetShader(vs); +``` + +## 相关文档 + +- [Material 总览](material.md) - 返回类总览 diff --git a/docs/api/resources/material/settexture.md b/docs/api/resources/material/settexture.md new file mode 100644 index 00000000..02f169fd --- /dev/null +++ b/docs/api/resources/material/settexture.md @@ -0,0 +1,28 @@ +# Material::SetTexture + +```cpp +void SetTexture(const Containers::String& name, const ResourceHandle& texture) +``` + +设置材质纹理属性。 + +**参数：** +- `name` - 属性名称 +- `texture` - 纹理资源句柄 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle albedoTex = ResourceManager::Get().Load("textures/albedo.png"); +ResourceHandle normalTex = ResourceManager::Get().Load("textures/normal.png"); +mat->SetTexture("albedoMap", albedoTex); +mat->SetTexture("normalMap", normalTex); +``` + +## 相关文档 + +- [Material 总览](material.md) - 返回类总览 diff --git a/docs/api/resources/material/updateconstantbuffer.md b/docs/api/resources/material/updateconstantbuffer.md new file mode 100644 index 00000000..5854f16f --- /dev/null +++ b/docs/api/resources/material/updateconstantbuffer.md @@ -0,0 +1,26 @@ +# Material::UpdateConstantBuffer + +```cpp +void UpdateConstantBuffer() +``` + +更新材质常量缓冲区。将所有属性值打包到常量缓冲区的二进制数据中，供 GPU 着色器使用。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n)，n 为属性数量 + +**示例：** + +```cpp +mat->SetFloat("roughness", 0.5f); +mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f)); +mat->UpdateConstantBuffer(); +auto cbData = mat->GetConstantBufferData(); +``` + +## 相关文档 + +- [Material 总览](material.md) - 返回类总览 diff --git a/docs/api/resources/mesh/addsection.md b/docs/api/resources/mesh/addsection.md new file mode 100644 index 00000000..f7dc0440 --- /dev/null +++ b/docs/api/resources/mesh/addsection.md @@ -0,0 +1,30 @@ +# Mesh::AddSection + +```cpp +void AddSection(const MeshSection& section) +``` + +添加网格分段（Submesh）。一个 Mesh 可以包含多个分段，每个分段对应一组索引和不同的材质。 + +**参数：** +- `section` - 网格分段描述结构体 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +MeshSection section; +section.baseVertex = 0; +section.vertexCount = 1000; +section.startIndex = 0; +section.indexCount = 3000; +section.materialID = 0; +mesh->AddSection(section); +``` + +## 相关文档 + +- [Mesh 总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/resources-mesh.md b/docs/api/resources/mesh/mesh.md similarity index 94% rename from docs/api/resources/resources-mesh.md rename to docs/api/resources/mesh/mesh.md index da9a7e4b..1752bada 100644 --- a/docs/api/resources/resources-mesh.md +++ b/docs/api/resources/mesh/mesh.md @@ -143,6 +143,7 @@ auto sections = mesh->GetSections(); ## 相关文档 -- [IResource](./resources-iresource.md) - 资源基类 -- [Material](./resources-material.md) - 材质资源 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 +- [IResource](../iresource/iresource.md) - 资源基类 +- [Material](../material/material.md) - 材质资源 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/mesh/setindexdata.md b/docs/api/resources/mesh/setindexdata.md new file mode 100644 index 00000000..06fd6153 --- /dev/null +++ b/docs/api/resources/mesh/setindexdata.md @@ -0,0 +1,30 @@ +# Mesh::SetIndexData + +```cpp +void SetIndexData(const void* data, size_t size, Core::uint32 indexCount, bool use32Bit) +``` + +设置网格索引数据。复制索引缓冲数据到内部存储。 + +**参数：** +- `data` - 索引数据指针 +- `size` - 数据大小（字节） +- `indexCount` - 索引数量 +- `use32Bit` - 是否使用 32 位索引（否则使用 16 位） + +**返回：** 无 + +**复杂度：** O(n)，n 为索引数据大小 + +**示例：** + +```cpp +Containers::Array indices; +// ... 填充索引数据 ... +mesh->SetIndexData(indices.Data(), indices.Size() * sizeof(uint32_t), + indices.Size(), true); +``` + +## 相关文档 + +- [Mesh 总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/setvertexdata.md b/docs/api/resources/mesh/setvertexdata.md new file mode 100644 index 00000000..38c5754d --- /dev/null +++ b/docs/api/resources/mesh/setvertexdata.md @@ -0,0 +1,37 @@ +# Mesh::SetVertexData + +```cpp +void SetVertexData(const void* data, size_t size, Core::uint32 vertexCount, + Core::uint32 vertexStride, VertexAttribute attributes) +``` + +设置网格顶点数据。复制顶点缓冲数据到内部存储。 + +**参数：** +- `data` - 顶点数据指针 +- `size` - 数据大小（字节） +- `vertexCount` - 顶点数量 +- `vertexStride` - 单个顶点结构体大小（字节） +- `attributes` - 顶点属性标志组合 + +**返回：** 无 + +**复杂度：** O(n)，n 为顶点数据大小 + +**示例：** + +```cpp +struct Vertex { + float position[3]; + float normal[3]; + float uv[2]; +}; + +mesh->SetVertexData(vertices.Data(), vertices.Size() * sizeof(Vertex), + vertexCount, sizeof(Vertex), + VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0); +``` + +## 相关文档 + +- [Mesh 总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/resourcecache/add.md b/docs/api/resources/resourcecache/add.md new file mode 100644 index 00000000..2d7ee72e --- /dev/null +++ b/docs/api/resources/resourcecache/add.md @@ -0,0 +1,25 @@ +# ResourceCache::Add + +```cpp +void Add(ResourceGUID guid, IResource* resource) +``` + +添加资源到缓存。将资源和 GUID 关联并记录内存大小、访问时间。线程安全。 + +**参数：** +- `guid` - 资源全局唯一标识符 +- `resource` - 资源指针 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +cache.Add(guid, resource); +``` + +## 相关文档 + +- [ResourceCache 总览](resourcecache.md) - 返回类总览 diff --git a/docs/api/resources/resourcecache/flush.md b/docs/api/resources/resourcecache/flush.md new file mode 100644 index 00000000..5b83ee7f --- /dev/null +++ b/docs/api/resources/resourcecache/flush.md @@ -0,0 +1,23 @@ +# ResourceCache::Flush + +```cpp +void Flush() +``` + +清空缓存，释放所有资源。将所有缓存条目标记为待释放状态，调用每个资源的 `Release()` 方法。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +cache.Flush(); +``` + +## 相关文档 + +- [ResourceCache 总览](resourcecache.md) - 返回类总览 diff --git a/docs/api/resources/resourcecache/getlrulist.md b/docs/api/resources/resourcecache/getlrulist.md new file mode 100644 index 00000000..6e850f9d --- /dev/null +++ b/docs/api/resources/resourcecache/getlrulist.md @@ -0,0 +1,27 @@ +# ResourceCache::GetLRUList + +```cpp +Containers::Array GetLRUList(size_t count) const +``` + +获取最近最少使用的 GUID 列表。按 LRU 顺序返回前 `count` 个资源 GUID。 + +**参数：** +- `count` - 要获取的 GUID 数量 + +**返回：** 最近最少使用的 GUID 数组 + +**复杂度：** O(n) + +**示例：** + +```cpp +auto lruList = cache.GetLRUList(10); +for (const auto& guid : lruList) { + // 标记或处理这些资源... +} +``` + +## 相关文档 + +- [ResourceCache 总览](resourcecache.md) - 返回类总览 diff --git a/docs/api/resources/resourcecache/onmemorypressure.md b/docs/api/resources/resourcecache/onmemorypressure.md new file mode 100644 index 00000000..5b6efa22 --- /dev/null +++ b/docs/api/resources/resourcecache/onmemorypressure.md @@ -0,0 +1,25 @@ +# ResourceCache::OnMemoryPressure + +```cpp +void OnMemoryPressure(size_t requiredBytes) +``` + +内存压力回调。当系统内存紧张时调用此方法，从 LRU 列表头部开始驱逐资源，直到释放足够空间。 + +**参数：** +- `requiredBytes` - 需要释放的字节数 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +// 需要 100MB 空间 +cache.OnMemoryPressure(100 * 1024 * 1024); +``` + +## 相关文档 + +- [ResourceCache 总览](resourcecache.md) - 返回类总览 diff --git a/docs/api/resources/resources-resourcecache.md b/docs/api/resources/resourcecache/resourcecache.md similarity index 88% rename from docs/api/resources/resources-resourcecache.md rename to docs/api/resources/resourcecache/resourcecache.md index fd15fa24..fcbee1d5 100644 --- a/docs/api/resources/resources-resourcecache.md +++ b/docs/api/resources/resourcecache/resourcecache.md @@ -10,6 +10,26 @@ `ResourceCache` 实现了资源的内存缓存管理。它跟踪每个资源的访问时间和访问次数，在内存压力下自动驱逐最近最少使用的资源，确保内存使用不超过预算。 +## CacheEntry 结构体 + +缓存条目结构体。 + +| 成员 | 类型 | 描述 | +|------|------|------| +| `resource` | `IResource*` | 资源指针 | +| `guid` | `ResourceGUID` | 全局唯一标识符 | +| `memorySize` | `size_t` | 内存大小 | +| `lastAccessTime` | `Core::uint64` | 上次访问时间戳 | +| `accessCount` | `Core::uint32` | 访问次数 | + +### 构造与静态方法 + +| 方法 | 描述 | +|------|------| +| `CacheEntry()` | 默认构造 | +| `CacheEntry(IResource* res, size_t size)` | 从资源和大小构造 | +| `static Core::uint64 GetCurrentTick()` | 获取当前时间戳 | + ## 公共方法 ### 生命周期 @@ -52,24 +72,6 @@ |------|------| | `Containers::Array GetLRUList(size_t count) const` | 获取最近最少使用的 GUID 列表 | -## CacheEntry 结构体 - -缓存条目结构体。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `resource` | `IResource*` | 资源指针 | -| `guid` | `ResourceGUID` | 全局唯一标识符 | -| `memorySize` | `size_t` | 内存大小 | -| `lastAccessTime` | `Core::uint64` | 上次访问时间戳 | -| `accessCount` | `Core::uint32` | 访问次数 | - -### 静态方法 - -| 方法 | 描述 | -|------|------| -| `static Core::uint64 GetCurrentTick()` | 获取当前时间戳 | - ## 使用示例 ```cpp @@ -94,5 +96,6 @@ auto lruList = cache.GetLRUList(10); ## 相关文档 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 -- [IResource](./resources-iresource.md) - 资源基类 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [IResource](../iresource/iresource.md) - 资源基类 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/resourcecache/touch.md b/docs/api/resources/resourcecache/touch.md new file mode 100644 index 00000000..138d7b7a --- /dev/null +++ b/docs/api/resources/resourcecache/touch.md @@ -0,0 +1,27 @@ +# ResourceCache::Touch + +```cpp +void Touch(ResourceGUID guid) +``` + +更新资源的最近访问时间。当缓存条目被命中时调用，用于 LRU 驱逐算法判断资源的访问热度。 + +**参数：** +- `guid` - 资源全局唯一标识符 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +IResource* res = cache.Find(guid); +if (res) { + cache.Touch(guid); // 更新 LRU +} +``` + +## 相关文档 + +- [ResourceCache 总览](resourcecache.md) - 返回类总览 diff --git a/docs/api/resources/resourcehandle/get.md b/docs/api/resources/resourcehandle/get.md new file mode 100644 index 00000000..bf010d3c --- /dev/null +++ b/docs/api/resources/resourcehandle/get.md @@ -0,0 +1,27 @@ +# ResourceHandle::Get + +```cpp +T* Get() const +``` + +获取资源裸指针。返回句柄内部持有的资源指针，不进行任何引用计数操作。 + +**参数：** 无 + +**返回：** 资源裸指针，可能为 `nullptr`（当句柄为空时） + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle tex = ResourceManager::Get().Load("tex.png"); +Texture* raw = tex.Get(); +if (raw != nullptr) { + uint32_t w = raw->GetWidth(); +} +``` + +## 相关文档 + +- [ResourceHandle 总览](resourcehandle.md) - 返回类总览 diff --git a/docs/api/resources/resourcehandle/getguid.md b/docs/api/resources/resourcehandle/getguid.md new file mode 100644 index 00000000..8dd379b6 --- /dev/null +++ b/docs/api/resources/resourcehandle/getguid.md @@ -0,0 +1,27 @@ +# ResourceHandle::GetGUID + +```cpp +ResourceGUID GetGUID() const +``` + +获取资源的全局唯一标识符。如果内部指针为空，则返回一个值为 0 的空 GUID。 + +**参数：** 无 + +**返回：** 资源的 `ResourceGUID`，如果句柄为空则返回 `ResourceGUID(0)` + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle tex = ResourceManager::Get().Load("tex.png"); +ResourceGUID guid = tex.GetGUID(); +if (guid.IsValid()) { + printf("GUID: %s\n", guid.ToString().CStr()); +} +``` + +## 相关文档 + +- [ResourceHandle 总览](resourcehandle.md) - 返回类总览 diff --git a/docs/api/resources/resourcehandle/isvalid.md b/docs/api/resources/resourcehandle/isvalid.md new file mode 100644 index 00000000..0b2c1d29 --- /dev/null +++ b/docs/api/resources/resourcehandle/isvalid.md @@ -0,0 +1,29 @@ +# ResourceHandle::IsValid + +```cpp +bool IsValid() const +``` + +检查句柄是否持有有效资源。判断条件为：内部指针非空且资源的 `IsValid()` 返回 true。 + +**参数：** 无 + +**返回：** 如果持有有效资源则返回 true，否则返回 false + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle tex = ResourceManager::Get().Load("tex.png"); +if (tex.IsValid()) { + // 安全访问资源 + tex->GenerateMipmaps(); +} else { + printf("Texture load failed!\n"); +} +``` + +## 相关文档 + +- [ResourceHandle 总览](resourcehandle.md) - 返回类总览 diff --git a/docs/api/resources/resourcehandle/reset.md b/docs/api/resources/resourcehandle/reset.md new file mode 100644 index 00000000..74f4484a --- /dev/null +++ b/docs/api/resources/resourcehandle/reset.md @@ -0,0 +1,31 @@ +# ResourceHandle::Reset + +```cpp +void Reset() +``` + +释放当前持有的资源引用。如果内部持有的资源指针非空，则调用 `ResourceManager::Release()` 减少引用计数，并将内部指针置为 `nullptr`。析构函数会自动调用此方法。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle tex = ResourceManager::Get().Load("tex.png"); +// 使用纹理... +tex.Reset(); // 释放引用，引用计数 -1 + +// 或者让句柄离开作用域自动释放 +{ + ResourceHandle mesh = ResourceManager::Get().Load("model.fbx"); + // 使用网格... +} // mesh 自动 Reset() +``` + +## 相关文档 + +- [ResourceHandle 总览](resourcehandle.md) - 返回类总览 diff --git a/docs/api/resources/resources-resourcehandle.md b/docs/api/resources/resourcehandle/resourcehandle.md similarity index 91% rename from docs/api/resources/resources-resourcehandle.md rename to docs/api/resources/resourcehandle/resourcehandle.md index 7e23ae23..982d3cc1 100644 --- a/docs/api/resources/resources-resourcehandle.md +++ b/docs/api/resources/resourcehandle/resourcehandle.md @@ -95,6 +95,7 @@ tex.Reset(); // 手动释放 ## 相关文档 -- [IResource](./resources-iresource.md) - 资源基类 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 -- [ResourceCache](./resources-resourcecache.md) - 资源缓存 +- [IResource](../iresource/iresource.md) - 资源基类 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [ResourceCache](../resourcecache/resourcecache.md) - 资源缓存 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/resourcehandle/swap.md b/docs/api/resources/resourcehandle/swap.md new file mode 100644 index 00000000..f41d7725 --- /dev/null +++ b/docs/api/resources/resourcehandle/swap.md @@ -0,0 +1,30 @@ +# ResourceHandle::Swap + +```cpp +void Swap(ResourceHandle& other) +``` + +交换两个句柄持有的资源指针。使用 `std::swap` 交换内部指针，不会改变任何引用计数。此操作常用于在不影响引用计数的情况下安全地交换两个句柄的内容。 + +**参数：** +- `other` - 要交换的另一个 ResourceHandle 引用 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle tex1 = ResourceManager::Get().Load("a.png"); +ResourceHandle tex2 = ResourceManager::Get().Load("b.png"); + +// 交换后 tex1 持有 b.png，tex2 持有 a.png +tex1.Swap(tex2); + +// 引用计数不变 +``` + +## 相关文档 + +- [ResourceHandle 总览](resourcehandle.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/exists.md b/docs/api/resources/resourcemanager/exists.md new file mode 100644 index 00000000..13e00903 --- /dev/null +++ b/docs/api/resources/resourcemanager/exists.md @@ -0,0 +1,28 @@ +# ResourceManager::Exists + +```cpp +bool Exists(const Containers::String& path) const +bool Exists(ResourceGUID guid) const +``` + +检查资源是否已加载。 + +**参数：** +- `path` - 资源路径 +- `guid` - 资源全局唯一标识符 + +**返回：** 如果资源在缓存中则返回 true + +**复杂度：** O(1) + +**示例：** + +```cpp +if (ResourceManager::Get().Exists("textures/player.png")) { + auto tex = ResourceManager::Get().Load("textures/player.png"); +} +``` + +## 相关文档 + +- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/find.md b/docs/api/resources/resourcemanager/find.md new file mode 100644 index 00000000..469f994b --- /dev/null +++ b/docs/api/resources/resourcemanager/find.md @@ -0,0 +1,29 @@ +# ResourceManager::Find + +```cpp +IResource* Find(const Containers::String& path) +IResource* Find(ResourceGUID guid) +``` + +在资源缓存中查找资源。返回裸指针，不增加引用计数。 + +**参数：** +- `path` - 资源路径 +- `guid` - 资源全局唯一标识符 + +**返回：** 找到则返回资源指针，否则返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +IResource* res = ResourceManager::Get().Find("textures/player.png"); +if (res && res->IsValid()) { + Texture* tex = static_cast(res); +} +``` + +## 相关文档 + +- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/getloader.md b/docs/api/resources/resourcemanager/getloader.md new file mode 100644 index 00000000..255e6f49 --- /dev/null +++ b/docs/api/resources/resourcemanager/getloader.md @@ -0,0 +1,27 @@ +# ResourceManager::GetLoader + +```cpp +IResourceLoader* GetLoader(ResourceType type) const +``` + +获取指定类型的资源加载器。 + +**参数：** +- `type` - 资源类型 + +**返回：** 对应的加载器指针，未找到则返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +IResourceLoader* texLoader = ResourceManager::Get().GetLoader(ResourceType::Texture); +if (texLoader) { + auto extensions = texLoader->GetSupportedExtensions(); +} +``` + +## 相关文档 + +- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/load.md b/docs/api/resources/resourcemanager/load.md new file mode 100644 index 00000000..83b65aab --- /dev/null +++ b/docs/api/resources/resourcemanager/load.md @@ -0,0 +1,32 @@ +# ResourceManager::Load + +```cpp +template +ResourceHandle Load(const Containers::String& path, ImportSettings* settings = nullptr) +``` + +同步加载资源。模板方法，根据路径生成 GUID，先在缓存中查找是否已加载；若未加载则查找对应类型的加载器并同步加载，然后将结果加入缓存。 + +**参数：** +- `path` - 资源路径 +- `settings` - 导入设置（可选） + +**返回：** `ResourceHandle`，持有加载的资源 + +**复杂度：** O(n)，取决于加载器实现 + +**示例：** + +```cpp +ResourceHandle tex = ResourceManager::Get().Load("textures/player.png"); +ResourceHandle mesh = ResourceManager::Get().Load("models/player.fbx"); +ResourceHandle mat = ResourceManager::Get().Load("materials/player.mat"); + +if (tex.IsValid()) { + // 使用纹理... +} +``` + +## 相关文档 + +- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/loadasync.md b/docs/api/resources/resourcemanager/loadasync.md new file mode 100644 index 00000000..7c470813 --- /dev/null +++ b/docs/api/resources/resourcemanager/loadasync.md @@ -0,0 +1,44 @@ +# ResourceManager::LoadAsync + +```cpp +void LoadAsync(const Containers::String& path, ResourceType type, + std::function callback) +void LoadAsync(const Containers::String& path, ResourceType type, + ImportSettings* settings, std::function callback) +``` + +异步加载资源。将加载请求提交到 `AsyncLoader`，在后台工作线程执行加载，完成后在主线程通过回调通知。 + +**参数：** +- `path` - 资源路径 +- `type` - 资源类型 +- `settings` - 导入设置（可为 nullptr） +- `callback` - 加载完成回调 + +**返回：** 无 + +**复杂度：** 提交 O(1)，实际加载 O(n) + +**示例：** + +```cpp +ResourceManager::Get().LoadAsync("textures/terrain.png", ResourceType::Texture, + [](LoadResult result) { + if (result.success) { + ResourceHandle tex(result.resource); + printf("Loaded: %s\n", tex->GetPath().CStr()); + } + }); + +ResourceManager::Get().LoadAsync("models/player.fbx", ResourceType::Mesh, + nullptr, + [](LoadResult result) { + if (result.success) { + ResourceHandle mesh(result.resource); + } + }); +``` + +## 相关文档 + +- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/loadgroup.md b/docs/api/resources/resourcemanager/loadgroup.md new file mode 100644 index 00000000..23193e57 --- /dev/null +++ b/docs/api/resources/resourcemanager/loadgroup.md @@ -0,0 +1,35 @@ +# ResourceManager::LoadGroup + +```cpp +template +void LoadGroup(const Containers::Array& paths, + std::function)> callback) +``` + +批量异步加载同类资源。为路径数组中的每个路径提交一个异步加载请求，所有加载完成时通过回调通知。 + +**参数：** +- `paths` - 资源路径数组 +- `callback` - 每个资源加载完成时的回调 + +**返回：** 无 + +**复杂度：** O(k)，k 为路径数量（每个加载为 O(n)） + +**示例：** + +```cpp +Containers::Array texPaths = { + "textures/a.png", "textures/b.png", "textures/c.png" +}; +ResourceManager::Get().LoadGroup(texPaths, + [](ResourceHandle tex) { + if (tex.IsValid()) { + printf("Loaded: %s\n", tex->GetPath().CStr()); + } + }); +``` + +## 相关文档 + +- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/registerloader.md b/docs/api/resources/resourcemanager/registerloader.md new file mode 100644 index 00000000..62c01cc8 --- /dev/null +++ b/docs/api/resources/resourcemanager/registerloader.md @@ -0,0 +1,26 @@ +# ResourceManager::RegisterLoader + +```cpp +void RegisterLoader(IResourceLoader* loader) +``` + +注册资源加载器。管理器持有加载器指针所有权。 + +**参数：** +- `loader` - 加载器实例指针 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceManager::Get().RegisterLoader(new TextureLoader()); +ResourceManager::Get().RegisterLoader(new MeshLoader()); +ResourceManager::Get().RegisterLoader(new MaterialLoader()); +``` + +## 相关文档 + +- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resources-resourcemanager.md b/docs/api/resources/resourcemanager/resourcemanager.md similarity index 87% rename from docs/api/resources/resources-resourcemanager.md rename to docs/api/resources/resourcemanager/resourcemanager.md index e024c85d..e167463c 100644 --- a/docs/api/resources/resources-resourcemanager.md +++ b/docs/api/resources/resourcemanager/resourcemanager.md @@ -107,15 +107,6 @@ | `Containers::Array GetResourcePaths() const` | 获取所有已加载资源的路径列表 | | `void UnloadGroup(const Containers::Array& guids)` | 按 GUID 批量卸载 | -## 私有方法（内部使用） - -| 方法 | 描述 | -|------|------| -| `IResource* FindInCache(ResourceGUID guid)` | 在缓存中查找资源 | -| `void AddToCache(ResourceGUID guid, IResource* resource)` | 添加到缓存 | -| `IResourceLoader* FindLoader(ResourceType type)` | 查找加载器 | -| `void ReloadResource(ResourceGUID guid)` | 重新加载资源 | - ## 使用示例 ```cpp @@ -133,7 +124,7 @@ ResourceHandle tex = ResourceManager::Get().Load("textures/pla ResourceHandle mesh = ResourceManager::Get().Load("models/player.fbx"); // 异步加载 -ResourceManager::Get().LoadAsync("textures/terrain.png", +ResourceManager::Get().LoadAsync("textures/terrain.png", ResourceType::Texture, [](LoadResult result) { if (result.success) { ResourceHandle tex(result.resource); @@ -160,7 +151,8 @@ ResourceManager::Get().Shutdown(); ## 相关文档 -- [IResource](./resources-iresource.md) - 资源基类 -- [ResourceHandle](./resources-resourcehandle.md) - 资源句柄 -- [ResourceCache](./resources-resourcecache.md) - 资源缓存 -- [AsyncLoader](./resources-asyncloader.md) - 异步加载器 +- [IResource](../iresource/iresource.md) - 资源基类 +- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄 +- [ResourceCache](../resourcecache/resourcecache.md) - 资源缓存 +- [AsyncLoader](../asyncloader/asyncloader.md) - 异步加载器 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/resourcemanager/setmemorybudget.md b/docs/api/resources/resourcemanager/setmemorybudget.md new file mode 100644 index 00000000..6d790ba9 --- /dev/null +++ b/docs/api/resources/resourcemanager/setmemorybudget.md @@ -0,0 +1,24 @@ +# ResourceManager::SetMemoryBudget + +```cpp +void SetMemoryBudget(size_t bytes) +``` + +设置资源管理的内存预算上限。当缓存中资源的总内存占用超过预算时，会触发 LRU 驱逐策略释放内存。 + +**参数：** +- `bytes` - 内存预算大小（字节） + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceManager::Get().SetMemoryBudget(1024 * 1024 * 1024); // 1GB 预算 +``` + +## 相关文档 + +- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/unload.md b/docs/api/resources/resourcemanager/unload.md new file mode 100644 index 00000000..8eea6d9a --- /dev/null +++ b/docs/api/resources/resourcemanager/unload.md @@ -0,0 +1,31 @@ +# ResourceManager::Unload + +```cpp +void Unload(const Containers::String& path) +void Unload(ResourceGUID guid) +``` + +卸载指定资源。按路径或 GUID 查找资源，如果引用计数降至零则释放资源内存。 + +**参数：** +- `path` - 资源路径 +- `guid` - 资源全局唯一标识符 + +**返回：** 无 + +**复杂度：** O(1) 查找 + +**示例：** + +```cpp +// 按路径卸载 +ResourceManager::Get().Unload("textures/player.png"); + +// 按 GUID 卸载 +ResourceGUID guid = tex.GetGUID(); +ResourceManager::Get().Unload(guid); +``` + +## 相关文档 + +- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/unloadunused.md b/docs/api/resources/resourcemanager/unloadunused.md new file mode 100644 index 00000000..27bcb763 --- /dev/null +++ b/docs/api/resources/resourcemanager/unloadunused.md @@ -0,0 +1,26 @@ +# ResourceManager::UnloadUnused + +```cpp +void UnloadUnused() +``` + +卸载所有无引用的资源。遍历资源缓存，将引用计数为零的资源全部释放。常在场景切换或内存紧张时调用。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +// 切换场景时清理无用资源 +void OnSceneUnload() { + ResourceManager::Get().UnloadUnused(); +} +``` + +## 相关文档 + +- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resources-iloader.md b/docs/api/resources/resources-iloader.md deleted file mode 100644 index 068fbd21..00000000 --- a/docs/api/resources/resources-iloader.md +++ /dev/null @@ -1,112 +0,0 @@ -# IResourceLoader - -**命名空间**: `XCEngine::Resources` - -**类型**: `class` (abstract) - -**描述**: 资源加载器抽象接口，定义了资源加载的标准协议。每个资源类型需要提供对应的加载器实现。 - -## 概述 - -`IResourceLoader` 是资源加载系统的核心抽象接口。它定义了同步和异步加载资源的方法，以及资源类型的查询和依赖信息的获取。`ResourceManager` 通过注册加载器来支持不同类型资源的加载。 - -## 公共方法 - -### 资源信息 - -| 方法 | 描述 | -|------|------| -| `ResourceType GetResourceType() const` | 获取此加载器支持的资源类型 | -| `const Containers::String& GetResourceTypeName() const` | 获取资源类型的字符串名称 | -| `size_t GetResourceSize(const Containers::String& path) const` | 获取资源文件大小 | - -### 同步加载 - -| 方法 | 描述 | -|------|------| -| `LoadResult Load(const Containers::String& path, ImportSettings* settings)` | 同步加载资源 | -| `bool Save(const Containers::String& path, IResource* resource)` | 保存资源到文件 | - -### 异步加载 - -| 方法 | 描述 | -|------|------| -| `LoadResult LoadAsync(const Containers::String& path, ImportSettings* settings)` | 异步加载资源（内部使用） | - -### 依赖管理 - -| 方法 | 描述 | -|------|------| -| `Containers::Array GetDependencies(const Containers::String& path) const` | 获取资源依赖的文件路径列表 | - -### 资源操作 - -| 方法 | 描述 | -|------|------| -| `bool Reload(IResource* resource, const Containers::String& path)` | 重新加载资源 | -| `void Unload(IResource* resource)` | 卸载资源 | - -### 文件系统 - -| 方法 | 描述 | -|------|------| -| `bool Exists(const Containers::String& path) const` | 检查资源文件是否存在 | -| `Containers::String ResolvePath(const Containers::String& relativePath) const` | 解析资源路径 | - -## LoadResult 结构体 - -加载操作的返回值结构体。 - -```cpp -struct LoadResult { - IResource* resource = nullptr; // 加载的资源对象 - bool success = false; // 是否成功 - Containers::String errorMessage; // 错误信息 - size_t memorySize = 0; // 资源内存大小 - Containers::Array dependencies; // 依赖列表 -}; -``` - -### 布尔转换 - -| 转换 | 描述 | -|------|------| -| `explicit operator bool() const` | `success == true` 时返回 true | - -## 使用示例 - -```cpp -class TextureLoader : public IResourceLoader { -public: - ResourceType GetResourceType() const override { - return ResourceType::Texture; - } - - const Containers::String& GetResourceTypeName() const override { - static Containers::String name = "Texture"; - return name; - } - - LoadResult Load(const Containers::String& path, - ImportSettings* settings) override { - LoadResult result; - // 实现加载逻辑... - result.success = true; - result.resource = new Texture(); - return result; - } - - Containers::Array - GetDependencies(const Containers::String& path) const override { - return {}; // 纹理通常无依赖 - } -}; - -// 注册加载器 -ResourceManager::Get().RegisterLoader(new TextureLoader()); -``` - -## 相关文档 - -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 -- [AsyncLoader](./resources-asyncloader.md) - 异步加载器 diff --git a/docs/api/resources/resources-resourcetypes.md b/docs/api/resources/resources-resourcetypes.md deleted file mode 100644 index fb6e53c5..00000000 --- a/docs/api/resources/resources-resourcetypes.md +++ /dev/null @@ -1,101 +0,0 @@ -# ResourceTypes - -**命名空间**: `XCEngine::Resources` - -**类型**: `enums` / `structs` - -**描述**: 资源模块中使用的所有类型定义，包括资源类型枚举、GUID 结构体等。 - -## 概述 - -本文档汇总了 Resources 模块中的所有类型定义，包括资源类型枚举、GUID 结构体等基础类型。 - ---- - -## ResourceType - -资源类型枚举。 - -| 值 | 描述 | -|----|------| -| `Unknown` | 未知类型 | -| `Texture` | 纹理资源 | -| `Mesh` | 网格/模型资源 | -| `Material` | 材质资源 | -| `Shader` | 着色器资源 | -| `AudioClip` | 音频资源 | -| `Binary` | 二进制数据 | -| `AnimationClip` | 动画片段 | -| `Skeleton` | 骨骼 | -| `Font` | 字体 | -| `ParticleSystem` | 粒子系统 | -| `Scene` | 场景 | -| `Prefab` | 预制体 | - ---- - -## ResourceGUID - -全局唯一标识符结构体，用于唯一标识每个资源。 - -```cpp -struct ResourceGUID { - uint64_t value = 0; -}; -``` - -### 构造方法 - -| 方法 | 描述 | -|------|------| -| `ResourceGUID()` | 默认构造（值为 0） | -| `explicit ResourceGUID(uint64_t value)` | 从整数值构造 | - -### 比较运算 - -| 运算符 | 描述 | -|------|------| -| `operator==(ResourceGUID, ResourceGUID)` | 判断相等 | -| `operator!=(ResourceGUID, ResourceGUID)` | 判断不等 | - -### 哈希支持 - -`ResourceGUID` 可作为 HashMap 的键使用。 - -### 静态方法 - -| 方法 | 描述 | -|------|------| -| `static ResourceGUID Generate(const Containers::String& path)` | 从资源路径生成唯一 GUID | - ---- - -## 辅助函数 - -| 函数 | 描述 | -|------|------| -| `const char* GetResourceTypeName(ResourceType type)` | 获取资源类型的字符串名称 | - ---- - -## 使用示例 - -```cpp -// 使用 ResourceGUID -ResourceGUID texGuid = ResourceGUID::Generate("textures/player.png"); -ResourceGUID meshGuid = ResourceGUID::Generate("models/player.fbx"); - -// GUID 比较 -if (texGuid == meshGuid) { - // 相同资源 -} - -// 在 HashMap 中使用 -Containers::HashMap cache; -cache[texGuid] = texture; -``` - -## 相关文档 - -- [IResource](./resources-iresource.md) - 资源基类 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 diff --git a/docs/api/resources/resources-overview.md b/docs/api/resources/resources.md similarity index 60% rename from docs/api/resources/resources-overview.md rename to docs/api/resources/resources.md index 8dbd4a44..3dd96050 100644 --- a/docs/api/resources/resources-overview.md +++ b/docs/api/resources/resources.md @@ -16,24 +16,24 @@ Resources 模块提供了一套完整的资源管理解决方案，支持同步 | 组件 | 文件 | 描述 | |------|------|------| -| [IResource](./resources-iresource.md) | `IResource.h` | 资源基类 | -| [ResourceHandle](./resources-resourcehandle.md) | `ResourceHandle.h` | 资源句柄模板 | -| [IResourceLoader](./resources-iloader.md) | `IResourceLoader.h` | 资源加载器接口 | -| [ResourceManager](./resources-resourcemanager.md) | `ResourceManager.h` | 资源管理器 | -| [ResourceCache](./resources-resourcecache.md) | `ResourceCache.h` | 资源缓存 | -| [AsyncLoader](./resources-asyncloader.md) | `AsyncLoader.h` | 异步加载器 | -| [ResourceDependencyGraph](./resources-dependencygraph.md) | `ResourceDependencyGraph.h` | 依赖图 | -| [ResourceTypes](./resources-resourcetypes.md) | `ResourceTypes.h` | 资源类型定义 | +| [IResource](iresource/iresource.md) | `IResource.h` | 资源基类 | +| [ResourceHandle](resourcehandle/resourcehandle.md) | `ResourceHandle.h` | 资源句柄模板 | +| [IResourceLoader](iloader/iloader.md) | `IResourceLoader.h` | 资源加载器接口 | +| [ResourceManager](resourcemanager/resourcemanager.md) | `ResourceManager.h` | 资源管理器 | +| [ResourceCache](resourcecache/resourcecache.md) | `ResourceCache.h` | 资源缓存 | +| [AsyncLoader](asyncloader/asyncloader.md) | `AsyncLoader.h` | 异步加载器 | +| [ResourceDependencyGraph](dependencygraph/dependencygraph.md) | `ResourceDependencyGraph.h` | 依赖图 | +| [ResourceTypes](resourcetypes/resourcetypes.md) | `ResourceTypes.h` | 资源类型定义 | ### 具体资源类型 | 组件 | 文件 | 描述 | |------|------|------| -| [Texture](./resources-texture.md) | `Texture.h` | 纹理资源 | -| [Mesh](./resources-mesh.md) | `Mesh.h` | 网格资源 | -| [Material](./resources-material.md) | `Material.h` | 材质资源 | -| [Shader](./resources-shader.md) | `Shader.h` | 着色器资源 | -| [AudioClip](./resources-audioclip.md) | `AudioClip.h` | 音频资源 | +| [Texture](texture/texture.md) | `Texture.h` | 纹理资源 | +| [Mesh](mesh/mesh.md) | `Mesh.h` | 网格资源 | +| [Material](material/material.md) | `Material.h` | 材质资源 | +| [Shader](shader/shader.md) | `Shader.h` | 着色器资源 | +| [AudioClip](audioclip/audioclip.md) | `AudioClip.h` | 音频资源 | ## 资源类型 @@ -79,4 +79,4 @@ mesh.Reset(); ## 相关文档 -- [RHI 模块](../rhi/rhi-overview.md) - GPU 资源创建 +- [RHI 模块](../rhi/rhi.md) - GPU 资源创建 diff --git a/docs/api/resources/resourcetypes/generate.md b/docs/api/resources/resourcetypes/generate.md new file mode 100644 index 00000000..e41bc239 --- /dev/null +++ b/docs/api/resources/resourcetypes/generate.md @@ -0,0 +1,26 @@ +# ResourceGUID::Generate + +```cpp +static ResourceGUID Generate(const char* path) +static ResourceGUID Generate(const Containers::String& path) +``` + +从资源路径生成唯一的全局标识符。通过哈希算法将路径字符串转换为唯一的 64 位整数。 + +**参数：** +- `path` - 资源路径 + +**返回：** 生成的 `ResourceGUID` + +**复杂度：** O(n) + +**示例：** + +```cpp +ResourceGUID guid = ResourceGUID::Generate("textures/player.png"); +ResourceGUID guid2 = ResourceGUID::Generate("models/player.fbx"); +``` + +## 相关文档 + +- [ResourceTypes 总览](resourcetypes.md) - 返回类总览 diff --git a/docs/api/resources/resourcetypes/getresourcetypename.md b/docs/api/resources/resourcetypes/getresourcetypename.md new file mode 100644 index 00000000..7a57e27c --- /dev/null +++ b/docs/api/resources/resourcetypes/getresourcetypename.md @@ -0,0 +1,25 @@ +# GetResourceTypeName + +```cpp +constexpr const char* GetResourceTypeName(ResourceType type) +``` + +获取资源类型的字符串名称。通过 switch 语句返回对应的类型名字符串。 + +**参数：** +- `type` - 资源类型枚举值 + +**返回：** 类型名字符串（如 `"Texture"`、`"Mesh"` 等） + +**复杂度：** O(1) + +**示例：** + +```cpp +const char* name = GetResourceTypeName(ResourceType::Texture); // "Texture" +const char* name2 = GetResourceTypeName(ResourceType::Shader); // "Shader" +``` + +## 相关文档 + +- [ResourceTypes 总览](resourcetypes.md) - 返回类总览 diff --git a/docs/api/resources/resourcetypes/resourcetypes.md b/docs/api/resources/resourcetypes/resourcetypes.md new file mode 100644 index 00000000..b8a4ae7c --- /dev/null +++ b/docs/api/resources/resourcetypes/resourcetypes.md @@ -0,0 +1,127 @@ +# ResourceTypes + +**命名空间**: `XCEngine::Resources` + +**类型**: `enums` / `structs` + +**描述**: 资源模块中使用的所有类型定义，包括资源类型枚举、GUID 结构体等。 + +## 概述 + +本文档汇总了 Resources 模块中的所有类型定义，包括资源类型枚举、GUID 结构体等基础类型。 + +--- + +## ResourceType + +资源类型枚举。 + +| 值 | 描述 | +|----|------| +| `Unknown` | 未知类型 | +| `Texture` | 纹理资源 | +| `Mesh` | 网格/模型资源 | +| `Material` | 材质资源 | +| `Shader` | 着色器资源 | +| `AudioClip` | 音频资源 | +| `Binary` | 二进制数据 | +| `AnimationClip` | 动画片段 | +| `Skeleton` | 骨骼 | +| `Font` | 字体 | +| `ParticleSystem` | 粒子系统 | +| `Scene` | 场景 | +| `Prefab` | 预制体 | + +--- + +## ResourceGUID + +全局唯一标识符结构体，用于唯一标识每个资源。 + +```cpp +struct ResourceGUID { + Core::uint64 value; + + ResourceGUID() : value(0) {} + explicit ResourceGUID(Core::uint64 v) : value(v) {} + + bool IsValid() const { return value != 0; } + bool operator==(const ResourceGUID& other) const { return value == other.value; } + bool operator!=(const ResourceGUID& other) const { return value != other.value; } + + static ResourceGUID Generate(const char* path); + static ResourceGUID Generate(const Containers::String& path); + + Containers::String ToString() const; +}; +``` + +### 比较运算 + +| 运算符 | 描述 | +|------|------| +| `operator==(ResourceGUID, ResourceGUID)` | 判断相等 | +| `operator!=(ResourceGUID, ResourceGUID)` | 判断不等 | + +### 哈希支持 + +`ResourceGUID` 可作为 HashMap 的键使用（特化了 `std::hash`）。 + +### 静态方法 + +| 方法 | 描述 | +|------|------| +| `static ResourceGUID Generate(const char* path)` | 从资源路径生成唯一 GUID | +| `static ResourceGUID Generate(const Containers::String& path)` | 从资源路径生成唯一 GUID | +| `Containers::String ToString() const` | 转换为字符串 | + +### 辅助函数 + +| 函数 | 描述 | +|------|------| +| `constexpr const char* GetResourceTypeName(ResourceType type)` | 获取资源类型的字符串名称 | + +### 模板特化 + +```cpp +template<> inline ResourceType GetResourceType() { return ResourceType::Texture; } +template<> inline ResourceType GetResourceType() { return ResourceType::Mesh; } +template<> inline ResourceType GetResourceType() { return ResourceType::Material; } +template<> inline ResourceType GetResourceType() { return ResourceType::Shader; } +template<> inline ResourceType GetResourceType() { return ResourceType::AudioClip; } +template<> inline ResourceType GetResourceType() { return ResourceType::Binary; } +``` + +## 使用示例 + +```cpp +// 使用 ResourceGUID +ResourceGUID texGuid = ResourceGUID::Generate("textures/player.png"); +ResourceGUID meshGuid = ResourceGUID::Generate("models/player.fbx"); + +// GUID 比较 +if (texGuid == meshGuid) { + // 相同资源 +} + +// 有效性检查 +if (texGuid.IsValid()) { + // GUID 有效 +} + +// 在 HashMap 中使用 +Containers::HashMap cache; +cache[texGuid] = texture; + +// 获取类型名称 +const char* name = GetResourceTypeName(ResourceType::Texture); // "Texture" + +// 使用模板获取类型 +ResourceType type = GetResourceType(); // ResourceType::Texture +``` + +## 相关文档 + +- [IResource](../iresource/iresource.md) - 资源基类 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/shader/addattribute.md b/docs/api/resources/shader/addattribute.md new file mode 100644 index 00000000..b1d2312e --- /dev/null +++ b/docs/api/resources/shader/addattribute.md @@ -0,0 +1,29 @@ +# Shader::AddAttribute + +```cpp +void AddAttribute(const ShaderAttribute& attribute) +``` + +添加顶点属性描述。 + +**参数：** +- `attribute` - 属性描述结构体 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ShaderAttribute attr; +attr.name = "position"; +attr.location = 0; +attr.size = sizeof(float) * 3; +attr.type = 0; +vs->AddAttribute(attr); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/adduniform.md b/docs/api/resources/shader/adduniform.md new file mode 100644 index 00000000..21d0b5f3 --- /dev/null +++ b/docs/api/resources/shader/adduniform.md @@ -0,0 +1,29 @@ +# Shader::AddUniform + +```cpp +void AddUniform(const ShaderUniform& uniform) +``` + +添加 Uniform 变量描述。 + +**参数：** +- `uniform` - Uniform 描述结构体 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ShaderUniform uniform; +uniform.name = "modelMatrix"; +uniform.location = 0; +uniform.size = sizeof(float) * 16; +uniform.type = 0; +vs->AddUniform(uniform); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/resources-shader.md b/docs/api/resources/shader/shader.md similarity index 94% rename from docs/api/resources/resources-shader.md rename to docs/api/resources/shader/shader.md index 22f5b2fc..82acf222 100644 --- a/docs/api/resources/resources-shader.md +++ b/docs/api/resources/shader/shader.md @@ -144,6 +144,7 @@ RHIShader* rhiShader = vs->GetRHIResource(); ## 相关文档 -- [IResource](./resources-iresource.md) - 资源基类 -- [RHIShader](../rhi/rhi-shader.md) - RHI 着色器接口 -- [Material](./resources-material.md) - 材质资源 +- [IResource](../iresource/iresource.md) - 资源基类 +- [RHIShader](../../rhi/shader/shader.md) - RHI 着色器接口 +- [Material](../material/material.md) - 材质资源 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/texture/create.md b/docs/api/resources/texture/create.md new file mode 100644 index 00000000..2c1ad787 --- /dev/null +++ b/docs/api/resources/texture/create.md @@ -0,0 +1,39 @@ +# Texture::Create + +```cpp +bool Create(Core::uint32 width, Core::uint32 height, Core::uint32 depth, + Core::uint32 mipLevels, TextureType type, TextureFormat format, + const void* data, size_t dataSize) +``` + +创建纹理资源。设置纹理的尺寸、格式和像素数据，并分配 GPU 资源。 + +**参数：** +- `width` - 纹理宽度（像素） +- `height` - 纹理高度（像素） +- `depth` - 纹理深度（3D 纹理设为 1） +- `mipLevels` - Mipmap 级别数（0 表示自动生成所有级别） +- `type` - 纹理类型 +- `format` - 纹理格式 +- `data` - 像素数据指针 +- `dataSize` - 像素数据大小 + +**返回：** 创建成功返回 true + +**复杂度：** O(n)，n 为像素数量 + +**示例：** + +```cpp +Texture tex; +bool ok = tex.Create( + 1024, 1024, 1, 0, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + pixelData, pixelDataSize +); +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 diff --git a/docs/api/resources/texture/generatemipmaps.md b/docs/api/resources/texture/generatemipmaps.md new file mode 100644 index 00000000..37a51645 --- /dev/null +++ b/docs/api/resources/texture/generatemipmaps.md @@ -0,0 +1,24 @@ +# Texture::GenerateMipmaps + +```cpp +bool GenerateMipmaps() +``` + +生成纹理的 Mipmap 链。根据基础级别纹理自动生成所有下采样级别，用于纹理在缩小渲染时避免闪烁。 + +**参数：** 无 + +**返回：** 生成成功返回 true + +**复杂度：** O(n) + +**示例：** + +```cpp +tex.Create(1024, 1024, 1, 1, TextureType::Texture2D, TextureFormat::RGBA8_UNORM, data, size); +tex.GenerateMipmaps(); +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 diff --git a/docs/api/resources/resources-texture.md b/docs/api/resources/texture/texture.md similarity index 94% rename from docs/api/resources/resources-texture.md rename to docs/api/resources/texture/texture.md index 90e56fdb..5582e945 100644 --- a/docs/api/resources/resources-texture.md +++ b/docs/api/resources/texture/texture.md @@ -147,6 +147,7 @@ uint32_t h = tex.GetHeight(); ## 相关文档 -- [IResource](./resources-iresource.md) - 资源基类 -- [ResourceManager](./resources-resourcemanager.md) - 资源管理器 -- [RHITexture](../rhi/rhi-texture.md) - RHI 纹理接口 +- [IResource](../iresource/iresource.md) - 资源基类 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [RHITexture](../../rhi/texture/texture.md) - RHI 纹理接口 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/rhi/rhi-buffer.md b/docs/api/rhi/buffer/buffer.md similarity index 57% rename from docs/api/rhi/rhi-buffer.md rename to docs/api/rhi/buffer/buffer.md index b0b0a7c9..3bdab6dc 100644 --- a/docs/api/rhi/rhi-buffer.md +++ b/docs/api/rhi/buffer/buffer.md @@ -12,44 +12,44 @@ ## 公共方法 -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual void Shutdown()` | 释放缓冲区资源 | - ### 数据操作 -| 方法 | 描述 | +| 方法 | 文档 | |------|------| -| `virtual void* Map()` | 映射缓冲区内存到 CPU 可访问 | -| `virtual void Unmap()` | 取消内存映射 | -| `virtual void SetData(const void* data, size_t size, size_t offset = 0)` | 设置缓冲区数据 | +| `Map` | [详细文档](map.md) | +| `Unmap` | [详细文档](unmap.md) | +| `SetData` | [详细文档](set-data.md) | ### 属性访问 -| 方法 | 描述 | +| 方法 | 文档 | |------|------| -| `virtual uint64_t GetSize() const` | 获取缓冲区大小（字节） | -| `virtual BufferType GetBufferType() const` | 获取缓冲区类型 | -| `virtual void SetBufferType(BufferType type)` | 设置缓冲区类型 | -| `virtual uint32_t GetStride() const` | 获取单个元素的字节大小 | -| `virtual void SetStride(uint32_t stride)` | 设置元素字节大小 | +| `GetSize` | [详细文档](get-size.md) | +| `GetBufferType` | [详细文档](get-buffer-type.md) | +| `SetBufferType` | [详细文档](set-buffer-type.md) | +| `GetStride` | [详细文档](get-stride.md) | +| `SetStride` | [详细文档](set-stride.md) | ### 状态管理 -| 方法 | 描述 | +| 方法 | 文档 | |------|------| -| `virtual ResourceStates GetState() const` | 获取当前资源状态 | -| `virtual void SetState(ResourceStates state)` | 设置资源状态 | +| `GetState` | [详细文档](get-state.md) | +| `SetState` | [详细文档](set-state.md) | + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | ### 其他 -| 方法 | 描述 | +| 方法 | 文档 | |------|------| -| `virtual void* GetNativeHandle()` | 获取原生 API 句柄 | -| `virtual const std::string& GetName() const` | 获取缓冲区名称 | -| `virtual void SetName(const std::string& name)` | 设置缓冲区名称（用于调试） | +| `GetNativeHandle` | [详细文档](get-native-handle.md) | +| `GetName` | [详细文档](get-name.md) | +| `SetName` | [详细文档](set-name.md) | ## 缓冲区类型 (BufferType) @@ -81,7 +81,6 @@ ## 使用示例 ```cpp -// 创建设备后创建顶点缓冲 BufferDesc desc; desc.size = sizeof(Vertex) * vertexCount; desc.stride = sizeof(Vertex); @@ -90,20 +89,17 @@ desc.flags = 0; RHIBuffer* vertexBuffer = device->CreateBuffer(desc); -// 上传顶点数据 void* mapped = vertexBuffer->Map(); memcpy(mapped, vertexData, desc.size); vertexBuffer->Unmap(); -// 设置资源状态为顶点缓冲 vertexBuffer->SetState(ResourceStates::VertexAndConstantBuffer); - -// 使用完毕后关闭 vertexBuffer->Shutdown(); ``` ## 相关文档 -- [RHIDevice](./rhi-device.md) - 创建设备 -- [RHITexture](./rhi-texture.md) - 纹理资源 -- [RHICommandList](./rhi-command-list.md) - 命令列表 +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHIDevice](../device/device.md) - 创建设备 +- [RHITexture](../texture/texture.md) - 纹理资源 +- [RHICommandList](../command-list/command-list.md) - 命令列表 diff --git a/docs/api/rhi/buffer/get-buffer-type.md b/docs/api/rhi/buffer/get-buffer-type.md new file mode 100644 index 00000000..df2d53ff --- /dev/null +++ b/docs/api/rhi/buffer/get-buffer-type.md @@ -0,0 +1,15 @@ +# RHIBuffer::GetBufferType + +```cpp +virtual BufferType GetBufferType() const = 0; +``` + +获取缓冲区类型。 + +**返回：** 缓冲区类型枚举值 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/get-name.md b/docs/api/rhi/buffer/get-name.md new file mode 100644 index 00000000..749f53fc --- /dev/null +++ b/docs/api/rhi/buffer/get-name.md @@ -0,0 +1,15 @@ +# RHIBuffer::GetName + +```cpp +virtual const std::string& GetName() const = 0; +``` + +获取缓冲区名称（用于调试）。 + +**返回：** 缓冲区名称 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/get-native-handle.md b/docs/api/rhi/buffer/get-native-handle.md new file mode 100644 index 00000000..dabc40f9 --- /dev/null +++ b/docs/api/rhi/buffer/get-native-handle.md @@ -0,0 +1,17 @@ +# RHIBuffer::GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取原生 API 句柄。 + +**返回：** +- D3D12: `ID3D12Resource*` +- OpenGL: `GLuint` 指针 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/get-size.md b/docs/api/rhi/buffer/get-size.md new file mode 100644 index 00000000..1e09922d --- /dev/null +++ b/docs/api/rhi/buffer/get-size.md @@ -0,0 +1,15 @@ +# RHIBuffer::GetSize + +```cpp +virtual uint64_t GetSize() const = 0; +``` + +获取缓冲区大小（字节）。 + +**返回：** 缓冲区大小 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/get-state.md b/docs/api/rhi/buffer/get-state.md new file mode 100644 index 00000000..c5818c83 --- /dev/null +++ b/docs/api/rhi/buffer/get-state.md @@ -0,0 +1,15 @@ +# RHIBuffer::GetState + +```cpp +virtual ResourceStates GetState() const = 0; +``` + +获取当前资源状态。 + +**返回：** 资源状态枚举值 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/get-stride.md b/docs/api/rhi/buffer/get-stride.md new file mode 100644 index 00000000..82b29828 --- /dev/null +++ b/docs/api/rhi/buffer/get-stride.md @@ -0,0 +1,15 @@ +# RHIBuffer::GetStride + +```cpp +virtual uint32_t GetStride() const = 0; +``` + +获取单个元素的字节大小。 + +**返回：** 元素步长（字节） + +**复杂度：** O(1) + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/map.md b/docs/api/rhi/buffer/map.md new file mode 100644 index 00000000..70ef5a7d --- /dev/null +++ b/docs/api/rhi/buffer/map.md @@ -0,0 +1,25 @@ +# RHIBuffer::Map + +```cpp +virtual void* Map() = 0; +``` + +映射缓冲区内存到 CPU 可访问空间。 + +**返回：** 指向缓冲区数据的指针 + +**复杂度：** O(1) + +**示例：** + +```cpp +void* data = buffer->Map(); +if (data) { + memcpy(data, vertexData, bufferSize); + buffer->Unmap(); +} +``` + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/set-buffer-type.md b/docs/api/rhi/buffer/set-buffer-type.md new file mode 100644 index 00000000..2541eb61 --- /dev/null +++ b/docs/api/rhi/buffer/set-buffer-type.md @@ -0,0 +1,16 @@ +# RHIBuffer::SetBufferType + +```cpp +virtual void SetBufferType(BufferType type) = 0; +``` + +设置缓冲区类型。 + +**参数：** +- `type` - 新的缓冲区类型 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/set-data.md b/docs/api/rhi/buffer/set-data.md new file mode 100644 index 00000000..4c390b57 --- /dev/null +++ b/docs/api/rhi/buffer/set-data.md @@ -0,0 +1,29 @@ +# RHIBuffer::SetData + +```cpp +virtual void SetData(const void* data, size_t size, size_t offset = 0) = 0; +``` + +设置缓冲区数据。 + +**参数：** +- `data` - 源数据指针 +- `size` - 数据大小（字节） +- `offset` - 缓冲区内的偏移量 + +**复杂度：** O(n) + +**示例：** + +```cpp +Vertex vertices[] = { + {0.0f, 0.5f, 0.0f}, + {0.5f, -0.5f, 0.0f}, + {-0.5f, -0.5f, 0.0f} +}; +buffer->SetData(vertices, sizeof(vertices), 0); +``` + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/set-name.md b/docs/api/rhi/buffer/set-name.md new file mode 100644 index 00000000..62d6a46c --- /dev/null +++ b/docs/api/rhi/buffer/set-name.md @@ -0,0 +1,22 @@ +# RHIBuffer::SetName + +```cpp +virtual void SetName(const std::string& name) = 0; +``` + +设置缓冲区名称（用于调试）。 + +**参数：** +- `name` - 新名称 + +**复杂度：** O(1) + +**示例：** + +```cpp +buffer->SetName("VertexBuffer_Main"); +``` + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/set-state.md b/docs/api/rhi/buffer/set-state.md new file mode 100644 index 00000000..6bc3eaaa --- /dev/null +++ b/docs/api/rhi/buffer/set-state.md @@ -0,0 +1,22 @@ +# RHIBuffer::SetState + +```cpp +virtual void SetState(ResourceStates state) = 0; +``` + +设置资源状态。 + +**参数：** +- `state` - 新的资源状态 + +**复杂度：** O(1) + +**示例：** + +```cpp +buffer->SetState(ResourceStates::VertexAndConstantBuffer); +``` + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/set-stride.md b/docs/api/rhi/buffer/set-stride.md new file mode 100644 index 00000000..fea09316 --- /dev/null +++ b/docs/api/rhi/buffer/set-stride.md @@ -0,0 +1,16 @@ +# RHIBuffer::SetStride + +```cpp +virtual void SetStride(uint32_t stride) = 0; +``` + +设置元素字节大小。 + +**参数：** +- `stride` - 新的步长值 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/shutdown.md b/docs/api/rhi/buffer/shutdown.md new file mode 100644 index 00000000..568391e5 --- /dev/null +++ b/docs/api/rhi/buffer/shutdown.md @@ -0,0 +1,13 @@ +# RHIBuffer::Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +释放缓冲区资源。 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/unmap.md b/docs/api/rhi/buffer/unmap.md new file mode 100644 index 00000000..51b5bf9a --- /dev/null +++ b/docs/api/rhi/buffer/unmap.md @@ -0,0 +1,21 @@ +# RHIBuffer::Unmap + +```cpp +virtual void Unmap() = 0; +``` + +取消内存映射。 + +**复杂度：** O(1) + +**示例：** + +```cpp +buffer->Map(); +memcpy(mappedData, sourceData, size); +buffer->Unmap(); +``` + +## 相关文档 + +- [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/rhi-capabilities.md b/docs/api/rhi/capabilities/capabilities.md similarity index 75% rename from docs/api/rhi/rhi-capabilities.md rename to docs/api/rhi/capabilities/capabilities.md index c450b5c2..21e409df 100644 --- a/docs/api/rhi/rhi-capabilities.md +++ b/docs/api/rhi/capabilities/capabilities.md @@ -6,10 +6,6 @@ **描述**: GPU 设备能力结构体，描述了当前图形设备支持的各种功能和限制。 -## 概述 - -`RHICapabilities` 存储了设备的能力信息，包括对各种图形特性的支持情况和资源尺寸限制。 - ## 公共成员 ### 特性支持 @@ -44,18 +40,6 @@ | `maxAnisotropy` | `uint32_t` | 最大各向异性级别 | | `maxColorAttachments` | `uint32_t` | 最大颜色附件数量 | -### 线/点渲染 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `minSmoothedLineWidth` | `float` | 最小平滑线宽 | -| `maxSmoothedLineWidth` | `float` | 最大平滑线宽 | -| `minPointSize` | `float` | 最小点大小 | -| `maxPointSize` | `float` | 最大点大小 | -| `maxPointSizeAA` | `float` | 抗锯齿最大点大小 | -| `maxLineWidth` | `float` | 最大线宽 | -| `maxLineWidthAA` | `float` | 抗锯齿最大线宽 | - ### 版本信息 | 成员 | 类型 | 描述 | @@ -67,22 +51,20 @@ ## 使用示例 ```cpp -// 获取设备能力 const RHICapabilities& caps = device->GetCapabilities(); -// 检查功能支持 if (caps.bSupportsRayTracing) { // 启用光线追踪功能 } if (caps.bSupportsComputeShaders) { - // 启用计算着色器功能 + // 启用计算着色器 } -// 使用资源限制 uint32_t textureSize = std::min(requestedSize, caps.maxTexture2DSize); ``` ## 相关文档 -- [RHIDevice](./rhi-device.md) - 设备对象 +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHIDevice](../device/device.md) - 设备对象 diff --git a/docs/api/rhi/command-list/clear-depth-stencil.md b/docs/api/rhi/command-list/clear-depth-stencil.md new file mode 100644 index 00000000..e9e34928 --- /dev/null +++ b/docs/api/rhi/command-list/clear-depth-stencil.md @@ -0,0 +1,22 @@ +# RHICommandList::ClearDepthStencil + +```cpp +virtual void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) = 0; +``` + +清除深度模板缓冲区。 + +**参数：** +- `depthStencil` - 深度模板缓冲区指针 +- `depth` - 深度值 +- `stencil` - 模板值 + +**示例：** + +```cpp +cmdList->ClearDepthStencil(depthStencil, 1.0f, 0); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/clear-render-target.md b/docs/api/rhi/command-list/clear-render-target.md new file mode 100644 index 00000000..2534b1d0 --- /dev/null +++ b/docs/api/rhi/command-list/clear-render-target.md @@ -0,0 +1,22 @@ +# RHICommandList::ClearRenderTarget + +```cpp +virtual void ClearRenderTarget(void* renderTarget, const float color[4]) = 0; +``` + +清除渲染目标。 + +**参数：** +- `renderTarget` - 渲染目标指针 +- `color` - 清除颜色 [r, g, b, a] + +**示例：** + +```cpp +float color[4] = {0.0f, 0.0f, 0.0f, 1.0f}; +cmdList->ClearRenderTarget(renderTarget, color); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/command-list.md b/docs/api/rhi/command-list/command-list.md new file mode 100644 index 00000000..296ff196 --- /dev/null +++ b/docs/api/rhi/command-list/command-list.md @@ -0,0 +1,102 @@ +# RHICommandList + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: GPU 命令列表抽象接口，用于录制和执行 GPU 命令。 + +## 公共方法 + +### 命令录制控制 + +| 方法 | 文档 | +|------|------| +| `Reset` | [详细文档](../../resources/resourcehandle/reset.md) | +| `Close` | [详细文档](../../core/filewriter/close.md) | + +### 资源状态转换 + +| 方法 | 文档 | +|------|------| +| `TransitionBarrier` | [详细文档](transition-barrier.md) | + +### 渲染状态设置 + +| 方法 | 文档 | +|------|------| +| `SetPipelineState` | [详细文档](set-pipeline-state.md) | +| `SetPrimitiveTopology` | [详细文档](set-primitive-topology.md) | +| `SetViewport` | [详细文档](set-viewport.md) | +| `SetViewports` | [详细文档](set-viewports.md) | +| `SetScissorRect` | [详细文档](set-scissor-rect.md) | +| `SetScissorRects` | [详细文档](set-scissor-rects.md) | +| `SetRenderTargets` | [详细文档](set-render-targets.md) | + +### 深度/混合状态 + +| 方法 | 文档 | +|------|------| +| `SetDepthStencilState` | [详细文档](set-depth-stencil-state.md) | +| `SetStencilRef` | [详细文档](set-stencil-ref.md) | +| `SetBlendState` | [详细文档](set-blend-state.md) | +| `SetBlendFactor` | [详细文档](set-blend-factor.md) | + +### 顶点/索引缓冲 + +| 方法 | 文档 | +|------|------| +| `SetVertexBuffer` | [详细文档](set-vertex-buffer.md) | +| `SetVertexBuffers` | [详细文档](set-vertex-buffers.md) | +| `SetIndexBuffer` | [详细文档](set-index-buffer.md) | + +### 绘制命令 + +| 方法 | 文档 | +|------|------| +| `Draw` | [详细文档](draw.md) | +| `DrawIndexed` | [详细文档](draw-indexed.md) | + +### 清除命令 + +| 方法 | 文档 | +|------|------| +| `Clear` | [详细文档](../../memory/linear-allocator/clear.md) | +| `ClearRenderTarget` | [详细文档](clear-render-target.md) | +| `ClearDepthStencil` | [详细文档](clear-depth-stencil.md) | + +### 资源复制 + +| 方法 | 文档 | +|------|------| +| `CopyResource` | [详细文档](copy-resource.md) | + +### 计算着色器 + +| 方法 | 文档 | +|------|------| +| `Dispatch` | [详细文档](dispatch.md) | + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | + +## 使用示例 + +```cpp +commandList->Reset(); +commandList->SetPipelineState(pipelineState); +commandList->SetPrimitiveTopology(PrimitiveTopology::TriangleList); +commandList->SetViewport(viewport); +commandList->SetRenderTargets(1, &renderTarget, depthStencil); +commandList->DrawIndexed(indexCount, 1, 0, 0, 0); +commandList->Close(); +commandQueue->ExecuteCommandLists(1, (void**)&commandList); +``` + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHICommandQueue](../command-queue/command-queue.md) - 命令队列 diff --git a/docs/api/rhi/command-list/copy-resource.md b/docs/api/rhi/command-list/copy-resource.md new file mode 100644 index 00000000..e1aa6446 --- /dev/null +++ b/docs/api/rhi/command-list/copy-resource.md @@ -0,0 +1,21 @@ +# RHICommandList::CopyResource + +```cpp +virtual void CopyResource(void* dst, void* src) = 0; +``` + +复制资源。 + +**参数：** +- `dst` - 目标资源 +- `src` - 源资源 + +**示例：** + +```cpp +cmdList->CopyResource(dstTexture, srcTexture); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/dispatch.md b/docs/api/rhi/command-list/dispatch.md new file mode 100644 index 00000000..c1b24b53 --- /dev/null +++ b/docs/api/rhi/command-list/dispatch.md @@ -0,0 +1,22 @@ +# RHICommandList::Dispatch + +```cpp +virtual void Dispatch(uint32_t x, uint32_t y, uint32_t z) = 0; +``` + +分发计算着色器。 + +**参数：** +- `x` - X 方向线程组数量 +- `y` - Y 方向线程组数量 +- `z` - Z 方向线程组数量 + +**示例：** + +```cpp +cmdList->Dispatch(8, 8, 1); // 分发 8x8x1 线程组 +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/draw-indexed.md b/docs/api/rhi/command-list/draw-indexed.md new file mode 100644 index 00000000..1d7e5fa0 --- /dev/null +++ b/docs/api/rhi/command-list/draw-indexed.md @@ -0,0 +1,24 @@ +# RHICommandList::DrawIndexed + +```cpp +virtual void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) = 0; +``` + +绘制索引图元。 + +**参数：** +- `indexCount` - 索引数量 +- `instanceCount` - 实例数量（默认1） +- `startIndex` - 起始索引 +- `baseVertex` - 基础顶点索引 +- `startInstance` - 起始实例索引 + +**示例：** + +```cpp +cmdList->DrawIndexed(36); // 绘制36个索引 +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/draw.md b/docs/api/rhi/command-list/draw.md new file mode 100644 index 00000000..70914f1d --- /dev/null +++ b/docs/api/rhi/command-list/draw.md @@ -0,0 +1,23 @@ +# RHICommandList::Draw + +```cpp +virtual void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) = 0; +``` + +绘制调用。 + +**参数：** +- `vertexCount` - 顶点数量 +- `instanceCount` - 实例数量（默认1） +- `startVertex` - 起始顶点索引 +- `startInstance` - 起始实例索引 + +**示例：** + +```cpp +cmdList->Draw(36); // 绘制36个顶点 +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/methods.md b/docs/api/rhi/command-list/methods.md new file mode 100644 index 00000000..ed6e704c --- /dev/null +++ b/docs/api/rhi/command-list/methods.md @@ -0,0 +1,201 @@ +# RHICommandList 方法 + +## Reset + +```cpp +virtual void Reset() = 0; +``` + +重置命令列表，开始新的录制。 + +## Close + +```cpp +virtual void Close() = 0; +``` + +关闭命令列表，结束录制。 + +## TransitionBarrier + +```cpp +virtual void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter) = 0; +``` + +资源状态转换屏障。 + +## SetPipelineState + +```cpp +virtual void SetPipelineState(void* pso) = 0; +``` + +设置管线状态对象。 + +## SetPrimitiveTopology + +```cpp +virtual void SetPrimitiveTopology(PrimitiveTopology topology) = 0; +``` + +设置图元拓扑。 + +## SetViewport + +```cpp +virtual void SetViewport(const Viewport& viewport) = 0; +``` + +设置视口。 + +## SetViewports + +```cpp +virtual void SetViewports(uint32_t count, const Viewport* viewports) = 0; +``` + +设置多个视口。 + +## SetScissorRect + +```cpp +virtual void SetScissorRect(const Rect& rect) = 0; +``` + +设置裁剪矩形。 + +## SetScissorRects + +```cpp +virtual void SetScissorRects(uint32_t count, const Rect* rects) = 0; +``` + +设置多个裁剪矩形。 + +## SetRenderTargets + +```cpp +virtual void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr) = 0; +``` + +设置渲染目标。 + +## SetDepthStencilState + +```cpp +virtual void SetDepthStencilState(const DepthStencilState& state) = 0; +``` + +设置深度模板状态。 + +## SetStencilRef + +```cpp +virtual void SetStencilRef(uint8_t ref) = 0; +``` + +设置模板参考值。 + +## SetBlendState + +```cpp +virtual void SetBlendState(const BlendState& state) = 0; +``` + +设置混合状态。 + +## SetBlendFactor + +```cpp +virtual void SetBlendFactor(const float factor[4]) = 0; +``` + +设置混合因子。 + +## SetVertexBuffer + +```cpp +virtual void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride) = 0; +``` + +设置顶点缓冲。 + +## SetVertexBuffers + +```cpp +virtual void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides) = 0; +``` + +设置多个顶点缓冲。 + +## SetIndexBuffer + +```cpp +virtual void SetIndexBuffer(void* buffer, uint64_t offset, Format format) = 0; +``` + +设置索引缓冲。 + +## Draw + +```cpp +virtual void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) = 0; +``` + +绘制调用。 + +## DrawIndexed + +```cpp +virtual void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) = 0; +``` + +索引绘制调用。 + +## Clear + +```cpp +virtual void Clear(float r, float g, float b, float a, uint32_t buffers) = 0; +``` + +清除缓冲。 + +## ClearRenderTarget + +```cpp +virtual void ClearRenderTarget(void* renderTarget, const float color[4]) = 0; +``` + +清除渲染目标。 + +## ClearDepthStencil + +```cpp +virtual void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) = 0; +``` + +清除深度模板。 + +## CopyResource + +```cpp +virtual void CopyResource(void* dst, void* src) = 0; +``` + +复制资源。 + +## Dispatch + +```cpp +virtual void Dispatch(uint32_t x, uint32_t y, uint32_t z) = 0; +``` + +分发计算着色器。 + +## Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +释放命令列表资源。 diff --git a/docs/api/rhi/command-list/set-blend-factor.md b/docs/api/rhi/command-list/set-blend-factor.md new file mode 100644 index 00000000..a075922e --- /dev/null +++ b/docs/api/rhi/command-list/set-blend-factor.md @@ -0,0 +1,21 @@ +# RHICommandList::SetBlendFactor + +```cpp +virtual void SetBlendFactor(const float factor[4]) = 0; +``` + +设置混合因子。 + +**参数：** +- `factor` - 混合因子数组 [r, g, b, a] + +**示例：** + +```cpp +float factor[4] = {0.5f, 0.5f, 0.5f, 1.0f}; +cmdList->SetBlendFactor(factor); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-blend-state.md b/docs/api/rhi/command-list/set-blend-state.md new file mode 100644 index 00000000..2ec1ae30 --- /dev/null +++ b/docs/api/rhi/command-list/set-blend-state.md @@ -0,0 +1,23 @@ +# RHICommandList::SetBlendState + +```cpp +virtual void SetBlendState(const BlendState& state) = 0; +``` + +设置混合状态。 + +**参数：** +- `state` - 混合状态结构体 + +**示例：** + +```cpp +BlendState blendState; +blendState.alphaToCoverageEnable = false; +blendState.independentBlendEnable = false; +cmdList->SetBlendState(blendState); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-depth-stencil-state.md b/docs/api/rhi/command-list/set-depth-stencil-state.md new file mode 100644 index 00000000..1bf38d7b --- /dev/null +++ b/docs/api/rhi/command-list/set-depth-stencil-state.md @@ -0,0 +1,24 @@ +# RHICommandList::SetDepthStencilState + +```cpp +virtual void SetDepthStencilState(const DepthStencilState& state) = 0; +``` + +设置深度模板状态。 + +**参数：** +- `state` - 深度模板状态结构体 + +**示例：** + +```cpp +DepthStencilState dsState; +dsState.depthEnable = true; +dsState.depthWriteMask = true; +dsState.depthFunc = ComparisonFunc::Less; +cmdList->SetDepthStencilState(dsState); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-index-buffer.md b/docs/api/rhi/command-list/set-index-buffer.md new file mode 100644 index 00000000..3698cc9a --- /dev/null +++ b/docs/api/rhi/command-list/set-index-buffer.md @@ -0,0 +1,22 @@ +# RHICommandList::SetIndexBuffer + +```cpp +virtual void SetIndexBuffer(void* buffer, uint64_t offset, Format format) = 0; +``` + +设置索引缓冲区。 + +**参数：** +- `buffer` - 索引缓冲区指针 +- `offset` - 数据偏移量 +- `format` - 索引格式（R16_UINT 或 R32_UINT） + +**示例：** + +```cpp +cmdList->SetIndexBuffer(indexBuffer, 0, Format::R16_UINT); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-pipeline-state.md b/docs/api/rhi/command-list/set-pipeline-state.md new file mode 100644 index 00000000..98ac03e1 --- /dev/null +++ b/docs/api/rhi/command-list/set-pipeline-state.md @@ -0,0 +1,20 @@ +# RHICommandList::SetPipelineState + +```cpp +virtual void SetPipelineState(void* pso) = 0; +``` + +设置渲染管线状态对象。 + +**参数：** +- `pso` - 管线状态对象指针 + +**示例：** + +```cpp +cmdList->SetPipelineState(pipelineState); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-primitive-topology.md b/docs/api/rhi/command-list/set-primitive-topology.md new file mode 100644 index 00000000..4efd502b --- /dev/null +++ b/docs/api/rhi/command-list/set-primitive-topology.md @@ -0,0 +1,20 @@ +# RHICommandList::SetPrimitiveTopology + +```cpp +virtual void SetPrimitiveTopology(PrimitiveTopology topology) = 0; +``` + +设置图元拓扑类型。 + +**参数：** +- `topology` - 图元拓扑类型（点、线、三角形等） + +**示例：** + +```cpp +cmdList->SetPrimitiveTopology(PrimitiveTopology::TriangleList); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-render-targets.md b/docs/api/rhi/command-list/set-render-targets.md new file mode 100644 index 00000000..3e826cd6 --- /dev/null +++ b/docs/api/rhi/command-list/set-render-targets.md @@ -0,0 +1,23 @@ +# RHICommandList::SetRenderTargets + +```cpp +virtual void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr) = 0; +``` + +设置渲染目标和深度模板缓冲区。 + +**参数：** +- `count` - 渲染目标数量 +- `renderTargets` - 渲染目标数组 +- `depthStencil` - 深度模板缓冲区（可选） + +**示例：** + +```cpp +void* targets[1] = {renderTarget}; +cmdList->SetRenderTargets(1, targets, depthStencil); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-scissor-rect.md b/docs/api/rhi/command-list/set-scissor-rect.md new file mode 100644 index 00000000..5cc7a751 --- /dev/null +++ b/docs/api/rhi/command-list/set-scissor-rect.md @@ -0,0 +1,25 @@ +# RHICommandList::SetScissorRect + +```cpp +virtual void SetScissorRect(const Rect& rect) = 0; +``` + +设置裁剪矩形。 + +**参数：** +- `rect` - 裁剪矩形结构体 + +**示例：** + +```cpp +Rect rect; +rect.left = 0; +rect.top = 0; +rect.right = 640; +rect.bottom = 480; +cmdList->SetScissorRect(rect); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-scissor-rects.md b/docs/api/rhi/command-list/set-scissor-rects.md new file mode 100644 index 00000000..fa857b9c --- /dev/null +++ b/docs/api/rhi/command-list/set-scissor-rects.md @@ -0,0 +1,24 @@ +# RHICommandList::SetScissorRects + +```cpp +virtual void SetScissorRects(uint32_t count, const Rect* rects) = 0; +``` + +设置多个裁剪矩形。 + +**参数：** +- `count` - 裁剪矩形数量 +- `rects` - 裁剪矩形数组指针 + +**示例：** + +```cpp +Rect rects[2]; +rects[0] = {0, 0, 640, 480}; +rects[1] = {640, 0, 640, 480}; +cmdList->SetScissorRects(2, rects); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-stencil-ref.md b/docs/api/rhi/command-list/set-stencil-ref.md new file mode 100644 index 00000000..eb1f4d05 --- /dev/null +++ b/docs/api/rhi/command-list/set-stencil-ref.md @@ -0,0 +1,20 @@ +# RHICommandList::SetStencilRef + +```cpp +virtual void SetStencilRef(uint8_t ref) = 0; +``` + +设置模板参考值。 + +**参数：** +- `ref` - 模板参考值 + +**示例：** + +```cpp +cmdList->SetStencilRef(0xFF); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-vertex-buffer.md b/docs/api/rhi/command-list/set-vertex-buffer.md new file mode 100644 index 00000000..0b13f64a --- /dev/null +++ b/docs/api/rhi/command-list/set-vertex-buffer.md @@ -0,0 +1,23 @@ +# RHICommandList::SetVertexBuffer + +```cpp +virtual void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride) = 0; +``` + +设置顶点缓冲区。 + +**参数：** +- `slot` - 顶点缓冲区槽位 +- `buffer` - 顶点缓冲区指针 +- `offset` - 数据偏移量 +- `stride` - 顶点步长 + +**示例：** + +```cpp +cmdList->SetVertexBuffer(0, vertexBuffer, 0, sizeof(Vertex)); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-vertex-buffers.md b/docs/api/rhi/command-list/set-vertex-buffers.md new file mode 100644 index 00000000..23bfd83b --- /dev/null +++ b/docs/api/rhi/command-list/set-vertex-buffers.md @@ -0,0 +1,27 @@ +# RHICommandList::SetVertexBuffers + +```cpp +virtual void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides) = 0; +``` + +设置多个顶点缓冲区。 + +**参数：** +- `startSlot` - 起始槽位 +- `count` - 缓冲区数量 +- `buffers` - 缓冲区指针数组 +- `offsets` - 偏移量数组 +- `strides` - 步长数组 + +**示例：** + +```cpp +uint64_t buffers[2] = {(uint64_t)vb1, (uint64_t)vb2}; +uint64_t offsets[2] = {0, 0}; +uint32_t strides[2] = {sizeof(Vertex), sizeof(Vertex)}; +cmdList->SetVertexBuffers(0, 2, buffers, offsets, strides); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-viewport.md b/docs/api/rhi/command-list/set-viewport.md new file mode 100644 index 00000000..53cff939 --- /dev/null +++ b/docs/api/rhi/command-list/set-viewport.md @@ -0,0 +1,27 @@ +# RHICommandList::SetViewport + +```cpp +virtual void SetViewport(const Viewport& viewport) = 0; +``` + +设置视口。 + +**参数：** +- `viewport` - 视口结构体 + +**示例：** + +```cpp +Viewport vp; +vp.topLeftX = 0; +vp.topLeftY = 0; +vp.width = 1280; +vp.height = 720; +vp.minDepth = 0.0f; +vp.maxDepth = 1.0f; +cmdList->SetViewport(vp); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/set-viewports.md b/docs/api/rhi/command-list/set-viewports.md new file mode 100644 index 00000000..13640fb1 --- /dev/null +++ b/docs/api/rhi/command-list/set-viewports.md @@ -0,0 +1,24 @@ +# RHICommandList::SetViewports + +```cpp +virtual void SetViewports(uint32_t count, const Viewport* viewports) = 0; +``` + +设置多个视口。 + +**参数：** +- `count` - 视口数量 +- `viewports` - 视口数组指针 + +**示例：** + +```cpp +Viewport viewports[2]; +viewports[0] = {0, 0, 640, 720, 0.0f, 1.0f}; +viewports[1] = {640, 0, 640, 720, 0.0f, 1.0f}; +cmdList->SetViewports(2, viewports); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-list/transition-barrier.md b/docs/api/rhi/command-list/transition-barrier.md new file mode 100644 index 00000000..2c0a7efd --- /dev/null +++ b/docs/api/rhi/command-list/transition-barrier.md @@ -0,0 +1,23 @@ +# RHICommandList::TransitionBarrier + +```cpp +virtual void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter) = 0; +``` + +设置资源状态转换屏障，确保 GPU 资源在状态转换前完成所有操作。 + +**参数：** +- `resource` - 目标资源指针 +- `stateBefore` - 转换前的资源状态 +- `stateAfter` - 转换后的资源状态 + +**示例：** + +```cpp +// 将纹理从渲染目标状态转换到着色器读取状态 +cmdList->TransitionBarrier(texture, ResourceStates::RenderTarget, ResourceStates::ShaderResource); +``` + +## 相关文档 + +- [RHICommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/command-queue/command-queue.md b/docs/api/rhi/command-queue/command-queue.md new file mode 100644 index 00000000..35ba12cd --- /dev/null +++ b/docs/api/rhi/command-queue/command-queue.md @@ -0,0 +1,67 @@ +# RHICommandQueue + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: GPU 命令队列抽象接口，负责提交和执行命令列表，以及 GPU/CPU 同步。 + +## 公共方法 + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | + +### 命令执行 + +| 方法 | 文档 | +|------|------| +| `ExecuteCommandLists` | [详细文档](execute-command-lists.md) | +| `Signal` | [详细文档](signal.md) | +| `Wait` | [详细文档](../../threading/task-group/wait.md) | +| `GetCompletedValue` | [详细文档](get-completed-value.md) | +| `WaitForIdle` | [详细文档](wait-for-idle.md) | + +### 属性访问 + +| 方法 | 文档 | +|------|------| +| `GetType` | [详细文档](../shader/get-type.md) | +| `GetTimestampFrequency` | [详细文档](get-timestamp-frequency.md) | + +### 其他 + +| 方法 | 文档 | +|------|------| +| `GetNativeHandle` | [详细文档](../buffer/get-native-handle.md) | + +## 命令队列类型 (CommandQueueType) + +| 枚举值 | 描述 | +|--------|------| +| `Direct` | 直接队列，用于图形和计算命令 | +| `Compute` | 计算队列，专门用于计算着色器 | +| `Copy` | 复制队列，专门用于资源复制 | + +## 使用示例 + +```cpp +CommandQueueDesc queueDesc; +queueDesc.queueType = (uint32_t)CommandQueueType::Direct; +RHICommandQueue* commandQueue = device->CreateCommandQueue(queueDesc); + +FenceDesc fenceDesc; +RHIFence* fence = device->CreateFence(fenceDesc); + +commandQueue->ExecuteCommandLists(1, (void**)&commandList); +commandQueue->Signal(fence, 1); +fence->Wait(1); +``` + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHICommandList](../command-list/command-list.md) - 命令列表 +- [RHIFence](../fence/fence.md) - 同步栅栏 diff --git a/docs/api/rhi/command-queue/execute-command-lists.md b/docs/api/rhi/command-queue/execute-command-lists.md new file mode 100644 index 00000000..631b5a29 --- /dev/null +++ b/docs/api/rhi/command-queue/execute-command-lists.md @@ -0,0 +1,22 @@ +# RHICommandQueue::ExecuteCommandLists + +```cpp +virtual void ExecuteCommandLists(uint32_t count, void** lists) = 0; +``` + +执行命令列表。 + +**参数：** +- `count` - 命令列表数量 +- `lists` - 命令列表指针数组 + +**示例：** + +```cpp +void* lists[1] = {cmdList}; +cmdQueue->ExecuteCommandLists(1, lists); +``` + +## 相关文档 + +- [RHICommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/command-queue/get-completed-value.md b/docs/api/rhi/command-queue/get-completed-value.md new file mode 100644 index 00000000..bdf98aaf --- /dev/null +++ b/docs/api/rhi/command-queue/get-completed-value.md @@ -0,0 +1,19 @@ +# RHICommandQueue::GetCompletedValue + +```cpp +virtual uint64_t GetCompletedValue() = 0; +``` + +获取栅栏已完成值。 + +**返回：** 已完成的信号值 + +**示例：** + +```cpp +uint64_t value = cmdQueue->GetCompletedValue(); +``` + +## 相关文档 + +- [RHICommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/command-queue/get-timestamp-frequency.md b/docs/api/rhi/command-queue/get-timestamp-frequency.md new file mode 100644 index 00000000..4622fbc3 --- /dev/null +++ b/docs/api/rhi/command-queue/get-timestamp-frequency.md @@ -0,0 +1,19 @@ +# RHICommandQueue::GetTimestampFrequency + +```cpp +virtual uint64_t GetTimestampFrequency() const = 0; +``` + +获取时间戳频率。 + +**返回：** 时间戳频率（每秒计数） + +**示例：** + +```cpp +uint64_t freq = cmdQueue->GetTimestampFrequency(); +``` + +## 相关文档 + +- [RHICommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/command-queue/methods.md b/docs/api/rhi/command-queue/methods.md new file mode 100644 index 00000000..b44ea12c --- /dev/null +++ b/docs/api/rhi/command-queue/methods.md @@ -0,0 +1,73 @@ +# RHICommandQueue 方法 + +## Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +关闭命令队列。 + +## ExecuteCommandLists + +```cpp +virtual void ExecuteCommandLists(uint32_t count, void** lists) = 0; +``` + +执行命令列表。 + +## Signal + +```cpp +virtual void Signal(RHIFence* fence, uint64_t value) = 0; +``` + +信号通知栅栏。 + +## Wait + +```cpp +virtual void Wait(RHIFence* fence, uint64_t value) = 0; +``` + +等待栅栏。 + +## GetCompletedValue + +```cpp +virtual uint64_t GetCompletedValue() = 0; +``` + +获取已完成的值。 + +## WaitForIdle + +```cpp +virtual void WaitForIdle() = 0; +``` + +等待队列空闲。 + +## GetType + +```cpp +virtual CommandQueueType GetType() const = 0; +``` + +获取队列类型。 + +## GetTimestampFrequency + +```cpp +virtual uint64_t GetTimestampFrequency() const = 0; +``` + +获取时间戳频率。 + +## GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取原生 API 句柄。 diff --git a/docs/api/rhi/command-queue/signal.md b/docs/api/rhi/command-queue/signal.md new file mode 100644 index 00000000..c9bcd539 --- /dev/null +++ b/docs/api/rhi/command-queue/signal.md @@ -0,0 +1,21 @@ +# RHICommandQueue::Signal + +```cpp +virtual void Signal(RHIFence* fence, uint64_t value) = 0; +``` + +向栅栏发送信号。 + +**参数：** +- `fence` - 目标栅栏 +- `value` - 信号值 + +**示例：** + +```cpp +cmdQueue->Signal(fence, 1); +``` + +## 相关文档 + +- [RHICommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/command-queue/wait-for-idle.md b/docs/api/rhi/command-queue/wait-for-idle.md new file mode 100644 index 00000000..80a50fc3 --- /dev/null +++ b/docs/api/rhi/command-queue/wait-for-idle.md @@ -0,0 +1,17 @@ +# RHICommandQueue::WaitForIdle + +```cpp +virtual void WaitForIdle() = 0; +``` + +等待命令队列完成所有操作。 + +**示例：** + +```cpp +cmdQueue->WaitForIdle(); +``` + +## 相关文档 + +- [RHICommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/README.md b/docs/api/rhi/d3d12/README.md new file mode 100644 index 00000000..0c5b1e61 --- /dev/null +++ b/docs/api/rhi/d3d12/README.md @@ -0,0 +1,36 @@ +# D3D12 后端组件 + +D3D12 后端已创建以下组件文件夹和文档： + +- `device/` - D3D12Device +- `buffer/` - D3D12Buffer +- `texture/` - D3D12Texture +- `command-list/` - D3D12CommandList +- `command-queue/` - D3D12CommandQueue +- `swap-chain/` - D3D12SwapChain +- `fence/` - D3D12Fence +- `shader/` - D3D12Shader +- `pipeline-state/` - D3D12PipelineState +- `sampler/` - D3D12Sampler +- `root-signature/` - D3D12RootSignature +- `descriptor-heap/` - D3D12DescriptorHeap +- `render-target-view/` - D3D12RenderTargetView +- `depth-stencil-view/` - D3D12DepthStencilView +- `shader-resource-view/` - D3D12ShaderResourceView +- `unordered-access-view/` - D3D12UnorderedAccessView +- `constant-buffer-view/` - D3D12ConstantBufferView +- `command-allocator/` - D3D12CommandAllocator +- `query-heap/` - D3D12QueryHeap +- `screenshot/` - D3D12Screenshot +- `types/` - D3D12 类型转换 +- `enums/` - D3D12 枚举转换 +- `common/` - D3D12 公共工具 + +每个组件文件夹包含: +- `{component}.md` - 类总览 +- `methods.md` - 方法详细文档 + +## 相关文档 + +- [D3D12 后端总览](overview.md) +- [RHI 抽象层](overview.md) diff --git a/docs/api/rhi/d3d12/buffer/buffer.md b/docs/api/rhi/d3d12/buffer/buffer.md new file mode 100644 index 00000000..d4cdd597 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/buffer.md @@ -0,0 +1,33 @@ +# D3D12Buffer + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 缓冲区的 D3D12 实现，继承自 `RHIBuffer`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](initialize.md) | +| `InitializeFromExisting` | [详细文档](initialize-from-existing.md) | +| `InitializeWithData` | [详细文档](initialize-with-data.md) | +| `Shutdown` | [详细文档](shutdown.md) | +| `UpdateData` | [详细文档](update-data.md) | +| `Map` | [详细文档](map.md) | +| `Unmap` | [详细文档](unmap.md) | +| `SetData` | [详细文档](set-data.md) | +| `GetResource` | [详细文档](get-resource.md) | +| `GetDesc` | [详细文档](get-desc.md) | +| `GetGPUVirtualAddress` | [详细文档](get-gpu-virtual-address.md) | +| `GetGPUAddress` | [详细文档](get-gpu-address.md) | +| `GetSize` | [详细文档](get-size.md) | +| `GetState` / `SetState` | [详细文档](get-state.md) | +| `GetName` / `SetName` | [详细文档](get-name.md) | +| `GetStride` / `SetStride` | [详细文档](get-stride.md) | +| `GetBufferType` / `SetBufferType` | [详细文档](get-buffer-type.md) | +| `GetNativeHandle` | [详细文档](get-native-handle.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHIBuffer](../../buffer/buffer.md) - 抽象缓冲区接口 diff --git a/docs/api/rhi/d3d12/buffer/get-buffer-type.md b/docs/api/rhi/d3d12/buffer/get-buffer-type.md new file mode 100644 index 00000000..44698e04 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/get-buffer-type.md @@ -0,0 +1,16 @@ +# D3D12Buffer::GetBufferType / SetBufferType + +## 函数签名 + +```cpp +BufferType GetBufferType() const override +void SetBufferType(BufferType type) override +``` + +## 中文描述 + +获取和设置缓冲区类型（Vertex / Index / Constant 等）。 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-desc.md b/docs/api/rhi/d3d12/buffer/get-desc.md new file mode 100644 index 00000000..49bfeab1 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/get-desc.md @@ -0,0 +1,19 @@ +# D3D12Buffer::GetDesc + +## 函数签名 + +```cpp +D3D12_RESOURCE_DESC GetDesc() const +``` + +## 中文描述 + +获取 D3D12 资源描述结构。 + +## 返回值 + +`D3D12_RESOURCE_DESC` - 资源描述 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-gpu-address.md b/docs/api/rhi/d3d12/buffer/get-gpu-address.md new file mode 100644 index 00000000..e8c6468b --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/get-gpu-address.md @@ -0,0 +1,19 @@ +# D3D12Buffer::GetGPUAddress + +## 函数签名 + +```cpp +uint64_t GetGPUAddress() const +``` + +## 中文描述 + +获取 GPU 地址（等同于 `GetGPUVirtualAddress`）。 + +## 返回值 + +`uint64_t` - GPU 地址 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-gpu-virtual-address.md b/docs/api/rhi/d3d12/buffer/get-gpu-virtual-address.md new file mode 100644 index 00000000..746d44b7 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/get-gpu-virtual-address.md @@ -0,0 +1,19 @@ +# D3D12Buffer::GetGPUVirtualAddress + +## 函数签名 + +```cpp +D3D12_GPU_VIRTUAL_ADDRESS GetGPUVirtualAddress() const +``` + +## 中文描述 + +获取 GPU 虚拟地址，用于根签名绑定。 + +## 返回值 + +`D3D12_GPU_VIRTUAL_ADDRESS` - GPU 虚拟地址 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-name.md b/docs/api/rhi/d3d12/buffer/get-name.md new file mode 100644 index 00000000..4d3d8739 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/get-name.md @@ -0,0 +1,16 @@ +# D3D12Buffer::GetName / SetName + +## 函数签名 + +```cpp +const std::string& GetName() const override +void SetName(const std::string& name) override +``` + +## 中文描述 + +获取和设置对象名称（用于调试）。 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-native-handle.md b/docs/api/rhi/d3d12/buffer/get-native-handle.md new file mode 100644 index 00000000..bf64fcd2 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/get-native-handle.md @@ -0,0 +1,19 @@ +# D3D12Buffer::GetNativeHandle + +## 函数签名 + +```cpp +void* GetNativeHandle() override +``` + +## 中文描述 + +返回原生句柄，即 `ID3D12Resource*`。 + +## 返回值 + +`void*` - 原生句柄 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-resource.md b/docs/api/rhi/d3d12/buffer/get-resource.md new file mode 100644 index 00000000..b7570306 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/get-resource.md @@ -0,0 +1,19 @@ +# D3D12Buffer::GetResource + +## 函数签名 + +```cpp +ID3D12Resource* GetResource() const +``` + +## 中文描述 + +获取底层 `ID3D12Resource` 指针。 + +## 返回值 + +`ID3D12Resource*` - D3D12 资源指针 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-size.md b/docs/api/rhi/d3d12/buffer/get-size.md new file mode 100644 index 00000000..9a1e8bcb --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/get-size.md @@ -0,0 +1,19 @@ +# D3D12Buffer::GetSize + +## 函数签名 + +```cpp +uint64_t GetSize() const override +``` + +## 中文描述 + +获取缓冲区大小（字节）。 + +## 返回值 + +`uint64_t` - 缓冲区大小 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-state.md b/docs/api/rhi/d3d12/buffer/get-state.md new file mode 100644 index 00000000..f1b2e93e --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/get-state.md @@ -0,0 +1,16 @@ +# D3D12Buffer::GetState / SetState + +## 函数签名 + +```cpp +ResourceStates GetState() const +void SetState(ResourceStates state) +``` + +## 中文描述 + +获取和设置当前资源状态。用于状态跟踪和屏障生成。 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-stride.md b/docs/api/rhi/d3d12/buffer/get-stride.md new file mode 100644 index 00000000..b29afae1 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/get-stride.md @@ -0,0 +1,16 @@ +# D3D12Buffer::GetStride / SetStride + +## 函数签名 + +```cpp +uint32_t GetStride() const override +void SetStride(uint32_t stride) override +``` + +## 中文描述 + +获取和设置顶点缓冲区步长（字节）。 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/initialize-from-existing.md b/docs/api/rhi/d3d12/buffer/initialize-from-existing.md new file mode 100644 index 00000000..d8eb37c0 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/initialize-from-existing.md @@ -0,0 +1,35 @@ +# D3D12Buffer::InitializeFromExisting + +## 函数签名 + +```cpp +bool InitializeFromExisting(ID3D12Resource* resource) +``` + +## 中文描述 + +从已存在的 D3D12 资源对象初始化缓冲区包装类，不分配新资源。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `resource` | `ID3D12Resource*` | 已存在的 D3D12 资源指针 | + +## 返回值 + +`bool` - 初始化是否成功 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +ComPtr existingResource; +device->CreateReservedResource(&desc, state, nullptr, IID_PPV_ARGS(&existingResource)); + +D3D12Buffer buffer; +buffer.InitializeFromExisting(existingResource.Get()); +``` diff --git a/docs/api/rhi/d3d12/buffer/initialize-with-data.md b/docs/api/rhi/d3d12/buffer/initialize-with-data.md new file mode 100644 index 00000000..41047bc6 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/initialize-with-data.md @@ -0,0 +1,42 @@ +# D3D12Buffer::InitializeWithData + +## 函数签名 + +```cpp +bool InitializeWithData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, const void* data, uint64_t size, D3D12_RESOURCE_STATES finalState) +``` + +## 中文描述 + +创建缓冲区并通过命令列表从内存数据初始化内容。内部会自动创建上传堆、复制数据、转换状态。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `commandList` | `ID3D12GraphicsCommandList*` | 命令列表（用于复制操作） | +| `data` | `const void*` | 初始数据指针 | +| `size` | `uint64_t` | 数据大小（字节） | +| `finalState` | `D3D12_RESOURCE_STATES` | 数据复制完成后的目标状态 | + +## 返回值 + +`bool` - 初始化是否成功 + +## 复杂度 + +O(n) - 取决于数据大小，内部创建临时上传堆 + +## 示例 + +```cpp +uint16_t indices[] = { 0, 1, 2, 1, 3, 2 }; +D3D12Buffer indexBuffer; +D3D12Buffer::InitializeWithData( + device->GetDevice(), + cmdList->GetCommandList(), + indices, + sizeof(indices), + D3D12_RESOURCE_STATE_INDEX_BUFFER); +``` diff --git a/docs/api/rhi/d3d12/buffer/initialize.md b/docs/api/rhi/d3d12/buffer/initialize.md new file mode 100644 index 00000000..94ef4131 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/initialize.md @@ -0,0 +1,39 @@ +# D3D12Buffer::Initialize + +## 函数签名 + +```cpp +bool Initialize(ID3D12Device* device, uint64_t size, D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON, D3D12_HEAP_TYPE heapType = D3D12_HEAP_TYPE_DEFAULT) +``` + +## 中文描述 + +创建新缓冲区，分配 D3D12 显存资源。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `size` | `uint64_t` | 缓冲区大小（字节） | +| `initialState` | `D3D12_RESOURCE_STATES` | 初始资源状态（默认 COMMON） | +| `heapType` | `D3D12_HEAP_TYPE` | 堆类型：DEFAULT（默认）、UPLOAD（上传）、READBACK（回读） | + +## 返回值 + +`bool` - 初始化是否成功 + +## 复杂度 + +O(n) - 取决于缓冲区大小 + +## 示例 + +```cpp +D3D12Buffer vertexBuffer; +vertexBuffer.Initialize( + device->GetDevice(), + sizeof(Vertex) * vertexCount, + D3D12_RESOURCE_STATE_VERTEX_AND_CONSTANT_BUFFER, + D3D12_HEAP_TYPE_DEFAULT); +``` diff --git a/docs/api/rhi/d3d12/buffer/map.md b/docs/api/rhi/d3d12/buffer/map.md new file mode 100644 index 00000000..fbe02910 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/map.md @@ -0,0 +1,27 @@ +# D3D12Buffer::Map + +## 函数签名 + +```cpp +void* Map() override +``` + +## 中文描述 + +将缓冲区内存映射到 CPU 可访问地址。仅对 UPLOAD 或 READBACK 堆有效。 + +## 返回值 + +`void*` - 映射的内存指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +void* mapped = uploadBuffer.Map(); +memcpy(mapped, vertexData, sizeof(vertexData)); +buffer.Unmap(); +``` diff --git a/docs/api/rhi/d3d12/buffer/set-data.md b/docs/api/rhi/d3d12/buffer/set-data.md new file mode 100644 index 00000000..e3f6376a --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/set-data.md @@ -0,0 +1,23 @@ +# D3D12Buffer::SetData + +## 函数签名 + +```cpp +void SetData(const void* data, size_t size, size_t offset = 0) override +``` + +## 中文描述 + +设置缓冲区数据。通过 Map/Unmap 实现。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `data` | `const void*` | 数据指针 | +| `size` | `size_t` | 数据大小 | +| `offset` | `size_t` | 缓冲区内的偏移量 | + +## 复杂度 + +O(n) diff --git a/docs/api/rhi/d3d12/buffer/shutdown.md b/docs/api/rhi/d3d12/buffer/shutdown.md new file mode 100644 index 00000000..9c3c4797 --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/shutdown.md @@ -0,0 +1,15 @@ +# D3D12Buffer::Shutdown + +## 函数签名 + +```cpp +void Shutdown() override +``` + +## 中文描述 + +释放 D3D12 缓冲区资源，将成员变量置为空。 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/unmap.md b/docs/api/rhi/d3d12/buffer/unmap.md new file mode 100644 index 00000000..2ee8db6f --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/unmap.md @@ -0,0 +1,15 @@ +# D3D12Buffer::Unmap + +## 函数签名 + +```cpp +void Unmap() override +``` + +## 中文描述 + +解除缓冲区内存映射。 + +## 复杂度 + +O(1) diff --git a/docs/api/rhi/d3d12/buffer/update-data.md b/docs/api/rhi/d3d12/buffer/update-data.md new file mode 100644 index 00000000..ab757c1f --- /dev/null +++ b/docs/api/rhi/d3d12/buffer/update-data.md @@ -0,0 +1,28 @@ +# D3D12Buffer::UpdateData + +## 函数签名 + +```cpp +void UpdateData(const void* data, uint64_t size) +``` + +## 中文描述 + +更新缓冲区数据。要求缓冲区使用 UPLOAD 堆类型，否则行为未定义。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `data` | `const void*` | 新数据指针 | +| `size` | `uint64_t` | 数据大小 | + +## 复杂度 + +O(n) + +## 示例 + +```cpp +uploadBuffer.UpdateData(newData, dataSize); +``` diff --git a/docs/api/rhi/d3d12/command-allocator/command-allocator.md b/docs/api/rhi/d3d12/command-allocator/command-allocator.md new file mode 100644 index 00000000..dd754336 --- /dev/null +++ b/docs/api/rhi/d3d12/command-allocator/command-allocator.md @@ -0,0 +1,19 @@ +# D3D12CommandAllocator + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 命令分配器的 D3D12 实现。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Reset` | [详细文档](../../../resources/resourcehandle/reset.md) | +| `IsReady` | [详细文档](is-ready.md) | +| `GetCommandAllocator` | [详细文档](get-command-allocator.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) diff --git a/docs/api/rhi/d3d12/command-allocator/get-command-allocator.md b/docs/api/rhi/d3d12/command-allocator/get-command-allocator.md new file mode 100644 index 00000000..da32a507 --- /dev/null +++ b/docs/api/rhi/d3d12/command-allocator/get-command-allocator.md @@ -0,0 +1,15 @@ +# D3D12CommandAllocator::GetCommandAllocator + +```cpp +ID3D12CommandAllocator* GetCommandAllocator() const { return m_commandAllocator.Get(); } +``` + +获取底层的 D3D12 命令分配器接口。 + +**返回：** `ID3D12CommandAllocator*` + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-allocator/is-ready.md b/docs/api/rhi/d3d12/command-allocator/is-ready.md new file mode 100644 index 00000000..c70acb1d --- /dev/null +++ b/docs/api/rhi/d3d12/command-allocator/is-ready.md @@ -0,0 +1,15 @@ +# D3D12CommandAllocator::IsReady + +```cpp +bool IsReady() const; +``` + +检查命令分配器是否准备就绪。 + +**返回：** 分配器是否准备就绪 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/alias-barrier.md b/docs/api/rhi/d3d12/command-list/alias-barrier.md new file mode 100644 index 00000000..c336fccb --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/alias-barrier.md @@ -0,0 +1,17 @@ +# D3D12CommandList::AliasBarrier + +```cpp +void AliasBarrier(void* beforeResource = nullptr, void* afterResource = nullptr); +``` + +添加资源别名屏障。 + +**参数：** +- `beforeResource` - 别名切换前的资源 +- `afterResource` - 别名切换后的资源 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/begin-query.md b/docs/api/rhi/d3d12/command-list/begin-query.md new file mode 100644 index 00000000..8fb4f0b6 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/begin-query.md @@ -0,0 +1,18 @@ +# D3D12CommandList::BeginQuery + +```cpp +void BeginQuery(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t index); +``` + +开始查询。 + +**参数：** +- `queryHeap` - 查询堆 +- `type` - 查询类型 +- `index` - 查询索引 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/clear-depth-stencil.md b/docs/api/rhi/d3d12/command-list/clear-depth-stencil.md new file mode 100644 index 00000000..961cca0e --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/clear-depth-stencil.md @@ -0,0 +1,18 @@ +# D3D12CommandList::ClearDepthStencil + +```cpp +void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) override; +``` + +清除深度模板。 + +**参数：** +- `depthStencil` - 深度模板指针 +- `depth` - 深度值 +- `stencil` - 模板值 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/clear-render-target.md b/docs/api/rhi/d3d12/command-list/clear-render-target.md new file mode 100644 index 00000000..e519370b --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/clear-render-target.md @@ -0,0 +1,17 @@ +# D3D12CommandList::ClearRenderTarget + +```cpp +void ClearRenderTarget(void* renderTarget, const float color[4]) override; +``` + +清除渲染目标。 + +**参数：** +- `renderTarget` - 渲染目标指针 +- `color` - 清除颜色 [r, g, b, a] + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/command-list.md b/docs/api/rhi/d3d12/command-list/command-list.md new file mode 100644 index 00000000..8fa04340 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/command-list.md @@ -0,0 +1,143 @@ +# D3D12CommandList + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 命令列表的 D3D12 实现，继承自 `RHICommandList`。 + +## 方法列表 + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Reset` | [详细文档](../../../resources/resourcehandle/reset.md) | +| `Close` | [详细文档](../../../core/filewriter/close.md) | +| `GetCommandList` | [详细文档](get-command-list.md) | + +### 资源屏障 + +| 方法 | 文档 | +|------|------| +| `TransitionBarrier` | [详细文档](transition-barrier.md) | +| `TransitionBarrierInternal` | [详细文档](transition-barrier-internal.md) | +| `UAVBarrier` | [详细文档](uav-barrier.md) | +| `AliasBarrier` | [详细文档](alias-barrier.md) | + +### 管线状态 + +| 方法 | 文档 | +|------|------| +| `SetPipelineState` | [详细文档](set-pipeline-state.md) | +| `SetRootSignature` | [详细文档](set-root-signature.md) | +| `SetPrimitiveTopology` | [详细文档](set-primitive-topology.md) | + +### 视口与裁剪 + +| 方法 | 文档 | +|------|------| +| `SetViewport` | [详细文档](set-viewport.md) | +| `SetViewports` | [详细文档](set-viewports.md) | +| `SetScissorRect` | [详细文档](set-scissor-rect.md) | +| `SetScissorRects` | [详细文档](set-scissor-rects.md) | + +### 渲染目标 + +| 方法 | 文档 | +|------|------| +| `SetRenderTargets` | [详细文档](set-render-targets.md) | +| `SetRenderTargetsInternal` | [详细文档](set-render-targets-internal.md) | +| `SetRenderTargetsHandle` | [详细文档](set-render-targets-handle.md) | + +### 顶点/索引缓冲区 + +| 方法 | 文档 | +|------|------| +| `SetVertexBuffer` | [详细文档](set-vertex-buffer.md) | +| `SetVertexBuffers` | [详细文档](set-vertex-buffers.md) | +| `SetIndexBuffer` | [详细文档](set-index-buffer.md) | + +### 描述符 + +| 方法 | 文档 | +|------|------| +| `SetDescriptorHeap` | [详细文档](set-descriptor-heap.md) | +| `SetDescriptorHeaps` | [详细文档](set-descriptor-heaps.md) | +| `SetGraphicsDescriptorTable` | [详细文档](set-graphics-descriptor-table.md) | +| `SetComputeDescriptorTable` | [详细文档](set-compute-descriptor-table.md) | + +### 根参数绑定 + +| 方法 | 文档 | +|------|------| +| `SetGraphicsRootConstantBufferView` | [详细文档](set-graphics-root-constant-buffer-view.md) | +| `SetGraphicsRoot32BitConstants` | [详细文档](set-graphics-root-32bit-constants.md) | +| `SetGraphicsRootDescriptorTable` | [详细文档](set-graphics-root-descriptor-table.md) | +| `SetGraphicsRootShaderResourceView` | [详细文档](set-graphics-root-shader-resource-view.md) | + +### 渲染状态 + +| 方法 | 文档 | +|------|------| +| `SetStencilRef` | [详细文档](set-stencil-ref.md) | +| `SetBlendFactor` | [详细文档](set-blend-factor.md) | +| `SetDepthBias` | [详细文档](set-depth-bias.md) | + +### 绘制 + +| 方法 | 文档 | +|------|------| +| `Draw` | [详细文档](draw.md) | +| `DrawIndexed` | [详细文档](draw-indexed.md) | +| `DrawInstancedIndirect` | [详细文档](draw-instanced-indirect.md) | +| `DrawIndexedInstancedIndirect` | [详细文档](draw-indexed-instanced-indirect.md) | + +### 清除 + +| 方法 | 文档 | +|------|------| +| `Clear` | [详细文档](../../../memory/linear-allocator/clear.md) | +| `ClearRenderTarget` | [详细文档](clear-render-target.md) | +| `ClearDepthStencil` | [详细文档](clear-depth-stencil.md) | + +### 复制 + +| 方法 | 文档 | +|------|------| +| `CopyResource` | [详细文档](copy-resource.md) | +| `CopyBuffer` | [详细文档](copy-buffer.md) | +| `CopyTexture` | [详细文档](copy-texture.md) | + +### 查询 + +| 方法 | 文档 | +|------|------| +| `BeginQuery` | [详细文档](begin-query.md) | +| `EndQuery` | [详细文档](end-query.md) | +| `ResolveQueryData` | [详细文档](resolve-query-data.md) | + +### 计算 + +| 方法 | 文档 | +|------|------| +| `Dispatch` | [详细文档](dispatch.md) | +| `DispatchIndirect` | [详细文档](dispatch-indirect.md) | + +### Bundle + +| 方法 | 文档 | +|------|------| +| `ExecuteBundle` | [详细文档](execute-bundle.md) | + +### 状态管理 + +| 方法 | 文档 | +|------|------| +| `GetResourceState` | [详细文档](get-resource-state.md) | +| `TrackResource` | [详细文档](track-resource.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHICommandList](../../command-list/command-list.md) - 抽象命令列表接口 diff --git a/docs/api/rhi/d3d12/command-list/copy-buffer.md b/docs/api/rhi/d3d12/command-list/copy-buffer.md new file mode 100644 index 00000000..49fddf4f --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/copy-buffer.md @@ -0,0 +1,20 @@ +# D3D12CommandList::CopyBuffer + +```cpp +void CopyBuffer(ID3D12Resource* dst, uint64_t dstOffset, ID3D12Resource* src, uint64_t srcOffset, uint64_t size); +``` + +复制缓冲区。 + +**参数：** +- `dst` - 目标缓冲区 +- `dstOffset` - 目标偏移 +- `src` - 源缓冲区 +- `srcOffset` - 源偏移 +- `size` - 复制大小 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/copy-resource.md b/docs/api/rhi/d3d12/command-list/copy-resource.md new file mode 100644 index 00000000..1ebadd90 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/copy-resource.md @@ -0,0 +1,17 @@ +# D3D12CommandList::CopyResource + +```cpp +void CopyResource(void* dst, void* src) override; +``` + +复制资源。 + +**参数：** +- `dst` - 目标资源指针 +- `src` - 源资源指针 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/copy-texture.md b/docs/api/rhi/d3d12/command-list/copy-texture.md new file mode 100644 index 00000000..cb7ea684 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/copy-texture.md @@ -0,0 +1,19 @@ +# D3D12CommandList::CopyTexture + +```cpp +void CopyTexture(ID3D12Resource* dst, const D3D12_TEXTURE_COPY_LOCATION& dstLocation, ID3D12Resource* src, const D3D12_TEXTURE_COPY_LOCATION& srcLocation); +``` + +复制纹理。 + +**参数：** +- `dst` - 目标纹理 +- `dstLocation` - 目标位置 +- `src` - 源纹理 +- `srcLocation` - 源位置 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/dispatch-indirect.md b/docs/api/rhi/d3d12/command-list/dispatch-indirect.md new file mode 100644 index 00000000..ab5cf179 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/dispatch-indirect.md @@ -0,0 +1,17 @@ +# D3D12CommandList::DispatchIndirect + +```cpp +void DispatchIndirect(void* argBuffer, uint64_t alignedByteOffset); +``` + +间接分发计算命令。 + +**参数：** +- `argBuffer` - 参数缓冲区 +- `alignedByteOffset` - 字节偏移 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/dispatch.md b/docs/api/rhi/d3d12/command-list/dispatch.md new file mode 100644 index 00000000..bada4012 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/dispatch.md @@ -0,0 +1,18 @@ +# D3D12CommandList::Dispatch + +```cpp +void Dispatch(uint32_t x, uint32_t y, uint32_t z) override; +``` + +分发计算命令。 + +**参数：** +- `x` - X 维度线程组数量 +- `y` - Y 维度线程组数量 +- `z` - Z 维度线程组数量 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/draw-indexed-instanced-indirect.md b/docs/api/rhi/d3d12/command-list/draw-indexed-instanced-indirect.md new file mode 100644 index 00000000..1f0e2231 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/draw-indexed-instanced-indirect.md @@ -0,0 +1,17 @@ +# D3D12CommandList::DrawIndexedInstancedIndirect + +```cpp +void DrawIndexedInstancedIndirect(void* argBuffer, uint64_t alignedByteOffset); +``` + +间接绘制索引实例。 + +**参数：** +- `argBuffer` - 参数缓冲区 +- `alignedByteOffset` - 字节偏移 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/draw-indexed.md b/docs/api/rhi/d3d12/command-list/draw-indexed.md new file mode 100644 index 00000000..24b54e07 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/draw-indexed.md @@ -0,0 +1,20 @@ +# D3D12CommandList::DrawIndexed + +```cpp +void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) override; +``` + +绘制索引调用。 + +**参数：** +- `indexCount` - 索引数量 +- `instanceCount` - 实例数量 +- `startIndex` - 起始索引 +- `baseVertex` - 基础顶点偏移 +- `startInstance` - 起始实例索引 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/draw-instanced-indirect.md b/docs/api/rhi/d3d12/command-list/draw-instanced-indirect.md new file mode 100644 index 00000000..9e44856d --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/draw-instanced-indirect.md @@ -0,0 +1,17 @@ +# D3D12CommandList::DrawInstancedIndirect + +```cpp +void DrawInstancedIndirect(void* argBuffer, uint64_t alignedByteOffset); +``` + +间接绘制实例。 + +**参数：** +- `argBuffer` - 参数缓冲区 +- `alignedByteOffset` - 字节偏移 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/draw.md b/docs/api/rhi/d3d12/command-list/draw.md new file mode 100644 index 00000000..acfc11c3 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/draw.md @@ -0,0 +1,19 @@ +# D3D12CommandList::Draw + +```cpp +void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) override; +``` + +绘制调用。 + +**参数：** +- `vertexCount` - 顶点数量 +- `instanceCount` - 实例数量 +- `startVertex` - 起始顶点索引 +- `startInstance` - 起始实例索引 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/end-query.md b/docs/api/rhi/d3d12/command-list/end-query.md new file mode 100644 index 00000000..f8bde2a2 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/end-query.md @@ -0,0 +1,18 @@ +# D3D12CommandList::EndQuery + +```cpp +void EndQuery(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t index); +``` + +结束查询。 + +**参数：** +- `queryHeap` - 查询堆 +- `type` - 查询类型 +- `index` - 查询索引 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/execute-bundle.md b/docs/api/rhi/d3d12/command-list/execute-bundle.md new file mode 100644 index 00000000..0ddd68fa --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/execute-bundle.md @@ -0,0 +1,16 @@ +# D3D12CommandList::ExecuteBundle + +```cpp +void ExecuteBundle(ID3D12GraphicsCommandList* bundle); +``` + +执行 Bundle。 + +**参数：** +- `bundle` - Bundle 命令列表 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/get-command-list.md b/docs/api/rhi/d3d12/command-list/get-command-list.md new file mode 100644 index 00000000..0743814b --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/get-command-list.md @@ -0,0 +1,15 @@ +# D3D12CommandList::GetCommandList + +```cpp +ID3D12GraphicsCommandList* GetCommandList() const { return m_commandList.Get(); } +``` + +获取底层的 D3D12 图形命令列表接口。 + +**返回：** `ID3D12GraphicsCommandList*` + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/get-resource-state.md b/docs/api/rhi/d3d12/command-list/get-resource-state.md new file mode 100644 index 00000000..81f3d2a6 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/get-resource-state.md @@ -0,0 +1,18 @@ +# D3D12CommandList::GetResourceState + +```cpp +ResourceStates GetResourceState(ID3D12Resource* resource) const; +``` + +获取资源状态。 + +**参数：** +- `resource` - D3D12 资源指针 + +**返回：** 资源当前状态 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/resolve-query-data.md b/docs/api/rhi/d3d12/command-list/resolve-query-data.md new file mode 100644 index 00000000..df1e241d --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/resolve-query-data.md @@ -0,0 +1,21 @@ +# D3D12CommandList::ResolveQueryData + +```cpp +void ResolveQueryData(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t startIndex, uint32_t count, ID3D12Resource* resultBuffer, uint64_t resultOffset); +``` + +解析查询数据。 + +**参数：** +- `queryHeap` - 查询堆 +- `type` - 查询类型 +- `startIndex` - 起始索引 +- `count` - 查询数量 +- `resultBuffer` - 结果缓冲区 +- `resultOffset` - 结果偏移 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-blend-factor.md b/docs/api/rhi/d3d12/command-list/set-blend-factor.md new file mode 100644 index 00000000..5553f755 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-blend-factor.md @@ -0,0 +1,16 @@ +# D3D12CommandList::SetBlendFactor + +```cpp +void SetBlendFactor(const float blendFactor[4]); +``` + +设置混合因子。 + +**参数：** +- `blendFactor` - 混合因子数组 [r, g, b, a] + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-compute-descriptor-table.md b/docs/api/rhi/d3d12/command-list/set-compute-descriptor-table.md new file mode 100644 index 00000000..b2ffe152 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-compute-descriptor-table.md @@ -0,0 +1,17 @@ +# D3D12CommandList::SetComputeDescriptorTable + +```cpp +void SetComputeDescriptorTable(uint32_t rootParameterIndex, D3D12_GPU_DESCRIPTOR_HANDLE baseHandle); +``` + +设置计算描述符表。 + +**参数：** +- `rootParameterIndex` - 根参数索引 +- `baseHandle` - GPU 描述符句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-depth-bias.md b/docs/api/rhi/d3d12/command-list/set-depth-bias.md new file mode 100644 index 00000000..55dd006c --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-depth-bias.md @@ -0,0 +1,18 @@ +# D3D12CommandList::SetDepthBias + +```cpp +void SetDepthBias(float depthBias, float slopeScaledDepthBias, float depthBiasClamp); +``` + +设置深度偏移。 + +**参数：** +- `depthBias` - 基础深度偏移 +- `slopeScaledDepthBias` - 斜率缩放深度偏移 +- `depthBiasClamp` - 深度偏移上限 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-descriptor-heap.md b/docs/api/rhi/d3d12/command-list/set-descriptor-heap.md new file mode 100644 index 00000000..d4a4b485 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-descriptor-heap.md @@ -0,0 +1,16 @@ +# D3D12CommandList::SetDescriptorHeap + +```cpp +void SetDescriptorHeap(ID3D12DescriptorHeap* heap); +``` + +设置描述符堆。 + +**参数：** +- `heap` - D3D12 描述符堆指针 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-descriptor-heaps.md b/docs/api/rhi/d3d12/command-list/set-descriptor-heaps.md new file mode 100644 index 00000000..a3d1eac1 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-descriptor-heaps.md @@ -0,0 +1,17 @@ +# D3D12CommandList::SetDescriptorHeaps + +```cpp +void SetDescriptorHeaps(uint32_t count, ID3D12DescriptorHeap** heaps); +``` + +设置多个描述符堆。 + +**参数：** +- `count` - 描述符堆数量 +- `heaps` - 描述符堆指针数组 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-graphics-descriptor-table.md b/docs/api/rhi/d3d12/command-list/set-graphics-descriptor-table.md new file mode 100644 index 00000000..51c21b88 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-graphics-descriptor-table.md @@ -0,0 +1,17 @@ +# D3D12CommandList::SetGraphicsDescriptorTable + +```cpp +void SetGraphicsDescriptorTable(uint32_t rootParameterIndex, D3D12_GPU_DESCRIPTOR_HANDLE baseHandle); +``` + +设置图形描述符表。 + +**参数：** +- `rootParameterIndex` - 根参数索引 +- `baseHandle` - GPU 描述符句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-graphics-root-32bit-constants.md b/docs/api/rhi/d3d12/command-list/set-graphics-root-32bit-constants.md new file mode 100644 index 00000000..ba7b6763 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-graphics-root-32bit-constants.md @@ -0,0 +1,19 @@ +# D3D12CommandList::SetGraphicsRoot32BitConstants + +```cpp +void SetGraphicsRoot32BitConstants(uint32_t rootParameterIndex, uint32_t num32BitValuesToSet, const void* pSrcData, uint32_t destOffsetIn32BitValues); +``` + +设置图形根 32 位常量。 + +**参数：** +- `rootParameterIndex` - 根参数索引 +- `num32BitValuesToSet` - 要设置的 32 位值数量 +- `pSrcData` - 源数据指针 +- `destOffsetIn32BitValues` - 目标偏移量 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-graphics-root-constant-buffer-view.md b/docs/api/rhi/d3d12/command-list/set-graphics-root-constant-buffer-view.md new file mode 100644 index 00000000..82b4aab9 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-graphics-root-constant-buffer-view.md @@ -0,0 +1,17 @@ +# D3D12CommandList::SetGraphicsRootConstantBufferView + +```cpp +void SetGraphicsRootConstantBufferView(uint32_t rootParameterIndex, D3D12_GPU_VIRTUAL_ADDRESS bufferLocation); +``` + +设置图形根常量缓冲区视图。 + +**参数：** +- `rootParameterIndex` - 根参数索引 +- `bufferLocation` - GPU 虚拟地址 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-graphics-root-descriptor-table.md b/docs/api/rhi/d3d12/command-list/set-graphics-root-descriptor-table.md new file mode 100644 index 00000000..5d17a3fc --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-graphics-root-descriptor-table.md @@ -0,0 +1,17 @@ +# D3D12CommandList::SetGraphicsRootDescriptorTable + +```cpp +void SetGraphicsRootDescriptorTable(uint32_t rootParameterIndex, D3D12_GPU_DESCRIPTOR_HANDLE baseDescriptor); +``` + +设置图形根描述符表。 + +**参数：** +- `rootParameterIndex` - 根参数索引 +- `baseDescriptor` - GPU 描述符句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-graphics-root-shader-resource-view.md b/docs/api/rhi/d3d12/command-list/set-graphics-root-shader-resource-view.md new file mode 100644 index 00000000..4dd985de --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-graphics-root-shader-resource-view.md @@ -0,0 +1,17 @@ +# D3D12CommandList::SetGraphicsRootShaderResourceView + +```cpp +void SetGraphicsRootShaderResourceView(uint32_t rootParameterIndex, D3D12_GPU_VIRTUAL_ADDRESS shaderResource); +``` + +设置图形根着色器资源视图。 + +**参数：** +- `rootParameterIndex` - 根参数索引 +- `shaderResource` - GPU 虚拟地址 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-index-buffer.md b/docs/api/rhi/d3d12/command-list/set-index-buffer.md new file mode 100644 index 00000000..45a26021 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-index-buffer.md @@ -0,0 +1,18 @@ +# D3D12CommandList::SetIndexBuffer + +```cpp +void SetIndexBuffer(void* buffer, uint64_t offset, Format format) override; +``` + +设置索引缓冲区。 + +**参数：** +- `buffer` - 缓冲区指针 +- `offset` - 缓冲区偏移 +- `format` - 索引格式 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-pipeline-state.md b/docs/api/rhi/d3d12/command-list/set-pipeline-state.md new file mode 100644 index 00000000..d05ac7c6 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-pipeline-state.md @@ -0,0 +1,16 @@ +# D3D12CommandList::SetPipelineState + +```cpp +void SetPipelineState(void* pso) override; +``` + +设置图形管线状态对象。 + +**参数：** +- `pso` - 管线状态对象指针 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-primitive-topology.md b/docs/api/rhi/d3d12/command-list/set-primitive-topology.md new file mode 100644 index 00000000..a8e13acf --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-primitive-topology.md @@ -0,0 +1,16 @@ +# D3D12CommandList::SetPrimitiveTopology + +```cpp +void SetPrimitiveTopology(PrimitiveTopology topology); +``` + +设置图元拓扑类型。 + +**参数：** +- `topology` - 图元拓扑类型 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-render-targets-handle.md b/docs/api/rhi/d3d12/command-list/set-render-targets-handle.md new file mode 100644 index 00000000..45081f7a --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-render-targets-handle.md @@ -0,0 +1,18 @@ +# D3D12CommandList::SetRenderTargetsHandle + +```cpp +void SetRenderTargetsHandle(uint32_t count, const D3D12_CPU_DESCRIPTOR_HANDLE* renderTargetHandles, const D3D12_CPU_DESCRIPTOR_HANDLE* depthStencilHandle = nullptr); +``` + +使用描述符句柄设置渲染目标。 + +**参数：** +- `count` - 渲染目标数量 +- `renderTargetHandles` - 渲染目标描述符句柄数组 +- `depthStencilHandle` - 深度模板描述符句柄 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-render-targets-internal.md b/docs/api/rhi/d3d12/command-list/set-render-targets-internal.md new file mode 100644 index 00000000..6ea787db --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-render-targets-internal.md @@ -0,0 +1,18 @@ +# D3D12CommandList::SetRenderTargetsInternal + +```cpp +void SetRenderTargetsInternal(uint32_t count, ID3D12Resource** renderTargets, ID3D12Resource* depthStencil = nullptr); +``` + +设置渲染目标（内部接口）。 + +**参数：** +- `count` - 渲染目标数量 +- `renderTargets` - D3D12 资源指针数组 +- `depthStencil` - 深度模板资源指针 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-render-targets.md b/docs/api/rhi/d3d12/command-list/set-render-targets.md new file mode 100644 index 00000000..d64ea5a7 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-render-targets.md @@ -0,0 +1,18 @@ +# D3D12CommandList::SetRenderTargets + +```cpp +void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr) override; +``` + +设置渲染目标。 + +**参数：** +- `count` - 渲染目标数量 +- `renderTargets` - 渲染目标指针数组 +- `depthStencil` - 深度模板目标指针 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-root-signature.md b/docs/api/rhi/d3d12/command-list/set-root-signature.md new file mode 100644 index 00000000..0593c1eb --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-root-signature.md @@ -0,0 +1,16 @@ +# D3D12CommandList::SetRootSignature + +```cpp +void SetRootSignature(ID3D12RootSignature* signature); +``` + +设置根签名。 + +**参数：** +- `signature` - D3D12 根签名指针 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-scissor-rect.md b/docs/api/rhi/d3d12/command-list/set-scissor-rect.md new file mode 100644 index 00000000..c01ba976 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-scissor-rect.md @@ -0,0 +1,16 @@ +# D3D12CommandList::SetScissorRect + +```cpp +void SetScissorRect(const Rect& rect) override; +``` + +设置裁剪矩形。 + +**参数：** +- `rect` - 裁剪矩形结构 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-scissor-rects.md b/docs/api/rhi/d3d12/command-list/set-scissor-rects.md new file mode 100644 index 00000000..4745112f --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-scissor-rects.md @@ -0,0 +1,17 @@ +# D3D12CommandList::SetScissorRects + +```cpp +void SetScissorRects(uint32_t count, const Rect* rects) override; +``` + +设置多个裁剪矩形。 + +**参数：** +- `count` - 裁剪矩形数量 +- `rects` - 裁剪矩形数组 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-stencil-ref.md b/docs/api/rhi/d3d12/command-list/set-stencil-ref.md new file mode 100644 index 00000000..88bbf001 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-stencil-ref.md @@ -0,0 +1,16 @@ +# D3D12CommandList::SetStencilRef + +```cpp +void SetStencilRef(uint32_t stencilRef); +``` + +设置模板参考值。 + +**参数：** +- `stencilRef` - 模板参考值 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-vertex-buffer.md b/docs/api/rhi/d3d12/command-list/set-vertex-buffer.md new file mode 100644 index 00000000..8811d8cf --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-vertex-buffer.md @@ -0,0 +1,19 @@ +# D3D12CommandList::SetVertexBuffer + +```cpp +void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride) override; +``` + +设置单个顶点缓冲区。 + +**参数：** +- `slot` - 顶点缓冲区槽位 +- `buffer` - 缓冲区指针 +- `offset` - 缓冲区偏移 +- `stride` - 顶点 stride + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-vertex-buffers.md b/docs/api/rhi/d3d12/command-list/set-vertex-buffers.md new file mode 100644 index 00000000..faedf0c9 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-vertex-buffers.md @@ -0,0 +1,20 @@ +# D3D12CommandList::SetVertexBuffers + +```cpp +void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides) override; +``` + +设置多个顶点缓冲区。 + +**参数：** +- `startSlot` - 起始槽位 +- `count` - 缓冲区数量 +- `buffers` - 缓冲区指针数组 +- `offsets` - 偏移数组 +- `strides` - stride 数组 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-viewport.md b/docs/api/rhi/d3d12/command-list/set-viewport.md new file mode 100644 index 00000000..7331fa70 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-viewport.md @@ -0,0 +1,16 @@ +# D3D12CommandList::SetViewport + +```cpp +void SetViewport(const Viewport& viewport) override; +``` + +设置视口。 + +**参数：** +- `viewport` - 视口结构 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/set-viewports.md b/docs/api/rhi/d3d12/command-list/set-viewports.md new file mode 100644 index 00000000..a84791e9 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/set-viewports.md @@ -0,0 +1,17 @@ +# D3D12CommandList::SetViewports + +```cpp +void SetViewports(uint32_t count, const Viewport* viewports) override; +``` + +设置多个视口。 + +**参数：** +- `count` - 视口数量 +- `viewports` - 视口数组 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/track-resource.md b/docs/api/rhi/d3d12/command-list/track-resource.md new file mode 100644 index 00000000..b9502045 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/track-resource.md @@ -0,0 +1,16 @@ +# D3D12CommandList::TrackResource + +```cpp +void TrackResource(ID3D12Resource* resource); +``` + +跟踪资源状态。 + +**参数：** +- `resource` - D3D12 资源指针 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/transition-barrier-internal.md b/docs/api/rhi/d3d12/command-list/transition-barrier-internal.md new file mode 100644 index 00000000..ef03d8f1 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/transition-barrier-internal.md @@ -0,0 +1,19 @@ +# D3D12CommandList::TransitionBarrierInternal + +```cpp +void TransitionBarrierInternal(ID3D12Resource* resource, ResourceStates stateBefore, ResourceStates stateAfter, uint32_t subresource = D3D12_RESOURCE_BARRIER_ALL_SUBRESOURCES); +``` + +为资源添加转换屏障（内部接口）。 + +**参数：** +- `resource` - D3D12 资源指针 +- `stateBefore` - 转换前的资源状态 +- `stateAfter` - 转换后的资源状态 +- `subresource` - 子资源索引，默认为所有子资源 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/transition-barrier.md b/docs/api/rhi/d3d12/command-list/transition-barrier.md new file mode 100644 index 00000000..49166c39 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/transition-barrier.md @@ -0,0 +1,18 @@ +# D3D12CommandList::TransitionBarrier + +```cpp +void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter) override; +``` + +为资源添加转换屏障。 + +**参数：** +- `resource` - 目标资源指针 +- `stateBefore` - 转换前的资源状态 +- `stateAfter` - 转换后的资源状态 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/uav-barrier.md b/docs/api/rhi/d3d12/command-list/uav-barrier.md new file mode 100644 index 00000000..c2536e90 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/uav-barrier.md @@ -0,0 +1,16 @@ +# D3D12CommandList::UAVBarrier + +```cpp +void UAVBarrier(void* resource = nullptr); +``` + +添加无序访问视图屏障。 + +**参数：** +- `resource` - 目标资源指针，nullptr 表示所有 UAV + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-queue/command-queue.md b/docs/api/rhi/d3d12/command-queue/command-queue.md new file mode 100644 index 00000000..9c8e0111 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/command-queue.md @@ -0,0 +1,26 @@ +# D3D12CommandQueue + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 命令队列的 D3D12 实现，继承自 `RHICommandQueue`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `ExecuteCommandLists` | [详细文档](execute-command-lists.md) | +| `Signal` | [详细文档](signal.md) | +| `Wait` | [详细文档](../../../threading/task-group/wait.md) | +| `GetCompletedValue` | [详细文档](get-completed-value.md) | +| `WaitForIdle` | [详细文档](wait-for-idle.md) | +| `GetType` | [详细文档](../../shader/get-type.md) | +| `GetTimestampFrequency` | [详细文档](get-timestamp-frequency.md) | +| `GetCommandQueue` | [详细文档](get-command-queue.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHICommandQueue](../../command-queue/command-queue.md) - 抽象命令队列接口 diff --git a/docs/api/rhi/d3d12/command-queue/execute-command-lists.md b/docs/api/rhi/d3d12/command-queue/execute-command-lists.md new file mode 100644 index 00000000..ca08fc31 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/execute-command-lists.md @@ -0,0 +1,17 @@ +# D3D12CommandQueue::ExecuteCommandLists + +```cpp +void ExecuteCommandLists(uint32_t count, void** lists) override; +``` + +执行命令列表。 + +**参数：** +- `count` - 命令列表数量 +- `lists` - 命令列表指针数组 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-queue/get-command-queue.md b/docs/api/rhi/d3d12/command-queue/get-command-queue.md new file mode 100644 index 00000000..90176f02 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/get-command-queue.md @@ -0,0 +1,15 @@ +# D3D12CommandQueue::GetCommandQueue + +```cpp +ID3D12CommandQueue* GetCommandQueue() const { return m_commandQueue.Get(); } +``` + +获取底层 D3D12 命令队列接口。 + +**返回：** `ID3D12CommandQueue*` + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-queue/get-completed-value.md b/docs/api/rhi/d3d12/command-queue/get-completed-value.md new file mode 100644 index 00000000..f649b7da --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/get-completed-value.md @@ -0,0 +1,15 @@ +# D3D12CommandQueue::GetCompletedValue + +```cpp +uint64_t GetCompletedValue() override; +``` + +获取已完成值。 + +**返回：** 栅栏已完成的值 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-queue/get-timestamp-frequency.md b/docs/api/rhi/d3d12/command-queue/get-timestamp-frequency.md new file mode 100644 index 00000000..187a99b5 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/get-timestamp-frequency.md @@ -0,0 +1,15 @@ +# D3D12CommandQueue::GetTimestampFrequency + +```cpp +uint64_t GetTimestampFrequency() const override { return m_timestampFrequency; } +``` + +获取时间戳频率。 + +**返回：** 时间戳频率 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-queue/signal.md b/docs/api/rhi/d3d12/command-queue/signal.md new file mode 100644 index 00000000..b1ec2650 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/signal.md @@ -0,0 +1,17 @@ +# D3D12CommandQueue::Signal + +```cpp +void Signal(RHIFence* fence, uint64_t value) override; +``` + +发送信号。 + +**参数：** +- `fence` - 栅栏指针 +- `value` - 信号值 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-queue/wait-for-idle.md b/docs/api/rhi/d3d12/command-queue/wait-for-idle.md new file mode 100644 index 00000000..71c0f4ba --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/wait-for-idle.md @@ -0,0 +1,13 @@ +# D3D12CommandQueue::WaitForIdle + +```cpp +void WaitForIdle() override; +``` + +等待空闲。 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/common/common.md b/docs/api/rhi/d3d12/common/common.md new file mode 100644 index 00000000..a48c8b03 --- /dev/null +++ b/docs/api/rhi/d3d12/common/common.md @@ -0,0 +1,67 @@ +# D3D12Common + +**命名空间**: `XCEngine::RHI` + +**描述**: D3D12 通用辅助函数集合，提供描述符大小、屏障创建、格式支持检查等功能。**所有函数均为 inline 函数**。 + +## 函数列表 + +### 描述符大小 + +| 函数 | 描述 | +|------|------| +| `GetDescriptorHandleIncrementSize` | 获取描述符增量大小 | +| `GetRTVDescriptorSize` | 获取 RTV 描述符大小 | +| `GetDSVDescriptorSize` | 获取 DSV 描述符大小 | +| `GetCBV_SRV_UAVDescriptorSize` | 获取 CBV/SRV/UAV 描述符大小 | +| `GetSamplerDescriptorSize` | 获取 Sampler 描述符大小 | + +### 屏障创建 + +| 函数 | 描述 | +|------|------| +| `CreateTransitionBarrier` | 创建资源状态转换屏障 | +| `CreateUAVBarrier` | 创建 UAV 屏障 | +| `CreateAliasingBarrier` | 创建别名化屏障 | + +### 格式支持 + +| 函数 | 描述 | +|------|------| +| `CheckFormatSupport` | 检查格式支持 | +| `IsRenderTargetFormatSupported` | 检查是否支持作为渲染目标 | +| `IsDepthStencilFormatSupported` | 检查是否支持作为深度模板 | +| `IsShaderResourceFormatSupported` | 检查 shader 是否可读取 | +| `IsTextureFormatSupported` | 检查是否支持作为纹理 | + +### 清除值创建 + +| 函数 | 描述 | +|------|------| +| `CreateRenderTargetClearValue` | 创建渲染目标清除值 | +| `CreateDepthStencilClearValue` | 创建深度模板清除值 | + +### 视口和裁剪矩形 + +| 函数 | 描述 | +|------|------| +| `CreateViewport` | 创建视口 | +| `CreateScissorRect` | 创建裁剪矩形 | + +### 缓冲区视图 + +| 函数 | 描述 | +|------|------| +| `CreateVertexBufferView` | 创建顶点缓冲区视图 | +| `CreateIndexBufferView` | 创建索引缓冲区视图 | + +### 描述符句柄运算 + +| 函数 | 描述 | +|------|------| +| `GetCPUDescriptorHandle` | 计算偏移后的 CPU 描述符句柄 | +| `GetGPUDescriptorHandle` | 计算偏移后的 GPU 描述符句柄 | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) diff --git a/docs/api/rhi/d3d12/constant-buffer-view/constant-buffer-view.md b/docs/api/rhi/d3d12/constant-buffer-view/constant-buffer-view.md new file mode 100644 index 00000000..02b7a125 --- /dev/null +++ b/docs/api/rhi/d3d12/constant-buffer-view/constant-buffer-view.md @@ -0,0 +1,17 @@ +# D3D12ConstantBufferView + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 常量缓冲区视图的 D3D12 实现。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetCPUDescriptorHandle` | [详细文档](get-cpu-descriptor-handle.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) diff --git a/docs/api/rhi/d3d12/constant-buffer-view/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/constant-buffer-view/get-cpu-descriptor-handle.md new file mode 100644 index 00000000..c4202e6e --- /dev/null +++ b/docs/api/rhi/d3d12/constant-buffer-view/get-cpu-descriptor-handle.md @@ -0,0 +1,15 @@ +# D3D12ConstantBufferView::GetCPUDescriptorHandle + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const { return m_handle; } +``` + +获取 CPU 描述符句柄。 + +**返回：** CPU 描述符句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12ConstantBufferView 总览](constant-buffer-view.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/d3d12-buffer.md b/docs/api/rhi/d3d12/d3d12-buffer.md deleted file mode 100644 index f0990259..00000000 --- a/docs/api/rhi/d3d12/d3d12-buffer.md +++ /dev/null @@ -1,178 +0,0 @@ -# D3D12Buffer - -DirectX 12 缓冲区的 D3D12 实现，封装了 `ID3D12Resource` (buffer 类型)。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHIBuffer (interface) -└── D3D12Buffer (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12Buffer()` -默认构造函数。 - -#### `~D3D12Buffer() override` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `bool Initialize(ID3D12Device* device, uint64_t size, D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON, D3D12_HEAP_TYPE heapType = D3D12_HEAP_TYPE_DEFAULT)` -创建新缓冲区。 -- `device`: D3D12 设备 -- `size`: 缓冲区大小（字节） -- `initialState`: 初始资源状态 -- `heapType`: 堆类型 (DEFAULT, UPLOAD, READBACK) -- 返回: 初始化是否成功 - -#### `bool InitializeFromExisting(ID3D12Resource* resource)` -从现有 D3D12 资源初始化。 -- `resource`: 已存在的 `ID3D12Resource` 指针 - -#### `bool InitializeWithData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, const void* data, uint64_t size, D3D12_RESOURCE_STATES finalState)` -创建缓冲区并从内存数据初始化内容。 -- `device`: D3D12 设备 -- `commandList`: 命令列表（用于复制数据） -- `data`: 初始数据指针 -- `size`: 数据大小 -- `finalState`: 数据复制完成后的目标状态 - -#### `void Shutdown() override` -释放缓冲区资源。 - -### 数据操作 - -#### `void UpdateData(const void* data, uint64_t size)` -更新缓冲区数据（需要 UPLOAD 堆类型）。 - -#### `void SetData(const void* data, size_t size, size_t offset = 0) override` -设置缓冲区数据。 - -#### `void* Map() override` -映射缓冲区内存到 CPU 可访问。 - -#### `void Unmap() override` -解除缓冲区内存映射。 - -### 资源信息 - -#### `ID3D12Resource* GetResource() const` -获取底层 `ID3D12Resource` 指针。 - -#### `D3D12_RESOURCE_DESC GetDesc() const` -获取资源描述。 - -#### `D3D12_GPU_VIRTUAL_ADDRESS GetGPUVirtualAddress() const` -获取 GPU 虚拟地址。 - -#### `uint64_t GetGPUAddress() const` -获取 GPU 地址（等同于 `GetGPUVirtualAddress`）。 - -#### `uint64_t GetSize() const override` -获取缓冲区大小。 - -#### `ResourceStates GetState() const` -获取当前资源状态。 - -#### `void SetState(ResourceStates state)` -设置资源状态。 - -### 接口实现 - -#### `void* GetNativeHandle() override { return m_resource.Get(); }` -返回原生句柄。 - -#### `const std::string& GetName() const override` -获取对象名称。 - -#### `void SetName(const std::string& name) override` -设置对象名称。 - -#### `uint32_t GetStride() const override` -获取顶点步长。 - -#### `BufferType GetBufferType() const override` -获取缓冲区类型。 - -#### `void SetStride(uint32_t stride) override` -设置顶点步长。 - -#### `void SetBufferType(BufferType type) override` -设置缓冲区类型。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_resource` | `ComPtr` | D3D12 资源对象 | -| `m_state` | `ResourceStates` | 当前资源状态 | -| `m_name` | `std::string` | 对象名称 | -| `m_stride` | `uint32_t` | 顶点步长 | -| `m_bufferType` | `BufferType` | 缓冲区类型 | - -## 使用示例 - -### 创建顶点缓冲区 - -```cpp -D3D12Buffer vertexBuffer; -struct Vertex { float pos[3]; float uv[2]; }; - -if (vertexBuffer.Initialize( - device->GetDevice(), - sizeof(Vertex) * vertexCount, - D3D12_RESOURCE_STATE_VERTEX_AND_CONSTANT_BUFFER, - D3D12_HEAP_TYPE_DEFAULT)) -{ - vertexBuffer.SetName(L"VertexBuffer"); - vertexBuffer.SetStride(sizeof(Vertex)); - vertexBuffer.SetBufferType(BufferType::Vertex); -} -``` - -### 创建并初始化索引缓冲区 - -```cpp -D3D12Buffer indexBuffer; -uint16_t indices[] = { 0, 1, 2, ... }; - -D3D12CommandList cmdList; -cmdList.Initialize(device->GetDevice()); - -indexBuffer.InitializeWithData( - device->GetDevice(), - cmdList.GetCommandList(), - indices, - sizeof(indices), - D3D12_RESOURCE_STATE_INDEX_BUFFER); - -cmdList.Close(); -``` - -### 更新 UPLOAD 缓冲区 - -```cpp -D3D12Buffer uploadBuffer; -uploadBuffer.Initialize(device, bufferSize, D3D12_RESOURCE_STATE_GENERIC_READ, D3D12_HEAP_TYPE_UPLOAD); - -void* mapped = uploadBuffer.Map(); -memcpy(mapped, data, dataSize); -uploadBuffer.Unmap(); -``` - -## 备注 - -- `D3D12_HEAP_TYPE_DEFAULT`: GPU 专用显存，适合渲染使用 -- `D3D12_HEAP_TYPE_UPLOAD`: CPU 可写 GPU 可读的堆，用于上传数据 -- `D3D12_HEAP_TYPE_READBACK`: CPU 可读 GPU 回读数据的堆 -- 创建后立即使用需注意资源状态转换 diff --git a/docs/api/rhi/d3d12/d3d12-command-allocator.md b/docs/api/rhi/d3d12/d3d12-command-allocator.md deleted file mode 100644 index 52bed1a8..00000000 --- a/docs/api/rhi/d3d12/d3d12-command-allocator.md +++ /dev/null @@ -1,80 +0,0 @@ -# D3D12CommandAllocator - -DirectX 12 命令分配器的 D3D12 实现，封装了 `ID3D12CommandAllocator`。 - -## 头文件 - -```cpp -#include -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12CommandAllocator()` -默认构造函数。 - -#### `~D3D12CommandAllocator()` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct)` -初始化命令分配器。 -- `device`: D3D12 设备 -- `type`: 命令类型，必须与命令列表类型匹配 -- 返回: 初始化是否成功 - -#### `void Shutdown()` -释放命令分配器。 - -### 操作 - -#### `void Reset()` -重置命令分配器，丢弃所有已记录的指令。 - -#### `bool IsReady() const` -检查分配器是否准备就绪（GPU 不再使用）。 - -### 属性 - -#### `ID3D12CommandAllocator* GetCommandAllocator() const` -获取底层 `ID3D12CommandAllocator` 指针。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_commandAllocator` | `ComPtr` | D3D12 命令分配器 | -| `m_type` | `CommandQueueType` | 命令类型 | - -## 使用示例 - -```cpp -// Create allocator -D3D12CommandAllocator allocator; -allocator.Initialize(device->GetDevice(), CommandQueueType::Direct); - -// Create command list with allocator -D3D12CommandList cmdList; -cmdList.Initialize(device->GetDevice(), CommandQueueType::Direct, - allocator.GetCommandAllocator()); - -// Use command list... -cmdList->Close(); -cmdQueue->ExecuteCommandListsInternal(1, &cmdList); - -// Wait for GPU to finish -cmdQueue->WaitForIdle(); - -// Reset allocator for next frame -allocator.Reset(); -cmdList->Reset(allocator.GetCommandAllocator(), nullptr); -``` - -## 备注 - -- 命令分配器必须在 GPU 完成所有关联命令后才能重置 -- 每个帧通常有独立的命令分配器以支持帧间并行 -- 命令分配器创建开销小，可以频繁创建销毁 diff --git a/docs/api/rhi/d3d12/d3d12-command-list.md b/docs/api/rhi/d3d12/d3d12-command-list.md deleted file mode 100644 index 82e8774d..00000000 --- a/docs/api/rhi/d3d12/d3d12-command-list.md +++ /dev/null @@ -1,269 +0,0 @@ -# D3D12CommandList - -DirectX 12 图形命令列表的 D3D12 实现，封装了 `ID3D12GraphicsCommandList`。 - -## 头文件 - -```cpp -#include -``` - -## 类概览 - -`D3D12CommandList` 继承自 `RHICommandList`，是 D3D12 渲染命令的录制和执行载体。它封装了 `ID3D12GraphicsCommandList`，并提供状态跟踪和资源管理功能。 - -## 公共成员函数 - -### 初始化与销毁 - -#### `bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct, ID3D12CommandAllocator* allocator = nullptr)` -初始化命令列表。 -- `device`: D3D12 设备指针 -- `type`: 命令队列类型 (Direct, Compute, Copy) -- `allocator`: 可选命令分配器 -- 返回: 初始化是否成功 - -#### `void Shutdown()` -关闭并释放命令列表。 - -### 命令录制控制 - -#### `void Reset()` -重置命令列表，重新开始录制。 - -#### `void Close()` -关闭命令列表，停止录制。 - -#### `ID3D12GraphicsCommandList* GetCommandList() const` -获取底层 `ID3D12GraphicsCommandList` 指针。 - -### 资源状态转换 - -#### `void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter)` -添加资源状态转换屏障。 - -#### `void UAVBarrier(void* resource = nullptr)` -添加无序访问视图屏障。 - -#### `void AliasBarrier(void* beforeResource = nullptr, void* afterResource = nullptr)` -添加别名化屏障。 - -### 管线状态设置 - -#### `void SetPipelineState(void* pso)` -设置图形管线状态对象。 - -#### `void SetRootSignature(ID3D12RootSignature* signature)` -设置根签名。 - -#### `void SetPrimitiveTopology(PrimitiveTopology topology)` -设置图元拓扑类型。 - -### 视口与裁剪矩形 - -#### `void SetViewport(const Viewport& viewport)` -设置单个视口。 - -#### `void SetViewports(uint32_t count, const Viewport* viewports)` -设置多个视口。 - -#### `void SetScissorRect(const Rect& rect)` -设置单个裁剪矩形。 - -#### `void SetScissorRects(uint32_t count, const Rect* rects)` -设置多个裁剪矩形。 - -### 渲染目标 - -#### `void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr)` -设置渲染目标视图。 - -#### `void SetRenderTargetsInternal(uint32_t count, ID3D12Resource** renderTargets, ID3D12Resource* depthStencil = nullptr)` -内部方法，直接使用 D3D12 资源指针。 - -#### `void SetRenderTargetsHandle(uint32_t count, const D3D12_CPU_DESCRIPTOR_HANDLE* renderTargetHandles, const D3D12_CPU_DESCRIPTOR_HANDLE* depthStencilHandle = nullptr)` -使用 CPU 描述符句柄设置渲染目标。 - -### 顶点缓冲区与索引缓冲区 - -#### `void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride)` -设置单个顶点缓冲区。 - -#### `void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides)` -批量设置顶点缓冲区。 - -#### `void SetIndexBuffer(void* buffer, uint64_t offset, Format format)` -设置索引缓冲区。 - -### 描述符堆 - -#### `void SetDescriptorHeap(ID3D12DescriptorHeap* heap)` -设置描述符堆。 - -#### `void SetDescriptorHeaps(uint32_t count, ID3D12DescriptorHeap** heaps)` -设置多个描述符堆。 - -### 描述符表绑定 - -#### `void SetGraphicsDescriptorTable(uint32_t rootParameterIndex, D3D12_GPU_DESCRIPTOR_HANDLE baseHandle)` -设置图形渲染的描述符表。 - -#### `void SetComputeDescriptorTable(uint32_t rootParameterIndex, D3D12_GPU_DESCRIPTOR_HANDLE baseHandle)` -设置计算渲染的描述符表。 - -### 根参数绑定 - -#### `void SetGraphicsRootConstantBufferView(uint32_t rootParameterIndex, D3D12_GPU_VIRTUAL_ADDRESS bufferLocation)` -设置根常量缓冲区视图。 - -#### `void SetGraphicsRoot32BitConstants(uint32_t rootParameterIndex, uint32_t num32BitValuesToSet, const void* pSrcData, uint32_t destOffsetIn32BitValues)` -设置根参数 32 位常量。 - -#### `void SetGraphicsRootDescriptorTable(uint32_t rootParameterIndex, D3D12_GPU_DESCRIPTOR_HANDLE baseDescriptor)` -设置根描述符表。 - -#### `void SetGraphicsRootShaderResourceView(uint32_t rootParameterIndex, D3D12_GPU_VIRTUAL_ADDRESS shaderResource)` -设置根着色器资源视图。 - -### 渲染状态 - -#### `void SetStencilRef(uint32_t stencilRef)` -设置模板参考值。 - -#### `void SetBlendFactor(const float blendFactor[4])` -设置混合因子。 - -#### `void SetDepthBias(float depthBias, float slopeScaledDepthBias, float depthBiasClamp)` -设置深度偏移。 - -### 绘制命令 - -#### `void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0)` -绘制非索引图元。 - -#### `void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0)` -绘制索引图元。 - -#### `void DrawInstancedIndirect(void* argBuffer, uint64_t alignedByteOffset)` -间接绘制实例化图元。 - -#### `void DrawIndexedInstancedIndirect(void* argBuffer, uint64_t alignedByteOffset)` -间接绘制索引实例化图元。 - -### 清除命令 - -#### `void Clear(float r, float g, float b, float a, uint32_t buffers)` -清除渲染目标和/或深度模板缓冲区。 - -#### `void ClearRenderTarget(void* renderTarget, const float color[4])` -清除渲染目标。 - -#### `void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil)` -清除深度模板缓冲区。 - -#### `void ClearRenderTargetView(ID3D12Resource* renderTarget, const float color[4], uint32_t rectCount = 0, const D3D12_RECT* rects = nullptr)` -使用资源指针清除渲染目标。 - -#### `void ClearDepthStencilView(ID3D12Resource* depthStencil, uint32_t clearFlags, float depth = 1.0f, uint8_t stencil = 0, uint32_t rectCount = 0, const D3D12_RECT* rects = nullptr)` -使用资源指针清除深度模板。 - -#### `void ClearUnorderedAccessView(...)` -清除无序访问视图。 - -### 资源复制 - -#### `void CopyResource(void* dst, void* src)` -复制整个资源。 - -#### `void CopyBuffer(ID3D12Resource* dst, uint64_t dstOffset, ID3D12Resource* src, uint64_t srcOffset, uint64_t size)` -复制缓冲区数据。 - -#### `void CopyTexture(ID3D12Resource* dst, const D3D12_TEXTURE_COPY_LOCATION& dstLocation, ID3D12Resource* src, const D3D12_TEXTURE_COPY_LOCATION& srcLocation)` -复制纹理数据。 - -### 查询 - -#### `void BeginQuery(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t index)` -开始查询。 - -#### `void EndQuery(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t index)` -结束查询。 - -#### `void ResolveQueryData(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t startIndex, uint32_t count, ID3D12Resource* resultBuffer, uint64_t resultOffset)` -解析查询数据。 - -### 计算着色器 - -#### `void Dispatch(uint32_t x, uint32_t y, uint32_t z)` -分发计算着色器。 - -#### `void DispatchIndirect(void* argBuffer, uint64_t alignedByteOffset)` -间接分发计算着色器。 - -### Bundle - -#### `void ExecuteBundle(ID3D12GraphicsCommandList* bundle)` -执行 Bundle 命令列表。 - -### 资源状态管理 - -#### `ResourceStates GetResourceState(ID3D12Resource* resource) const` -获取资源当前状态。 - -#### `void TrackResource(ID3D12Resource* resource)` -跟踪资源状态变化。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_commandList` | `ComPtr` | D3D12 命令列表 | -| `m_type` | `CommandQueueType` | 命令队列类型 | -| `m_resourceStateMap` | `unordered_map` | 资源状态映射 | -| `m_trackedResources` | `vector` | 跟踪的资源列表 | -| `m_currentTopology` | `D3D12_PRIMITIVE_TOPOLOGY` | 当前拓扑类型 | -| `m_currentPipelineState` | `ID3D12PipelineState*` | 当前 PSO | -| `m_currentRootSignature` | `ID3D12RootSignature*` | 当前根签名 | -| `m_currentDescriptorHeap` | `ID3D12DescriptorHeap*` | 当前描述符堆 | - -## 使用示例 - -```cpp -D3D12Device device; -device.Initialize(desc); - -// Create command queue and list -CommandQueueDesc queueDesc; -queueDesc.type = CommandQueueType::Direct; -D3D12CommandQueue* cmdQueue = device.CreateCommandQueueImpl(queueDesc); - -CommandListDesc listDesc; -listDesc.type = CommandQueueType::Direct; -D3D12CommandList* cmdList = device.CreateCommandListImpl(listDesc); - -// Begin recording -cmdList->Reset(); -cmdList->SetPipelineState(pipelineState); -cmdList->SetRenderTargets(1, &rtvHandle, &dsvHandle); -cmdList->SetViewports(1, &viewport); -cmdList->SetScissorRect(scissorRect); -cmdList->SetVertexBuffers(0, 1, &vbv); -cmdList->DrawIndexed(indexCount, 1, 0, 0, 0); -cmdList->Close(); - -// Execute -cmdQueue->ExecuteCommandListsInternal(1, &cmdList); -``` - -## 继承关系 - -``` -RHICommandList (interface) -└── D3D12CommandList (implementation) -``` - -## 备注 - -- D3D12CommandList 内部维护资源状态映射，自动处理资源状态转换 -- 使用 `TrackResource` 可以将自定义资源添加到状态跟踪系统 -- Bundle 是一种优化手段，可以复用频繁执行的命令序列 diff --git a/docs/api/rhi/d3d12/d3d12-command-queue.md b/docs/api/rhi/d3d12/d3d12-command-queue.md deleted file mode 100644 index cde95f61..00000000 --- a/docs/api/rhi/d3d12/d3d12-command-queue.md +++ /dev/null @@ -1,113 +0,0 @@ -# D3D12CommandQueue - -DirectX 12 命令队列的 D3D12 实现，封装了 `ID3D12CommandQueue`。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHICommandQueue (interface) -└── D3D12CommandQueue (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12CommandQueue()` -默认构造函数。 - -#### `~D3D12CommandQueue() override` -析构函数，确保调用 `Shutdown()`。 - -### 初始化与销毁 - -#### `bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct)` -初始化命令队列。 -- `device`: D3D12 设备 -- `type`: 命令队列类型 -- 返回: 初始化是否成功 - -#### `void Shutdown() override` -关闭命令队列。 - -### 命令执行 - -#### `void ExecuteCommandLists(uint32_t count, void** lists)` -执行命令列表（接口实现）。 - -#### `void ExecuteCommandListsInternal(uint32_t count, ID3D12CommandList** lists)` -执行命令列表（内部实现，接受 D3D12 原生类型）。 - -### 同步操作 - -#### `void Signal(RHIFence* fence, uint64_t value)` -发送信号量到栅栏。 - -#### `void Wait(RHIFence* fence, uint64_t value)` -等待栅栏达到指定值。 - -#### `void WaitForIdle()` -等待命令队列空闲。 - -#### `uint64_t GetCompletedValue() override` -获取已完成信号值。 - -#### `void Signal(ID3D12Fence* fence, uint64_t value)` -发送信号（内部版本）。 - -#### `void Wait(ID3D12Fence* fence, uint64_t value)` -等待（内部版本）。 - -### 属性查询 - -#### `CommandQueueType GetType() const override` -获取命令队列类型。 - -#### `uint64_t GetTimestampFrequency() const override` -获取时间戳频率（Hz）。 - -#### `ID3D12CommandQueue* GetCommandQueue() const` -获取底层 `ID3D12CommandQueue` 指针。 - -#### `void* GetNativeHandle() override` -返回原生句柄。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_commandQueue` | `ComPtr` | D3D12 命令队列 | -| `m_type` | `CommandQueueType` | 命令队列类型 | -| `m_timestampFrequency` | `uint64_t` | 时间戳频率 | - -## 使用示例 - -```cpp -D3D12CommandQueue cmdQueue; -cmdQueue.Initialize(device->GetDevice(), CommandQueueType::Direct); - -// Execute command list -ID3D12CommandList* lists[] = { cmdList->GetCommandList() }; -cmdQueue.ExecuteCommandListsInternal(1, lists); - -// Sync with fence -D3D12Fence fence; -fence.Initialize(device->GetDevice()); -cmdQueue.Signal(fence.GetFence(), 1); -fence.Wait(1); - -// Wait for idle -cmdQueue.WaitForIdle(); -``` - -## 备注 - -- 三种命令队列类型：Direct（图形/计算）、Compute（计算）、Copy（复制） -- 时间戳频率用于将 GPU 时间戳转换为实际时间 -- `WaitForIdle` 会阻塞 CPU 直到所有已提交命令完成 diff --git a/docs/api/rhi/d3d12/d3d12-common.md b/docs/api/rhi/d3d12/d3d12-common.md deleted file mode 100644 index fa8ac3f5..00000000 --- a/docs/api/rhi/d3d12/d3d12-common.md +++ /dev/null @@ -1,124 +0,0 @@ -# D3D12Common - -D3D12 通用辅助函数集合，提供描述符大小、屏障创建、格式支持检查等功能。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::RHI` - -## 描述符大小函数 - -#### `inline UINT GetDescriptorHandleIncrementSize(ID3D12Device* device, D3D12_DESCRIPTOR_HEAP_TYPE heapType)` -获取描述符增量大小。 - -#### `inline UINT GetRTVDescriptorSize(ID3D12Device* device)` -获取 RTV 描述符大小。 - -#### `inline UINT GetDSVDescriptorSize(ID3D12Device* device)` -获取 DSV 描述符大小。 - -#### `inline UINT GetCBV_SRV_UAVDescriptorSize(ID3D12Device* device)` -获取 CBV/SRV/UAV 描述符大小。 - -#### `inline UINT GetSamplerDescriptorSize(ID3D12Device* device)` -获取 Sampler 描述符大小。 - -## 屏障创建函数 - -#### `inline D3D12_RESOURCE_BARRIER CreateTransitionBarrier(...)` -创建资源状态转换屏障。 - -参数： -- `resource`: 目标资源 -- `stateBefore`: 转换前状态 -- `stateAfter`: 转换后状态 -- `subresource`: 子资源索引（默认所有） - -#### `inline D3D12_RESOURCE_BARRIER CreateUAVBarrier(ID3D12Resource* resource = nullptr)` -创建 UAV 屏障。 - -#### `inline D3D12_RESOURCE_BARRIER CreateAliasingBarrier(...)` -创建别名化屏障。 - -## 格式支持检查 - -#### `inline bool CheckFormatSupport(ID3D12Device* device, DXGI_FORMAT format, D3D12_FORMAT_SUPPORT1 support1, D3D12_FORMAT_SUPPORT2 support2 = D3D12_FORMAT_SUPPORT2_NONE)` -检查格式支持。 - -#### `inline bool IsRenderTargetFormatSupported(ID3D12Device* device, DXGI_FORMAT format)` -检查是否支持作为渲染目标。 - -#### `inline bool IsDepthStencilFormatSupported(ID3D12Device* device, DXGI_FORMAT format)` -检查是否支持作为深度模板。 - -#### `inline bool IsShaderResourceFormatSupported(ID3D12Device* device, DXGI_FORMAT format)` -检查 shader 是否可以读取该格式。 - -#### `inline bool IsTextureFormatSupported(ID3D12Device* device, DXGI_FORMAT format)` -检查是否支持作为纹理。 - -## 清除值创建 - -#### `inline D3D12_CLEAR_VALUE CreateRenderTargetClearValue(DXGI_FORMAT format, float r = 0.0f, float g = 0.0f, float b = 0.0f, float a = 1.0f)` -创建渲染目标清除值。 - -#### `inline D3D12_CLEAR_VALUE CreateDepthStencilClearValue(DXGI_FORMAT format, float depth = 1.0f, uint8_t stencil = 0)` -创建深度模板清除值。 - -## 视口和裁剪矩形 - -#### `inline D3D12_VIEWPORT CreateViewport(float width, float height, float topLeftX = 0.0f, float topLeftY = 0.0f, float minDepth = 0.0f, float maxDepth = 1.0f)` -创建视口。 - -#### `inline D3D12_RECT CreateScissorRect(int left, int top, int right, int bottom)` -创建裁剪矩形。 - -## 缓冲区视图 - -#### `inline D3D12_VERTEX_BUFFER_VIEW CreateVertexBufferView(...)` -创建顶点缓冲区视图。 - -#### `inline D3D12_INDEX_BUFFER_VIEW CreateIndexBufferView(...)` -创建索引缓冲区视图。 - -## 描述符句柄运算 - -#### `inline D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle(...)` -计算偏移后的 CPU 描述符句柄。 - -#### `inline D3D12_GPU_DESCRIPTOR_HANDLE GetGPUDescriptorHandle(...)` -计算偏移后的 GPU 描述符句柄。 - -## 使用示例 - -```cpp -// Check format support -if (!IsRenderTargetFormatSupported(device, DXGI_FORMAT_R8G8B8A8_UNORM)) { - // Fall back to supported format -} - -// Create barriers -D3D12_RESOURCE_BARRIER barriers[2]; -barriers[0] = CreateTransitionBarrier( - resource, D3D12_RESOURCE_STATE_RENDER_TARGET, - D3D12_RESOURCE_STATE_PIXEL_SHADER_RESOURCE); -barriers[1] = CreateUAVBarrier(uavResource); - -// Set barriers -cmdList->ResourceBarrier(2, barriers); - -// Create viewport -D3D12_VIEWPORT vp = CreateViewport(1920.0f, 1080.0f); -cmdList->RSSetViewports(1, &vp); -``` - -## 备注 - -- 所有函数为 inline，可在头文件中使用 -- 这些是高频使用的辅助函数，避免重复代码 diff --git a/docs/api/rhi/d3d12/d3d12-constant-buffer-view.md b/docs/api/rhi/d3d12/d3d12-constant-buffer-view.md deleted file mode 100644 index 36571bd4..00000000 --- a/docs/api/rhi/d3d12/d3d12-constant-buffer-view.md +++ /dev/null @@ -1,47 +0,0 @@ -# D3D12ConstantBufferView - -DirectX 12 常量缓冲区视图的 D3D12 实现。 - -## 头文件 - -```cpp -#include -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12ConstantBufferView()` -默认构造函数。 - -#### `~D3D12ConstantBufferView()` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `void Initialize(ID3D12Device* device, ID3D12Resource* buffer, const D3D12_CONSTANT_BUFFER_VIEW_DESC* desc = nullptr)` -创建 CBV。 -- `buffer`: 缓冲区资源 -- `desc`: CBV 描述（可选，会自动设置 size 为 256 字节对齐） - -#### `void Shutdown()` -释放 CBV。 - -### 属性 - -#### `D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const` -获取 CPU 描述符句柄。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_handle` | `D3D12_CPU_DESCRIPTOR_HANDLE` | CPU 描述符句柄 | -| `m_resource` | `ID3D12Resource*` | 关联的缓冲区资源 | - -## 备注 - -- CBV 大小自动向上对齐到 256 字节 -- 常量缓冲区应使用 UPLOAD 堆类型以便 CPU 更新 -- 可以通过根签名直接绑定 CBV 而无需 CBV 描述符 diff --git a/docs/api/rhi/d3d12/d3d12-depth-stencil-view.md b/docs/api/rhi/d3d12/d3d12-depth-stencil-view.md deleted file mode 100644 index beb3678d..00000000 --- a/docs/api/rhi/d3d12/d3d12-depth-stencil-view.md +++ /dev/null @@ -1,52 +0,0 @@ -# D3D12DepthStencilView - -DirectX 12 深度模板视图的 D3D12 实现。 - -## 头文件 - -```cpp -#include -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12DepthStencilView()` -默认构造函数。 - -#### `~D3D12DepthStencilView()` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `void Initialize(ID3D12Device* device, ID3D12Resource* resource, const D3D12_DEPTH_STENCIL_VIEW_DESC* desc = nullptr)` -创建 DSV。 - -#### `void InitializeAt(ID3D12Device* device, ID3D12Resource* resource, D3D12_CPU_DESCRIPTOR_HANDLE handle, const D3D12_DEPTH_STENCIL_VIEW_DESC* desc = nullptr)` -在指定位置创建 DSV。 - -#### `void Shutdown()` -释放 DSV。 - -### 属性 - -#### `D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const` -获取 CPU 描述符句柄。 - -### 静态辅助函数 - -#### `static D3D12_DEPTH_STENCIL_VIEW_DESC CreateDesc(Format format, D3D12_DSV_DIMENSION dimension = D3D12_DSV_DIMENSION_TEXTURE2D)` -创建 DSV 描述。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_handle` | `D3D12_CPU_DESCRIPTOR_HANDLE` | CPU 描述符句柄 | -| `m_resource` | `ID3D12Resource*` | 关联的资源 | - -## 备注 - -- DSV 必须在 DSV 类型描述符堆中分配 -- 支持只读 DSV（通过描述符标志区分） diff --git a/docs/api/rhi/d3d12/d3d12-descriptor-heap.md b/docs/api/rhi/d3d12/d3d12-descriptor-heap.md deleted file mode 100644 index 4e4e5831..00000000 --- a/docs/api/rhi/d3d12/d3d12-descriptor-heap.md +++ /dev/null @@ -1,114 +0,0 @@ -# D3D12DescriptorHeap - -DirectX 12 描述符堆的 D3D12 实现，封装了 `ID3D12DescriptorHeap`。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHIDescriptorPool (interface) -└── D3D12DescriptorHeap (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12DescriptorHeap()` -默认构造函数。 - -#### `~D3D12DescriptorHeap() override` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `bool Initialize(ID3D12Device* device, DescriptorHeapType type, uint32_t numDescriptors, bool shaderVisible = false)` -使用参数初始化。 -- `device`: D3D12 设备 -- `type`: 描述符堆类型 -- `numDescriptors`: 描述符数量 -- `shaderVisible`: 是否对 GPU 可见（CBV_SRV_UAV 和 Sampler 堆需要） -- 返回: 初始化是否成功 - -#### `bool Initialize(const DescriptorPoolDesc& desc) override` -使用统一描述符初始化。 - -#### `void Shutdown() override` -释放描述符堆。 - -### 描述符句柄 - -#### `ID3D12DescriptorHeap* GetDescriptorHeap() const` -获取底层 `ID3D12DescriptorHeap` 指针。 - -#### `CPUDescriptorHandle GetCPUDescriptorHandle(uint32_t index)` -获取指定索引的 CPU 描述符句柄。 - -#### `GPUDescriptorHandle GetGPUDescriptorHandle(uint32_t index)` -获取指定索引的 GPU 描述符句柄。 - -#### `D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandleForHeapStart() const` -获取堆起始 CPU 句柄。 - -#### `D3D12_GPU_DESCRIPTOR_HANDLE GetGPUDescriptorHandleForHeapStart() const` -获取堆起始 GPU 句柄。 - -### 属性 - -#### `uint32_t GetDescriptorCount() const override` -获取描述符总数。 - -#### `DescriptorHeapType GetType() const override` -获取描述符堆类型。 - -#### `uint32_t GetDescriptorSize() const` -获取单个描述符大小（增量大小）。 - -#### `void* GetNativeHandle() override` -返回原生句柄。 - -### 静态辅助函数 - -#### `static D3D12_DESCRIPTOR_HEAP_DESC CreateDesc(DescriptorHeapType type, uint32_t numDescriptors, bool shaderVisible = false)` -创建 D3D12 描述符堆描述。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_descriptorHeap` | `ComPtr` | D3D12 描述符堆 | -| `m_type` | `DescriptorHeapType` | 堆类型 | -| `m_numDescriptors` | `uint32_t` | 描述符数量 | -| `m_descriptorSize` | `uint32_t` | 增量大小 | -| `m_shaderVisible` | `bool` | 是否 shader visible | - -## 使用示例 - -```cpp -// Create RTV heap -D3D12DescriptorHeap rtvHeap; -rtvHeap.Initialize(device->GetDevice(), DescriptorHeapType::RTV, 10, false); - -// Create SRV/CBV/UAV heap -D3D12DescriptorHeap cbvHeap; -cbvHeap.Initialize(device->GetDevice(), DescriptorHeapType::CBV_SRV_UAV, 100, true); - -// Get handle for creating views -D3D12_CPU_DESCRIPTOR_HANDLE rtvHandle = rtvHeap.GetCPUDescriptorHandle(0); - -// Create RTV -D3D12RenderTargetView rtv; -rtv.InitializeAt(device->GetDevice(), texture->GetResource(), rtvHandle, nullptr); -``` - -## 备注 - -- 四种描述符堆类型: CBV_SRV_UAV, Sampler, RTV, DSV -- RTV 和 DSV 堆通常不需要 shader visible -- CBV_SRV_UAV 和 Sampler 堆如需在 shader 中访问必须 shader visible -- 描述符堆创建后大小固定，不能调整 diff --git a/docs/api/rhi/d3d12/d3d12-device.md b/docs/api/rhi/d3d12/d3d12-device.md deleted file mode 100644 index 9441a58f..00000000 --- a/docs/api/rhi/d3d12/d3d12-device.md +++ /dev/null @@ -1,169 +0,0 @@ -# D3D12Device - -DirectX 12 设备的 D3D12 实现，是引擎的 RHI 抽象层 `RHIDevice` 接口的具体实现。 - -## 头文件 - -```cpp -#include -``` - -## 类概览 - -`D3D12Device` 封装了 DirectX 12 的 `ID3D12Device` 和 `IDXGIFactory4`，负责创建和管理所有 RHI 资源。 - -## 公共成员函数 - -### 初始化与销毁 - -#### `bool Initialize(const RHIDeviceDesc& desc)` -初始化 D3D12 设备，包括创建 DXGI Factory 和 D3D12 Device。 -- `desc`: 设备描述符，包含调试层配置等 -- 返回: 初始化是否成功 - -#### `void Shutdown()` -关闭并释放所有 D3D12 资源。 - -### 设备信息 - -#### `ID3D12Device* GetDevice() const` -获取底层 `ID3D12Device` 指针。 - -#### `IDXGIFactory4* GetFactory() const` -获取底层 `IDXGIFactory4` 指针。 - -#### `const AdapterInfo& GetAdapterInfo() const` -获取当前 GPU 适配器信息，包含: -- `description`: 适配器描述 -- `dedicatedVideoMemory`: 专用显存 -- `dedicatedSystemMemory`: 专用系统内存 -- `sharedSystemMemory`: 共享系统内存 -- `vendorId` / `deviceId`: 供应商和设备 ID -- `isSoftware`: 是否为软件适配器 - -#### `std::vector EnumerateAdapters()` -枚举系统中所有可用的 GPU 适配器。 - -### 功能查询 - -#### `UINT GetDescriptorHandleIncrementSize(DescriptorHeapType type) const` -获取指定类型描述符堆的增量大小。 -- `type`: 堆类型 (CBV_SRV_UAV, Sampler, RTV, DSV) - -#### `bool CheckFeatureSupport(D3D12_FEATURE feature, void* featureSupportData, uint32_t featureSupportDataSize)` -查询设备支持的特定功能。 - -#### `const RHICapabilities& GetCapabilities() const` -获取设备功能支持信息。 - -#### `const RHIDeviceInfo& GetDeviceInfo() const` -获取设备详细信息。 - -### 设备状态 - -#### `bool IsDeviceRemoved() const` -检测设备是否被移除（通常因驱动崩溃）。 - -### 资源创建 - -#### `RHIBuffer* CreateBuffer(const BufferDesc& desc)` {#buffer} -创建 D3D12 缓冲区。 - -#### `RHITexture* CreateTexture(const TextureDesc& desc)` {#texture} -创建 D3D12 纹理。 - -#### `RHISwapChain* CreateSwapChain(const SwapChainDesc& desc)` {#swapchain} -创建 D3D12 交换链。 - -#### `RHICommandList* CreateCommandList(const CommandListDesc& desc)` {#cmdlist} -创建 D3D12 命令列表。 - -#### `RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc)` {#cmdqueue} -创建 D3D12 命令队列。 - -#### `RHIShader* CompileShader(const ShaderCompileDesc& desc)` {#shader} -编译着色器。 - -#### `RHIPipelineState* CreatePipelineState(const PipelineStateDesc& desc)` {#pso} -创建管线状态对象。 - -#### `RHIFence* CreateFence(const FenceDesc& desc)` {#fence} -创建栅栏同步对象。 - -#### `RHISampler* CreateSampler(const SamplerDesc& desc)` {#sampler} -创建采样器。 - -### 内部实现创建 - -#### `D3D12CommandQueue* CreateCommandQueueImpl(const CommandQueueDesc& desc)` -创建 `D3D12CommandQueue` 实例。 - -#### `D3D12CommandList* CreateCommandListImpl(const CommandListDesc& desc)` -创建 `D3D12CommandList` 实例。 - -#### `D3D12CommandAllocator* CreateCommandAllocator(const CommandAllocatorDesc& desc)` -创建 `D3D12CommandAllocator`。 - -#### `D3D12DescriptorHeap* CreateDescriptorHeap(const DescriptorHeapDesc& desc)` -创建 `D3D12DescriptorHeap`。 - -#### `D3D12QueryHeap* CreateQueryHeap(const QueryHeapDesc& desc)` -创建 `D3D12QueryHeap`。 - -#### `D3D12RootSignature* CreateRootSignature(const RootSignatureDesc& desc)` -创建 `D3D12RootSignature`。 - -### 视图创建 - -#### `D3D12RenderTargetView* CreateRenderTargetView(D3D12Buffer* resource, const RenderTargetViewDesc& desc)` -创建渲染目标视图。 - -#### `D3D12DepthStencilView* CreateDepthStencilView(D3D12Buffer* resource, const DepthStencilViewDesc& desc)` -创建深度模板视图。 - -#### `D3D12ShaderResourceView* CreateShaderResourceView(D3D12Buffer* resource, const ShaderResourceViewDesc& desc)` -创建着色器资源视图。 - -#### `D3D12UnorderedAccessView* CreateUnorderedAccessView(D3D12Buffer* resource, const UnorderedAccessViewDesc& desc)` -创建无序访问视图。 - -#### `D3D12ConstantBufferView* CreateConstantBufferView(D3D12Buffer* resource, const ConstantBufferViewDesc& desc)` -创建常量缓冲区视图。 - -## 使用示例 - -```cpp -#include - -using namespace XCEngine::RHI; - -D3D12Device device; -RHIDeviceDesc desc; -desc.enableDebugLayer = true; - -if (device.Initialize(desc)) { - auto& caps = device.GetCapabilities(); - auto& info = device.GetAdapterInfo(); - - // Create resources - BufferDesc vertexBufferDesc; - vertexBufferDesc.size = 1024; - vertexBufferDesc.type = BufferType::Vertex; - RHIBuffer* vb = device.CreateBuffer(vertexBufferDesc); - - device.Shutdown(); -} -``` - -## 继承关系 - -``` -RHIDevice (interface) -└── D3D12Device (implementation) -``` - -## 备注 - -- D3D12Device 是引擎中最重要的 D3D12 对象，所有其他 D3D12 资源都依赖它创建 -- 设备移除（Device Removed）通常由驱动超时或硬件问题导致 -- 使用 `SetDeviceRemoved()` 可以模拟设备移除场景用于测试 diff --git a/docs/api/rhi/d3d12/d3d12-enum.md b/docs/api/rhi/d3d12/d3d12-enum.md deleted file mode 100644 index 65cfe06d..00000000 --- a/docs/api/rhi/d3d12/d3d12-enum.md +++ /dev/null @@ -1,154 +0,0 @@ -# D3D12Enum - -D3D12 枚举值转换函数集合，提供 RHI 抽象枚举到 D3D12 原生枚举的转换。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::RHI` - -## 转换函数列表 - -### 填充模式和剔除模式 - -#### `inline D3D12_FILL_MODE ToD3D12(FillMode mode)` -`FillMode::Wireframe` -> `D3D12_FILL_MODE_WIREFRAME` -`FillMode::Solid` -> `D3D12_FILL_MODE_SOLID` - -#### `inline D3D12_CULL_MODE ToD3D12(CullMode mode)` -`CullMode::None` -> `D3D12_CULL_MODE_NONE` -`CullMode::Front` -> `D3D12_CULL_MODE_FRONT` -`CullMode::Back` -> `D3D12_CULL_MODE_BACK` - -### 深度模板 - -#### `inline D3D12_COMPARISON_FUNC ToD3D12(ComparisonFunc func)` -转换比较函数 (Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual, Always) - -#### `inline D3D12_STENCIL_OP ToD3D12(StencilOp op)` -转换模板操作 (Keep, Zero, Replace, IncrSat, DecrSat, Invert, Incr, Decr) - -### 混合 - -#### `inline D3D12_BLEND_OP ToD3D12(BlendOp op)` -转换混合操作 (Add, Subtract, ReverseSubtract, Min, Max) - -#### `inline D3D12_BLEND ToD3D12(BlendFactor factor)` -转换混合因子 (Zero, One, SrcColor, InvSrcColor, SrcAlpha, InvSrcAlpha, SrcAlphaSat, BlendFactor, InvBlendFactor) - -#### `inline D3D12_LOGIC_OP ToD3D12(LogicOp op)` -转换逻辑操作 (Clear, Set, Copy, CopyInverted, Noop, Invert, And, Nand, Or, Nor, Xor, Equiv, AndReverse, AndInverted, OrReverse, OrInverted) - -### 纹理采样 - -#### `inline D3D12_FILTER ToD3D12(FilterMode mode)` -转换过滤器模式 (Point, Linear, Anisotropic, ComparisonPoint, ComparisonLinear, ComparisonAnisotropic) - -#### `inline D3D12_TEXTURE_ADDRESS_MODE ToD3D12(TextureAddressMode mode)` -转换纹理寻址模式 (Wrap, Mirror, Clamp, Border, MirrorOnce) - -#### `inline D3D12_STATIC_BORDER_COLOR ToD3D12(BorderColor color)` -转换边框颜色 (TransparentBlack, OpaqueBlack, OpaqueWhite) - -### Shader 相关 - -#### `inline D3D12_SHADER_VISIBILITY ToD3D12(ShaderVisibility visibility)` -转换 Shader 可见性 (All, Vertex, Hull, Domain, Geometry, Pixel, Amplification, Mesh) - -### 格式 - -#### `inline DXGI_FORMAT ToD3D12(Format format)` -转换纹理/缓冲区格式。 - -支持的格式映射： -- `Format::Unknown` -> `DXGI_FORMAT_UNKNOWN` -- `Format::R8_UNorm` -> `DXGI_FORMAT_R8_UNORM` -- `Format::R8G8_UNorm` -> `DXGI_FORMAT_R8G8_UNORM` -- `Format::R8G8B8A8_UNorm` -> `DXGI_FORMAT_R8G8B8A8_UNORM` -- `Format::R16G16B16A16_Float` -> `DXGI_FORMAT_R16G16B16A16_FLOAT` -- `Format::R32G32B32A32_Float` -> `DXGI_FORMAT_R32G32B32A32_FLOAT` -- `Format::R16_Float` -> `DXGI_FORMAT_R16_FLOAT` -- `Format::R32_Float` -> `DXGI_FORMAT_R32_FLOAT` -- `Format::D16_UNorm` -> `DXGI_FORMAT_D16_UNORM` -- `Format::D24_UNorm_S8_UInt` -> `DXGI_FORMAT_D24_UNORM_S8_UINT` -- `Format::D32_Float` -> `DXGI_FORMAT_D32_FLOAT` -- `Format::BC1-7_UNorm` -> 对应 BC 压缩格式 -- `Format::R32G32B32A32_UInt` -> `DXGI_FORMAT_R32G32B32A32_UINT` -- `Format::R32_UInt` -> `DXGI_FORMAT_R32_UINT` - -#### `inline DXGI_FORMAT ToDXGI(Format format)` -同 `ToD3D12(format)`，DXGI 别名。 - -### 资源状态 - -#### `inline D3D12_RESOURCE_STATES ToD3D12(ResourceStates state)` -转换资源状态 (Common, VertexAndConstantBuffer, IndexBuffer, RenderTarget, UnorderedAccess, DepthWrite, DepthRead, NonPixelShaderResource, PixelShaderResource, CopySrc, CopyDst, Present, GenericRead) - -### 堆类型 - -#### `inline D3D12_HEAP_TYPE ToD3D12(HeapType type)` -转换堆类型 (Default, Upload, Readback) - -### 拓扑 - -#### `inline D3D12_PRIMITIVE_TOPOLOGY_TYPE ToD3D12(PrimitiveTopology topology)` -转换图元拓扑类型 (Point, Line, Triangle, Patch) - -#### `inline D3D12_PRIMITIVE_TOPOLOGY ToD3D12Topology(PrimitiveTopology topology)` -转换详细图元拓扑 (PointList, LineList, LineStrip, TriangleList, TriangleStrip, PatchList 等) - -### 描述符堆 - -#### `inline D3D12_DESCRIPTOR_HEAP_TYPE ToD3D12(DescriptorHeapType type)` -转换描述符堆类型 (CBV_SRV_UAV, Sampler, RTV, DSV) - -### 查询 - -#### `inline D3D12_QUERY_TYPE ToD3D12(QueryType type)` -转换查询类型 (Occlusion, Timestamp, PipelineStatistics) - -### 根参数 - -#### `inline D3D12_ROOT_PARAMETER_TYPE ToD3D12(RootParameterType type)` -转换根参数类型 (DescriptorTable, Constants, CBV, SRV, UAV) - -### 纹理类型 - -#### `inline D3D12_RESOURCE_DIMENSION ToD3D12(TextureType type)` -转换纹理类型维度 (Texture1D, Texture2D, Texture3D) - -### 命令列表 - -#### `inline D3D12_COMMAND_LIST_TYPE ToD3D12(CommandQueueType type)` -转换命令列表类型 (Direct, Compute, Copy) - -## 使用示例 - -```cpp -// When creating PSO -D3D12_GRAPHICS_PIPELINE_STATE_DESC desc = {}; -desc.FillMode = ToD3D12(fillMode); -desc.CullMode = ToD3D12(cullMode); -desc.DepthStencilState.DepthFunc = ToD3D12(depthFunc); - -// When creating texture -D3D12_RESOURCE_DESC texDesc = {}; -texDesc.Format = ToD3D12(textureFormat); - -// When transitioning resource -D3D12_RESOURCE_BARRIER barrier = CreateTransitionBarrier( - resource, - ToD3D12(stateBefore), - ToD3D12(stateAfter)); -``` - -## 备注 - -- 所有转换函数为 inline，可在头文件中使用 -- switch 语句确保编译期检查所有枚举值 -- 未处理的枚举值返回合理的默认值 diff --git a/docs/api/rhi/d3d12/d3d12-fence.md b/docs/api/rhi/d3d12/d3d12-fence.md deleted file mode 100644 index bd5ff532..00000000 --- a/docs/api/rhi/d3d12/d3d12-fence.md +++ /dev/null @@ -1,106 +0,0 @@ -# D3D12Fence - -DirectX 12 栅栏同步对象的 D3D12 实现，封装了 `ID3D12Fence`。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHIFence (interface) -└── D3D12Fence (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12Fence()` -默认构造函数。 - -#### `~D3D12Fence() override` -析构函数，确保调用 `Shutdown()`。 - -### 初始化与销毁 - -#### `bool Initialize(ID3D12Device* device, uint64_t initialValue = 0)` -初始化栅栏。 -- `device`: D3D12 设备 -- `initialValue`: 初始信号值 -- 返回: 初始化是否成功 - -#### `void Shutdown() override` -关闭栅栏并释放事件句柄。 - -### 信号操作 - -#### `void Signal() override` -发送信号，将值增加 1。 - -#### `void Signal(uint64_t value) override` -发送信号，设置指定值。 - -#### `void Wait(uint64_t value) override` -等待栅栏达到指定值。 - -#### `uint64_t GetCompletedValue() const override` -获取当前完成值。 - -#### `bool IsSignaled() const override` -检查是否已达到信号值。 - -#### `void* GetEventHandle()` -获取事件句柄，用于自定义等待。 - -### 原生接口 - -#### `void* GetNativeHandle() override { return m_fence.Get(); }` - -#### `ID3D12Fence* GetFence() const` -获取底层 `ID3D12Fence` 指针。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_fence` | `ComPtr` | D3D12 栅栏对象 | -| `m_eventHandle` | `void*` | 同步事件句柄 | -| `m_signalValue` | `uint64_t` | 最后信号值 | - -## 使用示例 - -```cpp -D3D12Fence fence; -fence.Initialize(device->GetDevice()); - -// CPU-GPU 同步 -cmdQueue->Signal(fence.GetFence(), 1); -fence.Wait(1); - -// 多帧同步 -uint64_t frameFenceValues[3] = {0, 0, 0}; -int frameIndex = 0; - -void RenderFrame() { - uint64_t fenceValue = frameIndex + 1; - cmdQueue->Signal(fence.GetFence(), fenceValue); - - // Wait for this frame's previous render to complete - if (fence.GetCompletedValue() < frameFenceValues[frameIndex]) { - fence.Wait(frameFenceValues[frameIndex]); - } - - frameFenceValues[frameIndex] = fenceValue; - frameIndex = (frameIndex + 1) % 3; -} -``` - -## 备注 - -- 栅栏用于 CPU-GPU 和 GPU-GPU 同步 -- 事件句柄可用于 `WaitForSingleObject` 等 Win32 API -- 多帧缓冲时常用栅栏确保帧间资源安全 diff --git a/docs/api/rhi/d3d12/d3d12-overview.md b/docs/api/rhi/d3d12/d3d12-overview.md deleted file mode 100644 index 8dfe2ef0..00000000 --- a/docs/api/rhi/d3d12/d3d12-overview.md +++ /dev/null @@ -1,78 +0,0 @@ -# D3D12 后端概览 - -**命名空间**: `XCEngine::RHI` - -**类型**: `module` - -**描述**: DirectX 12 后端实现模块，提供对 DirectX 12 API 的完整封装。 - -## 概述 - -D3D12 后端是 XCEngine RHI 抽象层的 DirectX 12 实现。该模块封装了 DirectX 12 的所有核心功能，包括设备管理、资源创建、命令录制和执行、同步等。 - -## 模块内容 - -### 核心组件 - -| 组件 | 描述 | -|------|------| -| [D3D12Device](./d3d12-device.md) | DirectX 12 设备实现 | -| [D3D12CommandList](./d3d12-command-list.md) | 命令列表实现 | - -### 资源类型 - -| 组件 | 描述 | -|------|------| -| [D3D12Buffer](./d3d12-buffer.md) | GPU 缓冲区实现 | -| [D3D12Texture](./d3d12-texture.md) | GPU 纹理实现 | - -### 命令执行 - -| 组件 | 描述 | -|------|------| -| [D3D12CommandQueue](./d3d12-command-queue.md) | 命令队列实现 | -| [D3D12CommandAllocator](./d3d12-command-allocator.md) | 命令分配器 | - -### 同步原语 - -| 组件 | 描述 | -|------|------| -| [D3D12Fence](./d3d12-fence.md) | 同步栅栏实现 | -| [D3D12SwapChain](./d3d12-swap-chain.md) | 交换链实现 | - -### 渲染状态 - -| 组件 | 描述 | -|------|------| -| [D3D12Shader](./d3d12-shader.md) | 着色器实现 | -| [D3D12PipelineState](./d3d12-pipeline-state.md) | 管线状态对象 | -| [D3D12Sampler](./d3d12-sampler.md) | 采样器实现 | -| [D3D12RootSignature](./d3d12-root-signature.md) | 根签名实现 | - -### 描述符 - -| 组件 | 描述 | -|------|------| -| [D3D12DescriptorHeap](./d3d12-descriptor-heap.md) | 描述符堆实现 | -| [D3D12RenderTargetView](./d3d12-render-target-view.md) | 渲染目标视图 | -| [D3D12DepthStencilView](./d3d12-depth-stencil-view.md) | 深度模板视图 | -| [D3D12ShaderResourceView](./d3d12-shader-resource-view.md) | 着色器资源视图 | -| [D3D12UnorderedAccessView](./d3d12-unordered-access-view.md) | 无序访问视图 | -| [D3D12ConstantBufferView](./d3d12-constant-buffer-view.md) | 常量缓冲视图 | - -### 查询 - -| 组件 | 描述 | -|------|------| -| [D3D12QueryHeap](./d3d12-query-heap.md) | 查询堆实现 | - -### 工具 - -| 组件 | 描述 | -|------|------| -| [D3D12Screenshot](./d3d12-screenshot.md) | 截图工具 | - -## 相关文档 - -- [RHI 抽象层](../rhi/rhi-overview.md) -- [OpenGL 后端](../opengl/opengl-device.md) diff --git a/docs/api/rhi/d3d12/d3d12-pipeline-state.md b/docs/api/rhi/d3d12/d3d12-pipeline-state.md deleted file mode 100644 index 74d503c2..00000000 --- a/docs/api/rhi/d3d12/d3d12-pipeline-state.md +++ /dev/null @@ -1,123 +0,0 @@ -# D3D12PipelineState - -DirectX 12 管线状态对象的 D3D12 实现，封装了 `ID3D12PipelineState`。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHIPipelineState (interface) -└── D3D12PipelineState (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12PipelineState()` -默认构造函数。 - -#### `~D3D12PipelineState() override` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `bool Initialize(ID3D12Device* device, const D3D12_GRAPHICS_PIPELINE_STATE_DESC& desc)` -使用 D3D12 PSO 描述初始化。 -- `device`: D3D12 设备 -- `desc`: 完整的图形管线状态描述 -- 返回: 初始化是否成功 - -#### `void Shutdown() override` -释放 PSO 资源。 - -### 原生接口 - -#### `ID3D12PipelineState* GetPipelineState() const` -获取底层 `ID3D12PipelineState` 指针。 - -#### `void* GetNativeHandle() override` -返回原生句柄。 - -#### `PipelineType GetType() const override` -返回 `PipelineType::Graphics`。 - -### 绑定 - -#### `void Bind() override` -绑定 PSO 到命令列表。 - -#### `void Unbind() override` -解绑 PSO。 - -### 静态辅助函数 - -#### `static D3D12_GRAPHICS_PIPELINE_STATE_DESC CreateDesc(...)` -创建完整的 PSO 描述。 - -参数： -- `ID3D12RootSignature* rootSignature`: 根签名 -- `const D3D12_SHADER_BYTECODE& vs`: 顶点着色器 -- `const D3D12_SHADER_BYTECODE& ps`: 像素着色器 -- `const D3D12_SHADER_BYTECODE& gs`: 几何着色器（可选） -- `uint32_t inputElementCount`: 输入元素数量 -- `const D3D12_INPUT_ELEMENT_DESC* inputElements`: 输入元素数组 - -#### `static D3D12_INPUT_ELEMENT_DESC CreateInputElement(...)` -创建输入元素描述，有两个重载： -- 带 `alignedByteOffset` 参数 -- 自动计算 `alignedByteOffset` 参数 - -参数： -- `semanticName`: 语义名称 (e.g., "POSITION", "TEXCOORD") -- `semanticIndex`: 语义索引 -- `format`: 格式 -- `inputSlot`: 输入槽 -- `alignedByteOffset`: 对齐偏移（可选） - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_pipelineState` | `ComPtr` | D3D12 PSO 对象 | - -## 使用示例 - -```cpp -// Define input layout -D3D12_INPUT_ELEMENT_DESC inputElements[] = { - D3D12PipelineState::CreateInputElement("POSITION", 0, Format::R32G32B32A32_Float, 0), - D3D12PipelineState::CreateInputElement("TEXCOORD", 0, Format::R32G32_Float, 1), -}; - -// Create PSO description -D3D12_GRAPHICS_PIPELINE_STATE_DESC psoDesc = {}; -psoDesc.pRootSignature = rootSignature->GetRootSignature(); -psoDesc.VS = vertexShader.GetD3D12Bytecode(); -psoDesc.PS = pixelShader.GetD3D12Bytecode(); -psoDesc.InputLayout = { inputElements, 2 }; -psoDesc.RasterizerState = ...; -psoDesc.BlendState = ...; -psoDesc.DepthStencilState = ...; -psoDesc.SampleMask = UINT_MAX; -psoDesc.PrimitiveTopologyType = D3D12_PRIMITIVE_TOPOLOGY_TYPE_TRIANGLE; -psoDesc.NumRenderTargets = 1; -psoDesc.RTVFormats[0] = DXGI_FORMAT_R8G8B8A8_UNORM; -psoDesc.DSVFormat = DXGI_FORMAT_D24_UNORM_S8_UINT; -psoDesc.SampleDesc.Count = 1; - -D3D12PipelineState pso; -pso.Initialize(device->GetDevice(), psoDesc); -pso.Bind(); -``` - -## 备注 - -- PSO 一旦创建不可修改，只能重新创建 -- PSO 创建开销大，应缓存复用 -- `ID3D12PipelineState` 是不可变对象，切换开销比 OpenGL 小 diff --git a/docs/api/rhi/d3d12/d3d12-query-heap.md b/docs/api/rhi/d3d12/d3d12-query-heap.md deleted file mode 100644 index b3710f61..00000000 --- a/docs/api/rhi/d3d12/d3d12-query-heap.md +++ /dev/null @@ -1,82 +0,0 @@ -# D3D12QueryHeap - -DirectX 12 查询堆的 D3D12 实现，封装了 `ID3D12QueryHeap`。 - -## 头文件 - -```cpp -#include -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12QueryHeap()` -默认构造函数。 - -#### `~D3D12QueryHeap()` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `bool Initialize(ID3D12Device* device, QueryType type, uint32_t count)` -初始化查询堆。 -- `device`: D3D12 设备 -- `type`: 查询类型 -- `count`: 查询数量 -- 返回: 初始化是否成功 - -#### `void Shutdown()` -释放查询堆。 - -### 属性 - -#### `ID3D12QueryHeap* GetQueryHeap() const` -获取底层 `ID3D12QueryHeap` 指针。 - -#### `void* GetNativeHandle() const` -返回原生句柄。 - -#### `QueryType GetType() const` -获取查询类型。 - -#### `uint32_t GetCount() const` -获取查询数量。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_queryHeap` | `ComPtr` | D3D12 查询堆 | -| `m_type` | `QueryType` | 查询类型 | -| `m_count` | `uint32_t` | 查询数量 | - -## 使用示例 - -```cpp -// Create query heap for occlusion -D3D12QueryHeap queryHeap; -queryHeap.Initialize(device->GetDevice(), QueryType::Occlusion, 2); - -// Create readback buffer for results -D3D12Buffer readbackBuffer; -readbackBuffer.Initialize(device->GetDevice(), sizeof(uint64_t) * 2, - D3D12_RESOURCE_STATE_COPY_DEST, D3D12_HEAP_TYPE_READBACK); - -// In render pass -cmdList->BeginQuery(queryHeap.GetQueryHeap(), QueryType::Occlusion, 0); -// Draw bounding box -cmdList->Draw(8); -cmdList->EndQuery(queryHeap.GetQueryHeap(), QueryType::Occlusion, 0); - -// Resolve to readback buffer -cmdList->ResolveQueryData(queryHeap.GetQueryHeap(), QueryType::Occlusion, 0, 1, - readbackBuffer.GetResource(), 0); -``` - -## 备注 - -- 三种查询类型: Occlusion（遮挡）、Timestamp（时间戳）、PipelineStatistics（管线统计） -- 查询数据需要通过 resolve 操作复制到可读缓冲区 -- 时间戳查询需要命令队列支持时间戳功能 diff --git a/docs/api/rhi/d3d12/d3d12-render-target-view.md b/docs/api/rhi/d3d12/d3d12-render-target-view.md deleted file mode 100644 index 0fa91d8b..00000000 --- a/docs/api/rhi/d3d12/d3d12-render-target-view.md +++ /dev/null @@ -1,68 +0,0 @@ -# D3D12RenderTargetView - -DirectX 12 渲染目标视图的 D3D12 实现。 - -## 头文件 - -```cpp -#include -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12RenderTargetView()` -默认构造函数。 - -#### `~D3D12RenderTargetView()` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `void Initialize(ID3D12Device* device, ID3D12Resource* resource, const D3D12_RENDER_TARGET_VIEW_DESC* desc = nullptr)` -在描述符堆中分配描述符并创建 RTV。 -- `device`: D3D12 设备 -- `resource`: 资源对象 -- `desc`: RTV 描述（可选，自动推断） - -#### `void InitializeAt(ID3D12Device* device, ID3D12Resource* resource, D3D12_CPU_DESCRIPTOR_HANDLE handle, const D3D12_RENDER_TARGET_VIEW_DESC* desc = nullptr)` -在指定描述符句柄位置创建 RTV。 -- `handle`: 预分配的描述符句柄 - -#### `void Shutdown()` -释放 RTV（不释放资源）。 - -### 属性 - -#### `D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const` -获取 CPU 描述符句柄。 - -### 静态辅助函数 - -#### `static D3D12_RENDER_TARGET_VIEW_DESC CreateDesc(Format format, D3D12_RTV_DIMENSION dimension = D3D12_RTV_DIMENSION_TEXTURE2D)` -创建 RTV 描述。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_handle` | `D3D12_CPU_DESCRIPTOR_HANDLE` | CPU 描述符句柄 | -| `m_resource` | `ID3D12Resource*` | 关联的资源 | - -## 使用示例 - -```cpp -D3D12RenderTargetView rtv; -rtv.Initialize(device->GetDevice(), texture->GetResource()); - -// Or at specific handle -D3D12_CPU_DESCRIPTOR_HANDLE handle = rtvHeap.GetCPUDescriptorHandle(0); -D3D12RenderTargetView rtv2; -rtv2.InitializeAt(device->GetDevice(), texture2->GetResource(), handle); -``` - -## 备注 - -- RTV 不拥有底层资源，Shutdown 不会释放资源 -- RTV 必须在 RTV 类型描述符堆中分配 diff --git a/docs/api/rhi/d3d12/d3d12-root-signature.md b/docs/api/rhi/d3d12/d3d12-root-signature.md deleted file mode 100644 index 31779ed7..00000000 --- a/docs/api/rhi/d3d12/d3d12-root-signature.md +++ /dev/null @@ -1,132 +0,0 @@ -# D3D12RootSignature - -DirectX 12 根签名的 D3D12 实现，封装了 `ID3D12RootSignature`。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::RHI` (不继承 RHI 抽象接口) - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12RootSignature()` -默认构造函数。 - -#### `~D3D12RootSignature()` -析构函数，确保调用 `Shutdown()`。 - -### 生命周期 - -#### `bool Initialize(ID3D12Device* device, const D3D12_ROOT_SIGNATURE_DESC& desc)` -初始化根签名。 -- `device`: D3D12 设备 -- `desc`: 根签名描述 -- 返回: 初始化是否成功 - -#### `void Shutdown()` -释放根签名。 - -### 原生接口 - -#### `ID3D12RootSignature* GetRootSignature() const` -获取底层 `ID3D12RootSignature` 指针。 - -#### `void* GetNativeHandle() const` -返回原生句柄。 - -#### `uint32_t GetParameterCount() const` -获取根参数数量。 - -### 静态辅助函数 - -#### `static D3D12_ROOT_SIGNATURE_DESC CreateDesc(...)` -创建根签名描述。 - -参数： -- `D3D12_ROOT_PARAMETER* parameters`: 根参数数组 -- `uint32_t parameterCount`: 参数数量 -- `D3D12_STATIC_SAMPLER_DESC* samplers`: 静态采样器数组 -- `uint32_t samplerCount`: 静态采样器数量 -- `D3D12_ROOT_SIGNATURE_FLAGS flags`: 标志 - -#### `static D3D12_ROOT_PARAMETER CreateCBV(uint32_t shaderRegister, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0)` -创建常量缓冲区视图根参数。 - -#### `static D3D12_ROOT_PARAMETER CreateSRV(uint32_t shaderRegister, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0)` -创建着色器资源视图根参数。 - -#### `static D3D12_ROOT_PARAMETER CreateUAV(uint32_t shaderRegister, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0)` -创建无序访问视图根参数。 - -#### `static D3D12_ROOT_PARAMETER Create32BitConstants(uint32_t shaderRegister, uint32_t num32BitValues, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0)` -创建 32 位常量根参数。 - -#### `static D3D12_ROOT_PARAMETER CreateDescriptorTable(uint32_t numRanges, const D3D12_DESCRIPTOR_RANGE* ranges, ShaderVisibility visibility = ShaderVisibility::All)` -创建描述符表根参数。 - -#### `static D3D12_STATIC_SAMPLER_DESC CreateStaticSampler(...)` -创建静态采样器描述。 - -#### `static D3D12_SAMPLER_DESC CreateSamplerDesc(FilterMode filter, TextureAddressMode address, float maxLOD = D3D12_FLOAT32_MAX)` -创建采样器描述。 - -#### `static D3D12_DESCRIPTOR_RANGE CreateDescriptorRange(...)` -创建描述符范围。 - -参数： -- `type`: 描述符类型 (CBV, SRV, UAV, Sampler) -- `baseShaderRegister`: 基寄存器编号 -- `numDescriptors`: 描述符数量 -- `registerSpace`: 寄存器空间 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_rootSignature` | `ComPtr` | D3D12 根签名 | -| `m_parameterCount` | `uint32_t` | 参数数量 | - -## 使用示例 - -```cpp -// Create root parameters -D3D12_ROOT_PARAMETER params[3]; - -// Parameter 0: CBV -params[0] = D3D12RootSignature::CreateCBV(0); - -// Parameter 1: 32-bit constants (e.g., 4x4 matrix = 16 floats) -params[1] = D3D12RootSignature::Create32BitConstants(0, 16); - -// Parameter 2: Descriptor table -D3D12_DESCRIPTOR_RANGE ranges[1]; -ranges[0] = D3D12RootSignature::CreateDescriptorRange( - D3D12_DESCRIPTOR_RANGE_TYPE_SRV, 0, 10); -params[2] = D3D12RootSignature::CreateDescriptorTable(1, ranges); - -// Create static samplers -D3D12_SAMPLER_DESC sampDesc = D3D12RootSignature::CreateSamplerDesc( - FilterMode::Linear, TextureAddressMode::Wrap); -D3D12_STATIC_SAMPLER_DESC staticSamp = D3D12RootSignature::CreateStaticSampler(0, sampDesc); - -// Create root signature -D3D12_ROOT_SIGNATURE_DESC rsDesc = D3D12RootSignature::CreateDesc( - params, 3, &staticSamp, 1); -D3D12RootSignature rootSig; -rootSig.Initialize(device->GetDevice(), rsDesc); -``` - -## 备注 - -- 根签名定义 GPU 能访问的资源布局 -- 根参数有三种类型: 描述符表、常量、描述符 -- 描述符表使用描述符范围引用描述符堆中的描述符 -- 静态采样器嵌入根签名，无需描述符堆 -- 根签名需要与 PSO 匹配 diff --git a/docs/api/rhi/d3d12/d3d12-sampler.md b/docs/api/rhi/d3d12/d3d12-sampler.md deleted file mode 100644 index a24c3af9..00000000 --- a/docs/api/rhi/d3d12/d3d12-sampler.md +++ /dev/null @@ -1,64 +0,0 @@ -# D3D12Sampler - -DirectX 12 采样器的 D3D12 实现。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHISampler (interface) -└── D3D12Sampler (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12Sampler()` -默认构造函数。 - -#### `~D3D12Sampler() override` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `bool Initialize(ID3D12Device* device, const D3D12_SAMPLER_DESC& desc)` -初始化采样器。 -- `device`: D3D12 设备 -- `desc`: D3D12 采样器描述 -- 返回: 初始化是否成功 - -#### `void Shutdown() override` -释放采样器。 - -### 描述 - -#### `D3D12_SAMPLER_DESC GetDesc() const` -获取采样器描述。 - -### 接口实现 - -#### `void* GetNativeHandle() override` -返回 `nullptr`（D3D12 采样器通过描述符堆管理）。 - -#### `unsigned int GetID() override` -返回 0。 - -#### `void Bind(unsigned int unit) override / Unbind(unsigned int unit) override` -绑定/解绑（空实现）。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_desc` | `D3D12_SAMPLER_DESC` | 采样器描述 | - -## 备注 - -- D3D12 采样器通常放在根签名或采样器描述符堆中 -- 静态采样器在根签名中声明，无需描述符堆 diff --git a/docs/api/rhi/d3d12/d3d12-screenshot.md b/docs/api/rhi/d3d12/d3d12-screenshot.md deleted file mode 100644 index 1ad5ce80..00000000 --- a/docs/api/rhi/d3d12/d3d12-screenshot.md +++ /dev/null @@ -1,50 +0,0 @@ -# D3D12Screenshot - -D3D12 截图工具类，提供屏幕截图捕获功能。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::RHI` - -## 公共静态成员函数 - -#### `static bool Capture(ID3D12Device* device, ID3D12CommandQueue* commandQueue, ID3D12Resource* renderTarget, const char* filename, uint32_t width, uint32_t height)` -捕获渲染目标内容并保存为图片。 -- `device`: D3D12 设备 -- `commandQueue`: 命令队列 -- `renderTarget`: 渲染目标资源 -- `filename`: 输出文件名 -- `width` / `height`: 截图尺寸 -- 返回: 捕获是否成功 - -## 内部静态成员函数 - -#### `static bool CopyToReadbackAndSave(...)` -内部实现：复制到回读缓冲区并保存。 - -## 使用示例 - -```cpp -// Capture back buffer -D3D12Texture* backBuffer = swapChain->GetBackBuffer( - swapChain->GetCurrentBackBufferIndex()); - -D3D12Screenshot::Capture( - device->GetDevice(), - cmdQueue->GetCommandQueue(), - backBuffer->GetResource(), - "screenshot.png", - 1920, 1080); -``` - -## 备注 - -- 截图自动复制到 READBACK 堆然后保存 -- 支持 PNG 等常见图片格式 -- 可能在内部创建临时资源 diff --git a/docs/api/rhi/d3d12/d3d12-shader-resource-view.md b/docs/api/rhi/d3d12/d3d12-shader-resource-view.md deleted file mode 100644 index 75e7fec9..00000000 --- a/docs/api/rhi/d3d12/d3d12-shader-resource-view.md +++ /dev/null @@ -1,53 +0,0 @@ -# D3D12ShaderResourceView - -DirectX 12 着色器资源视图的 D3D12 实现。 - -## 头文件 - -```cpp -#include -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12ShaderResourceView()` -默认构造函数。 - -#### `~D3D12ShaderResourceView()` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `void Initialize(ID3D12Device* device, ID3D12Resource* resource, const D3D12_SHADER_RESOURCE_VIEW_DESC* desc = nullptr)` -创建 SRV。 - -#### `void InitializeAt(ID3D12Device* device, ID3D12Resource* resource, D3D12_CPU_DESCRIPTOR_HANDLE handle, const D3D12_SHADER_RESOURCE_VIEW_DESC* desc = nullptr)` -在指定位置创建 SRV。 - -#### `void Shutdown()` -释放 SRV。 - -### 属性 - -#### `D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const` -获取 CPU 描述符句柄。 - -### 静态辅助函数 - -#### `static D3D12_SHADER_RESOURCE_VIEW_DESC CreateDesc(Format format, D3D12_SRV_DIMENSION dimension = D3D12_SRV_DIMENSION_TEXTURE2D, uint32_t mipLevels = 1)` -创建 SRV 描述。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_handle` | `D3D12_CPU_DESCRIPTOR_HANDLE` | CPU 描述符句柄 | -| `m_resource` | `ID3D12Resource*` | 关联的资源 | - -## 备注 - -- SRV 用于在 shader 中读取资源 -- SRV 必须在 CBV_SRV_UAV 类型描述符堆中分配 -- 如果需要在 shader 中访问，必须创建 shader visible 的描述符堆 diff --git a/docs/api/rhi/d3d12/d3d12-shader.md b/docs/api/rhi/d3d12/d3d12-shader.md deleted file mode 100644 index 0e31696f..00000000 --- a/docs/api/rhi/d3d12/d3d12-shader.md +++ /dev/null @@ -1,108 +0,0 @@ -# D3D12Shader - -DirectX 12 着色器的 D3D12 实现，封装了 `ID3DBlob` 编译结果。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHIShader (interface) -└── D3D12Shader (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12Shader()` -默认构造函数。 - -#### `~D3D12Shader() override` -析构函数，确保调用 `Shutdown()`。 - -### 编译 - -#### `bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) override` -从文件编译着色器。 -- `filePath`: HLSL 文件路径 -- `entryPoint`: 入口点函数名 (e.g., "VS", "PS") -- `target`: 着色器目标 (e.g., "vs_5_1", "ps_5_1", "cs_5_1") -- 返回: 编译是否成功 - -#### `bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) override` -从内存编译着色器。 -- `sourceData`: 着色器源代码 -- `sourceSize`: 代码大小 -- `entryPoint`: 入口点 -- `target`: 目标 -- 返回: 编译是否成功 - -#### `void Shutdown() override` -释放着色器编译结果。 - -### 着色器信息 - -#### `const D3D12_SHADER_BYTECODE GetD3D12Bytecode() const` -获取 D3D12 着色器字节码结构。 - -#### `const void* GetBytecode() const` -获取字节码指针。 - -#### `size_t GetBytecodeSize() const` -获取字节码大小。 - -#### `ShaderType GetType() const override` -获取着色器类型。 - -#### `const InputLayoutDesc& GetInputLayout() const` -获取输入布局描述。 - -### 接口实现 - -#### `void* GetNativeHandle() override` -返回字节码指针。 - -#### `bool IsValid() const override` -检查着色器是否有效。 - -#### `void Bind() override / Unbind() override` -绑定/解绑（空实现）。 - -#### `void SetInt/SetFloat/SetVec3/SetVec4/SetMat4(...)` -设置着色器变量（空实现，实际通过根签名绑定）。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_bytecode` | `ComPtr` | 编译成功的字节码 | -| `m_error` | `ComPtr` | 编译错误信息 | -| `m_type` | `ShaderType` | 着色器类型 | -| `m_inputLayout` | `InputLayoutDesc` | 输入布局 | - -## 使用示例 - -```cpp -D3D12Shader vertexShader; -if (vertexShader.CompileFromFile(L"shaders/DefaultVS.hlsl", "main", "vs_5_1")) { - auto bytecode = vertexShader.GetD3D12Bytecode(); - // Use in PSO description -} - -D3D12Shader pixelShader; -pixelShader.CompileFromFile(L"shaders/DefaultPS.hlsl", "main", "ps_5_1"); - -D3D12Shader computeShader; -computeShader.CompileFromFile(L"shaders/CopyCS.hlsl", "main", "cs_5_1"); -``` - -## 备注 - -- 编译错误信息存储在 `m_error` 中，可输出到日志 -- 字节码用于创建 Pipeline State Object -- 着色器目标格式: `{type}_{major}_{minor}`, e.g., `vs_5_1`, `ps_6_0` diff --git a/docs/api/rhi/d3d12/d3d12-swap-chain.md b/docs/api/rhi/d3d12/d3d12-swap-chain.md deleted file mode 100644 index c5eb253b..00000000 --- a/docs/api/rhi/d3d12/d3d12-swap-chain.md +++ /dev/null @@ -1,136 +0,0 @@ -# D3D12SwapChain - -DirectX 12 交换链的 D3D12 实现，封装了 `IDXGISwapChain3`。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHISwapChain (interface) -└── D3D12SwapChain (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12SwapChain()` -默认构造函数。 - -#### `~D3D12SwapChain() override` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `bool Initialize(IDXGIFactory4* factory, ID3D12CommandQueue* commandQueue, HWND windowHandle, uint32_t width, uint32_t height, uint32_t bufferCount = 2)` -创建新的交换链。 -- `factory`: DXGI Factory -- `commandQueue`: 命令队列 -- `windowHandle`: 窗口句柄 -- `width` / `height`: 交换链尺寸 -- `bufferCount`: 后台缓冲区数量（默认 2） -- 返回: 初始化是否成功 - -#### `bool Initialize(IDXGISwapChain* swapChain, uint32_t width, uint32_t height)` -从现有 `IDXGISwapChain` 初始化。 -- `swapChain`: 已存在的交换链 -- `width` / `height`: 尺寸 -- 返回: 初始化是否成功 - -#### `void Shutdown() override` -释放交换链资源。 - -### 交换链操作 - -#### `uint32_t GetCurrentBackBufferIndex() const override` -获取当前后台缓冲区索引。 - -#### `RHITexture* GetCurrentBackBuffer() override` -获取当前后台缓冲区纹理。 - -#### `D3D12Texture* GetBackBuffer(uint32_t index) const` -获取指定索引的后台缓冲区。 - -#### `void Present(uint32_t syncInterval = 1, uint32_t flags = 0) override` -呈现（显示）内容。 -- `syncInterval`: 垂直同步间隔 (0=立即, 1-4=等待) -- `flags`: 附加标志 - -#### `void Resize(uint32_t width, uint32_t height) override` -调整交换链尺寸。 - -### 显示模式 - -#### `void SetFullscreen(bool fullscreen) override` -切换全屏模式。 - -#### `bool IsFullscreen() const override` -检查是否处于全屏模式。 - -### 事件处理 - -#### `bool ShouldClose() const override` -检查是否应该关闭（全屏时按 Alt+Enter）。 - -#### `void SetShouldClose(bool shouldClose)` -设置关闭标志。 - -#### `void PollEvents() override` -轮询窗口事件。 - -### 原生接口 - -#### `void* GetNativeHandle() override` -获取原生句柄。 - -#### `IDXGISwapChain3* GetSwapChain() const` -获取底层 `IDXGISwapChain3` 指针。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_swapChain` | `ComPtr` | DXGI 交换链 | -| `m_commandQueue` | `ComPtr` | 命令队列引用 | -| `m_windowHandle` | `HWND` | 窗口句柄 | -| `m_width` | `uint32_t` | 宽度 | -| `m_height` | `uint32_t` | 高度 | -| `m_bufferCount` | `uint32_t` | 缓冲区数量 | -| `m_backBuffers` | `vector` | 后台缓冲区纹理 | - -## 使用示例 - -```cpp -D3D12SwapChain swapChain; -swapChain.Initialize( - device->GetFactory(), - cmdQueue->GetCommandQueue(), - hwnd, 1920, 1080, 2); - -// Render loop -while (!swapChain.ShouldClose()) { - swapChain.PollEvents(); - - auto backBuffer = swapChain.GetCurrentBackBuffer(); - // Transition to render target state - // Render... - // Transition to present state - - swapChain.Present(1, 0); -} - -// Resize -swapChain.Resize(3840, 2160); -``` - -## 备注 - -- `syncInterval = 0`: 立即呈现，可能产生撕裂 -- `syncInterval = 1`: 等待垂直同步（推荐） -- 全屏模式切换需要处理窗口消息 -- 窗口尺寸改变后必须调用 `Resize` diff --git a/docs/api/rhi/d3d12/d3d12-texture.md b/docs/api/rhi/d3d12/d3d12-texture.md deleted file mode 100644 index 3f1d6f06..00000000 --- a/docs/api/rhi/d3d12/d3d12-texture.md +++ /dev/null @@ -1,169 +0,0 @@ -# D3D12Texture - -DirectX 12 纹理的 D3D12 实现，封装了 `ID3D12Resource` (texture 类型)。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHITexture (interface) -└── D3D12Texture (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12Texture()` -默认构造函数。 - -#### `~D3D12Texture() override` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `bool Initialize(ID3D12Device* device, const D3D12_RESOURCE_DESC& desc, D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON)` -使用资源描述创建纹理。 -- `device`: D3D12 设备 -- `desc`: D3D12 资源描述 -- `initialState`: 初始资源状态 -- 返回: 初始化是否成功 - -#### `bool InitializeFromExisting(ID3D12Resource* resource)` -从现有 `ID3D12Resource` 初始化。 - -#### `bool InitializeFromData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, const void* pixelData, uint32_t width, uint32_t height, DXGI_FORMAT format)` -创建纹理并从像素数据初始化。 -- `device`: D3D12 设备 -- `commandList`: 命令列表 -- `pixelData`: 像素数据指针 -- `width` / `height`: 纹理尺寸 -- `format`: 像素格式 -- 返回: 初始化是否成功 - -#### `bool InitializeDepthStencil(ID3D12Device* device, uint32_t width, uint32_t height, DXGI_FORMAT format = DXGI_FORMAT_D24_UNORM_S8_UINT)` -创建深度模板纹理。 -- `device`: D3D12 设备 -- `width` / `height`: 纹理尺寸 -- `format`: 深度格式 (D16, D24S8, D32F) -- 返回: 初始化是否成功 - -#### `void Shutdown() override` -释放纹理资源。 - -### 资源信息 - -#### `ID3D12Resource* GetResource() const` -获取底层 `ID3D12Resource` 指针。 - -#### `D3D12_RESOURCE_DESC GetDesc() const` -获取资源描述。 - -#### `uint32_t GetWidth() const override` -获取纹理宽度。 - -#### `uint32_t GetHeight() const override` -获取纹理高度。 - -#### `uint32_t GetDepth() const override` -获取纹理深度（3D 纹理）或数组大小。 - -#### `uint32_t GetMipLevels() const override` -获取 Mipmap 级别数量。 - -#### `uint32_t GetArraySize() const` -获取数组大小。 - -#### `uint64_t GetGPUAddress() const` -获取 GPU 虚拟地址。 - -#### `size_t GetSize() const` -获取纹理大小（字节估算）。 - -### 状态管理 - -#### `void* GetNativeHandle() override { return m_resource.Get(); }` -返回原生句柄。 - -#### `ResourceStates GetState() const override` -获取当前资源状态。 - -#### `void SetState(ResourceStates state) override` -设置资源状态。 - -### 接口实现 - -#### `Format GetFormat() const override` -获取纹理格式。 - -#### `TextureType GetTextureType() const override` -获取纹理类型（当前固定返回 `TextureType::Texture2D`）。 - -#### `const std::string& GetName() const override` -获取对象名称。 - -#### `void SetName(const std::string& name) override` -设置对象名称。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_resource` | `ComPtr` | D3D12 纹理资源 | -| `m_state` | `ResourceStates` | 当前资源状态 | -| `m_name` | `std::string` | 对象名称 | - -## 使用示例 - -### 创建 2D 纹理 - -```cpp -D3D12Texture texture; -D3D12_RESOURCE_DESC texDesc = {}; -texDesc.Dimension = D3D12_RESOURCE_DIMENSION_TEXTURE2D; -texDesc.Width = 1024; -texDesc.Height = 1024; -texDesc.MipLevels = 1; -texDesc.Format = DXGI_FORMAT_R8G8B8A8_UNORM; -texDesc.SampleDesc.Count = 1; -texDesc.Flags = D3D12_RESOURCE_FLAG_NONE; - -texture.Initialize(device->GetDevice(), texDesc); -``` - -### 创建深度模板纹理 - -```cpp -D3D12Texture depthTexture; -depthTexture.InitializeDepthStencil( - device->GetDevice(), - 1920, 1080, - DXGI_FORMAT_D24_UNORM_S8_UINT); -``` - -### 创建并初始化纹理数据 - -```cpp -D3D12Texture texture; -std::vector pixels(width * height * 4); -FillPixelData(pixels.data(), width, height); - -texture.InitializeFromData( - device->GetDevice(), - cmdList->GetCommandList(), - pixels.data(), - width, height, - DXGI_FORMAT_R8G8B8A8_UNORM); -``` - -## 备注 - -- 纹理通常创建在 `D3D12_HEAP_TYPE_DEFAULT` 堆上 -- 需要上传数据时，先创建 UPLOAD 堆缓冲区，再通过命令列表复制 -- 深度纹理需要设置 `D3D12_RESOURCE_FLAG_ALLOW_DEPTH_STENCIL` -- 渲染目标纹理需要设置 `D3D12_RESOURCE_FLAG_ALLOW_RENDER_TARGET` diff --git a/docs/api/rhi/d3d12/d3d12-types.md b/docs/api/rhi/d3d12/d3d12-types.md deleted file mode 100644 index 9f7852ce..00000000 --- a/docs/api/rhi/d3d12/d3d12-types.md +++ /dev/null @@ -1,74 +0,0 @@ -# D3D12Types - -D3D12 类型转换和辅助函数集合，提供 RHI 抽象类型到 D3D12 类型的转换。 - -## 头文件 - -```cpp -#include -``` - -## 命名空间 - -`XCEngine::RHI` - -## 转换函数 - -### Viewport 和 Rect - -#### `inline D3D12_VIEWPORT ToD3D12(const Viewport& vp)` -将 `Viewport` 转换为 `D3D12_VIEWPORT`。 - -#### `inline D3D12_RECT ToD3D12(const Rect& rect)` -将 `Rect` 转换为 `D3D12_RECT`。 - -### ClearValue - -#### `inline D3D12_CLEAR_VALUE ToD3D12(const ClearValue& clearValue, D3D12_RESOURCE_FLAGS flags = D3D12_RESOURCE_FLAG_NONE)` -将 `ClearValue` 转换为 `D3D12_CLEAR_VALUE`（颜色清除值）。 - -#### `inline D3D12_CLEAR_VALUE ToD3D12DepthStencil(const ClearValue& clearValue, DXGI_FORMAT format)` -将 `ClearValue` 转换为深度模板清除值。 - -### 资源描述 - -#### `inline D3D12_RESOURCE_DESC ToD3D12(const TextureDesc& desc)` -将 `TextureDesc` 转换为 `D3D12_RESOURCE_DESC`。 - -#### `inline D3D12_RESOURCE_DESC ToD3D12(const BufferDesc& desc)` -将 `BufferDesc` 转换为 `D3D12_RESOURCE_DESC`。 - -#### `inline D3D12_DESCRIPTOR_HEAP_DESC ToD3D12(const DescriptorHeapDesc& desc)` -将 `DescriptorHeapDesc` 转换为 `D3D12_DESCRIPTOR_HEAP_DESC`。 - -#### `inline D3D12_COMMAND_QUEUE_DESC ToD3D12(const CommandQueueDesc& desc)` -将 `CommandQueueDesc` 转换为 `D3D12_COMMAND_QUEUE_DESC`。 - -### 堆属性 - -#### `inline D3D12_HEAP_PROPERTIES ToD3D12HeapProperties(D3D12_HEAP_TYPE heapType, UINT nodeMask = 0)` -创建 D3D12 堆属性结构。 - -## 使用示例 - -```cpp -Viewport vp; -vp.topLeftX = 0; vp.topLeftY = 0; -vp.width = 1920; vp.height = 1080; -vp.minDepth = 0.0f; vp.maxDepth = 1.0f; - -D3D12_VIEWPORT d3dVp = ToD3D12(vp); - -TextureDesc texDesc; -texDesc.width = 1920; -texDesc.height = 1080; -texDesc.format = Format::R8G8B8A8_UNorm; -// ... set other fields - -D3D12_RESOURCE_DESC d3d12Desc = ToD3D12(texDesc); -``` - -## 备注 - -- 所有转换函数为 inline，可在头文件中使用 -- 转换自动处理类型映射和默认值设置 diff --git a/docs/api/rhi/d3d12/d3d12-unordered-access-view.md b/docs/api/rhi/d3d12/d3d12-unordered-access-view.md deleted file mode 100644 index 53074ff4..00000000 --- a/docs/api/rhi/d3d12/d3d12-unordered-access-view.md +++ /dev/null @@ -1,45 +0,0 @@ -# D3D12UnorderedAccessView - -DirectX 12 无序访问视图的 D3D12 实现。 - -## 头文件 - -```cpp -#include -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `D3D12UnorderedAccessView()` -默认构造函数。 - -#### `~D3D12UnorderedAccessView()` -析构函数，确保调用 `Shutdown()`。 - -### 初始化 - -#### `void Initialize(ID3D12Device* device, ID3D12Resource* resource, const D3D12_UNORDERED_ACCESS_VIEW_DESC* desc = nullptr)` -创建 UAV。 - -#### `void Shutdown()` -释放 UAV。 - -### 属性 - -#### `D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const` -获取 CPU 描述符句柄。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_handle` | `D3D12_CPU_DESCRIPTOR_HANDLE` | CPU 描述符句柄 | -| `m_resource` | `ID3D12Resource*` | 关联的资源 | - -## 备注 - -- UAV 用于 compute shader 中的读写访问 -- UAV 需要 barrier 来同步读写 -- UAV 必须在 CBV_SRV_UAV 类型描述符堆中分配 diff --git a/docs/api/rhi/d3d12/depth-stencil-view/create-desc.md b/docs/api/rhi/d3d12/depth-stencil-view/create-desc.md new file mode 100644 index 00000000..5f36d14e --- /dev/null +++ b/docs/api/rhi/d3d12/depth-stencil-view/create-desc.md @@ -0,0 +1,19 @@ +# D3D12DepthStencilView::CreateDesc + +```cpp +static D3D12_DEPTH_STENCIL_VIEW_DESC CreateDesc(Format format, D3D12_DSV_DIMENSION dimension = D3D12_DSV_DIMENSION_TEXTURE2D); +``` + +创建深度模板视图描述（静态方法）。 + +**参数：** +- `format` - 格式 +- `dimension` - 视图维度 + +**返回：** D3D12 深度模板视图描述 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DepthStencilView 总览](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/depth-stencil-view/depth-stencil-view.md b/docs/api/rhi/d3d12/depth-stencil-view/depth-stencil-view.md new file mode 100644 index 00000000..8b8e6fd8 --- /dev/null +++ b/docs/api/rhi/d3d12/depth-stencil-view/depth-stencil-view.md @@ -0,0 +1,19 @@ +# D3D12DepthStencilView + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 深度模板视图的 D3D12 实现。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `InitializeAt` | [详细文档](initialize-at.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetCPUDescriptorHandle` | [详细文档](get-cpu-descriptor-handle.md) | +| `CreateDesc` (static) | [详细文档](create-desc.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) diff --git a/docs/api/rhi/d3d12/depth-stencil-view/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/depth-stencil-view/get-cpu-descriptor-handle.md new file mode 100644 index 00000000..a956320a --- /dev/null +++ b/docs/api/rhi/d3d12/depth-stencil-view/get-cpu-descriptor-handle.md @@ -0,0 +1,15 @@ +# D3D12DepthStencilView::GetCPUDescriptorHandle + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const { return m_handle; } +``` + +获取 CPU 描述符句柄。 + +**返回：** CPU 描述符句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DepthStencilView 总览](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/depth-stencil-view/initialize-at.md b/docs/api/rhi/d3d12/depth-stencil-view/initialize-at.md new file mode 100644 index 00000000..0ed47b9a --- /dev/null +++ b/docs/api/rhi/d3d12/depth-stencil-view/initialize-at.md @@ -0,0 +1,19 @@ +# D3D12DepthStencilView::InitializeAt + +```cpp +void InitializeAt(ID3D12Device* device, ID3D12Resource* resource, D3D12_CPU_DESCRIPTOR_HANDLE handle, const D3D12_DEPTH_STENCIL_VIEW_DESC* desc = nullptr); +``` + +在指定位置初始化深度模板视图。 + +**参数：** +- `device` - D3D12 设备 +- `resource` - D3D12 资源 +- `handle` - CPU 描述符句柄 +- `desc` - 深度模板视图描述 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DepthStencilView 总览](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/descriptor-heap/create-desc.md b/docs/api/rhi/d3d12/descriptor-heap/create-desc.md new file mode 100644 index 00000000..a2353253 --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/create-desc.md @@ -0,0 +1,20 @@ +# D3D12DescriptorHeap::CreateDesc + +```cpp +static D3D12_DESCRIPTOR_HEAP_DESC CreateDesc(DescriptorHeapType type, uint32_t numDescriptors, bool shaderVisible = false); +``` + +创建描述符堆描述（静态方法）。 + +**参数：** +- `type` - 描述符堆类型 +- `numDescriptors` - 描述符数量 +- `shaderVisible` - 是否对 Shader 可见 + +**返回：** D3D12 描述符堆描述 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/descriptor-heap/descriptor-heap.md b/docs/api/rhi/d3d12/descriptor-heap/descriptor-heap.md new file mode 100644 index 00000000..8555d894 --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/descriptor-heap.md @@ -0,0 +1,28 @@ +# D3D12DescriptorHeap + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 描述符堆的 D3D12 实现，继承自 `RHIDescriptorPool`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` (params) | [详细文档](../../../threading/task-system/initialize.md) | +| `Initialize` (desc) | [详细文档](initialize-from-desc.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetDescriptorHeap` | [详细文档](get-descriptor-heap.md) | +| `GetCPUDescriptorHandle` | [详细文档](get-cpu-descriptor-handle.md) | +| `GetGPUDescriptorHandle` | [详细文档](get-gpu-descriptor-handle.md) | +| `GetDescriptorCount` | [详细文档](get-descriptor-count.md) | +| `GetType` | [详细文档](../../shader/get-type.md) | +| `GetDescriptorSize` | [详细文档](get-descriptor-size.md) | +| `GetCPUDescriptorHandleForHeapStart` | [详细文档](get-cpu-descriptor-handle-for-heap-start.md) | +| `GetGPUDescriptorHandleForHeapStart` | [详细文档](get-gpu-descriptor-handle-for-heap-start.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `CreateDesc` (static) | [详细文档](create-desc.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHIDescriptorPool](../../descriptor-pool/descriptor-pool.md) - 抽象描述符池接口 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle-for-heap-start.md b/docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle-for-heap-start.md new file mode 100644 index 00000000..74caa4da --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle-for-heap-start.md @@ -0,0 +1,15 @@ +# D3D12DescriptorHeap::GetCPUDescriptorHandleForHeapStart + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandleForHeapStart() const; +``` + +获取堆起始处的 CPU 描述符句柄。 + +**返回：** CPU 描述符句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle.md new file mode 100644 index 00000000..af1d9dae --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle.md @@ -0,0 +1,18 @@ +# D3D12DescriptorHeap::GetCPUDescriptorHandle + +```cpp +CPUDescriptorHandle GetCPUDescriptorHandle(uint32_t index); +``` + +获取 CPU 描述符句柄。 + +**参数：** +- `index` - 描述符索引 + +**返回：** CPU 描述符句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-descriptor-count.md b/docs/api/rhi/d3d12/descriptor-heap/get-descriptor-count.md new file mode 100644 index 00000000..027027b9 --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/get-descriptor-count.md @@ -0,0 +1,15 @@ +# D3D12DescriptorHeap::GetDescriptorCount + +```cpp +uint32_t GetDescriptorCount() const override; +``` + +获取描述符数量。 + +**返回：** 描述符数量 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-descriptor-heap.md b/docs/api/rhi/d3d12/descriptor-heap/get-descriptor-heap.md new file mode 100644 index 00000000..502fbb1f --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/get-descriptor-heap.md @@ -0,0 +1,15 @@ +# D3D12DescriptorHeap::GetDescriptorHeap + +```cpp +ID3D12DescriptorHeap* GetDescriptorHeap() const { return m_descriptorHeap.Get(); } +``` + +获取底层 D3D12 描述符堆接口。 + +**返回：** `ID3D12DescriptorHeap*` + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-descriptor-size.md b/docs/api/rhi/d3d12/descriptor-heap/get-descriptor-size.md new file mode 100644 index 00000000..44e4059d --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/get-descriptor-size.md @@ -0,0 +1,15 @@ +# D3D12DescriptorHeap::GetDescriptorSize + +```cpp +uint32_t GetDescriptorSize() const { return m_descriptorSize; } +``` + +获取描述符大小。 + +**返回：** 描述符大小（字节） + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle-for-heap-start.md b/docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle-for-heap-start.md new file mode 100644 index 00000000..bc33191b --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle-for-heap-start.md @@ -0,0 +1,15 @@ +# D3D12DescriptorHeap::GetGPUDescriptorHandleForHeapStart + +```cpp +D3D12_GPU_DESCRIPTOR_HANDLE GetGPUDescriptorHandleForHeapStart() const; +``` + +获取堆起始处的 GPU 描述符句柄。 + +**返回：** GPU 描述符句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle.md b/docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle.md new file mode 100644 index 00000000..036b4723 --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle.md @@ -0,0 +1,18 @@ +# D3D12DescriptorHeap::GetGPUDescriptorHandle + +```cpp +GPUDescriptorHandle GetGPUDescriptorHandle(uint32_t index); +``` + +获取 GPU 描述符句柄。 + +**参数：** +- `index` - 描述符索引 + +**返回：** GPU 描述符句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/descriptor-heap/initialize-from-desc.md b/docs/api/rhi/d3d12/descriptor-heap/initialize-from-desc.md new file mode 100644 index 00000000..762c2610 --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/initialize-from-desc.md @@ -0,0 +1,18 @@ +# D3D12DescriptorHeap::InitializeFromDesc + +```cpp +bool Initialize(const DescriptorPoolDesc& desc) override; +``` + +从描述符初始化。 + +**参数：** +- `desc` - 描述符池描述 + +**返回：** 是否初始化成功 + +**复杂度：** O(n) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/device/check-feature-support.md b/docs/api/rhi/d3d12/device/check-feature-support.md new file mode 100644 index 00000000..2947ffb1 --- /dev/null +++ b/docs/api/rhi/d3d12/device/check-feature-support.md @@ -0,0 +1,25 @@ +# D3D12Device::CheckFeatureSupport + +```cpp +bool CheckFeatureSupport(D3D12_FEATURE feature, void* featureSupportData, uint32_t featureSupportDataSize) +``` + +检查特性支持。 + +**参数：** +- `feature` - 特性类型 +- `featureSupportData` - 特性支持数据缓冲区 +- `featureSupportDataSize` - 数据大小 + +**返回：** 是否支持该特性 + +**示例：** + +```cpp +D3D12_FEATURE_DATA_D3D12_OPTIONS options; +bool supported = d3d12Device->CheckFeatureSupport(D3D12_FEATURE_D3D12_OPTIONS, &options, sizeof(options)); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/device/device.md b/docs/api/rhi/d3d12/device/device.md new file mode 100644 index 00000000..c17580f2 --- /dev/null +++ b/docs/api/rhi/d3d12/device/device.md @@ -0,0 +1,42 @@ +# D3D12Device + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 设备实现，继承自 `RHIDevice`。 + +## 公共方法 + +### 继承方法 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `CreateBuffer` | [详细文档](../../device/create-buffer.md) | +| `CreateTexture` | [详细文档](../../device/create-texture.md) | +| `CreateSwapChain` | [详细文档](../../device/create-swap-chain.md) | +| `CreateCommandList` | [详细文档](../../device/create-command-list.md) | +| `CreateCommandQueue` | [详细文档](../../device/create-command-queue.md) | +| `CompileShader` | [详细文档](../../device/compile-shader.md) | +| `CreatePipelineState` | [详细文档](../../device/create-pipeline-state.md) | +| `CreateFence` | [详细文档](../../device/create-fence.md) | +| `CreateSampler` | [详细文档](../../device/create-sampler.md) | +| `GetCapabilities` | [详细文档](../../device/get-capabilities.md) | +| `GetDeviceInfo` | [详细文档](../../device/get-device-info.md) | +| `GetNativeDevice` | [详细文档](../../device/get-native-device.md) | + +### D3D12 特有方法 + +| 方法 | 文档 | +|------|------| +| `GetDevice` | [详细文档](get-device.md) | +| `GetFactory` | [详细文档](get-factory.md) | +| `GetAdapterInfo` | [详细文档](get-adapter-info.md) | +| `EnumerateAdapters` | [详细文档](enumerate-adapters.md) | +| `GetDescriptorHandleIncrementSize` | [详细文档](get-descriptor-handle-increment-size.md) | +| `CheckFeatureSupport` | [详细文档](check-feature-support.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHIDevice](../../device/device.md) - 抽象设备接口 diff --git a/docs/api/rhi/d3d12/device/enumerate-adapters.md b/docs/api/rhi/d3d12/device/enumerate-adapters.md new file mode 100644 index 00000000..a26b40be --- /dev/null +++ b/docs/api/rhi/d3d12/device/enumerate-adapters.md @@ -0,0 +1,22 @@ +# D3D12Device::EnumerateAdapters + +```cpp +std::vector EnumerateAdapters() +``` + +枚举所有可用的图形适配器。 + +**返回：** 适配器信息列表 + +**示例：** + +```cpp +std::vector adapters = d3d12Device->EnumerateAdapters(); +for (const auto& adapter : adapters) { + wprintf(L"Adapter: %ls\n", adapter.description.c_str()); +} +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/device/get-adapter-info.md b/docs/api/rhi/d3d12/device/get-adapter-info.md new file mode 100644 index 00000000..18fa3557 --- /dev/null +++ b/docs/api/rhi/d3d12/device/get-adapter-info.md @@ -0,0 +1,20 @@ +# D3D12Device::GetAdapterInfo + +```cpp +const AdapterInfo& GetAdapterInfo() const +``` + +获取适配器信息。 + +**返回：** 适配器信息结构体引用 + +**示例：** + +```cpp +const AdapterInfo& info = d3d12Device->GetAdapterInfo(); +wprintf(L"GPU: %ls\n", info.description.c_str()); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/device/get-descriptor-handle-increment-size.md b/docs/api/rhi/d3d12/device/get-descriptor-handle-increment-size.md new file mode 100644 index 00000000..2123bf5c --- /dev/null +++ b/docs/api/rhi/d3d12/device/get-descriptor-handle-increment-size.md @@ -0,0 +1,22 @@ +# D3D12Device::GetDescriptorHandleIncrementSize + +```cpp +UINT GetDescriptorHandleIncrementSize(DescriptorHeapType type) const +``` + +获取描述符句柄增量大小。 + +**参数：** +- `type` - 描述符堆类型 + +**返回：** 描述符句柄增量大小（字节） + +**示例：** + +```cpp +UINT size = d3d12Device->GetDescriptorHandleIncrementSize(DescriptorHeapType::CBV_SRV_UAV); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/device/get-device.md b/docs/api/rhi/d3d12/device/get-device.md new file mode 100644 index 00000000..df08ac45 --- /dev/null +++ b/docs/api/rhi/d3d12/device/get-device.md @@ -0,0 +1,19 @@ +# D3D12Device::GetDevice + +```cpp +ID3D12Device* GetDevice() const +``` + +获取底层 D3D12 设备指针。 + +**返回：** DirectX 12 设备指针 + +**示例：** + +```cpp +ID3D12Device* device = d3d12Device->GetDevice(); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/device/get-factory.md b/docs/api/rhi/d3d12/device/get-factory.md new file mode 100644 index 00000000..b90675a9 --- /dev/null +++ b/docs/api/rhi/d3d12/device/get-factory.md @@ -0,0 +1,19 @@ +# D3D12Device::GetFactory + +```cpp +IDXGIFactory4* GetFactory() const +``` + +获取底层 DXGI 工厂指针。 + +**返回：** DXGI 工厂指针 + +**示例：** + +```cpp +IDXGIFactory4* factory = d3d12Device->GetFactory(); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/device/methods.md b/docs/api/rhi/d3d12/device/methods.md new file mode 100644 index 00000000..fd1ef2a5 --- /dev/null +++ b/docs/api/rhi/d3d12/device/methods.md @@ -0,0 +1,165 @@ +# D3D12Device 方法 + +## 继承方法 + +### Initialize + +```cpp +bool Initialize(const RHIDeviceDesc& desc) override; +``` + +初始化 D3D12 设备。 + +### Shutdown + +```cpp +void Shutdown() override; +``` + +关闭设备。 + +### CreateBuffer + +```cpp +RHIBuffer* CreateBuffer(const BufferDesc& desc) override; +``` + +创建 D3D12 缓冲区。 + +### CreateTexture + +```cpp +RHITexture* CreateTexture(const TextureDesc& desc) override; +``` + +创建 D3D12 纹理。 + +### CreateSwapChain + +```cpp +RHISwapChain* CreateSwapChain(const SwapChainDesc& desc) override; +``` + +创建 D3D12 交换链。 + +### CreateCommandList + +```cpp +RHICommandList* CreateCommandList(const CommandListDesc& desc) override; +``` + +创建 D3D12 命令列表。 + +### CreateCommandQueue + +```cpp +RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) override; +``` + +创建 D3D12 命令队列。 + +### CompileShader + +```cpp +RHIShader* CompileShader(const ShaderCompileDesc& desc) override; +``` + +编译 D3D12 着色器。 + +### CreatePipelineState + +```cpp +RHIPipelineState* CreatePipelineState(const PipelineStateDesc& desc) override; +``` + +创建 D3D12 管线状态对象。 + +### CreateFence + +```cpp +RHIFence* CreateFence(const FenceDesc& desc) override; +``` + +创建 D3D12 栅栏。 + +### CreateSampler + +```cpp +RHISampler* CreateSampler(const SamplerDesc& desc) override; +``` + +创建 D3D12 采样器。 + +### GetCapabilities + +```cpp +const RHICapabilities& GetCapabilities() const override; +``` + +获取设备能力。 + +### GetDeviceInfo + +```cpp +const RHIDeviceInfo& GetDeviceInfo() const override; +``` + +获取设备信息。 + +### GetNativeDevice + +```cpp +void* GetNativeDevice() override; +``` + +获取原生 D3D12 设备指针。 + +## D3D12 特有方法 + +### GetDevice + +```cpp +ID3D12Device* GetDevice() const; +``` + +获取 `ID3D12Device` 接口。 + +### GetFactory + +```cpp +IDXGIFactory4* GetFactory() const; +``` + +获取 `IDXGIFactory4` 接口。 + +### GetAdapterInfo + +```cpp +const AdapterInfo& GetAdapterInfo() const; +``` + +获取适配器信息。 + +### EnumerateAdapters + +```cpp +std::vector EnumerateAdapters(); +``` + +枚举所有适配器。 + +### GetDescriptorHandleIncrementSize + +```cpp +UINT GetDescriptorHandleIncrementSize(DescriptorHeapType type) const; +``` + +获取描述符句柄增量大小。 + +### CheckFeatureSupport + +```cpp +bool CheckFeatureSupport(D3D12_FEATURE feature, void* featureSupportData, uint32_t featureSupportDataSize); +``` + +检查功能支持。 diff --git a/docs/api/rhi/d3d12/enums/enums.md b/docs/api/rhi/d3d12/enums/enums.md new file mode 100644 index 00000000..a9060c16 --- /dev/null +++ b/docs/api/rhi/d3d12/enums/enums.md @@ -0,0 +1,37 @@ +# D3D12Enum + +**命名空间**: `XCEngine::RHI` + +**描述**: D3D12 枚举值转换函数集合，提供 RHI 抽象枚举到 D3D12 原生枚举的转换。**所有函数均为 inline 函数**。 + +## 转换函数列表 + +| 函数 | 描述 | +|------|------| +| `ToD3D12(FillMode)` | 填充模式转换 | +| `ToD3D12(CullMode)` | 剔除模式转换 | +| `ToD3D12(ComparisonFunc)` | 比较函数转换 | +| `ToD3D12(StencilOp)` | 模板操作转换 | +| `ToD3D12(BlendOp)` | 混合操作转换 | +| `ToD3D12(BlendFactor)` | 混合因子转换 | +| `ToD3D12(LogicOp)` | 逻辑操作转换 | +| `ToD3D12(FilterMode)` | 过滤器模式转换 | +| `ToD3D12(TextureAddressMode)` | 纹理寻址模式转换 | +| `ToD3D12(BorderColor)` | 边框颜色转换 | +| `ToD3D12(ShaderVisibility)` | Shader 可见性转换 | +| `ToD3D12(Format)` | 格式转换 | +| `ToDXGI(Format)` | DXGI 格式转换 | +| `ToD3D12(ResourceStates)` | 资源状态转换 | +| `ToD3D12(HeapType)` | 堆类型转换 | +| `ToD3D12(PrimitiveTopology)` | 图元拓扑类型转换 | +| `ToD3D12Topology` | 图元拓扑详细转换 | +| `ToD3D12(DescriptorHeapType)` | 描述符堆类型转换 | +| `ToD3D12(QueryType)` | 查询类型转换 | +| `ToD3D12(RootParameterType)` | 根参数类型转换 | +| `ToD3D12(TextureType)` | 纹理类型维度转换 | +| `ToD3D12(CommandQueueType)` | 命令列表类型转换 | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [D3D12Types](../../types/types.md) - 类型转换 diff --git a/docs/api/rhi/d3d12/fence/fence.md b/docs/api/rhi/d3d12/fence/fence.md new file mode 100644 index 00000000..210240f9 --- /dev/null +++ b/docs/api/rhi/d3d12/fence/fence.md @@ -0,0 +1,24 @@ +# D3D12Fence + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 栅栏同步对象的 D3D12 实现，继承自 `RHIFence`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Signal` | [详细文档](signal.md) | +| `Wait` | [详细文档](../../../threading/task-group/wait.md) | +| `GetCompletedValue` | [详细文档](get-completed-value.md) | +| `IsSignaled` | [详细文档](is-signaled.md) | +| `GetEventHandle` | [详细文档](get-event-handle.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `GetFence` | [详细文档](get-fence.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHIFence](../../fence/fence.md) - 抽象栅栏接口 diff --git a/docs/api/rhi/d3d12/fence/get-completed-value.md b/docs/api/rhi/d3d12/fence/get-completed-value.md new file mode 100644 index 00000000..bbead1ad --- /dev/null +++ b/docs/api/rhi/d3d12/fence/get-completed-value.md @@ -0,0 +1,34 @@ +# D3D12Fence::GetCompletedValue + +## 函数签名 + +```cpp +uint64_t GetCompletedValue() const override +``` + +## 中文描述 + +获取 GPU 已完成的最新栅栏值。 + +## 返回值 + +`uint64_t` - 已完成的栅栏值 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +uint64_t completedValue = d3d12Fence->GetCompletedValue(); +if (completedValue >= fenceValue) { + // 指定的栅栏值已完成 +} +``` + +## 相关文档 + +- [D3D12Fence](fence.md) - 类总览 +- [D3D12Fence::Signal](signal.md) - 信号栅栏 +- [D3D12Fence::IsSignaled](is-signaled.md) - 检查是否已信号 diff --git a/docs/api/rhi/d3d12/fence/get-event-handle.md b/docs/api/rhi/d3d12/fence/get-event-handle.md new file mode 100644 index 00000000..cc889439 --- /dev/null +++ b/docs/api/rhi/d3d12/fence/get-event-handle.md @@ -0,0 +1,31 @@ +# D3D12Fence::GetEventHandle + +## 函数签名 + +```cpp +void* GetEventHandle() +``` + +## 中文描述 + +获取用于 CPU 等待的 event 句柄。用于 `WaitForSingleObject` 等 API 进行阻塞等待。 + +## 返回值 + +`void*` - Win32 event 句柄 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +HANDLE eventHandle = static_cast(d3d12Fence->GetEventHandle()); +WaitForSingleObject(eventHandle, INFINITE); +``` + +## 相关文档 + +- [D3D12Fence](fence.md) - 类总览 +- [D3D12Fence::Wait](../../../threading/task-group/wait.md) - 等待栅栏 diff --git a/docs/api/rhi/d3d12/fence/get-fence.md b/docs/api/rhi/d3d12/fence/get-fence.md new file mode 100644 index 00000000..4084d487 --- /dev/null +++ b/docs/api/rhi/d3d12/fence/get-fence.md @@ -0,0 +1,30 @@ +# D3D12Fence::GetFence + +## 函数签名 + +```cpp +ID3D12Fence* GetFence() const +``` + +## 中文描述 + +获取底层 `ID3D12Fence` 接口指针。 + +## 返回值 + +`ID3D12Fence*` - D3D12 栅栏接口指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +ID3D12Fence* fence = d3d12Fence->GetFence(); +``` + +## 相关文档 + +- [D3D12Fence](fence.md) - 类总览 +- [D3D12Fence::GetNativeHandle](../../buffer/get-native-handle.md) - 获取原生句柄 diff --git a/docs/api/rhi/d3d12/fence/is-signaled.md b/docs/api/rhi/d3d12/fence/is-signaled.md new file mode 100644 index 00000000..b6c622db --- /dev/null +++ b/docs/api/rhi/d3d12/fence/is-signaled.md @@ -0,0 +1,33 @@ +# D3D12Fence::IsSignaled + +## 函数签名 + +```cpp +bool IsSignaled() const override +``` + +## 中文描述 + +检查当前栅栏值是否已达到 signal 值。 + +## 返回值 + +`bool` - 如果已完成则返回 `true`，否则返回 `false` + +## 复杂度 + +O(1) + +## 示例 + +```cpp +if (d3d12Fence->IsSignaled()) { + // 栅栏已完成，可以继续执行 +} +``` + +## 相关文档 + +- [D3D12Fence](fence.md) - 类总览 +- [D3D12Fence::GetCompletedValue](get-completed-value.md) - 获取完成值 +- [D3D12Fence::Wait](../../../threading/task-group/wait.md) - 等待栅栏 diff --git a/docs/api/rhi/d3d12/fence/signal.md b/docs/api/rhi/d3d12/fence/signal.md new file mode 100644 index 00000000..6344e27a --- /dev/null +++ b/docs/api/rhi/d3d12/fence/signal.md @@ -0,0 +1,46 @@ +# D3D12Fence::Signal + +## 函数签名 + +```cpp +void Signal() override +``` + +## 中文描述 + +将栅栏值设置为 GPU 当前 signaled 值，通常用于标记命令队列执行完成。 + +## 重载 + +| 版本 | 签名 | +|------|------| +| 无参数 | `void Signal()` | +| 带值 | `void Signal(uint64_t value)` | + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `value` | `uint64_t` | 要设置的栅栏值（仅带参数版本） | + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +d3d12Fence->Signal(); +// 或指定值 +d3d12Fence->Signal(1); +``` + +## 相关文档 + +- [D3D12Fence](fence.md) - 类总览 +- [D3D12Fence::Wait](../../../threading/task-group/wait.md) - 等待栅栏 +- [D3D12Fence::GetCompletedValue](get-completed-value.md) - 获取完成值 diff --git a/docs/api/rhi/d3d12/overview.md b/docs/api/rhi/d3d12/overview.md new file mode 100644 index 00000000..74a50882 --- /dev/null +++ b/docs/api/rhi/d3d12/overview.md @@ -0,0 +1,77 @@ +# D3D12 后端概览 + +**命名空间**: `XCEngine::RHI` + +**类型**: `module` + +**描述**: DirectX 12 后端实现模块，提供对 DirectX 12 API 的完整封装。 + +## 组件列表 + +### 核心组件 + +| 组件 | 文档 | +|------|------| +| [D3D12Device](device/device.md) | DirectX 12 设备实现 | +| [D3D12CommandList](command-list/command-list.md) | 命令列表实现 | + +### 资源类型 + +| 组件 | 文档 | +|------|------| +| [D3D12Buffer](buffer/buffer.md) | GPU 缓冲区实现 | +| [D3D12Texture](texture/texture.md) | GPU 纹理实现 | + +### 命令执行 + +| 组件 | 文档 | +|------|------| +| [D3D12CommandQueue](command-queue/command-queue.md) | 命令队列实现 | +| [D3D12CommandAllocator](command-allocator/command-allocator.md) | 命令分配器 | + +### 同步原语 + +| 组件 | 文档 | +|------|------| +| [D3D12Fence](fence/fence.md) | 同步栅栏实现 | +| [D3D12SwapChain](swap-chain/swap-chain.md) | 交换链实现 | + +### 渲染状态 + +| 组件 | 文档 | +|------|------| +| [D3D12Shader](shader/shader.md) | 着色器实现 | +| [D3D12PipelineState](pipeline-state/pipeline-state.md) | 管线状态对象 | +| [D3D12Sampler](sampler/sampler.md) | 采样器实现 | +| [D3D12RootSignature](root-signature/root-signature.md) | 根签名实现 | + +### 描述符 + +| 组件 | 文档 | +|------|------| +| [D3D12DescriptorHeap](descriptor-heap/descriptor-heap.md) | 描述符堆实现 | +| [D3D12RenderTargetView](render-target-view/render-target-view.md) | 渲染目标视图 | +| [D3D12DepthStencilView](depth-stencil-view/depth-stencil-view.md) | 深度模板视图 | +| [D3D12ShaderResourceView](shader-resource-view/shader-resource-view.md) | 着色器资源视图 | +| [D3D12UnorderedAccessView](unordered-access-view/unordered-access-view.md) | 无序访问视图 | +| [D3D12ConstantBufferView](constant-buffer-view/constant-buffer-view.md) | 常量缓冲视图 | + +### 查询 + +| 组件 | 文档 | +|------|------| +| [D3D12QueryHeap](query-heap/query-heap.md) | 查询堆实现 | + +### 工具 + +| 组件 | 文档 | +|------|------| +| [D3D12Screenshot](screenshot/screenshot.md) | 截图工具 | +| [D3D12Types](types/types.md) | D3D12 类型转换 | +| [D3D12Enums](enums/enums.md) | D3D12 枚举转换 | +| [D3D12Common](common/common.md) | D3D12 公共工具函数 | + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [OpenGL 后端](../opengl/overview.md) diff --git a/docs/api/rhi/d3d12/pipeline-state/create-desc.md b/docs/api/rhi/d3d12/pipeline-state/create-desc.md new file mode 100644 index 00000000..b2e5060f --- /dev/null +++ b/docs/api/rhi/d3d12/pipeline-state/create-desc.md @@ -0,0 +1,53 @@ +# D3D12PipelineState::CreateDesc + +## 函数签名 + +```cpp +static D3D12_GRAPHICS_PIPELINE_STATE_DESC CreateDesc( + ID3D12RootSignature* rootSignature, + const D3D12_SHADER_BYTECODE& vs, + const D3D12_SHADER_BYTECODE& ps, + const D3D12_SHADER_BYTECODE& gs, + uint32_t inputElementCount, + const D3D12_INPUT_ELEMENT_DESC* inputElements) +``` + +## 中文描述 + +创建图形管线状态描述符，包含着色器和输入布局信息。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `rootSignature` | `ID3D12RootSignature*` | 根签名指针 | +| `vs` | `D3D12_SHADER_BYTECODE` | 顶点着色器字节码 | +| `ps` | `D3D12_SHADER_BYTECODE` | 像素着色器字节码 | +| `gs` | `D3D12_SHADER_BYTECODE` | 几何着色器字节码 | +| `inputElementCount` | `uint32_t` | 输入元素数量 | +| `inputElements` | `D3D12_INPUT_ELEMENT_DESC*` | 输入元素描述数组 | + +## 返回值 + +`D3D12_GRAPHICS_PIPELINE_STATE_DESC` - 管线状态描述符 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_GRAPHICS_PIPELINE_STATE_DESC psoDesc = D3D12PipelineState::CreateDesc( + rootSignature->GetRootSignature(), + vsBytecode, + psBytecode, + gsBytecode, + inputElementCount, + inputElements); +``` + +## 相关文档 + +- [D3D12PipelineState](pipeline-state.md) - 类总览 +- [D3D12PipelineState::CreateInputElement](create-input-element.md) - 创建输入元素 diff --git a/docs/api/rhi/d3d12/pipeline-state/create-input-element.md b/docs/api/rhi/d3d12/pipeline-state/create-input-element.md new file mode 100644 index 00000000..dd3999d9 --- /dev/null +++ b/docs/api/rhi/d3d12/pipeline-state/create-input-element.md @@ -0,0 +1,54 @@ +# D3D12PipelineState::CreateInputElement + +## 函数签名 + +```cpp +static D3D12_INPUT_ELEMENT_DESC CreateInputElement( + const char* semanticName, + uint32_t semanticIndex, + Format format, + uint32_t inputSlot, + uint32_t alignedByteOffset) + +static D3D12_INPUT_ELEMENT_DESC CreateInputElement( + const char* semanticName, + uint32_t semanticIndex, + Format format, + uint32_t inputSlot) +``` + +## 中文描述 + +创建输入元素描述符，用于定义顶点缓冲区的数据布局。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `semanticName` | `const char*` | 语义名称（如 "POSITION", "TEXCOORD"） | +| `semanticIndex` | `uint32_t` | 语义索引 | +| `format` | `Format` | 数据格式 | +| `inputSlot` | `uint32_t` | 输入槽位 | +| `alignedByteOffset` | `uint32_t` | 对齐字节偏移（仅第一个重载） | + +## 返回值 + +`D3D12_INPUT_ELEMENT_DESC` - 输入元素描述符 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_INPUT_ELEMENT_DESC elements[] = { + D3D12PipelineState::CreateInputElement("POSITION", 0, Format::R32G32B32_FLOAT, 0, 0), + D3D12PipelineState::CreateInputElement("TEXCOORD", 0, Format::R32G32_FLOAT, 0, 12) +}; +``` + +## 相关文档 + +- [D3D12PipelineState](pipeline-state.md) - 类总览 +- [D3D12PipelineState::CreateDesc](create-desc.md) - 创建管线描述符 diff --git a/docs/api/rhi/d3d12/pipeline-state/get-pipeline-state.md b/docs/api/rhi/d3d12/pipeline-state/get-pipeline-state.md new file mode 100644 index 00000000..c087ec7d --- /dev/null +++ b/docs/api/rhi/d3d12/pipeline-state/get-pipeline-state.md @@ -0,0 +1,29 @@ +# D3D12PipelineState::GetPipelineState + +## 函数签名 + +```cpp +ID3D12PipelineState* GetPipelineState() const +``` + +## 中文描述 + +获取底层 `ID3D12PipelineState` 接口指针。 + +## 返回值 + +`ID3D12PipelineState*` - D3D12 管线状态对象接口指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +ID3D12PipelineState* pso = pipelineState->GetPipelineState(); +``` + +## 相关文档 + +- [D3D12PipelineState](pipeline-state.md) - 类总览 diff --git a/docs/api/rhi/d3d12/pipeline-state/pipeline-state.md b/docs/api/rhi/d3d12/pipeline-state/pipeline-state.md new file mode 100644 index 00000000..cdf1c88a --- /dev/null +++ b/docs/api/rhi/d3d12/pipeline-state/pipeline-state.md @@ -0,0 +1,24 @@ +# D3D12PipelineState + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 管线状态对象的 D3D12 实现，继承自 `RHIPipelineState`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetPipelineState` | [详细文档](get-pipeline-state.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `GetType` | [详细文档](../../shader/get-type.md) | +| `Bind` | [详细文档](../../shader/bind.md) | +| `Unbind` | [详细文档](../../shader/unbind.md) | +| `CreateDesc` (static) | [详细文档](create-desc.md) | +| `CreateInputElement` (static) | [详细文档](create-input-element.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHIPipelineState](../../pipeline-state/pipeline-state.md) - 抽象管线状态接口 diff --git a/docs/api/rhi/d3d12/query-heap/get-count.md b/docs/api/rhi/d3d12/query-heap/get-count.md new file mode 100644 index 00000000..c730e8b1 --- /dev/null +++ b/docs/api/rhi/d3d12/query-heap/get-count.md @@ -0,0 +1,29 @@ +# D3D12QueryHeap::GetCount + +## 函数签名 + +```cpp +uint32_t GetCount() const +``` + +## 中文描述 + +获取查询堆中的查询数量。 + +## 返回值 + +`uint32_t` - 查询数量 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +uint32_t count = d3d12QueryHeap->GetCount(); +``` + +## 相关文档 + +- [D3D12QueryHeap](query-heap.md) - 类总览 diff --git a/docs/api/rhi/d3d12/query-heap/get-query-heap.md b/docs/api/rhi/d3d12/query-heap/get-query-heap.md new file mode 100644 index 00000000..3e37c4ed --- /dev/null +++ b/docs/api/rhi/d3d12/query-heap/get-query-heap.md @@ -0,0 +1,29 @@ +# D3D12QueryHeap::GetQueryHeap + +## 函数签名 + +```cpp +ID3D12QueryHeap* GetQueryHeap() const +``` + +## 中文描述 + +获取底层 `ID3D12QueryHeap` 接口指针。 + +## 返回值 + +`ID3D12QueryHeap*` - D3D12 查询堆接口指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +ID3D12QueryHeap* queryHeap = d3d12QueryHeap->GetQueryHeap(); +``` + +## 相关文档 + +- [D3D12QueryHeap](query-heap.md) - 类总览 diff --git a/docs/api/rhi/d3d12/query-heap/query-heap.md b/docs/api/rhi/d3d12/query-heap/query-heap.md new file mode 100644 index 00000000..54d80211 --- /dev/null +++ b/docs/api/rhi/d3d12/query-heap/query-heap.md @@ -0,0 +1,20 @@ +# D3D12QueryHeap + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 查询堆的 D3D12 实现。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetQueryHeap` | [详细文档](get-query-heap.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `GetType` | [详细文档](../../shader/get-type.md) | +| `GetCount` | [详细文档](get-count.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) diff --git a/docs/api/rhi/d3d12/render-target-view/create-desc.md b/docs/api/rhi/d3d12/render-target-view/create-desc.md new file mode 100644 index 00000000..269b94b5 --- /dev/null +++ b/docs/api/rhi/d3d12/render-target-view/create-desc.md @@ -0,0 +1,36 @@ +# D3D12RenderTargetView::CreateDesc + +## 函数签名 + +```cpp +static D3D12_RENDER_TARGET_VIEW_DESC CreateDesc(Format format, D3D12_RTV_DIMENSION dimension = D3D12_RTV_DIMENSION_TEXTURE2D) +``` + +## 中文描述 + +创建渲染目标视图描述符。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `format` | `Format` | 资源格式 | +| `dimension` | `D3D12_RTV_DIMENSION` | 视图维度（默认 TEXTURE2D） | + +## 返回值 + +`D3D12_RENDER_TARGET_VIEW_DESC` - 渲染目标视图描述符 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_RENDER_TARGET_VIEW_DESC desc = D3D12RenderTargetView::CreateDesc(Format::R8G8B8A8_UNORM); +``` + +## 相关文档 + +- [D3D12RenderTargetView](render-target-view.md) - 类总览 diff --git a/docs/api/rhi/d3d12/render-target-view/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/render-target-view/get-cpu-descriptor-handle.md new file mode 100644 index 00000000..b68c7f5f --- /dev/null +++ b/docs/api/rhi/d3d12/render-target-view/get-cpu-descriptor-handle.md @@ -0,0 +1,29 @@ +# D3D12RenderTargetView::GetCPUDescriptorHandle + +## 函数签名 + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const +``` + +## 中文描述 + +获取渲染目标视图的 CPU 描述符句柄。 + +## 返回值 + +`D3D12_CPU_DESCRIPTOR_HANDLE` - CPU 描述符句柄 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE handle = rtv->GetCPUDescriptorHandle(); +``` + +## 相关文档 + +- [D3D12RenderTargetView](render-target-view.md) - 类总览 diff --git a/docs/api/rhi/d3d12/render-target-view/initialize-at.md b/docs/api/rhi/d3d12/render-target-view/initialize-at.md new file mode 100644 index 00000000..76318609 --- /dev/null +++ b/docs/api/rhi/d3d12/render-target-view/initialize-at.md @@ -0,0 +1,40 @@ +# D3D12RenderTargetView::InitializeAt + +## 函数签名 + +```cpp +void InitializeAt(ID3D12Device* device, ID3D12Resource* resource, D3D12_CPU_DESCRIPTOR_HANDLE handle, const D3D12_RENDER_TARGET_VIEW_DESC* desc = nullptr) +``` + +## 中文描述 + +在指定描述符句柄位置初始化渲染目标视图，用于外部描述符堆管理场景。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `resource` | `ID3D12Resource*` | 资源指针 | +| `handle` | `D3D12_CPU_DESCRIPTOR_HANDLE` | 预分配的描述符句柄 | +| `desc` | `D3D12_RENDER_TARGET_VIEW_DESC*` | 视图描述符（可选） | + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE handle = descriptorHeap->GetCPUDescriptorHandleForHeapStart(); +rtv->InitializeAt(device, resource, handle); +``` + +## 相关文档 + +- [D3D12RenderTargetView](render-target-view.md) - 类总览 +- [D3D12RenderTargetView::Initialize](../../../threading/task-system/initialize.md) - 标准初始化 diff --git a/docs/api/rhi/d3d12/render-target-view/render-target-view.md b/docs/api/rhi/d3d12/render-target-view/render-target-view.md new file mode 100644 index 00000000..ca9a1546 --- /dev/null +++ b/docs/api/rhi/d3d12/render-target-view/render-target-view.md @@ -0,0 +1,19 @@ +# D3D12RenderTargetView + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 渲染目标视图的 D3D12 实现。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `InitializeAt` | [详细文档](initialize-at.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetCPUDescriptorHandle` | [详细文档](get-cpu-descriptor-handle.md) | +| `CreateDesc` (static) | [详细文档](create-desc.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) diff --git a/docs/api/rhi/d3d12/root-signature/create-32bit-constants.md b/docs/api/rhi/d3d12/root-signature/create-32bit-constants.md new file mode 100644 index 00000000..d8961a72 --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/create-32bit-constants.md @@ -0,0 +1,38 @@ +# D3D12RootSignature::Create32BitConstants + +## 函数签名 + +```cpp +static D3D12_ROOT_PARAMETER Create32BitConstants(uint32_t shaderRegister, uint32_t num32BitValues, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0) +``` + +## 中文描述 + +创建 32 位常量根参数，用于上传小量常量数据。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `shaderRegister` | `uint32_t` | 着色器寄存器编号 | +| `num32BitValues` | `uint32_t` | 32 位值的数量 | +| `visibility` | `ShaderVisibility` | 可见性（默认 All） | +| `registerSpace` | `uint32_t` | 寄存器空间（默认 0） | + +## 返回值 + +`D3D12_ROOT_PARAMETER` - 根参数 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_ROOT_PARAMETER constantsParam = D3D12RootSignature::Create32BitConstants(0, 4); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 diff --git a/docs/api/rhi/d3d12/root-signature/create-cbv.md b/docs/api/rhi/d3d12/root-signature/create-cbv.md new file mode 100644 index 00000000..b002c376 --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/create-cbv.md @@ -0,0 +1,39 @@ +# D3D12RootSignature::CreateCBV + +## 函数签名 + +```cpp +static D3D12_ROOT_PARAMETER CreateCBV(uint32_t shaderRegister, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0) +``` + +## 中文描述 + +创建常量缓冲区视图（CBV）根参数。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `shaderRegister` | `uint32_t` | 着色器寄存器编号 | +| `visibility` | `ShaderVisibility` | 可见性（默认 All） | +| `registerSpace` | `uint32_t` | 寄存器空间（默认 0） | + +## 返回值 + +`D3D12_ROOT_PARAMETER` - 根参数 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_ROOT_PARAMETER cbvParam = D3D12RootSignature::CreateCBV(0); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 +- [D3D12RootSignature::CreateSRV](create-srv.md) - 创建 SRV 根参数 +- [D3D12RootSignature::CreateUAV](create-uav.md) - 创建 UAV 根参数 diff --git a/docs/api/rhi/d3d12/root-signature/create-desc.md b/docs/api/rhi/d3d12/root-signature/create-desc.md new file mode 100644 index 00000000..96eaabc8 --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/create-desc.md @@ -0,0 +1,48 @@ +# D3D12RootSignature::CreateDesc + +## 函数签名 + +```cpp +static D3D12_ROOT_SIGNATURE_DESC CreateDesc( + D3D12_ROOT_PARAMETER* parameters, + uint32_t parameterCount, + D3D12_STATIC_SAMPLER_DESC* samplers = nullptr, + uint32_t samplerCount = 0, + D3D12_ROOT_SIGNATURE_FLAGS flags = D3D12_ROOT_SIGNATURE_FLAG_ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT) +``` + +## 中文描述 + +创建根签名描述符。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `parameters` | `D3D12_ROOT_PARAMETER*` | 根参数数组 | +| `parameterCount` | `uint32_t` | 根参数数量 | +| `samplers` | `D3D12_STATIC_SAMPLER_DESC*` | 静态采样器数组（可选） | +| `samplerCount` | `uint32_t` | 静态采样器数量 | +| `flags` | `D3D12_ROOT_SIGNATURE_FLAGS` | 根签名标志 | + +## 返回值 + +`D3D12_ROOT_SIGNATURE_DESC` - 根签名描述符 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_ROOT_SIGNATURE_DESC desc = D3D12RootSignature::CreateDesc( + parameters.data(), + parameters.size(), + samplers.data(), + samplers.size()); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 diff --git a/docs/api/rhi/d3d12/root-signature/create-descriptor-range.md b/docs/api/rhi/d3d12/root-signature/create-descriptor-range.md new file mode 100644 index 00000000..5853b140 --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/create-descriptor-range.md @@ -0,0 +1,39 @@ +# D3D12RootSignature::CreateDescriptorRange + +## 函数签名 + +```cpp +static D3D12_DESCRIPTOR_RANGE CreateDescriptorRange(D3D12_DESCRIPTOR_RANGE_TYPE type, uint32_t baseShaderRegister, uint32_t numDescriptors, uint32_t registerSpace = 0) +``` + +## 中文描述 + +创建描述符范围。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `type` | `D3D12_DESCRIPTOR_RANGE_TYPE` | 描述符范围类型 | +| `baseShaderRegister` | `uint32_t` | 基础着色器寄存器 | +| `numDescriptors` | `uint32_t` | 描述符数量 | +| `registerSpace` | `uint32_t` | 寄存器空间（默认 0） | + +## 返回值 + +`D3D12_DESCRIPTOR_RANGE` - 描述符范围 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_DESCRIPTOR_RANGE range = D3D12RootSignature::CreateDescriptorRange(D3D12_DESCRIPTOR_RANGE_TYPE_SRV, 0, 1); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 +- [D3D12RootSignature::CreateDescriptorTable](create-descriptor-table.md) - 创建描述符表 diff --git a/docs/api/rhi/d3d12/root-signature/create-descriptor-table.md b/docs/api/rhi/d3d12/root-signature/create-descriptor-table.md new file mode 100644 index 00000000..35433d04 --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/create-descriptor-table.md @@ -0,0 +1,40 @@ +# D3D12RootSignature::CreateDescriptorTable + +## 函数签名 + +```cpp +static D3D12_ROOT_PARAMETER CreateDescriptorTable(uint32_t numRanges, const D3D12_DESCRIPTOR_RANGE* ranges, ShaderVisibility visibility = ShaderVisibility::All) +``` + +## 中文描述 + +创建描述符表根参数。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `numRanges` | `uint32_t` | 描述符范围数量 | +| `ranges` | `D3D12_DESCRIPTOR_RANGE*` | 描述符范围数组 | +| `visibility` | `ShaderVisibility` | 可见性（默认 All） | + +## 返回值 + +`D3D12_ROOT_PARAMETER` - 根参数 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_DESCRIPTOR_RANGE ranges[1]; +ranges[0] = D3D12RootSignature::CreateDescriptorRange(D3D12_DESCRIPTOR_RANGE_TYPE_SRV, 0, 1); +D3D12_ROOT_PARAMETER descTable = D3D12RootSignature::CreateDescriptorTable(1, ranges); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 +- [D3D12RootSignature::CreateDescriptorRange](create-descriptor-range.md) - 创建描述符范围 diff --git a/docs/api/rhi/d3d12/root-signature/create-sampler-desc.md b/docs/api/rhi/d3d12/root-signature/create-sampler-desc.md new file mode 100644 index 00000000..bff4b574 --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/create-sampler-desc.md @@ -0,0 +1,38 @@ +# D3D12RootSignature::CreateSamplerDesc + +## 函数签名 + +```cpp +static D3D12_SAMPLER_DESC CreateSamplerDesc(FilterMode filter, TextureAddressMode address, float maxLOD = D3D12_FLOAT32_MAX) +``` + +## 中文描述 + +创建采样器描述符。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `filter` | `FilterMode` | 过滤模式 | +| `address` | `TextureAddressMode` | 寻址模式 | +| `maxLOD` | `float` | 最大 LOD（默认无限） | + +## 返回值 + +`D3D12_SAMPLER_DESC` - 采样器描述符 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_SAMPLER_DESC desc = D3D12RootSignature::CreateSamplerDesc(FilterMode::Anisotropic, TextureAddressMode::Wrap); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 +- [D3D12RootSignature::CreateStaticSampler](create-static-sampler.md) - 创建静态采样器 diff --git a/docs/api/rhi/d3d12/root-signature/create-srv.md b/docs/api/rhi/d3d12/root-signature/create-srv.md new file mode 100644 index 00000000..04a885e1 --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/create-srv.md @@ -0,0 +1,39 @@ +# D3D12RootSignature::CreateSRV + +## 函数签名 + +```cpp +static D3D12_ROOT_PARAMETER CreateSRV(uint32_t shaderRegister, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0) +``` + +## 中文描述 + +创建着色器资源视图（SRV）根参数。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `shaderRegister` | `uint32_t` | 着色器寄存器编号 | +| `visibility` | `ShaderVisibility` | 可见性（默认 All） | +| `registerSpace` | `uint32_t` | 寄存器空间（默认 0） | + +## 返回值 + +`D3D12_ROOT_PARAMETER` - 根参数 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_ROOT_PARAMETER srvParam = D3D12RootSignature::CreateSRV(0); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 +- [D3D12RootSignature::CreateCBV](create-cbv.md) - 创建 CBV 根参数 +- [D3D12RootSignature::CreateUAV](create-uav.md) - 创建 UAV 根参数 diff --git a/docs/api/rhi/d3d12/root-signature/create-static-sampler.md b/docs/api/rhi/d3d12/root-signature/create-static-sampler.md new file mode 100644 index 00000000..3b2f15e8 --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/create-static-sampler.md @@ -0,0 +1,39 @@ +# D3D12RootSignature::CreateStaticSampler + +## 函数签名 + +```cpp +static D3D12_STATIC_SAMPLER_DESC CreateStaticSampler(uint32_t shaderRegister, const D3D12_SAMPLER_DESC& desc, ShaderVisibility visibility = ShaderVisibility::Pixel) +``` + +## 中文描述 + +创建静态采样器描述符，静态采样器绑定到根签名中无需描述符堆。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `shaderRegister` | `uint32_t` | 着色器寄存器编号 | +| `desc` | `D3D12_SAMPLER_DESC` | 采样器描述符 | +| `visibility` | `ShaderVisibility` | 可见性（默认 Pixel） | + +## 返回值 + +`D3D12_STATIC_SAMPLER_DESC` - 静态采样器描述符 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_SAMPLER_DESC samplerDesc = D3D12RootSignature::CreateSamplerDesc(FilterMode::Anisotropic, TextureAddressMode::Wrap); +D3D12_STATIC_SAMPLER_DESC staticSampler = D3D12RootSignature::CreateStaticSampler(0, samplerDesc); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 +- [D3D12RootSignature::CreateSamplerDesc](create-sampler-desc.md) - 创建采样器描述符 diff --git a/docs/api/rhi/d3d12/root-signature/create-uav.md b/docs/api/rhi/d3d12/root-signature/create-uav.md new file mode 100644 index 00000000..3404f2ad --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/create-uav.md @@ -0,0 +1,39 @@ +# D3D12RootSignature::CreateUAV + +## 函数签名 + +```cpp +static D3D12_ROOT_PARAMETER CreateUAV(uint32_t shaderRegister, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0) +``` + +## 中文描述 + +创建无序访问视图（UAV）根参数。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `shaderRegister` | `uint32_t` | 着色器寄存器编号 | +| `visibility` | `ShaderVisibility` | 可见性（默认 All） | +| `registerSpace` | `uint32_t` | 寄存器空间（默认 0） | + +## 返回值 + +`D3D12_ROOT_PARAMETER` - 根参数 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_ROOT_PARAMETER uavParam = D3D12RootSignature::CreateUAV(0); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 +- [D3D12RootSignature::CreateCBV](create-cbv.md) - 创建 CBV 根参数 +- [D3D12RootSignature::CreateSRV](create-srv.md) - 创建 SRV 根参数 diff --git a/docs/api/rhi/d3d12/root-signature/get-parameter-count.md b/docs/api/rhi/d3d12/root-signature/get-parameter-count.md new file mode 100644 index 00000000..fa075ebb --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/get-parameter-count.md @@ -0,0 +1,29 @@ +# D3D12RootSignature::GetParameterCount + +## 函数签名 + +```cpp +uint32_t GetParameterCount() const +``` + +## 中文描述 + +获取根签名中根参数的数量。 + +## 返回值 + +`uint32_t` - 根参数数量 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +uint32_t count = rootSignature->GetParameterCount(); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 diff --git a/docs/api/rhi/d3d12/root-signature/get-root-signature.md b/docs/api/rhi/d3d12/root-signature/get-root-signature.md new file mode 100644 index 00000000..2273625c --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/get-root-signature.md @@ -0,0 +1,29 @@ +# D3D12RootSignature::GetRootSignature + +## 函数签名 + +```cpp +ID3D12RootSignature* GetRootSignature() const +``` + +## 中文描述 + +获取底层 `ID3D12RootSignature` 接口指针。 + +## 返回值 + +`ID3D12RootSignature*` - D3D12 根签名接口指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +ID3D12RootSignature* rs = rootSignature->GetRootSignature(); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 diff --git a/docs/api/rhi/d3d12/root-signature/root-signature.md b/docs/api/rhi/d3d12/root-signature/root-signature.md new file mode 100644 index 00000000..80ea67db --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/root-signature.md @@ -0,0 +1,28 @@ +# D3D12RootSignature + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 根签名的 D3D12 实现。**不继承 RHI 抽象接口**，是 D3D12 特有的封装类。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetRootSignature` | [详细文档](get-root-signature.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `GetParameterCount` | [详细文档](get-parameter-count.md) | +| `CreateDesc` (static) | [详细文档](create-desc.md) | +| `CreateCBV` (static) | [详细文档](create-cbv.md) | +| `CreateSRV` (static) | [详细文档](create-srv.md) | +| `CreateUAV` (static) | [详细文档](create-uav.md) | +| `Create32BitConstants` (static) | [详细文档](create-32bit-constants.md) | +| `CreateDescriptorTable` (static) | [详细文档](create-descriptor-table.md) | +| `CreateStaticSampler` (static) | [详细文档](create-static-sampler.md) | +| `CreateSamplerDesc` (static) | [详细文档](create-sampler-desc.md) | +| `CreateDescriptorRange` (static) | [详细文档](create-descriptor-range.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) diff --git a/docs/api/rhi/d3d12/sampler/get-id.md b/docs/api/rhi/d3d12/sampler/get-id.md new file mode 100644 index 00000000..aa70e34a --- /dev/null +++ b/docs/api/rhi/d3d12/sampler/get-id.md @@ -0,0 +1,29 @@ +# D3D12Sampler::GetID + +## 函数签名 + +```cpp +unsigned int GetID() override +``` + +## 中文描述 + +获取采样器唯一标识符。 + +## 返回值 + +`unsigned int` - 采样器 ID + +## 复杂度 + +O(1) + +## 示例 + +```cpp +unsigned int id = sampler->GetID(); +``` + +## 相关文档 + +- [D3D12Sampler](sampler.md) - 类总览 diff --git a/docs/api/rhi/d3d12/sampler/sampler.md b/docs/api/rhi/d3d12/sampler/sampler.md new file mode 100644 index 00000000..c3f9cc12 --- /dev/null +++ b/docs/api/rhi/d3d12/sampler/sampler.md @@ -0,0 +1,21 @@ +# D3D12Sampler + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 采样器的 D3D12 实现，继承自 `RHISampler`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetDesc` | [详细文档](../buffer/get-desc.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `GetID` | [详细文档](get-id.md) | +| `Bind` / `Unbind` | [详细文档](../../shader/bind.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHISampler](../../sampler/sampler.md) - 抽象采样器接口 diff --git a/docs/api/rhi/d3d12/screenshot/capture.md b/docs/api/rhi/d3d12/screenshot/capture.md new file mode 100644 index 00000000..2e527813 --- /dev/null +++ b/docs/api/rhi/d3d12/screenshot/capture.md @@ -0,0 +1,46 @@ +# D3D12Screenshot::Capture + +## 函数签名 + +```cpp +static bool Capture(ID3D12Device* device, + ID3D12CommandQueue* commandQueue, + ID3D12Resource* renderTarget, + const char* filename, + uint32_t width, + uint32_t height) +``` + +## 中文描述 + +从渲染目标捕获截图并保存为文件。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `commandQueue` | `ID3D12CommandQueue*` | 命令队列指针 | +| `renderTarget` | `ID3D12Resource*` | 渲染目标资源 | +| `filename` | `const char*` | 保存文件名 | +| `width` | `uint32_t` | 宽度 | +| `height` | `uint32_t` | 高度 | + +## 返回值 + +`bool` - 捕获是否成功 + +## 复杂度 + +O(n) - 取决于纹理大小 + +## 示例 + +```cpp +D3D12Screenshot::Capture(device, commandQueue, renderTarget, "screenshot.png", width, height); +``` + +## 相关文档 + +- [D3D12Screenshot](screenshot.md) - 类总览 +- [D3D12Screenshot::CopyToReadbackAndSave](copy-to-readback-and-save.md) - 复制到回读缓冲并保存 diff --git a/docs/api/rhi/d3d12/screenshot/copy-to-readback-and-save.md b/docs/api/rhi/d3d12/screenshot/copy-to-readback-and-save.md new file mode 100644 index 00000000..44f6ac49 --- /dev/null +++ b/docs/api/rhi/d3d12/screenshot/copy-to-readback-and-save.md @@ -0,0 +1,46 @@ +# D3D12Screenshot::CopyToReadbackAndSave + +## 函数签名 + +```cpp +static bool CopyToReadbackAndSave(ID3D12Device* device, + ID3D12CommandQueue* commandQueue, + ID3D12Resource* renderTarget, + const char* filename, + uint32_t width, + uint32_t height) +``` + +## 中文描述 + +复制渲染目标到回读缓冲区并保存为图片文件。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `commandQueue` | `ID3D12CommandQueue*` | 命令队列指针 | +| `renderTarget` | `ID3D12Resource*` | 渲染目标资源 | +| `filename` | `const char*` | 保存文件名 | +| `width` | `uint32_t` | 宽度 | +| `height` | `uint32_t` | 高度 | + +## 返回值 + +`bool` - 操作是否成功 + +## 复杂度 + +O(n) - 取决于纹理大小 + +## 示例 + +```cpp +D3D12Screenshot::CopyToReadbackAndSave(device, commandQueue, renderTarget, "screenshot.png", width, height); +``` + +## 相关文档 + +- [D3D12Screenshot](screenshot.md) - 类总览 +- [D3D12Screenshot::Capture](capture.md) - 捕获截图 diff --git a/docs/api/rhi/d3d12/screenshot/screenshot.md b/docs/api/rhi/d3d12/screenshot/screenshot.md new file mode 100644 index 00000000..5efc2d99 --- /dev/null +++ b/docs/api/rhi/d3d12/screenshot/screenshot.md @@ -0,0 +1,16 @@ +# D3D12Screenshot + +**命名空间**: `XCEngine::RHI` + +**描述**: D3D12 截图工具类，提供屏幕截图捕获功能。**所有方法均为静态方法**。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Capture` | [详细文档](capture.md) | +| `CopyToReadbackAndSave` | [详细文档](copy-to-readback-and-save.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) diff --git a/docs/api/rhi/d3d12/shader-resource-view/create-desc.md b/docs/api/rhi/d3d12/shader-resource-view/create-desc.md new file mode 100644 index 00000000..93b26bd7 --- /dev/null +++ b/docs/api/rhi/d3d12/shader-resource-view/create-desc.md @@ -0,0 +1,37 @@ +# D3D12ShaderResourceView::CreateDesc + +## 函数签名 + +```cpp +static D3D12_SHADER_RESOURCE_VIEW_DESC CreateDesc(Format format, D3D12_SRV_DIMENSION dimension = D3D12_SRV_DIMENSION_TEXTURE2D, uint32_t mipLevels = 1) +``` + +## 中文描述 + +创建着色器资源视图描述符。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `format` | `Format` | 资源格式 | +| `dimension` | `D3D12_SRV_DIMENSION` | 视图维度（默认 TEXTURE2D） | +| `mipLevels` | `uint32_t` | Mipmap 级别数量（默认 1） | + +## 返回值 + +`D3D12_SHADER_RESOURCE_VIEW_DESC` - 着色器资源视图描述符 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_SHADER_RESOURCE_VIEW_DESC desc = D3D12ShaderResourceView::CreateDesc(Format::R8G8B8A8_UNORM); +``` + +## 相关文档 + +- [D3D12ShaderResourceView](shader-resource-view.md) - 类总览 diff --git a/docs/api/rhi/d3d12/shader-resource-view/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/shader-resource-view/get-cpu-descriptor-handle.md new file mode 100644 index 00000000..6b07bb54 --- /dev/null +++ b/docs/api/rhi/d3d12/shader-resource-view/get-cpu-descriptor-handle.md @@ -0,0 +1,29 @@ +# D3D12ShaderResourceView::GetCPUDescriptorHandle + +## 函数签名 + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const +``` + +## 中文描述 + +获取着色器资源视图的 CPU 描述符句柄。 + +## 返回值 + +`D3D12_CPU_DESCRIPTOR_HANDLE` - CPU 描述符句柄 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE handle = srv->GetCPUDescriptorHandle(); +``` + +## 相关文档 + +- [D3D12ShaderResourceView](shader-resource-view.md) - 类总览 diff --git a/docs/api/rhi/d3d12/shader-resource-view/initialize-at.md b/docs/api/rhi/d3d12/shader-resource-view/initialize-at.md new file mode 100644 index 00000000..9746d5bd --- /dev/null +++ b/docs/api/rhi/d3d12/shader-resource-view/initialize-at.md @@ -0,0 +1,39 @@ +# D3D12ShaderResourceView::InitializeAt + +## 函数签名 + +```cpp +void InitializeAt(ID3D12Device* device, ID3D12Resource* resource, D3D12_CPU_DESCRIPTOR_HANDLE handle, const D3D12_SHADER_RESOURCE_VIEW_DESC* desc = nullptr) +``` + +## 中文描述 + +在指定描述符句柄位置初始化着色器资源视图，用于外部描述符堆管理场景。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `resource` | `ID3D12Resource*` | 资源指针 | +| `handle` | `D3D12_CPU_DESCRIPTOR_HANDLE` | 预分配的描述符句柄 | +| `desc` | `D3D12_SHADER_RESOURCE_VIEW_DESC*` | 视图描述符（可选） | + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE handle = descriptorHeap->GetCPUDescriptorHandleForHeapStart(); +srv->InitializeAt(device, resource, handle); +``` + +## 相关文档 + +- [D3D12ShaderResourceView](shader-resource-view.md) - 类总览 diff --git a/docs/api/rhi/d3d12/shader-resource-view/shader-resource-view.md b/docs/api/rhi/d3d12/shader-resource-view/shader-resource-view.md new file mode 100644 index 00000000..3824e1a9 --- /dev/null +++ b/docs/api/rhi/d3d12/shader-resource-view/shader-resource-view.md @@ -0,0 +1,19 @@ +# D3D12ShaderResourceView + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 着色器资源视图的 D3D12 实现。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `InitializeAt` | [详细文档](initialize-at.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetCPUDescriptorHandle` | [详细文档](get-cpu-descriptor-handle.md) | +| `CreateDesc` (static) | [详细文档](create-desc.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) diff --git a/docs/api/rhi/d3d12/shader/get-bytecode-size.md b/docs/api/rhi/d3d12/shader/get-bytecode-size.md new file mode 100644 index 00000000..8c6b7947 --- /dev/null +++ b/docs/api/rhi/d3d12/shader/get-bytecode-size.md @@ -0,0 +1,30 @@ +# D3D12Shader::GetBytecodeSize + +## 函数签名 + +```cpp +size_t GetBytecodeSize() const +``` + +## 中文描述 + +获取着色器字节码大小。 + +## 返回值 + +`size_t` - 字节码大小（字节） + +## 复杂度 + +O(1) + +## 示例 + +```cpp +size_t size = shader->GetBytecodeSize(); +``` + +## 相关文档 + +- [D3D12Shader](shader.md) - 类总览 +- [D3D12Shader::GetBytecode](get-bytecode.md) - 获取字节码数据 diff --git a/docs/api/rhi/d3d12/shader/get-bytecode.md b/docs/api/rhi/d3d12/shader/get-bytecode.md new file mode 100644 index 00000000..fe2cd8ec --- /dev/null +++ b/docs/api/rhi/d3d12/shader/get-bytecode.md @@ -0,0 +1,30 @@ +# D3D12Shader::GetBytecode + +## 函数签名 + +```cpp +const void* GetBytecode() const +``` + +## 中文描述 + +获取着色器字节码数据指针。 + +## 返回值 + +`const void*` - 字节码数据指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +const void* bytecode = shader->GetBytecode(); +``` + +## 相关文档 + +- [D3D12Shader](shader.md) - 类总览 +- [D3D12Shader::GetBytecodeSize](get-bytecode-size.md) - 获取字节码大小 diff --git a/docs/api/rhi/d3d12/shader/get-d3d12-bytecode.md b/docs/api/rhi/d3d12/shader/get-d3d12-bytecode.md new file mode 100644 index 00000000..832a410d --- /dev/null +++ b/docs/api/rhi/d3d12/shader/get-d3d12-bytecode.md @@ -0,0 +1,29 @@ +# D3D12Shader::GetD3D12Bytecode + +## 函数签名 + +```cpp +const D3D12_SHADER_BYTECODE GetD3D12Bytecode() const +``` + +## 中文描述 + +获取 D3D12 着色器字节码结构。 + +## 返回值 + +`D3D12_SHADER_BYTECODE` - D3D12 着色器字节码结构 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_SHADER_BYTECODE bytecode = shader->GetD3D12Bytecode(); +``` + +## 相关文档 + +- [D3D12Shader](shader.md) - 类总览 diff --git a/docs/api/rhi/d3d12/shader/get-input-layout.md b/docs/api/rhi/d3d12/shader/get-input-layout.md new file mode 100644 index 00000000..94a33bb2 --- /dev/null +++ b/docs/api/rhi/d3d12/shader/get-input-layout.md @@ -0,0 +1,29 @@ +# D3D12Shader::GetInputLayout + +## 函数签名 + +```cpp +const InputLayoutDesc& GetInputLayout() const +``` + +## 中文描述 + +获取着色器输入布局描述。 + +## 返回值 + +`const InputLayoutDesc&` - 输入布局描述引用 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +const InputLayoutDesc& layout = shader->GetInputLayout(); +``` + +## 相关文档 + +- [D3D12Shader](shader.md) - 类总览 diff --git a/docs/api/rhi/d3d12/shader/set-uniforms.md b/docs/api/rhi/d3d12/shader/set-uniforms.md new file mode 100644 index 00000000..bf04a346 --- /dev/null +++ b/docs/api/rhi/d3d12/shader/set-uniforms.md @@ -0,0 +1,46 @@ +# D3D12Shader::SetUniforms + +## 函数签名 + +```cpp +void SetInt(const char* name, int value) override +void SetFloat(const char* name, float value) override +void SetVec3(const char* name, float x, float y, float z) override +void SetVec4(const char* name, float x, float y, float z, float w) override +void SetMat4(const char* name, const float* value) override +``` + +## 中文描述 + +设置着色器 uniform 变量。当前实现为空（stub）。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `name` | `const char*` | 变量名称 | +| `value` | 各种类型 | 变量值 | +| `x, y, z, w` | `float` | 向量分量 | +| `value` | `const float*` | 矩阵数据指针 | + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +shader->SetInt("useLighting", 1); +shader->SetFloat("scale", 2.0f); +shader->SetVec3("lightPos", 1.0f, 2.0f, 3.0f); +shader->SetVec4("color", 1.0f, 0.0f, 0.0f, 1.0f); +shader->SetMat4("transform", matrixData); +``` + +## 相关文档 + +- [D3D12Shader](shader.md) - 类总览 diff --git a/docs/api/rhi/d3d12/shader/shader.md b/docs/api/rhi/d3d12/shader/shader.md new file mode 100644 index 00000000..4fab3dbf --- /dev/null +++ b/docs/api/rhi/d3d12/shader/shader.md @@ -0,0 +1,27 @@ +# D3D12Shader + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 着色器的 D3D12 实现，继承自 `RHIShader`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `CompileFromFile` | [详细文档](../../shader/compile-from-file.md) | +| `Compile` | [详细文档](../../shader/compile.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetD3D12Bytecode` | [详细文档](get-d3d12-bytecode.md) | +| `GetBytecode` | [详细文档](get-bytecode.md) | +| `GetBytecodeSize` | [详细文档](get-bytecode-size.md) | +| `GetType` | [详细文档](../../shader/get-type.md) | +| `GetInputLayout` | [详细文档](get-input-layout.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `IsValid` | [详细文档](../../shader/is-valid.md) | +| `Bind` / `Unbind` | [详细文档](../../shader/bind.md) | +| `SetInt` / `SetFloat` / `SetVec3` / `SetVec4` / `SetMat4` | [详细文档](set-uniforms.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHIShader](../../shader/shader.md) - 抽象着色器接口 diff --git a/docs/api/rhi/d3d12/swap-chain/get-back-buffer.md b/docs/api/rhi/d3d12/swap-chain/get-back-buffer.md new file mode 100644 index 00000000..9916688e --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/get-back-buffer.md @@ -0,0 +1,35 @@ +# D3D12SwapChain::GetBackBuffer + +## 函数签名 + +```cpp +D3D12Texture* GetBackBuffer(uint32_t index) const +``` + +## 中文描述 + +获取指定索引的后台缓冲区。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `index` | `uint32_t` | 缓冲区索引 | + +## 返回值 + +`D3D12Texture*` - 后台缓冲区纹理指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12Texture* buffer = swapChain->GetBackBuffer(0); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 diff --git a/docs/api/rhi/d3d12/swap-chain/get-current-back-buffer-index.md b/docs/api/rhi/d3d12/swap-chain/get-current-back-buffer-index.md new file mode 100644 index 00000000..d8179a94 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/get-current-back-buffer-index.md @@ -0,0 +1,30 @@ +# D3D12SwapChain::GetCurrentBackBufferIndex + +## 函数签名 + +```cpp +uint32_t GetCurrentBackBufferIndex() const override +``` + +## 中文描述 + +获取当前后台缓冲区的索引。 + +## 返回值 + +`uint32_t` - 当前后台缓冲区索引 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +uint32_t index = swapChain->GetCurrentBackBufferIndex(); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [D3D12SwapChain::GetCurrentBackBuffer](get-current-back-buffer.md) - 获取当前后台缓冲区 diff --git a/docs/api/rhi/d3d12/swap-chain/get-current-back-buffer.md b/docs/api/rhi/d3d12/swap-chain/get-current-back-buffer.md new file mode 100644 index 00000000..56b92e08 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/get-current-back-buffer.md @@ -0,0 +1,30 @@ +# D3D12SwapChain::GetCurrentBackBuffer + +## 函数签名 + +```cpp +RHITexture* GetCurrentBackBuffer() override +``` + +## 中文描述 + +获取当前后台缓冲区纹理。 + +## 返回值 + +`RHITexture*` - 当前后台缓冲区纹理指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +RHITexture* backBuffer = swapChain->GetCurrentBackBuffer(); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [D3D12SwapChain::GetCurrentBackBufferIndex](get-current-back-buffer-index.md) - 获取当前缓冲区索引 diff --git a/docs/api/rhi/d3d12/swap-chain/get-swap-chain.md b/docs/api/rhi/d3d12/swap-chain/get-swap-chain.md new file mode 100644 index 00000000..83a6f812 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/get-swap-chain.md @@ -0,0 +1,29 @@ +# D3D12SwapChain::GetSwapChain + +## 函数签名 + +```cpp +IDXGISwapChain3* GetSwapChain() const +``` + +## 中文描述 + +获取底层 `IDXGISwapChain3` 接口指针。 + +## 返回值 + +`IDXGISwapChain3*` - DXGI 交换链接口指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +IDXGISwapChain3* swapChain = d3d12SwapChain->GetSwapChain(); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 diff --git a/docs/api/rhi/d3d12/swap-chain/initialize-from-swapchain.md b/docs/api/rhi/d3d12/swap-chain/initialize-from-swapchain.md new file mode 100644 index 00000000..3e9d1116 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/initialize-from-swapchain.md @@ -0,0 +1,40 @@ +# D3D12SwapChain::Initialize + +## 函数签名 + +```cpp +bool Initialize(IDXGIFactory4* factory, ID3D12CommandQueue* commandQueue, HWND windowHandle, uint32_t width, uint32_t height, uint32_t bufferCount = 2) +``` + +## 中文描述 + +从工厂创建新的交换链。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `factory` | `IDXGIFactory4*` | DXGI 工厂指针 | +| `commandQueue` | `ID3D12CommandQueue*` | 命令队列指针 | +| `windowHandle` | `HWND` | 窗口句柄 | +| `width` | `uint32_t` | 宽度 | +| `height` | `uint32_t` | 高度 | +| `bufferCount` | `uint32_t` | 缓冲区数量（默认 2） | + +## 返回值 + +`bool` - 初始化是否成功 + +## 复杂度 + +O(n) - 取决于缓冲区数量和大小 + +## 示例 + +```cpp +swapChain->Initialize(factory, commandQueue, hwnd, 1920, 1080, 2); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 diff --git a/docs/api/rhi/d3d12/swap-chain/is-fullscreen.md b/docs/api/rhi/d3d12/swap-chain/is-fullscreen.md new file mode 100644 index 00000000..4fc3db1c --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/is-fullscreen.md @@ -0,0 +1,32 @@ +# D3D12SwapChain::IsFullscreen + +## 函数签名 + +```cpp +bool IsFullscreen() const override +``` + +## 中文描述 + +检查交换链是否处于全屏模式。 + +## 返回值 + +`bool` - 如果全屏则返回 `true` + +## 复杂度 + +O(1) + +## 示例 + +```cpp +if (swapChain->IsFullscreen()) { + // 全屏模式 +} +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [D3D12SwapChain::SetFullscreen](set-fullscreen.md) - 设置全屏模式 diff --git a/docs/api/rhi/d3d12/swap-chain/poll-events.md b/docs/api/rhi/d3d12/swap-chain/poll-events.md new file mode 100644 index 00000000..230908b7 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/poll-events.md @@ -0,0 +1,29 @@ +# D3D12SwapChain::PollEvents + +## 函数签名 + +```cpp +void PollEvents() override +``` + +## 中文描述 + +处理窗口消息队列中的事件。 + +## 返回值 + +无 + +## 复杂度 + +O(n) - 取决于待处理事件数量 + +## 示例 + +```cpp +swapChain->PollEvents(); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 diff --git a/docs/api/rhi/d3d12/swap-chain/present.md b/docs/api/rhi/d3d12/swap-chain/present.md new file mode 100644 index 00000000..c5ebef68 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/present.md @@ -0,0 +1,36 @@ +# D3D12SwapChain::Present + +## 函数签名 + +```cpp +void Present(uint32_t syncInterval = 1, uint32_t flags = 0) override +``` + +## 中文描述 + +呈现后台缓冲区内容到屏幕。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `syncInterval` | `uint32_t` | 垂直同步间隔（默认 1） | +| `flags` | `uint32_t` | 呈现标志（默认 0） | + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +swapChain->Present(1, 0); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 diff --git a/docs/api/rhi/d3d12/swap-chain/set-fullscreen.md b/docs/api/rhi/d3d12/swap-chain/set-fullscreen.md new file mode 100644 index 00000000..56e7d35d --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/set-fullscreen.md @@ -0,0 +1,36 @@ +# D3D12SwapChain::SetFullscreen + +## 函数签名 + +```cpp +void SetFullscreen(bool fullscreen) override +``` + +## 中文描述 + +设置全屏模式。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `fullscreen` | `bool` | 是否全屏 | + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +swapChain->SetFullscreen(true); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [D3D12SwapChain::IsFullscreen](is-fullscreen.md) - 检查全屏状态 diff --git a/docs/api/rhi/d3d12/swap-chain/set-should-close.md b/docs/api/rhi/d3d12/swap-chain/set-should-close.md new file mode 100644 index 00000000..e14196e6 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/set-should-close.md @@ -0,0 +1,36 @@ +# D3D12SwapChain::SetShouldClose + +## 函数签名 + +```cpp +void SetShouldClose(bool shouldClose) override +``` + +## 中文描述 + +设置窗口关闭标志。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `shouldClose` | `bool` | 是否应该关闭 | + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +swapChain->SetShouldClose(true); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [D3D12SwapChain::ShouldClose](should-close.md) - 检查关闭标志 diff --git a/docs/api/rhi/d3d12/swap-chain/should-close.md b/docs/api/rhi/d3d12/swap-chain/should-close.md new file mode 100644 index 00000000..9f4beed3 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/should-close.md @@ -0,0 +1,32 @@ +# D3D12SwapChain::ShouldClose + +## 函数签名 + +```cpp +bool ShouldClose() const override +``` + +## 中文描述 + +检查窗口是否应该关闭（如收到 WM_CLOSE 消息）。 + +## 返回值 + +`bool` - 如果应该关闭则返回 `true` + +## 复杂度 + +O(1) + +## 示例 + +```cpp +if (swapChain->ShouldClose()) { + // 处理关闭 +} +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [D3D12SwapChain::SetShouldClose](set-should-close.md) - 设置关闭标志 diff --git a/docs/api/rhi/d3d12/swap-chain/swap-chain.md b/docs/api/rhi/d3d12/swap-chain/swap-chain.md new file mode 100644 index 00000000..e2f34086 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/swap-chain.md @@ -0,0 +1,30 @@ +# D3D12SwapChain + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 交换链的 D3D12 实现，继承自 `RHISwapChain`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` (from factory) | [详细文档](../../../threading/task-system/initialize.md) | +| `Initialize` (from swapchain) | [详细文档](initialize-from-swapchain.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetCurrentBackBufferIndex` | [详细文档](get-current-back-buffer-index.md) | +| `GetCurrentBackBuffer` | [详细文档](get-current-back-buffer.md) | +| `GetBackBuffer` | [详细文档](get-back-buffer.md) | +| `Present` | [详细文档](present.md) | +| `Resize` | [详细文档](../../../containers/array/resize.md) | +| `SetFullscreen` | [详细文档](set-fullscreen.md) | +| `IsFullscreen` | [详细文档](is-fullscreen.md) | +| `ShouldClose` | [详细文档](should-close.md) | +| `SetShouldClose` | [详细文档](set-should-close.md) | +| `PollEvents` | [详细文档](poll-events.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `GetSwapChain` | [详细文档](get-swap-chain.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHISwapChain](../../swap-chain/swap-chain.md) - 抽象交换链接口 diff --git a/docs/api/rhi/d3d12/texture/get-array-size.md b/docs/api/rhi/d3d12/texture/get-array-size.md new file mode 100644 index 00000000..28975607 --- /dev/null +++ b/docs/api/rhi/d3d12/texture/get-array-size.md @@ -0,0 +1,29 @@ +# D3D12Texture::GetArraySize + +## 函数签名 + +```cpp +uint32_t GetArraySize() const +``` + +## 中文描述 + +获取纹理数组大小。对于非数组纹理，返回 1。 + +## 返回值 + +`uint32_t` - 数组大小 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +uint32_t arraySize = texture->GetArraySize(); +``` + +## 相关文档 + +- [D3D12Texture](texture.md) - 类总览 diff --git a/docs/api/rhi/d3d12/texture/initialize-depth-stencil.md b/docs/api/rhi/d3d12/texture/initialize-depth-stencil.md new file mode 100644 index 00000000..d454283c --- /dev/null +++ b/docs/api/rhi/d3d12/texture/initialize-depth-stencil.md @@ -0,0 +1,38 @@ +# D3D12Texture::InitializeDepthStencil + +## 函数签名 + +```cpp +bool InitializeDepthStencil(ID3D12Device* device, uint32_t width, uint32_t height, DXGI_FORMAT format = DXGI_FORMAT_D24_UNORM_S8_UINT) +``` + +## 中文描述 + +初始化深度模板纹理。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `width` | `uint32_t` | 纹理宽度 | +| `height` | `uint32_t` | 纹理高度 | +| `format` | `DXGI_FORMAT` | 深度格式（默认 D24_UNORM_S8_UINT） | + +## 返回值 + +`bool` - 初始化是否成功 + +## 复杂度 + +O(n) - 取决于纹理大小 + +## 示例 + +```cpp +texture->InitializeDepthStencil(device, 1920, 1080); +``` + +## 相关文档 + +- [D3D12Texture](texture.md) - 类总览 diff --git a/docs/api/rhi/d3d12/texture/initialize-from-data.md b/docs/api/rhi/d3d12/texture/initialize-from-data.md new file mode 100644 index 00000000..393ddce6 --- /dev/null +++ b/docs/api/rhi/d3d12/texture/initialize-from-data.md @@ -0,0 +1,42 @@ +# D3D12Texture::InitializeFromData + +## 函数签名 + +```cpp +bool InitializeFromData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, + const void* pixelData, uint32_t width, uint32_t height, DXGI_FORMAT format) +``` + +## 中文描述 + +从像素数据初始化纹理，内部会创建上传堆并复制数据。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `commandList` | `ID3D12GraphicsCommandList*` | 命令列表指针 | +| `pixelData` | `const void*` | 像素数据指针 | +| `width` | `uint32_t` | 纹理宽度 | +| `height` | `uint32_t` | 纹理高度 | +| `format` | `DXGI_FORMAT` | 像素格式 | + +## 返回值 + +`bool` - 初始化是否成功 + +## 复杂度 + +O(n) - 取决于纹理大小，内部创建临时上传堆 + +## 示例 + +```cpp +std::vector pixels = LoadImage("texture.png"); +texture->InitializeFromData(device, cmdList, pixels.data(), width, height, DXGI_FORMAT_R8G8B8A8_UNORM); +``` + +## 相关文档 + +- [D3D12Texture](texture.md) - 类总览 diff --git a/docs/api/rhi/d3d12/texture/texture.md b/docs/api/rhi/d3d12/texture/texture.md new file mode 100644 index 00000000..13d59713 --- /dev/null +++ b/docs/api/rhi/d3d12/texture/texture.md @@ -0,0 +1,34 @@ +# D3D12Texture + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 纹理的 D3D12 实现，继承自 `RHITexture`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `InitializeFromExisting` | [详细文档](../buffer/initialize-from-existing.md) | +| `InitializeFromData` | [详细文档](initialize-from-data.md) | +| `InitializeDepthStencil` | [详细文档](initialize-depth-stencil.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetResource` | [详细文档](../buffer/get-resource.md) | +| `GetDesc` | [详细文档](../buffer/get-desc.md) | +| `GetWidth` | [详细文档](../../texture/get-width.md) | +| `GetHeight` | [详细文档](../../texture/get-height.md) | +| `GetDepth` | [详细文档](../../texture/get-depth.md) | +| `GetMipLevels` | [详细文档](../../texture/get-mip-levels.md) | +| `GetArraySize` | [详细文档](get-array-size.md) | +| `GetGPUAddress` | [详细文档](../buffer/get-gpu-address.md) | +| `GetSize` | [详细文档](../../buffer/get-size.md) | +| `GetName` / `SetName` | [详细文档](../../buffer/get-name.md) | +| `GetFormat` | [详细文档](../../texture/get-format.md) | +| `GetTextureType` | [详细文档](../../texture/get-texture-type.md) | +| `GetState` / `SetState` | [详细文档](../../buffer/get-state.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [RHITexture](../../texture/texture.md) - 抽象纹理接口 diff --git a/docs/api/rhi/d3d12/types/to-d3d12-buffer-desc.md b/docs/api/rhi/d3d12/types/to-d3d12-buffer-desc.md new file mode 100644 index 00000000..f5e09f42 --- /dev/null +++ b/docs/api/rhi/d3d12/types/to-d3d12-buffer-desc.md @@ -0,0 +1,36 @@ +# ToD3D12(BufferDesc) + +## 函数签名 + +```cpp +inline D3D12_RESOURCE_DESC ToD3D12(const BufferDesc& desc) +``` + +## 中文描述 + +将 RHI BufferDesc 转换为 D3D12_RESOURCE_DESC。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `desc` | `const BufferDesc&` | RHI 缓冲区描述引用 | + +## 返回值 + +`D3D12_RESOURCE_DESC` - D3D12 资源描述结构 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +BufferDesc bd = { 1024 }; +D3D12_RESOURCE_DESC d3d12Desc = ToD3D12(bd); +``` + +## 相关文档 + +- [D3D12Types](types.md) - 类型总览 diff --git a/docs/api/rhi/d3d12/types/to-d3d12-clear-value.md b/docs/api/rhi/d3d12/types/to-d3d12-clear-value.md new file mode 100644 index 00000000..c46bd790 --- /dev/null +++ b/docs/api/rhi/d3d12/types/to-d3d12-clear-value.md @@ -0,0 +1,37 @@ +# ToD3D12(ClearValue) + +## 函数签名 + +```cpp +inline D3D12_CLEAR_VALUE ToD3D12(const ClearValue& clearValue, D3D12_RESOURCE_FLAGS flags = D3D12_RESOURCE_FLAG_NONE) +``` + +## 中文描述 + +将 RHI ClearValue 转换为 D3D12_CLEAR_VALUE。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `clearValue` | `const ClearValue&` | RHI ClearValue 引用 | +| `flags` | `D3D12_RESOURCE_FLAGS` | 资源标志（默认 NONE） | + +## 返回值 + +`D3D12_CLEAR_VALUE` - D3D12 清除值结构 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +ClearValue cv = { { 0.0f, 0.0f, 0.0f, 1.0f } }; +D3D12_CLEAR_VALUE d3d12CV = ToD3D12(cv); +``` + +## 相关文档 + +- [D3D12Types](types.md) - 类型总览 diff --git a/docs/api/rhi/d3d12/types/to-d3d12-command-queue-desc.md b/docs/api/rhi/d3d12/types/to-d3d12-command-queue-desc.md new file mode 100644 index 00000000..4803e3ad --- /dev/null +++ b/docs/api/rhi/d3d12/types/to-d3d12-command-queue-desc.md @@ -0,0 +1,36 @@ +# ToD3D12(CommandQueueDesc) + +## 函数签名 + +```cpp +inline D3D12_COMMAND_QUEUE_DESC ToD3D12(const CommandQueueDesc& desc) +``` + +## 中文描述 + +将 RHI CommandQueueDesc 转换为 D3D12_COMMAND_QUEUE_DESC。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `desc` | `const CommandQueueDesc&` | RHI 命令队列描述引用 | + +## 返回值 + +`D3D12_COMMAND_QUEUE_DESC` - D3D12 命令队列描述结构 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +CommandQueueDesc cqd = { CommandQueueType::Graphics }; +D3D12_COMMAND_QUEUE_DESC d3d12Desc = ToD3D12(cqd); +``` + +## 相关文档 + +- [D3D12Types](types.md) - 类型总览 diff --git a/docs/api/rhi/d3d12/types/to-d3d12-depth-stencil.md b/docs/api/rhi/d3d12/types/to-d3d12-depth-stencil.md new file mode 100644 index 00000000..80b8085c --- /dev/null +++ b/docs/api/rhi/d3d12/types/to-d3d12-depth-stencil.md @@ -0,0 +1,37 @@ +# ToD3D12DepthStencil + +## 函数签名 + +```cpp +inline D3D12_CLEAR_VALUE ToD3D12DepthStencil(const ClearValue& clearValue, DXGI_FORMAT format) +``` + +## 中文描述 + +将 RHI ClearValue 转换为 D3D12 深度模板清除值。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `clearValue` | `const ClearValue&` | RHI ClearValue 引用 | +| `format` | `DXGI_FORMAT` | 深度格式 | + +## 返回值 + +`D3D12_CLEAR_VALUE` - D3D12 清除值结构 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +ClearValue cv = { 1.0f, 0 }; +D3D12_CLEAR_VALUE d3d12CV = ToD3D12DepthStencil(cv, DXGI_FORMAT_D24_UNORM_S8_UINT); +``` + +## 相关文档 + +- [D3D12Types](types.md) - 类型总览 diff --git a/docs/api/rhi/d3d12/types/to-d3d12-descriptor-heap-desc.md b/docs/api/rhi/d3d12/types/to-d3d12-descriptor-heap-desc.md new file mode 100644 index 00000000..1eb2baea --- /dev/null +++ b/docs/api/rhi/d3d12/types/to-d3d12-descriptor-heap-desc.md @@ -0,0 +1,36 @@ +# ToD3D12(DescriptorHeapDesc) + +## 函数签名 + +```cpp +inline D3D12_DESCRIPTOR_HEAP_DESC ToD3D12(const DescriptorHeapDesc& desc) +``` + +## 中文描述 + +将 RHI DescriptorHeapDesc 转换为 D3D12_DESCRIPTOR_HEAP_DESC。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `desc` | `const DescriptorHeapDesc&` | RHI 描述符堆描述引用 | + +## 返回值 + +`D3D12_DESCRIPTOR_HEAP_DESC` - D3D12 描述符堆描述结构 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +DescriptorHeapDesc dhd = { DescriptorHeapType::CBV_SRV_UAV, 100 }; +D3D12_DESCRIPTOR_HEAP_DESC d3d12Desc = ToD3D12(dhd); +``` + +## 相关文档 + +- [D3D12Types](types.md) - 类型总览 diff --git a/docs/api/rhi/d3d12/types/to-d3d12-heap-properties.md b/docs/api/rhi/d3d12/types/to-d3d12-heap-properties.md new file mode 100644 index 00000000..ec0a02a8 --- /dev/null +++ b/docs/api/rhi/d3d12/types/to-d3d12-heap-properties.md @@ -0,0 +1,36 @@ +# ToD3D12HeapProperties + +## 函数签名 + +```cpp +inline D3D12_HEAP_PROPERTIES ToD3D12HeapProperties(D3D12_HEAP_TYPE heapType, UINT nodeMask = 0) +``` + +## 中文描述 + +将 D3D12_HEAP_TYPE 转换为 D3D12_HEAP_PROPERTIES。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `heapType` | `D3D12_HEAP_TYPE` | D3D12 堆类型 | +| `nodeMask` | `UINT` | 节点掩码（默认 0） | + +## 返回值 + +`D3D12_HEAP_PROPERTIES` - D3D12 堆属性结构 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_HEAP_PROPERTIES props = ToD3D12HeapProperties(D3D12_HEAP_TYPE_DEFAULT); +``` + +## 相关文档 + +- [D3D12Types](types.md) - 类型总览 diff --git a/docs/api/rhi/d3d12/types/to-d3d12-rect.md b/docs/api/rhi/d3d12/types/to-d3d12-rect.md new file mode 100644 index 00000000..9eb004ec --- /dev/null +++ b/docs/api/rhi/d3d12/types/to-d3d12-rect.md @@ -0,0 +1,36 @@ +# ToD3D12(Rect) + +## 函数签名 + +```cpp +inline D3D12_RECT ToD3D12(const Rect& rect) +``` + +## 中文描述 + +将 RHI Rect 转换为 D3D12_RECT。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `rect` | `const Rect&` | RHI Rect 引用 | + +## 返回值 + +`D3D12_RECT` - D3D12 矩形结构 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +Rect r = { 0, 0, 1920, 1080 }; +D3D12_RECT d3d12Rect = ToD3D12(r); +``` + +## 相关文档 + +- [D3D12Types](types.md) - 类型总览 diff --git a/docs/api/rhi/d3d12/types/to-d3d12-texture-desc.md b/docs/api/rhi/d3d12/types/to-d3d12-texture-desc.md new file mode 100644 index 00000000..ef9320e0 --- /dev/null +++ b/docs/api/rhi/d3d12/types/to-d3d12-texture-desc.md @@ -0,0 +1,36 @@ +# ToD3D12(TextureDesc) + +## 函数签名 + +```cpp +inline D3D12_RESOURCE_DESC ToD3D12(const TextureDesc& desc) +``` + +## 中文描述 + +将 RHI TextureDesc 转换为 D3D12_RESOURCE_DESC。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `desc` | `const TextureDesc&` | RHI 纹理描述引用 | + +## 返回值 + +`D3D12_RESOURCE_DESC` - D3D12 资源描述结构 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +TextureDesc td = { TextureType::Texture2D, 1920, 1080, 1, Format::R8G8B8A8_UNORM }; +D3D12_RESOURCE_DESC d3d12Desc = ToD3D12(td); +``` + +## 相关文档 + +- [D3D12Types](types.md) - 类型总览 diff --git a/docs/api/rhi/d3d12/types/to-d3d12-viewport.md b/docs/api/rhi/d3d12/types/to-d3d12-viewport.md new file mode 100644 index 00000000..95a53026 --- /dev/null +++ b/docs/api/rhi/d3d12/types/to-d3d12-viewport.md @@ -0,0 +1,36 @@ +# ToD3D12(Viewport) + +## 函数签名 + +```cpp +inline D3D12_VIEWPORT ToD3D12(const Viewport& vp) +``` + +## 中文描述 + +将 RHI Viewport 转换为 D3D12_VIEWPORT。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `vp` | `const Viewport&` | RHI Viewport 引用 | + +## 返回值 + +`D3D12_VIEWPORT` - D3D12 视口结构 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +Viewport vp = { 0, 0, 1920, 1080, 0.0f, 1.0f }; +D3D12_VIEWPORT d3d12Vp = ToD3D12(vp); +``` + +## 相关文档 + +- [D3D12Types](types.md) - 类型总览 diff --git a/docs/api/rhi/d3d12/types/types.md b/docs/api/rhi/d3d12/types/types.md new file mode 100644 index 00000000..38ae1b85 --- /dev/null +++ b/docs/api/rhi/d3d12/types/types.md @@ -0,0 +1,24 @@ +# D3D12Types + +**命名空间**: `XCEngine::RHI` + +**描述**: D3D12 类型转换和辅助函数集合，提供 RHI 抽象类型到 D3D12 类型的转换。**所有函数均为 inline 函数**。 + +## 转换函数列表 + +| 函数 | 文档 | +|------|------| +| `ToD3D12(Viewport)` | [详细文档](to-d3d12-viewport.md) | +| `ToD3D12(Rect)` | [详细文档](to-d3d12-rect.md) | +| `ToD3D12(ClearValue)` | [详细文档](to-d3d12-clear-value.md) | +| `ToD3D12DepthStencil` | [详细文档](to-d3d12-depth-stencil.md) | +| `ToD3D12(TextureDesc)` | [详细文档](to-d3d12-texture-desc.md) | +| `ToD3D12(BufferDesc)` | [详细文档](to-d3d12-buffer-desc.md) | +| `ToD3D12(DescriptorHeapDesc)` | [详细文档](to-d3d12-descriptor-heap-desc.md) | +| `ToD3D12(CommandQueueDesc)` | [详细文档](to-d3d12-command-queue-desc.md) | +| `ToD3D12HeapProperties` | [详细文档](to-d3d12-heap-properties.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) +- [D3D12Enum](../../enums/enums.md) - 枚举值转换 diff --git a/docs/api/rhi/d3d12/unordered-access-view/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/unordered-access-view/get-cpu-descriptor-handle.md new file mode 100644 index 00000000..105b13da --- /dev/null +++ b/docs/api/rhi/d3d12/unordered-access-view/get-cpu-descriptor-handle.md @@ -0,0 +1,29 @@ +# D3D12UnorderedAccessView::GetCPUDescriptorHandle + +## 函数签名 + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const +``` + +## 中文描述 + +获取无序访问视图的 CPU 描述符句柄。 + +## 返回值 + +`D3D12_CPU_DESCRIPTOR_HANDLE` - CPU 描述符句柄 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE handle = uav->GetCPUDescriptorHandle(); +``` + +## 相关文档 + +- [D3D12UnorderedAccessView](unordered-access-view.md) - 类总览 diff --git a/docs/api/rhi/d3d12/unordered-access-view/unordered-access-view.md b/docs/api/rhi/d3d12/unordered-access-view/unordered-access-view.md new file mode 100644 index 00000000..98f7e743 --- /dev/null +++ b/docs/api/rhi/d3d12/unordered-access-view/unordered-access-view.md @@ -0,0 +1,17 @@ +# D3D12UnorderedAccessView + +**命名空间**: `XCEngine::RHI` + +**描述**: DirectX 12 无序访问视图的 D3D12 实现。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `GetCPUDescriptorHandle` | [详细文档](get-cpu-descriptor-handle.md) | + +## 相关文档 + +- [D3D12 后端总览](../overview.md) diff --git a/docs/api/rhi/descriptor-pool/descriptor-pool.md b/docs/api/rhi/descriptor-pool/descriptor-pool.md new file mode 100644 index 00000000..b3ffd328 --- /dev/null +++ b/docs/api/rhi/descriptor-pool/descriptor-pool.md @@ -0,0 +1,29 @@ +# RHIDescriptorPool + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: GPU 描述符堆池抽象接口，用于管理 GPU 描述符的分配和回收。 + +## 公共方法 + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | + +### 属性访问 + +| 方法 | 文档 | +|------|------| +| `GetNativeHandle` | [详细文档](../buffer/get-native-handle.md) | +| `GetDescriptorCount` | [详细文档](get-descriptor-count.md) | +| `GetType` | [详细文档](../shader/get-type.md) | + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHIDevice](../device/device.md) - 创建设备 diff --git a/docs/api/rhi/descriptor-pool/get-descriptor-count.md b/docs/api/rhi/descriptor-pool/get-descriptor-count.md new file mode 100644 index 00000000..2505223d --- /dev/null +++ b/docs/api/rhi/descriptor-pool/get-descriptor-count.md @@ -0,0 +1,19 @@ +# RHIDescriptorPool::GetDescriptorCount + +```cpp +virtual uint32_t GetDescriptorCount() const = 0; +``` + +获取描述符数量。 + +**返回：** 描述符池中的描述符数量 + +**示例：** + +```cpp +uint32_t count = descriptorPool->GetDescriptorCount(); +``` + +## 相关文档 + +- [RHIDescriptorPool 总览](descriptor-pool.md) - 返回类总览 diff --git a/docs/api/rhi/descriptor-pool/methods.md b/docs/api/rhi/descriptor-pool/methods.md new file mode 100644 index 00000000..dcda05db --- /dev/null +++ b/docs/api/rhi/descriptor-pool/methods.md @@ -0,0 +1,41 @@ +# RHIDescriptorPool 方法 + +## Initialize + +```cpp +virtual bool Initialize(const DescriptorPoolDesc& desc) = 0; +``` + +初始化描述符池。 + +## Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +释放描述符池资源。 + +## GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取原生 API 句柄。 + +## GetDescriptorCount + +```cpp +virtual uint32_t GetDescriptorCount() const = 0; +``` + +获取描述符数量。 + +## GetType + +```cpp +virtual DescriptorHeapType GetType() const = 0; +``` + +获取堆类型。 diff --git a/docs/api/rhi/device/compile-shader.md b/docs/api/rhi/device/compile-shader.md new file mode 100644 index 00000000..e577171b --- /dev/null +++ b/docs/api/rhi/device/compile-shader.md @@ -0,0 +1,35 @@ +# RHIDevice::CompileShader + +```cpp +virtual RHIShader* CompileShader(const ShaderCompileDesc& desc) = 0; +``` + +编译着色器程序。 + +**参数：** +- `desc` - 着色器编译描述符，包含入口点、配置文件、源文件等 + +**返回：** 新创建的着色器指针，失败返回 `nullptr` + +**复杂度：** O(n) - 取决于着色器代码复杂度 + +**示例：** + +```cpp +ShaderCompileDesc shaderDesc; +shaderDesc.entryPoint = L"main"; +shaderDesc.profile = L"vs_6_0"; +shaderDesc.fileName = L"shaders/vertex.hlsl"; +shaderDesc.macros = {}; + +RHIShader* vertexShader = device->CompileShader(shaderDesc); +if (!vertexShader->IsValid()) { + // 处理编译错误 + vertexShader->Shutdown(); +} +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHIShader](../shader/shader.md) - 着色器类 diff --git a/docs/api/rhi/device/create-buffer.md b/docs/api/rhi/device/create-buffer.md new file mode 100644 index 00000000..a2469415 --- /dev/null +++ b/docs/api/rhi/device/create-buffer.md @@ -0,0 +1,32 @@ +# RHIDevice::CreateBuffer + +```cpp +virtual RHIBuffer* CreateBuffer(const BufferDesc& desc) = 0; +``` + +创建 GPU 缓冲区资源。 + +**参数：** +- `desc` - 缓冲区描述符，包含大小、类型、标志等 + +**返回：** 新创建的缓冲区指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +BufferDesc bufferDesc; +bufferDesc.size = sizeof(Vertex) * vertexCount; +bufferDesc.stride = sizeof(Vertex); +bufferDesc.bufferType = (uint32_t)BufferType::Vertex; +bufferDesc.flags = 0; + +RHIBuffer* vertexBuffer = device->CreateBuffer(bufferDesc); +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHIBuffer](../buffer/buffer.md) - 缓冲区类 +- [BufferDesc](../types/types.md) - 缓冲区描述结构体 diff --git a/docs/api/rhi/device/create-command-list.md b/docs/api/rhi/device/create-command-list.md new file mode 100644 index 00000000..2c04e661 --- /dev/null +++ b/docs/api/rhi/device/create-command-list.md @@ -0,0 +1,29 @@ +# RHIDevice::CreateCommandList + +```cpp +virtual RHICommandList* CreateCommandList(const CommandListDesc& desc) = 0; +``` + +创建命令列表，用于录制 GPU 命令。 + +**参数：** +- `desc` - 命令列表描述符，包含类型和节点掩码 + +**返回：** 新创建的命令列表指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +CommandListDesc cmdListDesc; +cmdListDesc.commandListType = (uint32_t)CommandQueueType::Direct; +cmdListDesc.nodeMask = 0; + +RHICommandList* commandList = device->CreateCommandList(cmdListDesc); +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHICommandList](../command-list/command-list.md) - 命令列表类 diff --git a/docs/api/rhi/device/create-command-queue.md b/docs/api/rhi/device/create-command-queue.md new file mode 100644 index 00000000..874317b3 --- /dev/null +++ b/docs/api/rhi/device/create-command-queue.md @@ -0,0 +1,31 @@ +# RHIDevice::CreateCommandQueue + +```cpp +virtual RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) = 0; +``` + +创建命令队列，用于提交和执行命令列表。 + +**参数：** +- `desc` - 命令队列描述符，包含队列类型和优先级 + +**返回：** 新创建的命令队列指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +CommandQueueDesc queueDesc; +queueDesc.queueType = (uint32_t)CommandQueueType::Direct; +queueDesc.priority = 0; +queueDesc.nodeMask = 0; +queueDesc.flags = 0; + +RHICommandQueue* commandQueue = device->CreateCommandQueue(queueDesc); +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHICommandQueue](../command-queue/command-queue.md) - 命令队列类 diff --git a/docs/api/rhi/device/create-fence.md b/docs/api/rhi/device/create-fence.md new file mode 100644 index 00000000..a0345cf1 --- /dev/null +++ b/docs/api/rhi/device/create-fence.md @@ -0,0 +1,29 @@ +# RHIDevice::CreateFence + +```cpp +virtual RHIFence* CreateFence(const FenceDesc& desc) = 0; +``` + +创建同步栅栏，用于 CPU/GPU 同步。 + +**参数：** +- `desc` - 栅栏描述符，包含初始值和标志 + +**返回：** 新创建的栅栏指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +FenceDesc fenceDesc; +fenceDesc.initialValue = 0; +fenceDesc.flags = 0; + +RHIFence* fence = device->CreateFence(fenceDesc); +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHIFence](../fence/fence.md) - 栅栏类 diff --git a/docs/api/rhi/device/create-pipeline-state.md b/docs/api/rhi/device/create-pipeline-state.md new file mode 100644 index 00000000..ab6beae1 --- /dev/null +++ b/docs/api/rhi/device/create-pipeline-state.md @@ -0,0 +1,29 @@ +# RHIDevice::CreatePipelineState + +```cpp +virtual RHIPipelineState* CreatePipelineState(const PipelineStateDesc& desc) = 0; +``` + +创建渲染管线状态对象（PSO）。 + +**参数：** +- `desc` - 管线状态描述符，包含编译好的着色器字节码 + +**返回：** 新创建的管线状态指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +PipelineStateDesc psoDesc; +psoDesc.pBlob = compiledShaderBytecode; +psoDesc.size = bytecodeSize; + +RHIPipelineState* pipelineState = device->CreatePipelineState(psoDesc); +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHIPipelineState](../pipeline-state/pipeline-state.md) - 管线状态类 diff --git a/docs/api/rhi/device/create-sampler.md b/docs/api/rhi/device/create-sampler.md new file mode 100644 index 00000000..2d0a6df3 --- /dev/null +++ b/docs/api/rhi/device/create-sampler.md @@ -0,0 +1,34 @@ +# RHIDevice::CreateSampler + +```cpp +virtual RHISampler* CreateSampler(const SamplerDesc& desc) = 0; +``` + +创建纹理采样器。 + +**参数：** +- `desc` - 采样器描述符，包含过滤模式、寻址模式等 + +**返回：** 新创建的采样器指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +SamplerDesc samplerDesc; +samplerDesc.filter = (uint32_t)FilterMode::Anisotropic; +samplerDesc.addressU = (uint32_t)TextureAddressMode::Wrap; +samplerDesc.addressV = (uint32_t)TextureAddressMode::Wrap; +samplerDesc.addressW = (uint32_t)TextureAddressMode::Wrap; +samplerDesc.maxAnisotropy = 16; +samplerDesc.minLod = 0; +samplerDesc.maxLod = FLT_MAX; + +RHISampler* sampler = device->CreateSampler(samplerDesc); +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHISampler](../sampler/sampler.md) - 采样器类 diff --git a/docs/api/rhi/device/create-swap-chain.md b/docs/api/rhi/device/create-swap-chain.md new file mode 100644 index 00000000..63c9663a --- /dev/null +++ b/docs/api/rhi/device/create-swap-chain.md @@ -0,0 +1,34 @@ +# RHIDevice::CreateSwapChain + +```cpp +virtual RHISwapChain* CreateSwapChain(const SwapChainDesc& desc) = 0; +``` + +创建交换链，用于管理窗口渲染和帧缓冲区切换。 + +**参数：** +- `desc` - 交换链描述符，包含尺寸、缓冲数量、格式等 + +**返回：** 新创建的交换链指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +SwapChainDesc swapChainDesc; +swapChainDesc.width = 1280; +swapChainDesc.height = 720; +swapChainDesc.bufferCount = 2; +swapChainDesc.format = (uint32_t)Format::R8G8B8A8_UNorm; +swapChainDesc.refreshRate = 60; +swapChainDesc.sampleCount = 1; +swapChainDesc.sampleQuality = 0; + +RHISwapChain* swapChain = device->CreateSwapChain(swapChainDesc); +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHISwapChain](../swap-chain/swap-chain.md) - 交换链类 diff --git a/docs/api/rhi/device/create-texture.md b/docs/api/rhi/device/create-texture.md new file mode 100644 index 00000000..68876020 --- /dev/null +++ b/docs/api/rhi/device/create-texture.md @@ -0,0 +1,38 @@ +# RHIDevice::CreateTexture + +```cpp +virtual RHITexture* CreateTexture(const TextureDesc& desc) = 0; +``` + +创建 GPU 纹理资源。 + +**参数：** +- `desc` - 纹理描述符，包含尺寸、格式、纹理类型等 + +**返回：** 新创建的纹理指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +TextureDesc textureDesc; +textureDesc.width = 1024; +textureDesc.height = 1024; +textureDesc.depth = 1; +textureDesc.mipLevels = 1; +textureDesc.arraySize = 1; +textureDesc.format = (uint32_t)Format::R8G8B8A8_UNorm; +textureDesc.textureType = (uint32_t)TextureType::Texture2D; +textureDesc.sampleCount = 1; +textureDesc.sampleQuality = 0; +textureDesc.flags = 0; + +RHITexture* texture = device->CreateTexture(textureDesc); +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHITexture](../texture/texture.md) - 纹理类 +- [TextureDesc](../types/types.md) - 纹理描述结构体 diff --git a/docs/api/rhi/device/device.md b/docs/api/rhi/device/device.md new file mode 100644 index 00000000..63a60662 --- /dev/null +++ b/docs/api/rhi/device/device.md @@ -0,0 +1,85 @@ +# RHIDevice + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: RHI 渲染设备抽象接口，代表一个图形设备实例。 + +## 概述 + +`RHIDevice` 是 RHI 模块的核心接口之一，负责创建和管理所有 GPU 资源。每个 RHI 后端（D3D12、OpenGL 等）都需要实现此接口。 + +## 公共方法 + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](initialize.md) | +| `Shutdown` | [详细文档](shutdown.md) | + +### 资源创建 + +| 方法 | 文档 | +|------|------| +| `CreateBuffer` | [详细文档](create-buffer.md) | +| `CreateTexture` | [详细文档](create-texture.md) | +| `CreateSwapChain` | [详细文档](create-swap-chain.md) | +| `CreateCommandList` | [详细文档](create-command-list.md) | +| `CreateCommandQueue` | [详细文档](create-command-queue.md) | +| `CompileShader` | [详细文档](compile-shader.md) | +| `CreatePipelineState` | [详细文档](create-pipeline-state.md) | +| `CreateFence` | [详细文档](create-fence.md) | +| `CreateSampler` | [详细文档](create-sampler.md) | + +### 设备信息 + +| 方法 | 文档 | +|------|------| +| `GetCapabilities` | [详细文档](get-capabilities.md) | +| `GetDeviceInfo` | [详细文档](get-device-info.md) | +| `GetNativeDevice` | [详细文档](get-native-device.md) | + +## 使用示例 + +```cpp +// 创建 D3D12 设备 +RHI::RHIDevice* device = RHI::RHIFactory::CreateRHIDevice(RHI::RHIType::D3D12); + +// 配置设备描述 +RHI::RHIDeviceDesc desc; +desc.windowHandle = hwnd; +desc.width = 1280; +desc.height = 720; +desc.appName = L"MyApp"; +desc.enableDebugLayer = true; + +// 初始化设备 +if (device->Initialize(desc)) { + const RHI::RHICapabilities& caps = device->GetCapabilities(); + if (caps.bSupportsRayTracing) { + // 设备支持光线追踪 + } + + const RHI::RHIDeviceInfo& info = device->GetDeviceInfo(); + printf("GPU: %ls\n", info.description.c_str()); + + // 创建资源 + RHI::BufferDesc bufferDesc; + bufferDesc.size = 1024; + bufferDesc.bufferType = (uint32_t)RHI::BufferType::Vertex; + RHI::RHIBuffer* buffer = device->CreateBuffer(bufferDesc); + + device->Shutdown(); +} + +delete device; +``` + +## 相关文档 + +- [../../rhi.md](../rhi.md) - RHI 模块总览 +- [RHIFactory](../factory/factory.md) - 设备工厂 +- [RHICapabilities](../capabilities/capabilities.md) - 设备能力 +- [RHITypes](../types/types.md) - 设备描述结构体 diff --git a/docs/api/rhi/device/get-capabilities.md b/docs/api/rhi/device/get-capabilities.md new file mode 100644 index 00000000..1012565b --- /dev/null +++ b/docs/api/rhi/device/get-capabilities.md @@ -0,0 +1,32 @@ +# RHIDevice::GetCapabilities + +```cpp +virtual const RHICapabilities& GetCapabilities() const = 0; +``` + +获取当前设备的图形能力。 + +**返回：** 设备能力结构体引用 + +**复杂度：** O(1) + +**示例：** + +```cpp +const RHICapabilities& caps = device->GetCapabilities(); + +if (caps.bSupportsRayTracing) { + // 启用光线追踪功能 +} + +if (caps.bSupportsComputeShaders) { + // 启用计算着色器 +} + +uint32_t maxTexSize = caps.maxTexture2DSize; +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHICapabilities](../capabilities/capabilities.md) - 设备能力类 diff --git a/docs/api/rhi/device/get-device-info.md b/docs/api/rhi/device/get-device-info.md new file mode 100644 index 00000000..94b67d23 --- /dev/null +++ b/docs/api/rhi/device/get-device-info.md @@ -0,0 +1,27 @@ +# RHIDevice::GetDeviceInfo + +```cpp +virtual const RHIDeviceInfo& GetDeviceInfo() const = 0; +``` + +获取当前设备的详细信息。 + +**返回：** 设备信息结构体引用 + +**复杂度：** O(1) + +**示例：** + +```cpp +const RHIDeviceInfo& info = device->GetDeviceInfo(); + +printf("GPU: %ls\n", info.description.c_str()); +printf("Vendor: %ls\n", info.vendor.c_str()); +printf("Driver: %ls\n", info.version.c_str()); +printf("VRAM: %llu MB\n", info.dedicatedVideoMemory / 1024 / 1024); +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHIDeviceInfo](../types/types.md) - 设备信息结构体 diff --git a/docs/api/rhi/device/get-native-device.md b/docs/api/rhi/device/get-native-device.md new file mode 100644 index 00000000..477396b3 --- /dev/null +++ b/docs/api/rhi/device/get-native-device.md @@ -0,0 +1,29 @@ +# RHIDevice::GetNativeDevice + +```cpp +virtual void* GetNativeDevice() = 0; +``` + +获取原生图形 API 设备指针。 + +**返回：** +- D3D12 后端: `ID3D12Device*` +- OpenGL 后端: `void*` (GLFWwindow* 或 GL 上下文指针) + +**复杂度：** O(1) + +**示例：** + +```cpp +void* nativeDevice = device->GetNativeDevice(); + +// D3D12 使用 +ID3D12Device* d3d12Device = static_cast(nativeDevice); + +// OpenGL 使用 +GLFWwindow* glfwWindow = static_cast(nativeDevice); +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 diff --git a/docs/api/rhi/device/initialize.md b/docs/api/rhi/device/initialize.md new file mode 100644 index 00000000..54470eb1 --- /dev/null +++ b/docs/api/rhi/device/initialize.md @@ -0,0 +1,39 @@ +# RHIDevice::Initialize + +```cpp +virtual bool Initialize(const RHIDeviceDesc& desc) = 0; +``` + +初始化 RHI 设备，建立与图形适配器的连接。 + +**参数：** +- `desc` - 设备描述符，包含窗口句柄、分辨率、调试选项等配置 + +**返回：** 成功返回 `true`，失败返回 `false` + +**复杂度：** O(1) + +**示例：** + +```cpp +RHIDeviceDesc desc; +desc.windowHandle = hwnd; +desc.width = 1920; +desc.height = 1080; +desc.appName = L"MyApp"; +desc.enableDebugLayer = true; +desc.enableGPUValidation = true; + +RHIDevice* device = RHIFactory::CreateRHIDevice(RHIType::D3D12); +if (device->Initialize(desc)) { + // 设备初始化成功 +} else { + // 处理初始化失败 + delete device; +} +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 +- [RHIDeviceDesc](../types/types.md) - 设备描述结构体 diff --git a/docs/api/rhi/device/shutdown.md b/docs/api/rhi/device/shutdown.md new file mode 100644 index 00000000..60d9b00c --- /dev/null +++ b/docs/api/rhi/device/shutdown.md @@ -0,0 +1,20 @@ +# RHIDevice::Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +关闭 RHI 设备，释放所有相关资源。 + +**复杂度：** O(n) - 取决于管理的资源数量 + +**示例：** + +```cpp +device->Shutdown(); +delete device; +``` + +## 相关文档 + +- [RHIDevice 总览](device.md) - 返回类总览 diff --git a/docs/api/rhi/enums/enums.md b/docs/api/rhi/enums/enums.md new file mode 100644 index 00000000..616b5aaf --- /dev/null +++ b/docs/api/rhi/enums/enums.md @@ -0,0 +1,78 @@ +# RHIEnums + +**命名空间**: `XCEngine::RHI` + +**类型**: `enums` + +**描述**: RHI 模块中使用的所有枚举类型汇总。 + +## 主要枚举 + +### 着色器 + +| 枚举 | 描述 | +|------|------| +| `ShaderType` | 着色器类型 | +| `ShaderVisibility` | 着色器可见性 | + +### 渲染状态 + +| 枚举 | 描述 | +|------|------| +| `CullMode` | 背面剔除模式 | +| `FillMode` | 填充模式 | +| `BlendOp` | 混合操作 | +| `BlendFactor` | 混合因子 | +| `ComparisonFunc` | 比较函数 | +| `StencilOp` | 模板操作 | +| `PrimitiveTopology` | 图元拓扑 | + +### 纹理和采样 + +| 枚举 | 描述 | +|------|------| +| `TextureType` | 纹理类型 | +| `Format` | 纹理/缓冲区格式 | +| `FilterMode` | 采样器过滤模式 | +| `TextureAddressMode` | 纹理寻址模式 | +| `BorderColor` | 边框颜色 | + +### 资源和缓冲 + +| 枚举 | 描述 | +|------|------| +| `BufferType` | 缓冲区类型 | +| `ResourceStates` | 资源状态 | +| `HeapType` | 内存堆类型 | +| `DescriptorType` | 描述符类型 | +| `DescriptorHeapType` | 描述符堆类型 | + +### 命令和管线 + +| 枚举 | 描述 | +|------|------| +| `CommandQueueType` | 命令队列类型 | +| `PipelineType` | 管线类型 | +| `LoadAction` | 加载操作 | +| `StoreAction` | 存储操作 | +| `PresentFlags` | 呈现标志 | + +### 查询和同步 + +| 枚举 | 描述 | +|------|------| +| `QueryType` | 查询类型 | +| `RootParameterType` | 根参数类型 | + +### 其他 + +| 枚举 | 描述 | +|------|------| +| `LogicOp` | 逻辑操作 | +| `ColorWriteMask` | 颜色写入掩码 | +| `RHIType` | RHI 后端类型 | + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHITypes](../types/types.md) - 结构体类型汇总 diff --git a/docs/api/rhi/factory/create-rhi-device-string.md b/docs/api/rhi/factory/create-rhi-device-string.md new file mode 100644 index 00000000..5cb37179 --- /dev/null +++ b/docs/api/rhi/factory/create-rhi-device-string.md @@ -0,0 +1,32 @@ +# RHIFactory::CreateRHIDevice (string) + +```cpp +static RHIDevice* CreateRHIDevice(const std::string& typeName); +``` + +根据字符串名称创建 RHI 设备。 + +**参数：** +- `typeName` - 后端类型名称字符串（不区分大小写） + +**返回：** 新创建的设备指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**支持的类型名称：** +- `"D3D12"` / `"d3d12"` +- `"OpenGL"` / `"opengl"` +- `"Vulkan"` / `"vulkan"` +- `"Metal"` / `"metal"` + +**示例：** + +```cpp +// 从配置文件读取后端类型 +std::string backendType = "D3D12"; +RHIDevice* device = RHIFactory::CreateRHIDevice(backendType); +``` + +## 相关文档 + +- [RHIFactory 总览](factory.md) - 返回类总览 diff --git a/docs/api/rhi/factory/create-rhi-device-type.md b/docs/api/rhi/factory/create-rhi-device-type.md new file mode 100644 index 00000000..deaeb840 --- /dev/null +++ b/docs/api/rhi/factory/create-rhi-device-type.md @@ -0,0 +1,28 @@ +# RHIFactory::CreateRHIDevice + +```cpp +static RHIDevice* CreateRHIDevice(RHIType type); +``` + +根据枚举类型创建 RHI 设备。 + +**参数：** +- `type` - 后端类型枚举值 + +**返回：** 新创建的设备指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +RHIDevice* device = RHIFactory::CreateRHIDevice(RHIType::D3D12); +if (device) { + device->Initialize(desc); +} +``` + +## 相关文档 + +- [RHIFactory 总览](factory.md) - 返回类总览 +- [RHIType](../enums/enums.md) - 枚举类型 diff --git a/docs/api/rhi/rhi-factory.md b/docs/api/rhi/factory/factory.md similarity index 69% rename from docs/api/rhi/rhi-factory.md rename to docs/api/rhi/factory/factory.md index 40f3b5b2..e3f997ba 100644 --- a/docs/api/rhi/rhi-factory.md +++ b/docs/api/rhi/factory/factory.md @@ -2,7 +2,7 @@ **命名空间**: `XCEngine::RHI` -**类型**: `class` +**类型**: `class` (static) **描述**: RHI 设备工厂，用于创建不同图形 API 后端的渲染设备。 @@ -12,10 +12,10 @@ ## 公共方法 -| 方法 | 描述 | +| 方法 | 文档 | |------|------| -| `static RHIDevice* CreateRHIDevice(RHIType type)` | 根据类型创建 RHI 设备 | -| `static RHIDevice* CreateRHIDevice(const std::string& typeName)` | 根据类型名称字符串创建设备 | +| `CreateRHIDevice(RHIType)` | [详细文档](create-rhi-device-type.md) | +| `CreateRHIDevice(std::string)` | [详细文档](create-rhi-device-string.md) | ## 类型映射 @@ -36,11 +36,12 @@ RHIDevice* d3d12Device = RHIFactory::CreateRHIDevice(RHIType::D3D12); RHIDevice* glDevice = RHIFactory::CreateRHIDevice("OpenGL"); // 方法3：根据配置选择 -std::string backend = "D3D12"; // 可以从配置文件读取 +std::string backend = "D3D12"; RHIDevice* device = RHIFactory::CreateRHIDevice(backend); ``` ## 相关文档 -- [RHIDevice](./rhi-device.md) - 渲染设备 -- [RHIEnums](./rhi-enums.md) - RHIType 枚举定义 +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHIDevice](../device/device.md) - 渲染设备 +- [RHIEnums](../enums/enums.md) - RHIType 枚举定义 diff --git a/docs/api/rhi/fence/fence.md b/docs/api/rhi/fence/fence.md new file mode 100644 index 00000000..f3f6856d --- /dev/null +++ b/docs/api/rhi/fence/fence.md @@ -0,0 +1,46 @@ +# RHIFence + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: GPU 同步栅栏抽象接口，用于 GPU/CPU 同步和跨队列同步。 + +## 公共方法 + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | + +### 同步操作 + +| 方法 | 文档 | +|------|------| +| `Signal` | [详细文档](../command-queue/signal.md) | +| `Wait` | [详细文档](../../threading/task-group/wait.md) | +| `GetCompletedValue` | [详细文档](../command-queue/get-completed-value.md) | +| `IsSignaled` | [详细文档](is-signaled.md) | + +### 其他 + +| 方法 | 文档 | +|------|------| +| `GetNativeHandle` | [详细文档](../buffer/get-native-handle.md) | + +## 使用示例 + +```cpp +FenceDesc desc; +desc.initialValue = 0; +RHIFence* fence = device->CreateFence(desc); + +commandQueue->Signal(fence, 1); +fence->Wait(1); +``` + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHICommandQueue](../command-queue/command-queue.md) - 命令队列 diff --git a/docs/api/rhi/fence/get-completed-value.md b/docs/api/rhi/fence/get-completed-value.md new file mode 100644 index 00000000..7d83dc99 --- /dev/null +++ b/docs/api/rhi/fence/get-completed-value.md @@ -0,0 +1,19 @@ +# RHIFence::GetCompletedValue + +```cpp +virtual uint64_t GetCompletedValue() const = 0; +``` + +获取已完成信号值。 + +**返回：** 已完成的信号值 + +**示例：** + +```cpp +uint64_t value = fence->GetCompletedValue(); +``` + +## 相关文档 + +- [RHIFence 总览](fence.md) - 返回类总览 diff --git a/docs/api/rhi/fence/is-signaled.md b/docs/api/rhi/fence/is-signaled.md new file mode 100644 index 00000000..b595f56f --- /dev/null +++ b/docs/api/rhi/fence/is-signaled.md @@ -0,0 +1,21 @@ +# RHIFence::IsSignaled + +```cpp +virtual bool IsSignaled() const = 0; +``` + +检查栅栏是否被信号触发。 + +**返回：** 如果栅栏已被信号触发返回 true + +**示例：** + +```cpp +if (fence->IsSignaled()) { + // 栅栏已完成 +} +``` + +## 相关文档 + +- [RHIFence 总览](fence.md) - 返回类总览 diff --git a/docs/api/rhi/fence/methods.md b/docs/api/rhi/fence/methods.md new file mode 100644 index 00000000..8b715be5 --- /dev/null +++ b/docs/api/rhi/fence/methods.md @@ -0,0 +1,50 @@ +# RHIFence 方法 + +## Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +释放栅栏资源。 + +## Signal + +```cpp +virtual void Signal() = 0; +virtual void Signal(uint64_t value) = 0; +``` + +信号通知（值为 1）或指定值。 + +## Wait + +```cpp +virtual void Wait(uint64_t value) = 0; +``` + +等待指定值。 + +## GetCompletedValue + +```cpp +virtual uint64_t GetCompletedValue() const = 0; +``` + +获取已完成的值。 + +## IsSignaled + +```cpp +virtual bool IsSignaled() const = 0; +``` + +检查是否已信号通知。 + +## GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取原生 API 句柄。 diff --git a/docs/api/rhi/fence/signal.md b/docs/api/rhi/fence/signal.md new file mode 100644 index 00000000..2319c426 --- /dev/null +++ b/docs/api/rhi/fence/signal.md @@ -0,0 +1,22 @@ +# RHIFence::Signal + +```cpp +virtual void Signal() = 0; +virtual void Signal(uint64_t value) = 0; +``` + +向栅栏发送信号。 + +**参数：** +- `value` - 信号值（重载版本） + +**示例：** + +```cpp +fence->Signal(); +fence->Signal(1); +``` + +## 相关文档 + +- [RHIFence 总览](fence.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/README.md b/docs/api/rhi/opengl/README.md new file mode 100644 index 00000000..0fab2897 --- /dev/null +++ b/docs/api/rhi/opengl/README.md @@ -0,0 +1,26 @@ +# OpenGL 后端组件 + +OpenGL 后端已创建以下组件文件夹和文档： + +- `device/` - OpenGLDevice +- `buffer/` - OpenGLBuffer +- `texture/` - OpenGLTexture +- `command-list/` - OpenGLCommandList +- `command-queue/` - OpenGLCommandQueue +- `swap-chain/` - OpenGLSwapChain +- `fence/` - OpenGLFence +- `shader/` - OpenGLShader +- `pipeline-state/` - OpenGLPipelineState +- `sampler/` - OpenGLSampler +- `vertex-array/` - OpenGLVertexArray +- `render-target-view/` - OpenGLRenderTargetView +- `depth-stencil-view/` - OpenGLDepthStencilView + +每个组件文件夹包含: +- `{component}.md` - 类总览 +- `methods.md` - 方法详细文档 + +## 相关文档 + +- [OpenGL 后端总览](overview.md) +- [RHI 抽象层](../d3d12/overview.md) diff --git a/docs/api/rhi/opengl/buffer/bind-base.md b/docs/api/rhi/opengl/buffer/bind-base.md new file mode 100644 index 00000000..6baa0123 --- /dev/null +++ b/docs/api/rhi/opengl/buffer/bind-base.md @@ -0,0 +1,21 @@ +# OpenGLBuffer::BindBase + +```cpp +void BindBase(unsigned int target, unsigned int index) const +``` + +将缓冲区绑定到固定的 binding point。 + +**参数：** +- `target` - OpenGL target (如 GL_ARRAY_BUFFER, GL_ELEMENT_ARRAY_BUFFER) +- `index` - binding point 索引 + +**示例：** + +```cpp +buffer.BindBase(GL_UNIFORM_BUFFER, 0); +``` + +## 相关文档 + +- [OpenGLBuffer](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/buffer/buffer.md b/docs/api/rhi/opengl/buffer/buffer.md new file mode 100644 index 00000000..1129f9c6 --- /dev/null +++ b/docs/api/rhi/opengl/buffer/buffer.md @@ -0,0 +1,34 @@ +# OpenGLBuffer + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 缓冲区的实现，继承自 `RHIBuffer`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `InitializeVertexBuffer` | [详细文档](initialize-vertex-buffer.md) | +| `InitializeIndexBuffer` | [详细文档](initialize-index-buffer.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Bind` | [详细文档](../../shader/bind.md) | +| `Unbind` | [详细文档](../../shader/unbind.md) | +| `BindBase` | [详细文档](bind-base.md) | +| `Map` | [详细文档](../../buffer/map.md) | +| `Unmap` | [详细文档](../../buffer/unmap.md) | +| `SetData` | [详细文档](../../buffer/set-data.md) | +| `GetID` | [详细文档](get-id.md) | +| `GetSize` | [详细文档](../../buffer/get-size.md) | +| `GetType` | [详细文档](../../shader/get-type.md) | +| `IsDynamic` | [详细文档](is-dynamic.md) | +| `GetBufferType` / `SetBufferType` | [详细文档](../../buffer/get-buffer-type.md) | +| `GetStride` / `SetStride` | [详细文档](../../buffer/get-stride.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `GetState` / `SetState` | [详细文档](../../buffer/get-state.md) | +| `GetName` / `SetName` | [详细文档](../../buffer/get-name.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) +- [RHIBuffer](../../buffer/buffer.md) - 抽象缓冲区接口 diff --git a/docs/api/rhi/opengl/buffer/get-id.md b/docs/api/rhi/opengl/buffer/get-id.md new file mode 100644 index 00000000..76db6159 --- /dev/null +++ b/docs/api/rhi/opengl/buffer/get-id.md @@ -0,0 +1,20 @@ +# OpenGLBuffer::GetID + +```cpp +unsigned int GetID() const +``` + +获取 OpenGL buffer 的 GLuint ID。 + +**返回：** OpenGL buffer ID + +**示例：** + +```cpp +unsigned int id = buffer.GetID(); +glBindBuffer(GL_ARRAY_BUFFER, id); +``` + +## 相关文档 + +- [OpenGLBuffer](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/buffer/initialize-index-buffer.md b/docs/api/rhi/opengl/buffer/initialize-index-buffer.md new file mode 100644 index 00000000..bc23db6c --- /dev/null +++ b/docs/api/rhi/opengl/buffer/initialize-index-buffer.md @@ -0,0 +1,25 @@ +# OpenGLBuffer::InitializeIndexBuffer + +```cpp +bool InitializeIndexBuffer(const void* data, size_t size) +``` + +初始化索引缓冲区。 + +**参数：** +- `data` - 索引数据指针 +- `size` - 数据大小（字节） + +**返回：** 成功返回 true + +**示例：** + +```cpp +uint32_t indices[] = { 0, 1, 2 }; +OpenGLBuffer buffer; +buffer.InitializeIndexBuffer(indices, sizeof(indices)); +``` + +## 相关文档 + +- [OpenGLBuffer](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/buffer/initialize-vertex-buffer.md b/docs/api/rhi/opengl/buffer/initialize-vertex-buffer.md new file mode 100644 index 00000000..e216d9e5 --- /dev/null +++ b/docs/api/rhi/opengl/buffer/initialize-vertex-buffer.md @@ -0,0 +1,25 @@ +# OpenGLBuffer::InitializeVertexBuffer + +```cpp +bool InitializeVertexBuffer(const void* data, size_t size) +``` + +初始化顶点缓冲区。 + +**参数：** +- `data` - 顶点数据指针 +- `size` - 数据大小（字节） + +**返回：** 成功返回 true + +**示例：** + +```cpp +float vertices[] = { 0.0f, 0.5f, 0.0f }; +OpenGLBuffer buffer; +buffer.InitializeVertexBuffer(vertices, sizeof(vertices)); +``` + +## 相关文档 + +- [OpenGLBuffer](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/buffer/is-dynamic.md b/docs/api/rhi/opengl/buffer/is-dynamic.md new file mode 100644 index 00000000..40e892d1 --- /dev/null +++ b/docs/api/rhi/opengl/buffer/is-dynamic.md @@ -0,0 +1,24 @@ +# OpenGLBuffer::IsDynamic + +```cpp +bool IsDynamic() const +``` + +判断缓冲区是否为动态缓冲区。 + +**返回：** 如果是动态缓冲区返回 true + +**示例：** + +```cpp +if (buffer.IsDynamic()) { + // 动态缓冲区可以直接 Map/Unmap + void* data = buffer.Map(); + // ... + buffer.Unmap(); +} +``` + +## 相关文档 + +- [OpenGLBuffer](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/clear-color.md b/docs/api/rhi/opengl/command-list/clear-color.md new file mode 100644 index 00000000..6c7638f1 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/clear-color.md @@ -0,0 +1,23 @@ +# OpenGLCommandList::ClearColor + +```cpp +void ClearColor(float r, float g, float b, float a) +``` + +清除颜色缓冲区。 + +**参数：** +- `r` - 红色分量 (0.0-1.0) +- `g` - 绿色分量 (0.0-1.0) +- `b` - 蓝色分量 (0.0-1.0) +- `a` - 透明度分量 (0.0-1.0) + +**示例：** + +```cpp +commandList->ClearColor(0.0f, 0.0f, 0.0f, 1.0f); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/clear-depth-stencil.md b/docs/api/rhi/opengl/command-list/clear-depth-stencil.md new file mode 100644 index 00000000..b81f0fa6 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/clear-depth-stencil.md @@ -0,0 +1,22 @@ +# OpenGLCommandList::ClearDepthStencil + +```cpp +void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) +``` + +清除深度模板目标。 + +**参数：** +- `depthStencil` - 深度模板目标指针 +- `depth` - 深度值 +- `stencil` - 模板值 + +**示例：** + +```cpp +commandList->ClearDepthStencil(depthStencil, 1.0f, 0); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/clear-depth.md b/docs/api/rhi/opengl/command-list/clear-depth.md new file mode 100644 index 00000000..66bea50f --- /dev/null +++ b/docs/api/rhi/opengl/command-list/clear-depth.md @@ -0,0 +1,20 @@ +# OpenGLCommandList::ClearDepth + +```cpp +void ClearDepth(float depth) +``` + +清除深度缓冲区。 + +**参数：** +- `depth` - 深度值 (0.0-1.0) + +**示例：** + +```cpp +commandList->ClearDepth(1.0f); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/clear-render-target.md b/docs/api/rhi/opengl/command-list/clear-render-target.md new file mode 100644 index 00000000..e3c1063b --- /dev/null +++ b/docs/api/rhi/opengl/command-list/clear-render-target.md @@ -0,0 +1,22 @@ +# OpenGLCommandList::ClearRenderTarget + +```cpp +void ClearRenderTarget(void* renderTarget, const float color[4]) +``` + +清除渲染目标。 + +**参数：** +- `renderTarget` - 渲染目标指针 +- `color` - 清除颜色 [r, g, b, a] + +**示例：** + +```cpp +float color[4] = { 0.0f, 0.0f, 0.0f, 1.0f }; +commandList->ClearRenderTarget(renderTarget, color); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/clear-stencil.md b/docs/api/rhi/opengl/command-list/clear-stencil.md new file mode 100644 index 00000000..5a26581a --- /dev/null +++ b/docs/api/rhi/opengl/command-list/clear-stencil.md @@ -0,0 +1,20 @@ +# OpenGLCommandList::ClearStencil + +```cpp +void ClearStencil(int stencil) +``` + +清除模板缓冲区。 + +**参数：** +- `stencil` - 模板值 + +**示例：** + +```cpp +commandList->ClearStencil(0); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/command-list.md b/docs/api/rhi/opengl/command-list/command-list.md new file mode 100644 index 00000000..aff85d19 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/command-list.md @@ -0,0 +1,45 @@ +# OpenGLCommandList + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 命令列表实现，继承自 `RHICommandList`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Reset` | [详细文档](../../../resources/resourcehandle/reset.md) | +| `Close` | [详细文档](../../../core/filewriter/close.md) | +| `Clear` | [详细文档](../../../memory/linear-allocator/clear.md) | +| `ClearColor` | [详细文档](clear-color.md) | +| `ClearDepth` | [详细文档](clear-depth.md) | +| `ClearStencil` | [详细文档](clear-stencil.md) | +| `ClearDepthStencil` | [详细文档](clear-depth-stencil.md) | +| `SetPipelineState` | [详细文档](set-pipeline-state.md) | +| `SetVertexBuffer` | [详细文档](set-vertex-buffer.md) | +| `SetVertexBuffers` | [详细文档](set-vertex-buffers.md) | +| `SetIndexBuffer` | [详细文档](set-index-buffer.md) | +| `TransitionBarrier` | [详细文档](transition-barrier.md) | +| `SetPrimitiveTopology` | [详细文档](set-primitive-topology.md) | +| `SetViewport` | [详细文档](set-viewport.md) | +| `SetViewports` | [详细文档](set-viewports.md) | +| `SetScissorRect` | [详细文档](set-scissor-rect.md) | +| `SetScissorRects` | [详细文档](set-scissor-rects.md) | +| `SetRenderTargets` | [详细文档](set-render-targets.md) | +| `SetDepthStencilState` | [详细文档](set-depth-stencil-state.md) | +| `SetStencilRef` | [详细文档](set-stencil-ref.md) | +| `SetBlendState` | [详细文档](set-blend-state.md) | +| `SetBlendFactor` | [详细文档](set-blend-factor.md) | +| `ClearRenderTarget` | [详细文档](clear-render-target.md) | +| `ClearDepthStencil` | [详细文档](clear-depth-stencil.md) | +| `Draw` | [详细文档](draw.md) | +| `DrawIndexed` | [详细文档](draw-indexed.md) | +| `Dispatch` | [详细文档](dispatch.md) | +| `CopyResource` | [详细文档](copy-resource.md) | +| **OpenGL 特有方法** | [详细文档](opengl-methods.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) +- [RHICommandList](../../command-list/command-list.md) - 抽象命令列表接口 diff --git a/docs/api/rhi/opengl/command-list/copy-resource.md b/docs/api/rhi/opengl/command-list/copy-resource.md new file mode 100644 index 00000000..f06886c7 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/copy-resource.md @@ -0,0 +1,21 @@ +# OpenGLCommandList::CopyResource + +```cpp +void CopyResource(void* dst, void* src) +``` + +复制资源。 + +**参数：** +- `dst` - 目标资源指针 +- `src` - 源资源指针 + +**示例：** + +```cpp +commandList->CopyResource(dstTexture, srcTexture); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/dispatch.md b/docs/api/rhi/opengl/command-list/dispatch.md new file mode 100644 index 00000000..b3b80aa5 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/dispatch.md @@ -0,0 +1,22 @@ +# OpenGLCommandList::Dispatch + +```cpp +void Dispatch(uint32_t x, uint32_t y, uint32_t z) +``` + +分发计算着色器。 + +**参数：** +- `x` - X 方向线程组数量 +- `y` - Y 方向线程组数量 +- `z` - Z 方向线程组数量 + +**示例：** + +```cpp +commandList->Dispatch(8, 8, 1); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/draw-indexed.md b/docs/api/rhi/opengl/command-list/draw-indexed.md new file mode 100644 index 00000000..7f4f6915 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/draw-indexed.md @@ -0,0 +1,24 @@ +# OpenGLCommandList::DrawIndexed + +```cpp +void DrawIndexed(uint32_t indexCount, uint32_t instanceCount, uint32_t startIndex, int32_t baseVertex, uint32_t startInstance) +``` + +绘制索引图元。 + +**参数：** +- `indexCount` - 索引数量 +- `instanceCount` - 实例数量 +- `startIndex` - 起始索引 +- `baseVertex` - 基础顶点 +- `startInstance` - 起始实例 + +**示例：** + +```cpp +commandList->DrawIndexed(6, 1, 0, 0, 0); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/draw.md b/docs/api/rhi/opengl/command-list/draw.md new file mode 100644 index 00000000..bbdf9387 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/draw.md @@ -0,0 +1,23 @@ +# OpenGLCommandList::Draw + +```cpp +void Draw(uint32_t vertexCount, uint32_t instanceCount, uint32_t startVertex, uint32_t startInstance) +``` + +绘制非索引图元。 + +**参数：** +- `vertexCount` - 顶点数量 +- `instanceCount` - 实例数量 +- `startVertex` - 起始顶点 +- `startInstance` - 起始实例 + +**示例：** + +```cpp +commandList->Draw(3, 1, 0, 0); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/opengl-methods.md b/docs/api/rhi/opengl/command-list/opengl-methods.md new file mode 100644 index 00000000..e6c13273 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/opengl-methods.md @@ -0,0 +1,545 @@ +# OpenGLCommandList - OpenGL 特有方法 + +以下是 `OpenGLCommandList` 中 OpenGL 特有的底层逃逸方法。这些方法不存在于 RHI 抽象接口中，用于需要直接操作 OpenGL 状态的高级场景。 + +## 顶点缓冲区（OpenGL 逃逸） + +### SetVertexBuffer (GL uint) + +```cpp +void SetVertexBuffer(unsigned int buffer, size_t offset, size_t stride) +``` + +直接使用 OpenGL buffer ID 设置顶点缓冲区。 + +### SetVertexBuffers (GL uint) + +```cpp +void SetVertexBuffers(unsigned int startSlot, unsigned int count, const unsigned int* buffers, const size_t* offsets, const size_t* strides) +``` + +批量设置顶点缓冲区。 + +### SetIndexBuffer (GL uint) + +```cpp +void SetIndexBuffer(unsigned int buffer, unsigned int type) +void SetIndexBuffer(unsigned int buffer, unsigned int type, size_t offset) +``` + +直接设置索引缓冲区。 + +## 顶点数组 + +### BindVertexArray + +```cpp +void BindVertexArray(unsigned int vao) +void BindVertexArray(unsigned int vao, unsigned int indexBuffer, unsigned int indexType) +``` + +绑定 VAO，可同时设置索引缓冲区。 + +### UseShader + +```cpp +void UseShader(unsigned int program) +``` + +使用 shader program。 + +## 视口与裁剪 + +### SetViewport (int) + +```cpp +void SetViewport(int x, int y, int width, int height) +``` + +使用整数参数设置视口。 + +### SetViewport (float) + +```cpp +void SetViewport(float x, float y, float width, float height, float minDepth, float maxDepth) +``` + +使用浮点参数设置视口。 + +### SetViewports + +```cpp +void SetViewports(unsigned int count, const float* viewports) +``` + +批量设置视口（6 个浮点值 per viewport: x, y, width, height, minDepth, maxDepth）。 + +### SetScissor + +```cpp +void SetScissor(int x, int y, int width, int height) +``` + +设置裁剪矩形。 + +### SetScissorRects + +```cpp +void SetScissorRects(unsigned int count, const int* rects) +``` + +批量设置裁剪矩形（4 个整数值 per rect: x, y, width, height）。 + +### EnableScissorTest + +```cpp +void EnableScissorTest(bool enable) +``` + +启用/禁用裁剪测试。 + +## 深度测试 + +### EnableDepthTest + +```cpp +void EnableDepthTest(bool enable) +``` + +启用/禁用深度测试。 + +### EnableDepthWrite + +```cpp +void EnableDepthWrite(bool enable) +``` + +启用/禁用深度写入。 + +### SetDepthFunc + +```cpp +void SetDepthFunc(unsigned int func) +``` + +设置深度比较函数（GL_NEVER, GL_LESS, GL_EQUAL, etc.）。 + +## 模板测试 + +### EnableStencilTest + +```cpp +void EnableStencilTest(bool enable) +``` + +启用/禁用模板测试。 + +### SetStencilFunc + +```cpp +void SetStencilFunc(unsigned int func, int ref, unsigned int mask) +``` + +设置模板测试函数。 + +### SetStencilOp + +```cpp +void SetStencilOp(unsigned int fail, unsigned int zfail, unsigned int zpass) +``` + +设置模板操作。 + +## 混合 + +### EnableBlending + +```cpp +void EnableBlending(bool enable) +``` + +启用/禁用混合。 + +### SetBlendFunc + +```cpp +void SetBlendFunc(unsigned int src, unsigned int dst) +``` + +设置混合函数。 + +### SetBlendFuncSeparate + +```cpp +void SetBlendFuncSeparate(unsigned int srcRGB, unsigned int dstRGB, unsigned int srcAlpha, unsigned int dstAlpha) +``` + +分别设置 RGB 和 Alpha 的混合函数。 + +### SetBlendEquation + +```cpp +void SetBlendEquation(unsigned int mode) +``` + +设置混合方程。 + +### SetBlendColor + +```cpp +void SetBlendColor(float r, float g, float b, float a) +``` + +设置混合因子颜色。 + +## 光栅化 + +### EnableCulling + +```cpp +void EnableCulling(bool enable) +``` + +启用/禁用面剔除。 + +### SetCullFace + +```cpp +void SetCullFace(unsigned int face) +``` + +设置剔除面（GL_FRONT, GL_BACK, GL_FRONT_AND_BACK）。 + +### SetFrontFace + +```cpp +void SetFrontFace(unsigned int face) +``` + +设置正面方向（GL_CW, GL_CCW）。 + +### SetPolygonMode + +```cpp +void SetPolygonMode(unsigned int mode) +``` + +设置多边形模式（GL_POINT, GL_LINE, GL_FILL）。 + +### SetPolygonOffset + +```cpp +void SetPolygonOffset(float factor, float units) +``` + +设置多边形偏移。 + +### SetPrimitiveType + +```cpp +void SetPrimitiveType(PrimitiveType type) +``` + +设置图元类型。 + +## 绘制（OpenGL 类型） + +### Draw (PrimitiveType) + +```cpp +void Draw(PrimitiveType type, unsigned int vertexCount, unsigned int startVertex) +``` + +绘制非索引图元。 + +### DrawInstanced + +```cpp +void DrawInstanced(PrimitiveType type, unsigned int vertexCount, unsigned int instanceCount, unsigned int startVertex, unsigned int startInstance) +``` + +实例化绘制。 + +### DrawIndexed (PrimitiveType) + +```cpp +void DrawIndexed(PrimitiveType type, unsigned int indexCount, unsigned int startIndex, int baseVertex) +``` + +绘制索引图元。 + +### DrawIndexedInstanced + +```cpp +void DrawIndexedInstanced(PrimitiveType type, unsigned int indexCount, unsigned int instanceCount, unsigned int startIndex, int baseVertex, unsigned int startInstance) +``` + +实例化索引绘制。 + +### DrawIndirect + +```cpp +void DrawIndirect(PrimitiveType type, unsigned int buffer, size_t offset, unsigned int drawCount, unsigned int stride) +``` + +间接绘制。 + +### DrawIndexedIndirect + +```cpp +void DrawIndexedIndirect(PrimitiveType type, unsigned int buffer, size_t offset, unsigned int drawCount, unsigned int stride) +``` + +间接索引绘制。 + +### MultiDrawArrays + +```cpp +void MultiDrawArrays(PrimitiveType type, const int* first, const int* count, unsigned int drawCount) +``` + +多重绘制。 + +### MultiDrawElements + +```cpp +void MultiDrawElements(PrimitiveType type, const int* count, unsigned int type_, const void* const* indices, unsigned int drawCount) +``` + +多重索引绘制。 + +## 计算着色器 + +### DispatchIndirect + +```cpp +void DispatchIndirect(unsigned int buffer, size_t offset) +``` + +间接分发计算着色器。 + +### DispatchCompute + +```cpp +void DispatchCompute(unsigned int x, unsigned int y, unsigned int z, unsigned int groupX, unsigned int groupY, unsigned int groupZ) +``` + +分发计算着色器（带参数）。 + +## 内存屏障 + +### MemoryBarrier + +```cpp +void MemoryBarrier(unsigned int barriers) +``` + +设置内存屏障。 + +### TextureBarrier + +```cpp +void TextureBarrier() +``` + +纹理屏障。 + +## 纹理绑定 + +### BindTexture + +```cpp +void BindTexture(unsigned int target, unsigned int unit, unsigned int texture) +``` + +绑定纹理到纹理单元。 + +### BindTextures + +```cpp +void BindTextures(unsigned int first, unsigned int count, const unsigned int* textures) +``` + +批量绑定纹理。 + +### BindSampler + +```cpp +void BindSampler(unsigned int unit, unsigned int sampler) +``` + +绑定采样器。 + +### BindSamplers + +```cpp +void BindSamplers(unsigned int first, unsigned int count, const unsigned int* samplers) +``` + +批量绑定采样器。 + +### BindImageTexture + +```cpp +void BindImageTexture(unsigned int unit, unsigned int texture, int level, bool layered, int layer, unsigned int access, unsigned int format) +``` + +绑定为 image texture。 + +## 缓冲区绑定 + +### BindBufferBase + +```cpp +void BindBufferBase(unsigned int target, unsigned int index, unsigned int buffer) +``` + +绑定到固定 binding point。 + +### BindBufferRange + +```cpp +void BindBufferRange(unsigned int target, unsigned int index, unsigned int buffer, size_t offset, size_t size) +``` + +绑定到范围 binding point。 + +## OpenGL 状态 + +### Enable / Disable + +```cpp +void Enable(unsigned int cap) +void Disable(unsigned int cap) +void Enablei(unsigned int cap, unsigned int index) +void Disablei(unsigned int cap, unsigned int index) +``` + +启用/禁用 GL capability。 + +## Uniform 设置 + +### SetUniform1i / SetUniform1f + +```cpp +void SetUniform1i(int location, int v) +void SetUniform1f(int location, float v) +``` + +### SetUniform2f + +```cpp +void SetUniform2f(int location, float x, float y) +``` + +### SetUniform3f + +```cpp +void SetUniform3f(int location, float x, float y, float z) +``` + +### SetUniform4f + +```cpp +void SetUniform4f(int location, float x, float y, float z, float w) +``` + +### SetUniform1fv / SetUniform2fv / SetUniform3fv / SetUniform4fv + +```cpp +void SetUniform1fv(int location, int count, const float* v) +void SetUniform2fv(int location, int count, const float* v) +void SetUniform3fv(int location, int count, const float* v) +void SetUniform4fv(int location, int count, const float* v) +``` + +### SetUniformMatrix4fv + +```cpp +void SetUniformMatrix4fv(int location, int count, bool transpose, const float* v) +``` + +## Shader 程序 + +### UseProgram + +```cpp +void UseProgram(unsigned int program) +``` + +使用 program。 + +### BindFragDataLocation + +```cpp +void BindFragDataLocation(unsigned int program, unsigned int colorNumber, const char* name) +void BindFragDataLocationIndexed(unsigned int program, unsigned int colorNumber, unsigned int index, const char* name) +``` + +设置颜色输出绑定。 + +## 查询 + +### BeginQuery / EndQuery + +```cpp +void BeginQuery(unsigned int target, unsigned int id) +void EndQuery(unsigned int target) +``` + +开始/结束查询。 + +### GetQueryObjectiv / GetQueryObjectuiv + +```cpp +void GetQueryObjectiv(unsigned int id, unsigned int pname, int* params) +void GetQueryObjectuiv(unsigned int id, unsigned int pname, unsigned int* params) +``` + +获取查询结果。 + +## Framebuffer 操作 + +### ReadPixels + +```cpp +void ReadPixels(int x, int y, int width, int height, unsigned int format, unsigned int type, void* data) +``` + +读取像素。 + +### BlitFramebuffer + +```cpp +void BlitFramebuffer(int srcX0, int srcY0, int srcX1, int srcY1, int dstX0, int dstY0, int dstX1, int dstY1, unsigned int mask, unsigned int filter) +``` + +Blit 帧缓冲区。 + +### CopyImageSubData + +```cpp +void CopyImageSubData(unsigned int srcName, unsigned int srcTarget, int srcLevel, int srcX, int srcY, int srcZ, unsigned int dstName, unsigned int dstTarget, int dstLevel, int dstX, int dstY, int dstZ, int width, int height, int depth) +``` + +复制图像子数据。 + +### InvalidateFramebuffer + +```cpp +void InvalidateFramebuffer(unsigned int target, unsigned int count, const unsigned int* attachments) +void InvalidateSubFramebuffer(unsigned int target, unsigned int count, const unsigned int* attachments, int x, int y, int width, int height) +``` + +使帧缓冲区失效。 + +## 调试 + +### PushDebugGroup / PopDebugGroup + +```cpp +void PushDebugGroup(unsigned int source, unsigned int id, int length, const char* message) +void PopDebugGroup() +``` + +推送/弹出调试组。 diff --git a/docs/api/rhi/opengl/command-list/set-blend-factor.md b/docs/api/rhi/opengl/command-list/set-blend-factor.md new file mode 100644 index 00000000..27c00f63 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-blend-factor.md @@ -0,0 +1,21 @@ +# OpenGLCommandList::SetBlendFactor + +```cpp +void SetBlendFactor(const float factor[4]) +``` + +设置混合因子。 + +**参数：** +- `factor` - 混合因子数组 [r, g, b, a] + +**示例：** + +```cpp +float factor[4] = { 1.0f, 1.0f, 1.0f, 1.0f }; +commandList->SetBlendFactor(factor); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-blend-state.md b/docs/api/rhi/opengl/command-list/set-blend-state.md new file mode 100644 index 00000000..cc0daf39 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-blend-state.md @@ -0,0 +1,24 @@ +# OpenGLCommandList::SetBlendState + +```cpp +void SetBlendState(const BlendState& state) +``` + +设置混合状态。 + +**参数：** +- `state` - 混合状态结构 + +**示例：** + +```cpp +BlendState state; +state.enable = true; +state.srcBlend = BlendFunc::SrcAlpha; +state.dstBlend = BlendFunc::InvSrcAlpha; +commandList->SetBlendState(state); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-depth-stencil-state.md b/docs/api/rhi/opengl/command-list/set-depth-stencil-state.md new file mode 100644 index 00000000..a7111ada --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-depth-stencil-state.md @@ -0,0 +1,24 @@ +# OpenGLCommandList::SetDepthStencilState + +```cpp +void SetDepthStencilState(const DepthStencilState& state) +``` + +设置深度模板状态。 + +**参数：** +- `state` - 深度模板状态结构 + +**示例：** + +```cpp +DepthStencilState state; +state.depthEnable = true; +state.depthWriteEnable = true; +state.depthFunc = ComparisonFunc::Less; +commandList->SetDepthStencilState(state); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-index-buffer.md b/docs/api/rhi/opengl/command-list/set-index-buffer.md new file mode 100644 index 00000000..12fafe2b --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-index-buffer.md @@ -0,0 +1,22 @@ +# OpenGLCommandList::SetIndexBuffer + +```cpp +void SetIndexBuffer(void* buffer, uint64_t offset, Format format) +``` + +设置索引缓冲区。 + +**参数：** +- `buffer` - 缓冲区指针 +- `offset` - 数据偏移 +- `format` - 索引格式 + +**示例：** + +```cpp +commandList->SetIndexBuffer(indexBuffer, 0, Format::R32_UINT); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-pipeline-state.md b/docs/api/rhi/opengl/command-list/set-pipeline-state.md new file mode 100644 index 00000000..a035992e --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-pipeline-state.md @@ -0,0 +1,20 @@ +# OpenGLCommandList::SetPipelineState + +```cpp +void SetPipelineState(void* pipelineState) +``` + +设置渲染管线状态。 + +**参数：** +- `pipelineState` - 管线状态对象指针 + +**示例：** + +```cpp +commandList->SetPipelineState(pipelineState); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-primitive-topology.md b/docs/api/rhi/opengl/command-list/set-primitive-topology.md new file mode 100644 index 00000000..8ddb42c1 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-primitive-topology.md @@ -0,0 +1,20 @@ +# OpenGLCommandList::SetPrimitiveTopology + +```cpp +void SetPrimitiveTopology(PrimitiveTopology topology) +``` + +设置图元拓扑类型。 + +**参数：** +- `topology` - 图元拓扑类型 + +**示例：** + +```cpp +commandList->SetPrimitiveTopology(PrimitiveTopology::TriangleList); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-render-targets.md b/docs/api/rhi/opengl/command-list/set-render-targets.md new file mode 100644 index 00000000..081eb74b --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-render-targets.md @@ -0,0 +1,23 @@ +# OpenGLCommandList::SetRenderTargets + +```cpp +void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr) +``` + +设置渲染目标。 + +**参数：** +- `count` - 渲染目标数量 +- `renderTargets` - 渲染目标指针数组 +- `depthStencil` - 深度模板缓冲区指针（可选） + +**示例：** + +```cpp +void* targets[1] = { colorTarget }; +commandList->SetRenderTargets(1, targets, depthStencil); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-scissor-rect.md b/docs/api/rhi/opengl/command-list/set-scissor-rect.md new file mode 100644 index 00000000..4434bbaa --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-scissor-rect.md @@ -0,0 +1,23 @@ +# OpenGLCommandList::SetScissorRect + +```cpp +void SetScissorRect(const Rect& rect) +``` + +设置裁剪矩形。 + +**参数：** +- `rect` - 裁剪矩形结构 + +**示例：** + +```cpp +Rect rect; +rect.x = 0; rect.y = 0; +rect.width = 800; rect.height = 600; +commandList->SetScissorRect(rect); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-scissor-rects.md b/docs/api/rhi/opengl/command-list/set-scissor-rects.md new file mode 100644 index 00000000..d3567b65 --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-scissor-rects.md @@ -0,0 +1,22 @@ +# OpenGLCommandList::SetScissorRects + +```cpp +void SetScissorRects(uint32_t count, const Rect* rects) +``` + +批量设置裁剪矩形。 + +**参数：** +- `count` - 裁剪矩形数量 +- `rects` - 裁剪矩形数组指针 + +**示例：** + +```cpp +Rect rects[2] = { ... }; +commandList->SetScissorRects(2, rects); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-stencil-ref.md b/docs/api/rhi/opengl/command-list/set-stencil-ref.md new file mode 100644 index 00000000..1227c33d --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-stencil-ref.md @@ -0,0 +1,20 @@ +# OpenGLCommandList::SetStencilRef + +```cpp +void SetStencilRef(uint8_t ref) +``` + +设置模板测试参考值。 + +**参数：** +- `ref` - 模板参考值 + +**示例：** + +```cpp +commandList->SetStencilRef(1); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-vertex-buffer.md b/docs/api/rhi/opengl/command-list/set-vertex-buffer.md new file mode 100644 index 00000000..8d1bdc0c --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-vertex-buffer.md @@ -0,0 +1,23 @@ +# OpenGLCommandList::SetVertexBuffer + +```cpp +void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride) +``` + +设置单个顶点缓冲区。 + +**参数：** +- `slot` - 顶点缓冲区槽位 +- `buffer` - 缓冲区指针 +- `offset` - 数据偏移 +- `stride` - 顶点跨度 + +**示例：** + +```cpp +commandList->SetVertexBuffer(0, vertexBuffer, 0, sizeof(Vertex)); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-vertex-buffers.md b/docs/api/rhi/opengl/command-list/set-vertex-buffers.md new file mode 100644 index 00000000..f5647ddd --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-vertex-buffers.md @@ -0,0 +1,24 @@ +# OpenGLCommandList::SetVertexBuffers + +```cpp +void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides) +``` + +批量设置顶点缓冲区。 + +**参数：** +- `startSlot` - 起始槽位 +- `count` - 缓冲区数量 +- `buffers` - 缓冲区指针数组 +- `offsets` - 偏移数组 +- `strides` - 跨度数组 + +**示例：** + +```cpp +commandList->SetVertexBuffers(0, 2, buffers, offsets, strides); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-viewport.md b/docs/api/rhi/opengl/command-list/set-viewport.md new file mode 100644 index 00000000..85a367ca --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-viewport.md @@ -0,0 +1,24 @@ +# OpenGLCommandList::SetViewport + +```cpp +void SetViewport(const Viewport& viewport) +``` + +设置视口。 + +**参数：** +- `viewport` - 视口结构 + +**示例：** + +```cpp +Viewport viewport; +viewport.x = 0; viewport.y = 0; +viewport.width = 800; viewport.height = 600; +viewport.minDepth = 0.0f; viewport.maxDepth = 1.0f; +commandList->SetViewport(viewport); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-viewports.md b/docs/api/rhi/opengl/command-list/set-viewports.md new file mode 100644 index 00000000..b513ef4f --- /dev/null +++ b/docs/api/rhi/opengl/command-list/set-viewports.md @@ -0,0 +1,22 @@ +# OpenGLCommandList::SetViewports + +```cpp +void SetViewports(uint32_t count, const Viewport* viewports) +``` + +批量设置视口。 + +**参数：** +- `count` - 视口数量 +- `viewports` - 视口数组指针 + +**示例：** + +```cpp +Viewport viewports[2] = { ... }; +commandList->SetViewports(2, viewports); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/transition-barrier.md b/docs/api/rhi/opengl/command-list/transition-barrier.md new file mode 100644 index 00000000..0e4dda1c --- /dev/null +++ b/docs/api/rhi/opengl/command-list/transition-barrier.md @@ -0,0 +1,22 @@ +# OpenGLCommandList::TransitionBarrier + +```cpp +void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter) +``` + +设置资源状态转换屏障。 + +**参数：** +- `resource` - 资源指针 +- `stateBefore` - 转换前状态 +- `stateAfter` - 转换后状态 + +**示例：** + +```cpp +commandList->TransitionBarrier(texture, ResourceStates::RenderTarget, ResourceStates::Common); +``` + +## 相关文档 + +- [OpenGLCommandList](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-queue/command-queue.md b/docs/api/rhi/opengl/command-queue/command-queue.md new file mode 100644 index 00000000..3416e7b0 --- /dev/null +++ b/docs/api/rhi/opengl/command-queue/command-queue.md @@ -0,0 +1,24 @@ +# OpenGLCommandQueue + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 命令队列实现，继承自 `RHICommandQueue`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `ExecuteCommandLists` | [详细文档](execute-command-lists.md) | +| `Signal` | [详细文档](signal.md) | +| `Wait` | [详细文档](../../../threading/task-group/wait.md) | +| `GetCompletedValue` | [详细文档](get-completed-value.md) | +| `WaitForIdle` | [详细文档](wait-for-idle.md) | +| `GetType` | [详细文档](../../shader/get-type.md) | +| `GetTimestampFrequency` | [详细文档](get-timestamp-frequency.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) +- [RHICommandQueue](../../command-queue/command-queue.md) - 抽象命令队列接口 diff --git a/docs/api/rhi/opengl/command-queue/execute-command-lists.md b/docs/api/rhi/opengl/command-queue/execute-command-lists.md new file mode 100644 index 00000000..60ad7d57 --- /dev/null +++ b/docs/api/rhi/opengl/command-queue/execute-command-lists.md @@ -0,0 +1,22 @@ +# OpenGLCommandQueue::ExecuteCommandLists + +```cpp +void ExecuteCommandLists(uint32_t count, void** lists) +``` + +执行命令列表。 + +**参数：** +- `count` - 命令列表数量 +- `lists` - 命令列表指针数组 + +**示例：** + +```cpp +void* lists[] = { commandList }; +commandQueue->ExecuteCommandLists(1, lists); +``` + +## 相关文档 + +- [OpenGLCommandQueue](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-queue/get-completed-value.md b/docs/api/rhi/opengl/command-queue/get-completed-value.md new file mode 100644 index 00000000..d1107187 --- /dev/null +++ b/docs/api/rhi/opengl/command-queue/get-completed-value.md @@ -0,0 +1,19 @@ +# OpenGLCommandQueue::GetCompletedValue + +```cpp +uint64_t GetCompletedValue() +``` + +获取已完成的值。 + +**返回：** 已完成的围栏值 + +**示例：** + +```cpp +uint64_t value = commandQueue->GetCompletedValue(); +``` + +## 相关文档 + +- [OpenGLCommandQueue](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-queue/get-timestamp-frequency.md b/docs/api/rhi/opengl/command-queue/get-timestamp-frequency.md new file mode 100644 index 00000000..a21eb792 --- /dev/null +++ b/docs/api/rhi/opengl/command-queue/get-timestamp-frequency.md @@ -0,0 +1,19 @@ +# OpenGLCommandQueue::GetTimestampFrequency + +```cpp +uint64_t GetTimestampFrequency() const +``` + +获取时间戳频率。 + +**返回：** 时间戳频率（Hz） + +**示例：** + +```cpp +uint64_t frequency = commandQueue->GetTimestampFrequency(); +``` + +## 相关文档 + +- [OpenGLCommandQueue](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-queue/signal.md b/docs/api/rhi/opengl/command-queue/signal.md new file mode 100644 index 00000000..282b43a0 --- /dev/null +++ b/docs/api/rhi/opengl/command-queue/signal.md @@ -0,0 +1,21 @@ +# OpenGLCommandQueue::Signal + +```cpp +void Signal(RHIFence* fence, uint64_t value) +``` + +发送信号。 + +**参数：** +- `fence` - 围栏指针 +- `value` - 信号值 + +**示例：** + +```cpp +commandQueue->Signal(fence, 1); +``` + +## 相关文档 + +- [OpenGLCommandQueue](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-queue/wait-for-idle.md b/docs/api/rhi/opengl/command-queue/wait-for-idle.md new file mode 100644 index 00000000..7175e75a --- /dev/null +++ b/docs/api/rhi/opengl/command-queue/wait-for-idle.md @@ -0,0 +1,17 @@ +# OpenGLCommandQueue::WaitForIdle + +```cpp +void WaitForIdle() +``` + +等待命令队列空闲。 + +**示例：** + +```cpp +commandQueue->WaitForIdle(); +``` + +## 相关文档 + +- [OpenGLCommandQueue](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/bind-framebuffer.md b/docs/api/rhi/opengl/depth-stencil-view/bind-framebuffer.md new file mode 100644 index 00000000..a737aa4b --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/bind-framebuffer.md @@ -0,0 +1,20 @@ +# OpenGLDepthStencilView::BindFramebuffer + +```cpp +static void BindFramebuffer(unsigned int framebuffer) +``` + +静态方法，将指定帧缓冲区绑定为当前深度模板帧缓冲区。 + +**参数：** +- `framebuffer` - 帧缓冲区 ID（0 表示解除绑定） + +**示例：** + +```cpp +OpenGLDepthStencilView::BindFramebuffer(dsv.GetFramebuffer()); +``` + +## 相关文档 + +- [OpenGLDepthStencilView](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/clear-depth-stencil.md b/docs/api/rhi/opengl/depth-stencil-view/clear-depth-stencil.md new file mode 100644 index 00000000..5f3f191f --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/clear-depth-stencil.md @@ -0,0 +1,21 @@ +# OpenGLDepthStencilView::ClearDepthStencil + +```cpp +void ClearDepthStencil(float depth, uint8_t stencil) +``` + +同时清除深度和模板缓冲区。 + +**参数：** +- `depth` - 深度值（通常为 0.0 到 1.0） +- `stencil` - 模板值（0-255） + +**示例：** + +```cpp +dsv.ClearDepthStencil(1.0f, 0); +``` + +## 相关文档 + +- [OpenGLDepthStencilView](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/clear-depth.md b/docs/api/rhi/opengl/depth-stencil-view/clear-depth.md new file mode 100644 index 00000000..8292a28a --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/clear-depth.md @@ -0,0 +1,20 @@ +# OpenGLDepthStencilView::ClearDepth + +```cpp +void ClearDepth(float depth) +``` + +清除深度缓冲区的深度值。 + +**参数：** +- `depth` - 深度值（通常为 0.0 到 1.0） + +**示例：** + +```cpp +dsv.ClearDepth(1.0f); +``` + +## 相关文档 + +- [OpenGLDepthStencilView](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/clear-stencil.md b/docs/api/rhi/opengl/depth-stencil-view/clear-stencil.md new file mode 100644 index 00000000..bca7b5d2 --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/clear-stencil.md @@ -0,0 +1,20 @@ +# OpenGLDepthStencilView::ClearStencil + +```cpp +void ClearStencil(uint8_t stencil) +``` + +清除模板缓冲区的模板值。 + +**参数：** +- `stencil` - 模板值（0-255） + +**示例：** + +```cpp +dsv.ClearStencil(0); +``` + +## 相关文档 + +- [OpenGLDepthStencilView](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md new file mode 100644 index 00000000..f2bd0c3a --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md @@ -0,0 +1,28 @@ +# OpenGLDepthStencilView + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 深度模板视图实现。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `InitializeCubemap` | [详细文档](initialize-cubemap.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Bind` | [详细文档](../../shader/bind.md) | +| `Unbind` | [详细文档](../../shader/unbind.md) | +| `ClearDepth` | [详细文档](clear-depth.md) | +| `ClearStencil` | [详细文档](clear-stencil.md) | +| `ClearDepthStencil` | [详细文档](clear-depth-stencil.md) | +| `GetFramebuffer` | [详细文档](get-framebuffer.md) | +| `GetTexture` | [详细文档](get-texture.md) | +| `GetMipLevel` | [详细文档](get-mip-level.md) | +| `GetWidth` / `GetHeight` | [详细文档](../../buffer/get-size.md) | +| `BindFramebuffer` | [详细文档](bind-framebuffer.md) | +| `UnbindFramebuffer` | [详细文档](unbind-framebuffer.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) diff --git a/docs/api/rhi/opengl/depth-stencil-view/get-framebuffer.md b/docs/api/rhi/opengl/depth-stencil-view/get-framebuffer.md new file mode 100644 index 00000000..940b5a1b --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/get-framebuffer.md @@ -0,0 +1,19 @@ +# OpenGLDepthStencilView::GetFramebuffer + +```cpp +unsigned int GetFramebuffer() const +``` + +获取帧缓冲区对象 ID。 + +**返回：** `unsigned int` - 帧缓冲区 ID + +**示例：** + +```cpp +unsigned int fbo = dsv.GetFramebuffer(); +``` + +## 相关文档 + +- [OpenGLDepthStencilView](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/get-mip-level.md b/docs/api/rhi/opengl/depth-stencil-view/get-mip-level.md new file mode 100644 index 00000000..bc7cfce0 --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/get-mip-level.md @@ -0,0 +1,19 @@ +# OpenGLDepthStencilView::GetMipLevel + +```cpp +int GetMipLevel() const +``` + +获取 mipmap 级别。 + +**返回：** `int` - mip 级别 + +**示例：** + +```cpp +int mipLevel = dsv.GetMipLevel(); +``` + +## 相关文档 + +- [OpenGLDepthStencilView](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/get-texture.md b/docs/api/rhi/opengl/depth-stencil-view/get-texture.md new file mode 100644 index 00000000..7958415f --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/get-texture.md @@ -0,0 +1,19 @@ +# OpenGLDepthStencilView::GetTexture + +```cpp +unsigned int GetTexture() const +``` + +获取关联的纹理对象 ID。 + +**返回：** `unsigned int` - 纹理 ID + +**示例：** + +```cpp +unsigned int tex = dsv.GetTexture(); +``` + +## 相关文档 + +- [OpenGLDepthStencilView](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/initialize-cubemap.md b/docs/api/rhi/opengl/depth-stencil-view/initialize-cubemap.md new file mode 100644 index 00000000..40a5d861 --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/initialize-cubemap.md @@ -0,0 +1,25 @@ +# OpenGLDepthStencilView::InitializeCubemap + +```cpp +bool InitializeCubemap(unsigned int cubemap, int face, int mipLevel = 0) +``` + +初始化立方体贴图的深度模板视图。 + +**参数：** +- `cubemap` - 立方体贴图对象 ID +- `face` - 立方体贴面索引（0-5） +- `mipLevel` - mipmap 级别（默认为 0） + +**返回：** `bool` - 成功返回 true，失败返回 false + +**示例：** + +```cpp +OpenGLDepthStencilView dsv; +dsv.InitializeCubemap(cubemapTexture, 0, 0); +``` + +## 相关文档 + +- [OpenGLDepthStencilView](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/unbind-framebuffer.md b/docs/api/rhi/opengl/depth-stencil-view/unbind-framebuffer.md new file mode 100644 index 00000000..a686aa0b --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/unbind-framebuffer.md @@ -0,0 +1,17 @@ +# OpenGLDepthStencilView::UnbindFramebuffer + +```cpp +static void UnbindFramebuffer() +``` + +静态方法，解除当前深度模板帧缓冲区的绑定。 + +**示例：** + +```cpp +OpenGLDepthStencilView::UnbindFramebuffer(); +``` + +## 相关文档 + +- [OpenGLDepthStencilView](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/device/create-render-window.md b/docs/api/rhi/opengl/device/create-render-window.md new file mode 100644 index 00000000..24a800bb --- /dev/null +++ b/docs/api/rhi/opengl/device/create-render-window.md @@ -0,0 +1,28 @@ +# OpenGLDevice::CreateRenderWindow + +```cpp +bool CreateRenderWindow(int width, int height, const char* title, bool enableDebug = false) +``` + +创建并初始化一个新的 GLFW 窗口，同时初始化 OpenGL 上下文。 + +**参数：** +- `width` - 窗口宽度（像素） +- `height` - 窗口高度（像素） +- `title` - 窗口标题 +- `enableDebug` - 是否启用 OpenGL 调试上下文（可选，默认为 false） + +**返回：** `bool` - 成功返回 true，失败返回 false + +**示例：** + +```cpp +OpenGLDevice device; +if (device.CreateRenderWindow(1280, 720, "XCEngine", false)) { + // 窗口创建成功，可以开始渲染循环 +} +``` + +## 相关文档 + +- [OpenGLDevice](device.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/device/device.md b/docs/api/rhi/opengl/device/device.md new file mode 100644 index 00000000..80dcd430 --- /dev/null +++ b/docs/api/rhi/opengl/device/device.md @@ -0,0 +1,37 @@ +# OpenGLDevice + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 设备的实现，继承自 `RHIDevice`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `CreateRenderWindow` | [详细文档](create-render-window.md) | +| `InitializeWithExistingWindow` | [详细文档](initialize-with-existing-window.md) | +| `GetWindow` | [详细文档](get-window.md) | +| `SwapBuffers` | [详细文档](swap-buffers.md) | +| `PollEvents` | [详细文档](poll-events.md) | +| `SetShouldClose` | [详细文档](set-should-close.md) | +| `ShouldClose` | [详细文档](should-close.md) | +| `CreateBuffer` | [详细文档](../../device/create-buffer.md) | +| `CreateTexture` | [详细文档](../../device/create-texture.md) | +| `CreateSwapChain` | [详细文档](../../device/create-swap-chain.md) | +| `CreateCommandList` | [详细文档](../../device/create-command-list.md) | +| `CreateCommandQueue` | [详细文档](../../device/create-command-queue.md) | +| `CompileShader` | [详细文档](../../device/compile-shader.md) | +| `CreatePipelineState` | [详细文档](../../device/create-pipeline-state.md) | +| `CreateFence` | [详细文档](../../device/create-fence.md) | +| `CreateSampler` | [详细文档](../../device/create-sampler.md) | +| `GetCapabilities` | [详细文档](../../device/get-capabilities.md) | +| `GetDeviceInfo` | [详细文档](../../device/get-device-info.md) | +| `GetNativeDevice` | [详细文档](../../device/get-native-device.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) +- [RHIDevice](../../device/device.md) - 抽象设备接口 diff --git a/docs/api/rhi/opengl/device/get-window.md b/docs/api/rhi/opengl/device/get-window.md new file mode 100644 index 00000000..288b5da2 --- /dev/null +++ b/docs/api/rhi/opengl/device/get-window.md @@ -0,0 +1,22 @@ +# OpenGLDevice::GetWindow + +```cpp +GLFWwindow* GetWindow() const +``` + +获取关联的 GLFW 窗口指针。 + +**返回：** `GLFWwindow*` - GLFW 窗口指针 + +**示例：** + +```cpp +GLFWwindow* window = device.GetWindow(); +if (window) { + glfwSetWindowTitle(window, "New Title"); +} +``` + +## 相关文档 + +- [OpenGLDevice](device.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/device/initialize-with-existing-window.md b/docs/api/rhi/opengl/device/initialize-with-existing-window.md new file mode 100644 index 00000000..939fd699 --- /dev/null +++ b/docs/api/rhi/opengl/device/initialize-with-existing-window.md @@ -0,0 +1,26 @@ +# OpenGLDevice::InitializeWithExistingWindow + +```cpp +bool InitializeWithExistingWindow(GLFWwindow* window) +``` + +使用已有的 GLFW 窗口初始化 OpenGL 设备，不会创建新窗口或管理窗口生命周期。 + +**参数：** +- `window` - 已存在的 GLFWwindow 指针 + +**返回：** `bool` - 成功返回 true，失败返回 false + +**示例：** + +```cpp +GLFWwindow* existingWindow = glfwCreateWindow(1280, 720, "Existing", nullptr, nullptr); +OpenGLDevice device; +if (device.InitializeWithExistingWindow(existingWindow)) { + // 使用已有窗口初始化设备 +} +``` + +## 相关文档 + +- [OpenGLDevice](device.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/device/poll-events.md b/docs/api/rhi/opengl/device/poll-events.md new file mode 100644 index 00000000..4d26430a --- /dev/null +++ b/docs/api/rhi/opengl/device/poll-events.md @@ -0,0 +1,23 @@ +# OpenGLDevice::PollEvents + +```cpp +bool PollEvents() +``` + +处理所有挂起的 GLFW 事件（窗口事件、输入事件等）。 + +**返回：** `bool` - 如果窗口应保持打开返回 true，如果窗口应关闭返回 false + +**示例：** + +```cpp +while (device.PollEvents()) { + // 渲染和交换缓冲区 + renderScene(); + device.SwapBuffers(); +} +``` + +## 相关文档 + +- [OpenGLDevice](device.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/device/set-should-close.md b/docs/api/rhi/opengl/device/set-should-close.md new file mode 100644 index 00000000..3cc22124 --- /dev/null +++ b/docs/api/rhi/opengl/device/set-should-close.md @@ -0,0 +1,20 @@ +# OpenGLDevice::SetShouldClose + +```cpp +void SetShouldClose(bool shouldClose) +``` + +设置窗口是否应该关闭的标志。 + +**参数：** +- `shouldClose` - true 表示窗口应该关闭，false 表示保持打开 + +**示例：** + +```cpp +device.SetShouldClose(true); // 请求关闭窗口 +``` + +## 相关文档 + +- [OpenGLDevice](device.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/device/should-close.md b/docs/api/rhi/opengl/device/should-close.md new file mode 100644 index 00000000..c75d4f5b --- /dev/null +++ b/docs/api/rhi/opengl/device/should-close.md @@ -0,0 +1,23 @@ +# OpenGLDevice::ShouldClose + +```cpp +bool ShouldClose() const +``` + +检查窗口是否应该关闭。 + +**返回：** `bool` - 如果窗口应该关闭返回 true，否则返回 false + +**示例：** + +```cpp +while (!device.ShouldClose()) { + device.PollEvents(); + renderScene(); + device.SwapBuffers(); +} +``` + +## 相关文档 + +- [OpenGLDevice](device.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/device/swap-buffers.md b/docs/api/rhi/opengl/device/swap-buffers.md new file mode 100644 index 00000000..444d30d7 --- /dev/null +++ b/docs/api/rhi/opengl/device/swap-buffers.md @@ -0,0 +1,19 @@ +# OpenGLDevice::SwapBuffers + +```cpp +void SwapBuffers() +``` + +交换前后缓冲区，将渲染内容显示到屏幕上。 + +**示例：** + +```cpp +// 渲染完成后交换缓冲区 +renderScene(); +device.SwapBuffers(); +``` + +## 相关文档 + +- [OpenGLDevice](device.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/fence/fence.md b/docs/api/rhi/opengl/fence/fence.md new file mode 100644 index 00000000..be4057cd --- /dev/null +++ b/docs/api/rhi/opengl/fence/fence.md @@ -0,0 +1,25 @@ +# OpenGLFence + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 栅栏同步实现，继承自 `RHIFence`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Signal` | [详细文档](signal.md) | +| `Wait` | [详细文档](../../../threading/task-group/wait.md) | +| `Reset` | [详细文档](../../../resources/resourcehandle/reset.md) | +| `IsSignaled` | [详细文档](is-signaled.md) | +| `GetStatus` | [详细文档](get-status.md) | +| `GetCompletedValue` | [详细文档](get-completed-value.md) | +| `GetCurrentValue` | [详细文档](get-current-value.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) +- [RHIFence](../../fence/fence.md) - 抽象栅栏接口 diff --git a/docs/api/rhi/opengl/fence/get-completed-value.md b/docs/api/rhi/opengl/fence/get-completed-value.md new file mode 100644 index 00000000..0d03ce1c --- /dev/null +++ b/docs/api/rhi/opengl/fence/get-completed-value.md @@ -0,0 +1,19 @@ +# OpenGLFence::GetCompletedValue + +```cpp +uint64_t GetCompletedValue() const override +``` + +获取已完成的最大栅栏值。 + +**返回：** `uint64_t` - 已完成的栅栏值 + +**示例：** + +```cpp +uint64_t completed = fence.GetCompletedValue(); +``` + +## 相关文档 + +- [OpenGLFence](fence.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/fence/get-current-value.md b/docs/api/rhi/opengl/fence/get-current-value.md new file mode 100644 index 00000000..22433f9f --- /dev/null +++ b/docs/api/rhi/opengl/fence/get-current-value.md @@ -0,0 +1,19 @@ +# OpenGLFence::GetCurrentValue + +```cpp +uint64_t GetCurrentValue() const +``` + +获取栅栏的当前值。 + +**返回：** `uint64_t` - 当前栅栏值 + +**示例：** + +```cpp +uint64_t current = fence.GetCurrentValue(); +``` + +## 相关文档 + +- [OpenGLFence](fence.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/fence/get-status.md b/docs/api/rhi/opengl/fence/get-status.md new file mode 100644 index 00000000..e9412168 --- /dev/null +++ b/docs/api/rhi/opengl/fence/get-status.md @@ -0,0 +1,25 @@ +# OpenGLFence::GetStatus + +```cpp +FenceStatus GetStatus() const +``` + +获取栅栏的当前状态。 + +**返回：** `FenceStatus` - 栅栏状态，可能的值： +- `FenceStatus::Signaled` - 栅栏已signaled +- `FenceStatus::Unsignaled` - 栅栏未signaled +- `FenceStatus::Error` - 发生错误 + +**示例：** + +```cpp +FenceStatus status = fence.GetStatus(); +if (status == FenceStatus::Signaled) { + // 操作已完成 +} +``` + +## 相关文档 + +- [OpenGLFence](fence.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/fence/is-signaled.md b/docs/api/rhi/opengl/fence/is-signaled.md new file mode 100644 index 00000000..8ec86c88 --- /dev/null +++ b/docs/api/rhi/opengl/fence/is-signaled.md @@ -0,0 +1,21 @@ +# OpenGLFence::IsSignaled + +```cpp +bool IsSignaled() const override +``` + +检查栅栏是否处于 signaled 状态。 + +**返回：** `bool` - 如果栅栏已signaled返回 true，否则返回 false + +**示例：** + +```cpp +if (fence.IsSignaled()) { + // 可以安全地继续执行 +} +``` + +## 相关文档 + +- [OpenGLFence](fence.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/fence/signal.md b/docs/api/rhi/opengl/fence/signal.md new file mode 100644 index 00000000..52eb47a6 --- /dev/null +++ b/docs/api/rhi/opengl/fence/signal.md @@ -0,0 +1,20 @@ +# OpenGLFence::Signal + +```cpp +void Signal() override +void Signal(uint64_t value) override +``` + +将栅栏设置为 signaled 状态，通知等待的线程操作完成。 + +**示例：** + +```cpp +OpenGLFence fence; +fence.Initialize(false); +fence.Signal(); +``` + +## 相关文档 + +- [OpenGLFence](fence.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/opengl-buffer.md b/docs/api/rhi/opengl/opengl-buffer.md deleted file mode 100644 index 546e4fd4..00000000 --- a/docs/api/rhi/opengl/opengl-buffer.md +++ /dev/null @@ -1,135 +0,0 @@ -# OpenGLBuffer - -OpenGL 缓冲区的实现，封装 OpenGL buffer object。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHIBuffer (interface) -└── OpenGLBuffer (implementation) -``` - -## OpenGLBufferType 枚举 - -| 值 | 描述 | -|----|------| -| `Vertex` | 顶点缓冲区 | -| `Index` | 索引缓冲区 | -| `Uniform` | Uniform 缓冲区 (UBO) | -| `CopyRead` | 复制源缓冲区 | -| `CopyWrite` | 复制目标缓冲区 | -| `AtomicCounter` | 原子计数器缓冲区 | -| `DispatchIndirect` | 间接计算调用缓冲区 | -| `DrawIndirect` | 间接绘制缓冲区 | -| `ShaderBindingTable` | 光线追踪 Shader 绑定表 | - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `OpenGLBuffer()` - -#### `~OpenGLBuffer() override` - -### 初始化 - -#### `bool Initialize(OpenGLBufferType type, size_t size, const void* data = nullptr, bool dynamic = false)` -通用初始化。 -- `type`: 缓冲区类型 -- `size`: 大小（字节） -- `data`: 初始数据（可选） -- `dynamic`: 是否动态更新 - -#### `bool InitializeVertexBuffer(const void* data, size_t size)` -初始化顶点缓冲区。 - -#### `bool InitializeIndexBuffer(const void* data, size_t size)` -初始化索引缓冲区。 - -#### `void Shutdown() override` - -### 绑定操作 - -#### `void Bind() const` -绑定缓冲区到当前 target。 - -#### `void Unbind() const` -解除绑定。 - -#### `void BindBase(unsigned int target, unsigned int index) const` -绑定到指定的 binding point（用于 UBO、SSBO 等）。 - -### 数据操作 - -#### `void* Map() override` -映射缓冲区到 CPU。 - -#### `void Unmap() override` -解除映射。 - -#### `void SetData(const void* data, size_t size, size_t offset = 0) override` -更新缓冲区数据。 - -### 属性 - -#### `unsigned int GetID() const` -获取 OpenGL buffer ID。 - -#### `uint64_t GetSize() const override` -获取缓冲区大小。 - -#### `OpenGLBufferType GetType() const` -获取缓冲区类型。 - -#### `bool IsDynamic() const` -是否动态缓冲区。 - -#### `BufferType GetBufferType() const override / void SetBufferType(BufferType type) override` - -#### `uint32_t GetStride() const override / void SetStride(uint32_t stride) override` - -#### `void* GetNativeHandle() override` -返回 `reinterpret_cast(static_cast(m_buffer))` - -#### `ResourceStates GetState() const override` -返回 `ResourceStates::Common`（OpenGL 无显式状态） - -#### `const std::string& GetName() const override / void SetName(...) override` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_buffer` | `unsigned int` | GL buffer ID | -| `m_size` | `size_t` | 大小 | -| `m_isIndexBuffer` | `bool` | 是否索引缓冲区 | -| `m_dynamic` | `bool` | 是否动态 | -| `m_type` | `OpenGLBufferType` | 缓冲区类型 | -| `m_bufferType` | `BufferType` | RHI 缓冲区类型 | -| `m_stride` | `uint32_t` | 顶点步长 | -| `m_name` | `std::string` | 名称 | - -## 使用示例 - -```cpp -OpenGLBuffer vb; -float vertices[] = { ... }; -vb.InitializeVertexBuffer(vertices, sizeof(vertices)); -vb.SetBufferType(BufferType::Vertex); -vb.SetStride(sizeof(float) * 5); - -OpenGLBuffer ib; -uint16_t indices[] = { 0, 1, 2, ... }; -ib.InitializeIndexBuffer(indices, sizeof(indices)); - -// Bind and draw -vb.Bind(); -ib.Bind(); -glDrawElements(GL_TRIANGLES, indexCount, GL_UNSIGNED_SHORT, 0); -``` diff --git a/docs/api/rhi/opengl/opengl-command-list.md b/docs/api/rhi/opengl/opengl-command-list.md deleted file mode 100644 index 9c89ff2f..00000000 --- a/docs/api/rhi/opengl/opengl-command-list.md +++ /dev/null @@ -1,308 +0,0 @@ -# OpenGLCommandList - -OpenGL 命令列表实现。OpenGL 是立即模式 API，此类提供命令录制和批量提交的能力。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHICommandList (interface) -└── OpenGLCommandList (implementation) -``` - -## 枚举 - -### PrimitiveType - -| 值 | OpenGL 常量 | -|----|-------------| -| `Points` | `GL_POINTS` | -| `Lines` | `GL_LINES` | -| `LineStrip` | `GL_LINE_STRIP` | -| `Triangles` | `GL_TRIANGLES` | -| `TriangleStrip` | `GL_TRIANGLE_STRIP` | -| `TriangleFan` | `GL_TRIANGLE_FAN` | -| `LineListAdj` | `GL_LINES_ADJACENCY` | -| `TriangleListAdj` | `GL_TRIANGLES_ADJACENCY` | -| `Patch` | `GL_PATCHES` | - -### ClearFlag - -| 值 | 描述 | -|----|------| -| `Color` | 清除颜色缓冲区 | -| `Depth` | 清除深度缓冲区 | -| `Stencil` | 清除模板缓冲区 | - -支持 `|` 操作符合并。 - -## 公共成员函数 - -### 生命周期 - -#### `void Shutdown() override` - -#### `void Reset() override` -重置命令列表。 - -#### `void Close() override` -关闭命令列表。 - -### 清除操作 - -#### `void Clear(float r, float g, float b, float a, unsigned int buffers)` -清除指定缓冲区。 - -#### `void ClearColor(float r, float g, float b, float a)` - -#### `void ClearDepth(float depth)` - -#### `void ClearStencil(int stencil)` - -#### `void ClearDepthStencil(float depth, int stencil)` - -### RHI 接口实现 - -#### `void SetPipelineState(void* pipelineState) override` - -#### `void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride) override` - -#### `void SetVertexBuffers(uint32_t startSlot, uint32_t count, ...) override` - -#### `void SetIndexBuffer(void* buffer, uint64_t offset, Format format) override` - -#### `void TransitionBarrier(void* resource, ...) override` -OpenGL 实现为空（无显式状态管理）。 - -#### `void SetPrimitiveTopology(PrimitiveTopology topology) override` - -#### `void SetViewport(const Viewport& viewport) override` - -#### `void SetViewports(uint32_t count, const Viewport* viewports) override` - -#### `void SetScissorRect(const Rect& rect) override` - -#### `void SetScissorRects(uint32_t count, const Rect* rects) override` - -#### `void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil) override` - -#### `void SetDepthStencilState(const DepthStencilState& state) override` - -#### `void SetStencilRef(uint8_t ref) override` - -#### `void SetBlendState(const BlendState& state) override` - -#### `void SetBlendFactor(const float factor[4]) override` - -#### `void ClearRenderTarget(void* renderTarget, const float color[4]) override` - -#### `void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) override` - -#### `void Draw(uint32_t vertexCount, uint32_t instanceCount, uint32_t startVertex, uint32_t startInstance) override` - -#### `void DrawIndexed(uint32_t indexCount, uint32_t instanceCount, uint32_t startIndex, int32_t baseVertex, uint32_t startInstance) override` - -#### `void Dispatch(uint32_t x, uint32_t y, uint32_t z) override` - -#### `void CopyResource(void* dst, void* src) override` - -### OpenGL 特有方法 - -#### `void SetVertexBuffer(unsigned int buffer, size_t offset, size_t stride)` -直接设置顶点缓冲区（OpenGL 逃逸）。 - -#### `void SetVertexBuffers(unsigned int startSlot, unsigned int count, const unsigned int* buffers, const size_t* offsets, const size_t* strides)` - -#### `void SetIndexBuffer(unsigned int buffer, unsigned int type)` - -#### `void SetIndexBuffer(unsigned int buffer, unsigned int type, size_t offset)` - -#### `void BindVertexArray(unsigned int vao)` - -#### `void BindVertexArray(unsigned int vao, unsigned int indexBuffer, unsigned int indexType)` - -#### `void UseShader(unsigned int program)` - -### 视口与裁剪 - -#### `void SetViewport(int x, int y, int width, int height)` - -#### `void SetViewport(float x, float y, float width, float height, float minDepth, float maxDepth)` - -#### `void SetViewports(unsigned int count, const float* viewports)` - -#### `void SetScissor(int x, int y, int width, int height)` - -#### `void SetScissorRects(unsigned int count, const int* rects)` - -#### `void EnableScissorTest(bool enable)` - -### 深度测试 - -#### `void EnableDepthTest(bool enable)` - -#### `void EnableDepthWrite(bool enable)` - -#### `void SetDepthFunc(unsigned int func)` - -### 模板测试 - -#### `void EnableStencilTest(bool enable)` - -#### `void SetStencilFunc(unsigned int func, int ref, unsigned int mask)` - -#### `void SetStencilOp(unsigned int fail, unsigned int zfail, unsigned int zpass)` - -### 混合 - -#### `void EnableBlending(bool enable)` - -#### `void SetBlendFunc(unsigned int src, unsigned int dst)` - -#### `void SetBlendFuncSeparate(unsigned int srcRGB, unsigned int dstRGB, unsigned int srcAlpha, unsigned int dstAlpha)` - -#### `void SetBlendEquation(unsigned int mode)` - -#### `void SetBlendColor(float r, float g, float b, float a)` - -### 光栅化 - -#### `void EnableCulling(bool enable)` - -#### `void SetCullFace(unsigned int face)` - -#### `void SetFrontFace(unsigned int face)` - -#### `void SetPolygonMode(unsigned int mode)` - -#### `void SetPolygonOffset(float factor, float units)` - -#### `void SetPrimitiveType(PrimitiveType type)` - -### 绘制 - -#### `void Draw(PrimitiveType type, unsigned int vertexCount, unsigned int startVertex)` - -#### `void DrawInstanced(PrimitiveType type, unsigned int vertexCount, unsigned int instanceCount, unsigned int startVertex, unsigned int startInstance)` - -#### `void DrawIndexed(PrimitiveType type, unsigned int indexCount, unsigned int startIndex, int baseVertex)` - -#### `void DrawIndexedInstanced(PrimitiveType type, unsigned int indexCount, unsigned int instanceCount, unsigned int startIndex, int baseVertex, unsigned int startInstance)` - -#### `void DrawIndirect(...)` - -#### `void DrawIndexedIndirect(...)` - -#### `void MultiDrawArrays(PrimitiveType type, const int* first, const int* count, unsigned int drawCount)` - -#### `void MultiDrawElements(...)` - -### 计算着色器 - -#### `void DispatchIndirect(unsigned int buffer, size_t offset)` - -#### `void DispatchCompute(unsigned int x, unsigned int y, unsigned int z, unsigned int groupX, unsigned int groupY, unsigned int groupZ)` - -### 内存屏障 - -#### `void MemoryBarrier(unsigned int barriers)` - -#### `void TextureBarrier()` - -### 纹理绑定 - -#### `void BindTexture(unsigned int target, unsigned int unit, unsigned int texture)` - -#### `void BindTextures(unsigned int first, unsigned int count, const unsigned int* textures)` - -#### `void BindSampler(unsigned int unit, unsigned int sampler)` - -#### `void BindSamplers(unsigned int first, unsigned int count, const unsigned int* samplers)` - -#### `void BindImageTexture(...)` - -### 缓冲区绑定 - -#### `void BindBufferBase(unsigned int target, unsigned int index, unsigned int buffer)` - -#### `void BindBufferRange(unsigned int target, unsigned int index, unsigned int buffer, size_t offset, size_t size)` - -### OpenGL 状态 - -#### `void Enable(unsigned int cap)` - -#### `void Disable(unsigned int cap)` - -#### `void Enablei(unsigned int cap, unsigned int index)` - -#### `void Disablei(unsigned int cap, unsigned int index)` - -### Uniform 设置 - -#### `void SetUniform1i(int location, int v)` - -#### `void SetUniform1f(int location, float v)` - -#### `void SetUniform2f(int location, float x, float y)` - -#### `void SetUniform3f(int location, float x, float y, float z)` - -#### `void SetUniform4f(int location, float x, float y, float z, float w)` - -#### `void SetUniform1fv(int location, int count, const float* v)` - -#### `void SetUniform2fv/3fv/4fv` - -#### `void SetUniformMatrix4fv(int location, int count, bool transpose, const float* v)` - -### Shader 程序 - -#### `void UseProgram(unsigned int program)` - -#### `void BindFragDataLocation(unsigned int program, unsigned int colorNumber, const char* name)` - -#### `void BindFragDataLocationIndexed(...)` - -### 查询 - -#### `void BeginQuery(unsigned int target, unsigned int id)` - -#### `void EndQuery(unsigned int target)` - -#### `void GetQueryObjectiv/GetQueryObjectuiv` - -### Framebuffer 操作 - -#### `void ReadPixels(int x, int y, int width, int height, unsigned int format, unsigned int type, void* data)` - -#### `void BlitFramebuffer(...)` - -#### `void CopyImageSubData(...)` - -#### `void InvalidateFramebuffer(unsigned int target, unsigned int count, const unsigned int* attachments)` - -#### `void InvalidateSubFramebuffer(...)` - -### 调试 - -#### `void PushDebugGroup(unsigned int source, unsigned int id, int length, const char* message)` - -#### `void PopDebugGroup()` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_primitiveType` | `unsigned int` | 当前图元类型 | -| `m_currentVAO` | `unsigned int` | 当前 VAO | -| `m_currentProgram` | `unsigned int` | 当前 program | - -## 备注 - -- OpenGL 是立即模式 API，`OpenGLCommandList` 主要用于状态批处理 -- `Reset()` 和 `Close()` 是可选的，可直接调用 GL 命令 diff --git a/docs/api/rhi/opengl/opengl-command-queue.md b/docs/api/rhi/opengl/opengl-command-queue.md deleted file mode 100644 index 29548aa8..00000000 --- a/docs/api/rhi/opengl/opengl-command-queue.md +++ /dev/null @@ -1,63 +0,0 @@ -# OpenGLCommandQueue - -OpenGL 命令队列实现。OpenGL 是立即模式 API，此类主要提供 RHI 接口兼容。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHICommandQueue (interface) -└── OpenGLCommandQueue (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `OpenGLCommandQueue()` - -#### `~OpenGLCommandQueue() override` - -### 生命周期 - -#### `void Shutdown() override` - -### 命令执行 - -#### `void ExecuteCommandLists(uint32_t count, void** lists) override` -执行命令列表（OpenGL 下为 no-op，直接调用 GL 命令）。 - -### 同步 - -#### `void Signal(RHIFence* fence, uint64_t value) override` -发送信号。 - -#### `void Wait(RHIFence* fence, uint64_t value) override` -等待栅栏。 - -#### `uint64_t GetCompletedValue() override` - -#### `void WaitForIdle() override` -等待空闲（调用 `glFinish`）。 - -### 属性 - -#### `CommandQueueType GetType() const override` -返回 `CommandQueueType::Direct`。 - -#### `uint64_t GetTimestampFrequency() const override` -返回 0。 - -#### `void* GetNativeHandle() override` -返回 `nullptr`。 - -## 备注 - -- OpenGL 没有显式的命令队列，所有命令立即执行 -- `ExecuteCommandLists` 在 OpenGL 后端为空操作 -- `Signal`/`Wait` 仍然工作，使用 GLsync/fence 对象实现 diff --git a/docs/api/rhi/opengl/opengl-depth-stencil-view.md b/docs/api/rhi/opengl/opengl-depth-stencil-view.md deleted file mode 100644 index 4a6af4c6..00000000 --- a/docs/api/rhi/opengl/opengl-depth-stencil-view.md +++ /dev/null @@ -1,105 +0,0 @@ -# OpenGLDepthStencilView - -OpenGL 深度模板视图实现。 - -## 头文件 - -```cpp -#include -``` - -## 枚举 - -### DepthStencilFormat - -| 值 | OpenGL 内部格式 | -|----|----------------| -| `D16_UNORM` | `GL_DEPTH_COMPONENT16` | -| `D24_UNORM_S8_UINT` | `GL_DEPTH24_STENCIL8` | -| `D32_FLOAT` | `GL_DEPTH_COMPONENT32F` | -| `D32_FLOAT_S8X24_UINT` | `GL_DEPTH32F_STENCIL8` | - -### DepthStencilType - -| 值 | 描述 | -|----|------| -| `Texture2D` | 2D 纹理 | -| `Texture2DArray` | 2D 纹理数组 | -| `TextureCube` | 立方体贴图 | - -## OpenGLDepthStencilViewDesc - -```cpp -struct OpenGLDepthStencilViewDesc { - DepthStencilType type = DepthStencilType::Texture2D; - int mipLevel = 0; - int baseArraySlice = 0; - int arraySize = 1; - int layer = 0; -}; -``` - -## 公共成员函数 - -#### `OpenGLDepthStencilView()` - -#### `~OpenGLDepthStencilView()` - -#### `bool Initialize(unsigned int texture, const OpenGLDepthStencilViewDesc& desc)` - -#### `bool Initialize(unsigned int texture, int mipLevel = 0)` - -#### `bool InitializeCubemap(unsigned int cubemap, int face, int mipLevel = 0)` - -#### `void Shutdown()` - -#### `void Bind()` - -#### `void Unbind()` - -#### `void ClearDepth(float depth)` - -#### `void ClearStencil(uint8_t stencil)` - -#### `void ClearDepthStencil(float depth, uint8_t stencil)` - -#### `unsigned int GetFramebuffer() const` - -#### `unsigned int GetTexture() const` - -#### `int GetMipLevel() const` - -#### `int GetWidth() const` - -#### `int GetHeight() const` - -#### `static void BindFramebuffer(unsigned int framebuffer)` - -#### `static void UnbindFramebuffer()` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_texture` | `unsigned int` | GL texture ID | -| `m_framebuffer` | `unsigned int` | GL framebuffer ID | -| `m_mipLevel` | `int` | Mip 级别 | -| `m_width/height` | `int` | 尺寸 | -| `m_type` | `DepthStencilType` | 类型 | -| `m_format` | `DepthStencilFormat` | 格式 | - -## 使用示例 - -```cpp -OpenGLDepthStencilView dsv; -dsv.Initialize(depthTexture.GetID()); - -dsv.Bind(); -dsv.ClearDepthStencil(1.0f, 0); -dsv.Unbind(); - -// Combined with RTV -glBindFramebuffer(GL_FRAMEBUFFER, fbo); -glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, colorTex, 0); -glFramebufferTexture2D(GL_FRAMEBUFFER, GL_DEPTH_STENCIL_ATTACHMENT, GL_TEXTURE_2D, depthTex, 0); -``` diff --git a/docs/api/rhi/opengl/opengl-device.md b/docs/api/rhi/opengl/opengl-device.md deleted file mode 100644 index 96e5d73c..00000000 --- a/docs/api/rhi/opengl/opengl-device.md +++ /dev/null @@ -1,109 +0,0 @@ -# OpenGLDevice - -OpenGL 设备的实现，基于 GLFW 和现代 OpenGL。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHIDevice (interface) -└── OpenGLDevice (implementation) -``` - -## 公共成员函数 - -### 初始化与销毁 - -#### `bool Initialize(const RHIDeviceDesc& desc) override` -初始化 OpenGL 上下文和设备。 - -#### `void Shutdown() override` -关闭设备，销毁窗口（如果拥有）。 - -#### `bool CreateRenderWindow(int width, int height, const char* title, bool enableDebug = false)` -创建渲染窗口并初始化 OpenGL 上下文。 - -#### `bool InitializeWithExistingWindow(GLFWwindow* window)` -使用已有的 GLFW 窗口初始化。 - -### 窗口操作 - -#### `GLFWwindow* GetWindow() const` -获取 GLFW 窗口指针。 - -#### `void SwapBuffers()` -交换前后缓冲区。 - -#### `bool PollEvents()` -轮询窗口事件。 - -#### `void SetShouldClose(bool shouldClose)` -设置关闭标志。 - -#### `bool ShouldClose() const` -检查是否应该关闭。 - -### 资源创建 - -#### `RHIBuffer* CreateBuffer(const BufferDesc& desc) override` - -#### `RHITexture* CreateTexture(const TextureDesc& desc) override` - -#### `RHISwapChain* CreateSwapChain(const SwapChainDesc& desc) override` - -#### `RHICommandList* CreateCommandList(const CommandListDesc& desc) override` - -#### `RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) override` - -#### `RHIShader* CompileShader(const ShaderCompileDesc& desc) override` - -#### `RHIPipelineState* CreatePipelineState(const PipelineStateDesc& desc) override` - -#### `RHIFence* CreateFence(const FenceDesc& desc) override` - -#### `RHISampler* CreateSampler(const SamplerDesc& desc) override` - -### 设备信息 - -#### `const RHICapabilities& GetCapabilities() const override` -获取 OpenGL 功能支持信息。 - -#### `const RHIDeviceInfo& GetDeviceInfo() const override` -获取设备详细信息。 - -#### `void* GetNativeDevice() override` -返回窗口指针。 - -#### `void* GetNativeHandle() const` -返回窗口指针。 - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_window` | `GLFWwindow*` | GLFW 窗口 | -| `m_deviceInfo` | `RHIDeviceInfo` | 设备信息 | -| `m_capabilities` | `RHICapabilities` | 功能支持 | -| `m_initialized` | `bool` | 是否已初始化 | -| `m_ownsWindow` | `bool` | 是否拥有窗口 | - -## 使用示例 - -```cpp -OpenGLDevice device; -device.CreateRenderWindow(1920, 1080, "XCEngine", true); - -RHIShader* shader = device.CompileShader(shaderDesc); -RHIPipelineState* pso = device.CreatePipelineState(psoDesc); - -while (!device.ShouldClose()) { - device.PollEvents(); - // Render... - device.SwapBuffers(); -} -``` diff --git a/docs/api/rhi/opengl/opengl-fence.md b/docs/api/rhi/opengl/opengl-fence.md deleted file mode 100644 index 19306b97..00000000 --- a/docs/api/rhi/opengl/opengl-fence.md +++ /dev/null @@ -1,99 +0,0 @@ -# OpenGLFence - -OpenGL 栅栏同步实现，使用 `GLsync` (Fence objects)。 - -## 头文件 - -```cpp -#include -``` - -## FenceStatus 枚举 - -| 值 | 描述 | -|----|------| -| `Signaled` | 栅栏已发出信号 | -| `Unsignaled` | 栅栏未发出信号 | -| `Error` | 错误状态 | - -## 继承关系 - -``` -RHIFence (interface) -└── OpenGLFence (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `OpenGLFence()` - -#### `~OpenGLFence() override` - -### 初始化 - -#### `bool Initialize(bool signaled = false)` -初始化栅栏。 -- `signaled`: 是否初始为已发出信号状态 - -#### `void Shutdown() override` - -### 信号操作 - -#### `void Signal() override` -发送信号。 - -#### `void Signal(uint64_t value) override` -发送信号（值递增）。 - -#### `void Wait(uint64_t value) override` -等待栅栏达到指定值。 - -#### `void Reset()` -重置栅栏。 - -### 状态查询 - -#### `bool IsSignaled() const override` -检查是否已发出信号。 - -#### `FenceStatus GetStatus() const` -获取栅栏状态。 - -#### `uint64_t GetCompletedValue() const override` -获取已完成值。 - -#### `uint64_t GetCurrentValue() const` -获取当前值。 - -### 原生接口 - -#### `void* GetNativeHandle() override { return m_sync; }` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_sync` | `void*` | GLsync 对象 | -| `m_fenceValue` | `uint64_t` | 栅栏值 | -| `m_completedValue` | `uint64_t` | 已完成值 | -| `m_signaled` | `bool` | 是否已发出信号 | - -## 使用示例 - -```cpp -OpenGLFence fence; -fence.Initialize(); - -// Insert fence after draw commands -glFlush(); -GLsync sync = glFenceSync(GL_SYNC_GPU_commands_COMPLETE, 0); -glClientWaitSync(sync, GL_SYNC_FLUSH_COMMANDS_BIT, timeout); - -// Or use class -glFlush(); -fence.Signal(); - -fence.Wait(1); -``` diff --git a/docs/api/rhi/opengl/opengl-overview.md b/docs/api/rhi/opengl/opengl-overview.md deleted file mode 100644 index 7dc4ecfc..00000000 --- a/docs/api/rhi/opengl/opengl-overview.md +++ /dev/null @@ -1,87 +0,0 @@ -# OpenGL Backend Overview - -OpenGL RHI 后端实现，基于 GLFW 和现代 OpenGL (Core Profile)。 - -## 头文件 - -所有 OpenGL 后端头文件位于 `engine/include/XCEngine/RHI/OpenGL/`。 - -## 架构说明 - -OpenGL 是**立即模式** API，与 D3D12 的命令列表模式有本质区别： - -- 无显式的命令列表录制和提交 -- 状态通过 OpenGL 状态机管理 -- `OpenGLCommandList` 主要用于状态批处理和 RHI 接口兼容 -- 交换链使用 GLFW 窗口管理 - -## 后端组件 - -| 类 | 文件 | 描述 | -|----|------|------| -| `OpenGLDevice` | `OpenGLDevice.h` | 主设备，管理窗口和 OpenGL 上下文 | -| `OpenGLBuffer` | `OpenGLBuffer.h` | GPU 缓冲区（VBO/UBO/SSBO） | -| `OpenGLTexture` | `OpenGLTexture.h` | 纹理对象（1D/2D/3D/Cube） | -| `OpenGLCommandList` | `OpenGLCommandList.h` | 命令列表（状态批处理） | -| `OpenGLCommandQueue` | `OpenGLCommandQueue.h` | 命令队列（RHI 兼容层） | -| `OpenGLSwapChain` | `OpenGLSwapChain.h` | 交换链（GLFW 窗口） | -| `OpenGLFence` | `OpenGLFence.h` | 栅栏同步（GLsync） | -| `OpenGLShader` | `OpenGLShader.h` | Shader Program | -| `OpenGLPipelineState` | `OpenGLPipelineState.h` | 管线状态 | -| `OpenGLSampler` | `OpenGLSampler.h` | 采样器对象 | -| `OpenGLVertexArray` | `OpenGLVertexArray.h` | 顶点数组对象 (VAO) | -| `OpenGLRenderTargetView` | `OpenGLRenderTargetView.h` | 渲染目标 (FBO) | -| `OpenGLDepthStencilView` | `OpenGLDepthStencilView.h` | 深度模板 (FBO) | - -## 初始化流程 - -```cpp -#include - -using namespace XCEngine::RHI; - -OpenGLDevice device; -device.CreateRenderWindow(1920, 1080, "XCEngine", true); - -// Create resources -OpenGLShader shader; -shader.CompileFromFile("shaders/Default.vert", "shaders/Default.frag"); - -OpenGLBuffer vb; -vb.InitializeVertexBuffer(vertices, sizeof(vertices)); - -OpenGLTexture texture; -texture.LoadFromFile("textures/diffuse.png"); - -// Render loop -while (!device.ShouldClose()) { - device.PollEvents(); - - glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); - - shader.Use(); - vb.Bind(); - texture.Bind(0); - - glDrawArrays(GL_TRIANGLES, 0, vertexCount); - - device.SwapBuffers(); -} -``` - -## 与 D3D12 的差异 - -| 方面 | D3D12 | OpenGL | -|------|-------|--------| -| 模式 | 命令列表录制 | 立即模式 | -| 状态管理 | 显式资源状态 | OpenGL 状态机 | -| 描述符 | 描述符堆 + 句柄 | 绑定点 | -| 管线状态 | PSO（不可变） | 可变状态 | -| 内存管理 | 显式显存管理 | 驱动自动管理 | -| 多线程 | 需要 Bundle | 上下文共享 | - -## 扩展模块 - -- **GLFW**: 窗口管理和输入 -- **GLSL**: 着色器语言 (Core Profile) -- **stb_image**: 纹理文件加载 diff --git a/docs/api/rhi/opengl/opengl-pipeline-state.md b/docs/api/rhi/opengl/opengl-pipeline-state.md deleted file mode 100644 index 72f07947..00000000 --- a/docs/api/rhi/opengl/opengl-pipeline-state.md +++ /dev/null @@ -1,229 +0,0 @@ -# OpenGLPipelineState - -OpenGL 管线状态对象实现，封装多种 OpenGL 状态。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHIPipelineState (interface) -└── OpenGLPipelineState (implementation) -``` - -## 枚举 - -### OpenGLPrimitiveTopology - -| 值 | 描述 | -|----|------| -| `Points` | 点 | -| `Lines` | 线 | -| `LineStrip` | 线带 | -| `Triangles` | 三角形 | -| `TriangleStrip` | 三角形带 | - -### OpenGLBlendOp - -| 值 | OpenGL 常量 | -|----|-------------| -| `Add` | `GL_FUNC_ADD` | -| `Subtract` | `GL_FUNC_SUBTRACT` | -| `ReverseSubtract` | `GL_FUNC_REVERSE_SUBTRACT` | -| `Min` | `GL_MIN` | -| `Max` | `GL_MAX` | - -### CullFace / FrontFace / PolygonMode - -```cpp -enum class CullFace { Front, Back, FrontAndBack }; -enum class FrontFace { Clockwise, CounterClockwise }; -enum class PolygonMode { Point, Line, Fill }; -``` - -## 状态结构体 - -### OpenGLDepthStencilState - -```cpp -struct OpenGLDepthStencilState { - bool depthTestEnable = true; - bool depthWriteEnable = true; - ComparisonFunc depthFunc = ComparisonFunc::Less; - bool stencilEnable = false; - uint8_t stencilReadMask = 0xFF; - uint8_t stencilWriteMask = 0xFF; - int stencilRef = 0; - ComparisonFunc stencilFunc = ComparisonFunc::Always; - StencilOp stencilFailOp = StencilOp::Keep; - StencilOp stencilDepthFailOp = StencilOp::Keep; - StencilOp stencilDepthPassOp = StencilOp::Keep; -}; -``` - -### OpenGLBlendState - -```cpp -struct OpenGLBlendState { - bool blendEnable = false; - BlendFactor srcBlend = BlendFactor::SrcAlpha; - BlendFactor dstBlend = BlendFactor::InvSrcAlpha; - BlendFactor srcBlendAlpha = BlendFactor::One; - BlendFactor dstBlendAlpha = BlendFactor::Zero; - BlendOp blendOp = BlendOp::Add; - BlendOp blendOpAlpha = BlendOp::Add; - uint8_t colorWriteMask = 0xF; - float blendFactor[4] = { 0.0f, 0.0f, 0.0f, 0.0f }; -}; -``` - -### OpenGLRasterizerState - -```cpp -struct OpenGLRasterizerState { - bool cullFaceEnable = true; - CullFace cullFace = CullFace::Back; - FrontFace frontFace = FrontFace::CounterClockwise; - PolygonMode polygonMode = PolygonMode::Fill; - float polygonOffsetFactor = 0.0f; - float polygonOffsetUnits = 0.0f; - bool depthClipEnable = true; - bool scissorTestEnable = false; - bool multisampleEnable = false; - bool sampleAlphaToCoverageEnable = false; -}; -``` - -### ViewportState / ScissorState / LogicalOperation - -```cpp -struct ViewportState { - float x = 0.0f, y = 0.0f; - float width = 0.0f, height = 0.0f; - float minDepth = 0.0f, maxDepth = 1.0f; -}; - -struct ScissorState { - bool enable = false; - int x = 0, y = 0, width = 0, height = 0; -}; - -struct LogicalOperation { - bool enable = false; - uint32_t operation = 0; -}; -``` - -## 公共成员函数 - -### 生命周期 - -#### `OpenGLPipelineState()` - -#### `~OpenGLPipelineState() override` - -#### `void Shutdown() override` - -### 绑定 - -#### `void Bind() override` -应用所有状态。 - -#### `void Unbind() override` - -#### `void* GetNativeHandle() override` - -#### `PipelineType GetType() const override { return PipelineType::Graphics; }` - -### 状态设置 - -#### `void SetDepthStencilState(const OpenGLDepthStencilState& state)` - -#### `void SetBlendState(const OpenGLBlendState& state)` - -#### `void SetRasterizerState(const OpenGLRasterizerState& state)` - -#### `void SetViewport(const ViewportState& state)` - -#### `void SetScissor(const ScissorState& state)` - -#### `void SetLogicalOperation(const LogicalOperation& state)` - -### 状态应用 - -#### `void Apply()` -应用所有状态。 - -#### `void ApplyDepthStencil()` - -#### `void ApplyBlend()` - -#### `void ApplyRasterizer()` - -#### `void ApplyViewport()` - -#### `void ApplyScissor()` - -### 清除 - -#### `void SetClearColor(float r, float g, float b, float a)` - -#### `void Clear(unsigned int buffers)` - -### Shader 附加 - -#### `void AttachShader(unsigned int program)` - -#### `void DetachShader()` - -### 属性获取 - -#### `const OpenGLDepthStencilState& GetDepthStencilState() const` - -#### `const OpenGLBlendState& GetBlendState() const` - -#### `const OpenGLRasterizerState& GetRasterizerState() const` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_depthStencilState` | `OpenGLDepthStencilState` | 深度模板状态 | -| `m_blendState` | `OpenGLBlendState` | 混合状态 | -| `m_rasterizerState` | `OpenGLRasterizerState` | 光栅化状态 | -| `m_viewportState` | `ViewportState` | 视口状态 | -| `m_scissorState` | `ScissorState` | 裁剪状态 | -| `m_logicalOperation` | `LogicalOperation` | 逻辑操作 | -| `m_clearColor` | `float[4]` | 清除颜色 | -| `m_program` | `unsigned int` | GL program | -| `m_programAttached` | `bool` | program 是否附加 | - -## 使用示例 - -```cpp -OpenGLPipelineState pso; - -OpenGLDepthStencilState ds; -ds.depthTestEnable = true; -ds.depthWriteEnable = true; -ds.depthFunc = ComparisonFunc::Less; -pso.SetDepthStencilState(ds); - -OpenGLBlendState blend; -blend.blendEnable = true; -blend.srcBlend = BlendFactor::SrcAlpha; -blend.dstBlend = BlendFactor::InvSrcAlpha; -pso.SetBlendState(blend); - -OpenGLRasterizerState raster; -raster.cullFaceEnable = true; -raster.cullFace = CullFace::Back; -pso.SetRasterizerState(raster); - -pso.AttachShader(shaderProgram); -pso.Bind(); -``` diff --git a/docs/api/rhi/opengl/opengl-render-target-view.md b/docs/api/rhi/opengl/opengl-render-target-view.md deleted file mode 100644 index 9739f3b5..00000000 --- a/docs/api/rhi/opengl/opengl-render-target-view.md +++ /dev/null @@ -1,106 +0,0 @@ -# OpenGLRenderTargetView - -OpenGL 渲染目标视图实现，使用 framebuffer object (FBO)。 - -## 头文件 - -```cpp -#include -``` - -## 枚举 - -### RenderTargetType - -| 值 | 描述 | -|----|------| -| `Texture2D` | 2D 纹理 | -| `Texture2DArray` | 2D 纹理数组 | -| `Texture3D` | 3D 纹理 | -| `TextureCube` | 立方体贴图 | -| `TextureCubeArray` | 立方体贴图数组 | - -## OpenGLRenderTargetViewDesc - -```cpp -struct OpenGLRenderTargetViewDesc { - RenderTargetType type = RenderTargetType::Texture2D; - int mipLevel = 0; - int baseArraySlice = 0; - int arraySize = 1; - int layer = 0; - uint32_t format = 0; -}; -``` - -## 公共成员函数 - -#### `OpenGLRenderTargetView()` - -#### `~OpenGLRenderTargetView()` - -#### `bool Initialize(unsigned int texture, const OpenGLRenderTargetViewDesc& desc)` - -#### `bool Initialize(unsigned int texture, int mipLevel = 0)` - -#### `bool InitializeCubemap(unsigned int cubemap, int face, int mipLevel = 0)` - -#### `void Shutdown()` - -#### `void Bind(unsigned int slot = 0)` - -#### `void Bind(unsigned int count, const unsigned int* framebuffers, const int* drawBuffers)` - -#### `void Unbind()` - -#### `void Clear(float r, float g, float b, float a)` - -#### `void Clear(float r, float g, float b, float a, float depth, uint8_t stencil)` - -#### `unsigned int GetFramebuffer() const` - -#### `unsigned int GetTexture() const` - -#### `int GetMipLevel() const` - -#### `int GetWidth() const` - -#### `int GetHeight() const` - -#### `static void BindFramebuffer(unsigned int framebuffer)` - -#### `static void UnbindFramebuffer()` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_texture` | `unsigned int` | GL texture ID | -| `m_framebuffer` | `unsigned int` | GL framebuffer ID | -| `m_mipLevel` | `int` | Mip 级别 | -| `m_width/height` | `int` | 尺寸 | -| `m_type` | `RenderTargetType` | 类型 | -| `m_framebuffers` | `vector` | 额外 framebuffer 列表 | - -## 使用示例 - -```cpp -// Create framebuffer with color attachment -OpenGLRenderTargetView rtv; -rtv.Initialize(texture.GetID()); - -rtv.Bind(); -glClear(GL_COLOR_BUFFER_BIT); -glDrawArrays(GL_TRIANGLES, 0, 3); -rtv.Unbind(); - -// MRT -OpenGLRenderTargetView rtvs[2]; -rtvs[0].Initialize(texture0.GetID()); -rtvs[1].Initialize(texture1.GetID()); - -unsigned int fbs[] = { rtvs[0].GetFramebuffer(), rtvs[1].GetFramebuffer() }; -int draws[] = { 0, 1 }; -rtvs[0].Bind(2, fbs, draws); -glClear(GL_COLOR_BUFFER_BIT); -``` diff --git a/docs/api/rhi/opengl/opengl-sampler.md b/docs/api/rhi/opengl/opengl-sampler.md deleted file mode 100644 index 8026ccca..00000000 --- a/docs/api/rhi/opengl/opengl-sampler.md +++ /dev/null @@ -1,102 +0,0 @@ -# OpenGLSampler - -OpenGL 采样器实现。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHISampler (interface) -└── OpenGLSampler (implementation) -``` - -## 枚举 - -### SamplerWrapMode - -| 值 | OpenGL 常量 | -|----|-------------| -| `Repeat` | `GL_REPEAT` | -| `MirroredRepeat` | `GL_MIRRORED_REPEAT` | -| `ClampToEdge` | `GL_CLAMP_TO_EDGE` | -| `ClampToBorder` | `GL_CLAMP_TO_BORDER` | - -### SamplerFilter - -| 值 | OpenGL 常量 | -|----|-------------| -| `Nearest` | `GL_NEAREST` | -| `Linear` | `GL_LINEAR` | -| `NearestMipmapNearest` | `GL_NEAREST_MIPMAP_NEAREST` | -| `LinearMipmapNearest` | `GL_LINEAR_MIPMAP_NEAREST` | -| `NearestMipmapLinear` | `GL_NEAREST_MIPMAP_LINEAR` | -| `LinearMipmapLinear` | `GL_LINEAR_MIPMAP_LINEAR` | - -### SamplerCompareMode - -| 值 | OpenGL 常量 | -|----|-------------| -| `None` | `GL_NONE` | -| `CompareToRef` | `GL_COMPARE_REF_TO_TEXTURE` | - -## OpenGLSamplerDesc - -```cpp -struct OpenGLSamplerDesc { - SamplerFilter minFilter = SamplerFilter::LinearMipmapLinear; - SamplerFilter magFilter = SamplerFilter::Linear; - SamplerWrapMode wrapS = SamplerWrapMode::Repeat; - SamplerWrapMode wrapT = SamplerWrapMode::Repeat; - SamplerWrapMode wrapR = SamplerWrapMode::Repeat; - SamplerCompareMode compareMode = SamplerCompareMode::None; - int compareFunc = 0; - float maxAnisotropy = 1.0f; - float minLod = -1000.0f; - float maxLod = 1000.0f; -}; -``` - -## 公共成员函数 - -#### `OpenGLSampler()` - -#### `~OpenGLSampler() override` - -#### `bool Initialize(const OpenGLSamplerDesc& desc)` - -#### `void Shutdown() override` - -#### `void Bind(unsigned int unit) override` - -#### `void Unbind(unsigned int unit) override` - -#### `unsigned int GetID() const` - -#### `void* GetNativeHandle() override` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_sampler` | `unsigned int` | GL sampler ID | -| `m_desc` | `OpenGLSamplerDesc` | 采样器描述 | - -## 使用示例 - -```cpp -OpenGLSampler sampler; -OpenGLSamplerDesc desc; -desc.minFilter = SamplerFilter::LinearMipmapLinear; -desc.magFilter = SamplerFilter::Linear; -desc.wrapS = desc.wrapT = SamplerWrapMode::Repeat; -desc.maxAnisotropy = 16.0f; -sampler.Initialize(desc); - -sampler.Bind(0); -glBindTextureUnit(0, texture.GetID()); -``` diff --git a/docs/api/rhi/opengl/opengl-shader.md b/docs/api/rhi/opengl/opengl-shader.md deleted file mode 100644 index b0ebe130..00000000 --- a/docs/api/rhi/opengl/opengl-shader.md +++ /dev/null @@ -1,151 +0,0 @@ -# OpenGLShader - -OpenGL 着色器实现，封装 shader program。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHIShader (interface) -└── OpenGLShader (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `OpenGLShader()` - -#### `~OpenGLShader() override` - -### RHI 接口实现 - -#### `bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) override` -从文件编译（适配 RHI 接口，`target` 被忽略）。 - -#### `bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) override` -从内存编译。 - -#### `void Shutdown() override` - -### OpenGL 特有编译方法 - -#### `bool CompileFromFile(const char* vertexPath, const char* fragmentPath)` -编译顶点+片元着色器。 - -#### `bool CompileFromFile(const char* vertexPath, const char* fragmentPath, const char* geometryPath)` -编译 VS + GS + FS。 - -#### `bool Compile(const char* vertexSource, const char* fragmentSource)` -从源码编译 VS + FS。 - -#### `bool Compile(const char* vertexSource, const char* fragmentSource, const char* geometrySource)` - -#### `bool CompileCompute(const char* computeSource)` -编译计算着色器。 - -#### `bool Compile(const char* source, ShaderType type)` -按类型编译单个着色器。 - -### 绑定 - -#### `void Use() const` -使用此 program。 - -#### `void Bind() override { Use(); }` - -#### `void Unbind() override` - -### Uniform 设置 - -#### `void SetInt(const char* name, int value) override` - -#### `void SetIntArray(const char* name, const int* values, unsigned int count)` - -#### `void SetFloat(const char* name, float value) override` - -#### `void SetFloatArray(const char* name, const float* values, unsigned int count)` - -#### `void SetVec3(const char* name, float x, float y, float z) override` - -#### `void SetVec3(const char* name, const float* values)` - -#### `void SetVec4(const char* name, float x, float y, float z, float w) override` - -#### `void SetVec4(const char* name, const float* values)` - -#### `void SetMat2(const char* name, const float* value)` - -#### `void SetMat3(const char* name, const float* value)` - -#### `void SetMat4(const char* name, const float* value) override` - -#### `void SetMat4Array(const char* name, const float* values, unsigned int count)` - -### 属性 - -#### `int GetUniformLocation(const char* name) const` -获取 uniform location。 - -#### `unsigned int GetID() const` -获取 GL program ID。 - -#### `void* GetNativeHandle() override` - -#### `bool IsValid() const override` -检查 program 是否有效。 - -#### `ShaderType GetType() const override` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_program` | `unsigned int` | GL program ID | -| `m_type` | `ShaderType` | 着色器类型 | - -## 私有方法 - -#### `bool CheckCompileErrors(unsigned int shader, const char* type)` -检查单个 shader 编译错误。 - -#### `bool CheckLinkErrors(unsigned int program)` -检查 program 链接错误。 - -## 使用示例 - -```cpp -// Simple shader -OpenGLShader shader; -shader.Compile(R"( - #version 450 core - layout(location=0) in vec3 aPos; - void main() { gl_Position = vec4(aPos, 1.0); } -)", - R"( - #version 450 core - out vec4 FragColor; - void main() { FragColor = vec4(1.0); } - )", - "vs", "fs"); - -shader.Use(); -shader.SetMat4("u_model", glm::value_ptr(model)); -shader.SetVec3("u_color", 1.0f, 0.0f, 0.0f); -shader.SetInt("u_texture", 0); - -// From files -OpenGLShader shader2; -shader2.CompileFromFile("shaders/Default.vert", "shaders/Default.frag"); -``` - -## 备注 - -- 使用 GLSL 450 core profile -- 编译/链接错误通过日志输出 -- `GetUniformLocation` 返回 -1 表示 uniform 不存在 diff --git a/docs/api/rhi/opengl/opengl-swap-chain.md b/docs/api/rhi/opengl/opengl-swap-chain.md deleted file mode 100644 index 50848a9f..00000000 --- a/docs/api/rhi/opengl/opengl-swap-chain.md +++ /dev/null @@ -1,138 +0,0 @@ -# OpenGLSwapChain - -OpenGL 交换链实现，基于 GLFW 窗口和双缓冲。 - -## 头文件 - -```cpp -#include -``` - -## 枚举 - -### PresentMode - -| 值 | 描述 | -|----|------| -| `Immediate` | 立即呈现，无垂直同步 | -| `VSync` | 等待垂直同步 | -| `Mailbox` | 邮箱模式（渲染时不阻塞） | -| `Fifo` | 标准 FIFO 队列（默认） | - -### SurfaceFormat - -| 值 | 描述 | -|----|------| -| `RGBA8` | 8-bit RGBA | -| `RGBA16F` | 16-bit float RGBA | -| `RGBA32F` | 32-bit float RGBA | -| `BGRA8` | BGRA 格式 | - -## 继承关系 - -``` -RHISwapChain (interface) -└── OpenGLSwapChain (implementation) -``` - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `OpenGLSwapChain()` - -#### `~OpenGLSwapChain() override` - -### 初始化 - -#### `bool Initialize(GLFWwindow* window, bool vsync = true)` -初始化交换链。 - -#### `bool Initialize(GLFWwindow* window, int width, int height, PresentMode mode = PresentMode::VSync)` - -#### `void Shutdown() override` - -### 呈现操作 - -#### `void Present(uint32_t syncInterval = 1, uint32_t flags = 0) override` -呈现帧。 -- `syncInterval`: 垂直同步间隔 - -#### `void SwapBuffers()` -直接交换缓冲区。 - -### 尺寸管理 - -#### `void Resize(uint32_t width, uint32_t height) override` - -#### `void SetFramebufferSize(int width, int height)` - -### 垂直同步 - -#### `void SetVSync(bool enabled)` -设置垂直同步。 - -#### `bool IsVSync() const` -检查是否启用垂直同步。 - -### 全屏 - -#### `void SetFullscreen(bool fullscreen) override` - -#### `bool IsFullscreen() const override` - -### 窗口事件 - -#### `bool ShouldClose() const override` - -#### `void SetShouldClose(bool shouldClose) override` - -#### `void PollEvents() override` - -### 缓冲区查询 - -#### `uint32_t GetCurrentBackBufferIndex() const override` -返回 0（OpenGL 单缓冲区索引）。 - -#### `RHITexture* GetCurrentBackBuffer() override` -返回 `nullptr`（OpenGL 使用默认 framebuffer）。 - -### 属性 - -#### `int GetWidth() const` - -#### `int GetHeight() const` - -#### `int GetFramebufferWidth() const` - -#### `int GetFramebufferHeight() const` - -#### `GLFWwindow* GetWindow() const` - -#### `void* GetNativeHandle() override` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_window` | `GLFWwindow*` | GLFW 窗口 | -| `m_width/height` | `int` | 窗口尺寸 | -| `m_framebufferWidth/height` | `int` | 帧缓冲尺寸 (DPI aware) | -| `m_vsync` | `bool` | 是否垂直同步 | -| `m_presentMode` | `PresentMode` | 呈现模式 | - -## 使用示例 - -```cpp -OpenGLSwapChain swapChain; -swapChain.Initialize(window, true); - -while (!swapChain.ShouldClose()) { - swapChain.PollEvents(); - - glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); - // Render... - - swapChain.Present(1); -} -``` diff --git a/docs/api/rhi/opengl/opengl-texture.md b/docs/api/rhi/opengl/opengl-texture.md deleted file mode 100644 index 0a517bba..00000000 --- a/docs/api/rhi/opengl/opengl-texture.md +++ /dev/null @@ -1,149 +0,0 @@ -# OpenGLTexture - -OpenGL 纹理的实现，封装 OpenGL texture object。 - -## 头文件 - -```cpp -#include -``` - -## 继承关系 - -``` -RHITexture (interface) -└── OpenGLTexture (implementation) -``` - -## 枚举 - -### OpenGLTextureType - -| 值 | 描述 | -|----|------| -| `Texture1D` | 1D 纹理 | -| `Texture2D` | 2D 纹理 | -| `Texture2DArray` | 2D 纹理数组 | -| `Texture3D` | 3D 纹理 | -| `TextureCube` | 立方体贴图 | -| `TextureCubeArray` | 立方体贴图数组 | - -### OpenGLFormat / OpenGLInternalFormat - -| OpenGLFormat | OpenGLInternalFormat | 描述 | -|--------------|---------------------|------| -| `R8` | `1` | 单通道 8-bit | -| `RG8` | `2` | 双通道 8-bit | -| `RGBA8` | `4` | 四通道 8-bit | -| `RGBA16F` | `11` | 四通道 16-bit float | -| `RGBA32F` | `16` | 四通道 32-bit float | -| `Depth24Stencil8` | `38` | 24-bit depth + 8-bit stencil | -| `Depth32F` | `31` | 32-bit float depth | -| `CompressedDXT1` | `21` | DXT1 压缩 | -| `CompressedDXT5` | `22` | DXT5 压缩 | - -## 公共成员函数 - -### 构造函数与析构函数 - -#### `OpenGLTexture()` - -#### `~OpenGLTexture() override` - -### 初始化 - -#### `bool Initialize(OpenGLTextureType type, int width, int height, int depth, int mipLevels, OpenGLFormat format, const void* data = nullptr)` -通用初始化。 - -#### `bool Initialize2D(int width, int height, int channels, const void* data, bool generateMipmap = true)` -便捷的 2D 纹理初始化。 -- `channels`: 通道数 (1-4) - -#### `bool InitializeCubeMap(int size, int mipLevels, OpenGLFormat format, const void* data = nullptr)` -初始化立方体贴图。 - -#### `bool LoadFromFile(const char* path, bool flipVertical = true)` -从图片文件加载纹理（需要 stb_image）。 - -#### `void Shutdown() override` - -### 绑定操作 - -#### `void Bind(int slot = 0) const` -绑定纹理到纹理单元。 - -#### `void Unbind() const` - -#### `void BindImage(int slot, bool read, bool write) const` -绑定为 image texture（用于 compute shader）。 - -### 纹理操作 - -#### `void GenerateMipmap()` -生成 Mipmap。 - -#### `void SetFiltering(int minFilter, int magFilter)` -设置过滤模式。 - -#### `void SetWrapping(int wrapS, int wrapT, int wrapR = -1)` -设置纹理环绕模式。 - -### 属性 - -#### `unsigned int GetID() const` -获取 OpenGL texture ID。 - -#### `OpenGLTextureType GetOpenGLType() const` -获取纹理类型。 - -#### `uint32_t GetWidth() const override` - -#### `uint32_t GetHeight() const override` - -#### `uint32_t GetDepth() const override` - -#### `uint32_t GetMipLevels() const override` - -#### `TextureType GetTextureType() const override` -转换为 RHI TextureType。 - -#### `void* GetNativeHandle() override` - -#### `Format GetFormat() const override / void SetFormat(Format format)` - -#### `const std::string& GetName() const override / void SetName(...)` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_texture` | `unsigned int` | GL texture ID | -| `m_type` | `OpenGLTextureType` | 纹理类型 | -| `m_width/height/depth` | `int` | 尺寸 | -| `m_mipLevels` | `int` | Mipmap 级别 | -| `m_channels` | `int` | 通道数 | -| `m_format` | `Format` | RHI 格式 | -| `m_name` | `std::string` | 名称 | - -## 使用示例 - -```cpp -// Load from file -OpenGLTexture diffuse; -diffuse.LoadFromFile("textures/diffuse.png"); - -// Create from data -OpenGLTexture texture; -unsigned char pixels[] = { ... }; -texture.Initialize2D(512, 512, 4, pixels); -texture.SetFiltering(GL_LINEAR_MIPMAP_LINEAR, GL_LINEAR); -texture.SetWrapping(GL_REPEAT, GL_REPEAT); -texture.GenerateMipmap(); - -// Bind -texture.Bind(0); -glBindTextureUnit(0, texture.GetID()); - -// Compute image binding -texture.BindImage(0, true, false); -``` diff --git a/docs/api/rhi/opengl/opengl-vertex-array.md b/docs/api/rhi/opengl/opengl-vertex-array.md deleted file mode 100644 index 22e255ae..00000000 --- a/docs/api/rhi/opengl/opengl-vertex-array.md +++ /dev/null @@ -1,88 +0,0 @@ -# OpenGLVertexArray - -OpenGL 顶点数组对象 (VAO) 封装。 - -## 头文件 - -```cpp -#include -``` - -## VertexAttribute - -```cpp -struct VertexAttribute { - unsigned int index; // 属性索引 (layout location) - int count; // 组件数量 (1-4) - unsigned int type; // GL 类型 (GL_FLOAT, etc.) - bool normalized; // 是否归一化 - size_t stride; // 顶点步长 - size_t offset; // 属性偏移 -}; -``` - -## 公共成员函数 - -#### `OpenGLVertexArray()` - -#### `~OpenGLVertexArray()` - -#### `bool Initialize()` - -#### `void AddVertexBuffer(unsigned int buffer, const VertexAttribute& attribute)` - -#### `void SetIndexBuffer(unsigned int buffer, unsigned int type)` - -#### `void Shutdown()` - -#### `void Bind() const` - -#### `void Unbind() const` - -#### `unsigned int GetID() const` - -#### `unsigned int GetIndexBuffer() const` - -#### `unsigned int GetIndexCount() const` - -## 内部成员 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `m_vao` | `unsigned int` | GL VAO ID | -| `m_indexBuffer` | `unsigned int` | 索引缓冲区 | -| `m_indexCount` | `unsigned int` | 索引数量 | -| `m_vertexBufferCount` | `int` | 顶点缓冲区数量 | - -## 使用示例 - -```cpp -OpenGLVertexArray vao; -vao.Initialize(); - -// Position attribute -VertexAttribute pos; -pos.index = 0; -pos.count = 3; -pos.type = GL_FLOAT; -pos.normalized = false; -pos.stride = sizeof(Vertex); -pos.offset = 0; -vao.AddVertexBuffer(vb.GetID(), pos); - -// UV attribute -VertexAttribute uv; -uv.index = 1; -uv.count = 2; -uv.type = GL_FLOAT; -uv.normalized = false; -uv.stride = sizeof(Vertex); -uv.offset = sizeof(float) * 3; -vao.AddVertexBuffer(vb.GetID(), uv); - -// Index buffer -vao.SetIndexBuffer(ib.GetID(), GL_UNSIGNED_SHORT); - -vao.Bind(); -glDrawElements(GL_TRIANGLES, vao.GetIndexCount(), GL_UNSIGNED_SHORT, 0); -``` diff --git a/docs/api/rhi/opengl/overview.md b/docs/api/rhi/opengl/overview.md new file mode 100644 index 00000000..777487f9 --- /dev/null +++ b/docs/api/rhi/opengl/overview.md @@ -0,0 +1,41 @@ +# OpenGL 后端概览 + +**命名空间**: `XCEngine::RHI` + +**类型**: `module` + +**描述**: OpenGL 后端实现模块，基于 GLFW 和现代 OpenGL (Core Profile)。 + +## 组件列表 + +| 组件 | 文档 | +|------|------| +| [OpenGLDevice](device/device.md) | OpenGL 设备实现 | +| [OpenGLBuffer](buffer/buffer.md) | OpenGL 缓冲区实现 | +| [OpenGLTexture](texture/texture.md) | OpenGL 纹理实现 | +| [OpenGLCommandList](command-list/command-list.md) | OpenGL 命令列表实现 | +| [OpenGLCommandQueue](command-queue/command-queue.md) | OpenGL 命令队列实现 | +| [OpenGLSwapChain](swap-chain/swap-chain.md) | OpenGL 交换链实现 | +| [OpenGLFence](fence/fence.md) | OpenGL 同步栅栏实现 | +| [OpenGLShader](shader/shader.md) | OpenGL 着色器实现 | +| [OpenGLPipelineState](pipeline-state/pipeline-state.md) | OpenGL 管线状态实现 | +| [OpenGLSampler](sampler/sampler.md) | OpenGL 采样器实现 | +| [OpenGLVertexArray](vertex-array/vertex-array.md) | OpenGL 顶点数组实现 | +| [OpenGLRenderTargetView](render-target-view/render-target-view.md) | OpenGL 渲染目标实现 | +| [OpenGLDepthStencilView](depth-stencil-view/depth-stencil-view.md) | OpenGL 深度模板实现 | + +## 与 D3D12 的差异 + +| 方面 | D3D12 | OpenGL | +|------|-------|--------| +| 模式 | 命令列表录制 | 立即模式 | +| 状态管理 | 显式资源状态 | OpenGL 状态机 | +| 描述符 | 描述符堆 + 句柄 | 绑定点 | +| 管线状态 | PSO（不可变） | 可变状态 | +| 内存管理 | 显式显存管理 | 驱动自动管理 | +| 多线程 | 需要 Bundle | 上下文共享 | + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [D3D12 后端](overview.md) diff --git a/docs/api/rhi/opengl/pipeline-state/apply-blend.md b/docs/api/rhi/opengl/pipeline-state/apply-blend.md new file mode 100644 index 00000000..c4fcc3be --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/apply-blend.md @@ -0,0 +1,21 @@ +# OpenGLPipelineState::ApplyBlend + +```cpp +void ApplyBlend(); +``` + +应用混合状态到 OpenGL。 + +**线程安全：** ❌ + +**示例：** + +```cpp +pipelineState->SetBlendState(blendState); +pipelineState->ApplyBlend(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [Apply](apply.md) - 应用所有状态 diff --git a/docs/api/rhi/opengl/pipeline-state/apply-depth-stencil.md b/docs/api/rhi/opengl/pipeline-state/apply-depth-stencil.md new file mode 100644 index 00000000..24702420 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/apply-depth-stencil.md @@ -0,0 +1,21 @@ +# OpenGLPipelineState::ApplyDepthStencil + +```cpp +void ApplyDepthStencil(); +``` + +应用深度模板状态到 OpenGL。 + +**线程安全：** ❌ + +**示例：** + +```cpp +pipelineState->SetDepthStencilState(dsState); +pipelineState->ApplyDepthStencil(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [Apply](apply.md) - 应用所有状态 diff --git a/docs/api/rhi/opengl/pipeline-state/apply-rasterizer.md b/docs/api/rhi/opengl/pipeline-state/apply-rasterizer.md new file mode 100644 index 00000000..45fd9c9a --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/apply-rasterizer.md @@ -0,0 +1,21 @@ +# OpenGLPipelineState::ApplyRasterizer + +```cpp +void ApplyRasterizer(); +``` + +应用光栅化状态到 OpenGL。 + +**线程安全：** ❌ + +**示例：** + +```cpp +pipelineState->SetRasterizerState(rsState); +pipelineState->ApplyRasterizer(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [Apply](apply.md) - 应用所有状态 diff --git a/docs/api/rhi/opengl/pipeline-state/apply-scissor.md b/docs/api/rhi/opengl/pipeline-state/apply-scissor.md new file mode 100644 index 00000000..8716bf27 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/apply-scissor.md @@ -0,0 +1,21 @@ +# OpenGLPipelineState::ApplyScissor + +```cpp +void ApplyScissor(); +``` + +应用裁剪状态到 OpenGL。 + +**线程安全：** ❌ + +**示例：** + +```cpp +pipelineState->SetScissor(scissor); +pipelineState->ApplyScissor(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [Apply](apply.md) - 应用所有状态 diff --git a/docs/api/rhi/opengl/pipeline-state/apply-viewport.md b/docs/api/rhi/opengl/pipeline-state/apply-viewport.md new file mode 100644 index 00000000..2bcbe67d --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/apply-viewport.md @@ -0,0 +1,21 @@ +# OpenGLPipelineState::ApplyViewport + +```cpp +void ApplyViewport(); +``` + +应用视口状态到 OpenGL。 + +**线程安全：** ❌ + +**示例：** + +```cpp +pipelineState->SetViewport(viewport); +pipelineState->ApplyViewport(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [Apply](apply.md) - 应用所有状态 diff --git a/docs/api/rhi/opengl/pipeline-state/apply.md b/docs/api/rhi/opengl/pipeline-state/apply.md new file mode 100644 index 00000000..1878101d --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/apply.md @@ -0,0 +1,27 @@ +# OpenGLPipelineState::Apply + +```cpp +void Apply(); +``` + +应用所有管线状态（深度模板、混合、光栅化、视口、裁剪）。 + +**线程安全：** ❌ + +**示例：** + +```cpp +pipelineState->SetDepthStencilState(dsState); +pipelineState->SetBlendState(blendState); +pipelineState->SetRasterizerState(rsState); +pipelineState->SetViewport(viewport); +pipelineState->SetScissor(scissor); +pipelineState->Apply(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [ApplyDepthStencil](apply-depth-stencil.md) - 仅应用深度模板 +- [ApplyBlend](apply-blend.md) - 仅应用混合 +- [ApplyRasterizer](apply-rasterizer.md) - 仅应用光栅化 diff --git a/docs/api/rhi/opengl/pipeline-state/attach-shader.md b/docs/api/rhi/opengl/pipeline-state/attach-shader.md new file mode 100644 index 00000000..db348116 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/attach-shader.md @@ -0,0 +1,23 @@ +# OpenGLPipelineState::AttachShader + +```cpp +void AttachShader(unsigned int program); +``` + +附加 OpenGL 着色器程序到管线状态。 + +**参数：** +- `program` - OpenGL 着色器程序 ID + +**线程安全：** ❌ + +**示例：** + +```cpp +pipelineState->AttachShader(shaderProgram); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [DetachShader](detach-shader.md) - 分离着色器程序 diff --git a/docs/api/rhi/opengl/pipeline-state/detach-shader.md b/docs/api/rhi/opengl/pipeline-state/detach-shader.md new file mode 100644 index 00000000..3b98083d --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/detach-shader.md @@ -0,0 +1,20 @@ +# OpenGLPipelineState::DetachShader + +```cpp +void DetachShader(); +``` + +从管线状态分离着色器程序。 + +**线程安全：** ❌ + +**示例：** + +```cpp +pipelineState->DetachShader(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [AttachShader](attach-shader.md) - 附加着色器程序 diff --git a/docs/api/rhi/opengl/pipeline-state/get-blend-state.md b/docs/api/rhi/opengl/pipeline-state/get-blend-state.md new file mode 100644 index 00000000..9f3a3187 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/get-blend-state.md @@ -0,0 +1,25 @@ +# OpenGLPipelineState::GetBlendState + +```cpp +const OpenGLBlendState& GetBlendState() const; +``` + +获取当前混合状态。 + +**返回：** 混合状态结构体引用 + +**线程安全：** ❌ + +**示例：** + +```cpp +const auto& blendState = pipelineState->GetBlendState(); +if (blendState.blendEnable) { + // blend is enabled +} +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [SetBlendState](set-blend-state.md) - 设置混合状态 diff --git a/docs/api/rhi/opengl/pipeline-state/get-depth-stencil-state.md b/docs/api/rhi/opengl/pipeline-state/get-depth-stencil-state.md new file mode 100644 index 00000000..6f98d6f1 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/get-depth-stencil-state.md @@ -0,0 +1,25 @@ +# OpenGLPipelineState::GetDepthStencilState + +```cpp +const OpenGLDepthStencilState& GetDepthStencilState() const; +``` + +获取当前深度模板状态。 + +**返回：** 深度模板状态结构体引用 + +**线程安全：** ❌ + +**示例：** + +```cpp +const auto& dsState = pipelineState->GetDepthStencilState(); +if (dsState.depthTestEnable) { + // depth test is enabled +} +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [SetDepthStencilState](set-depth-stencil-state.md) - 设置深度模板状态 diff --git a/docs/api/rhi/opengl/pipeline-state/get-rasterizer-state.md b/docs/api/rhi/opengl/pipeline-state/get-rasterizer-state.md new file mode 100644 index 00000000..333563d3 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/get-rasterizer-state.md @@ -0,0 +1,25 @@ +# OpenGLPipelineState::GetRasterizerState + +```cpp +const OpenGLRasterizerState& GetRasterizerState() const; +``` + +获取当前光栅化状态。 + +**返回：** 光栅化状态结构体引用 + +**线程安全：** ❌ + +**示例：** + +```cpp +const auto& rsState = pipelineState->GetRasterizerState(); +if (rsState.cullFaceEnable) { + // culling is enabled +} +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [SetRasterizerState](set-rasterizer-state.md) - 设置光栅化状态 diff --git a/docs/api/rhi/opengl/pipeline-state/pipeline-state.md b/docs/api/rhi/opengl/pipeline-state/pipeline-state.md new file mode 100644 index 00000000..6b8eede3 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/pipeline-state.md @@ -0,0 +1,39 @@ +# OpenGLPipelineState + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 管线状态对象实现，继承自 `RHIPipelineState`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Bind` | [详细文档](../../shader/bind.md) | +| `Unbind` | [详细文档](../../shader/unbind.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `GetType` | [详细文档](../../shader/get-type.md) | +| `SetDepthStencilState` | [详细文档](set-depth-stencil-state.md) | +| `SetBlendState` | [详细文档](set-blend-state.md) | +| `SetRasterizerState` | [详细文档](set-rasterizer-state.md) | +| `SetViewport` | [详细文档](set-viewport.md) | +| `SetScissor` | [详细文档](set-scissor.md) | +| `SetLogicalOperation` | [详细文档](set-logical-operation.md) | +| `Apply` | [详细文档](apply.md) | +| `ApplyDepthStencil` | [详细文档](apply-depth-stencil.md) | +| `ApplyBlend` | [详细文档](apply-blend.md) | +| `ApplyRasterizer` | [详细文档](apply-rasterizer.md) | +| `ApplyViewport` | [详细文档](apply-viewport.md) | +| `ApplyScissor` | [详细文档](apply-scissor.md) | +| `SetClearColor` | [详细文档](set-clear-color.md) | +| `Clear` | [详细文档](../../../memory/linear-allocator/clear.md) | +| `AttachShader` | [详细文档](attach-shader.md) | +| `DetachShader` | [详细文档](detach-shader.md) | +| `GetDepthStencilState` | [详细文档](get-depth-stencil-state.md) | +| `GetBlendState` | [详细文档](get-blend-state.md) | +| `GetRasterizerState` | [详细文档](get-rasterizer-state.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) +- [RHIPipelineState](../../pipeline-state/pipeline-state.md) - 抽象管线状态接口 diff --git a/docs/api/rhi/opengl/pipeline-state/set-blend-state.md b/docs/api/rhi/opengl/pipeline-state/set-blend-state.md new file mode 100644 index 00000000..5f121d59 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/set-blend-state.md @@ -0,0 +1,27 @@ +# OpenGLPipelineState::SetBlendState + +```cpp +void SetBlendState(const OpenGLBlendState& state); +``` + +设置混合状态。 + +**参数：** +- `state` - 混合状态结构体 + +**线程安全：** ❌ + +**示例：** + +```cpp +OpenGLBlendState blendState; +blendState.blendEnable = true; +blendState.srcBlend = BlendFactor::SrcAlpha; +blendState.dstBlend = BlendFactor::InvSrcAlpha; +pipelineState->SetBlendState(blendState); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [GetBlendState](get-blend-state.md) - 获取混合状态 diff --git a/docs/api/rhi/opengl/pipeline-state/set-clear-color.md b/docs/api/rhi/opengl/pipeline-state/set-clear-color.md new file mode 100644 index 00000000..eca1f25b --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/set-clear-color.md @@ -0,0 +1,26 @@ +# OpenGLPipelineState::SetClearColor + +```cpp +void SetClearColor(float r, float g, float b, float a); +``` + +设置清除颜色值。 + +**参数：** +- `r` - 红色通道 (0.0 ~ 1.0) +- `g` - 绿色通道 (0.0 ~ 1.0) +- `b` - 蓝色通道 (0.0 ~ 1.0) +- `a` - Alpha 通道 (0.0 ~ 1.0) + +**线程安全：** ❌ + +**示例：** + +```cpp +pipelineState->SetClearColor(0.1f, 0.1f, 0.1f, 1.0f); +pipelineState->Clear(GL_COLOR_BUFFER_BIT); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/pipeline-state/set-depth-stencil-state.md b/docs/api/rhi/opengl/pipeline-state/set-depth-stencil-state.md new file mode 100644 index 00000000..e6346536 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/set-depth-stencil-state.md @@ -0,0 +1,27 @@ +# OpenGLPipelineState::SetDepthStencilState + +```cpp +void SetDepthStencilState(const OpenGLDepthStencilState& state); +``` + +设置深度模板状态。 + +**参数：** +- `state` - 深度模板状态结构体 + +**线程安全：** ❌ + +**示例：** + +```cpp +OpenGLDepthStencilState dsState; +dsState.depthTestEnable = true; +dsState.depthWriteEnable = true; +dsState.depthFunc = ComparisonFunc::Less; +pipelineState->SetDepthStencilState(dsState); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [GetDepthStencilState](get-depth-stencil-state.md) - 获取深度模板状态 diff --git a/docs/api/rhi/opengl/pipeline-state/set-logical-operation.md b/docs/api/rhi/opengl/pipeline-state/set-logical-operation.md new file mode 100644 index 00000000..531f5441 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/set-logical-operation.md @@ -0,0 +1,25 @@ +# OpenGLPipelineState::SetLogicalOperation + +```cpp +void SetLogicalOperation(const LogicalOperation& state); +``` + +设置逻辑操作状态。 + +**参数：** +- `state` - 逻辑操作状态结构体 + +**线程安全：** ❌ + +**示例：** + +```cpp +LogicalOperation op; +op.enable = false; +op.operation = 0; +pipelineState->SetLogicalOperation(op); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/pipeline-state/set-rasterizer-state.md b/docs/api/rhi/opengl/pipeline-state/set-rasterizer-state.md new file mode 100644 index 00000000..c46b9911 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/set-rasterizer-state.md @@ -0,0 +1,27 @@ +# OpenGLPipelineState::SetRasterizerState + +```cpp +void SetRasterizerState(const OpenGLRasterizerState& state); +``` + +设置光栅化状态。 + +**参数：** +- `state` - 光栅化状态结构体 + +**线程安全：** ❌ + +**示例：** + +```cpp +OpenGLRasterizerState rsState; +rsState.cullFaceEnable = true; +rsState.cullFace = CullFace::Back; +rsState.frontFace = FrontFace::CounterClockwise; +pipelineState->SetRasterizerState(rsState); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [GetRasterizerState](get-rasterizer-state.md) - 获取光栅化状态 diff --git a/docs/api/rhi/opengl/pipeline-state/set-scissor.md b/docs/api/rhi/opengl/pipeline-state/set-scissor.md new file mode 100644 index 00000000..d9301885 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/set-scissor.md @@ -0,0 +1,29 @@ +# OpenGLPipelineState::SetScissor + +```cpp +void SetScissor(const ScissorState& state); +``` + +设置裁剪状态。 + +**参数：** +- `state` - 裁剪状态结构体 + +**线程安全：** ❌ + +**示例：** + +```cpp +ScissorState scissor; +scissor.enable = true; +scissor.x = 0; +scissor.y = 0; +scissor.width = 1920; +scissor.height = 1080; +pipelineState->SetScissor(scissor); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [ApplyScissor](apply-scissor.md) - 应用裁剪状态 diff --git a/docs/api/rhi/opengl/pipeline-state/set-viewport.md b/docs/api/rhi/opengl/pipeline-state/set-viewport.md new file mode 100644 index 00000000..1e5e5f1b --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/set-viewport.md @@ -0,0 +1,30 @@ +# OpenGLPipelineState::SetViewport + +```cpp +void SetViewport(const ViewportState& state); +``` + +设置视口状态。 + +**参数：** +- `state` - 视口状态结构体 + +**线程安全：** ❌ + +**示例：** + +```cpp +ViewportState viewport; +viewport.x = 0; +viewport.y = 0; +viewport.width = 1920; +viewport.height = 1080; +viewport.minDepth = 0.0f; +viewport.maxDepth = 1.0f; +pipelineState->SetViewport(viewport); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [ApplyViewport](apply-viewport.md) - 应用视口状态 diff --git a/docs/api/rhi/opengl/render-target-view/bind-framebuffer.md b/docs/api/rhi/opengl/render-target-view/bind-framebuffer.md new file mode 100644 index 00000000..969ff3f2 --- /dev/null +++ b/docs/api/rhi/opengl/render-target-view/bind-framebuffer.md @@ -0,0 +1,20 @@ +# OpenGLRenderTargetView::BindFramebuffer + +```cpp +static void BindFramebuffer(unsigned int framebuffer) +``` + +静态方法，将指定帧缓冲区绑定为当前渲染目标。 + +**参数：** +- `framebuffer` - 帧缓冲区 ID（0 表示解除绑定） + +**示例：** + +```cpp +OpenGLRenderTargetView::BindFramebuffer(rtv.GetFramebuffer()); +``` + +## 相关文档 + +- [OpenGLRenderTargetView](render-target-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/render-target-view/get-framebuffer.md b/docs/api/rhi/opengl/render-target-view/get-framebuffer.md new file mode 100644 index 00000000..cb6d40fc --- /dev/null +++ b/docs/api/rhi/opengl/render-target-view/get-framebuffer.md @@ -0,0 +1,19 @@ +# OpenGLRenderTargetView::GetFramebuffer + +```cpp +unsigned int GetFramebuffer() const +``` + +获取帧缓冲区对象 ID。 + +**返回：** `unsigned int` - 帧缓冲区 ID + +**示例：** + +```cpp +unsigned int fbo = rtv.GetFramebuffer(); +``` + +## 相关文档 + +- [OpenGLRenderTargetView](render-target-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/render-target-view/get-mip-level.md b/docs/api/rhi/opengl/render-target-view/get-mip-level.md new file mode 100644 index 00000000..a791bad8 --- /dev/null +++ b/docs/api/rhi/opengl/render-target-view/get-mip-level.md @@ -0,0 +1,19 @@ +# OpenGLRenderTargetView::GetMipLevel + +```cpp +int GetMipLevel() const +``` + +获取 mipmap 级别。 + +**返回：** `int` - mip 级别 + +**示例：** + +```cpp +int mipLevel = rtv.GetMipLevel(); +``` + +## 相关文档 + +- [OpenGLRenderTargetView](render-target-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/render-target-view/get-texture.md b/docs/api/rhi/opengl/render-target-view/get-texture.md new file mode 100644 index 00000000..e3b9af55 --- /dev/null +++ b/docs/api/rhi/opengl/render-target-view/get-texture.md @@ -0,0 +1,19 @@ +# OpenGLRenderTargetView::GetTexture + +```cpp +unsigned int GetTexture() const +``` + +获取关联的纹理对象 ID。 + +**返回：** `unsigned int` - 纹理 ID + +**示例：** + +```cpp +unsigned int tex = rtv.GetTexture(); +``` + +## 相关文档 + +- [OpenGLRenderTargetView](render-target-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/render-target-view/initialize-cubemap.md b/docs/api/rhi/opengl/render-target-view/initialize-cubemap.md new file mode 100644 index 00000000..b960da50 --- /dev/null +++ b/docs/api/rhi/opengl/render-target-view/initialize-cubemap.md @@ -0,0 +1,25 @@ +# OpenGLRenderTargetView::InitializeCubemap + +```cpp +bool InitializeCubemap(unsigned int cubemap, int face, int mipLevel = 0) +``` + +初始化立方体贴图的渲染目标视图。 + +**参数：** +- `cubemap` - 立方体贴图对象 ID +- `face` - 立方体贴面索引（0-5） +- `mipLevel` - mipmap 级别（默认为 0） + +**返回：** `bool` - 成功返回 true，失败返回 false + +**示例：** + +```cpp +OpenGLRenderTargetView rtv; +rtv.InitializeCubemap(cubemapTexture, 0, 0); +``` + +## 相关文档 + +- [OpenGLRenderTargetView](render-target-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/render-target-view/render-target-view.md b/docs/api/rhi/opengl/render-target-view/render-target-view.md new file mode 100644 index 00000000..7c1fdb2a --- /dev/null +++ b/docs/api/rhi/opengl/render-target-view/render-target-view.md @@ -0,0 +1,26 @@ +# OpenGLRenderTargetView + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 渲染目标视图实现。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `InitializeCubemap` | [详细文档](initialize-cubemap.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Bind` | [详细文档](../../shader/bind.md) | +| `Unbind` | [详细文档](../../shader/unbind.md) | +| `Clear` | [详细文档](../../../memory/linear-allocator/clear.md) | +| `GetFramebuffer` | [详细文档](get-framebuffer.md) | +| `GetTexture` | [详细文档](get-texture.md) | +| `GetMipLevel` | [详细文档](get-mip-level.md) | +| `GetWidth` / `GetHeight` | [详细文档](../../buffer/get-size.md) | +| `BindFramebuffer` | [详细文档](bind-framebuffer.md) | +| `UnbindFramebuffer` | [详细文档](unbind-framebuffer.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) diff --git a/docs/api/rhi/opengl/render-target-view/unbind-framebuffer.md b/docs/api/rhi/opengl/render-target-view/unbind-framebuffer.md new file mode 100644 index 00000000..b90f020e --- /dev/null +++ b/docs/api/rhi/opengl/render-target-view/unbind-framebuffer.md @@ -0,0 +1,17 @@ +# OpenGLRenderTargetView::UnbindFramebuffer + +```cpp +static void UnbindFramebuffer() +``` + +静态方法，解除当前渲染目标帧缓冲区的绑定。 + +**示例：** + +```cpp +OpenGLRenderTargetView::UnbindFramebuffer(); +``` + +## 相关文档 + +- [OpenGLRenderTargetView](render-target-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/sampler/get-id.md b/docs/api/rhi/opengl/sampler/get-id.md new file mode 100644 index 00000000..80340840 --- /dev/null +++ b/docs/api/rhi/opengl/sampler/get-id.md @@ -0,0 +1,21 @@ +# OpenGLSampler::GetID + +```cpp +unsigned int GetID() const +unsigned int GetID() override +``` + +获取 OpenGL 采样器对象 ID。 + +**返回：** `unsigned int` - 采样器 ID + +**示例：** + +```cpp +unsigned int samplerID = sampler.GetID(); +glBindSampler(0, samplerID); +``` + +## 相关文档 + +- [OpenGLSampler](sampler.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/sampler/sampler.md b/docs/api/rhi/opengl/sampler/sampler.md new file mode 100644 index 00000000..0dea5d69 --- /dev/null +++ b/docs/api/rhi/opengl/sampler/sampler.md @@ -0,0 +1,21 @@ +# OpenGLSampler + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 采样器实现，继承自 `RHISampler`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Bind` | [详细文档](../../shader/bind.md) | +| `Unbind` | [详细文档](../../shader/unbind.md) | +| `GetID` | [详细文档](get-id.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) +- [RHISampler](../../sampler/sampler.md) - 抽象采样器接口 diff --git a/docs/api/rhi/opengl/shader/compile-compute.md b/docs/api/rhi/opengl/shader/compile-compute.md new file mode 100644 index 00000000..f5d05cd7 --- /dev/null +++ b/docs/api/rhi/opengl/shader/compile-compute.md @@ -0,0 +1,30 @@ +# OpenGLShader::CompileCompute + +```cpp +bool CompileCompute(const char* computeSource); +``` + +从源代码编译计算着色器。 + +**参数：** +- `computeSource` - 计算着色器源代码 + +**返回：** 成功返回 `true`，失败返回 `false` + +**线程安全：** ❌ + +**示例：** + +```cpp +const char* cs = R"( + #version 430 core + layout(local_size_x = 16, local_size_y = 16) in; + void main() { /* compute logic */ } +)"; +shader->CompileCompute(cs); +``` + +## 相关文档 + +- [OpenGLShader 总览](shader.md) - 返回类总览 +- [Compile (VS+FS)](compile-vs-fs.md) - 图形着色器版本 diff --git a/docs/api/rhi/opengl/shader/compile-from-file-vs-fs.md b/docs/api/rhi/opengl/shader/compile-from-file-vs-fs.md new file mode 100644 index 00000000..7ed115a1 --- /dev/null +++ b/docs/api/rhi/opengl/shader/compile-from-file-vs-fs.md @@ -0,0 +1,25 @@ +# OpenGLShader::CompileFromFile (VS+FS) + +```cpp +bool CompileFromFile(const char* vertexPath, const char* fragmentPath); +``` + +从文件编译顶点着色器和片段着色器。 + +**参数：** +- `vertexPath` - 顶点着色器文件路径 +- `fragmentPath` - 片段着色器文件路径 + +**返回：** 成功返回 `true`，失败返回 `false` + +**示例：** + +```cpp +shader->CompileFromFile("shaders/vertex.glsl", "shaders/fragment.glsl"); +shader->Use(); +``` + +## 相关文档 + +- [OpenGLShader 总览](shader.md) - 返回类总览 +- [CompileFromFile (VS+GS+FS)](compile-from-file-vs-gs-fs.md) - 带几何着色器版本 diff --git a/docs/api/rhi/opengl/shader/compile-from-file-vs-gs-fs.md b/docs/api/rhi/opengl/shader/compile-from-file-vs-gs-fs.md new file mode 100644 index 00000000..b79c5170 --- /dev/null +++ b/docs/api/rhi/opengl/shader/compile-from-file-vs-gs-fs.md @@ -0,0 +1,26 @@ +# OpenGLShader::CompileFromFile (VS+GS+FS) + +```cpp +bool CompileFromFile(const char* vertexPath, const char* fragmentPath, const char* geometryPath); +``` + +从文件编译顶点着色器、几何着色器和片段着色器。 + +**参数：** +- `vertexPath` - 顶点着色器文件路径 +- `fragmentPath` - 片段着色器文件路径 +- `geometryPath` - 几何着色器文件路径 + +**返回：** 成功返回 `true`，失败返回 `false` + +**示例：** + +```cpp +shader->CompileFromFile("shaders/vertex.glsl", "shaders/fragment.glsl", "shaders/geometry.glsl"); +shader->Use(); +``` + +## 相关文档 + +- [OpenGLShader 总览](shader.md) - 返回类总览 +- [CompileFromFile (VS+FS)](compile-from-file-vs-fs.md) - 不带几何着色器版本 diff --git a/docs/api/rhi/opengl/shader/compile-vs-fs.md b/docs/api/rhi/opengl/shader/compile-vs-fs.md new file mode 100644 index 00000000..8aa96f4c --- /dev/null +++ b/docs/api/rhi/opengl/shader/compile-vs-fs.md @@ -0,0 +1,34 @@ +# OpenGLShader::Compile (VS+FS) + +```cpp +bool Compile(const char* vertexSource, const char* fragmentSource); +``` + +从源代码编译顶点着色器和片段着色器。 + +**参数：** +- `vertexSource` - 顶点着色器源代码 +- `fragmentSource` - 片段着色器源代码 + +**返回：** 成功返回 `true`，失败返回 `false` + +**示例：** + +```cpp +const char* vs = R"( + #version 330 core + void main() { gl_Position = vec4(0.0); } +)"; +const char* fs = R"( + #version 330 core + out vec4 color; + void main() { color = vec4(1.0); } +)"; +shader->Compile(vs, fs); +shader->Use(); +``` + +## 相关文档 + +- [OpenGLShader 总览](shader.md) - 返回类总览 +- [CompileCompute](compile-compute.md) - 计算着色器版本 diff --git a/docs/api/rhi/opengl/shader/get-id.md b/docs/api/rhi/opengl/shader/get-id.md new file mode 100644 index 00000000..6b8bfb65 --- /dev/null +++ b/docs/api/rhi/opengl/shader/get-id.md @@ -0,0 +1,23 @@ +# OpenGLShader::GetID + +```cpp +unsigned int GetID() const; +``` + +获取 OpenGL 着色器程序 ID。 + +**返回：** OpenGL 程序对象 ID + +**线程安全：** ❌ + +**示例：** + +```cpp +unsigned int programId = shader->GetID(); +glUseProgram(programId); +``` + +## 相关文档 + +- [OpenGLShader 总览](shader.md) - 返回类总览 +- [GetNativeHandle](../../buffer/get-native-handle.md) - 原生句柄 diff --git a/docs/api/rhi/opengl/shader/get-uniform-location.md b/docs/api/rhi/opengl/shader/get-uniform-location.md new file mode 100644 index 00000000..aa658d07 --- /dev/null +++ b/docs/api/rhi/opengl/shader/get-uniform-location.md @@ -0,0 +1,27 @@ +# OpenGLShader::GetUniformLocation + +```cpp +int GetUniformLocation(const char* name) const; +``` + +获取 Uniform 变量的位置索引。 + +**参数：** +- `name` - Uniform 变量名称 + +**返回：** Uniform 位置索引，失败返回 -1 + +**线程安全：** ❌ + +**示例：** + +```cpp +int loc = shader->GetUniformLocation("modelMatrix"); +if (loc != -1) { + glUniformMatrix4fv(loc, 1, GL_FALSE, &modelMatrix[0][0]); +} +``` + +## 相关文档 + +- [OpenGLShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/shader/set-float-array.md b/docs/api/rhi/opengl/shader/set-float-array.md new file mode 100644 index 00000000..4852a204 --- /dev/null +++ b/docs/api/rhi/opengl/shader/set-float-array.md @@ -0,0 +1,26 @@ +# OpenGLShader::SetFloatArray + +```cpp +void SetFloatArray(const char* name, const float* values, unsigned int count); +``` + +设置浮点数数组 Uniform 变量。 + +**参数：** +- `name` - Uniform 变量名称 +- `values` - 浮点数数组指针 +- `count` - 数组元素数量 + +**线程安全：** ❌ + +**示例：** + +```cpp +float weights[] = { 0.25f, 0.25f, 0.25f, 0.25f }; +shader->SetFloatArray("vertexWeights", weights, 4); +``` + +## 相关文档 + +- [OpenGLShader 总览](shader.md) - 返回类总览 +- [SetFloat](../../shader/set-float.md) - 单个浮点数版本 diff --git a/docs/api/rhi/opengl/shader/set-int-array.md b/docs/api/rhi/opengl/shader/set-int-array.md new file mode 100644 index 00000000..600f662d --- /dev/null +++ b/docs/api/rhi/opengl/shader/set-int-array.md @@ -0,0 +1,26 @@ +# OpenGLShader::SetIntArray + +```cpp +void SetIntArray(const char* name, const int* values, unsigned int count); +``` + +设置整数数组 Uniform 变量。 + +**参数：** +- `name` - Uniform 变量名称 +- `values` - 整数数组指针 +- `count` - 数组元素数量 + +**线程安全：** ❌ + +**示例：** + +```cpp +int indices[] = { 0, 1, 2, 3 }; +shader->SetIntArray("boneIndices", indices, 4); +``` + +## 相关文档 + +- [OpenGLShader 总览](shader.md) - 返回类总览 +- [SetInt](../../shader/set-int.md) - 单个整数版本 diff --git a/docs/api/rhi/opengl/shader/shader.md b/docs/api/rhi/opengl/shader/shader.md new file mode 100644 index 00000000..135bec19 --- /dev/null +++ b/docs/api/rhi/opengl/shader/shader.md @@ -0,0 +1,36 @@ +# OpenGLShader + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 着色器实现，继承自 `RHIShader`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `CompileFromFile` | [详细文档](../../shader/compile-from-file.md) | +| `Compile` | [详细文档](../../shader/compile.md) | +| `CompileFromFile` (VS+FS) | [详细文档](compile-from-file-vs-fs.md) | +| `CompileFromFile` (VS+GS+FS) | [详细文档](compile-from-file-vs-gs-fs.md) | +| `Compile` (VS+FS) | [详细文档](compile-vs-fs.md) | +| `CompileCompute` | [详细文档](compile-compute.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Use` | [详细文档](use.md) | +| `Bind` / `Unbind` | [详细文档](../../shader/bind.md) | +| `SetInt` | [详细文档](../../shader/set-int.md) | +| `SetIntArray` | [详细文档](set-int-array.md) | +| `SetFloat` | [详细文档](../../shader/set-float.md) | +| `SetFloatArray` | [详细文档](set-float-array.md) | +| `SetVec3` | [详细文档](../../shader/set-vec3.md) | +| `SetVec4` | [详细文档](../../shader/set-vec4.md) | +| `SetMat4` | [详细文档](../../shader/set-mat4.md) | +| `GetUniformLocation` | [详细文档](get-uniform-location.md) | +| `GetID` | [详细文档](get-id.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `IsValid` | [详细文档](../../shader/is-valid.md) | +| `GetType` | [详细文档](../../shader/get-type.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) +- [RHIShader](../../shader/shader.md) - 抽象着色器接口 diff --git a/docs/api/rhi/opengl/shader/use.md b/docs/api/rhi/opengl/shader/use.md new file mode 100644 index 00000000..91d4b18a --- /dev/null +++ b/docs/api/rhi/opengl/shader/use.md @@ -0,0 +1,21 @@ +# OpenGLShader::Use + +```cpp +void Use() const; +``` + +激活并使用当前着色器程序。 + +**线程安全：** ❌ + +**示例：** + +```cpp +shader->Use(); +// 渲染操作使用此着色器 +``` + +## 相关文档 + +- [OpenGLShader 总览](shader.md) - 返回类总览 +- [Bind/Unbind](../../shader/bind.md) - 基类绑定接口 diff --git a/docs/api/rhi/opengl/swap-chain/get-framebuffer-size.md b/docs/api/rhi/opengl/swap-chain/get-framebuffer-size.md new file mode 100644 index 00000000..174fc44d --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/get-framebuffer-size.md @@ -0,0 +1,23 @@ +# OpenGLSwapChain::GetFramebufferSize + +```cpp +void SetFramebufferSize(int width, int height); +``` + +设置帧缓冲区大小。 + +**参数：** +- `width` - 帧缓冲区宽度 +- `height` - 帧缓冲区高度 + +**线程安全：** ❌ + +**示例：** + +```cpp +swapChain->SetFramebufferSize(1920, 1080); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/swap-chain/get-window.md b/docs/api/rhi/opengl/swap-chain/get-window.md new file mode 100644 index 00000000..3014baf5 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/get-window.md @@ -0,0 +1,22 @@ +# OpenGLSwapChain::GetWindow + +```cpp +GLFWwindow* GetWindow() const; +``` + +获取关联的 GLFW 窗口指针。 + +**返回：** GLFW 窗口指针 + +**线程安全：** ❌ + +**示例：** + +```cpp +GLFWwindow* window = swapChain->GetWindow(); +glfwSetWindowTitle(window, "New Title"); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/swap-chain/initialize-mode.md b/docs/api/rhi/opengl/swap-chain/initialize-mode.md new file mode 100644 index 00000000..96b9fa60 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/initialize-mode.md @@ -0,0 +1,25 @@ +# OpenGLSwapChain::Initialize (mode) + +```cpp +bool Initialize(GLFWwindow* window, int width, int height, PresentMode mode = PresentMode::VSync); +``` + +使用指定显示模式初始化交换链。 + +**参数：** +- `window` - GLFW 窗口指针 +- `width` - 交换链宽度 +- `height` - 交换链高度 +- `mode` - 呈现模式（默认 VSync） + +**返回：** 成功返回 `true`，失败返回 `false` + +**示例：** + +```cpp +swapChain->Initialize(window, 1920, 1080, PresentMode::VSync); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/swap-chain/is-fullscreen.md b/docs/api/rhi/opengl/swap-chain/is-fullscreen.md new file mode 100644 index 00000000..73b7059a --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/is-fullscreen.md @@ -0,0 +1,24 @@ +# OpenGLSwapChain::IsFullscreen + +```cpp +bool IsFullscreen() const; +``` + +查询是否处于全屏模式。 + +**返回：** `true` 表示全屏模式，`false` 表示窗口模式 + +**线程安全：** ❌ + +**示例：** + +```cpp +if (swapChain->IsFullscreen()) { + // 全屏模式 +} +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [SetFullscreen](set-fullscreen.md) - 设置全屏模式 diff --git a/docs/api/rhi/opengl/swap-chain/is-vsync.md b/docs/api/rhi/opengl/swap-chain/is-vsync.md new file mode 100644 index 00000000..8182a608 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/is-vsync.md @@ -0,0 +1,24 @@ +# OpenGLSwapChain::IsVSync + +```cpp +bool IsVSync() const; +``` + +查询垂直同步是否启用。 + +**返回：** `true` 表示启用垂直同步，`false` 表示禁用 + +**线程安全：** ❌ + +**示例：** + +```cpp +if (swapChain->IsVSync()) { + // 垂直同步已启用 +} +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [SetVSync](set-vsync.md) - 设置垂直同步 diff --git a/docs/api/rhi/opengl/swap-chain/poll-events.md b/docs/api/rhi/opengl/swap-chain/poll-events.md new file mode 100644 index 00000000..caa6ba40 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/poll-events.md @@ -0,0 +1,22 @@ +# OpenGLSwapChain::PollEvents + +```cpp +void PollEvents(); +``` + +处理所有待处理的窗口事件。 + +**线程安全：** ❌ + +**示例：** + +```cpp +while (!swapChain->ShouldClose()) { + swapChain->PollEvents(); + // 渲染逻辑 +} +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/swap-chain/present.md b/docs/api/rhi/opengl/swap-chain/present.md new file mode 100644 index 00000000..4eb86faf --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/present.md @@ -0,0 +1,24 @@ +# OpenGLSwapChain::Present + +```cpp +void Present(uint32_t syncInterval = 1, uint32_t flags = 0); +``` + +呈现渲染结果到屏幕。 + +**参数：** +- `syncInterval` - 垂直同步间隔（0=立即，1+=等待垂直同步） +- `flags` - 呈现标志 + +**线程安全：** ❌ + +**示例：** + +```cpp +swapChain->Present(1, 0); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [SwapBuffers](swap-buffers.md) - 直接交换缓冲区 diff --git a/docs/api/rhi/opengl/swap-chain/set-fullscreen.md b/docs/api/rhi/opengl/swap-chain/set-fullscreen.md new file mode 100644 index 00000000..92ef5733 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/set-fullscreen.md @@ -0,0 +1,23 @@ +# OpenGLSwapChain::SetFullscreen + +```cpp +void SetFullscreen(bool fullscreen); +``` + +设置全屏模式。 + +**参数：** +- `fullscreen` - 是否切换到全屏模式 + +**线程安全：** ❌ + +**示例：** + +```cpp +swapChain->SetFullscreen(true); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [IsFullscreen](is-fullscreen.md) - 查询全屏状态 diff --git a/docs/api/rhi/opengl/swap-chain/set-should-close.md b/docs/api/rhi/opengl/swap-chain/set-should-close.md new file mode 100644 index 00000000..ccfd3316 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/set-should-close.md @@ -0,0 +1,23 @@ +# OpenGLSwapChain::SetShouldClose + +```cpp +void SetShouldClose(bool shouldClose); +``` + +设置窗口关闭标志。 + +**参数：** +- `shouldClose` - 是否应该关闭 + +**线程安全：** ❌ + +**示例：** + +```cpp +swapChain->SetShouldClose(true); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [ShouldClose](should-close.md) - 查询关闭标志 diff --git a/docs/api/rhi/opengl/swap-chain/set-vsync.md b/docs/api/rhi/opengl/swap-chain/set-vsync.md new file mode 100644 index 00000000..9c872262 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/set-vsync.md @@ -0,0 +1,23 @@ +# OpenGLSwapChain::SetVSync + +```cpp +void SetVSync(bool enabled); +``` + +设置垂直同步开关。 + +**参数：** +- `enabled` - 是否启用垂直同步 + +**线程安全：** ❌ + +**示例：** + +```cpp +swapChain->SetVSync(true); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [IsVSync](is-vsync.md) - 查询垂直同步状态 diff --git a/docs/api/rhi/opengl/swap-chain/should-close.md b/docs/api/rhi/opengl/swap-chain/should-close.md new file mode 100644 index 00000000..2ba2d565 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/should-close.md @@ -0,0 +1,25 @@ +# OpenGLSwapChain::ShouldClose + +```cpp +bool ShouldClose() const; +``` + +查询窗口是否应该关闭。 + +**返回：** `true` 表示应该关闭，`false` 表示继续运行 + +**线程安全：** ❌ + +**示例：** + +```cpp +while (!swapChain->ShouldClose()) { + swapChain->PollEvents(); + // 渲染逻辑 +} +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [SetShouldClose](set-should-close.md) - 设置关闭标志 diff --git a/docs/api/rhi/opengl/swap-chain/swap-buffers.md b/docs/api/rhi/opengl/swap-chain/swap-buffers.md new file mode 100644 index 00000000..771345b6 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/swap-buffers.md @@ -0,0 +1,20 @@ +# OpenGLSwapChain::SwapBuffers + +```cpp +void SwapBuffers(); +``` + +直接交换前后缓冲区。 + +**线程安全：** ❌ + +**示例：** + +```cpp +swapChain->SwapBuffers(); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [Present](present.md) - 呈现（带垂直同步） diff --git a/docs/api/rhi/opengl/swap-chain/swap-chain.md b/docs/api/rhi/opengl/swap-chain/swap-chain.md new file mode 100644 index 00000000..6ec7ec48 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/swap-chain.md @@ -0,0 +1,34 @@ +# OpenGLSwapChain + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 交换链实现，继承自 `RHISwapChain`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` (vsync) | [详细文档](../../../threading/task-system/initialize.md) | +| `Initialize` (mode) | [详细文档](initialize-mode.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Present` | [详细文档](present.md) | +| `SwapBuffers` | [详细文档](swap-buffers.md) | +| `Resize` | [详细文档](../../../containers/array/resize.md) | +| `SetVSync` | [详细文档](set-vsync.md) | +| `IsVSync` | [详细文档](is-vsync.md) | +| `SetFullscreen` | [详细文档](set-fullscreen.md) | +| `IsFullscreen` | [详细文档](is-fullscreen.md) | +| `ShouldClose` | [详细文档](should-close.md) | +| `SetShouldClose` | [详细文档](set-should-close.md) | +| `PollEvents` | [详细文档](poll-events.md) | +| `GetCurrentBackBufferIndex` | [详细文档](../../swap-chain/get-current-back-buffer-index.md) | +| `GetCurrentBackBuffer` | [详细文档](../../swap-chain/get-current-back-buffer.md) | +| `GetWidth` / `GetHeight` | [详细文档](../../buffer/get-size.md) | +| `GetFramebufferWidth` / `GetFramebufferHeight` | [详细文档](get-framebuffer-size.md) | +| `GetWindow` | [详细文档](get-window.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) +- [RHISwapChain](../../swap-chain/swap-chain.md) - 抽象交换链接口 diff --git a/docs/api/rhi/opengl/texture/bind-image.md b/docs/api/rhi/opengl/texture/bind-image.md new file mode 100644 index 00000000..78739611 --- /dev/null +++ b/docs/api/rhi/opengl/texture/bind-image.md @@ -0,0 +1,22 @@ +# OpenGLTexture::BindImage + +```cpp +void BindImage(int slot, bool read, bool write) const +``` + +将纹理绑定到图像单元，用于着色器图像访问。 + +**参数：** +- `slot` - 图像单元槽位 +- `read` - 是否可读 +- `write` - 是否可写 + +**示例：** + +```cpp +texture.BindImage(0, true, false); // 只读访问 +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/texture/generate-mipmap.md b/docs/api/rhi/opengl/texture/generate-mipmap.md new file mode 100644 index 00000000..b7126d0e --- /dev/null +++ b/docs/api/rhi/opengl/texture/generate-mipmap.md @@ -0,0 +1,18 @@ +# OpenGLTexture::GenerateMipmap + +```cpp +void GenerateMipmap() +``` + +生成纹理的 mipmap。 + +**示例：** + +```cpp +texture.LoadFromFile("assets/textures/wood.jpg"); +texture.GenerateMipmap(); +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/texture/get-id.md b/docs/api/rhi/opengl/texture/get-id.md new file mode 100644 index 00000000..b43ecb99 --- /dev/null +++ b/docs/api/rhi/opengl/texture/get-id.md @@ -0,0 +1,20 @@ +# OpenGLTexture::GetID + +```cpp +unsigned int GetID() const +``` + +获取 OpenGL 纹理对象 ID。 + +**返回：** `unsigned int` - OpenGL 纹理 ID + +**示例：** + +```cpp +unsigned int texID = texture.GetID(); +glBindTexture(GL_TEXTURE_2D, texID); +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/texture/get-opengl-type.md b/docs/api/rhi/opengl/texture/get-opengl-type.md new file mode 100644 index 00000000..f9dcf687 --- /dev/null +++ b/docs/api/rhi/opengl/texture/get-opengl-type.md @@ -0,0 +1,23 @@ +# OpenGLTexture::GetOpenGLType + +```cpp +OpenGLTextureType GetOpenGLType() const +``` + +获取纹理的 OpenGL 类型。 + +**返回：** `OpenGLTextureType` - 纹理类型枚举值： +- `OpenGLTextureType::Texture1D` +- `OpenGLTextureType::Texture2D` +- `OpenGLTextureType::TextureCube` +- 等等 + +**示例：** + +```cpp +OpenGLTextureType type = texture.GetOpenGLType(); +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/texture/initialize-2d.md b/docs/api/rhi/opengl/texture/initialize-2d.md new file mode 100644 index 00000000..14c1a663 --- /dev/null +++ b/docs/api/rhi/opengl/texture/initialize-2d.md @@ -0,0 +1,28 @@ +# OpenGLTexture::Initialize2D + +```cpp +bool Initialize2D(int width, int height, int channels, const void* data, bool generateMipmap = true) +``` + +初始化一个 2D 纹理。 + +**参数：** +- `width` - 纹理宽度（像素） +- `height` - 纹理高度（像素） +- `channels` - 通道数（1=R, 2=RG, 4=RGBA） +- `data` - 纹理数据指针（可以为 nullptr 创建空纹理） +- `generateMipmap` - 是否自动生成 mipmap（默认为 true） + +**返回：** `bool` - 成功返回 true，失败返回 false + +**示例：** + +```cpp +OpenGLTexture texture; +std::vector pixels(width * height * 4); +texture.Initialize2D(width, height, 4, pixels.data(), true); +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/texture/initialize-cube-map.md b/docs/api/rhi/opengl/texture/initialize-cube-map.md new file mode 100644 index 00000000..0a5242f4 --- /dev/null +++ b/docs/api/rhi/opengl/texture/initialize-cube-map.md @@ -0,0 +1,26 @@ +# OpenGLTexture::InitializeCubeMap + +```cpp +bool InitializeCubeMap(int size, int mipLevels, OpenGLFormat format, const void* data = nullptr) +``` + +初始化一个立方体纹理。 + +**参数：** +- `size` - 立方体贴面的边长 +- `mipLevels` - mipmap 级别数量 +- `format` - 纹理格式（OpenGLFormat 枚举值） +- `data` - 纹理数据指针（可以为 nullptr） + +**返回：** `bool` - 成功返回 true，失败返回 false + +**示例：** + +```cpp +OpenGLTexture cubemap; +cubemap.InitializeCubeMap(512, 1, OpenGLFormat::RGBA8, nullptr); +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/texture/load-from-file.md b/docs/api/rhi/opengl/texture/load-from-file.md new file mode 100644 index 00000000..be55ffc1 --- /dev/null +++ b/docs/api/rhi/opengl/texture/load-from-file.md @@ -0,0 +1,26 @@ +# OpenGLTexture::LoadFromFile + +```cpp +bool LoadFromFile(const char* path, bool flipVertical = true) +``` + +从图像文件加载纹理。 + +**参数：** +- `path` - 图像文件路径 +- `flipVertical` - 是否垂直翻转图像（默认为 true） + +**返回：** `bool` - 成功返回 true，失败返回 false + +**示例：** + +```cpp +OpenGLTexture texture; +if (texture.LoadFromFile("assets/textures/brick.jpg", true)) { + texture.GenerateMipmap(); +} +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/texture/set-filtering.md b/docs/api/rhi/opengl/texture/set-filtering.md new file mode 100644 index 00000000..50f91f9a --- /dev/null +++ b/docs/api/rhi/opengl/texture/set-filtering.md @@ -0,0 +1,21 @@ +# OpenGLTexture::SetFiltering + +```cpp +void SetFiltering(int minFilter, int magFilter) +``` + +设置纹理过滤模式。 + +**参数：** +- `minFilter` - 缩小过滤模式（GL_NEAREST, GL_LINEAR, GL_NEAREST_MIPMAP_NEAREST 等） +- `magFilter` - 放大过滤模式（GL_NEAREST, GL_LINEAR） + +**示例：** + +```cpp +texture.SetFiltering(GL_LINEAR_MIPMAP_LINEAR, GL_LINEAR); +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/texture/set-wrapping.md b/docs/api/rhi/opengl/texture/set-wrapping.md new file mode 100644 index 00000000..879307cf --- /dev/null +++ b/docs/api/rhi/opengl/texture/set-wrapping.md @@ -0,0 +1,22 @@ +# OpenGLTexture::SetWrapping + +```cpp +void SetWrapping(int wrapS, int wrapT, int wrapR = -1) +``` + +设置纹理环绕模式。 + +**参数：** +- `wrapS` - S 轴环绕模式（GL_REPEAT, GL_CLAMP_TO_EDGE 等） +- `wrapT` - T 轴环绕模式 +- `wrapR` - R 轴环绕模式（默认为 -1，表示与 wrapT 相同） + +**示例：** + +```cpp +texture.SetWrapping(GL_REPEAT, GL_REPEAT, GL_REPEAT); +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/texture/texture.md b/docs/api/rhi/opengl/texture/texture.md new file mode 100644 index 00000000..c413dab2 --- /dev/null +++ b/docs/api/rhi/opengl/texture/texture.md @@ -0,0 +1,37 @@ +# OpenGLTexture + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 纹理的实现，继承自 `RHITexture`。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `Initialize2D` | [详细文档](initialize-2d.md) | +| `InitializeCubeMap` | [详细文档](initialize-cube-map.md) | +| `LoadFromFile` | [详细文档](load-from-file.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Bind` | [详细文档](../../shader/bind.md) | +| `Unbind` | [详细文档](../../shader/unbind.md) | +| `BindImage` | [详细文档](bind-image.md) | +| `GenerateMipmap` | [详细文档](generate-mipmap.md) | +| `SetFiltering` | [详细文档](set-filtering.md) | +| `SetWrapping` | [详细文档](set-wrapping.md) | +| `GetID` | [详细文档](get-id.md) | +| `GetOpenGLType` | [详细文档](get-opengl-type.md) | +| `GetWidth` | [详细文档](../../texture/get-width.md) | +| `GetHeight` | [详细文档](../../texture/get-height.md) | +| `GetDepth` | [详细文档](../../texture/get-depth.md) | +| `GetMipLevels` | [详细文档](../../texture/get-mip-levels.md) | +| `GetTextureType` | [详细文档](../../texture/get-texture-type.md) | +| `GetNativeHandle` | [详细文档](../../buffer/get-native-handle.md) | +| `GetState` / `SetState` | [详细文档](../../buffer/get-state.md) | +| `GetName` / `SetName` | [详细文档](../../buffer/get-name.md) | +| `GetFormat` / `SetFormat` | [详细文档](../../texture/get-format.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) +- [RHITexture](../../texture/texture.md) - 抽象纹理接口 diff --git a/docs/api/rhi/opengl/vertex-array/add-vertex-buffer.md b/docs/api/rhi/opengl/vertex-array/add-vertex-buffer.md new file mode 100644 index 00000000..5af59a05 --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/add-vertex-buffer.md @@ -0,0 +1,28 @@ +# OpenGLVertexArray::AddVertexBuffer + +```cpp +void AddVertexBuffer(unsigned int buffer, const VertexAttribute& attribute) +``` + +添加顶点缓冲区并指定顶点属性。 + +**参数：** +- `buffer` - OpenGL 缓冲区对象 ID +- `attribute` - 顶点属性描述结构体 + +**示例：** + +```cpp +VertexAttribute attr; +attr.index = 0; +attr.count = 3; +attr.type = GL_FLOAT; +attr.normalized = GL_FALSE; +attr.stride = sizeof(Vertex); +attr.offset = 0; +vao.AddVertexBuffer(vbo, attr); +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/vertex-array/get-id.md b/docs/api/rhi/opengl/vertex-array/get-id.md new file mode 100644 index 00000000..b391419e --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/get-id.md @@ -0,0 +1,20 @@ +# OpenGLVertexArray::GetID + +```cpp +unsigned int GetID() const +``` + +获取 OpenGL 顶点数组对象 ID。 + +**返回：** `unsigned int` - VAO ID + +**示例：** + +```cpp +unsigned int vaoID = vao.GetID(); +glBindVertexArray(vaoID); +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/vertex-array/get-index-buffer.md b/docs/api/rhi/opengl/vertex-array/get-index-buffer.md new file mode 100644 index 00000000..9f2615dd --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/get-index-buffer.md @@ -0,0 +1,19 @@ +# OpenGLVertexArray::GetIndexBuffer + +```cpp +unsigned int GetIndexBuffer() const +``` + +获取索引缓冲区 ID。 + +**返回：** `unsigned int` - 索引缓冲区 ID + +**示例：** + +```cpp +unsigned int ibo = vao.GetIndexBuffer(); +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/vertex-array/get-index-count.md b/docs/api/rhi/opengl/vertex-array/get-index-count.md new file mode 100644 index 00000000..14b5ec7f --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/get-index-count.md @@ -0,0 +1,20 @@ +# OpenGLVertexArray::GetIndexCount + +```cpp +unsigned int GetIndexCount() const +``` + +获取索引数量。 + +**返回：** `unsigned int` - 索引数量 + +**示例：** + +```cpp +unsigned int count = vao.GetIndexCount(); +glDrawElements(GL_TRIANGLES, count, GL_UNSIGNED_INT, 0); +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/vertex-array/set-index-buffer.md b/docs/api/rhi/opengl/vertex-array/set-index-buffer.md new file mode 100644 index 00000000..866316b3 --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/set-index-buffer.md @@ -0,0 +1,21 @@ +# OpenGLVertexArray::SetIndexBuffer + +```cpp +void SetIndexBuffer(unsigned int buffer, unsigned int type) +``` + +设置索引缓冲区。 + +**参数：** +- `buffer` - OpenGL 缓冲区对象 ID +- `type` - 索引数据类型（GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT, GL_UNSIGNED_INT） + +**示例：** + +```cpp +vao.SetIndexBuffer(ibo, GL_UNSIGNED_INT); +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/vertex-array/vertex-array.md b/docs/api/rhi/opengl/vertex-array/vertex-array.md new file mode 100644 index 00000000..40fcfdb8 --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/vertex-array.md @@ -0,0 +1,23 @@ +# OpenGLVertexArray + +**命名空间**: `XCEngine::RHI` + +**描述**: OpenGL 顶点数组对象 (VAO) 封装。 + +## 方法列表 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../../threading/task-system/initialize.md) | +| `AddVertexBuffer` | [详细文档](add-vertex-buffer.md) | +| `SetIndexBuffer` | [详细文档](set-index-buffer.md) | +| `Shutdown` | [详细文档](../../../threading/task-system/shutdown.md) | +| `Bind` | [详细文档](../../shader/bind.md) | +| `Unbind` | [详细文档](../../shader/unbind.md) | +| `GetID` | [详细文档](get-id.md) | +| `GetIndexBuffer` | [详细文档](get-index-buffer.md) | +| `GetIndexCount` | [详细文档](get-index-count.md) | + +## 相关文档 + +- [OpenGL 后端总览](../overview.md) diff --git a/docs/api/rhi/pipeline-layout/methods.md b/docs/api/rhi/pipeline-layout/methods.md new file mode 100644 index 00000000..b0372042 --- /dev/null +++ b/docs/api/rhi/pipeline-layout/methods.md @@ -0,0 +1,25 @@ +# RHIPipelineLayout 方法 + +## Initialize + +```cpp +virtual bool Initialize(const RHIPipelineLayoutDesc& desc) = 0; +``` + +初始化管线布局。 + +## Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +释放管线布局资源。 + +## GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取原生 API 句柄。 diff --git a/docs/api/rhi/pipeline-layout/pipeline-layout.md b/docs/api/rhi/pipeline-layout/pipeline-layout.md new file mode 100644 index 00000000..2b4335e3 --- /dev/null +++ b/docs/api/rhi/pipeline-layout/pipeline-layout.md @@ -0,0 +1,27 @@ +# RHIPipelineLayout + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: GPU 渲染管线布局抽象接口，用于定义着色器资源的绑定布局。 + +## 公共方法 + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Initialize` | [详细文档](../../threading/task-system/initialize.md) | +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | + +### 其他 + +| 方法 | 文档 | +|------|------| +| `GetNativeHandle` | [详细文档](../buffer/get-native-handle.md) | + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHIDevice](../device/device.md) - 创建设备 diff --git a/docs/api/rhi/pipeline-state/methods.md b/docs/api/rhi/pipeline-state/methods.md new file mode 100644 index 00000000..c5618d64 --- /dev/null +++ b/docs/api/rhi/pipeline-state/methods.md @@ -0,0 +1,41 @@ +# RHIPipelineState 方法 + +## Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +释放管线状态对象。 + +## Bind + +```cpp +virtual void Bind() = 0; +``` + +绑定管线状态到管线。 + +## Unbind + +```cpp +virtual void Unbind() = 0; +``` + +解绑管线状态。 + +## GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取原生 API 句柄。 + +## GetType + +```cpp +virtual PipelineType GetType() const = 0; +``` + +获取管线类型。 diff --git a/docs/api/rhi/pipeline-state/pipeline-state.md b/docs/api/rhi/pipeline-state/pipeline-state.md new file mode 100644 index 00000000..56eaedb3 --- /dev/null +++ b/docs/api/rhi/pipeline-state/pipeline-state.md @@ -0,0 +1,42 @@ +# RHIPipelineState + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: GPU 渲染管线状态抽象接口，封装了渲染管线的各种固定功能配置。 + +## 公共方法 + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | + +### 绑定/解绑 + +| 方法 | 文档 | +|------|------| +| `Bind` | [详细文档](../shader/bind.md) | +| `Unbind` | [详细文档](../shader/unbind.md) | + +### 属性访问 + +| 方法 | 文档 | +|------|------| +| `GetNativeHandle` | [详细文档](../buffer/get-native-handle.md) | +| `GetType` | [详细文档](../shader/get-type.md) | + +## 管线类型 (PipelineType) + +| 枚举值 | 描述 | +|--------|------| +| `Graphics` | 图形渲染管线 | +| `Compute` | 计算管线 | +| `Raytracing` | 光线追踪管线 | + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHIDevice](../device/device.md) - 创建设备 diff --git a/docs/api/rhi/rhi-command-list.md b/docs/api/rhi/rhi-command-list.md deleted file mode 100644 index bc3d1528..00000000 --- a/docs/api/rhi/rhi-command-list.md +++ /dev/null @@ -1,179 +0,0 @@ -# RHICommandList - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: GPU 命令列表抽象接口，用于录制和执行 GPU 命令。 - -## 概述 - -`RHICommandList` 封装了 GPU 命令的录制和执行。每个后端实现需要提供命令列表的创建、重置、命令录制和关闭等功能。 - -## 公共类型 - -### DepthStencilState - -深度模板状态结构体。 - -```cpp -struct DepthStencilState { - bool depthEnable = true; // 启用深度测试 - bool depthWriteMask = true; // 深度写入掩码 - ComparisonFunc depthFunc; // 深度比较函数 - bool stencilEnable = false; // 启用模板测试 - uint8_t stencilReadMask = 0xFF; // 模板读取掩码 - uint8_t stencilWriteMask = 0xFF; // 模板写入掩码 - struct StencilOpDesc { // 模板操作描述 - StencilOp stencilFailOp; // 模板失败操作 - StencilOp stencilDepthFailOp; // 深度失败操作 - StencilOp stencilPassOp; // 通过操作 - ComparisonFunc stencilFunc; // 模板比较函数 - }; - StencilOpDesc frontFace; // 前面模板状态 - StencilOpDesc backFace; // 背面模板状态 -}; -``` - -### BlendState - -混合状态结构体。 - -```cpp -struct BlendState { - bool alphaToCoverageEnable = false; // Alpha 到覆盖 - bool independentBlendEnable = false; // 独立混合 - struct RenderTarget { // 渲染目标混合 - bool blendEnable; // 启用混合 - BlendFactor srcBlend; // 源混合因子 - BlendFactor dstBlend; // 目标混合因子 - BlendOp blendOp; // 混合操作 - BlendFactor srcBlendAlpha; // Alpha 源混合 - BlendFactor dstBlendAlpha; // Alpha 目标混合 - BlendOp blendOpAlpha; // Alpha 混合操作 - uint8_t renderTargetWriteMask; // 颜色写入掩码 - }; - RenderTarget renderTargets[8]; // 每个 RT 的混合状态 - float blendFactor[4]; // 全局混合因子 -}; -``` - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual void Shutdown()` | 释放命令列表资源 | - -### 命令录制控制 - -| 方法 | 描述 | -|------|------| -| `virtual void Reset()` | 重置命令列表，开始新的录制 | -| `virtual void Close()` | 关闭命令列表，结束录制 | - -### 资源状态转换 - -| 方法 | 描述 | -|------|------| -| `virtual void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter)` | 资源状态转换屏障 | - -### 渲染状态设置 - -| 方法 | 描述 | -|------|------| -| `virtual void SetPipelineState(void* pso)` | 设置管线状态对象 | -| `virtual void SetPrimitiveTopology(PrimitiveTopology topology)` | 设置图元拓扑 | -| `virtual void SetViewport(const Viewport& viewport)` | 设置视口 | -| `virtual void SetViewports(uint32_t count, const Viewport* viewports)` | 设置多个视口 | -| `virtual void SetScissorRect(const Rect& rect)` | 设置裁剪矩形 | -| `virtual void SetScissorRects(uint32_t count, const Rect* rects)` | 设置多个裁剪矩形 | -| `virtual void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr)` | 设置渲染目标 | - -### 深度/混合状态 - -| 方法 | 描述 | -|------|------| -| `virtual void SetDepthStencilState(const DepthStencilState& state)` | 设置深度模板状态 | -| `virtual void SetStencilRef(uint8_t ref)` | 设置模板参考值 | -| `virtual void SetBlendState(const BlendState& state)` | 设置混合状态 | -| `virtual void SetBlendFactor(const float factor[4])` | 设置混合因子 | - -### 顶点/索引缓冲 - -| 方法 | 描述 | -|------|------| -| `virtual void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride)` | 设置顶点缓冲 | -| `virtual void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides)` | 设置多个顶点缓冲 | -| `virtual void SetIndexBuffer(void* buffer, uint64_t offset, Format format)` | 设置索引缓冲 | - -### 绘制命令 - -| 方法 | 描述 | -|------|------| -| `virtual void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0)` | 绘制调用 | -| `virtual void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0)` | 索引绘制调用 | - -### 清除命令 - -| 方法 | 描述 | -|------|------| -| `virtual void Clear(float r, float g, float b, float a, uint32_t buffers)` | 清除缓冲 | -| `virtual void ClearRenderTarget(void* renderTarget, const float color[4])` | 清除渲染目标 | -| `virtual void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil)` | 清除深度模板 | - -### 资源复制 - -| 方法 | 描述 | -|------|------| -| `virtual void CopyResource(void* dst, void* src)` | 复制资源 | - -### 计算着色器 - -| 方法 | 描述 | -|------|------| -| `virtual void Dispatch(uint32_t x, uint32_t y, uint32_t z)` | 分发计算着色器 | - -## 图元拓扑类型 (PrimitiveTopology) - -| 枚举值 | 描述 | -|--------|------| -| `PointList` | 点列表 | -| `LineList` | 线段列表 | -| `LineStrip` | 线段条带 | -| `TriangleList` | 三角形列表 | -| `TriangleStrip` | 三角形条带 | -| `PatchList` | 补丁列表（曲面细分） | - -## 使用示例 - -```cpp -// 重置命令列表 -commandList->Reset(); - -// 设置渲染状态 -commandList->SetPipelineState(pipelineState); -commandList->SetPrimitiveTopology(PrimitiveTopology::TriangleList); -commandList->SetViewport(viewport); -commandList->SetRenderTargets(1, &renderTarget, depthStencil); - -// 设置顶点缓冲 -commandList->SetVertexBuffer(0, vertexBuffer->GetNativeHandle(), 0, sizeof(Vertex)); -commandList->SetIndexBuffer(indexBuffer->GetNativeHandle(), 0, Format::R32_UInt); - -// 绘制 -commandList->DrawIndexed(indexCount, 1, 0, 0, 0); - -// 关闭命令列表 -commandList->Close(); - -// 提交到命令队列执行 -commandQueue->ExecuteCommandLists(1, (void**)&commandList); -``` - -## 相关文档 - -- [RHICommandQueue](./rhi-command-queue.md) - 命令队列 -- [RHIPipelineState](./rhi-pipeline-state.md) - 管线状态 -- [RHIDevice](./rhi-device.md) - 创建设备 diff --git a/docs/api/rhi/rhi-command-queue.md b/docs/api/rhi/rhi-command-queue.md deleted file mode 100644 index 6aa3f488..00000000 --- a/docs/api/rhi/rhi-command-queue.md +++ /dev/null @@ -1,82 +0,0 @@ -# RHICommandQueue - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: GPU 命令队列抽象接口，负责提交和执行命令列表，以及 GPU/CPU 同步。 - -## 概述 - -`RHICommandQueue` 封装了 GPU 命令队列的操作，包括命令列表提交、同步栅栏操作、GPU 空闲等待等功能。 - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual void Shutdown()` | 关闭命令队列 | - -### 命令执行 - -| 方法 | 描述 | -|------|------| -| `virtual void ExecuteCommandLists(uint32_t count, void** lists)` | 执行命令列表 | -| `virtual void Signal(RHIFence* fence, uint64_t value)` | 信号通知栅栏 | -| `virtual void Wait(RHIFence* fence, uint64_t value)` | 等待栅栏 | -| `virtual uint64_t GetCompletedValue()` | 获取已完成的值 | -| `virtual void WaitForIdle()` | 等待队列空闲 | - -### 属性访问 - -| 方法 | 描述 | -|------|------| -| `virtual CommandQueueType GetType() const` | 获取队列类型 | -| `virtual uint64_t GetTimestampFrequency() const` | 获取时间戳频率 | - -### 其他 - -| 方法 | 描述 | -|------|------| -| `virtual void* GetNativeHandle()` | 获取原生 API 句柄 | - -## 命令队列类型 (CommandQueueType) - -| 枚举值 | 描述 | -|--------|------| -| `Direct` | 直接队列，用于图形和计算命令 | -| `Compute` | 计算队列，专门用于计算着色器 | -| `Copy` | 复制队列，专门用于资源复制 | - -## 使用示例 - -```cpp -// 创建命令队列 -CommandQueueDesc queueDesc; -queueDesc.queueType = (uint32_t)CommandQueueType::Direct; -RHICommandQueue* commandQueue = device->CreateCommandQueue(queueDesc); - -// 创建同步栅栏 -FenceDesc fenceDesc; -fenceDesc.initialValue = 0; -RHIFence* fence = device->CreateFence(fenceDesc); - -// 提交命令列表执行 -commandQueue->ExecuteCommandLists(1, (void**)&commandList); - -// 信号通知栅栏 -commandQueue->Signal(fence, 1); - -// CPU 等待 GPU 完成 -fence->Wait(1); - -// 或者让 CPU 等待队列空闲 -commandQueue->WaitForIdle(); -``` - -## 相关文档 - -- [RHICommandList](./rhi-command-list.md) - 命令列表 -- [RHIFence](./rhi-fence.md) - 同步栅栏 -- [RHIDevice](./rhi-device.md) - 创建设备 diff --git a/docs/api/rhi/rhi-descriptor-pool.md b/docs/api/rhi/rhi-descriptor-pool.md deleted file mode 100644 index ac0aa1f6..00000000 --- a/docs/api/rhi/rhi-descriptor-pool.md +++ /dev/null @@ -1,51 +0,0 @@ -# RHIDescriptorPool - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: GPU 描述符堆池抽象接口，用于管理 GPU 描述符的分配和回收。 - -## 概述 - -`RHIDescriptorPool` 封装了描述符堆（Descriptor Heap）的操作。描述符堆用于存储各种 GPU 描述符，如常量缓冲视图（CBV）、着色器资源视图（SRV）、无序访问视图（UAV）和采样器等。 - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual bool Initialize(const DescriptorPoolDesc& desc)` | 初始化描述符池 | -| `virtual void Shutdown()` | 释放描述符池资源 | - -### 属性访问 - -| 方法 | 描述 | -|------|------| -| `virtual void* GetNativeHandle()` | 获取原生 API 句柄 | -| `virtual uint32_t GetDescriptorCount() const` | 获取描述符数量 | -| `virtual DescriptorHeapType GetType() const` | 获取堆类型 | - -## 描述符池描述 (DescriptorPoolDesc) - -| 成员 | 类型 | 描述 | -|------|------|------| -| `device` | `void*` | 关联的设备指针 | -| `type` | `DescriptorHeapType` | 堆类型 | -| `descriptorCount` | `uint32_t` | 描述符数量 | -| `shaderVisible` | `bool` | 是否对着色器可见 | - -## 描述符堆类型 (DescriptorHeapType) - -| 枚举值 | 描述 | -|--------|------| -| `CBV_SRV_UAV` | 常量缓冲/着色器资源/无序访问视图 | -| `Sampler` | 采样器 | -| `RTV` | 渲染目标视图 | -| `DSV` | 深度模板视图 | - -## 相关文档 - -- [RHIDevice](./rhi-device.md) - 创建设备 -- [RHICapabilities](./rhi-capabilities.md) - 设备能力 diff --git a/docs/api/rhi/rhi-device.md b/docs/api/rhi/rhi-device.md deleted file mode 100644 index 82548d50..00000000 --- a/docs/api/rhi/rhi-device.md +++ /dev/null @@ -1,89 +0,0 @@ -# RHIDevice - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: RHI 渲染设备抽象接口，代表一个图形设备实例。 - -## 概述 - -`RHIDevice` 是 RHI 模块的核心接口之一，负责创建和管理所有 GPU 资源。每个 RHI 后端（D3D12、OpenGL 等）都需要实现此接口。 - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual bool Initialize(const RHIDeviceDesc& desc)` | 初始化设备 | -| `virtual void Shutdown()` | 关闭设备，释放所有资源 | - -### 资源创建 - -| 方法 | 描述 | -|------|------| -| `virtual RHIBuffer* CreateBuffer(const BufferDesc& desc)` | 创建 GPU 缓冲区 | -| `virtual RHITexture* CreateTexture(const TextureDesc& desc)` | 创建 GPU 纹理 | -| `virtual RHISwapChain* CreateSwapChain(const SwapChainDesc& desc)` | 创建交换链 | -| `virtual RHICommandList* CreateCommandList(const CommandListDesc& desc)` | 创建命令列表 | -| `virtual RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc)` | 创建命令队列 | -| `virtual RHIShader* CompileShader(const ShaderCompileDesc& desc)` | 编译着色器 | -| `virtual RHIPipelineState* CreatePipelineState(const PipelineStateDesc& desc)` | 创建管线状态对象 | -| `virtual RHIFence* CreateFence(const FenceDesc& desc)` | 创建同步栅栏 | -| `virtual RHISampler* CreateSampler(const SamplerDesc& desc)` | 创建采样器 | - -### 设备信息 - -| 方法 | 描述 | -|------|------| -| `virtual const RHICapabilities& GetCapabilities() const` | 获取设备能力 | -| `virtual const RHIDeviceInfo& GetDeviceInfo() const` | 获取设备信息 | -| `virtual void* GetNativeDevice() = 0` | 获取原生设备指针 | - -## 使用示例 - -```cpp -// 创建 D3D12 设备 -RHI::RHIDevice* device = RHI::RHIFactory::CreateRHIDevice(RHI::RHIType::D3D12); - -// 配置设备描述 -RHI::RHIDeviceDesc desc; -desc.windowHandle = hwnd; -desc.width = 1280; -desc.height = 720; -desc.appName = L"MyApp"; -desc.enableDebugLayer = true; - -// 初始化设备 -if (device->Initialize(desc)) { - // 获取设备能力 - const RHI::RHICapabilities& caps = device->GetCapabilities(); - if (caps.bSupportsRayTracing) { - // 设备支持光线追踪 - } - - // 获取设备信息 - const RHI::RHIDeviceInfo& info = device->GetDeviceInfo(); - printf("GPU: %ls\n", info.description.c_str()); - - // 创建资源 - RHI::BufferDesc bufferDesc; - bufferDesc.size = 1024; - bufferDesc.bufferType = (uint32_t)RHI::BufferType::Vertex; - RHI::RHIBuffer* buffer = device->CreateBuffer(bufferDesc); - - // ... 使用设备 ... - - // 关闭设备 - device->Shutdown(); -} - -delete device; -``` - -## 相关文档 - -- [RHIFactory](./rhi-factory.md) - 设备工厂 -- [RHICapabilities](./rhi-capabilities.md) - 设备能力 -- [RHITypes](./rhi-types.md) - 设备描述结构体 diff --git a/docs/api/rhi/rhi-enums.md b/docs/api/rhi/rhi-enums.md deleted file mode 100644 index e3a85486..00000000 --- a/docs/api/rhi/rhi-enums.md +++ /dev/null @@ -1,458 +0,0 @@ -# RHIEnums - -**命名空间**: `XCEngine::RHI` - -**类型**: `enums` - -**描述**: RHI 模块中使用的所有枚举类型汇总。 - -## 概述 - -本文档汇总了 RHI 模块中定义的所有枚举类型。这些枚举定义了图形 API 的各种选项和状态。 - ---- - -## ShaderType - -着色器类型枚举。 - -| 值 | 描述 | -|----|------| -| `ShaderType::Vertex` | 顶点着色器 | -| `ShaderType::Fragment` | 片元着色器 | -| `ShaderType::Geometry` | 几何着色器 | -| `ShaderType::Compute` | 计算着色器 | -| `ShaderType::TessControl` | 曲面细分控制 | -| `ShaderType::TessEvaluation` | 曲面细分评估 | -| `ShaderType::Hull` | Hull 着色器 (D3D) | -| `ShaderType::Domain` | Domain 着色器 (D3D) | -| `ShaderType::Amplification` | 放大着色器 (D3D12.9+) | -| `ShaderType::Mesh` | Mesh 着色器 (D3D12.9+) | -| `ShaderType::Library` | 着色器库 | - ---- - -## CullMode - -背面剔除模式枚举。 - -| 值 | 描述 | -|----|------| -| `CullMode::None` | 不剔除 | -| `CullMode::Front` | 剔除正面 | -| `CullMode::Back` | 剔除背面（默认） | - ---- - -## FillMode - -填充模式枚举。 - -| 值 | 描述 | -|----|------| -| `FillMode::Wireframe` | 线框模式 | -| `FillMode::Solid` | 实体模式（默认） | - ---- - -## BlendOp - -混合操作枚举。 - -| 值 | 描述 | -|----|------| -| `BlendOp::Add` | 加法 | -| `BlendOp::Subtract` | 减法 | -| `BlendOp::ReverseSubtract` | 反向减法 | -| `BlendOp::Min` | 最小值 | -| `BlendOp::Max` | 最大值 | - ---- - -## BlendFactor - -混合因子枚举。 - -| 值 | 描述 | -|----|------| -| `BlendFactor::Zero` | 0 | -| `BlendFactor::One` | 1 | -| `BlendFactor::SrcColor` | 源颜色 | -| `BlendFactor::InvSrcColor` | 1 - 源颜色 | -| `BlendFactor::SrcAlpha` | 源 Alpha | -| `BlendFactor::InvSrcAlpha` | 1 - 源 Alpha | -| `BlendFactor::DstAlpha` | 目标 Alpha | -| `BlendFactor::InvDstAlpha` | 1 - 目标 Alpha | -| `BlendFactor::DstColor` | 目标颜色 | -| `BlendFactor::InvDstColor` | 1 - 目标颜色 | -| `BlendFactor::SrcAlphaSat` | 饱和(源 Alpha, 1 - 目标 Alpha) | -| `BlendFactor::BlendFactor` | 混合因子 | -| `BlendFactor::InvBlendFactor` | 1 - 混合因子 | -| `BlendFactor::Src1Color` | 第二个源颜色 | -| `BlendFactor::InvSrc1Color` | 1 - 第二个源颜色 | -| `BlendFactor::Src1Alpha` | 第二个源 Alpha | -| `BlendFactor::InvSrc1Alpha` | 1 - 第二个源 Alpha | - ---- - -## ComparisonFunc - -比较函数枚举。 - -| 值 | 描述 | -|----|------| -| `ComparisonFunc::Never` | 从不通过 | -| `ComparisonFunc::Less` | 小于通过 | -| `ComparisonFunc::Equal` | 等于通过 | -| `ComparisonFunc::LessEqual` | 小于等于通过 | -| `ComparisonFunc::Greater` | 大于通过 | -| `ComparisonFunc::NotEqual` | 不等于通过 | -| `ComparisonFunc::GreaterEqual` | 大于等于通过 | -| `ComparisonFunc::Always` | 总是通过 | - ---- - -## StencilOp - -模板操作枚举。 - -| 值 | 描述 | -|----|------| -| `StencilOp::Keep` | 保持当前值 | -| `StencilOp::Zero` | 设置为 0 | -| `StencilOp::Replace` | 替换为参考值 | -| `StencilOp::IncrSat` | 增加并饱和 | -| `StencilOp::DecrSat` | 减少并饱和 | -| `StencilOp::Invert` | 位反转 | -| `StencilOp::Incr` | 增加并回绕 | -| `StencilOp::Decr` | 减少并回绕 | - ---- - -## TextureType - -纹理类型枚举。 - -| 值 | 描述 | -|----|------| -| `TextureType::Texture1D` | 1D 纹理 | -| `TextureType::Texture2D` | 2D 纹理 | -| `TextureType::Texture2DArray` | 2D 纹理数组 | -| `TextureType::Texture3D` | 3D 纹理 | -| `TextureType::TextureCube` | 立方体贴图 | -| `TextureType::TextureCubeArray` | 立方体贴图数组 | - ---- - -## BufferType - -缓冲区类型枚举。 - -| 值 | 描述 | -|----|------| -| `BufferType::Vertex` | 顶点缓冲 | -| `BufferType::Index` | 索引缓冲 | -| `BufferType::Constant` | 常量缓冲 | -| `BufferType::ReadBack` | 回读缓冲 | -| `BufferType::Indirect` | 间接缓冲 | -| `BufferType::RaytracingAccelerationStructure` | 光追加速结构 | -| `BufferType::ShaderBindingTable` | 着色器绑定表 | - ---- - -## DescriptorType - -描述符类型枚举。 - -| 值 | 描述 | -|----|------| -| `DescriptorType::CBV` | 常量缓冲视图 | -| `DescriptorType::SRV` | 着色器资源视图 | -| `DescriptorType::UAV` | 无序访问视图 | -| `DescriptorType::Sampler` | 采样器 | -| `DescriptorType::RTV` | 渲染目标视图 | -| `DescriptorType::DSV` | 深度模板视图 | - ---- - -## PipelineType - -管线类型枚举。 - -| 值 | 描述 | -|----|------| -| `PipelineType::Graphics` | 图形管线 | -| `PipelineType::Compute` | 计算管线 | -| `PipelineType::Raytracing` | 光线追踪管线 | - ---- - -## CommandQueueType - -命令队列类型枚举。 - -| 值 | 描述 | -|----|------| -| `CommandQueueType::Direct` | 直接队列 | -| `CommandQueueType::Compute` | 计算队列 | -| `CommandQueueType::Copy` | 复制队列 | - ---- - -## LoadAction - -加载操作枚举。 - -| 值 | 描述 | -|----|------| -| `LoadAction::Undefined` | 未定义 | -| `LoadAction::Load` | 加载现有内容 | -| `LoadAction::Clear` | 清除为默认值 | - ---- - -## StoreAction - -存储操作枚举。 - -| 值 | 描述 | -|----|------| -| `StoreAction::Undefined` | 未定义 | -| `StoreAction::Store` | 存储 | -| `StoreAction::Resolve` | 解析 | -| `StoreAction::StoreAndResolve` | 存储并解析 | -| `StoreAction::Discard` | 丢弃 | - ---- - -## PresentFlags - -呈现标志枚举。 - -| 值 | 描述 | -|----|------| -| `PresentFlags::None` | 无特殊标志 | -| `PresentFlags::AllowTearing` | 允许垂直同步撕裂 | -| `PresentFlags::StrictlyTimedFrame` | 严格帧时序 | -| `PresentFlags::AllowDisplayLatencyWaitableObject` | 显示延迟等待对象 | - ---- - -## FilterMode - -采样器过滤模式枚举。 - -| 值 | 描述 | -|----|------| -| `FilterMode::Point` | 点采样 | -| `FilterMode::Linear` | 双线性插值 | -| `FilterMode::Anisotropic` | 各向异性过滤 | -| `FilterMode::ComparisonPoint` | 比较点采样 | -| `FilterMode::ComparisonLinear` | 比较双线性 | -| `FilterMode::ComparisonAnisotropic` | 比较各向异性 | -| `FilterMode::MinimumPoint` | 最小值点采样 | -| `FilterMode::MinimumLinear` | 最小值线性 | -| `FilterMode::MinimumAnisotropic` | 最小值各向异性 | -| `FilterMode::MaximumPoint` | 最大值点采样 | -| `FilterMode::MaximumLinear` | 最大值线性 | -| `FilterMode::MaximumAnisotropic` | 最大值各向异性 | - ---- - -## TextureAddressMode - -纹理寻址模式枚举。 - -| 值 | 描述 | -|----|------| -| `TextureAddressMode::Wrap` | 重复寻址 | -| `TextureAddressMode::Mirror` | 镜像寻址 | -| `TextureAddressMode::Clamp` | 钳制寻址 | -| `TextureAddressMode::Border` | 边框颜色 | -| `TextureAddressMode::MirrorOnce` | 单次镜像 | - ---- - -## BorderColor - -边框颜色枚举。 - -| 值 | 描述 | -|----|------| -| `BorderColor::TransparentBlack` | 透明黑色 (0,0,0,0) | -| `BorderColor::OpaqueBlack` | 不透明黑色 (0,0,0,1) | -| `BorderColor::OpaqueWhite` | 不透明白色 (1,1,1,1) | - ---- - -## LogicOp - -逻辑操作枚举。 - -| 值 | 描述 | -|----|------| -| `LogicOp::Clear` | 清零 | -| `LogicOp::Set` | 置一 | -| `LogicOp::Copy` | 复制 | -| `LogicOp::CopyInverted` | 复制取反 | -| `LogicOp::Noop` | 无操作 | -| `LogicOp::Invert` | 取反 | -| `LogicOp::And` | 与 | -| `LogicOp::Nand` | 与非 | -| `LogicOp::Or` | 或 | -| `LogicOp::Nor` | 或非 | -| `LogicOp::Xor` | 异或 | -| `LogicOp::Equiv` | 同或 | -| `LogicOp::AndReverse` | 反向与 | -| `LogicOp::AndInverted` | 与反 | -| `LogicOp::OrReverse` | 反向或 | -| `LogicOp::OrInverted` | 或反 | - ---- - -## ColorWriteMask - -颜色写入掩码枚举，支持位运算组合。 - -| 值 | 描述 | -|----|------| -| `ColorWriteMask::Red` | 红色通道 (1) | -| `ColorWriteMask::Green` | 绿色通道 (2) | -| `ColorWriteMask::Blue` | 蓝色通道 (4) | -| `ColorWriteMask::Alpha` | Alpha 通道 (8) | -| `ColorWriteMask::All` | 所有通道 (15) | - -支持 `operator|` 进行组合，如 `ColorWriteMask::Red | ColorWriteMask::Green`。 - ---- - -## ShaderVisibility - -着色器可见性枚举。 - -| 值 | 描述 | -|----|------| -| `ShaderVisibility::All` | 所有着色器阶段 | -| `ShaderVisibility::Vertex` | 顶点着色器 | -| `ShaderVisibility::Hull` | Hull 着色器 | -| `ShaderVisibility::Domain` | Domain 着色器 | -| `ShaderVisibility::Geometry` | 几何着色器 | -| `ShaderVisibility::Pixel` | 像素着色器 | -| `ShaderVisibility::Amplification` | 放大着色器 | -| `ShaderVisibility::Mesh` | Mesh 着色器 | - ---- - -## RootParameterType - -根参数类型枚举。 - -| 值 | 描述 | -|----|------| -| `RootParameterType::DescriptorTable` | 描述符表 | -| `RootParameterType::Constants` | 内联常量 | -| `RootParameterType::CBV` | 常量缓冲视图 | -| `RootParameterType::SRV` | 着色器资源视图 | -| `RootParameterType::UAV` | 无序访问视图 | - ---- - -## DescriptorHeapType - -描述符堆类型枚举。 - -| 值 | 描述 | -|----|------| -| `DescriptorHeapType::CBV_SRV_UAV` | 常量缓冲/着色器资源/无序访问视图 | -| `DescriptorHeapType::Sampler` | 采样器 | -| `DescriptorHeapType::RTV` | 渲染目标视图 | -| `DescriptorHeapType::DSV` | 深度模板视图 | - ---- - -## QueryType - -查询类型枚举。 - -| 值 | 描述 | -|----|------| -| `QueryType::Occlusion` | 遮挡查询 | -| `QueryType::Timestamp` | 时间戳查询 | -| `QueryType::PipelineStatistics` | 管线统计查询 | - ---- - -## Format - -纹理/缓冲区格式枚举。 - -| 值 | 描述 | -|----|------| -| `Format::Unknown` | 未知 | -| `Format::R8_UNorm` | 单通道 8 位归一化 | -| `Format::R8G8_UNorm` | 双通道 8 位归一化 | -| `Format::R8G8B8A8_UNorm` | 四通道 8 位归一化 | -| `Format::R16G16B16A16_Float` | 四通道 16 位浮点 | -| `Format::R32G32B32A32_Float` | 四通道 32 位浮点 | -| `Format::R16_Float` | 单通道 16 位浮点 | -| `Format::R32_Float` | 单通道 32 位浮点 | -| `Format::D16_UNorm` | 16 位深度 | -| `Format::D24_UNorm_S8_UInt` | 24 位深度 + 8 位模板 | -| `Format::D32_Float` | 32 位深度 | -| `Format::BC1_UNorm` | BC1 压缩 (DXT1) | -| `Format::BC2_UNorm` | BC2 压缩 (DXT3) | -| `Format::BC3_UNorm` | BC3 压缩 (DXT5) | -| `Format::BC4_UNorm` | BC4 压缩 (ATI1N) | -| `Format::BC5_UNorm` | BC5 压缩 (ATI2N) | -| `Format::BC6H_UF16` | BC6H 有符号浮点压缩 | -| `Format::BC7_UNorm` | BC7 高质量压缩 | -| `Format::R32_UInt` | 单通道 32 位无符号整数 | -| `Format::R32G32B32A32_UInt` | 四通道 32 位无符号整数 | - ---- - -## ResourceStates - -资源状态枚举。 - -| 值 | 描述 | -|----|------| -| `ResourceStates::Common` | 通用状态 | -| `ResourceStates::VertexAndConstantBuffer` | 顶点/常量缓冲 | -| `ResourceStates::IndexBuffer` | 索引缓冲 | -| `ResourceStates::RenderTarget` | 渲染目标 | -| `ResourceStates::UnorderedAccess` | 无序访问 | -| `ResourceStates::DepthWrite` | 深度写入 | -| `ResourceStates::DepthRead` | 深度读取 | -| `ResourceStates::NonPixelShaderResource` | 非像素着色器资源 | -| `ResourceStates::PixelShaderResource` | 像素着色器资源 | -| `ResourceStates::CopySrc` | 复制源 | -| `ResourceStates::CopyDst` | 复制目标 | -| `ResourceStates::Present` | 呈现 | -| `ResourceStates::GenericRead` | 通用读取 | - ---- - -## HeapType - -内存堆类型枚举。 - -| 值 | 描述 | -|----|------| -| `HeapType::Default` | 默认堆（GPU 直接访问） | -| `HeapType::Upload` | 上传堆（CPU 可写，GPU 可读） | -| `HeapType::Readback` | 回读堆（CPU 可读） | -| `HeapType::Custom` | 自定义堆 | - ---- - -## RHIType - -RHI 后端类型枚举。 - -| 值 | 描述 | -|----|------| -| `RHIType::D3D12` | DirectX 12 | -| `RHIType::OpenGL` | OpenGL | -| `RHIType::Vulkan` | Vulkan（预留） | -| `RHIType::Metal` | Metal（预留） | diff --git a/docs/api/rhi/rhi-fence.md b/docs/api/rhi/rhi-fence.md deleted file mode 100644 index 7a982a6d..00000000 --- a/docs/api/rhi/rhi-fence.md +++ /dev/null @@ -1,68 +0,0 @@ -# RHIFence - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: GPU 同步栅栏抽象接口，用于 GPU/CPU 同步和跨队列同步。 - -## 概述 - -`RHIFence` 封装了 GPU 栅栏操作，提供了一种可靠的方式来同步 CPU 和 GPU 之间的执行，以及不同命令队列之间的同步。 - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual void Shutdown()` | 释放栅栏资源 | - -### 同步操作 - -| 方法 | 描述 | -|------|------| -| `virtual void Signal()` | 信号通知（值为 1） | -| `virtual void Signal(uint64_t value)` | 信号通知（指定值） | -| `virtual void Wait(uint64_t value)` | 等待指定值 | -| `virtual uint64_t GetCompletedValue() const` | 获取已完成的值 | -| `virtual bool IsSignaled() const` | 检查是否已信号通知 | - -### 其他 - -| 方法 | 描述 | -|------|------| -| `virtual void* GetNativeHandle()` | 获取原生 API 句柄 | - -## 使用示例 - -```cpp -// 创建栅栏 -FenceDesc desc; -desc.initialValue = 0; -RHIFence* fence = device->CreateFence(desc); - -// CPU 等待 GPU 完成工作 -commandQueue->Signal(fence, 1); -fence->Wait(1); - -// 或者使用 GetCompletedValue 轮询 -commandQueue->Signal(fence, 100); -while (fence->GetCompletedValue() < 100) { - // CPU 可以做其他工作 - DoOtherWork(); -} - -// 检查栅栏状态 -if (fence->IsSignaled()) { - // GPU 工作已完成 -} - -// 重置和复用 -fence->Signal(0); -``` - -## 相关文档 - -- [RHICommandQueue](./rhi-command-queue.md) - 命令队列 -- [RHIDevice](./rhi-device.md) - 创建设备 diff --git a/docs/api/rhi/rhi-overview.md b/docs/api/rhi/rhi-overview.md deleted file mode 100644 index 6ebf566b..00000000 --- a/docs/api/rhi/rhi-overview.md +++ /dev/null @@ -1,122 +0,0 @@ -# RHI (Render Hardware Interface) - -**命名空间**: `XCEngine::RHI` - -**类型**: `module` - -**描述**: RHI 抽象层是 XCEngine 的核心渲染硬件接口模块，提供了对底层图形 API（D3D12、OpenGL 等）的统一抽象。 - -## 概述 - -RHI（Render Hardware Interface）模块是 XCEngine 图形引擎的核心抽象层。它通过定义一组统一的接口和类型，封装了不同图形 API 的差异，使上层代码可以在不关心具体实现的情况下进行渲染。 - -### 架构设计 - -``` -┌─────────────────────────────────────────────┐ -│ 上层渲染代码 │ -│ (Renderer, Scene, Materials, etc.) │ -└─────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────┐ -│ RHI 抽象接口层 │ -│ RHIDevice, RHICommandList, RHIBuffer, ... │ -└─────────────────────────────────────────────┘ - │ - ┌───────────┴───────────┐ - ▼ ▼ -┌─────────────────────┐ ┌─────────────────────┐ -│ D3D12 后端 │ │ OpenGL 后端 │ -│ D3D12Device, ... │ │ OpenGLDevice, ... │ -└─────────────────────┘ └─────────────────────┘ -``` - -### 核心组件 - -| 组件 | 描述 | -|------|------| -| `RHIDevice` | 渲染设备抽象，代表一个图形设备实例 | -| `RHIFactory` | RHI 设备工厂，用于创建不同后端的设备 | -| `RHIBuffer` | GPU 缓冲区资源抽象（顶点缓冲、索引缓冲、常量缓冲等） | -| `RHITexture` | GPU 纹理资源抽象 | -| `RHICommandList` | GPU 命令列表抽象 | -| `RHICommandQueue` | GPU 命令队列抽象 | -| `RHISwapChain` | 交换链抽象，用于窗口渲染 | -| `RHIFence` | GPU 同步栅栏抽象 | -| `RHIShader` | 着色器资源抽象 | -| `RHIPipelineState` | 渲染管线状态抽象 | -| `RHISampler` | 纹理采样器抽象 | - -### 设备创建流程 - -```cpp -// 1. 使用工厂创建设备 -RHIDevice* device = RHIFactory::CreateRHIDevice(RHIType::D3D12); - -// 2. 初始化设备 -RHIDeviceDesc desc; -desc.windowHandle = hwnd; -desc.width = 1280; -desc.height = 720; -desc.appName = L"MyApp"; -device->Initialize(desc); - -// 3. 获取设备能力 -const RHICapabilities& caps = device->GetCapabilities(); - -// 4. 创建资源 -RHIBuffer* vertexBuffer = device->CreateBuffer(bufferDesc); -RHITexture* texture = device->CreateTexture(textureDesc); - -// 5. 使用完毕后关闭设备 -device->Shutdown(); -delete device; -``` - -### 支持的后端 - -| 后端 | 枚举值 | 状态 | -|------|--------|------| -| DirectX 12 | `RHIType::D3D12` | ✅ 已实现 | -| OpenGL | `RHIType::OpenGL` | ✅ 已实现 | -| Vulkan | `RHIType::Vulkan` | 🔜 预留 | -| Metal | `RHIType::Metal` | 🔜 预留 | - -## 模块内容 - -### 核心接口 - -- [RHIDevice](./rhi-device.md) - 渲染设备 -- [RHIFactory](./rhi-factory.md) - 设备工厂 - -### 资源类型 - -- [RHIBuffer](./rhi-buffer.md) - GPU 缓冲区 -- [RHITexture](./rhi-texture.md) - GPU 纹理 - -### 命令执行 - -- [RHICommandList](./rhi-command-list.md) - 命令列表 -- [RHICommandQueue](./rhi-command-queue.md) - 命令队列 -- [RHISwapChain](./rhi-swap-chain.md) - 交换链 -- [RHIFence](./rhi-fence.md) - 同步栅栏 - -### 渲染状态 - -- [RHIShader](./rhi-shader.md) - 着色器 -- [RHIPipelineState](./rhi-pipeline-state.md) - 管线状态 -- [RHISampler](./rhi-sampler.md) - 采样器 -- [RHIDescriptorPool](./rhi-descriptor-pool.md) - 描述符池 -- [RHIPipelineLayout](./rhi-pipeline-layout.md) - 管线布局 -- [RHICapabilities](./rhi-capabilities.md) - 设备能力 - -### 类型定义 - -- [RHIEnums](./rhi-enums.md) - 枚举类型汇总 -- [RHITypes](./rhi-types.md) - 结构体类型汇总 - -## 相关文档 - -- [D3D12 后端](./d3d12/d3d12-overview.md) -- [OpenGL 后端](./opengl/opengl-overview.md) diff --git a/docs/api/rhi/rhi-pipeline-layout.md b/docs/api/rhi/rhi-pipeline-layout.md deleted file mode 100644 index 14fcd8c1..00000000 --- a/docs/api/rhi/rhi-pipeline-layout.md +++ /dev/null @@ -1,40 +0,0 @@ -# RHIPipelineLayout - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: GPU 渲染管线布局抽象接口，用于定义着色器资源的绑定布局。 - -## 概述 - -`RHIPipelineLayout` 封装了管线布局（Root Signature）的创建和管理。管线布局定义了着色器程序期望的资源布局，包括常量缓冲、纹理和采样器的绑定位置。 - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual bool Initialize(const RHIPipelineLayoutDesc& desc)` | 初始化管线布局 | -| `virtual void Shutdown()` | 释放管线布局资源 | - -### 其他 - -| 方法 | 描述 | -|------|------| -| `virtual void* GetNativeHandle()` | 获取原生 API 句柄 | - -## 管线布局描述 (RHIPipelineLayoutDesc) - -| 成员 | 类型 | 描述 | -|------|------|------| -| `constantBufferCount` | `uint32_t` | 常量缓冲数量 | -| `textureCount` | `uint32_t` | 纹理数量 | -| `samplerCount` | `uint32_t` | 采样器数量 | -| `uavCount` | `uint32_t` | UAV 数量 | - -## 相关文档 - -- [RHIDevice](./rhi-device.md) - 创建设备 -- [RHIPipelineState](./rhi-pipeline-state.md) - 管线状态 diff --git a/docs/api/rhi/rhi-pipeline-state.md b/docs/api/rhi/rhi-pipeline-state.md deleted file mode 100644 index 9bc4f74d..00000000 --- a/docs/api/rhi/rhi-pipeline-state.md +++ /dev/null @@ -1,47 +0,0 @@ -# RHIPipelineState - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: GPU 渲染管线状态抽象接口，封装了渲染管线的各种固定功能配置。 - -## 概述 - -`RHIPipelineState` 封装了渲染管线状态的创建和管理。管线状态对象（PIPSO）存储了 GPU 管线的不可变配置，包括着色器、混合状态、深度模板状态、光栅化状态等。 - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual void Shutdown()` | 释放管线状态对象 | - -### 绑定/解绑 - -| 方法 | 描述 | -|------|------| -| `virtual void Bind()` | 绑定管线状态到管线 | -| `virtual void Unbind()` | 解绑管线状态 | - -### 属性访问 - -| 方法 | 描述 | -|------|------| -| `virtual void* GetNativeHandle()` | 获取原生 API 句柄 | -| `virtual PipelineType GetType() const` | 获取管线类型 | - -## 管线类型 (PipelineType) - -| 枚举值 | 描述 | -|--------|------| -| `Graphics` | 图形渲染管线 | -| `Compute` | 计算管线 | -| `Raytracing` | 光线追踪管线 | - -## 相关文档 - -- [RHIDevice](./rhi-device.md) - 创建设备 -- [RHIShader](./rhi-shader.md) - 着色器 -- [RHICommandList](./rhi-command-list.md) - 命令列表 diff --git a/docs/api/rhi/rhi-sampler.md b/docs/api/rhi/rhi-sampler.md deleted file mode 100644 index 76f9dcdc..00000000 --- a/docs/api/rhi/rhi-sampler.md +++ /dev/null @@ -1,101 +0,0 @@ -# RHISampler - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: GPU 纹理采样器抽象接口，用于配置纹理过滤和寻址模式。 - -## 概述 - -`RHISampler` 封装了纹理采样器的配置，包括过滤模式、寻址模式、各向异性、mipmap 等设置。 - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual void Shutdown()` | 释放采样器资源 | - -### 绑定/解绑 - -| 方法 | 描述 | -|------|------| -| `virtual void Bind(unsigned int unit)` | 绑定采样器到纹理单元 | -| `virtual void Unbind(unsigned int unit)` | 解绑采样器 | - -### 属性访问 - -| 方法 | 描述 | -|------|------| -| `virtual void* GetNativeHandle()` | 获取原生 API 句柄 | -| `virtual unsigned int GetID()` | 获取采样器 ID | - -## 采样器描述 (SamplerDesc) - -| 成员 | 类型 | 描述 | -|------|------|------| -| `filter` | `uint32_t` | 过滤模式 | -| `addressU` | `uint32_t` | U 轴寻址模式 | -| `addressV` | `uint32_t` | V 轴寻址模式 | -| `addressW` | `uint32_t` | W 轴寻址模式 | -| `mipLodBias` | `float` | Mipmap 级别偏移 | -| `maxAnisotropy` | `uint32_t` | 最大各向异性级别 | -| `comparisonFunc` | `uint32_t` | 比较函数 | -| `borderColorR` | `float` | 边框颜色 R | -| `borderColorG` | `float` | 边框颜色 G | -| `borderColorB` | `float` | 边框颜色 B | -| `borderColorA` | `float` | 边框颜色 A | -| `minLod` | `float` | 最小 Mipmap 级别 | -| `maxLod` | `float` | 最大 Mipmap 级别 | - -## 过滤模式 (FilterMode) - -| 枚举值 | 描述 | -|--------|------| -| `Point` | 点采样 | -| `Linear` | 双线性插值 | -| `Anisotropic` | 各向异性过滤 | -| `ComparisonPoint` | 带比较的点采样 | -| `ComparisonLinear` | 带比较的双线性插值 | -| `ComparisonAnisotropic` | 带比较的各向异性 | - -## 寻址模式 (TextureAddressMode) - -| 枚举值 | 描述 | -|--------|------| -| `Wrap` | 重复寻址 | -| `Mirror` | 镜像寻址 | -| `Clamp` | 钳制寻址 | -| `Border` | 边框颜色寻址 | -| `MirrorOnce` | 单次镜像 | - -## 使用示例 - -```cpp -// 创建采样器 -SamplerDesc samplerDesc; -samplerDesc.filter = (uint32_t)FilterMode::Anisotropic; -samplerDesc.addressU = (uint32_t)TextureAddressMode::Wrap; -samplerDesc.addressV = (uint32_t)TextureAddressMode::Wrap; -samplerDesc.addressW = (uint32_t)TextureAddressMode::Wrap; -samplerDesc.maxAnisotropy = 16; -samplerDesc.minLod = 0; -samplerDesc.maxLod = FLT_MAX; -samplerDesc.mipLodBias = 0; -samplerDesc.comparisonFunc = (uint32_t)ComparisonFunc::Never; - -RHISampler* sampler = device->CreateSampler(samplerDesc); - -// 绑定到纹理单元 0 -sampler->Bind(0); - -// 解绑 -sampler->Unbind(0); -``` - -## 相关文档 - -- [RHITexture](./rhi-texture.md) - 纹理资源 -- [RHIDevice](./rhi-device.md) - 创建设备 diff --git a/docs/api/rhi/rhi-shader.md b/docs/api/rhi/rhi-shader.md deleted file mode 100644 index fe49823e..00000000 --- a/docs/api/rhi/rhi-shader.md +++ /dev/null @@ -1,115 +0,0 @@ -# RHIShader - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: GPU 着色器资源抽象接口，用于管理着色器代码的编译和绑定。 - -## 概述 - -`RHIShader` 封装了着色器的编译、参数设置和绑定操作。着色器是 GPU 可编程管线的核心组件。 - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual void Shutdown()` | 释放着色器资源 | - -### 编译 - -| 方法 | 描述 | -|------|------| -| `virtual bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target)` | 从文件编译着色器 | -| `virtual bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target)` | 从内存编译着色器 | - -### 属性访问 - -| 方法 | 描述 | -|------|------| -| `virtual ShaderType GetType() const` | 获取着色器类型 | -| `virtual bool IsValid() const` | 检查着色器是否有效 | - -### 绑定/解绑 - -| 方法 | 描述 | -|------|------| -| `virtual void Bind()` | 绑定着色器到管线 | -| `virtual void Unbind()` | 解绑着色器 | - -### Uniform 设置 - -| 方法 | 描述 | -|------|------| -| `virtual void SetInt(const char* name, int value)` | 设置整数 uniform | -| `virtual void SetFloat(const char* name, float value)` | 设置浮点 uniform | -| `virtual void SetVec3(const char* name, float x, float y, float z)` | 设置三维向量 uniform | -| `virtual void SetVec4(const char* name, float x, float y, float z, float w)` | 设置四维向量 uniform | -| `virtual void SetMat4(const char* name, const float* value)` | 设置 4x4 矩阵 uniform | - -### 其他 - -| 方法 | 描述 | -|------|------| -| `virtual void* GetNativeHandle()` | 获取原生 API 句柄 | - -## 着色器类型 (ShaderType) - -| 枚举值 | 描述 | -|--------|------| -| `Vertex` | 顶点着色器 | -| `Fragment` | 片元着色器 | -| `Geometry` | 几何着色器 | -| `Compute` | 计算着色器 | -| `TessControl` | 曲面细分控制着色器 | -| `TessEvaluation` | 曲面细分评估着色器 | -| `Hull` | Hull 着色器 (D3D) | -| `Domain` | Domain 着色器 (D3D) | -| `Amplification` | 放大着色器 (D3D12.9+) | -| `Mesh` | Mesh 着色器 (D3D12.9+) | -| `Library` | 着色器库 | - -## 编译目标格式 - -| API | 目标格式 | -|-----|----------| -| D3D11 | `vs_5_0`, `ps_5_0`, `gs_5_0`, `cs_5_0` | -| D3D12 | `vs_6_0`, `ps_6_0`, `gs_6_0`, `cs_6_0`, `ds_6_0`, `hs_6_0` | -| OpenGL | `GLSL` (GLSL 源码) | - -## 使用示例 - -```cpp -// 编译顶点着色器 -RHIShader* vs = device->CompileShader({}); -vs->CompileFromFile(L"shaders/vertex.hlsl", "main", "vs_6_0"); - -// 编译片元着色器 -RHIShader* ps = device->CompileShader({}); -ps->CompileFromFile(L"shaders/fragment.hlsl", "main", "ps_6_0"); - -// 设置 uniform -vs->SetMat4("modelMatrix", modelMatrix); -vs->SetMat4("viewMatrix", viewMatrix); -vs->SetMat4("projectionMatrix", projectionMatrix); - -ps->SetVec3("lightDir", 0.5f, 0.8f, 0.3f); -ps->SetFloat("roughness", 0.5f); -ps->SetInt("albedoMap", 0); - -// 绑定着色器 -vs->Bind(); -ps->Bind(); - -// 使用完毕后关闭 -vs->Shutdown(); -ps->Shutdown(); -``` - -## 相关文档 - -- [RHIDevice](./rhi-device.md) - 创建设备 -- [RHIPipelineState](./rhi-pipeline-state.md) - 管线状态 -- [RHICommandList](./rhi-command-list.md) - 命令列表 diff --git a/docs/api/rhi/rhi-swap-chain.md b/docs/api/rhi/rhi-swap-chain.md deleted file mode 100644 index 7b6f7318..00000000 --- a/docs/api/rhi/rhi-swap-chain.md +++ /dev/null @@ -1,94 +0,0 @@ -# RHISwapChain - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: GPU 交换链抽象接口，用于管理窗口渲染和帧缓冲区切换。 - -## 概述 - -`RHISwapChain` 封装了帧缓冲区交换链的操作，包括获取当前后台缓冲、呈现渲染结果、窗口调整等功能。 - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual void Shutdown()` | 关闭交换链 | - -### 交换链操作 - -| 方法 | 描述 | -|------|------| -| `virtual uint32_t GetCurrentBackBufferIndex() const` | 获取当前后台缓冲索引 | -| `virtual RHITexture* GetCurrentBackBuffer()` | 获取当前后台缓冲纹理 | -| `virtual void Present(uint32_t syncInterval = 1, uint32_t flags = 0)` | 呈现渲染结果 | -| `virtual void Resize(uint32_t width, uint32_t height)` | 调整交换链大小 | - -### 全屏模式 - -| 方法 | 描述 | -|------|------| -| `virtual void SetFullscreen(bool fullscreen)` | 设置全屏模式 | -| `virtual bool IsFullscreen() const` | 检查是否全屏 | - -### 窗口事件 - -| 方法 | 描述 | -|------|------| -| `virtual bool ShouldClose() const` | 检查是否应该关闭 | -| `virtual void SetShouldClose(bool shouldClose)` | 设置关闭标志 | -| `virtual void PollEvents()` | 处理窗口事件 | - -### 其他 - -| 方法 | 描述 | -|------|------| -| `virtual void* GetNativeHandle()` | 获取原生 API 句柄 | - -## 相关文档 - -```cpp -// 创建交换链 -SwapChainDesc swapChainDesc; -swapChainDesc.width = 1280; -swapChainDesc.height = 720; -swapChainDesc.bufferCount = 2; -swapChainDesc.format = (uint32_t)Format::R8G8B8A8_UNorm; -swapChainDesc.refreshRate = 60; -swapChainDesc.sampleCount = 1; -swapChainDesc.sampleQuality = 0; -swapChainDesc.swapEffect = 0; -swapChainDesc.flags = 0; - -RHISwapChain* swapChain = device->CreateSwapChain(swapChainDesc); - -// 渲染循环 -while (!swapChain->ShouldClose()) { - swapChain->PollEvents(); - - // 获取当前后台缓冲 - RHITexture* backBuffer = swapChain->GetCurrentBackBuffer(); - - // 录制渲染命令 - commandList->Reset(); - commandList->SetRenderTargets(1, &backBuffer, nullptr); - commandList->ClearRenderTarget(backBuffer, clearColor); - // ... 更多渲染命令 ... - commandList->Close(); - - // 执行并呈现 - commandQueue->ExecuteCommandLists(1, (void**)&commandList); - swapChain->Present(1, 0); -} - -swapChain->Shutdown(); -``` - -## 相关文档 - -- [RHITexture](./rhi-texture.md) - 纹理资源 -- [RHICommandQueue](./rhi-command-queue.md) - 命令队列 -- [RHIDevice](./rhi-device.md) - 创建设备 diff --git a/docs/api/rhi/rhi-texture.md b/docs/api/rhi/rhi-texture.md deleted file mode 100644 index 4f8ca8a9..00000000 --- a/docs/api/rhi/rhi-texture.md +++ /dev/null @@ -1,102 +0,0 @@ -# RHITexture - -**命名空间**: `XCEngine::RHI` - -**类型**: `class` (abstract) - -**描述**: GPU 纹理资源抽象接口，用于管理 1D、2D、3D 纹理和立方体贴图等 GPU 资源。 - -## 概述 - -`RHITexture` 封装了 GPU 纹理的创建、状态管理和属性访问。纹理是 GPU 渲染中最常用的资源类型之一。 - -## 公共方法 - -### 生命周期 - -| 方法 | 描述 | -|------|------| -| `virtual void Shutdown()` | 释放纹理资源 | - -### 属性访问 - -| 方法 | 描述 | -|------|------| -| `virtual uint32_t GetWidth() const` | 获取纹理宽度（像素） | -| `virtual uint32_t GetHeight() const` | 获取纹理高度（像素） | -| `virtual uint32_t GetDepth() const` | 获取纹理深度（3D 纹理） | -| `virtual uint32_t GetMipLevels() const` | 获取 Mipmap 级别数 | -| `virtual Format GetFormat() const` | 获取纹理格式 | -| `virtual TextureType GetTextureType() const` | 获取纹理类型 | - -### 状态管理 - -| 方法 | 描述 | -|------|------| -| `virtual ResourceStates GetState() const` | 获取当前资源状态 | -| `virtual void SetState(ResourceStates state)` | 设置资源状态 | - -### 其他 - -| 方法 | 描述 | -|------|------| -| `virtual void* GetNativeHandle()` | 获取原生 API 句柄 | -| `virtual const std::string& GetName() const` | 获取纹理名称 | -| `virtual void SetName(const std::string& name)` | 设置纹理名称（用于调试） | - -## 纹理类型 (TextureType) - -| 枚举值 | 描述 | -|--------|------| -| `TextureType::Texture1D` | 1D 纹理 | -| `TextureType::Texture2D` | 2D 纹理 | -| `TextureType::Texture2DArray` | 2D 纹理数组 | -| `TextureType::Texture3D` | 3D 纹理（体积纹理） | -| `TextureType::TextureCube` | 立方体贴图 | -| `TextureType::TextureCubeArray` | 立方体贴图数组 | - -## 纹理格式 (Format) - -| 格式 | 描述 | -|------|------| -| `Format::Unknown` | 未知格式 | -| `Format::R8_UNorm` | 单通道 8 位归一化 | -| `Format::R8G8_UNorm` | 双通道 8 位归一化 | -| `Format::R8G8B8A8_UNorm` | 四通道 8 位归一化 | -| `Format::R16G16B16A16_Float` | 四通道 16 位浮点 | -| `Format::R32G32B32A32_Float` | 四通道 32 位浮点 | -| `Format::D32_Float` | 32 位深度 | -| `Format::D24_UNorm_S8_UInt` | 24 位深度 + 8 位模板 | -| `Format::BC1_UNorm` | 压缩格式 (DXT1) | -| `Format::BC7_UNorm` | 压缩格式 | - -## 使用示例 - -```cpp -// 创建 2D 纹理 -TextureDesc desc; -desc.width = 1024; -desc.height = 1024; -desc.depth = 1; -desc.mipLevels = 1; -desc.arraySize = 1; -desc.format = (uint32_t)Format::R8G8B8A8_UNorm; -desc.textureType = (uint32_t)TextureType::Texture2D; -desc.sampleCount = 1; -desc.sampleQuality = 0; -desc.flags = 0; - -RHITexture* texture = device->CreateTexture(desc); - -// 设置资源状态 -texture->SetState(ResourceStates::PixelShaderResource); - -// 使用完毕后关闭 -texture->Shutdown(); -``` - -## 相关文档 - -- [RHIDevice](./rhi-device.md) - 创建设备 -- [RHIBuffer](./rhi-buffer.md) - 缓冲区资源 -- [RHISampler](./rhi-sampler.md) - 纹理采样器 diff --git a/docs/api/rhi/rhi-types.md b/docs/api/rhi/rhi-types.md deleted file mode 100644 index c39c8b4f..00000000 --- a/docs/api/rhi/rhi-types.md +++ /dev/null @@ -1,394 +0,0 @@ -# RHITypes - -**命名空间**: `XCEngine::RHI` - -**类型**: `structs` - -**描述**: RHI 模块中使用的所有结构体类型汇总。 - -## 概述 - -本文档汇总了 RHI 模块中定义的所有结构体类型。这些结构体用于配置各种资源的创建和渲染状态。 - ---- - -## Viewport - -视口结构体。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `topLeftX` | `float` | 视口左上角 X 坐标 | -| `topLeftY` | `float` | 视口左上角 Y 坐标 | -| `width` | `float` | 视口宽度 | -| `height` | `float` | 视口高度 | -| `minDepth` | `float` | 最小深度值 | -| `maxDepth` | `float` | 最大深度值 | - ---- - -## Rect - -裁剪矩形结构体。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `left` | `int32_t` | 矩形左边界 | -| `top` | `int32_t` | 矩形上边界 | -| `right` | `int32_t` | 矩形右边界 | -| `bottom` | `int32_t` | 矩形下边界 | - ---- - -## Color - -颜色结构体。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `r` | `float` | 红色分量 (0-1) | -| `g` | `float` | 绿色分量 (0-1) | -| `b` | `float` | 蓝色分量 (0-1) | -| `a` | `float` | Alpha 分量 (0-1) | - ---- - -## ClearValue - -清除值结构体。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `color` | `Color` | 清除颜色 | -| `depth` | `float` | 清除深度值 | -| `stencil` | `uint8_t` | 清除模板值 | - ---- - -## ShaderCompileMacro - -着色器编译宏定义。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `name` | `std::wstring` | 宏名称 | -| `definition` | `std::wstring` | 宏定义值 | - ---- - -## ShaderCompileDesc - -着色器编译描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `entryPoint` | `std::wstring` | 入口点函数名 | -| `profile` | `std::wstring` | 着色器配置文件 | -| `fileName` | `std::wstring` | 源文件名 | -| `macros` | `std::vector` | 编译宏列表 | - ---- - -## InputElementDesc - -输入布局元素描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `semanticName` | `std::string` | 语义名称 (如 POSITION, TEXCOORD) | -| `semanticIndex` | `uint32_t` | 语义索引 | -| `format` | `uint32_t` | 数据格式 | -| `inputSlot` | `uint32_t` | 输入槽 | -| `alignedByteOffset` | `uint32_t` | 对齐字节偏移 | -| `inputSlotClass` | `uint32_t` | 输入槽类别 | -| `instanceDataStepRate` | `uint32_t` | 实例数据步进率 | - ---- - -## InputLayoutDesc - -输入布局描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `elements` | `std::vector` | 输入元素列表 | - ---- - -## VertexBufferBinding - -顶点缓冲绑定描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `bufferLocation` | `uint64_t` | GPU 虚拟地址 | -| `sizeInBytes` | `uint32_t` | 缓冲区大小（字节） | -| `strideInBytes` | `uint32_t` | 单个顶点字节大小 | - ---- - -## TextureCopyLocation - -纹理复制位置描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `plSubresourceIndex` | `uint64_t` | 子资源索引 | -| `pResource` | `void*` | 资源指针 | - ---- - -## TextureDesc - -纹理描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `width` | `uint32_t` | 纹理宽度 | -| `height` | `uint32_t` | 纹理高度 | -| `depth` | `uint32_t` | 纹理深度 | -| `mipLevels` | `uint32_t` | Mipmap 级别数 | -| `arraySize` | `uint32_t` | 数组大小 | -| `format` | `uint32_t` | 纹理格式 | -| `textureType` | `uint32_t` | 纹理类型 | -| `sampleCount` | `uint32_t` | 采样数量 | -| `sampleQuality` | `uint32_t` | 采样质量 | -| `flags` | `uint64_t` | 纹理标志 | - ---- - -## BufferDesc - -缓冲区描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `size` | `uint64_t` | 缓冲区大小（字节） | -| `stride` | `uint32_t` | 元素字节大小 | -| `bufferType` | `uint32_t` | 缓冲区类型 | -| `flags` | `uint64_t` | 缓冲区标志 | - ---- - -## RenderTargetDesc - -渲染目标描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `width` | `uint32_t` | 宽度 | -| `height` | `uint32_t` | 高度 | -| `format` | `uint32_t` | 格式 | -| `sampleCount` | `uint32_t` | 采样数量 | -| `sampleQuality` | `uint32_t` | 采样质量 | - ---- - -## DepthStencilDesc - -深度模板描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `width` | `uint32_t` | 宽度 | -| `height` | `uint32_t` | 高度 | -| `format` | `uint32_t` | 格式 | -| `sampleCount` | `uint32_t` | 采样数量 | -| `sampleQuality` | `uint32_t` | 采样质量 | -| `depthEnable` | `bool` | 是否启用深度测试 | -| `stencilEnable` | `bool` | 是否启用模板测试 | - ---- - -## DescriptorHeapDesc - -描述符堆描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `descriptorCount` | `uint32_t` | 描述符数量 | -| `heapType` | `uint32_t` | 堆类型 | -| `flags` | `uint32_t` | 堆标志 | -| `nodeMask` | `uint32_t` | 节点掩码 | - ---- - -## CommandQueueDesc - -命令队列描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `queueType` | `uint32_t` | 队列类型 | -| `priority` | `uint32_t` | 优先级 | -| `nodeMask` | `uint32_t` | 节点掩码 | -| `flags` | `uint64_t` | 队列标志 | - ---- - -## CommandListDesc - -命令列表描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `commandListType` | `uint32_t` | 命令列表类型 | -| `nodeMask` | `uint32_t` | 节点掩码 | - ---- - -## FenceDesc - -栅栏描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `initialValue` | `uint64_t` | 初始值 | -| `flags` | `uint32_t` | 栅栏标志 | - ---- - -## SamplerDesc - -采样器描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `filter` | `uint32_t` | 过滤模式 | -| `addressU` | `uint32_t` | U 轴寻址模式 | -| `addressV` | `uint32_t` | V 轴寻址模式 | -| `addressW` | `uint32_t` | W 轴寻址模式 | -| `mipLodBias` | `float` | Mipmap 级别偏移 | -| `maxAnisotropy` | `uint32_t` | 最大各向异性 | -| `comparisonFunc` | `uint32_t` | 比较函数 | -| `borderColorR` | `float` | 边框颜色 R | -| `borderColorG` | `float` | 边框颜色 G | -| `borderColorB` | `float` | 边框颜色 B | -| `borderColorA` | `float` | 边框颜色 A | -| `minLod` | `float` | 最小 LOD | -| `maxLod` | `float` | 最大 LOD | - ---- - -## SwapChainDesc - -交换链描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `width` | `uint32_t` | 宽度 | -| `height` | `uint32_t` | 高度 | -| `bufferCount` | `uint32_t` | 缓冲数量 | -| `format` | `uint32_t` | 格式 | -| `refreshRate` | `uint32_t` | 刷新率 | -| `sampleCount` | `uint32_t` | 采样数量 | -| `sampleQuality` | `uint32_t` | 采样质量 | -| `swapEffect` | `uint32_t` | 交换效果 | -| `flags` | `uint32_t` | 交换链标志 | - ---- - -## RHIDeviceDesc - -设备描述。 - -| 成员 | 类型 | 描述 | 默认值 | -|------|------|------|--------| -| `enableDebugLayer` | `bool` | 启用调试层 | `false` | -| `enableGPUValidation` | `bool` | 启用 GPU 验证 | `false` | -| `adapterIndex` | `uint32_t` | 适配器索引 | `0` | -| `windowHandle` | `void*` | 窗口句柄 | `nullptr` | -| `width` | `uint32_t` | 窗口宽度 | `1280` | -| `height` | `uint32_t` | 窗口高度 | `720` | -| `appName` | `std::wstring` | 应用程序名称 | `L"XCEngine"` | - ---- - -## RHIDeviceInfo - -设备信息结构体。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `description` | `std::wstring` | 设备描述 | -| `vendor` | `std::wstring` | 供应商 | -| `renderer` | `std::wstring` | 渲染器 | -| `version` | `std::wstring` | 驱动版本 | -| `majorVersion` | `uint32_t` | 主版本 | -| `minorVersion` | `uint32_t` | 次版本 | -| `dedicatedVideoMemory` | `uint64_t` | 专用显存 | -| `dedicatedSystemMemory` | `uint64_t` | 专用系统内存 | -| `sharedSystemMemory` | `uint64_t` | 共享系统内存 | -| `vendorId` | `uint32_t` | 供应商 ID | -| `deviceId` | `uint32_t` | 设备 ID | -| `isSoftware` | `bool` | 是否软件设备 | - ---- - -## RHIRenderPassDesc - -渲染通道描述。 - -```cpp -struct RHIRenderPassDesc { - struct ColorAttachment { - void* texture = nullptr; - uint32_t loadAction = 0; - uint32_t storeAction = 0; - float clearColor[4] = {0.0f, 0.0f, 0.0f, 1.0f}; - }; - ColorAttachment colorAttachments[8]; - uint32_t colorAttachmentCount = 0; - struct DepthStencilAttachment { - void* texture = nullptr; - uint32_t loadAction = 0; - uint32_t storeAction = 0; - float clearDepth = 1.0f; - uint8_t clearStencil = 0; - } depthStencilAttachment; - bool hasDepthStencil = false; -}; -``` - ---- - -## DescriptorHandle - -描述符句柄。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `ptr` | `uint64_t` | 句柄指针 | - ---- - -## GPUDescriptorHandle - -GPU 描述符句柄。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `ptr` | `uint64_t` | GPU 句柄指针 | - ---- - -## CPUDescriptorHandle - -CPU 描述符句柄。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `ptr` | `uint64_t` | CPU 句柄指针 | - ---- - -## SubresourceRange - -子资源范围。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `baseMipLevel` | `uint32_t` | 基础 Mip 级别 | -| `mipLevels` | `uint32_t` | Mip 级别数 | -| `baseArraySlice` | `uint32_t` | 基础数组切片 | -| `arraySize` | `uint32_t` | 数组大小 | diff --git a/docs/api/rhi/rhi.md b/docs/api/rhi/rhi.md new file mode 100644 index 00000000..3aa0e07a --- /dev/null +++ b/docs/api/rhi/rhi.md @@ -0,0 +1,121 @@ +# RHI 模块 + +**命名空间**: `XCEngine::RHI` + +**描述**: RHI (Rendering Hardware Interface) 是 XCEngine 的硬件抽象层，提供统一的图形 API 接口，支持多个后端实现。 + +## 概述 + +RHI 模块将上层渲染逻辑与底层图形 API 解耦，通过抽象接口层提供对 DirectX 12、OpenGL 等图形 API 的统一访问。这种设计使得渲染代码可以在不同的图形 API 之间无缝切换，无需修改上层业务逻辑。 + +## 架构 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 上层渲染代码 │ +├─────────────────────────────────────────────────────────┤ +│ RHI 抽象接口层 │ +│ (RHIDevice, RHIBuffer, RHITexture, RHICommandList...) │ +├───────────────┬─────────────────┬───────────────────────┤ +│ D3D12 后端 │ OpenGL 后端 │ Vulkan 后端 │ +│ (D3D12Device) │ (OpenGLDevice) │ (预留) │ +├───────────────┴─────────────────┴───────────────────────┤ +│ 原生图形 API (DirectX 12 / OpenGL) │ +└─────────────────────────────────────────────────────────┘ +``` + +## 后端类型 + +| 后端 | 枚举值 | 描述 | +|------|--------|------| +| DirectX 12 | `RHIType::D3D12` | DirectX 12 实现，现代 PC 游戏首选 | +| OpenGL | `RHIType::OpenGL` | OpenGL Core Profile 实现，跨平台兼容 | + +## 抽象类 + +### 核心设备 + +| 类 | 文档 | 描述 | +|----|------|------| +| [RHIDevice](device/device.md) | `RHIDevice.h` | 渲染设备抽象，代表图形适配器实例 | +| [RHIFactory](factory/factory.md) | `RHIFactory.h` | 设备工厂，用于创建不同后端的设备实例 | + +### 资源管理 + +| 类 | 文档 | 描述 | +|----|------|------| +| [RHIBuffer](buffer/buffer.md) | `RHIBuffer.h` | GPU 缓冲区资源，存储顶点、索引、常量等数据 | +| [RHITexture](texture/texture.md) | `RHITexture.h` | GPU 纹理资源，存储 1D/2D/3D 图像数据 | +| [RHIShader](shader/shader.md) | `RHIShader.h` | 着色器资源，管理顶点、像素等着色器程序 | + +### 命令执行 + +| 类 | 文档 | 描述 | +|----|------|------| +| [RHICommandList](command-list/command-list.md) | `RHICommandList.h` | 命令列表，记录 GPU 命令 | +| [RHICommandQueue](command-queue/command-queue.md) | `RHICommandQueue.h` | 命令队列，提交和执行命令列表 | +| [RHISwapChain](swap-chain/swap-chain.md) | `RHISwapChain.h` | 交换链，管理帧缓冲区和显示输出 | + +### 同步与状态 + +| 类 | 文档 | 描述 | +|----|------|------| +| [RHIFence](fence/fence.md) | `RHIFence.h` | 同步栅栏，CPU/GPU 同步原语 | +| [RHIPipelineState](pipeline-state/pipeline-state.md) | `RHIPipelineState.h` | 管线状态对象，封装渲染管线配置 | +| [RHISampler](sampler/sampler.md) | `RHISampler.h` | 纹理采样器，配置纹理过滤和寻址模式 | +| [RHIPipelineLayout](pipeline-layout/pipeline-layout.md) | `RHIPipelineLayout.h` | 管线布局，定义着色器资源绑定布局 | +| [RHIDescriptorPool](descriptor-pool/descriptor-pool.md) | `RHIDescriptorPool.h` | 描述符池，管理 GPU 描述符分配 | + +### 类型与能力 + +| 类 | 文档 | 描述 | +|----|------|------| +| [RHICapabilities](capabilities/capabilities.md) | `RHICapabilities.h` | 设备能力结构，描述支持的图形特性 | +| [RHITypes](types/types.md) | `RHITypes.h` | 类型定义，包含所有结构体描述符 | +| [RHIEnums](enums/enums.md) | `RHIEnums.h` | 枚举定义，包含所有枚举类型 | + +## 使用流程 + +```cpp +#include +#include + +using namespace XCEngine::RHI; + +// 1. 创建设备 +RHIDevice* device = RHIFactory::CreateRHIDevice(RHIType::D3D12); + +// 2. 初始化设备 +RHIDeviceDesc desc; +desc.windowHandle = hwnd; +desc.width = 1280; +desc.height = 720; +device->Initialize(desc); + +// 3. 创建资源 +RHIBuffer* vertexBuffer = device->CreateBuffer(bufferDesc); +RHITexture* texture = device->CreateTexture(textureDesc); + +// 4. 创建命令列表并录制 +RHICommandList* cmdList = device->CreateCommandList(cmdListDesc); +RHICommandQueue* cmdQueue = device->CreateCommandQueue(queueDesc); + +// 5. 渲染循环 +while (!swapChain->ShouldClose()) { + cmdQueue->ExecuteCommandLists(1, (void**)&cmdList); + swapChain->Present(); +} + +// 6. 清理 +device->Shutdown(); +delete device; +``` + +## 后端文档 + +- [D3D12 后端](d3d12/overview.md) - DirectX 12 实现详情 +- [OpenGL 后端](d3d12/overview.md) - OpenGL 实现详情 + +## 相关文档 + +- [RHI 模块源码](../../engine/include/XCEngine/RHI/) - 源代码位置 diff --git a/docs/api/rhi/sampler/get-id.md b/docs/api/rhi/sampler/get-id.md new file mode 100644 index 00000000..a38a1c38 --- /dev/null +++ b/docs/api/rhi/sampler/get-id.md @@ -0,0 +1,19 @@ +# RHISampler::GetID + +```cpp +virtual unsigned int GetID() = 0; +``` + +获取采样器 ID。 + +**返回：** 采样器唯一标识符 + +**示例：** + +```cpp +unsigned int id = sampler->GetID(); +``` + +## 相关文档 + +- [RHISampler 总览](sampler.md) - 返回类总览 diff --git a/docs/api/rhi/sampler/methods.md b/docs/api/rhi/sampler/methods.md new file mode 100644 index 00000000..a4307b0e --- /dev/null +++ b/docs/api/rhi/sampler/methods.md @@ -0,0 +1,41 @@ +# RHISampler 方法 + +## Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +释放采样器资源。 + +## Bind + +```cpp +virtual void Bind(unsigned int unit) = 0; +``` + +绑定采样器到纹理单元。 + +## Unbind + +```cpp +virtual void Unbind(unsigned int unit) = 0; +``` + +解绑采样器。 + +## GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取原生 API 句柄。 + +## GetID + +```cpp +virtual unsigned int GetID() = 0; +``` + +获取采样器 ID。 diff --git a/docs/api/rhi/sampler/sampler.md b/docs/api/rhi/sampler/sampler.md new file mode 100644 index 00000000..27654e83 --- /dev/null +++ b/docs/api/rhi/sampler/sampler.md @@ -0,0 +1,34 @@ +# RHISampler + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: GPU 纹理采样器抽象接口，用于配置纹理过滤和寻址模式。 + +## 公共方法 + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | + +### 绑定/解绑 + +| 方法 | 文档 | +|------|------| +| `Bind` | [详细文档](../shader/bind.md) | +| `Unbind` | [详细文档](../shader/unbind.md) | + +### 属性访问 + +| 方法 | 文档 | +|------|------| +| `GetNativeHandle` | [详细文档](../buffer/get-native-handle.md) | +| `GetID` | [详细文档](get-id.md) | + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHITexture](../texture/texture.md) - 纹理资源 diff --git a/docs/api/rhi/shader/bind.md b/docs/api/rhi/shader/bind.md new file mode 100644 index 00000000..b5461119 --- /dev/null +++ b/docs/api/rhi/shader/bind.md @@ -0,0 +1,20 @@ +# RHIShader::Bind + +```cpp +virtual void Bind() = 0; +``` + +绑定着色器到管线。 + +**复杂度：** O(1) + +**示例：** + +```cpp +vs->Bind(); +ps->Bind(); +``` + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/compile-from-file.md b/docs/api/rhi/shader/compile-from-file.md new file mode 100644 index 00000000..92a28a53 --- /dev/null +++ b/docs/api/rhi/shader/compile-from-file.md @@ -0,0 +1,26 @@ +# RHIShader::CompileFromFile + +```cpp +virtual bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) = 0; +``` + +从文件编译着色器。 + +**参数：** +- `filePath` - 着色器源文件路径 +- `entryPoint` - 入口点函数名 +- `target` - 编译目标（如 `"vs_6_0"`, `"ps_6_0"`） + +**返回：** 成功返回 `true`，失败返回 `false` + +**复杂度：** O(n) - 取决于着色器代码复杂度 + +**示例：** + +```cpp +shader->CompileFromFile(L"shaders/vertex.hlsl", "main", "vs_6_0"); +``` + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/compile.md b/docs/api/rhi/shader/compile.md new file mode 100644 index 00000000..b9032398 --- /dev/null +++ b/docs/api/rhi/shader/compile.md @@ -0,0 +1,21 @@ +# RHIShader::Compile + +```cpp +virtual bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) = 0; +``` + +从内存编译着色器。 + +**参数：** +- `sourceData` - 着色器源代码指针 +- `sourceSize` - 源代码大小 +- `entryPoint` - 入口点函数名 +- `target` - 编译目标 + +**返回：** 成功返回 `true`，失败返回 `false` + +**复杂度：** O(n) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/get-native-handle.md b/docs/api/rhi/shader/get-native-handle.md new file mode 100644 index 00000000..d46e059e --- /dev/null +++ b/docs/api/rhi/shader/get-native-handle.md @@ -0,0 +1,15 @@ +# RHIShader::GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取原生 API 句柄。 + +**返回：** 原生着色器句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/get-type.md b/docs/api/rhi/shader/get-type.md new file mode 100644 index 00000000..5b364da5 --- /dev/null +++ b/docs/api/rhi/shader/get-type.md @@ -0,0 +1,15 @@ +# RHIShader::GetType + +```cpp +virtual ShaderType GetType() const = 0; +``` + +获取着色器类型。 + +**返回：** 着色器类型枚举值 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/is-valid.md b/docs/api/rhi/shader/is-valid.md new file mode 100644 index 00000000..56597ea1 --- /dev/null +++ b/docs/api/rhi/shader/is-valid.md @@ -0,0 +1,15 @@ +# RHIShader::IsValid + +```cpp +virtual bool IsValid() const = 0; +``` + +检查着色器是否有效（已成功编译）。 + +**返回：** 有效返回 `true`，无效返回 `false` + +**复杂度：** O(1) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/set-float.md b/docs/api/rhi/shader/set-float.md new file mode 100644 index 00000000..89f6ad17 --- /dev/null +++ b/docs/api/rhi/shader/set-float.md @@ -0,0 +1,17 @@ +# RHIShader::SetFloat + +```cpp +virtual void SetFloat(const char* name, float value) = 0; +``` + +设置浮点 uniform。 + +**参数：** +- `name` - uniform 变量名 +- `value` - 浮点值 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/set-int.md b/docs/api/rhi/shader/set-int.md new file mode 100644 index 00000000..1bddd314 --- /dev/null +++ b/docs/api/rhi/shader/set-int.md @@ -0,0 +1,17 @@ +# RHIShader::SetInt + +```cpp +virtual void SetInt(const char* name, int value) = 0; +``` + +设置整数 uniform。 + +**参数：** +- `name` - uniform 变量名 +- `value` - 整数值 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/set-mat4.md b/docs/api/rhi/shader/set-mat4.md new file mode 100644 index 00000000..b739e3f1 --- /dev/null +++ b/docs/api/rhi/shader/set-mat4.md @@ -0,0 +1,17 @@ +# RHIShader::SetMat4 + +```cpp +virtual void SetMat4(const char* name, const float* value) = 0; +``` + +设置 4x4 矩阵 uniform。 + +**参数：** +- `name` - uniform 变量名 +- `value` - 矩阵数据指针（16 个 float） + +**复杂度：** O(1) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/set-vec3.md b/docs/api/rhi/shader/set-vec3.md new file mode 100644 index 00000000..3ef86651 --- /dev/null +++ b/docs/api/rhi/shader/set-vec3.md @@ -0,0 +1,17 @@ +# RHIShader::SetVec3 + +```cpp +virtual void SetVec3(const char* name, float x, float y, float z) = 0; +``` + +设置三维向量 uniform。 + +**参数：** +- `name` - uniform 变量名 +- `x, y, z` - 向量分量 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/set-vec4.md b/docs/api/rhi/shader/set-vec4.md new file mode 100644 index 00000000..b3e456f3 --- /dev/null +++ b/docs/api/rhi/shader/set-vec4.md @@ -0,0 +1,17 @@ +# RHIShader::SetVec4 + +```cpp +virtual void SetVec4(const char* name, float x, float y, float z, float w) = 0; +``` + +设置四维向量 uniform。 + +**参数：** +- `name` - uniform 变量名 +- `x, y, z, w` - 向量分量 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/shader.md b/docs/api/rhi/shader/shader.md new file mode 100644 index 00000000..0b6efcff --- /dev/null +++ b/docs/api/rhi/shader/shader.md @@ -0,0 +1,74 @@ +# RHIShader + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: GPU 着色器资源抽象接口，用于管理着色器代码的编译和绑定。 + +## 公共方法 + +### 编译 + +| 方法 | 文档 | +|------|------| +| `CompileFromFile` | [详细文档](compile-from-file.md) | +| `Compile` | [详细文档](compile.md) | + +### 属性访问 + +| 方法 | 文档 | +|------|------| +| `GetType` | [详细文档](get-type.md) | +| `IsValid` | [详细文档](is-valid.md) | + +### 绑定/解绑 + +| 方法 | 文档 | +|------|------| +| `Bind` | [详细文档](bind.md) | +| `Unbind` | [详细文档](unbind.md) | + +### Uniform 设置 + +| 方法 | 文档 | +|------|------| +| `SetInt` | [详细文档](set-int.md) | +| `SetFloat` | [详细文档](set-float.md) | +| `SetVec3` | [详细文档](set-vec3.md) | +| `SetVec4` | [详细文档](set-vec4.md) | +| `SetMat4` | [详细文档](set-mat4.md) | + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | + +### 其他 + +| 方法 | 文档 | +|------|------| +| `GetNativeHandle` | [详细文档](../buffer/get-native-handle.md) | + +## 着色器类型 (ShaderType) + +| 枚举值 | 描述 | +|--------|------| +| `Vertex` | 顶点着色器 | +| `Fragment` | 片元着色器 | +| `Compute` | 计算着色器 | + +## 使用示例 + +```cpp +RHIShader* vs = device->CompileShader({}); +vs->CompileFromFile(L"shaders/vertex.hlsl", "main", "vs_6_0"); +vs->SetMat4("modelMatrix", modelMatrix); +vs->Bind(); +``` + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHIDevice](../device/device.md) - 创建设备 diff --git a/docs/api/rhi/shader/shutdown.md b/docs/api/rhi/shader/shutdown.md new file mode 100644 index 00000000..9972cefe --- /dev/null +++ b/docs/api/rhi/shader/shutdown.md @@ -0,0 +1,13 @@ +# RHIShader::Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +释放着色器资源。 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/unbind.md b/docs/api/rhi/shader/unbind.md new file mode 100644 index 00000000..53aedf60 --- /dev/null +++ b/docs/api/rhi/shader/unbind.md @@ -0,0 +1,13 @@ +# RHIShader::Unbind + +```cpp +virtual void Unbind() = 0; +``` + +解绑着色器。 + +**复杂度：** O(1) + +## 相关文档 + +- [RHIShader 总览](shader.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/get-current-back-buffer-index.md b/docs/api/rhi/swap-chain/get-current-back-buffer-index.md new file mode 100644 index 00000000..18666dfa --- /dev/null +++ b/docs/api/rhi/swap-chain/get-current-back-buffer-index.md @@ -0,0 +1,19 @@ +# RHISwapChain::GetCurrentBackBufferIndex + +```cpp +virtual uint32_t GetCurrentBackBufferIndex() const = 0; +``` + +获取当前后台缓冲区索引。 + +**返回：** 当前后台缓冲区索引 + +**示例：** + +```cpp +uint32_t index = swapChain->GetCurrentBackBufferIndex(); +``` + +## 相关文档 + +- [RHISwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/get-current-back-buffer.md b/docs/api/rhi/swap-chain/get-current-back-buffer.md new file mode 100644 index 00000000..b068535c --- /dev/null +++ b/docs/api/rhi/swap-chain/get-current-back-buffer.md @@ -0,0 +1,19 @@ +# RHISwapChain::GetCurrentBackBuffer + +```cpp +virtual RHITexture* GetCurrentBackBuffer() = 0; +``` + +获取当前后台缓冲区纹理。 + +**返回：** 当前后台缓冲区纹理指针 + +**示例：** + +```cpp +RHITexture* backBuffer = swapChain->GetCurrentBackBuffer(); +``` + +## 相关文档 + +- [RHISwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/is-fullscreen.md b/docs/api/rhi/swap-chain/is-fullscreen.md new file mode 100644 index 00000000..f7ef1b0b --- /dev/null +++ b/docs/api/rhi/swap-chain/is-fullscreen.md @@ -0,0 +1,21 @@ +# RHISwapChain::IsFullscreen + +```cpp +virtual bool IsFullscreen() const = 0; +``` + +检查是否处于全屏模式。 + +**返回：** 如果全屏返回 true + +**示例：** + +```cpp +if (swapChain->IsFullscreen()) { + // 全屏模式 +} +``` + +## 相关文档 + +- [RHISwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/methods.md b/docs/api/rhi/swap-chain/methods.md new file mode 100644 index 00000000..5f2ac89e --- /dev/null +++ b/docs/api/rhi/swap-chain/methods.md @@ -0,0 +1,89 @@ +# RHISwapChain 方法 + +## Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +关闭交换链。 + +## GetCurrentBackBufferIndex + +```cpp +virtual uint32_t GetCurrentBackBufferIndex() const = 0; +``` + +获取当前后台缓冲索引。 + +## GetCurrentBackBuffer + +```cpp +virtual RHITexture* GetCurrentBackBuffer() = 0; +``` + +获取当前后台缓冲纹理。 + +## Present + +```cpp +virtual void Present(uint32_t syncInterval = 1, uint32_t flags = 0) = 0; +``` + +呈现渲染结果。 + +## Resize + +```cpp +virtual void Resize(uint32_t width, uint32_t height) = 0; +``` + +调整交换链大小。 + +## SetFullscreen + +```cpp +virtual void SetFullscreen(bool fullscreen) = 0; +``` + +设置全屏模式。 + +## IsFullscreen + +```cpp +virtual bool IsFullscreen() const = 0; +``` + +检查是否全屏。 + +## ShouldClose + +```cpp +virtual bool ShouldClose() const = 0; +``` + +检查是否应该关闭。 + +## SetShouldClose + +```cpp +virtual void SetShouldClose(bool shouldClose) = 0; +``` + +设置关闭标志。 + +## PollEvents + +```cpp +virtual void PollEvents() = 0; +``` + +处理窗口事件。 + +## GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取原生 API 句柄。 diff --git a/docs/api/rhi/swap-chain/poll-events.md b/docs/api/rhi/swap-chain/poll-events.md new file mode 100644 index 00000000..c49d8723 --- /dev/null +++ b/docs/api/rhi/swap-chain/poll-events.md @@ -0,0 +1,17 @@ +# RHISwapChain::PollEvents + +```cpp +virtual void PollEvents() = 0; +``` + +处理窗口事件。 + +**示例：** + +```cpp +swapChain->PollEvents(); +``` + +## 相关文档 + +- [RHISwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/present.md b/docs/api/rhi/swap-chain/present.md new file mode 100644 index 00000000..ca10e72d --- /dev/null +++ b/docs/api/rhi/swap-chain/present.md @@ -0,0 +1,21 @@ +# RHISwapChain::Present + +```cpp +virtual void Present(uint32_t syncInterval = 1, uint32_t flags = 0) = 0; +``` + +呈现后台缓冲区。 + +**参数：** +- `syncInterval` - 垂直同步间隔（0=立即，1+=等待） +- `flags` - 呈现标志 + +**示例：** + +```cpp +swapChain->Present(1); // 垂直同步呈现 +``` + +## 相关文档 + +- [RHISwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/set-fullscreen.md b/docs/api/rhi/swap-chain/set-fullscreen.md new file mode 100644 index 00000000..bdc99ac9 --- /dev/null +++ b/docs/api/rhi/swap-chain/set-fullscreen.md @@ -0,0 +1,20 @@ +# RHISwapChain::SetFullscreen + +```cpp +virtual void SetFullscreen(bool fullscreen) = 0; +``` + +设置全屏模式。 + +**参数：** +- `fullscreen` - 是否全屏 + +**示例：** + +```cpp +swapChain->SetFullscreen(true); +``` + +## 相关文档 + +- [RHISwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/set-should-close.md b/docs/api/rhi/swap-chain/set-should-close.md new file mode 100644 index 00000000..f16d4dc0 --- /dev/null +++ b/docs/api/rhi/swap-chain/set-should-close.md @@ -0,0 +1,20 @@ +# RHISwapChain::SetShouldClose + +```cpp +virtual void SetShouldClose(bool shouldClose) = 0; +``` + +设置交换链关闭标志。 + +**参数：** +- `shouldClose` - 是否应该关闭 + +**示例：** + +```cpp +swapChain->SetShouldClose(true); +``` + +## 相关文档 + +- [RHISwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/should-close.md b/docs/api/rhi/swap-chain/should-close.md new file mode 100644 index 00000000..7d7eed36 --- /dev/null +++ b/docs/api/rhi/swap-chain/should-close.md @@ -0,0 +1,21 @@ +# RHISwapChain::ShouldClose + +```cpp +virtual bool ShouldClose() const = 0; +``` + +检查交换链是否应该关闭。 + +**返回：** 如果应该关闭返回 true + +**示例：** + +```cpp +while (!swapChain->ShouldClose()) { + // 渲染循环 +} +``` + +## 相关文档 + +- [RHISwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/swap-chain.md b/docs/api/rhi/swap-chain/swap-chain.md new file mode 100644 index 00000000..3590ae57 --- /dev/null +++ b/docs/api/rhi/swap-chain/swap-chain.md @@ -0,0 +1,65 @@ +# RHISwapChain + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: GPU 交换链抽象接口，用于管理窗口渲染和帧缓冲区切换。 + +## 公共方法 + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | + +### 交换链操作 + +| 方法 | 文档 | +|------|------| +| `GetCurrentBackBufferIndex` | [详细文档](get-current-back-buffer-index.md) | +| `GetCurrentBackBuffer` | [详细文档](get-current-back-buffer.md) | +| `Present` | [详细文档](present.md) | +| `Resize` | [详细文档](../../containers/array/resize.md) | + +### 全屏模式 + +| 方法 | 文档 | +|------|------| +| `SetFullscreen` | [详细文档](set-fullscreen.md) | +| `IsFullscreen` | [详细文档](is-fullscreen.md) | + +### 窗口事件 + +| 方法 | 文档 | +|------|------| +| `ShouldClose` | [详细文档](should-close.md) | +| `SetShouldClose` | [详细文档](set-should-close.md) | +| `PollEvents` | [详细文档](poll-events.md) | + +### 其他 + +| 方法 | 文档 | +|------|------| +| `GetNativeHandle` | [详细文档](../buffer/get-native-handle.md) | + +## 使用示例 + +```cpp +while (!swapChain->ShouldClose()) { + swapChain->PollEvents(); + RHITexture* backBuffer = swapChain->GetCurrentBackBuffer(); + commandList->Reset(); + commandList->SetRenderTargets(1, &backBuffer, nullptr); + commandList->ClearRenderTarget(backBuffer, clearColor); + commandList->Close(); + commandQueue->ExecuteCommandLists(1, (void**)&commandList); + swapChain->Present(1, 0); +} +``` + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHITexture](../texture/texture.md) - 纹理资源 diff --git a/docs/api/rhi/texture/get-depth.md b/docs/api/rhi/texture/get-depth.md new file mode 100644 index 00000000..fdaf4ddd --- /dev/null +++ b/docs/api/rhi/texture/get-depth.md @@ -0,0 +1,15 @@ +# RHITexture::GetDepth + +```cpp +virtual uint32_t GetDepth() const = 0; +``` + +获取纹理深度（3D 纹理）。 + +**返回：** 纹理深度 + +**复杂度：** O(1) + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-format.md b/docs/api/rhi/texture/get-format.md new file mode 100644 index 00000000..50fd3c95 --- /dev/null +++ b/docs/api/rhi/texture/get-format.md @@ -0,0 +1,15 @@ +# RHITexture::GetFormat + +```cpp +virtual Format GetFormat() const = 0; +``` + +获取纹理格式。 + +**返回：** 纹理格式枚举值 + +**复杂度：** O(1) + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-height.md b/docs/api/rhi/texture/get-height.md new file mode 100644 index 00000000..fe5675e8 --- /dev/null +++ b/docs/api/rhi/texture/get-height.md @@ -0,0 +1,15 @@ +# RHITexture::GetHeight + +```cpp +virtual uint32_t GetHeight() const = 0; +``` + +获取纹理高度（像素）。 + +**返回：** 纹理高度 + +**复杂度：** O(1) + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-mip-levels.md b/docs/api/rhi/texture/get-mip-levels.md new file mode 100644 index 00000000..3c0e74c0 --- /dev/null +++ b/docs/api/rhi/texture/get-mip-levels.md @@ -0,0 +1,15 @@ +# RHITexture::GetMipLevels + +```cpp +virtual uint32_t GetMipLevels() const = 0; +``` + +获取 Mipmap 级别数。 + +**返回：** Mipmap 级别数 + +**复杂度：** O(1) + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-name.md b/docs/api/rhi/texture/get-name.md new file mode 100644 index 00000000..a2ede79c --- /dev/null +++ b/docs/api/rhi/texture/get-name.md @@ -0,0 +1,20 @@ +# RHITexture::GetName / SetName + +```cpp +virtual const std::string& GetName() const = 0; +virtual void SetName(const std::string& name) = 0; +``` + +获取或设置纹理名称（用于调试）。 + +**复杂度：** O(1) + +**示例：** + +```cpp +texture->SetName("DiffuseMap_Main"); +``` + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-native-handle.md b/docs/api/rhi/texture/get-native-handle.md new file mode 100644 index 00000000..eac0e540 --- /dev/null +++ b/docs/api/rhi/texture/get-native-handle.md @@ -0,0 +1,15 @@ +# RHITexture::GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取原生 API 句柄。 + +**返回：** 原生纹理句柄 + +**复杂度：** O(1) + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-state.md b/docs/api/rhi/texture/get-state.md new file mode 100644 index 00000000..2b907ad0 --- /dev/null +++ b/docs/api/rhi/texture/get-state.md @@ -0,0 +1,15 @@ +# RHITexture::GetState + +```cpp +virtual ResourceStates GetState() const = 0; +``` + +获取当前资源状态。 + +**返回：** 资源状态枚举值 + +**复杂度：** O(1) + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-texture-type.md b/docs/api/rhi/texture/get-texture-type.md new file mode 100644 index 00000000..3081d471 --- /dev/null +++ b/docs/api/rhi/texture/get-texture-type.md @@ -0,0 +1,15 @@ +# RHITexture::GetTextureType + +```cpp +virtual TextureType GetTextureType() const = 0; +``` + +获取纹理类型。 + +**返回：** 纹理类型枚举值 + +**复杂度：** O(1) + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-width.md b/docs/api/rhi/texture/get-width.md new file mode 100644 index 00000000..9b339620 --- /dev/null +++ b/docs/api/rhi/texture/get-width.md @@ -0,0 +1,15 @@ +# RHITexture::GetWidth + +```cpp +virtual uint32_t GetWidth() const = 0; +``` + +获取纹理宽度（像素）。 + +**返回：** 纹理宽度 + +**复杂度：** O(1) + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/set-name.md b/docs/api/rhi/texture/set-name.md new file mode 100644 index 00000000..5300884d --- /dev/null +++ b/docs/api/rhi/texture/set-name.md @@ -0,0 +1,22 @@ +# RHITexture::SetName + +```cpp +virtual void SetName(const std::string& name) = 0; +``` + +设置纹理名称（用于调试）。 + +**参数：** +- `name` - 新名称 + +**复杂度：** O(1) + +**示例：** + +```cpp +texture->SetName("DiffuseMap"); +``` + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/set-state.md b/docs/api/rhi/texture/set-state.md new file mode 100644 index 00000000..5956f72a --- /dev/null +++ b/docs/api/rhi/texture/set-state.md @@ -0,0 +1,22 @@ +# RHITexture::SetState + +```cpp +virtual void SetState(ResourceStates state) = 0; +``` + +设置资源状态。 + +**参数：** +- `state` - 新的资源状态 + +**复杂度：** O(1) + +**示例：** + +```cpp +texture->SetState(ResourceStates::PixelShaderResource); +``` + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/shutdown.md b/docs/api/rhi/texture/shutdown.md new file mode 100644 index 00000000..9ccf4beb --- /dev/null +++ b/docs/api/rhi/texture/shutdown.md @@ -0,0 +1,13 @@ +# RHITexture::Shutdown + +```cpp +virtual void Shutdown() = 0; +``` + +释放纹理资源。 + +**复杂度：** O(1) + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/texture.md b/docs/api/rhi/texture/texture.md new file mode 100644 index 00000000..b5147d52 --- /dev/null +++ b/docs/api/rhi/texture/texture.md @@ -0,0 +1,82 @@ +# RHITexture + +**命名空间**: `XCEngine::RHI` + +**类型**: `class` (abstract) + +**描述**: GPU 纹理资源抽象接口，用于管理 1D、2D、3D 纹理和立方体贴图等 GPU 资源。 + +## 公共方法 + +### 属性访问 + +| 方法 | 文档 | +|------|------| +| `GetWidth` | [详细文档](get-width.md) | +| `GetHeight` | [详细文档](get-height.md) | +| `GetDepth` | [详细文档](get-depth.md) | +| `GetMipLevels` | [详细文档](get-mip-levels.md) | +| `GetFormat` | [详细文档](get-format.md) | +| `GetTextureType` | [详细文档](get-texture-type.md) | + +### 状态管理 + +| 方法 | 文档 | +|------|------| +| `GetState` | [详细文档](../buffer/get-state.md) | +| `SetState` | [详细文档](../buffer/set-state.md) | + +### 生命周期 + +| 方法 | 文档 | +|------|------| +| `Shutdown` | [详细文档](../../threading/task-system/shutdown.md) | + +### 其他 + +| 方法 | 文档 | +|------|------| +| `GetNativeHandle` | [详细文档](../buffer/get-native-handle.md) | +| `GetName` | [详细文档](../buffer/get-name.md) | +| `SetName` | [详细文档](../buffer/set-name.md) | + +## 纹理类型 (TextureType) + +| 枚举值 | 描述 | +|--------|------| +| `TextureType::Texture1D` | 1D 纹理 | +| `TextureType::Texture2D` | 2D 纹理 | +| `TextureType::Texture2DArray` | 2D 纹理数组 | +| `TextureType::Texture3D` | 3D 纹理（体积纹理） | +| `TextureType::TextureCube` | 立方体贴图 | +| `TextureType::TextureCubeArray` | 立方体贴图数组 | + +## 纹理格式 (Format) + +| 格式 | 描述 | +|------|------| +| `Format::R8G8B8A8_UNorm` | 四通道 8 位归一化 | +| `Format::R16G16B16A16_Float` | 四通道 16 位浮点 | +| `Format::D32_Float` | 32 位深度 | +| `Format::BC1_UNorm` | BC1 压缩 (DXT1) | +| `Format::BC7_UNorm` | BC7 高质量压缩 | + +## 使用示例 + +```cpp +TextureDesc desc; +desc.width = 1024; +desc.height = 1024; +desc.format = (uint32_t)Format::R8G8B8A8_UNorm; +desc.textureType = (uint32_t)TextureType::Texture2D; + +RHITexture* texture = device->CreateTexture(desc); +texture->SetState(ResourceStates::PixelShaderResource); +texture->Shutdown(); +``` + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHIDevice](../device/device.md) - 创建设备 +- [RHIBuffer](../buffer/buffer.md) - 缓冲区资源 diff --git a/docs/api/rhi/types/types.md b/docs/api/rhi/types/types.md new file mode 100644 index 00000000..67e72f18 --- /dev/null +++ b/docs/api/rhi/types/types.md @@ -0,0 +1,81 @@ +# RHITypes + +**命名空间**: `XCEngine::RHI` + +**类型**: `structs` + +**描述**: RHI 模块中使用的所有结构体类型汇总。 + +## 概述 + +本模块汇总了 RHI 模块中定义的所有结构体类型。这些结构体用于配置各种资源的创建和渲染状态。 + +## 主要结构体 + +### 视口和矩形 + +| 结构体 | 描述 | +|--------|------| +| `Viewport` | 视口结构体 | +| `Rect` | 裁剪矩形结构体 | +| `Color` | 颜色结构体 | +| `ClearValue` | 清除值结构体 | + +### 着色器 + +| 结构体 | 描述 | +|--------|------| +| `ShaderCompileMacro` | 着色器编译宏定义 | +| `ShaderCompileDesc` | 着色器编译描述 | +| `InputElementDesc` | 输入布局元素描述 | +| `InputLayoutDesc` | 输入布局描述 | + +### 资源和描述符 + +| 结构体 | 描述 | +|--------|------| +| `TextureDesc` | 纹理描述 | +| `BufferDesc` | 缓冲区描述 | +| `RenderTargetDesc` | 渲染目标描述 | +| `DepthStencilDesc` | 深度模板描述 | +| `DescriptorHeapDesc` | 描述符堆描述 | +| `RenderTargetViewDesc` | 渲染目标视图描述 | +| `DepthStencilViewDesc` | 深度模板视图描述 | +| `ShaderResourceViewDesc` | 着色器资源视图描述 | +| `ConstantBufferViewDesc` | 常量缓冲视图描述 | +| `UnorderedAccessViewDesc` | 无序访问视图描述 | + +### 命令 + +| 结构体 | 描述 | +|--------|------| +| `CommandQueueDesc` | 命令队列描述 | +| `CommandListDesc` | 命令列表描述 | +| `CommandAllocatorDesc` | 命令分配器描述 | +| `FenceDesc` | 栅栏描述 | +| `QueryHeapDesc` | 查询堆描述 | +| `SamplerDesc` | 采样器描述 | +| `SwapChainDesc` | 交换链描述 | + +### 设备 + +| 结构体 | 描述 | +|--------|------| +| `RHIDeviceDesc` | 设备描述 | +| `RHIDeviceInfo` | 设备信息 | +| `RHIRenderPassDesc` | 渲染通道描述 | +| `RHIPipelineLayoutDesc` | 管线布局描述 | + +### 句柄 + +| 结构体 | 描述 | +|--------|------| +| `DescriptorHandle` | 描述符句柄 | +| `GPUDescriptorHandle` | GPU 描述符句柄 | +| `CPUDescriptorHandle` | CPU 描述符句柄 | +| `SubresourceRange` | 子资源范围 | + +## 相关文档 + +- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHIEnums](../enums/enums.md) - 枚举类型汇总 diff --git a/docs/api/threading/lambdatask/constructor.md b/docs/api/threading/lambdatask/constructor.md new file mode 100644 index 00000000..81d56424 --- /dev/null +++ b/docs/api/threading/lambdatask/constructor.md @@ -0,0 +1,41 @@ +# LambdaTask::LambdaTask + +```cpp +explicit LambdaTask(Func&& func, TaskPriority priority = TaskPriority::Normal) +``` + +构造 Lambda 任务对象，将可调用对象包装为 ITask。 + +**模板参数：** +- `Func` - 可调用对象类型 + +**参数：** +- `func` - 要封装的可调用对象（lambda、函数指针、std::function 等） +- `priority` - 任务优先级，默认值为 TaskPriority::Normal + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +// 使用 std::function lambda +auto task = std::make_unique>>( + []() { printf("Task executed\n"); }, + TaskPriority::High +); +TaskSystem::Get().Submit(std::move(task)); + +// 配合 TaskSystem::Submit 的重载直接使用 +TaskSystem::Get().Submit( + std::make_unique>>( + []() { ProcessData(); }, + TaskPriority::Critical + ) +); +``` + +## 相关文档 + +- [LambdaTask 总览](lambdatask.md) - 返回类总览 diff --git a/docs/api/threading/threading-lambdatask.md b/docs/api/threading/lambdatask/lambdatask.md similarity index 70% rename from docs/api/threading/threading-lambdatask.md rename to docs/api/threading/lambdatask/lambdatask.md index 2ccbcf96..1251db80 100644 --- a/docs/api/threading/threading-lambdatask.md +++ b/docs/api/threading/lambdatask/lambdatask.md @@ -4,6 +4,8 @@ **类型**: `class` (template) +**头文件**: `XCEngine/Threading/LambdaTask.h` + **描述**: Lambda 任务封装模板类，允许使用 lambda 表达式创建任务，无需继承 ITask。 ## 概述 @@ -20,7 +22,7 @@ | 方法 | 描述 | |------|------| -| `explicit LambdaTask(Func&& func, TaskPriority priority = TaskPriority::Normal)` | 构造 Lambda 任务 | +| [`LambdaTask`](constructor.md) | 构造 Lambda 任务 | ## 使用示例 @@ -39,15 +41,11 @@ TaskSystem::Get().Submit( TaskSystem::Get().Submit([]() { printf("Direct lambda task!\n"); }); - -// 带依赖的任务 -TaskSystem::Get().Submit>([]() { - // 任务内容 -}, TaskPriority::High); ``` ## 相关文档 -- [ITask](./threading-task.md) - 任务基类 -- [TaskGroup](./threading-task-group.md) - 任务组 -- [TaskSystem](./threading-task-system.md) - 任务系统 +- [ITask](../task/task.md) - 任务基类 +- [TaskGroup](../task-group/task-group.md) - 任务组 +- [TaskSystem](../task-system/task-system.md) - 任务系统 +- [../threading/threading.md](../threading.md) - 模块总览 diff --git a/docs/api/threading/mutex/lock.md b/docs/api/threading/mutex/lock.md new file mode 100644 index 00000000..7fc8e74e --- /dev/null +++ b/docs/api/threading/mutex/lock.md @@ -0,0 +1,34 @@ +# Mutex::Lock + +```cpp +void Lock() +``` + +获取互斥锁。如果锁已被其他线程持有，则阻塞当前线程直到锁可用。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** 平均 O(1)，最坏情况 O(n)，n 为竞争线程数 + +**注意：** +- 同一线程不可重复 Lock 同一个 Mutex（会导致死锁）。 +- 建议使用 RAII 封装（如 std::lock_guard）自动管理锁的释放。 + +**示例：** + +```cpp +Threading::Mutex mtx; +int counter = 0; + +void Increment() { + mtx.Lock(); + ++counter; + mtx.Unlock(); +} +``` + +## 相关文档 + +- [Mutex 总览](mutex.md) - 返回类总览 diff --git a/docs/api/threading/threading-mutex.md b/docs/api/threading/mutex/mutex.md similarity index 65% rename from docs/api/threading/threading-mutex.md rename to docs/api/threading/mutex/mutex.md index 713417cc..c1326dc9 100644 --- a/docs/api/threading/threading-mutex.md +++ b/docs/api/threading/mutex/mutex.md @@ -4,6 +4,8 @@ **类型**: `class` +**头文件**: `XCEngine/Threading/Mutex.h` + **描述**: 互斥锁封装类，基于 `std::mutex` 实现，提供线程安全的互斥访问。 ## 概述 @@ -14,9 +16,9 @@ | 方法 | 描述 | |------|------| -| `void Lock()` | 获取锁（阻塞） | -| `void Unlock()` | 释放锁 | -| `bool TryLock()` | 尝试获取锁（非阻塞，成功返回 true） | +| [`Lock`](lock.md) | 获取锁（阻塞） | +| [`Unlock`](unlock.md) | 释放锁 | +| [`TryLock`](trylock.md) | 尝试获取锁（非阻塞，成功返回 true） | ## STL 兼容方法 @@ -46,6 +48,7 @@ void SafeTryIncrement() { ## 相关文档 -- [SpinLock](./threading-spinlock.md) - 自旋锁 -- [ReadWriteLock](./threading-readwritelock.md) - 读写锁 -- [TaskSystem](./threading-task-system.md) - 任务系统 +- [SpinLock](../spinlock/spinlock.md) - 自旋锁 +- [ReadWriteLock](../readwritelock/readwritelock.md) - 读写锁 +- [TaskSystem](../task-system/task-system.md) - 任务系统 +- [../threading/threading.md](../threading.md) - 模块总览 diff --git a/docs/api/threading/mutex/trylock.md b/docs/api/threading/mutex/trylock.md new file mode 100644 index 00000000..8ae80c6a --- /dev/null +++ b/docs/api/threading/mutex/trylock.md @@ -0,0 +1,36 @@ +# Mutex::TryLock + +```cpp +bool TryLock() +``` + +尝试获取互斥锁（非阻塞）。如果锁可用则立即获取并返回 true，否则立即返回 false 而不阻塞。 + +**参数：** 无 + +**返回：** `bool` - 获取成功返回 true，锁不可用返回 false + +**复杂度：** O(1) + +**使用场景：** 适用于需要尝试获取锁但不希望阻塞的场景，如实现无锁算法或避免死锁。 + +**示例：** + +```cpp +Threading::Mutex mtx; +volatile bool updated = false; + +void TryUpdate() { + if (mtx.TryLock()) { + updated = true; + mtx.Unlock(); + printf("Update succeeded\n"); + } else { + printf("Update skipped (lock held)\n"); + } +} +``` + +## 相关文档 + +- [Mutex 总览](mutex.md) - 返回类总览 diff --git a/docs/api/threading/mutex/unlock.md b/docs/api/threading/mutex/unlock.md new file mode 100644 index 00000000..b8c7c6a9 --- /dev/null +++ b/docs/api/threading/mutex/unlock.md @@ -0,0 +1,32 @@ +# Mutex::Unlock + +```cpp +void Unlock() +``` + +释放互斥锁，允许其他等待中的线程获取该锁。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** 必须在持有锁的线程中调用 Unlock。解锁一个未持有的锁将导致未定义行为。 + +**示例：** + +```cpp +Threading::Mutex mtx; +std::vector data; + +void SafePush(int value) { + mtx.Lock(); + data.push_back(value); + mtx.Unlock(); +} +``` + +## 相关文档 + +- [Mutex 总览](mutex.md) - 返回类总览 diff --git a/docs/api/threading/readwritelock/readlock.md b/docs/api/threading/readwritelock/readlock.md new file mode 100644 index 00000000..57a71f5a --- /dev/null +++ b/docs/api/threading/readwritelock/readlock.md @@ -0,0 +1,36 @@ +# ReadWriteLock::ReadLock + +```cpp +void ReadLock() +``` + +获取读锁。如果有写者持有锁或正在等待写锁，当前线程将阻塞，直到所有写者完成。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** 平均 O(1) + +**注意：** +- 多个读者可以同时持有读锁。 +- 写锁具有优先权——正在等待的写者会阻塞新的读者，防止写者饥饿。 +- 读锁不可重入，同一线程不可嵌套持有读锁（会导致死锁）。 + +**示例：** + +```cpp +ReadWriteLock rwLock; +int sharedValue = 0; + +int ReadValue() { + rwLock.ReadLock(); + int value = sharedValue; + rwLock.ReadUnlock(); + return value; +} +``` + +## 相关文档 + +- [ReadWriteLock 总览](readwritelock.md) - 返回类总览 diff --git a/docs/api/threading/readwritelock/readunlock.md b/docs/api/threading/readwritelock/readunlock.md new file mode 100644 index 00000000..7d2f6be2 --- /dev/null +++ b/docs/api/threading/readwritelock/readunlock.md @@ -0,0 +1,33 @@ +# ReadWriteLock::ReadUnlock + +```cpp +void ReadUnlock() +``` + +释放读锁。如果这是最后一个读者，将唤醒等待中的写者。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** 必须与 ReadLock 配对使用，且在持有读锁的线程中调用。 + +**示例：** + +```cpp +ReadWriteLock rwLock; +float sharedData = 0.0f; + +float GetData() { + rwLock.ReadLock(); + float data = sharedData; + rwLock.ReadUnlock(); + return data; +} +``` + +## 相关文档 + +- [ReadWriteLock 总览](readwritelock.md) - 返回类总览 diff --git a/docs/api/threading/threading-readwritelock.md b/docs/api/threading/readwritelock/readwritelock.md similarity index 64% rename from docs/api/threading/threading-readwritelock.md rename to docs/api/threading/readwritelock/readwritelock.md index efdac37f..56f3a4d5 100644 --- a/docs/api/threading/threading-readwritelock.md +++ b/docs/api/threading/readwritelock/readwritelock.md @@ -4,6 +4,8 @@ **类型**: `class` +**头文件**: `XCEngine/Threading/ReadWriteLock.h` + **描述**: 读写锁实现，支持多个并发读取或单一写入，提高读多写少场景的并发性能。 ## 概述 @@ -16,15 +18,15 @@ | 方法 | 描述 | |------|------| -| `void ReadLock()` | 获取读锁（可重入，支持多个并发读者） | -| `void ReadUnlock()` | 释放读锁 | +| [`ReadLock`](readlock.md) | 获取读锁（可重入，支持多个并发读者） | +| [`ReadUnlock`](readunlock.md) | 释放读锁 | ### 写锁 | 方法 | 描述 | |------|------| -| `void WriteLock()` | 获取写锁（独占，阻塞所有读者和写者） | -| `void WriteUnlock()` | 释放写锁 | +| [`WriteLock`](writelock.md) | 获取写锁（独占，阻塞所有读者和写者） | +| [`WriteUnlock`](writeunlock.md) | 释放写锁 | ## 使用示例 @@ -33,10 +35,11 @@ Threading::ReadWriteLock rwLock; Containers::HashMap sharedMap; // 读操作（多个线程可同时读） -void ReadData(const String& key) { +int* ReadData(const String& key) { rwLock.ReadLock(); int* value = sharedMap.Find(key); rwLock.ReadUnlock(); + return value; } // 写操作（独占） @@ -49,5 +52,6 @@ void WriteData(const String& key, int value) { ## 相关文档 -- [Mutex](./threading-mutex.md) - 互斥锁 -- [SpinLock](./threading-spinlock.md) - 自旋锁 +- [Mutex](../mutex/mutex.md) - 互斥锁 +- [SpinLock](../spinlock/spinlock.md) - 自旋锁 +- [../threading/threading.md](../threading.md) - 模块总览 diff --git a/docs/api/threading/readwritelock/writelock.md b/docs/api/threading/readwritelock/writelock.md new file mode 100644 index 00000000..0d2af801 --- /dev/null +++ b/docs/api/threading/readwritelock/writelock.md @@ -0,0 +1,35 @@ +# ReadWriteLock::WriteLock + +```cpp +void WriteLock() +``` + +获取写锁（独占）。如果有读者持有锁或有其他写者正在等待，当前线程将阻塞，直到获得独占访问权。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** 平均 O(1)，写者饥饿时可能 O(n) + +**注意：** +- 写锁为独占访问，持有期间不允许任何读锁或写锁。 +- 写锁具有优先权，会阻塞后续到达的读者。 +- 同一线程不可重复 WriteLock。 + +**示例：** + +```cpp +ReadWriteLock rwLock; +std::vector buffer; + +void Append(int value) { + rwLock.WriteLock(); + buffer.push_back(value); + rwLock.WriteUnlock(); +} +``` + +## 相关文档 + +- [ReadWriteLock 总览](readwritelock.md) - 返回类总览 diff --git a/docs/api/threading/readwritelock/writeunlock.md b/docs/api/threading/readwritelock/writeunlock.md new file mode 100644 index 00000000..778e6fc0 --- /dev/null +++ b/docs/api/threading/readwritelock/writeunlock.md @@ -0,0 +1,32 @@ +# ReadWriteLock::WriteUnlock + +```cpp +void WriteUnlock() +``` + +释放写锁。唤醒所有等待中的读者和下一个写者。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** 必须在持有写锁的线程中调用。 + +**示例：** + +```cpp +ReadWriteLock rwLock; +std::unordered_map cache; + +void UpdateCache(const String& key, int value) { + rwLock.WriteLock(); + cache[key] = value; + rwLock.WriteUnlock(); +} +``` + +## 相关文档 + +- [ReadWriteLock 总览](readwritelock.md) - 返回类总览 diff --git a/docs/api/threading/spinlock/lock.md b/docs/api/threading/spinlock/lock.md new file mode 100644 index 00000000..5917c9d3 --- /dev/null +++ b/docs/api/threading/spinlock/lock.md @@ -0,0 +1,35 @@ +# SpinLock::Lock + +```cpp +void Lock() +``` + +获取自旋锁。如果锁已被其他线程持有，则使用忙等待（spin）持续轮询，直到获取到锁。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** 平均 O(1)，最坏情况取决于竞争程度 + +**注意：** +- 适用于临界区极短（几个 CPU 指令）的场景，避免线程切换开销。 +- 在锁持有时间较长或多核竞争激烈时，会浪费大量 CPU 周期，此时应使用 Mutex。 +- 同一线程不可重复 Lock 同一个 SpinLock。 + +**示例：** + +```cpp +Threading::SpinLock spinLock; +int64_t fastCounter = 0; + +void IncrementFast() { + spinLock.Lock(); + ++fastCounter; + spinLock.Unlock(); +} +``` + +## 相关文档 + +- [SpinLock 总览](spinlock.md) - 返回类总览 diff --git a/docs/api/threading/threading-spinlock.md b/docs/api/threading/spinlock/spinlock.md similarity index 67% rename from docs/api/threading/threading-spinlock.md rename to docs/api/threading/spinlock/spinlock.md index 0e60e429..784f7cda 100644 --- a/docs/api/threading/threading-spinlock.md +++ b/docs/api/threading/spinlock/spinlock.md @@ -4,6 +4,8 @@ **类型**: `class` +**头文件**: `XCEngine/Threading/SpinLock.h` + **描述**: 自旋锁封装类，使用原子操作实现，适用于保护极短的临界区。 ## 概述 @@ -14,9 +16,9 @@ | 方法 | 描述 | |------|------| -| `void Lock()` | 获取锁（忙等待） | -| `void Unlock()` | 释放锁 | -| `bool TryLock()` | 尝试获取锁（非阻塞） | +| [`Lock`](lock.md) | 获取锁（忙等待） | +| [`Unlock`](unlock.md) | 释放锁 | +| [`TryLock`](trylock.md) | 尝试获取锁（非阻塞） | ## 使用示例 @@ -27,7 +29,7 @@ int counter = 0; // 保护极短的临界区 void FastIncrement() { spinLock.Lock(); - ++counter; // 单一操作，无需切换到内核 + ++counter; spinLock.Unlock(); } @@ -42,5 +44,6 @@ void SafeIncrement() { ## 相关文档 -- [Mutex](./threading-mutex.md) - 互斥锁 -- [ReadWriteLock](./threading-readwritelock.md) - 读写锁 +- [Mutex](../mutex/mutex.md) - 互斥锁 +- [ReadWriteLock](../readwritelock/readwritelock.md) - 读写锁 +- [../threading/threading.md](../threading.md) - 模块总览 diff --git a/docs/api/threading/spinlock/trylock.md b/docs/api/threading/spinlock/trylock.md new file mode 100644 index 00000000..f56a41cb --- /dev/null +++ b/docs/api/threading/spinlock/trylock.md @@ -0,0 +1,31 @@ +# SpinLock::TryLock + +```cpp +bool TryLock() +``` + +尝试获取自旋锁（非阻塞）。如果锁可用则立即获取并返回 true，否则立即返回 false。 + +**参数：** 无 + +**返回：** `bool` - 获取成功返回 true，锁不可用返回 false + +**复杂度：** O(1) + +**示例：** + +```cpp +Threading::SpinLock spinLock; +int64_t counter = 0; + +void TryIncrement() { + if (spinLock.TryLock()) { + ++counter; + spinLock.Unlock(); + } +} +``` + +## 相关文档 + +- [SpinLock 总览](spinlock.md) - 返回类总览 diff --git a/docs/api/threading/spinlock/unlock.md b/docs/api/threading/spinlock/unlock.md new file mode 100644 index 00000000..01703dd7 --- /dev/null +++ b/docs/api/threading/spinlock/unlock.md @@ -0,0 +1,32 @@ +# SpinLock::Unlock + +```cpp +void Unlock() +``` + +释放自旋锁，允许其他等待中的线程获取该锁。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** 必须在持有锁的线程中调用 Unlock。 + +**示例：** + +```cpp +Threading::SpinLock spinLock; +int64_t counter = 0; + +void SafeAdd(int64_t value) { + spinLock.Lock(); + counter += value; + spinLock.Unlock(); +} +``` + +## 相关文档 + +- [SpinLock 总览](spinlock.md) - 返回类总览 diff --git a/docs/api/threading/task-group/adddependency.md b/docs/api/threading/task-group/adddependency.md new file mode 100644 index 00000000..94829a4e --- /dev/null +++ b/docs/api/threading/task-group/adddependency.md @@ -0,0 +1,44 @@ +# TaskGroup::AddDependency + +```cpp +void AddDependency(uint64_t taskId, uint64_t dependsOn) +``` + +为任务添加依赖关系。被依赖的任务必须先完成，当前任务才会开始执行。 + +**参数：** +- `taskId` - 任务 ID（需要等待的任务） +- `dependsOn` - 依赖的父任务 ID + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** +- 如果被依赖的任务不存在或已完成，调用无效果。 +- 支持添加多个依赖，但不支持循环依赖。 + +**示例：** + +```cpp +TaskGroup* group = TaskSystem::Get().CreateTaskGroup(); + +uint64_t init = group->AddTask([]() { Initialize(); }); +uint64_t task1 = group->AddTask([]() { Phase1(); }); +uint64_t task2 = group->AddTask([]() { Phase2(); }); +uint64_t cleanup = group->AddTask([]() { Cleanup(); }); + +// task1 和 task2 依赖 init +group->AddDependency(task1, init); +group->AddDependency(task2, init); + +// cleanup 依赖 task1 和 task2 +group->AddDependency(cleanup, task1); +group->AddDependency(cleanup, task2); + +group->Wait(); +``` + +## 相关文档 + +- [TaskGroup 总览](task-group.md) - 返回类总览 diff --git a/docs/api/threading/task-group/addtask.md b/docs/api/threading/task-group/addtask.md new file mode 100644 index 00000000..53dadbeb --- /dev/null +++ b/docs/api/threading/task-group/addtask.md @@ -0,0 +1,60 @@ +# TaskGroup::AddTask + +添加任务到任务组。有两个重载版本。 + +## 重载 1: 添加 ITask 对象 + +```cpp +uint64_t AddTask(std::unique_ptr task) +``` + +将一个已有的 ITask 对象添加到任务组。 + +**参数：** +- `task` - 要添加的 unique_ptr 任务对象 + +**返回：** `uint64_t` - 分配的任务 ID + +**复杂度：** O(1) + +## 重载 2: 添加 lambda 任务 + +```cpp +uint64_t AddTask(Callback&& func, TaskPriority priority = TaskPriority::Normal) +``` + +将一个 lambda 函数包装为任务添加到任务组。 + +**参数：** +- `func` - 要执行的可调用对象 +- `priority` - 任务优先级，默认 TaskPriority::Normal + +**返回：** `uint64_t` - 分配的任务 ID + +**复杂度：** O(1) + +**示例：** + +```cpp +TaskGroup* group = TaskSystem::Get().CreateTaskGroup(); + +// 添加 lambda 任务 +uint64_t id1 = group->AddTask([]() { + printf("Task A running\n"); +}); + +uint64_t id2 = group->AddTask([]() { + printf("Task B running\n"); +}, TaskPriority::High); + +// 添加自定义 ITask +class MyTask : public ITask { +public: + void Execute() override { printf("Custom task\n"); } +}; +uint64_t id3 = group->AddTask(std::make_unique()); +``` + +## 相关文档 + +- [TaskGroup 总览](task-group.md) - 返回类总览 diff --git a/docs/api/threading/task-group/cancel.md b/docs/api/threading/task-group/cancel.md new file mode 100644 index 00000000..5c8038f2 --- /dev/null +++ b/docs/api/threading/task-group/cancel.md @@ -0,0 +1,45 @@ +# TaskGroup::Cancel + +```cpp +void Cancel() +``` + +取消任务组中所有尚未执行的任务。正在执行的任务将不受影响。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** +- 已完成的任务不受影响。 +- 正在执行的任务继续执行直到完成。 +- 调用后所有 Wait/WaitFor 会立即返回。 + +**示例：** + +```cpp +TaskGroup* group = TaskSystem::Get().CreateTaskGroup(); + +for (int i = 0; i < 100; ++i) { + group->AddTask([i]() { + if (ShouldCancel()) { + return; // 检查取消状态 + } + ProcessLongTask(i); + }); +} + +// 如果用户点击取消按钮 +if (userClickedCancel) { + group->Cancel(); + printf("Tasks canceled. Progress: %.1f%%\n", group->GetProgress() * 100.0f); +} + +group->Wait(); +``` + +## 相关文档 + +- [TaskGroup 总览](task-group.md) - 返回类总览 diff --git a/docs/api/threading/task-group/getprogress.md b/docs/api/threading/task-group/getprogress.md new file mode 100644 index 00000000..cfa8b28d --- /dev/null +++ b/docs/api/threading/task-group/getprogress.md @@ -0,0 +1,39 @@ +# TaskGroup::GetProgress + +```cpp +float GetProgress() const +``` + +获取任务组的完成进度。 + +**参数：** 无 + +**返回：** `float` - 进度值，范围 0.0f ~ 1.0f + +**复杂度：** O(1) + +**示例：** + +```cpp +TaskGroup* group = TaskSystem::Get().CreateTaskGroup(); + +for (int i = 0; i < 1000; ++i) { + group->AddTask([i]() { ProcessItem(i); }); +} + +// 显示进度 +while (!group->IsComplete()) { + float progress = group->GetProgress(); + printf("\rLoading: [%-50s] %.1f%%", + std::string(50, '=').substr(0, (int)(progress * 50)).c_str(), + progress * 100.0f); + fflush(stdout); + Thread::Sleep(100); +} +printf("\n"); +``` + +## 相关文档 + +- [TaskGroup 总览](task-group.md) - 返回类总览 +- [IsComplete](iscomplete.md) - 检查是否完成 diff --git a/docs/api/threading/task-group/iscomplete.md b/docs/api/threading/task-group/iscomplete.md new file mode 100644 index 00000000..88df587a --- /dev/null +++ b/docs/api/threading/task-group/iscomplete.md @@ -0,0 +1,34 @@ +# TaskGroup::IsComplete + +```cpp +bool IsComplete() const +``` + +检查任务组中所有任务是否已完成。 + +**参数：** 无 + +**返回：** `bool` - 所有任务完成返回 true，否则返回 false + +**复杂度：** O(1) + +**示例：** + +```cpp +TaskGroup* group = TaskSystem::Get().CreateTaskGroup(); + +for (int i = 0; i < 100; ++i) { + group->AddTask([i]() { HeavyCompute(i); }); +} + +// 非阻塞轮询 +while (!group->IsComplete()) { + printf("Progress: %.1f%%\n", group->GetProgress() * 100.0f); + Thread::Sleep(500); +} +``` + +## 相关文档 + +- [TaskGroup 总览](task-group.md) - 返回类总览 +- [GetProgress](getprogress.md) - 获取完成进度 diff --git a/docs/api/threading/task-group/setcompletecallback.md b/docs/api/threading/task-group/setcompletecallback.md new file mode 100644 index 00000000..45256a46 --- /dev/null +++ b/docs/api/threading/task-group/setcompletecallback.md @@ -0,0 +1,36 @@ +# TaskGroup::SetCompleteCallback + +```cpp +void SetCompleteCallback(Callback&& callback) +``` + +设置任务组完成回调。当所有任务都完成后，回调函数将在某个工作线程中被调用。 + +**参数：** +- `callback` - 完成时要调用的回调函数 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +TaskGroup* group = TaskSystem::Get().CreateTaskGroup(); + +group->AddTask([]() { LoadTextures(); }); +group->AddTask([]() { LoadMeshes(); }); +group->AddTask([]() { LoadAudio(); }); + +group->SetCompleteCallback([]() { + printf("All assets loaded!\n"); + ResourceManager::InitGPUResources(); +}); + +group->Wait(); +TaskSystem::Get().DestroyTaskGroup(group); +``` + +## 相关文档 + +- [TaskGroup 总览](task-group.md) - 返回类总览 diff --git a/docs/api/threading/threading-task-group.md b/docs/api/threading/task-group/task-group.md similarity index 58% rename from docs/api/threading/threading-task-group.md rename to docs/api/threading/task-group/task-group.md index 51abe816..576bd650 100644 --- a/docs/api/threading/threading-task-group.md +++ b/docs/api/threading/task-group/task-group.md @@ -4,6 +4,8 @@ **类型**: `class` +**头文件**: `XCEngine/Threading/TaskGroup.h` + **描述**: 任务组管理类，用于组织多个任务并支持批量等待、进度跟踪和依赖管理。 ## 概述 @@ -23,30 +25,30 @@ | 方法 | 描述 | |------|------| -| `uint64_t AddTask(std::unique_ptr task)` | 添加任务对象 | -| `uint64_t AddTask(Callback&& func, TaskPriority priority = TaskPriority::Normal)` | 添加 lambda 任务 | +| [`AddTask(unique_ptr)`](addtask.md) | 添加任务对象 | +| [`AddTask(callback)`](addtask.md) | 添加 lambda 任务 | ### 依赖管理 | 方法 | 描述 | |------|------| -| `void AddDependency(uint64_t taskId, uint64_t dependsOn)` | 添加任务依赖关系 | +| [`AddDependency`](adddependency.md) | 添加任务依赖关系 | ### 等待 | 方法 | 描述 | |------|------| -| `void Wait()` | 阻塞等待所有任务完成 | -| `bool WaitFor(std::chrono::milliseconds timeout)` | 超时等待 | +| [`Wait`](wait.md) | 阻塞等待所有任务完成 | +| [`WaitFor`](waitfor.md) | 超时等待 | ### 回调和状态 | 方法 | 描述 | |------|------| -| `void SetCompleteCallback(Callback&& callback)` | 设置完成回调 | -| `bool IsComplete() const` | 检查所有任务是否完成 | -| `float GetProgress() const` | 获取完成进度（0.0f ~ 1.0f） | -| `void Cancel()` | 取消所有任务 | +| [`SetCompleteCallback`](setcompletecallback.md) | 设置完成回调 | +| [`IsComplete`](iscomplete.md) | 检查所有任务是否完成 | +| [`GetProgress`](getprogress.md) | 获取完成进度（0.0f ~ 1.0f） | +| [`Cancel`](cancel.md) | 取消所有任务 | ## 使用示例 @@ -69,18 +71,12 @@ group->SetCompleteCallback([]() { // 等待完成 group->Wait(); -// 或者超时等待 -if (group->WaitFor(std::chrono::seconds(5))) { - printf("Completed within 5 seconds\n"); -} else { - printf("Timeout, some tasks did not complete\n"); -} - // 销毁 TaskSystem::Get().DestroyTaskGroup(group); ``` ## 相关文档 -- [ITask](./threading-task.md) - 任务基类 -- [TaskSystem](./threading-task-system.md) - 任务系统 +- [ITask](../task/task.md) - 任务基类 +- [TaskSystem](../task-system/task-system.md) - 任务系统 +- [../threading/threading.md](../threading.md) - 模块总览 diff --git a/docs/api/threading/task-group/wait.md b/docs/api/threading/task-group/wait.md new file mode 100644 index 00000000..9303d1d9 --- /dev/null +++ b/docs/api/threading/task-group/wait.md @@ -0,0 +1,38 @@ +# TaskGroup::Wait + +```cpp +void Wait() +``` + +阻塞当前线程，等待任务组中所有任务完成。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n)，n 为任务数量 + +**注意：** 如果任务组已被取消，此方法将立即返回。 + +**示例：** + +```cpp +TaskGroup* group = TaskSystem::Get().CreateTaskGroup(); + +for (int i = 0; i < 10; ++i) { + group->AddTask([i]() { + printf("Task %d running\n", i); + }); +} + +printf("Waiting for all tasks...\n"); +group->Wait(); +printf("All tasks completed!\n"); + +TaskSystem::Get().DestroyTaskGroup(group); +``` + +## 相关文档 + +- [TaskGroup 总览](task-group.md) - 返回类总览 +- [WaitFor](waitfor.md) - 超时等待 diff --git a/docs/api/threading/task-group/waitfor.md b/docs/api/threading/task-group/waitfor.md new file mode 100644 index 00000000..f64c42f3 --- /dev/null +++ b/docs/api/threading/task-group/waitfor.md @@ -0,0 +1,39 @@ +# TaskGroup::WaitFor + +```cpp +bool WaitFor(std::chrono::milliseconds timeout) +``` + +等待任务组中所有任务完成，可在超时后返回。 + +**参数：** +- `timeout` - 最大等待时间 + +**返回：** `bool` - 所有任务在超时前完成返回 true，超时返回 false + +**复杂度：** O(n) + +**示例：** + +```cpp +TaskGroup* group = TaskSystem::Get().CreateTaskGroup(); + +for (int i = 0; i < 5; ++i) { + group->AddTask([i]() { + Thread::Sleep(i * 100); + printf("Task %d done\n", i); + }); +} + +if (group->WaitFor(std::chrono::seconds(1))) { + printf("All tasks completed within 1 second\n"); +} else { + printf("Timeout! Some tasks still running\n"); + printf("Progress: %.1f%%\n", group->GetProgress() * 100.0f); +} +``` + +## 相关文档 + +- [TaskGroup 总览](task-group.md) - 返回类总览 +- [Wait](wait.md) - 无超时等待 diff --git a/docs/api/threading/task-system/createtaskgroup.md b/docs/api/threading/task-system/createtaskgroup.md new file mode 100644 index 00000000..6232ca43 --- /dev/null +++ b/docs/api/threading/task-system/createtaskgroup.md @@ -0,0 +1,39 @@ +# TaskSystem::CreateTaskGroup + +```cpp +TaskGroup* CreateTaskGroup() +``` + +创建一个任务组用于批量管理多个任务。 + +**参数：** 无 + +**返回：** `TaskGroup*` - 新创建的任务组指针 + +**复杂度：** O(1) + +**注意：** +- 任务组必须通过 DestroyTaskGroup 显式销毁。 +- 任务组的所有权归调用者，TaskSystem 不负责销毁。 + +**示例：** + +```cpp +TaskGroup* group = TaskSystem::Get().CreateTaskGroup(); + +group->AddTask([]() { LoadTextures(); }); +group->AddTask([]() { LoadModels(); }); +group->AddTask([]() { LoadAudio(); }); + +group->SetCompleteCallback([]() { + printf("All resources loaded!\n"); +}); + +group->Wait(); +TaskSystem::Get().DestroyTaskGroup(group); +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 +- [DestroyTaskGroup](destroytaskgroup.md) - 销毁任务组 diff --git a/docs/api/threading/task-system/destroytaskgroup.md b/docs/api/threading/task-system/destroytaskgroup.md new file mode 100644 index 00000000..cc362db0 --- /dev/null +++ b/docs/api/threading/task-system/destroytaskgroup.md @@ -0,0 +1,32 @@ +# TaskSystem::DestroyTaskGroup + +```cpp +void DestroyTaskGroup(TaskGroup* group) +``` + +销毁一个任务组并释放其资源。 + +**参数：** +- `group` - 要销毁的任务组指针 + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** +- 销毁时如果还有未完成的任务，这些任务将被取消。 +- 传入 nullptr 无效果。 + +**示例：** + +```cpp +TaskGroup* group = TaskSystem::Get().CreateTaskGroup(); +// ... 添加任务 ... + +TaskSystem::Get().DestroyTaskGroup(group); +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 +- [CreateTaskGroup](createtaskgroup.md) - 创建任务组 diff --git a/docs/api/threading/task-system/get.md b/docs/api/threading/task-system/get.md new file mode 100644 index 00000000..a6d22f77 --- /dev/null +++ b/docs/api/threading/task-system/get.md @@ -0,0 +1,26 @@ +# TaskSystem::Get + +```cpp +static TaskSystem& Get() +``` + +获取 TaskSystem 单例实例。第一次调用时创建单例。 + +**参数：** 无 + +**返回：** `TaskSystem&` - 单例实例的引用 + +**复杂度：** O(1) + +**线程安全：** 线程安全 + +**示例：** + +```cpp +TaskSystem& system = TaskSystem::Get(); +system.Initialize(config); +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 diff --git a/docs/api/threading/task-system/getworkerthreadcount.md b/docs/api/threading/task-system/getworkerthreadcount.md new file mode 100644 index 00000000..d9ba16f6 --- /dev/null +++ b/docs/api/threading/task-system/getworkerthreadcount.md @@ -0,0 +1,25 @@ +# TaskSystem::GetWorkerThreadCount + +```cpp +uint32_t GetWorkerThreadCount() const +``` + +获取工作线程的数量。 + +**参数：** 无 + +**返回：** `uint32_t` - 工作线程数量 + +**复杂度：** O(1) + +**示例：** + +```cpp +TaskSystem::Get().Initialize(config); +uint32_t count = TaskSystem::Get().GetWorkerThreadCount(); +printf("Worker threads: %u\n", count); +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 diff --git a/docs/api/threading/task-system/initialize.md b/docs/api/threading/task-system/initialize.md new file mode 100644 index 00000000..cf51ca45 --- /dev/null +++ b/docs/api/threading/task-system/initialize.md @@ -0,0 +1,37 @@ +# TaskSystem::Initialize + +```cpp +void Initialize(const TaskSystemConfig& config) +``` + +初始化任务系统，创建工作线程并启动任务调度。 + +**参数：** +- `config` - 任务系统配置（参见 TaskSystemConfig） + +**返回：** 无 + +**复杂度：** O(n)，n 为 workerThreadCount + +**注意：** +- 多次调用将先关闭已有系统再重新初始化。 +- 应在主线程中调用，在任何任务提交之前完成初始化。 + +**示例：** + +```cpp +TaskSystemConfig config; +config.workerThreadCount = std::thread::hardware_concurrency(); +config.enableTaskProfiling = true; +config.stealTasks = true; +config.maxTaskQueueSize = 2048; + +TaskSystem::Get().Initialize(config); +printf("TaskSystem started with %u workers\n", + TaskSystem::Get().GetWorkerThreadCount()); +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 +- [Shutdown](shutdown.md) - 关闭任务系统 diff --git a/docs/api/threading/task-system/parallelfor.md b/docs/api/threading/task-system/parallelfor.md new file mode 100644 index 00000000..589aecc4 --- /dev/null +++ b/docs/api/threading/task-system/parallelfor.md @@ -0,0 +1,46 @@ +# TaskSystem::ParallelFor + +```cpp +template +void ParallelFor(int32_t start, int32_t end, Func&& func) +``` + +并行执行 for 循环。将循环范围划分为多个块，分配给多个工作线程并行处理。 + +**模板参数：** +- `Func` - 可调用对象类型，签名为 `void(int32_t)` + +**参数：** +- `start` - 循环起始索引（包含） +- `end` - 循环结束索引（不包含） +- `func` - 对每个索引执行的函数 + +**返回：** 无 + +**复杂度：** O(n) + +**分区策略：** +- 根据 `std::thread::hardware_concurrency()` 确定线程数。 +- 将范围均分给各线程，每个线程处理连续的块。 + +**示例：** + +```cpp +// 并行处理 10000 个元素 +std::vector data(10000, 0.0f); + +TaskSystem::Get().ParallelFor(0, 10000, [&data](int32_t i) { + data[i] = std::sin(i * 0.01f) * std::cos(i * 0.007f); +}); + +// 并行矩阵乘法 +TaskSystem::Get().ParallelFor(0, N, [&matrix](int32_t row) { + for (int32_t col = 0; col < N; ++col) { + matrix[row * N + col] = Compute(row, col); + } +}); +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 diff --git a/docs/api/threading/task-system/runonmainthread.md b/docs/api/threading/task-system/runonmainthread.md new file mode 100644 index 00000000..5afc1493 --- /dev/null +++ b/docs/api/threading/task-system/runonmainthread.md @@ -0,0 +1,43 @@ +# TaskSystem::RunOnMainThread + +```cpp +void RunOnMainThread(std::function&& func) +``` + +将任务提交到主线程队列。在主线程中调用 Update 时执行。 + +**参数：** +- `func` - 要在主线程执行的函数 + +**返回：** 无 + +**复杂度：** O(1) + +**使用场景：** +- 从工作线程回调需要更新 UI 或访问主线程资源。 +- 避免跨线程数据竞争。 + +**示例：** + +```cpp +// 在工作线程中 +void WorkerThreadCode() { + int result = HeavyCompute(); + + // 将结果发送到主线程更新 UI + TaskSystem::Get().RunOnMainThread([result]() { + UI.UpdateResult(result); + }); +} + +// 在主线程中 +while (running) { + TaskSystem::Get().Update(); // 处理主线程任务 + RenderFrame(); +} +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 +- [Update](update.md) - 处理主线程队列 diff --git a/docs/api/threading/task-system/shutdown.md b/docs/api/threading/task-system/shutdown.md new file mode 100644 index 00000000..6d1d0c45 --- /dev/null +++ b/docs/api/threading/task-system/shutdown.md @@ -0,0 +1,33 @@ +# TaskSystem::Shutdown + +```cpp +void Shutdown() +``` + +关闭任务系统，停止所有工作线程并清理资源。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n) + +**注意：** +- 调用后应等待所有提交的任务执行完毕，或确保不再需要未完成的任务。 +- 关闭后不可再次使用，必须重新 Initialize。 + +**示例：** + +```cpp +TaskSystem::Get().Initialize(config); + +// ... 使用任务系统 ... + +TaskSystem::Get().Shutdown(); +printf("TaskSystem stopped\n"); +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 +- [Initialize](initialize.md) - 初始化任务系统 diff --git a/docs/api/threading/task-system/submit.md b/docs/api/threading/task-system/submit.md new file mode 100644 index 00000000..beafa89f --- /dev/null +++ b/docs/api/threading/task-system/submit.md @@ -0,0 +1,63 @@ +# TaskSystem::Submit + +将任务提交到任务系统调度执行。有两个重载版本。 + +## 重载 1: 提交 ITask 对象 + +```cpp +uint64_t Submit(std::unique_ptr task) +``` + +提交一个 ITask 对象到任务队列。 + +**参数：** +- `task` - 要提交的任务对象 + +**返回：** `uint64_t` - 分配的任务 ID + +**复杂度：** O(log n) + +## 重载 2: 提交 lambda 任务 + +```cpp +uint64_t Submit(std::function&& func, TaskPriority priority = TaskPriority::Normal) +``` + +将可调用对象包装为任务提交。 + +**参数：** +- `func` - 要执行的可调用对象 +- `priority` - 任务优先级，默认 TaskPriority::Normal + +**返回：** `uint64_t` - 分配的任务 ID + +**复杂度：** O(log n) + +**示例：** + +```cpp +// 提交自定义任务 +class MyTask : public ITask { +public: + void Execute() override { printf("MyTask running\n"); } +}; +uint64_t id1 = TaskSystem::Get().Submit(std::make_unique()); + +// 提交 lambda +uint64_t id2 = TaskSystem::Get().Submit([]() { + printf("Lambda task\n"); +}); + +uint64_t id3 = TaskSystem::Get().Submit([]() { + HeavyCompute(); +}, TaskPriority::High); + +// 等待任务完成 +TaskSystem::Get().Wait(id1); +TaskSystem::Get().Wait(id2); +TaskSystem::Get().Wait(id3); +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 diff --git a/docs/api/threading/threading-task-system.md b/docs/api/threading/task-system/task-system.md similarity index 57% rename from docs/api/threading/threading-task-system.md rename to docs/api/threading/task-system/task-system.md index 33053714..ad75c248 100644 --- a/docs/api/threading/threading-task-system.md +++ b/docs/api/threading/task-system/task-system.md @@ -4,6 +4,8 @@ **类型**: `class` (singleton) +**头文件**: `XCEngine/Threading/TaskSystem.h` + **描述**: 并行任务调度系统单例，提供工作窃取式任务队列和并行 for 循环。 ## 概述 @@ -14,7 +16,7 @@ | 方法 | 描述 | |------|------| -| `static TaskSystem& Get()` | 获取单例实例 | +| [`Get`](get.md) | 获取单例实例 | ## 公共方法 @@ -22,47 +24,47 @@ | 方法 | 描述 | |------|------| -| `void Initialize(const TaskSystemConfig& config)` | 初始化任务系统 | -| `void Shutdown()` | 关闭任务系统 | +| [`Initialize`](initialize.md) | 初始化任务系统 | +| [`Shutdown`](shutdown.md) | 关闭任务系统 | ### 任务提交 | 方法 | 描述 | |------|------| -| `uint64_t Submit(std::unique_ptr task)` | 提交任务对象 | -| `uint64_t Submit(std::function&& func, TaskPriority priority = TaskPriority::Normal)` | 提交 lambda 任务 | +| [`Submit(unique_ptr)`](submit.md) | 提交任务对象 | +| [`Submit(callback)`](submit.md) | 提交 lambda 任务 | ### 任务组 | 方法 | 描述 | |------|------| -| `TaskGroup* CreateTaskGroup()` | 创建任务组 | -| `void DestroyTaskGroup(TaskGroup* group)` | 销毁任务组 | +| [`CreateTaskGroup`](createtaskgroup.md) | 创建任务组 | +| [`DestroyTaskGroup`](destroytaskgroup.md) | 销毁任务组 | ### 等待 | 方法 | 描述 | |------|------| -| `void Wait(uint64_t taskId)` | 等待指定任务完成 | +| [`Wait`](wait.md) | 等待指定任务完成 | ### 信息 | 方法 | 描述 | |------|------| -| `uint32_t GetWorkerThreadCount() const` | 获取工作线程数量 | +| [`GetWorkerThreadCount`](getworkerthreadcount.md) | 获取工作线程数量 | ### 并行 for | 方法 | 描述 | |------|------| -| `template void ParallelFor(int32_t start, int32_t end, Func&& func)` | 并行执行 for 循环 | +| [`ParallelFor`](parallelfor.md) | 并行执行 for 循环 | ### 主线程 | 方法 | 描述 | |------|------| -| `void RunOnMainThread(std::function&& func)` | 将任务提交到主线程执行 | -| `void Update()` | 在主线程中处理主线程队列 | +| [`RunOnMainThread`](runonmainthread.md) | 将任务提交到主线程执行 | +| [`Update`](update.md) | 在主线程中处理主线程队列 | ## 使用示例 @@ -83,7 +85,6 @@ TaskSystem::Get().Submit([]() { // 并行 for TaskSystem::Get().ParallelFor(0, 1000, [](int32_t i) { - // 每个 i 独立处理 process(i); }); @@ -95,7 +96,6 @@ TaskSystem::Get().RunOnMainThread([]() { // 主循环中调用 Update while (running) { TaskSystem::Get().Update(); // 处理主线程任务 - // 其他渲染... } // 关闭 @@ -104,7 +104,8 @@ TaskSystem::Get().Shutdown(); ## 相关文档 -- [ITask](./threading-task.md) - 任务基类 -- [LambdaTask](./threading-lambdatask.md) - Lambda 任务 -- [TaskGroup](./threading-task-group.md) - 任务组 -- [TaskSystemConfig](./threading-tasksystemconfig.md) - 配置 +- [ITask](../task/task.md) - 任务基类 +- [LambdaTask](../lambdatask/lambdatask.md) - Lambda 任务 +- [TaskGroup](../task-group/task-group.md) - 任务组 +- [TaskSystemConfig](../tasksystemconfig/tasksystemconfig.md) - 配置 +- [../threading/threading.md](../threading.md) - 模块总览 diff --git a/docs/api/threading/task-system/update.md b/docs/api/threading/task-system/update.md new file mode 100644 index 00000000..adfe429e --- /dev/null +++ b/docs/api/threading/task-system/update.md @@ -0,0 +1,36 @@ +# TaskSystem::Update + +```cpp +void Update() +``` + +在主线程中处理主线程队列。执行所有通过 RunOnMainThread 提交的任务。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n)，n 为队列中待执行任务数 + +**使用场景：** +- 在主循环中调用，确保 RunOnMainThread 提交的任务能够执行。 +- 应在渲染前调用。 + +**示例：** + +```cpp +// 主循环 +while (application.IsRunning()) { + TaskSystem::Get().Update(); // 处理主线程任务 + + // 渲染 + Renderer.BeginFrame(); + RenderScene(); + Renderer.EndFrame(); +} +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 +- [RunOnMainThread](runonmainthread.md) - 提交主线程任务 diff --git a/docs/api/threading/task-system/wait.md b/docs/api/threading/task-system/wait.md new file mode 100644 index 00000000..31673b44 --- /dev/null +++ b/docs/api/threading/task-system/wait.md @@ -0,0 +1,37 @@ +# TaskSystem::Wait + +```cpp +void Wait(uint64_t taskId) +``` + +**注意：** 此方法当前为空实现，不执行任何操作。 + +阻塞当前线程，等待指定任务完成（功能暂未实现）。 + +**参数：** +- `taskId` - 要等待的任务 ID + +**返回：** 无 + +**复杂度：** N/A（空实现） + +**建议：** 建议使用 `TaskGroup::Wait` 代替此方法。 + +**示例：** + +```cpp +uint64_t id = TaskSystem::Get().Submit([]() { + for (int i = 0; i < 1000000; ++i) { + Compute(i); + } +}); + +printf("Waiting for task...\n"); +// 注意：当前实现为空，建议使用 TaskGroup 来等待任务完成 +TaskSystem::Get().Wait(id); +printf("Task completed\n"); +``` + +## 相关文档 + +- [TaskSystem 总览](task-system.md) - 返回类总览 diff --git a/docs/api/threading/task/addref.md b/docs/api/threading/task/addref.md new file mode 100644 index 00000000..114fd61a --- /dev/null +++ b/docs/api/threading/task/addref.md @@ -0,0 +1,27 @@ +# ITask::AddRef + +```cpp +void AddRef() +``` + +增加任务的引用计数。用于延长任务的生命周期，使其不会被自动释放。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +ITask* task = new MyTask(); +task->AddRef(); // 保持引用，不会在 Release 时被删除 +task->SetPriority(TaskPriority::High); +TaskSystem::Get().Submit(std::unique_ptr(task)); +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 +- [Release](release.md) - 释放引用计数 diff --git a/docs/api/threading/task/execute.md b/docs/api/threading/task/execute.md new file mode 100644 index 00000000..476730e6 --- /dev/null +++ b/docs/api/threading/task/execute.md @@ -0,0 +1,43 @@ +# ITask::Execute + +```cpp +virtual void Execute() = 0 +``` + +任务执行逻辑（纯虚方法）。用户必须在派生类中实现此方法以定义任务的具体行为。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** 取决于具体任务实现 + +**注意：** +- 此方法由 TaskSystem 的工作线程调用。 +- 任务执行期间如发生未捕获异常，行为未定义。 + +**示例：** + +```cpp +class ComputeTask : public ITask { +public: + explicit ComputeTask(int n) : m_n(n) {} + + void Execute() override { + int result = 0; + for (int i = 0; i < m_n; ++i) { + result += i; + } + printf("Result: %d\n", result); + } + +private: + int m_n; +}; + +TaskSystem::Get().Submit(std::make_unique(100)); +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 diff --git a/docs/api/threading/task/getid.md b/docs/api/threading/task/getid.md new file mode 100644 index 00000000..8a40ad32 --- /dev/null +++ b/docs/api/threading/task/getid.md @@ -0,0 +1,25 @@ +# ITask::GetId + +```cpp +uint64_t GetId() const +``` + +获取任务的唯一标识符。 + +**参数：** 无 + +**返回：** `uint64_t` - 任务的唯一 ID + +**复杂度：** O(1) + +**示例：** + +```cpp +ITask* task = /* ... */; +uint64_t id = task->GetId(); +printf("Task ID: %llu\n", (unsigned long long)id); +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 diff --git a/docs/api/threading/task/getpriority.md b/docs/api/threading/task/getpriority.md new file mode 100644 index 00000000..c88c0e8a --- /dev/null +++ b/docs/api/threading/task/getpriority.md @@ -0,0 +1,27 @@ +# ITask::GetPriority + +```cpp +TaskPriority GetPriority() const +``` + +获取任务的优先级。 + +**参数：** 无 + +**返回：** `TaskPriority` - 当前任务的优先级 + +**复杂度：** O(1) + +**示例：** + +```cpp +ITask* task = /* ... */; +TaskPriority priority = task->GetPriority(); +if (priority == TaskPriority::Critical) { + printf("Critical task\n"); +} +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 diff --git a/docs/api/threading/task/getstatus.md b/docs/api/threading/task/getstatus.md new file mode 100644 index 00000000..f0ae485e --- /dev/null +++ b/docs/api/threading/task/getstatus.md @@ -0,0 +1,32 @@ +# ITask::GetStatus + +```cpp +TaskStatus GetStatus() const +``` + +获取任务的当前状态。 + +**参数：** 无 + +**返回：** `TaskStatus` - 当前任务状态 + +**复杂度：** O(1) + +**示例：** + +```cpp +ITask* task = /* ... */; +TaskStatus status = task->GetStatus(); +switch (status) { + case TaskStatus::Pending: printf("Pending\n"); break; + case TaskStatus::Scheduled: printf("Scheduled\n"); break; + case TaskStatus::Running: printf("Running\n"); break; + case TaskStatus::Completed: printf("Completed\n"); break; + case TaskStatus::Failed: printf("Failed\n"); break; + case TaskStatus::Canceled: printf("Canceled\n"); break; +} +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 diff --git a/docs/api/threading/task/oncancel.md b/docs/api/threading/task/oncancel.md new file mode 100644 index 00000000..02c7ff10 --- /dev/null +++ b/docs/api/threading/task/oncancel.md @@ -0,0 +1,38 @@ +# ITask::OnCancel + +```cpp +virtual void OnCancel() +``` + +任务取消回调。可在派生类中重写此方法，以在任务被取消时执行清理操作。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** 取决于具体实现 + +**示例：** + +```cpp +class NetworkTask : public ITask { +public: + void Execute() override { + for (int i = 0; i < 100; ++i) { + if (GetStatus() == TaskStatus::Canceled) { + return; + } + SendPacket(i); + } + } + + void OnCancel() override { + CloseConnection(); + printf("Network task canceled\n"); + } +}; +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 diff --git a/docs/api/threading/task/oncomplete.md b/docs/api/threading/task/oncomplete.md new file mode 100644 index 00000000..3191a6ab --- /dev/null +++ b/docs/api/threading/task/oncomplete.md @@ -0,0 +1,39 @@ +# ITask::OnComplete + +```cpp +virtual void OnComplete() +``` + +任务完成回调。可在派生类中重写此方法，以在任务执行完毕后执行清理或后续操作。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** 取决于具体实现 + +**示例：** + +```cpp +class DataLoadTask : public ITask { +public: + explicit DataLoadTask(const String& path) : m_path(path) {} + + void Execute() override { + m_data = LoadFromFile(m_path); + } + + void OnComplete() override { + printf("Data loaded, size: %zu\n", m_data.Size()); + ProcessData(m_data); + } + +private: + String m_path; + Containers::Vector m_data; +}; +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 diff --git a/docs/api/threading/task/release.md b/docs/api/threading/task/release.md new file mode 100644 index 00000000..f06c866b --- /dev/null +++ b/docs/api/threading/task/release.md @@ -0,0 +1,32 @@ +# ITask::Release + +```cpp +void Release() +``` + +减少引用计数。当引用计数归零时，对象会自动 delete 自身。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** +- 任务提交给 TaskSystem 后，TaskSystem 会自动管理引用计数。 +- 当任务完成且无人持有引用时，任务对象将被自动销毁。 +- 不要在任务执行过程中调用 Release。 + +**示例：** + +```cpp +ITask* task = new MyTask(); +task->AddRef(); // 引用计数 = 2 +TaskSystem::Get().Submit(std::unique_ptr(task)); // 引用计数 = 1 +task->Release(); // 引用计数 = 0，任务被 delete +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 +- [AddRef](addref.md) - 增加引用计数 diff --git a/docs/api/threading/task/setid.md b/docs/api/threading/task/setid.md new file mode 100644 index 00000000..adeda81b --- /dev/null +++ b/docs/api/threading/task/setid.md @@ -0,0 +1,28 @@ +# ITask::SetId + +```cpp +void SetId(uint64_t id) +``` + +设置任务的唯一标识符。通常由 TaskSystem 在提交时自动分配。 + +**参数：** +- `id` - 要设置的唯一标识符 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +class MyTask : public ITask { +public: + MyTask() { SetId(GenerateId()); } + void Execute() override { /* ... */ } +}; +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 diff --git a/docs/api/threading/task/setpriority.md b/docs/api/threading/task/setpriority.md new file mode 100644 index 00000000..eb0efde8 --- /dev/null +++ b/docs/api/threading/task/setpriority.md @@ -0,0 +1,28 @@ +# ITask::SetPriority + +```cpp +void SetPriority(TaskPriority priority) +``` + +设置任务的优先级。 + +**参数：** +- `priority` - 新的优先级（参见 TaskPriority 枚举） + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** 任务提交后修改优先级可能不会立即生效，取决于任务系统实现。 + +**示例：** + +```cpp +auto task = std::make_unique(); +task->SetPriority(TaskPriority::High); +TaskSystem::Get().Submit(std::move(task)); +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 diff --git a/docs/api/threading/task/setstatus.md b/docs/api/threading/task/setstatus.md new file mode 100644 index 00000000..d3da1487 --- /dev/null +++ b/docs/api/threading/task/setstatus.md @@ -0,0 +1,35 @@ +# ITask::SetStatus + +```cpp +void SetStatus(TaskStatus status) +``` + +设置任务的当前状态。 + +**参数：** +- `status` - 新的状态（参见 TaskStatus 枚举） + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** 正常情况下由 TaskSystem 管理状态。手动设置状态可能干扰任务系统的正常调度。 + +**示例：** + +```cpp +class ConditionalTask : public ITask { +public: + void Execute() override { + if (someCondition) { + SetStatus(TaskStatus::Failed); + return; + } + // 正常处理 + } +}; +``` + +## 相关文档 + +- [ITask 总览](task.md) - 返回类总览 diff --git a/docs/api/threading/threading-task.md b/docs/api/threading/task/task.md similarity index 60% rename from docs/api/threading/threading-task.md rename to docs/api/threading/task/task.md index cf69f5d5..695876e8 100644 --- a/docs/api/threading/threading-task.md +++ b/docs/api/threading/task/task.md @@ -1,8 +1,10 @@ -# ITask / Task +# ITask **命名空间**: `XCEngine::Threading` -**类型**: `class` (abstract) / `enum` +**类型**: `class` (abstract) + +**头文件**: `XCEngine/Threading/Task.h` **描述**: 任务基类抽象接口和任务状态/优先级枚举定义。 @@ -41,27 +43,27 @@ | 方法 | 描述 | |------|------| -| `virtual void Execute() = 0` | 任务执行逻辑（纯虚） | -| `virtual void OnComplete() {}` | 任务完成回调（可重写） | -| `virtual void OnCancel() {}` | 任务取消回调（可重写） | +| [`Execute`](execute.md) | 任务执行逻辑（纯虚） | +| [`OnComplete`](oncomplete.md) | 任务完成回调（可重写） | +| [`OnCancel`](oncancel.md) | 任务取消回调（可重写） | ### 属性 | 方法 | 描述 | |------|------| -| `TaskPriority GetPriority() const` | 获取优先级 | -| `TaskStatus GetStatus() const` | 获取状态 | -| `uint64_t GetId() const` | 获取任务 ID | -| `void SetId(uint64_t id)` | 设置任务 ID | -| `void SetPriority(TaskPriority priority)` | 设置优先级 | -| `void SetStatus(TaskStatus status)` | 设置状态 | +| [`GetPriority`](getpriority.md) | 获取优先级 | +| [`GetStatus`](getstatus.md) | 获取状态 | +| [`GetId`](getid.md) | 获取任务 ID | +| [`SetId`](setid.md) | 设置任务 ID | +| [`SetPriority`](setpriority.md) | 设置优先级 | +| [`SetStatus`](setstatus.md) | 设置状态 | ### 引用计数 | 方法 | 描述 | |------|------| -| `void AddRef()` | 增加引用计数 | -| `void Release()` | 减少引用计数（自动 delete 引用归零时） | +| [`AddRef`](addref.md) | 增加引用计数 | +| [`Release`](release.md) | 减少引用计数（引用归零时自动 delete） | ## 使用示例 @@ -71,19 +73,17 @@ public: explicit MyTask(int data) : m_data(data) {} void Execute() override { - // 执行任务逻辑 printf("Task executed with data: %d\n", m_data); } void OnComplete() override { - // 任务完成后的清理 + printf("Task completed\n"); } private: int m_data; }; -// 使用 auto task = new MyTask(42); task->SetPriority(TaskPriority::High); TaskSystem::Get().Submit(std::unique_ptr(task)); @@ -91,6 +91,7 @@ TaskSystem::Get().Submit(std::unique_ptr(task)); ## 相关文档 -- [LambdaTask](./threading-lambdatask.md) - Lambda 任务封装 -- [TaskGroup](./threading-task-group.md) - 任务组 -- [TaskSystem](./threading-task-system.md) - 任务系统 +- [LambdaTask](../lambdatask/lambdatask.md) - Lambda 任务封装 +- [TaskGroup](../task-group/task-group.md) - 任务组 +- [TaskSystem](../task-system/task-system.md) - 任务系统 +- [../threading/threading.md](../threading.md) - 模块总览 diff --git a/docs/api/threading/tasksystemconfig/enabletaskprofiling.md b/docs/api/threading/tasksystemconfig/enabletaskprofiling.md new file mode 100644 index 00000000..7d0eb114 --- /dev/null +++ b/docs/api/threading/tasksystemconfig/enabletaskprofiling.md @@ -0,0 +1,27 @@ +# TaskSystemConfig::enableTaskProfiling + +```cpp +bool enableTaskProfiling = true +``` + +是否启用任务性能分析。启用后系统会记录任务的执行时间、等待时间等统计信息，可用于性能调试。 + +**类型：** `bool` + +**默认值：** `true` + +**示例：** + +```cpp +TaskSystemConfig config; +config.workerThreadCount = 4; +config.enableTaskProfiling = true; // 启用分析 + +#ifdef NDEBUG +config.enableTaskProfiling = false; // 发布版本关闭 +#endif +``` + +## 相关文档 + +- [TaskSystemConfig 总览](tasksystemconfig.md) - 返回类总览 diff --git a/docs/api/threading/tasksystemconfig/maxtaskqueuesize.md b/docs/api/threading/tasksystemconfig/maxtaskqueuesize.md new file mode 100644 index 00000000..1d628354 --- /dev/null +++ b/docs/api/threading/tasksystemconfig/maxtaskqueuesize.md @@ -0,0 +1,22 @@ +# TaskSystemConfig::maxTaskQueueSize + +```cpp +uint32_t maxTaskQueueSize = 1024 +``` + +任务队列的最大容量。当队列满时，新提交的任务将阻塞直到有空间。 + +**类型：** `uint32_t` + +**默认值：** `1024` + +**示例：** + +```cpp +TaskSystemConfig config; +config.maxTaskQueueSize = 4096; // 允许更大的队列 +``` + +## 相关文档 + +- [TaskSystemConfig 总览](tasksystemconfig.md) - 返回类总览 diff --git a/docs/api/threading/tasksystemconfig/stealtasks.md b/docs/api/threading/tasksystemconfig/stealtasks.md new file mode 100644 index 00000000..33ba3a3c --- /dev/null +++ b/docs/api/threading/tasksystemconfig/stealtasks.md @@ -0,0 +1,23 @@ +# TaskSystemConfig::stealTasks + +```cpp +bool stealTasks = true +``` + +是否启用工作窃取。当启用时，空闲的工作线程可以从其他繁忙线程的任务队列中窃取任务，提高整体吞吐率。 + +**类型：** `bool` + +**默认值：** `true` + +**示例：** + +```cpp +TaskSystemConfig config; +config.workerThreadCount = 8; +config.stealTasks = true; // 启用工作窃取以获得更好负载均衡 +``` + +## 相关文档 + +- [TaskSystemConfig 总览](tasksystemconfig.md) - 返回类总览 diff --git a/docs/api/threading/tasksystemconfig/tasksystemconfig.md b/docs/api/threading/tasksystemconfig/tasksystemconfig.md new file mode 100644 index 00000000..d7eb1d4b --- /dev/null +++ b/docs/api/threading/tasksystemconfig/tasksystemconfig.md @@ -0,0 +1,36 @@ +# TaskSystemConfig + +**命名空间**: `XCEngine::Threading` + +**类型**: `struct` + +**头文件**: `XCEngine/Threading/TaskSystemConfig.h` + +**描述**: 任务系统配置结构体，用于初始化 TaskSystem 的行为参数。 + +## 结构体成员 + +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| [`workerThreadCount`](workerthreadcount.md) | `uint32_t` | 工作线程数量（0=自动检测 CPU 核心数） | 0 | +| [`enableTaskProfiling`](enabletaskprofiling.md) | `bool` | 启用任务性能分析 | true | +| [`stealTasks`](stealtasks.md) | `bool` | 启用工作窃取（负载均衡） | true | +| [`maxTaskQueueSize`](maxtaskqueuesize.md) | `uint32_t` | 最大任务队列大小 | 1024 | +| [`threadStackSize`](threadstacksize.md) | `uint32_t` | 线程栈大小（0=系统默认） | 0 | + +## 使用示例 + +```cpp +TaskSystemConfig config; +config.workerThreadCount = std::thread::hardware_concurrency(); +config.enableTaskProfiling = true; +config.stealTasks = true; +config.maxTaskQueueSize = 2048; + +TaskSystem::Get().Initialize(config); +``` + +## 相关文档 + +- [TaskSystem](../task-system/task-system.md) - 任务系统 +- [../threading/threading.md](../threading.md) - 模块总览 diff --git a/docs/api/threading/tasksystemconfig/threadstacksize.md b/docs/api/threading/tasksystemconfig/threadstacksize.md new file mode 100644 index 00000000..89404459 --- /dev/null +++ b/docs/api/threading/tasksystemconfig/threadstacksize.md @@ -0,0 +1,26 @@ +# TaskSystemConfig::threadStackSize + +```cpp +uint32_t threadStackSize = 0 +``` + +工作线程的栈大小（字节）。值为 0 时使用系统默认值。 + +**类型：** `uint32_t` + +**默认值：** `0`（使用系统默认） + +**示例：** + +```cpp +TaskSystemConfig config; +config.workerThreadCount = 4; +config.threadStackSize = 1024 * 1024; // 1MB 栈大小 + +TaskSystemConfig defaultConfig; +defaultConfig.threadStackSize = 0; // 使用系统默认 +``` + +## 相关文档 + +- [TaskSystemConfig 总览](tasksystemconfig.md) - 返回类总览 diff --git a/docs/api/threading/tasksystemconfig/workerthreadcount.md b/docs/api/threading/tasksystemconfig/workerthreadcount.md new file mode 100644 index 00000000..169d3318 --- /dev/null +++ b/docs/api/threading/tasksystemconfig/workerthreadcount.md @@ -0,0 +1,25 @@ +# TaskSystemConfig::workerThreadCount + +```cpp +uint32_t workerThreadCount = 0 +``` + +工作线程数量。当值为 0 时，任务系统自动检测 `std::thread::hardware_concurrency()` 并使用该值。 + +**类型：** `uint32_t` + +**默认值：** `0`（自动检测） + +**示例：** + +```cpp +TaskSystemConfig config; +config.workerThreadCount = 4; // 使用 4 个工作线程 + +TaskSystemConfig autoConfig; +autoConfig.workerThreadCount = 0; // 自动检测（推荐） +``` + +## 相关文档 + +- [TaskSystemConfig 总览](tasksystemconfig.md) - 返回类总览 diff --git a/docs/api/threading/thread/detach.md b/docs/api/threading/thread/detach.md new file mode 100644 index 00000000..4372841c --- /dev/null +++ b/docs/api/threading/thread/detach.md @@ -0,0 +1,38 @@ +# Thread::Detach + +```cpp +void Detach() +``` + +分离线程，使其成为后台线程独立运行。分离后，线程的资源将在其终止时自动释放，调用线程不会被阻塞。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**注意：** +- 分离后的线程无法再被 Join 或进行任何同步操作。 +- 确保分离线程的所有资源访问都是线程安全的，因为主线程可能在分离线程结束前退出。 +- 如果 Thread 对象在分离线程结束前被销毁，行为取决于具体实现。 + +**示例：** + +```cpp +Thread background; +background.Start([]() { + printf("Background task running\n"); + for (int i = 0; i < 3; ++i) { + Thread::Sleep(500); + printf("Background: tick %d\n", i); + } +}, "BackgroundThread"); + +background.Detach(); +printf("Main thread continues immediately\n"); +``` + +## 相关文档 + +- [Thread 总览](thread.md) - 返回类总览 diff --git a/docs/api/threading/thread/getcurrentid.md b/docs/api/threading/thread/getcurrentid.md new file mode 100644 index 00000000..6b5cbc2d --- /dev/null +++ b/docs/api/threading/thread/getcurrentid.md @@ -0,0 +1,30 @@ +# Thread::GetCurrentId + +```cpp +static Id GetCurrentId() +``` + +获取当前执行线程的唯一标识符。这是一个静态方法，可以在任何线程上下文中调用。 + +**参数：** 无 + +**返回：** `Thread::Id` - 当前执行线程的唯一标识符 + +**复杂度：** O(1) + +**示例：** + +```cpp +Thread worker; +worker.Start([]() { + printf("Worker thread id: %llu\n", (unsigned long long)Thread::GetCurrentId()); +}, "WorkerThread"); + +printf("Main thread id: %llu\n", (unsigned long long)Thread::GetCurrentId()); +worker.Join(); +``` + +## 相关文档 + +- [Thread 总览](thread.md) - 返回类总览 +- [GetId](getid.md) - 获取 Thread 对象的 ID diff --git a/docs/api/threading/thread/getid.md b/docs/api/threading/thread/getid.md new file mode 100644 index 00000000..033812ab --- /dev/null +++ b/docs/api/threading/thread/getid.md @@ -0,0 +1,30 @@ +# Thread::GetId + +```cpp +Id GetId() const +``` + +获取当前线程对象的唯一标识符。该 ID 在线程启动后有效。 + +**参数：** 无 + +**返回：** `Thread::Id` - 线程的唯一标识符（uint64_t 类型） + +**复杂度：** O(1) + +**注意：** 在调用 Start 之前返回 0。 + +**示例：** + +```cpp +Thread worker; +printf("Before start: id=%llu\n", (unsigned long long)worker.GetId()); +worker.Start([]() {}, "Test"); +printf("After start: id=%llu\n", (unsigned long long)worker.GetId()); +worker.Join(); +``` + +## 相关文档 + +- [Thread 总览](thread.md) - 返回类总览 +- [GetCurrentId](getcurrentid.md) - 获取当前执行线程的 ID diff --git a/docs/api/threading/thread/getname.md b/docs/api/threading/thread/getname.md new file mode 100644 index 00000000..6603fc2e --- /dev/null +++ b/docs/api/threading/thread/getname.md @@ -0,0 +1,28 @@ +# Thread::GetName + +```cpp +const Containers::String& GetName() const +``` + +获取线程的名称。该名称在调用 Start 时设置。 + +**参数：** 无 + +**返回：** `const Containers::String&` - 线程名称的引用 + +**复杂度：** O(1) + +**注意：** 在调用 Start 之前返回空字符串。 + +**示例：** + +```cpp +Thread worker; +worker.Start([]() {}, "ComputeThread"); +printf("Thread name: %s\n", worker.GetName().CStr()); +worker.Join(); +``` + +## 相关文档 + +- [Thread 总览](thread.md) - 返回类总览 diff --git a/docs/api/threading/thread/join.md b/docs/api/threading/thread/join.md new file mode 100644 index 00000000..b0f16c79 --- /dev/null +++ b/docs/api/threading/thread/join.md @@ -0,0 +1,37 @@ +# Thread::Join + +```cpp +void Join() +``` + +等待线程结束并回收其资源。调用线程将被阻塞，直到目标线程完成执行。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n)，n 为目标线程的执行时间 + +**注意：** +- 如果线程已经被分离（Detach）或已经 Join 过，调用此方法将导致未定义行为。 +- 建议在使用完 Thread 对象后始终调用 Join 或 Detach。 + +**示例：** + +```cpp +Thread worker; +worker.Start([]() { + for (int i = 0; i < 5; ++i) { + printf("Working...\n"); + Thread::Sleep(100); + } +}, "WorkerThread"); + +printf("Main thread waiting...\n"); +worker.Join(); +printf("Worker thread finished\n"); +``` + +## 相关文档 + +- [Thread 总览](thread.md) - 返回类总览 diff --git a/docs/api/threading/thread/sleep.md b/docs/api/threading/thread/sleep.md new file mode 100644 index 00000000..9e837dda --- /dev/null +++ b/docs/api/threading/thread/sleep.md @@ -0,0 +1,30 @@ +# Thread::Sleep + +```cpp +static void Sleep(uint32_t milliseconds) +``` + +使当前线程休眠指定的时间。线程在休眠期间不会消耗 CPU 时间。 + +**参数：** +- `milliseconds` - 休眠时间，以毫秒为单位 + +**返回：** 无 + +**复杂度：** 取决于操作系统的调度精度，通常为 O(milliseconds) + +**示例：** + +```cpp +printf("Start\n"); +Thread::Sleep(1000); // 休眠1秒 +printf("After 1 second\n"); + +Thread::Sleep(500); // 再休眠0.5秒 +printf("After 0.5 more seconds\n"); +``` + +## 相关文档 + +- [Thread 总览](thread.md) - 返回类总览 +- [Yield](yield.md) - 让出时间片 diff --git a/docs/api/threading/thread/start.md b/docs/api/threading/thread/start.md new file mode 100644 index 00000000..433cb6d3 --- /dev/null +++ b/docs/api/threading/thread/start.md @@ -0,0 +1,37 @@ +# Thread::Start + +```cpp +template +void Start(Func&& func, const Containers::String& name = "Thread") +``` + +启动线程，执行传入的可调用对象。该方法创建一个新的执行线程，立即开始运行。 + +**参数：** +- `func` - 要在线程中执行的可调用对象（lambda、函数指针、仿函数等） +- `name` - 线程名称，用于调试和日志输出，默认值为 "Thread" + +**返回：** 无 + +**复杂度：** O(1) + +**线程安全：** 该方法不是线程安全的，不应在同一 Thread 对象上并发调用。 + +**示例：** + +```cpp +#include + +Thread worker; +worker.Start([]() { + printf("Worker thread running\n"); + Thread::Sleep(100); + printf("Worker thread done\n"); +}, "WorkerThread"); + +worker.Join(); +``` + +## 相关文档 + +- [Thread 总览](thread.md) - 返回类总览 diff --git a/docs/api/threading/threading-thread.md b/docs/api/threading/thread/thread.md similarity index 62% rename from docs/api/threading/threading-thread.md rename to docs/api/threading/thread/thread.md index c7a6d2b0..86f3a941 100644 --- a/docs/api/threading/threading-thread.md +++ b/docs/api/threading/thread/thread.md @@ -31,24 +31,24 @@ | 方法 | 描述 | |------|------| -| `template void Start(Func&& func, const Containers::String& name = "Thread")` | 启动线程，执行传入的函数 | -| `void Join()` | 等待线程结束 | -| `void Detach()` | 分离线程，使其独立运行 | +| [`Start`](start.md) | 启动线程，执行传入的函数 | +| [`Join`](join.md) | 等待线程结束 | +| [`Detach`](detach.md) | 分离线程，使其独立运行 | ### 属性访问 | 方法 | 描述 | |------|------| -| `Id GetId() const` | 获取线程 ID | -| `const Containers::String& GetName() const` | 获取线程名称 | +| [`GetId`](getid.md) | 获取线程 ID | +| [`GetName`](getname.md) | 获取线程名称 | ### 静态方法 | 方法 | 描述 | |------|------| -| `static Id GetCurrentId()` | 获取当前线程 ID | -| `static void Sleep(uint32_t milliseconds)` | 线程休眠指定毫秒数 | -| `static void Yield()` | 让出当前线程的时间片 | +| [`GetCurrentId`](getcurrentid.md) | 获取当前线程 ID | +| [`Sleep`](sleep.md) | 线程休眠指定毫秒数 | +| [`Yield`](yield.md) | 让出当前线程的时间片 | ## 使用示例 @@ -58,7 +58,6 @@ // 创建并启动线程 Thread thread; thread.Start([]() { - // 线程工作 printf("Worker thread running\n"); }, "WorkerThread"); @@ -73,5 +72,6 @@ auto currentId = Thread::GetCurrentId(); ## 相关文档 -- [Mutex](./threading-mutex.md) - 互斥锁 -- [TaskSystem](./threading-task-system.md) - 任务调度系统 +- [Mutex](../mutex/mutex.md) - 互斥锁 +- [TaskSystem](../task-system/task-system.md) - 任务调度系统 +- [../threading/threading.md](../threading.md) - 模块总览 diff --git a/docs/api/threading/thread/yield.md b/docs/api/threading/thread/yield.md new file mode 100644 index 00000000..9024b9ab --- /dev/null +++ b/docs/api/threading/thread/yield.md @@ -0,0 +1,40 @@ +# Thread::Yield + +```cpp +static void Yield() +``` + +让出当前线程的时间片，允许操作系统调度器将 CPU 时间分配给其他就绪线程。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**使用场景：** +- 在自旋等待某个条件时调用，避免浪费 CPU 周期。 +- 在长时间循环中定期让出时间片，提高其他线程的响应性。 + +**示例：** + +```cpp +volatile bool ready = false; + +Thread worker; +worker.Start([]() { + ready = true; +}, "WorkerThread"); + +// 忙等待，但定期让出时间片 +while (!ready) { + Thread::Yield(); +} + +worker.Join(); +``` + +## 相关文档 + +- [Thread 总览](thread.md) - 返回类总览 +- [Sleep](sleep.md) - 线程休眠 diff --git a/docs/api/threading/threading-tasksystemconfig.md b/docs/api/threading/threading-tasksystemconfig.md deleted file mode 100644 index 555f0d4f..00000000 --- a/docs/api/threading/threading-tasksystemconfig.md +++ /dev/null @@ -1,33 +0,0 @@ -# TaskSystemConfig - -**命名空间**: `XCEngine::Threading` - -**类型**: `struct` - -**描述**: 任务系统配置结构体。 - -## 结构体成员 - -| 成员 | 类型 | 描述 | 默认值 | -|------|------|------|--------| -| `workerThreadCount` | `uint32_t` | 工作线程数量（0=自动检测） | 0 | -| `enableTaskProfiling` | `bool` | 启用任务性能分析 | true | -| `stealTasks` | `bool` | 启用工作窃取 | true | -| `maxTaskQueueSize` | `uint32_t` | 最大任务队列大小 | 1024 | -| `threadStackSize` | `uint32_t` | 线程栈大小（0=默认） | 0 | - -## 使用示例 - -```cpp -TaskSystemConfig config; -config.workerThreadCount = std::thread::hardware_concurrency(); -config.enableTaskProfiling = true; -config.stealTasks = true; -config.maxTaskQueueSize = 2048; - -TaskSystem::Get().Initialize(config); -``` - -## 相关文档 - -- [TaskSystem](./threading-task-system.md) - 任务系统 diff --git a/docs/api/threading/threading-overview.md b/docs/api/threading/threading.md similarity index 65% rename from docs/api/threading/threading-overview.md rename to docs/api/threading/threading.md index b922687a..5abab8e8 100644 --- a/docs/api/threading/threading-overview.md +++ b/docs/api/threading/threading.md @@ -16,25 +16,25 @@ Threading 模块提供了一套完整的多线程编程工具，包括线程封 | 组件 | 文件 | 描述 | |------|------|------| -| [Mutex](./threading-mutex.md) | `Mutex.h` | 互斥锁 | -| [SpinLock](./threading-spinlock.md) | `SpinLock.h` | 自旋锁 | -| [ReadWriteLock](./threading-readwritelock.md) | `ReadWriteLock.h` | 读写锁 | +| [Mutex](mutex/mutex.md) | `Mutex.h` | 互斥锁 | +| [SpinLock](spinlock/spinlock.md) | `SpinLock.h` | 自旋锁 | +| [ReadWriteLock](readwritelock/readwritelock.md) | `ReadWriteLock.h` | 读写锁 | ### 线程 | 组件 | 文件 | 描述 | |------|------|------| -| [Thread](./threading-thread.md) | `Thread.h` | 线程封装类 | +| [Thread](thread/thread.md) | `Thread.h` | 线程封装类 | ### 任务系统 | 组件 | 文件 | 描述 | |------|------|------| -| [ITask](./threading-task.md) | `Task.h` | 任务基类 | -| [LambdaTask](./threading-lambdatask.md) | `LambdaTask.h` | Lambda 任务封装模板 | -| [TaskGroup](./threading-task-group.md) | `TaskGroup.h` | 任务组 | -| [TaskSystem](./threading-task-system.md) | `TaskSystem.h` | 并行任务调度系统 | -| [TaskSystemConfig](./threading-tasksystemconfig.md) | `TaskSystemConfig.h` | 任务系统配置 | +| [ITask](task/task.md) | `Task.h` | 任务基类 | +| [LambdaTask](lambdatask/lambdatask.md) | `LambdaTask.h` | Lambda 任务封装模板 | +| [TaskGroup](task-group/task-group.md) | `TaskGroup.h` | 任务组 | +| [TaskSystem](task-system/task-system.md) | `TaskSystem.h` | 并行任务调度系统 | +| [TaskSystemConfig](tasksystemconfig/tasksystemconfig.md) | `TaskSystemConfig.h` | 任务系统配置 | ## 同步原语对比 @@ -71,4 +71,4 @@ TaskSystem::Get().DestroyTaskGroup(group); ## 相关文档 -- [Memory 模块](../memory/memory-overview.md) - 内存分配器 +- [Memory 模块](../memory/memory.md) - 内存分配器 diff --git a/skills/doc-api-manager/SKILL.md b/skills/doc-api-manager/SKILL.md index 01f29130..fd363876 100644 --- a/skills/doc-api-manager/SKILL.md +++ b/skills/doc-api-manager/SKILL.md @@ -8,33 +8,42 @@ ## 文档层次结构规范 -### 文件命名 +### 目录结构 -文档文件统一命名为 `{module-name}.md`，按子系统组织目录结构： +每个类对应一个文件夹，类文件夹下包含类总览页和方法详情页： ``` docs/api/ -├── index.md # 总索引 -├── math/ # 数学库 -├── containers/ # 容器 -├── memory/ # 内存管理 -├── threading/ # 线程与任务 -├── debug/ # 调试与日志 -├── core/ # 核心基础 -├── rhi/ # RHI 抽象层 -│ ├── d3d12/ # D3D12 后端 -│ └── opengl/ # OpenGL 后端 -└── resources/ # 资源管理 +├── index.md # 总索引 +├── math/ +│ ├── math.md # Math 模块总览 +│ ├── vector3.md # Vector3 类总览 +│ ├── dot.md # Dot 方法详情 +│ ├── cross.md # Cross 方法详情 +│ └── ... +├── containers/ +│ ├── containers.md # Containers 模块总览 +│ ├── array.md # Array 类总览 +│ ├── emplace.md # Emplace 方法详情 +│ ├── push.md # Push 方法详情 +│ └── ... +└── ... ``` -### 文档模板 +**规则：** +- 模块总览页：`{module}/{module}.md`（如 `math/math.md`、`containers/containers.md`） +- 类文件夹：`{class-name}/`（如 `array/`、`vector3/`） +- 类总览页：`{class-name}/{class-name}.md`（如 `array/array.md`） +- 方法详情页：`{class-name}/{method-name}.md`（如 `array/emplace.md`） + +### 类总览页模板 ```markdown -# {类/结构体名称} +# {类名称} **命名空间**: `{namespace}` -**类型**: `{type}` (`class` / `struct` / `class` (abstract) / `class` (template) / `class` (singleton) / `enum` / `struct`) +**类型**: `{type}` **描述**: {一句话功能描述} @@ -42,35 +51,12 @@ docs/api/ {模块功能详细介绍，包括设计目的和使用场景} -## {类型别名/子类型 1}（可选章节） - -{子类型详细说明} - ## 公共方法 -### {方法分组 1} - | 方法 | 描述 | |------|------| -| `{signature}` | {描述} | - -### {方法分组 2} - -| 方法 | 描述 | -|------|------| -| `{signature}` | {描述} | - -## 公共成员（struct/enum 时） - -| 成员 | 类型 | 描述 | -|------|------|------| -| `{name}` | `{type}` | {description} | - -## 枚举值（enum 时） - -| 值 | 描述 | -|----|------| -| `{EnumValue}` | {description} | +| [`Emplace`](./emplace.md) | 原地构造元素 | +| [`Push`](./push.md) | 末尾添加元素 | ## 使用示例 @@ -83,30 +69,64 @@ docs/api/ - [{文档名}](./{filename}.md) - {简短描述} ``` +### 方法详情页模板 + +```markdown +# {类名称}::{方法名} + +```cpp +{完整方法签名} +``` + +{方法详细描述，包括设计目的、使用场景、注意事项} + +**参数：** +- `{param}` - {参数描述} + +**返回：** {返回值描述} + +**异常：** （如有） + +**线程安全：** ✅ / ❌ + +**复杂度：** O(n) + +**示例：** + +```cpp +{可运行的完整示例代码} +``` + +## 相关文档 + +- [{类总览}](./{class}.md) - 返回类总览 +``` + --- ## 必需字段规范 ### 元信息（必须） -- `**命名空间**`: C++ 命名空间，如 `XCEngine::Math`、`XCEngine::RHI` -- `**类型**`: `class`、`struct`、`enum`、`class` (abstract)、`class` (template)、`class` (singleton) +- `**命名空间**`: C++ 命名空间，如 `XCEngine::Math` +- `**类型**`: `class`、`struct`、`enum` 等 - `**描述**`: 一句话功能描述 ### 必需章节 1. **概述** - 模块功能介绍（设计目的、使用场景） -2. **公共方法** - 所有 public 方法按逻辑分组列出 +2. **公共方法** - 表格形式，每个方法链接到详情页 3. **使用示例** - 完整可运行的代码示例 -4. **相关文档** - @see 交叉引用 +4. **相关文档** - 交叉引用 -### 可选章节（按需添加） +### 方法详情页必需章节 -- **类型别名/子类型** - 嵌套类型、结构体成员、枚举值 -- **构造/析构** -- **运算符重载** -- **静态方法** -- **私有成员说明** +1. **方法签名** - 完整 C++ 签名 +2. **详细描述** - 语义、使用场景、注意事项 +3. **参数列表** - 每个参数的含义 +4. **返回值** - 返回值含义 +5. **示例代码** - 可运行的完整示例 +6. **相关文档** - 返回类总览的链接 --- @@ -114,15 +134,14 @@ docs/api/ ### 1. 格式校验 -- [ ] 文档有且只有一个 `#` 一级标题 +- [ ] 文档结构正确：模块有 `{module}/{module}.md`，类有 `{class}/{class}.md` - [ ] 元信息完整：`命名空间`、`类型`、`描述` -- [ ] 每个方法有清晰的分组标题 -- [ ] 代码块使用 ``` 包裹，语言标识正确（`cpp`、`json`） -- [ ] 表格格式正确：`|header|`，有分隔行 `|------|------|` +- [ ] 类总览页的公共方法表格中，每个方法都有对应的详情页 +- [ ] 代码块使用 ``` 包裹，语言标识正确（`cpp`） ### 2. 引用校验 -- [ ] `@see` / `- [xxx](./xxx.md)` 引用的文件存在 +- [ ] 所有 `./{method}.md` 链接指向的文件存在 - [ ] 引用路径使用相对路径 - [ ] 不存在循环引用 @@ -139,189 +158,13 @@ docs/api/ ## 生成流程 -1. **扫描源码**：分析 `engine/include/XCEngine/` 目录下的头文件 +1. **扫描源码**：分析指定目录下的头文件 2. **识别 API**：查找 `class`、`struct`、`enum`、`namespace` 3. **提取信息**：从源码中提取方法签名、成员变量、枚举值、文档注释 -4. **生成文档**：按照上述模板生成 Markdown 文件 -5. **校验输出**：运行校验规则，检查格式和引用 -6. **输出报告**：列出生成的文档和发现的问题 - ---- - -## 各子系统文档清单 - -### Math 模块 - -- [x] math-overview.md -- [x] math-h.md (常量) -- [x] math-vector2.md -- [x] math-vector3.md -- [x] math-vector4.md -- [x] math-matrix3.md -- [x] math-matrix4.md -- [x] math-quaternion.md -- [x] math-transform.md -- [x] math-color.md -- [x] math-plane.md -- [x] math-sphere.md -- [x] math-box.md -- [x] math-bounds.md -- [x] math-aabb.md -- [x] math-frustum.md -- [x] math-ray.md -- [x] math-rect.md - -### Containers 模块 - -- [x] container-overview.md -- [x] container-array.md -- [x] container-string.md -- [x] container-hashmap.md - -### Memory 模块 - -- [x] memory-overview.md -- [x] memory-allocator.md -- [x] memory-linear-allocator.md -- [x] memory-pool-allocator.md -- [x] memory-proxy-allocator.md -- [x] memory-manager.md - -### Threading 模块 - -- [x] threading-overview.md -- [x] threading-thread.md -- [x] threading-mutex.md -- [x] threading-spinlock.md -- [x] threading-readwritelock.md -- [x] threading-task.md -- [x] threading-lambdatask.md -- [x] threading-task-group.md -- [x] threading-task-system.md -- [x] threading-tasksystemconfig.md - -### Debug 模块 - -- [x] debug-overview.md -- [x] debug-logger.md -- [x] debug-ilogsink.md -- [x] debug-consolelogsink.md -- [x] debug-filelogsink.md -- [x] debug-loglevel.md -- [x] debug-logcategory.md -- [x] debug-logentry.md -- [x] debug-profiler.md - -### Core 模块 - -- [x] core-overview.md -- [x] core-types.md -- [x] core-smartptr.md -- [x] core-refcounted.md -- [x] core-event.md -- [x] core-filewriter.md - -### RHI 模块（抽象层） - -- [x] rhi-overview.md -- [x] rhi-device.md -- [x] rhi-factory.md -- [x] rhi-buffer.md -- [x] rhi-texture.md -- [x] rhi-shader.md -- [x] rhi-command-list.md -- [x] rhi-command-queue.md -- [x] rhi-swap-chain.md -- [x] rhi-fence.md -- [x] rhi-pipeline-state.md -- [x] rhi-sampler.md -- [x] rhi-pipeline-layout.md -- [x] rhi-descriptor-pool.md -- [x] rhi-capabilities.md -- [x] rhi-types.md -- [x] rhi-enums.md - -### RHI D3D12 后端 - -- [x] d3d12-overview.md -- [x] d3d12-device.md -- [x] d3d12-buffer.md -- [x] d3d12-texture.md -- [x] d3d12-command-list.md -- [x] d3d12-command-queue.md -- [x] d3d12-swap-chain.md -- [x] d3d12-fence.md -- [x] d3d12-shader.md -- [x] d3d12-pipeline-state.md -- [x] d3d12-sampler.md -- [x] d3d12-root-signature.md -- [x] d3d12-descriptor-heap.md -- [x] d3d12-render-target-view.md -- [x] d3d12-depth-stencil-view.md -- [x] d3d12-shader-resource-view.md -- [x] d3d12-unordered-access-view.md -- [x] d3d12-constant-buffer-view.md -- [x] d3d12-command-allocator.md -- [x] d3d12-query-heap.md -- [x] d3d12-screenshot.md -- [x] d3d12-types.md -- [x] d3d12-enums.md -- [x] d3d12-common.md - -### RHI OpenGL 后端 - -- [x] opengl-overview.md -- [x] opengl-device.md -- [x] opengl-buffer.md -- [x] opengl-texture.md -- [x] opengl-command-list.md -- [x] opengl-command-queue.md -- [x] opengl-swap-chain.md -- [x] opengl-fence.md -- [x] opengl-shader.md -- [x] opengl-pipeline-state.md -- [x] opengl-sampler.md -- [x] opengl-vertex-array.md -- [x] opengl-render-target-view.md -- [x] opengl-depth-stencil-view.md - -### Resources 模块 - -- [x] resources-overview.md -- [x] resources-iresource.md -- [x] resources-resourcehandle.md -- [x] resources-iloader.md -- [x] resources-resourcemanager.md -- [x] resources-resourcecache.md -- [x] resources-asyncloader.md -- [x] resources-dependencygraph.md -- [x] resources-filesystem.md -- [x] resources-resourcetypes.md -- [x] resources-importsettings.md - ---- - -## 输出格式 - -```json -{ - "generated": [ - { - "file": "docs/api/math/math-vector3.md", - "status": "created", - "classes": 1, - "methods": 15 - } - ], - "issues": [ - { - "file": "docs/api/rhi/rhi-overview.md", - "type": "broken_reference", - "message": "../rhi/d3d12/d3d12-device.md 引用了不存在的文件，应为 ../rhi/d3d12/d3d12-overview.md" - } - ] -} -``` +4. **创建结构**：为每个类创建文件夹，生成类总览页和方法详情页 +5. **生成文档**：按照上述模板生成 Markdown 文件 +6. **校验输出**：运行校验规则，检查格式和引用 +7. **输出报告**：列出生成的文档和发现的问题 --- @@ -333,7 +176,7 @@ docs/api/ ``` AI 执行： -1. 扫描 `engine/include/XCEngine/` 源码目录 +1. 扫描指定源码目录 2. 识别所有头文件中的 class/struct/enum 3. 对比现有文档，找出缺失文件和错误引用 4. 生成或修复 Markdown 文档 diff --git a/skills/doc-blueprint-manager/SKILL.md b/skills/doc-blueprint-manager/SKILL.md index e80d50fb..29732b55 100644 --- a/skills/doc-blueprint-manager/SKILL.md +++ b/skills/doc-blueprint-manager/SKILL.md @@ -268,7 +268,7 @@ feature_plan: ## 生成流程 -1. **分析源码**：扫描 `src/` 目录下的代码文件 +1. **分析源码**：扫描指定目录下的代码文件 2. **识别子系统**：根据目录结构或模块注释识别子系统 3. **提取接口**：从代码中提取 public API（函数签名、参数、返回值） 4. **识别依赖**：分析 `import`/`require` 语句确定模块依赖 @@ -280,42 +280,6 @@ feature_plan: --- -## 输出格式 - -```json -{ - "generated": { - "meta": { - "name": "系统名称", - "subsystems": 8, - "modules": 15, - "requirements": 10, - "mvs_solutions": 3 - } - }, - "issues": [ - { - "section": "SYSTEM_STRUCTURE", - "type": "missing_dependency", - "message": "子系统 'Physics' 依赖 'Rendering'，但该子系统不存在" - }, - { - "section": "SYSTEM_STRUCTURE", - "type": "circular_dependency", - "message": "发现循环依赖: Core → Rendering → Core" - } - ], - "warnings": [ - { - "section": "REQUIREMENTS", - "message": "REQ-005 的 acceptance_criteria 为空" - } - ] -} -``` - ---- - ## 使用示例 用户输入： @@ -324,7 +288,7 @@ feature_plan: ``` AI 执行： -1. 扫描源码目录分析代码结构 +1. 扫描指定源码目录分析代码结构 2. 识别子系统（Core、Rendering、Physics、Scripting 等） 3. 提取模块和 public API 4. 生成 `blueprint.md` 文件