QAudioEngine Class

QAudioEngine verwaltet ein dreidimensionales Klangfeld. Mehr...

Kopfzeile: #include <QAudioEngine>
CMake: find_package(Qt6 REQUIRED COMPONENTS SpatialAudio)
target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio)
qmake: QT += spatialaudio
Vererbt: QObject

Öffentliche Typen

enum OutputMode { Surround, Stereo, Headphone }

Eigenschaften

Öffentliche Funktionen

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)

Öffentliche Slots

void pause()
void resume()
void start()
void stop()

Signale

Detaillierte Beschreibung

Sie können eine Instanz von QAudioEngine verwenden, um ein Schallfeld in drei Dimensionen zu verwalten. Ein Klangfeld wird durch mehrere QSpatialSound Objekte definiert, die einen Klang an einer bestimmten Stelle im 3D-Raum definieren. Sie können auch Stereo-Overlays mit QAmbientSound hinzufügen.

Sie können QAudioListener verwenden, um die Position der Person, die das Schallfeld hört, relativ zu den Schallquellen zu definieren. Schallquellen sind weniger gut hörbar, wenn der Zuhörer weiter von der Quelle entfernt ist. Sie werden auch den entsprechenden Lautsprechern zugeordnet, abhängig von der Richtung zwischen Hörer und Quelle.

QAudioEngine bietet zwei Ausgabemodi. Der erste Modus gibt das Klangfeld an eine Reihe von Lautsprechern aus, entweder ein Stereolautsprecherpaar oder eine Surround-Konfiguration. Der zweite Modus bietet bei Verwendung von Kopfhörern ein immersives 3D-Klangerlebnis.

Die Wahrnehmung der Klanglokalisierung wird hauptsächlich von zwei Faktoren bestimmt. Der erste Faktor ist der zeitliche Unterschied der Schallwellen zwischen dem linken und dem rechten Ohr. Der zweite Faktor ergibt sich aus der Art und Weise, wie Klänge, die aus verschiedenen Richtungen kommen, verschiedene Arten von Reflexionen an unseren Ohren und Köpfen erzeugen. Siehe https://en.wikipedia.org/wiki/Sound_localization für weitere Details.

