ssdfasd
a1804f4cb0
- resources: 更新 asyncloader, audioclip, mesh-import-settings, texture-loader 文档 - rhi: 更新 opengl render-target-view 文档 - components: 新增 camera-component 全部方法文档 (15个文件)
154 lines
4.5 KiB
Markdown
154 lines
4.5 KiB
Markdown
# AudioClip
|
||
|
||
**命名空间**: `XCEngine::Resources`
|
||
|
||
**类型**: `class`
|
||
|
||
**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h`
|
||
|
||
**描述**: 音频片段资源类，管理音频样本数据、格式信息和播放参数。
|
||
|
||
## 概述
|
||
|
||
`AudioClip` 是 XCEngine 中的音频资源类，继承自 `IResource`。它管理音频的原始样本数据、采样率、通道数、位深度、时长、格式类型和播放参数。
|
||
|
||
## 头文件
|
||
|
||
```cpp
|
||
#include <XCEngine/Resources/AudioClip/AudioClip.h>
|
||
```
|
||
|
||
## 枚举类型
|
||
|
||
### AudioFormat
|
||
|
||
音频格式枚举。
|
||
|
||
| 值 | 描述 |
|
||
|----|------|
|
||
| `Unknown` | 未知格式 |
|
||
| `WAV` | WAV 格式 |
|
||
| `OGG` | OGG Vorbis 格式 |
|
||
| `MP3` | MP3 格式 |
|
||
| `FLAC` | FLAC 无损格式 |
|
||
|
||
### AudioType
|
||
|
||
音频类型枚举。
|
||
|
||
| 值 | 描述 |
|
||
|----|------|
|
||
| `SoundEffect` | 音效 |
|
||
| `Music` | 音乐 |
|
||
| `Voice` | 语音 |
|
||
| `Ambient` | 环境音 |
|
||
|
||
## 公共方法
|
||
|
||
### 构造与析构
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| [AudioClip](constructor.md) | 默认构造函数 |
|
||
| [~AudioClip](destructor.md) | 析构函数 |
|
||
|
||
### 基础属性
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `ResourceType GetType() const` | 返回 `ResourceType::AudioClip` |
|
||
| `const Containers::String& GetName() const` | 获取音频名称 |
|
||
| `const Containers::String& GetPath() const` | 获取音频路径 |
|
||
| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
|
||
| [IsValid](is-valid.md) | 检查音频是否有效 |
|
||
| [GetMemorySize](get-memory-size.md) | 获取内存大小 |
|
||
| [Release](release.md) | 释放音频引用 |
|
||
|
||
### 音频数据
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| [SetAudioData](setaudiodata.md) | 设置音频数据（需先设置采样率、通道数、位深度，自动计算时长） |
|
||
| [GetAudioData](get-audio-data.md) | 获取音频数据指针 |
|
||
|
||
### 音频参数
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| [SetSampleRate](set-sample-rate.md) | 设置采样率（Hz） |
|
||
| [GetSampleRate](get-sample-rate.md) | 获取采样率 |
|
||
| [SetChannels](set-channels.md) | 设置通道数（1=单声道, 2=立体声） |
|
||
| [GetChannels](get-channels.md) | 获取通道数 |
|
||
| [SetBitsPerSample](set-bits-per-sample.md) | 设置位深度（8/16/24/32） |
|
||
| [GetBitsPerSample](get-bits-per-sample.md) | 获取位深度 |
|
||
| [SetDuration](set-duration.md) | 设置时长（秒） |
|
||
| [GetDuration](get-duration.md) | 获取时长（秒） |
|
||
|
||
### 格式与类型
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| [SetAudioFormat](set-audio-format.md) | 设置音频格式 |
|
||
| [GetAudioFormat](get-audio-format.md) | 获取音频格式 |
|
||
| [SetAudioType](set-audio-type.md) | 设置音频类型 |
|
||
| [GetAudioType](get-audio-type.md) | 获取音频类型 |
|
||
|
||
### 3D 和循环
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| [SetIs3D](set-is-3d.md) | 设置是否为 3D 音频 |
|
||
| [Is3D](is-3d.md) | 检查是否为 3D 音频 |
|
||
| [SetLoop](set-loop.md) | 设置是否循环播放 |
|
||
| [IsLoop](is-loop.md) | 检查是否循环播放 |
|
||
|
||
### RHI 资源
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| [GetRHIResource](get-rhi-resource.md) | 获取 RHI 音频缓冲区 |
|
||
| [SetRHIResource](set-rhi-resource.md) | 设置 RHI 音频缓冲区 |
|
||
|
||
## 实现说明
|
||
|
||
**注意**:
|
||
- `AudioLoader::Load()` 加载 WAV 文件时仅设置格式，不解析 WAV 头信息来设置采样率、通道数和位深度。这些字段需要手动设置或通过 `SetAudioData()` 的自动计算（需先设置 `m_sampleRate`、`m_channels`、`m_bitsPerSample`）。
|
||
- `AudioLoader::ParseWAVData()` 为 stub，始终返回 true。
|
||
- `AudioLoader::DetectAudioFormat()` 不检测 AIFF/AIF 格式的文件头，仅依赖扩展名判断。
|
||
|
||
## 使用示例
|
||
|
||
```cpp
|
||
#include <XCEngine/Resources/AudioClip/AudioClip.h>
|
||
#include <XCEngine/Resources/ResourceManager.h>
|
||
|
||
using namespace XCEngine::Resources;
|
||
|
||
// 加载音频
|
||
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](../resource-manager/resource-manager.md) - 资源管理器
|
||
- [Resources 总览](../resources.md) - 返回模块总览
|