diff --git a/docs/api/math/aabb/aabb.md b/docs/api/math/aabb/aabb.md index b72251e2..637ef6c1 100644 --- a/docs/api/math/aabb/aabb.md +++ b/docs/api/math/aabb/aabb.md @@ -31,12 +31,12 @@ struct OBB { | 方法 | 返回值 | 描述 | |------|--------|------| -| [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` | 与球体相交 | +| [GetAxis(index)](getaxis.md) | `Vector3` | 获取局部轴（index 必须是 0、1 或 2） | +| [GetMin()](../box/getmin.md) | `Vector3` | 局部空间最小点 | +| [GetMax()](../box/getmax.md) | `Vector3` | 局部空间最大点 | +| [Contains(point)](../box/contains.md) | `bool` | 点是否在 OBB 内 | +| [Intersects(OBB)](intersects-obb.md) | `bool` | 与另一个 OBB 相交 | +| [Intersects(Sphere)](intersects-sphere.md) | `bool` | 与球体相交 | ## 相关文档 diff --git a/docs/api/math/aabb/getaxis.md b/docs/api/math/aabb/getaxis.md new file mode 100644 index 00000000..769e6ec4 --- /dev/null +++ b/docs/api/math/aabb/getaxis.md @@ -0,0 +1,23 @@ +# OBB::GetAxis + +```cpp +Vector3 GetAxis(int index) const +``` + +获取 OBB 的局部坐标轴。 + +**参数：** +- `index` - 轴索引（0=X轴, 1=Y轴, 2=Z轴） + +**返回：** `Vector3` - 对应轴的方向向量 + +**复杂度：** O(1) + +**示例：** + +```cpp +OBB obb = ...; +Vector3 xAxis = obb.GetAxis(0); // 局部 X 轴 +Vector3 yAxis = obb.GetAxis(1); // 局部 Y 轴 +Vector3 zAxis = obb.GetAxis(2); // 局部 Z 轴 +``` diff --git a/docs/api/math/aabb/intersects-obb.md b/docs/api/math/aabb/intersects-obb.md new file mode 100644 index 00000000..feeadb99 --- /dev/null +++ b/docs/api/math/aabb/intersects-obb.md @@ -0,0 +1,24 @@ +# OBB::Intersects (OBB) + +```cpp +bool Intersects(const OBB& other) const +``` + +检测两个 OBB 是否相交（使用 SAT 分离轴定理）。 + +**参数：** +- `other` - 另一个 OBB + +**返回：** `bool` - true 表示相交 + +**复杂度：** O(1) + +**示例：** + +```cpp +OBB obbA = ...; +OBB obbB = ...; +if (obbA.Intersects(obbB)) { + // 两个有向包围盒相交 +} +``` diff --git a/docs/api/math/aabb/intersects-sphere.md b/docs/api/math/aabb/intersects-sphere.md new file mode 100644 index 00000000..13d919a2 --- /dev/null +++ b/docs/api/math/aabb/intersects-sphere.md @@ -0,0 +1,24 @@ +# OBB::Intersects (Sphere) + +```cpp +bool Intersects(const Sphere& sphere) const +``` + +检测 OBB 是否与球体相交。 + +**参数：** +- `sphere` - 要检测的球体 + +**返回：** `bool` - true 表示相交 + +**复杂度：** O(1) + +**示例：** + +```cpp +OBB obb = ...; +Sphere sphere = ...; +if (obb.Intersects(sphere)) { + // OBB 与球体相交 +} +``` diff --git a/docs/api/math/box/box.md b/docs/api/math/box/box.md index 79dd1718..3f6952e2 100644 --- a/docs/api/math/box/box.md +++ b/docs/api/math/box/box.md @@ -16,6 +16,11 @@ struct Box { }; ``` +**成员：** +- `center` - 包围盒中心点 +- `extents` - 包围盒半长（各轴向的半径） +- `transform` - 变换矩阵（用于 OBB 检测） + **注意：** `Contains` 方法会使用 `transform` 进行真正的 OBB 检测。`Intersects(Box)` 目前使用 AABB 简化算法，未考虑旋转。 ## 构造函数 diff --git a/docs/api/math/color/color.md b/docs/api/math/color/color.md index ff46d6c0..de20d2cc 100644 --- a/docs/api/math/color/color.md +++ b/docs/api/math/color/color.md @@ -17,6 +17,11 @@ struct Color { }; ``` +## 构造函数 + +- `Color()` - 默认构造，初始化为白色 (1, 1, 1, 1) +- `constexpr Color(float r, float g, float b, float a = 1.0f)` - 从 RGBA 分量构造 + ## 静态工厂方法 | 方法 | 返回值 | 描述 | diff --git a/docs/api/math/quaternion/normalized.md b/docs/api/math/quaternion/normalized.md index a795631d..db4822bc 100644 --- a/docs/api/math/quaternion/normalized.md +++ b/docs/api/math/quaternion/normalized.md @@ -1,12 +1,34 @@ -# Quaternion::Normalized +# Quaternion::Normalized / Normalize + +## 实例方法 ```cpp Quaternion Normalized() const -Quaternion Normalize(const Quaternion& q) +``` + +返回当前四元数的归一化副本（不修改原四元数）。 + +**返回：** `Quaternion` - 归一化后的四元数副本 + +**复杂度：** O(1) + +**示例：** + +```cpp +Quaternion unit = quat.Normalized(); // quat 保持不变 +``` + +## 静态方法 + +```cpp +static Quaternion Normalize(const Quaternion& q) ``` 归一化四元数。 +**参数：** +- `q` - 要归一化的四元数 + **返回：** `Quaternion` - 归一化后的四元数 **复杂度：** O(1) @@ -14,6 +36,5 @@ Quaternion Normalize(const Quaternion& q) **示例：** ```cpp -Quaternion unit = quat.Normalized(); -Quaternion unit2 = Quaternion::Normalize(quat); +Quaternion unit = Quaternion::Normalize(quat); ``` diff --git a/docs/api/math/quaternion/quaternion.md b/docs/api/math/quaternion/quaternion.md index 96fb64b6..2b2fb1d8 100644 --- a/docs/api/math/quaternion/quaternion.md +++ b/docs/api/math/quaternion/quaternion.md @@ -38,8 +38,13 @@ struct Quaternion { | [Inverse()](inverse.md) | `Quaternion` | 共轭/逆四元数 | | [Dot(other)](dot.md) | `float` | 点积 | | [Magnitude()](magnitude.md) | `float` | 模长 | -| [Normalized()](normalized.md) | `Quaternion` | 归一化 | -| [Normalize(q)](normalized.md) | `Quaternion` | 归一化（静态） | +| [Normalized()](normalized.md) | `Quaternion` | 归一化副本 | + +## 静态方法 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| [Normalize(q)](normalized.md) | `Quaternion` | 归一化四元数 | ## 运算符 diff --git a/docs/api/resources/audioclip/audioclip.md b/docs/api/resources/audioclip/audioclip.md index 5aa7aa65..ada1c2b9 100644 --- a/docs/api/resources/audioclip/audioclip.md +++ b/docs/api/resources/audioclip/audioclip.md @@ -59,9 +59,16 @@ | 方法 | 描述 | |------|------| -| `void SetAudioData(const Containers::Array& data)` | 设置音频数据 | +| `void SetAudioData(const Containers::Array& data)` | 设置音频数据（根据采样率、通道数、位深度自动计算时长） | | `const Containers::Array& GetAudioData() const` | 获取音频数据指针 | +## 实现说明 + +**注意**: +- `AudioLoader::Load()` 加载 WAV 文件时仅设置格式，不解析 WAV 头信息来设置采样率、通道数和位深度。这些字段需要手动设置或通过 `SetAudioData()` 的自动计算（需先设置 `m_sampleRate`、`m_channels`、`m_bitsPerSample`）。 +- `AudioLoader::ParseWAVData()` 为 stub，始终返回 true。 +- `AudioLoader::DetectAudioFormat()` 不检测 AIFF/AIF 格式的文件头，仅依赖扩展名判断。 + ### 音频参数 | 方法 | 描述 | diff --git a/docs/api/resources/filearchive/filearchive.md b/docs/api/resources/filearchive/filearchive.md index b72f9d43..7138ebb5 100644 --- a/docs/api/resources/filearchive/filearchive.md +++ b/docs/api/resources/filearchive/filearchive.md @@ -41,9 +41,13 @@ IArchive | `bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const override` | 从归档中读取文件数据 | | `size_t GetSize(const Containers::String& fileName) const override` | 获取归档内文件大小 | | `bool Exists(const Containers::String& fileName) const override` | 检查文件是否存在于归档中 | -| `void Enumerate(const Containers::String& pattern, Containers::Array& outFiles) const override` | 枚举归档内匹配的文件 | +| `void Enumerate(const Containers::String& pattern, Containers::Array& outFiles) const override` | 枚举归档内匹配的文件（当前为 stub） | | `bool IsValid() const override` | 检查归档是否有效 | +## 实现说明 + +**注意**: `Enumerate()` 当前为 stub，仅清空输出数组。 + ### 访问器 | 方法 | 描述 | diff --git a/docs/api/resources/filesystem/filesystem.md b/docs/api/resources/filesystem/filesystem.md index 6806bdac..eddaeaf6 100644 --- a/docs/api/resources/filesystem/filesystem.md +++ b/docs/api/resources/filesystem/filesystem.md @@ -71,8 +71,12 @@ | 方法 | 描述 | |------|------| -| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源信息 | -| `void EnumerateResources(const Containers::String& pattern, Containers::Array& outResources) const` | 枚举匹配的资源 | +| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源信息（部分字段可能未填充） | +| `void EnumerateResources(const Containers::String& pattern, Containers::Array& outResources) const` | 枚举匹配的资源（当前为 stub，仅清空输出） | + +## 实现说明 + +**注意**: 当前 `GetResourceInfo()` 不填充 `modifiedTime` 字段，`EnumerateResources()` 为 stub 实现。 ## 使用示例 diff --git a/docs/api/resources/iloader/iloader.md b/docs/api/resources/iloader/iloader.md index d1f2880c..f893c998 100644 --- a/docs/api/resources/iloader/iloader.md +++ b/docs/api/resources/iloader/iloader.md @@ -58,6 +58,10 @@ struct LoadResult { | `static Containers::Array ReadFileData(const Containers::String& path)` | 读取文件数据 | | `static Containers::String GetExtension(const Containers::String& path)` | 获取文件扩展名 | +## 实现说明 + +**注意**: 各资源加载器的 `GetDefaultSettings()` 当前返回 `nullptr`，未返回实际的默认设置对象。 + ## 宏 ### REGISTER_RESOURCE_LOADER diff --git a/docs/api/resources/material/material.md b/docs/api/resources/material/material.md index 80bb3391..343992ba 100644 --- a/docs/api/resources/material/material.md +++ b/docs/api/resources/material/material.md @@ -109,6 +109,10 @@ | `void RemoveProperty(const Containers::String& name)` | 移除属性 | | `void ClearAllProperties()` | 清空所有属性 | +## 实现说明 + +**注意**: `MaterialLoader::ParseMaterialData()` 为 stub，始终返回 true。`MaterialLoader::Load()` 仅为示例实现，未解析材质属性。 + ## 使用示例 ```cpp diff --git a/docs/api/resources/mesh/mesh.md b/docs/api/resources/mesh/mesh.md index 1752bada..388275c6 100644 --- a/docs/api/resources/mesh/mesh.md +++ b/docs/api/resources/mesh/mesh.md @@ -147,3 +147,4 @@ auto sections = mesh->GetSections(); - [Material](../material/material.md) - 材质资源 - [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 - [Resources 总览](../resources.md) - 返回模块总览 +- **实现说明**: `MeshLoader::Load()` 仅为示例实现，不解析 FBX/OBJ 等格式的实际网格数据 diff --git a/docs/api/resources/resourcepackage/resourcepackage.md b/docs/api/resources/resourcepackage/resourcepackage.md index 1a68463a..8afc1f88 100644 --- a/docs/api/resources/resourcepackage/resourcepackage.md +++ b/docs/api/resources/resourcepackage/resourcepackage.md @@ -47,13 +47,17 @@ | 方法 | 描述 | |------|------| | `bool AddFile(const Containers::String& sourcePath, const Containers::String& relativePath)` | 添加单个文件到包 | -| `bool AddDirectory(const Containers::String& sourceDir, const Containers::String& relativeBase = "")` | 添加整个目录到包 | +| `bool AddDirectory(const Containers::String& sourceDir, const Containers::String& relativeBase = "")` | 添加整个目录到包（当前为 stub，始终返回 true） | | `void SetOutputPath(const Containers::String& path)` | 设置输出包文件路径 | | `const Containers::String& GetOutputPath() const` | 获取输出路径 | | `bool Build()` | 构建包文件 | | `float GetProgress() const` | 获取构建进度（0.0f ~ 1.0f） | | `const Containers::String& GetError() const` | 获取错误信息 | +## 实现说明 + +**注意**: `ResourcePackageBuilder::AddDirectory()` 当前为 stub，始终返回 true。 + ## 使用示例（构建） ```cpp diff --git a/docs/api/resources/shader/shader.md b/docs/api/resources/shader/shader.md index 82acf222..6caf6b55 100644 --- a/docs/api/resources/shader/shader.md +++ b/docs/api/resources/shader/shader.md @@ -79,6 +79,10 @@ Uniform 变量描述。 | `size_t GetMemorySize() const` | 获取内存大小 | | `void Release()` | 释放着色器引用 | +## 实现说明 + +**注意**: `ShaderLoader::DetectShaderType()` 对于非标准扩展名始终返回 `ShaderType::Fragment`。`ShaderLoader::ParseShaderSource()` 为 stub，始终返回 true。 + ### 类型与语言 | 方法 | 描述 | diff --git a/docs/api/resources/texture/texture.md b/docs/api/resources/texture/texture.md index 5582e945..1c8fa988 100644 --- a/docs/api/resources/texture/texture.md +++ b/docs/api/resources/texture/texture.md @@ -116,7 +116,11 @@ | 方法 | 描述 | |------|------| | `bool Create(Core::uint32 width, Core::uint32 height, Core::uint32 depth, Core::uint32 mipLevels, TextureType type, TextureFormat format, const void* data, size_t dataSize)` | 创建纹理 | -| `bool GenerateMipmaps()` | 生成 Mipmap | +| `bool GenerateMipmaps()` | 生成 Mipmap（当前返回 false - stub） | + +## 实现说明 + +**注意**: `Create()` 方法中 `mipLevels` 参数为 0 时不会自动计算所有级别。`GenerateMipmaps()` 当前返回 false，为 stub 实现。 ## 使用示例 @@ -151,3 +155,7 @@ uint32_t h = tex.GetHeight(); - [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 - [RHITexture](../../rhi/texture/texture.md) - RHI 纹理接口 - [Resources 总览](../resources.md) - 返回模块总览 + +## 实现说明 + +**注意**: `TextureLoader::Load()` 仅为示例实现，不解析 PNG/JPG 等格式的实际图像数据，仅创建空纹理对象。 diff --git a/docs/api/threading/task-group/cancel.md b/docs/api/threading/task-group/cancel.md index 1d0ed472..a7a55daa 100644 --- a/docs/api/threading/task-group/cancel.md +++ b/docs/api/threading/task-group/cancel.md @@ -4,19 +4,17 @@ void Cancel() ``` +**注意：** 此方法为**部分实现**，存在已知问题。 + 取消任务组中所有尚未执行的任务。正在执行的任务将不受影响。 **参数：** 无 **返回：** 无 -**复杂度：** O(1) +**复杂度：** O(n) -**注意：** -- 已完成的任务不受影响。 -- 正在执行的任务继续执行直到完成。 -- 调用后所有 Wait/WaitFor 会立即返回（但请参见下方警告）。 -- **警告**：`Cancel()` 调用 `OnCancel()` 后不会减少待完成任务数，因此如果任务组中还有未执行的任务，调用 `Wait()` 会导致永久阻塞。建议在 `Cancel()` 后使用 `IsComplete()` 轮询或使用带超时的 `WaitFor()`。 +**当前状态：** 此方法会调用各任务的 `OnCancel()` 回调，但不会减少 `m_pendingCount` 计数器。因此调用 `Wait()` 会导致永久阻塞。建议在 `Cancel()` 后使用 `IsComplete()` 轮询或使用带超时的 `WaitFor()`。 **示例：** @@ -38,7 +36,8 @@ if (userClickedCancel) { printf("Tasks canceled. Progress: %.1f%%\n", group->GetProgress() * 100.0f); } -group->Wait(); +// 注意：Cancel() 后 Wait() 会永久阻塞，应使用 WaitFor() +group->WaitFor(std::chrono::seconds(1)); ``` ## 相关文档 diff --git a/docs/api/threading/task-group/getprogress.md b/docs/api/threading/task-group/getprogress.md index aa2a181e..bf695466 100644 --- a/docs/api/threading/task-group/getprogress.md +++ b/docs/api/threading/task-group/getprogress.md @@ -4,15 +4,17 @@ float GetProgress() const ``` +**注意：** 此方法当前为**空实现/桩代码**。 + 获取任务组的完成进度。 **参数：** 无 -**返回：** `float` - 进度值，范围 0.0f ~ 1.0f +**返回：** `float` - 始终返回 `0.0f`（任务组为空时返回 `1.0f`） **复杂度：** O(1) -**注意：** 当前实现中 `m_completedCount` 未被更新，此方法始终返回 0.0f（任务组为空时返回 1.0f）。此为实现限制，文档仅作记录。 +**当前状态：** 此方法为空实现，始终返回 `0.0f`，因为 `m_completedCount` 未被更新。 **示例：** diff --git a/docs/api/threading/task-group/iscomplete.md b/docs/api/threading/task-group/iscomplete.md index 8d4b42a8..9c8d0eab 100644 --- a/docs/api/threading/task-group/iscomplete.md +++ b/docs/api/threading/task-group/iscomplete.md @@ -4,15 +4,17 @@ bool IsComplete() const ``` +**注意：** 此方法当前为**空实现/桩代码**。 + 检查任务组中所有任务是否已完成。 **参数：** 无 -**返回：** `bool` - 所有任务完成返回 true，否则返回 false +**返回：** `bool` - 始终返回 `false`（空实现） -**复杂度：** O(1) +**复杂度：** O(1)（空实现） -**注意：** 由于实现缺陷，`m_pendingCount` 计数器在任务完成后不会递减，因此此方法在所有任务执行完毕后仍会错误地返回 false。 +**当前状态：** 此方法为空实现，始终返回 `false`，因为 `m_pendingCount` 计数器未正确递减。 **示例：** diff --git a/docs/api/threading/task-group/wait.md b/docs/api/threading/task-group/wait.md index 7c94e5bc..0d8765e2 100644 --- a/docs/api/threading/task-group/wait.md +++ b/docs/api/threading/task-group/wait.md @@ -4,18 +4,19 @@ void Wait() ``` +**注意：** 此方法当前为**空实现/桩代码**，不执行任何操作。 + 阻塞当前线程，等待任务组中所有任务完成。 **参数：** 无 **返回：** 无 -**复杂度：** O(n)，n 为任务数量 +**复杂度：** N/A（空实现） -**注意：** -- 如果任务组已被取消，此方法将立即返回。 -- **警告**：由于实现缺陷，`m_pendingCount` 计数器在任务完成后不会递减，导致 `Wait()` 在所有任务执行完毕后仍会永久阻塞。这是当前实现的已知问题。 -- 建议使用 `WaitFor()` 代替以避免永久阻塞。 +**当前状态：** 此方法为空实现，不执行任何操作。由于 `m_pendingCount` 计数器未正确更新，此方法永远无法正常运作。 + +**建议：** 使用 `WaitFor()` 代替以避免永久阻塞。 **示例：** @@ -29,8 +30,12 @@ for (int i = 0; i < 10; ++i) { } printf("Waiting for all tasks...\n"); -group->Wait(); -printf("All tasks completed!\n"); +// 注意：Wait() 为空实现，建议使用 WaitFor() +if (group->WaitFor(std::chrono::seconds(5))) { + printf("All tasks completed within 5 seconds\n"); +} else { + printf("Timeout! Tasks may not have completed\n"); +} TaskSystem::Get().DestroyTaskGroup(group); ```