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

docs: Document stub/not-implemented methods in resources module

Browse Source 
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:
ssdfasd
2026-03-19 01:16:12 +08:00
parent 8c719418d0
commit 7e4c48d4f9
21 changed files with 192 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/api/resources/audioclip/audioclip.md
View File

@@ -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 格式的文件头，仅依赖扩展名判断。
### 音频参数
| 方法 | 描述 |

6
docs/api/resources/filearchive/filearchive.md
View File

@@ -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，仅清空输出数组。
### 访问器
| 方法 | 描述 |

8
docs/api/resources/filesystem/filesystem.md
View File

@@ -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 实现。
## 使用示例

4
docs/api/resources/iloader/iloader.md
View File

@@ -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

4
docs/api/resources/material/material.md
View File

@@ -109,6 +109,10 @@
| `void RemoveProperty(const Containers::String& name)` | 移除属性 |
| `void ClearAllProperties()` | 清空所有属性 |
## 实现说明
**注意**: `MaterialLoader::ParseMaterialData()` 为 stub，始终返回 true。`MaterialLoader::Load()` 仅为示例实现，未解析材质属性。
## 使用示例
```cpp

1
docs/api/resources/mesh/mesh.md
View File

@@ -147,3 +147,4 @@ auto sections = mesh->GetSections();
- [Material](../material/material.md) - 材质资源
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
- [Resources 总览](../resources.md) - 返回模块总览
- **实现说明**: `MeshLoader::Load()` 仅为示例实现，不解析 FBX/OBJ 等格式的实际网格数据

6
docs/api/resources/resourcepackage/resourcepackage.md
View File

@@ -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

4
docs/api/resources/shader/shader.md
View File

@@ -79,6 +79,10 @@ Uniform 变量描述。
| `size_t GetMemorySize() const` | 获取内存大小 |
| `void Release()` | 释放着色器引用 |
## 实现说明
**注意**: `ShaderLoader::DetectShaderType()` 对于非标准扩展名始终返回 `ShaderType::Fragment`。`ShaderLoader::ParseShaderSource()` 为 stub，始终返回 true。
### 类型与语言
| 方法 | 描述 |

10
docs/api/resources/texture/texture.md
View File

@@ -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 等格式的实际图像数据，仅创建空纹理对象。