QAudioEngine Class

QAudioEngine manages a three dimensional sound field. 更多...

头: #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 ()
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 pause ()
void resume ()
void start ()
void stop ()

信号

void distanceScaleChanged ()
void masterVolumeChanged ()
void outputDeviceChanged ()
void outputModeChanged ()
void pausedChanged ()

详细描述

You can use an instance of QAudioEngine to manage a sound field in three dimensions. A sound field is defined by several QSpatialSound objects that define a sound at a specified location in 3D space. You can also add stereo overlays using QAmbientSound .

可以使用 QAudioListener to define the position of the person listening to the sound field relative to the sound sources. Sound sources will be less audible if the listener is further away from source. They will also get mapped to the corresponding loudspeakers depending on the direction between listener and source.

QAudioEngine offers two output modes. The first mode renders the sound field to a set of speakers, either a stereo speaker pair or a surround configuration. The second mode provides an immersive 3D sound experience when using headphones.

Perception of sound localization is driven mainly by two factors. The first factor is timing differences of the sound waves between left and right ear. The second factor comes from various ways how sounds coming from different direcations create different types of reflections from our ears and heads. See https://en.wikipedia.org/wiki/Sound_localization for more details.

The spatial audio engine emulates those timing differences and reflections through Head related transfer functions (HRTF, see https://en.wikipedia.org/wiki/Head-related_transfer_function). The functions used emulates those effects for an average persons ears and head. It provides a good and immersive 3D sound localization experience for most persons when using headphones.

The engine is rather versatile allowing you to define room properties and reverb settings to emulate different types of rooms.

Sound sources can also be occluded dampening the sound coming from those sources.

The audio engine uses a coordinate system that is in centimeters by default. The axes are aligned with the typical coordinate system used in 3D. Positive x points to the right, positive y points up and positive z points backwards.

成员类型文档编制

enum QAudioEngine:: OutputMode

常量 描述
QAudioEngine::Surround 0 Map the sounds to the loudspeaker configuration of the output device. This is normally a stereo or surround speaker setup.
QAudioEngine::Stereo 1 Map the sounds to the stereo loudspeaker configuration of the output device. This will ignore any additional speakers and only use the left and right channels to create a stero rendering of the sound field.
QAudioEngine::Headphone 2 Use Headphone spatialization to create a 3D audio effect when listening to the sound field through headphones

特性文档编制

distanceScale : float

Defines the scale of the coordinate system being used by the spatial audio engine. By default, all units are in centimeters, in line with the default units being used by Qt Quick 3D.

Set the distance scale to QAudioEngine::DistanceScaleMeter to get units in meters.

访问函数:

float distanceScale () const
void setDistanceScale (float scale )

通知程序信号:

void distanceScaleChanged ()

masterVolume : float

Sets or returns volume being used to render the sound field.

访问函数:

float masterVolume () const
void setMasterVolume (float volume )

通知程序信号:

void masterVolumeChanged ()

outputDevice : QAudioDevice

Sets or returns the device that is being used for playing the sound field.

访问函数:

QAudioDevice outputDevice () const
void setOutputDevice (const QAudioDevice & device )

通知程序信号:

void outputDeviceChanged ()

outputMode : OutputMode

Sets or retrieves the current output mode of the engine.

访问函数:

QAudioEngine::OutputMode outputMode () const
void setOutputMode (QAudioEngine::OutputMode mode )

通知程序信号:

void outputModeChanged ()

另请参阅 QAudioEngine::OutputMode .

paused : bool

Pauses the spatial audio engine.

访问函数:

bool paused () const
void setPaused (bool paused )

通知程序信号:

void pausedChanged ()

成员函数文档编制

QAudioEngine:: QAudioEngine ()

[explicit] QAudioEngine:: QAudioEngine ( QObject * parent )

[explicit] QAudioEngine:: QAudioEngine ( int sampleRate , QObject * parent = nullptr)

Constructs a spatial audio engine with parent ,若有的话。

The engine will operate with a sample rate given by sampleRate . The default sample rate, if none is provided, is 44100 (44.1kHz).

Sound content that is not provided at that sample rate will automatically get resampled to sampleRate when being processed by the engine. The default sample rate is fine in most cases, but you can define a different rate if most of your sound files are sampled with a different rate, and avoid some CPU overhead for resampling.

[virtual noexcept] QAudioEngine:: ~QAudioEngine ()

Destroys the spatial audio engine.

[slot] void QAudioEngine:: pause ()

Pauses playback.

[slot] void QAudioEngine:: resume ()

Resumes playback.

bool QAudioEngine:: roomEffectsEnabled () const

Returns true if room effects are enabled.

另请参阅 setRoomEffectsEnabled ().

int QAudioEngine:: sampleRate () const

Returns the sample rate the engine has been configured with.

void QAudioEngine:: setRoomEffectsEnabled ( bool enabled )

Enables room effects such as echos and reverb.

Enables room effects if enabled is true. Room effects will only apply if you create one or more QAudioRoom objects and the listener is inside at least one of the rooms. If the listener is inside multiple rooms, the room with the smallest volume will be used.

另请参阅 roomEffectsEnabled ().

[slot] void QAudioEngine:: start ()

Starts the engine.

[slot] void QAudioEngine:: stop ()

Stops the engine.