QAudioEngine Class
QAudioEngine 管理一个三维声场。更多内容...
| 标题： | #include <QAudioEngine> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio) target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake： | QT += spatialaudio |
| 继承自： | QObject |
公共类型
| enum | OutputMode { Surround, Stereo, Headphone } |
属性
|
|
公共函数
| QAudioEngine() | |
| QAudioEngine(QObject *parent) | |
| QAudioEngine(int sampleRate, QObject *parent = nullptr) | |
| virtual | ~QAudioEngine() override |
| float | distanceScale() const |
| float | masterVolume() const |
| QAudioDevice | outputDevice() const |
| QAudioEngine::OutputMode | outputMode() const |
| bool | paused() const |
| bool | roomEffectsEnabled() const |
| int | sampleRate() const |
| void | setDistanceScale(float scale) |
| void | setMasterVolume(float volume) |
| void | setOutputDevice(const QAudioDevice &device) |
| void | setOutputMode(QAudioEngine::OutputMode mode) |
| void | setPaused(bool paused) |
| void | setRoomEffectsEnabled(bool enabled) |
公共槽位
信号
| void | distanceScaleChanged() |
| void | masterVolumeChanged() |
| void | outputDeviceChanged() |
| void | outputModeChanged() |
| void | pausedChanged() |
详细说明
您可以使用 QAudioEngine 的实例来管理三维声场。声场由多个 `QSpatialSound ` 对象定义，这些对象在三维空间的指定位置定义声音。您还可以使用 `QAmbientSound` 添加立体声叠加层。
您可以使用QAudioListener 来定义聆听者相对于声源的位置。聆听者距离声源越远，声源发出的声音就越微弱。此外，根据聆听者与声源之间的方向关系，声音会被映射到相应的扬声器上。
QAudioEngine 提供两种输出模式。第一种模式将声场渲染到一组扬声器上，可以是立体声扬声器对，也可以是环绕声配置。第二种模式在使用耳机时提供身临其境的 3D 音效体验。
声音定位的感知主要由两个因素驱动。第一个因素是声波在左耳和右耳之间的时间差。第二个因素源于来自不同方向的声音在我们的耳朵和头部产生不同类型反射的各种方式。 更多详细信息请参阅https://en.wikipedia.org/wiki/Sound_localization。
空间音频引擎通过头相关传递函数（HRTF，参见https://en.wikipedia.org/wiki/Head-related_transfer_function）模拟这些时间差和反射效应。 所使用的函数模拟了普通人耳朵和头部产生的这些效果。对于大多数人来说，使用耳机时，它能提供良好且身临其境的3D声音定位体验。
该引擎功能相当灵活，允许您定义房间属性及混响设置，以模拟不同类型的房间。
声源还可以被遮挡，从而削弱来自这些声源的声音。
该音频引擎默认采用以厘米为单位的坐标系。其坐标轴与3D中常用的坐标系对齐：x轴正方向指向右侧，y轴正方向指向上方，z轴正方向指向后方。
成员类型文档
enum QAudioEngine::OutputMode
| 常量 | 值 | 描述 |
|---|---|---|
QAudioEngine::Surround | 0 | 将声音映射到输出设备的扬声器配置。这通常是立体声或环绕声扬声器配置。 注意：OutputMode ::Surround 将禁用QAmbientSound |
QAudioEngine::Stereo | 1 | 将声音映射到输出设备的立体声扬声器配置。这将忽略任何额外的扬声器，仅使用左右声道来生成声音场的立体声渲染效果。 |
QAudioEngine::Headphone | 2 | 使用“耳机空间化”功能，在通过耳机聆听声场时创建 3D 音频效果 |
属性文档
distanceScale : float
定义空间音频引擎所使用的坐标系的比例尺。默认情况下，所有单位均为厘米，这与Qt Quick 3D 所使用的默认单位保持一致。
将距离比例设置为 QAudioEngine::DistanceScaleMeter，即可将单位转换为米。
访问函数：
| float | distanceScale() const |
| void | setDistanceScale(float scale) |
通知器信号：
| void | distanceScaleChanged() |
masterVolume : float
设置或返回用于渲染声场的音量。
访问函数：
| float | masterVolume() const |
| void | setMasterVolume(float volume) |
通知信号：
| void | masterVolumeChanged() |
outputDevice : QAudioDevice
设置或返回用于播放声场的设备。
访问函数：
| QAudioDevice | outputDevice() const |
| void | setOutputDevice(const QAudioDevice &device) |
通知信号：
| void | outputDeviceChanged() |
outputMode : OutputMode
设置或获取引擎的当前输出模式。
访问函数：
| QAudioEngine::OutputMode | outputMode() const |
| void | setOutputMode(QAudioEngine::OutputMode mode) |
通知信号：
| void | outputModeChanged() |
另请参阅 QAudioEngine::OutputMode 。
paused : bool
暂停空间音频引擎。
访问函数：
| bool | paused() const |
| void | setPaused(bool paused) |
通知信号：
| void | pausedChanged() |
成员函数文档
QAudioEngine::QAudioEngine()
[explicit] QAudioEngine::QAudioEngine(QObject *parent)
[explicit] QAudioEngine::QAudioEngine(int sampleRate, QObject *parent = nullptr)
使用parent （如有）构建空间音频引擎。
该引擎将以sampleRate 指定的采样率运行。若未提供采样率，默认采样率为44100（44.1kHz）。
未以该采样率提供的音频内容在由引擎处理时，将自动重采样为sampleRate 。在大多数情况下，默认采样率已足够使用；但若您的音频文件大多采用其他采样率录制，则可定义不同的采样率，从而避免因重采样而产生的部分 CPU 开销。
[override virtual noexcept] QAudioEngine::~QAudioEngine()
销毁了空间音频引擎。
[slot] void QAudioEngine::pause()
暂停播放。
[slot] void QAudioEngine::resume()
继续播放。
bool QAudioEngine::roomEffectsEnabled() const
如果房间特效已启用，则返回 true。
另请参阅 ` setRoomEffectsEnabled()`。
int QAudioEngine::sampleRate() const
返回引擎当前配置的采样率。
void QAudioEngine::setRoomEffectsEnabled(bool enabled)
启用回声和混响等房间效果。
当enabled 为true时，启用房间效果。只有在创建了一个或多个QAudioRoom 对象，且听众位于至少一个房间内时，房间效果才会生效。如果听众位于多个房间内，则将使用体积最小的房间。
另请参阅 roomEffectsEnabled()。
[slot] void QAudioEngine::start()
启动发动机。
[slot] void QAudioEngine::stop()
熄火。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
