QAudioEngine Class
QAudioEngine 管理三维声场。更多
| 头文件： | #include <QAudioEngine> |
| CMake.QAudioEngine | 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 | 将声音映射到输出设备的扬声器配置。通常是立体声或环绕声扬声器设置。 |
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) |
Notifier 信号：
| 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) |
Notifier 信号：
| 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()
停止发动机。
© 2025 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.
