docs: Document stub/not-implemented methods in resources module
Fixed discrepancies between source code and documentation: - AsyncLoader: Document Initialize() ignores workerThreadCount, Submit() doesn't do actual async loading, Update() is stub - ResourceManager: Document UnloadUnused() and ReloadResource() are stubs - ResourceCache: Document OnZeroRefCount() and Flush() are stubs - ResourceDependencyGraph: Document TopologicalSort() returns empty (stub) - ResourceFileSystem: Document GetResourceInfo() doesn't fill modifiedTime, EnumerateResources() is stub - FileArchive: Document Enumerate() is stub - ResourcePackageBuilder: Document AddDirectory() is stub - ImportSettings: Document LoadFromJSON/SaveToJSON are stubs - TextureImportSettings/MeshImportSettings: Document JSON methods are stubs - TextureLoader/MeshLoader/MaterialLoader/ShaderLoader/AudioLoader: Document GetDefaultSettings() returns nullptr - AudioLoader: Document ParseWAVData() is stub, Load() doesn't parse WAV headers - ShaderLoader: Document DetectShaderType/ParseShaderSource are stubs - MaterialLoader: Document ParseMaterialData() is stub - Texture: Document Create() mipLevels=0 behavior, GenerateMipmaps() returns false - Mesh: Document MeshLoader::Load() is example only - IResourceLoader: Document GetDefaultSettings() returns nullptr for all loaders
This commit is contained in:
@@ -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` | 与球体相交 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
23
docs/api/math/aabb/getaxis.md
Normal file
23
docs/api/math/aabb/getaxis.md
Normal file
@@ -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 轴
|
||||
```
|
||||
24
docs/api/math/aabb/intersects-obb.md
Normal file
24
docs/api/math/aabb/intersects-obb.md
Normal file
@@ -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)) {
|
||||
// 两个有向包围盒相交
|
||||
}
|
||||
```
|
||||
24
docs/api/math/aabb/intersects-sphere.md
Normal file
24
docs/api/math/aabb/intersects-sphere.md
Normal file
@@ -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 与球体相交
|
||||
}
|
||||
```
|
||||
@@ -16,6 +16,11 @@ struct Box {
|
||||
};
|
||||
```
|
||||
|
||||
**成员：**
|
||||
- `center` - 包围盒中心点
|
||||
- `extents` - 包围盒半长（各轴向的半径）
|
||||
- `transform` - 变换矩阵（用于 OBB 检测）
|
||||
|
||||
**注意：** `Contains` 方法会使用 `transform` 进行真正的 OBB 检测。`Intersects(Box)` 目前使用 AABB 简化算法，未考虑旋转。
|
||||
|
||||
## 构造函数
|
||||
|
||||
@@ -17,6 +17,11 @@ struct Color {
|
||||
};
|
||||
```
|
||||
|
||||
## 构造函数
|
||||
|
||||
- `Color()` - 默认构造，初始化为白色 (1, 1, 1, 1)
|
||||
- `constexpr Color(float r, float g, float b, float a = 1.0f)` - 从 RGBA 分量构造
|
||||
|
||||
## 静态工厂方法
|
||||
|
||||
| 方法 | 返回值 | 描述 |
|
||||
|
||||
@@ -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);
|
||||
```
|
||||
|
||||
@@ -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` | 归一化四元数 |
|
||||
|
||||
## 运算符
|
||||
|
||||
|
||||
@@ -59,9 +59,16 @@
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetAudioData(const Containers::Array<Core::uint8>& data)` | 设置音频数据 |
|
||||
| `void SetAudioData(const Containers::Array<Core::uint8>& data)` | 设置音频数据（根据采样率、通道数、位深度自动计算时长） |
|
||||
| `const Containers::Array<Core::uint8>& GetAudioData() const` | 获取音频数据指针 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**:
|
||||
- `AudioLoader::Load()` 加载 WAV 文件时仅设置格式，不解析 WAV 头信息来设置采样率、通道数和位深度。这些字段需要手动设置或通过 `SetAudioData()` 的自动计算（需先设置 `m_sampleRate`、`m_channels`、`m_bitsPerSample`）。
|
||||
- `AudioLoader::ParseWAVData()` 为 stub，始终返回 true。
|
||||
- `AudioLoader::DetectAudioFormat()` 不检测 AIFF/AIF 格式的文件头，仅依赖扩展名判断。
|
||||
|
||||
### 音频参数
|
||||
|
||||
| 方法 | 描述 |
|
||||
|
||||
@@ -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<Containers::String>& outFiles) const override` | 枚举归档内匹配的文件 |
|
||||
| `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const override` | 枚举归档内匹配的文件（当前为 stub） |
|
||||
| `bool IsValid() const override` | 检查归档是否有效 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: `Enumerate()` 当前为 stub，仅清空输出数组。
|
||||
|
||||
### 访问器
|
||||
|
||||
| 方法 | 描述 |
|
||||
|
||||
@@ -71,8 +71,12 @@
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源信息 |
|
||||
| `void EnumerateResources(const Containers::String& pattern, Containers::Array<ResourceInfo>& outResources) const` | 枚举匹配的资源 |
|
||||
| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源信息（部分字段可能未填充） |
|
||||
| `void EnumerateResources(const Containers::String& pattern, Containers::Array<ResourceInfo>& outResources) const` | 枚举匹配的资源（当前为 stub，仅清空输出） |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: 当前 `GetResourceInfo()` 不填充 `modifiedTime` 字段，`EnumerateResources()` 为 stub 实现。
|
||||
|
||||
## 使用示例
|
||||
|
||||
|
||||
@@ -58,6 +58,10 @@ struct LoadResult {
|
||||
| `static Containers::Array<Core::uint8> ReadFileData(const Containers::String& path)` | 读取文件数据 |
|
||||
| `static Containers::String GetExtension(const Containers::String& path)` | 获取文件扩展名 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: 各资源加载器的 `GetDefaultSettings()` 当前返回 `nullptr`，未返回实际的默认设置对象。
|
||||
|
||||
## 宏
|
||||
|
||||
### REGISTER_RESOURCE_LOADER
|
||||
|
||||
@@ -109,6 +109,10 @@
|
||||
| `void RemoveProperty(const Containers::String& name)` | 移除属性 |
|
||||
| `void ClearAllProperties()` | 清空所有属性 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: `MaterialLoader::ParseMaterialData()` 为 stub，始终返回 true。`MaterialLoader::Load()` 仅为示例实现，未解析材质属性。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
|
||||
@@ -147,3 +147,4 @@ auto sections = mesh->GetSections();
|
||||
- [Material](../material/material.md) - 材质资源
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
- **实现说明**: `MeshLoader::Load()` 仅为示例实现，不解析 FBX/OBJ 等格式的实际网格数据
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -79,6 +79,10 @@ Uniform 变量描述。
|
||||
| `size_t GetMemorySize() const` | 获取内存大小 |
|
||||
| `void Release()` | 释放着色器引用 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: `ShaderLoader::DetectShaderType()` 对于非标准扩展名始终返回 `ShaderType::Fragment`。`ShaderLoader::ParseShaderSource()` 为 stub，始终返回 true。
|
||||
|
||||
### 类型与语言
|
||||
|
||||
| 方法 | 描述 |
|
||||
|
||||
@@ -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 等格式的实际图像数据，仅创建空纹理对象。
|
||||
|
||||
@@ -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));
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -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` 未被更新。
|
||||
|
||||
**示例：**
|
||||
|
||||
|
||||
@@ -4,15 +4,17 @@
|
||||
bool IsComplete() const
|
||||
```
|
||||
|
||||
**注意：** 此方法当前为**空实现/桩代码**。
|
||||
|
||||
检查任务组中所有任务是否已完成。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** `bool` - 所有任务完成返回 true，否则返回 false
|
||||
**返回：** `bool` - 始终返回 `false`（空实现）
|
||||
|
||||
**复杂度：** O(1)
|
||||
**复杂度：** O(1)（空实现）
|
||||
|
||||
**注意：** 由于实现缺陷，`m_pendingCount` 计数器在任务完成后不会递减，因此此方法在所有任务执行完毕后仍会错误地返回 false。
|
||||
**当前状态：** 此方法为空实现，始终返回 `false`，因为 `m_pendingCount` 计数器未正确递减。
|
||||
|
||||
**示例：**
|
||||
|
||||
|
||||
@@ -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);
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user