104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
|
# AudioSourceComponent
|
|||
|
|
|
|||
|
|
**命名空间**: `XCEngine::Components`
|
|||
|
|
|
|||
|
|
**类型**: `class`
|
|||
|
|
|
|||
|
|
**头文件**: `XCEngine/Components/AudioSourceComponent.h`
|
|||
|
|
|
|||
|
|
**描述**: 音频源组件，负责在 ECS 实体上播放音频。
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
AudioSourceComponent 是 XCEngine ECS 系统中的音频源组件，附加到游戏实体上后可以播放音频片段（AudioClip）。它支持 3D 空间化定位、音量、音调、循环、展开角度、多普勒效应等丰富的音频播放参数。该组件需要与 AudioListenerComponent 配合使用以实现 3D 空间音效。
|
|||
|
|
|
|||
|
|
## 公共方法
|
|||
|
|
|
|||
|
|
| 方法 | 描述 |
|
|||
|
|
|------|------|
|
|||
|
|
| [`AudioSourceComponent`](constructor.md) | 构造函数 |
|
|||
|
|
| [`~AudioSourceComponent`](destructor.md) | 析构函数 |
|
|||
|
|
| [`Play`](play.md) | 开始播放 |
|
|||
|
|
| [`Pause`](pause.md) | 暂停播放 |
|
|||
|
|
| [`Stop`](stop.md) | 停止播放 |
|
|||
|
|
| [`IsPlaying`](is-playing.md) | 检查是否正在播放 |
|
|||
|
|
| [`IsPaused`](is-paused.md) | 检查是否已暂停 |
|
|||
|
|
| [`SetClip`](set-clip.md) | 设置音频片段 |
|
|||
|
|
| [`GetClip`](get-clip.md) | 获取音频片段 |
|
|||
|
|
| [`SetVolume`](set-volume.md) | 设置音量 |
|
|||
|
|
| [`GetVolume`](get-volume.md) | 获取音量 |
|
|||
|
|
| [`SetPitch`](set-pitch.md) | 设置音调 |
|
|||
|
|
| [`GetPitch`](get-pitch.md) | 获取音调 |
|
|||
|
|
| [`SetPan`](set-pan.md) | 设置声像 |
|
|||
|
|
| [`GetPan`](get-pan.md) | 获取声像 |
|
|||
|
|
| [`SetLooping`](set-looping.md) | 设置循环播放 |
|
|||
|
|
| [`IsLooping`](is-looping.md) | 检查循环状态 |
|
|||
|
|
| [`SetSpatialize`](set-spatialize.md) | 设置是否启用空间化 |
|
|||
|
|
| [`IsSpatialize`](is-spatialize.md) | 检查空间化状态 |
|
|||
|
|
| [`Set3DParams`](set-3d-params.md) | 设置 3D 参数 |
|
|||
|
|
| [`Get3DParams`](get-3d-params.md) | 获取 3D 参数 |
|
|||
|
|
| [`SetDopplerLevel`](set-doppler-level.md) | 设置多普勒等级 |
|
|||
|
|
| [`GetDopplerLevel`](get-doppler-level.md) | 获取多普勒等级 |
|
|||
|
|
| [`SetSpread`](set-spread.md) | 设置展开角度 |
|
|||
|
|
| [`GetSpread`](get-spread.md) | 获取展开角度 |
|
|||
|
|
| [`SetReverbZoneMix`](set-reverb-zone-mix.md) | 设置混响区域混合 |
|
|||
|
|
| [`GetReverbZoneMix`](get-reverb-zone-mix.md) | 获取混响区域混合 |
|
|||
|
|
| [`SetOutputMixer`](set-output-mixer.md) | 设置输出混音器 |
|
|||
|
|
| [`GetOutputMixer`](get-output-mixer.md) | 获取输出混音器 |
|
|||
|
|
| [`SetTime`](set-time.md) | 设置播放时间 |
|
|||
|
|
| [`GetTime`](get-time.md) | 获取播放时间 |
|
|||
|
|
| [`GetDuration`](get-duration.md) | 获取音频时长 |
|
|||
|
|
| [`GetEnergy`](get-energy.md) | 获取音频能量 |
|
|||
|
|
| [`StartEnergyDetect`](start-energy-detect.md) | 开始能量检测 |
|
|||
|
|
| [`StopEnergyDetect`](stop-energy-detect.md) | 停止能量检测 |
|
|||
|
|
| [`IsEnergyDetecting`](is-energy-detecting.md) | 检查能量检测状态 |
|
|||
|
|
|
|||
|
|
## 组件方法
|
|||
|
|
|
|||
|
|
| 方法 | 描述 |
|
|||
|
|
|------|------|
|
|||
|
|
| [`Update`](update.md) | 每帧更新 |
|
|||
|
|
| [`OnEnable`](on-enable.md) | 启用时回调 |
|
|||
|
|
| [`OnDisable`](on-disable.md) | 禁用时回调 |
|
|||
|
|
| [`OnDestroy`](on-destroy.md) | 销毁时回调 |
|
|||
|
|
| [`GetName`](get-name.md) | 获取组件名称 |
|
|||
|
|
|
|||
|
|
## 使用示例
|
|||
|
|
|
|||
|
|
```cpp
|
|||
|
|
#include <XCEngine/Components/AudioSourceComponent.h>
|
|||
|
|
#include <XCEngine/Resources/ResourceManager.h>
|
|||
|
|
|
|||
|
|
using namespace XCEngine::Components;
|
|||
|
|
|
|||
|
|
void PlaySoundEffect(Entity entity, const char* soundPath) {
|
|||
|
|
AudioSourceComponent* audioSource = entity.AddComponent<AudioSourceComponent>();
|
|||
|
|
|
|||
|
|
auto clip = Resources::ResourceManager::Get().Load<Resources::AudioClip>(soundPath);
|
|||
|
|
audioSource->SetClip(clip.Get());
|
|||
|
|
audioSource->SetVolume(0.8f);
|
|||
|
|
audioSource->SetLooping(false);
|
|||
|
|
audioSource->SetSpatialize(true);
|
|||
|
|
|
|||
|
|
audioSource->Play();
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
void PlayLoopingMusic(Entity entity, const char* musicPath) {
|
|||
|
|
AudioSourceComponent* audioSource = entity.AddComponent<AudioSourceComponent>();
|
|||
|
|
|
|||
|
|
auto clip = Resources::ResourceManager::Get().Load<Resources::AudioClip>(musicPath);
|
|||
|
|
audioSource->SetClip(clip.Get());
|
|||
|
|
audioSource->SetVolume(0.5f);
|
|||
|
|
audioSource->SetLooping(true);
|
|||
|
|
audioSource->SetSpatialize(false);
|
|||
|
|
|
|||
|
|
audioSource->Play();
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 相关文档
|
|||
|
|
|
|||
|
|
- [Components 模块总览](../components.md) - Components 模块总览
|
|||
|
|
- [AudioListenerComponent](../audio-listener/audio-listener-component.md) - 音频监听器组件
|
|||
|
|
- [AudioSystem 模块](../../audio/audio.md) - 音频系统模块
|