ssdfasd
7e4c48d4f9
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
140 lines
4.2 KiB
Markdown
140 lines
4.2 KiB
Markdown
# AudioClip
|
||
|
||
**命名空间**: `XCEngine::Resources`
|
||
|
||
**类型**: `class`
|
||
|
||
**描述**: 音频片段资源类，管理音频样本数据、格式信息和播放参数。
|
||
|
||
## 概述
|
||
|
||
`AudioClip` 是 XCEngine 中的音频资源类，继承自 `IResource`。它管理音频的原始样本数据、采样率、通道数、位深度、时长、格式类型和播放参数。
|
||
|
||
## 头文件
|
||
|
||
```cpp
|
||
#include <XCEngine/Resources/AudioClip.h>
|
||
```
|
||
|
||
## 枚举类型
|
||
|
||
### AudioFormat
|
||
|
||
音频格式枚举。
|
||
|
||
| 值 | 描述 |
|
||
|----|------|
|
||
| `Unknown` | 未知格式 |
|
||
| `WAV` | WAV 格式 |
|
||
| `OGG` | OGG Vorbis 格式 |
|
||
| `MP3` | MP3 格式 |
|
||
| `FLAC` | FLAC 无损格式 |
|
||
|
||
### AudioType
|
||
|
||
音频类型枚举。
|
||
|
||
| 值 | 描述 |
|
||
|----|------|
|
||
| `SoundEffect` | 音效 |
|
||
| `Music` | 音乐 |
|
||
| `Voice` | 语音 |
|
||
| `Ambient` | 环境音 |
|
||
|
||
## 公共方法
|
||
|
||
### 基础属性
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `ResourceType GetType() const` | 返回 `ResourceType::AudioClip` |
|
||
| `const Containers::String& GetName() const` | 获取音频名称 |
|
||
| `const Containers::String& GetPath() const` | 获取音频路径 |
|
||
| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
|
||
| `bool IsValid() const` | 检查音频是否有效 |
|
||
| `size_t GetMemorySize() const` | 获取内存大小 |
|
||
| `void Release()` | 释放音频引用 |
|
||
|
||
### 音频数据
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `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 格式的文件头，仅依赖扩展名判断。
|
||
|
||
### 音频参数
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `void SetSampleRate(Core::uint32 rate)` | 设置采样率（Hz） |
|
||
| `Core::uint32 GetSampleRate() const` | 获取采样率 |
|
||
| `void SetChannels(Core::uint32 channels)` | 设置通道数（1=单声道, 2=立体声） |
|
||
| `Core::uint32 GetChannels() const` | 获取通道数 |
|
||
| `void SetBitsPerSample(Core::uint32 bits)` | 设置位深度（8/16/24/32） |
|
||
| `Core::uint32 GetBitsPerSample() const` | 获取位深度 |
|
||
| `void SetDuration(float seconds)` | 设置时长（秒） |
|
||
| `float GetDuration() const` | 获取时长（秒） |
|
||
|
||
### 格式与类型
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `void SetAudioFormat(AudioFormat format)` | 设置音频格式 |
|
||
| `AudioFormat GetAudioFormat() const` | 获取音频格式 |
|
||
| `void SetAudioType(AudioType type)` | 设置音频类型 |
|
||
| `AudioType GetAudioType() const` | 获取音频类型 |
|
||
|
||
### 3D 和循环
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `void SetIs3D(bool is3D)` | 设置是否为 3D 音频 |
|
||
| `bool Is3D() const` | 检查是否为 3D 音频 |
|
||
| `void SetLoop(bool loop)` | 设置是否循环播放 |
|
||
| `bool IsLoop() const` | 检查是否循环播放 |
|
||
|
||
### RHI 资源
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `class IRHIAudioBuffer* GetRHIResource() const` | 获取 RHI 音频缓冲区 |
|
||
| `void SetRHIResource(class IRHIAudioBuffer* resource)` | 设置 RHI 音频缓冲区 |
|
||
|
||
## 使用示例
|
||
|
||
```cpp
|
||
// 加载音频
|
||
ResourceHandle<AudioClip> sfx = ResourceManager::Get().Load<AudioClip>("sounds/explosion.wav");
|
||
ResourceHandle<AudioClip> music = ResourceManager::Get().Load<AudioClip>("music/background.ogg");
|
||
|
||
// 设置参数
|
||
sfx->SetAudioType(AudioType::SoundEffect);
|
||
sfx->SetSampleRate(44100);
|
||
sfx->SetChannels(2);
|
||
sfx->SetBitsPerSample(16);
|
||
sfx->SetDuration(1.5f);
|
||
sfx->SetLoop(false);
|
||
|
||
// 3D 音频
|
||
sfx->SetIs3D(false);
|
||
music->SetIs3D(false);
|
||
|
||
// 获取信息
|
||
uint32_t sampleRate = sfx->GetSampleRate();
|
||
float duration = sfx->GetDuration();
|
||
bool loop = sfx->IsLoop();
|
||
```
|
||
|
||
## 相关文档
|
||
|
||
- [IResource](../iresource/iresource.md) - 资源基类
|
||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||
- [Resources 总览](../resources.md) - 返回模块总览
|