Die Spatial-Audio-Engine emuliert diese Zeitunterschiede und Reflexionen durch kopfbezogene Übertragungsfunktionen (HRTF, siehe https://en.wikipedia.org/wiki/Head-related_transfer_function). Die verwendeten Funktionen emulieren diese Effekte für die Ohren und den Kopf einer durchschnittlichen Person. Für die meisten Personen, die Kopfhörer benutzen, bietet sie ein gutes und realistisches 3D-Klangerlebnis.

Die Engine ist recht vielseitig und erlaubt es Ihnen, Raumeigenschaften und Reverb-Einstellungen zu definieren, um verschiedene Arten von Räumen zu emulieren.

Schallquellen können auch verdeckt werden, wodurch der von diesen Quellen ausgehende Schall gedämpft wird.

Die Audio-Engine verwendet ein Koordinatensystem, das standardmäßig in Zentimetern angegeben ist. Die Achsen sind an dem typischen 3D-Koordinatensystem ausgerichtet. Positives x zeigt nach rechts, positives y zeigt nach oben und positives z zeigt nach hinten.

Dokumentation der Mitgliedstypen

enum QAudioEngine::OutputMode

KonstanteWertBeschreibung
QAudioEngine::Surround0Ordnet die Klänge der Lautsprecherkonfiguration des Ausgabegeräts zu. Dies ist normalerweise eine Stereo- oder Surround-Lautsprecherkonfiguration.
QAudioEngine::Stereo1Ordnet die Klänge der Stereo-Lautsprecherkonfiguration des Ausgabegeräts zu. Dabei werden alle zusätzlichen Lautsprecher ignoriert und nur der linke und der rechte Kanal verwendet, um eine Stereowiedergabe des Klangfelds zu erzeugen.
QAudioEngine::Headphone2Verwenden Sie Headphone Spatialization, um einen 3D-Audioeffekt zu erzeugen, wenn Sie das Klangfeld über Kopfhörer hören.

Dokumentation der Eigenschaft

distanceScale : float

Legt den Maßstab des Koordinatensystems fest, das von der räumlichen Audio-Engine verwendet wird. Standardmäßig sind alle Einheiten in Zentimetern, in Übereinstimmung mit den Standardeinheiten, die von Qt Quick 3D verwendet werden.

Setzen Sie die Distanzskala auf QAudioEngine::DistanceScaleMeter, um Einheiten in Metern zu erhalten.

Zugriffsfunktionen:

float distanceScale() const
void setDistanceScale(float scale)

Melder-Signal:

void distanceScaleChanged()

masterVolume : float

Legt die Lautstärke fest oder gibt sie zurück, die zum Rendern des Klangfelds verwendet wird.

Zugriffsfunktionen:

float masterVolume() const
void setMasterVolume(float volume)

Melder-Signal:

void masterVolumeChanged()

outputDevice : QAudioDevice

Legt das Gerät fest oder gibt es zurück, das zum Abspielen des Klangfeldes verwendet wird.

Zugriffsfunktionen:

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

Melder-Signal:

void outputDeviceChanged()

outputMode : OutputMode

Legt den aktuellen Ausgabemodus des Motors fest oder ruft ihn ab.

Zugriffsfunktionen:

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

Melder-Signal:

void outputModeChanged()

Siehe auch QAudioEngine::OutputMode.

paused : bool

Pausiert die räumliche Audio-Engine.

Zugriffsfunktionen:

bool paused() const
void setPaused(bool paused)

Benachrichtigungssignal:

void pausedChanged()

Member Function Dokumentation

QAudioEngine::QAudioEngine()

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

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

Konstruiert eine räumliche Audio-Engine mit parent, falls vorhanden.

Die Engine arbeitet mit einer durch sampleRate vorgegebenen Abtastrate. Die Standard-Abtastrate, wenn keine angegeben ist, ist 44100 (44,1 kHz).

Toninhalte, die nicht mit dieser Abtastrate bereitgestellt werden, werden bei der Verarbeitung durch die Engine automatisch auf sampleRate umgetastet. Die Standard-Samplerate ist in den meisten Fällen in Ordnung, aber Sie können eine andere Rate festlegen, wenn die meisten Ihrer Sounddateien mit einer anderen Rate abgetastet werden, um einen gewissen CPU-Overhead für das Resampling zu vermeiden.

[override virtual noexcept] QAudioEngine::~QAudioEngine()

Zerstört die räumliche Audio-Engine.

[slot] void QAudioEngine::pause()

Hält die Wiedergabe an.

[slot] void QAudioEngine::resume()

Setzt die Wiedergabe fort.

bool QAudioEngine::roomEffectsEnabled() const

Gibt true zurück, wenn Raumeffekte aktiviert sind.

Siehe auch setRoomEffectsEnabled().

int QAudioEngine::sampleRate() const

Gibt die Abtastrate zurück, mit der die Engine konfiguriert wurde.

void QAudioEngine::setRoomEffectsEnabled(bool enabled)

Aktiviert Raumeffekte wie Echos und Reverb.

Aktiviert Raumeffekte, wenn enabled wahr ist. Raumeffekte werden nur angewendet, wenn Sie ein oder mehrere QAudioRoom Objekte erstellen und sich der Hörer in mindestens einem der Räume befindet. Wenn sich der Zuhörer in mehreren Räumen befindet, wird der Raum mit der geringsten Lautstärke verwendet.

Siehe auch roomEffectsEnabled().

[slot] void QAudioEngine::start()

Startet den Motor.

[slot] void QAudioEngine::stop()

Stoppt den Motor.

© 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.