132 lines
3.6 KiB
Markdown
132 lines
3.6 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` | 获取音频数据指针 |
|
||
|
||
### 音频参数
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `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](./resources-iresource.md) - 资源基类
|
||
- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
|