XCEngine/docs/api/resources/resources-audioclip.md

# 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) - 资源管理器