QAudioEngine Class
QAudioEngine verwaltet ein dreidimensionales Klangfeld. Mehr...
| Überschrift: | #include <QAudioEngine> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio) target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake: | QT += spatialaudio |
| Erbt von: | 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
Signale
| void | distanceScaleChanged() |
| void | masterVolumeChanged() |
| void | outputDeviceChanged() |
| void | outputModeChanged() |
| void | pausedChanged() |
Ausführliche Beschreibung
Mit einer Instanz von `QAudioEngine` können Sie ein dreidimensionales Klangfeld verwalten. Ein Klangfeld wird durch mehrere ` QSpatialSound `-Objekte definiert, die einen Ton an einer bestimmten Position im 3D-Raum festlegen. Mit ` QAmbientSound` können Sie zudem Stereo-Overlays hinzufügen.
Mit ` QAudioListener ` können Sie die Position der Person, die das Klangfeld hört, relativ zu den Klangquellen definieren. Klangquellen sind umso leiser, je weiter der Zuhörer von der Quelle entfernt ist. Sie werden außerdem je nach Richtung zwischen Zuhörer und Quelle den entsprechenden Lautsprechern zugeordnet.
QAudioEngine bietet zwei Ausgabemodi. Der erste Modus gibt das Klangfeld über eine Reihe von Lautsprechern wieder, entweder über ein Stereo-Lautsprecherpaar oder eine Surround-Konfiguration. Der zweite Modus sorgt bei Verwendung von Kopfhörern für ein immersives 3D-Klangerlebnis.
Die Wahrnehmung der Schalllokalisierung wird hauptsächlich von zwei Faktoren bestimmt. Der erste Faktor sind die zeitlichen Unterschiede der Schallwellen zwischen dem linken und dem rechten Ohr. Der zweite Faktor ergibt sich aus den verschiedenen Arten, wie Schalle, die aus unterschiedlichen Richtungen kommen, unterschiedliche Reflexionen an unseren Ohren und Köpfen erzeugen. Weitere Details finden Sie unter https://en.wikipedia.org/wiki/Sound_localization.
Die räumliche Audio-Engine emuliert diese Zeitunterschiede und Reflexionen mithilfe von kopfbezogenen Ü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. Sie bieten den meisten Menschen bei der Verwendung von Kopfhörern ein gutes und immersives 3D-Klanglokalisierungserlebnis.
Die Engine ist sehr vielseitig und ermöglicht es Ihnen, Raumeigenschaften und Nachhall-Einstellungen zu definieren, um verschiedene Raumtypen zu emulieren.
Schallquellen können zudem verdeckt werden, wodurch der von diesen Quellen kommende Schall gedämpft wird.
Die Audio-Engine verwendet standardmäßig ein Koordinatensystem in Zentimetern. Die Achsen sind an das typische Koordinatensystem in 3D angepasst. Positive x-Werte zeigen nach rechts, positive y-Werte zeigen nach oben und positive z-Werte zeigen nach hinten.
Dokumentation zum Mitgliedstyp
enum QAudioEngine::OutputMode
| Konstante | Wert | Beschreibung |
|---|---|---|
QAudioEngine::Surround | 0 | Ordnet die Töne der Lautsprecherkonfiguration des Ausgabegeräts zu. Dabei handelt es sich in der Regel um eine Stereo- oder Surround-Lautsprecherkonfiguration. Hinweis: „OutputMode ::Surround“ deaktiviert die Wiedergabe von QAmbientSound |
QAudioEngine::Stereo | 1 | Ordnen Sie die Töne der Stereo-Lautsprecherkonfiguration des Ausgabegeräts zu. Dabei werden zusätzliche Lautsprecher ignoriert und nur der linke und der rechte Kanal verwendet, um eine Stereo-Wiedergabe des Klangfelds zu erzeugen. |
QAudioEngine::Headphone | 2 | Verwenden Sie die Kopfhörer-Spatialisierung, um einen 3D-Audioeffekt zu erzeugen, wenn Sie das Klangfeld über Kopfhörer hören |
Dokumentation der Eigenschaften
distanceScale : float
Legt den Maßstab des Koordinatensystems fest, das von der Spatial-Audio-Engine verwendet wird. Standardmäßig werden alle Einheiten in Zentimetern angegeben, entsprechend den von Qt Quick 3D verwendeten Standardeinheiten.
Stellen Sie den Entfernungsmaßstab auf `QAudioEngine::DistanceScaleMeter` ein, um Einheiten in Metern zu erhalten.
Zugriffsfunktionen:
| float | distanceScale() const |
| void | setDistanceScale(float scale) |
Notifier-Signal:
| void | distanceScaleChanged() |
masterVolume : float
Legt die Lautstärke fest, die zum Rendern des Klangfelds verwendet wird, oder gibt sie zurück.
Zugriffsfunktionen:
| float | masterVolume() const |
| void | setMasterVolume(float volume) |
Benachrichtigungssignal:
| void | masterVolumeChanged() |
outputDevice : QAudioDevice
Legt das Gerät fest, das für die Wiedergabe des Klangfeldes verwendet wird, oder gibt es zurück.
Zugriffsfunktionen:
| QAudioDevice | outputDevice() const |
| void | setOutputDevice(const QAudioDevice &device) |
Benachrichtigungssignal:
| void | outputDeviceChanged() |
outputMode : OutputMode
Legt den aktuellen Ausgabemodus der Engine fest oder ruft ihn ab.
Zugriffsfunktionen:
| QAudioEngine::OutputMode | outputMode() const |
| void | setOutputMode(QAudioEngine::OutputMode mode) |
Benachrichtigungssignal:
| void | outputModeChanged() |
Siehe auch „ QAudioEngine::OutputMode “.
paused : bool
Hält die Raumklang-Engine an.
Zugriffsfunktionen:
| bool | paused() const |
| void | setPaused(bool paused) |
Benachrichtigungssignal:
| void | pausedChanged() |
Dokumentation der Mitgliedsfunktionen
QAudioEngine::QAudioEngine()
[explicit] QAudioEngine::QAudioEngine(QObject *parent)
[explicit] QAudioEngine::QAudioEngine(int sampleRate, QObject *parent = nullptr)
Erstellt eine Spatial-Audio-Engine mit „ parent “, sofern vorhanden.
Die Engine arbeitet mit einer durch ` sampleRate` vorgegebenen Abtastrate. Die Standard-Abtastrate beträgt 44100 (44,1 kHz), sofern keine andere angegeben wird.
Soundinhalte, die nicht mit dieser Abtastrate vorliegen, werden bei der Verarbeitung durch die Engine automatisch auf ` sampleRate ` neu abgetastet. Die Standard-Abtastrate ist in den meisten Fällen ausreichend, Sie können jedoch eine andere Rate festlegen, wenn die meisten Ihrer Sounddateien mit einer anderen Rate abgetastet wurden, um den CPU-Aufwand für das Neusampeln zu vermeiden.
[override virtual noexcept] QAudioEngine::~QAudioEngine()
Zerstört die Spatial-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 Hall.
Aktiviert Raumeffekte, wenn „ enabled “ auf „true“ gesetzt ist. Raumeffekte werden nur angewendet, wenn Sie ein oder mehrere „ QAudioRoom “-Objekte erstellen und sich der Zuhörer in mindestens einem der Räume befindet. Befindet sich der Zuhörer in mehreren Räumen, wird der Raum mit dem kleinsten Volumen verwendet.
Siehe auch „ roomEffectsEnabled()“.
[slot] void QAudioEngine::start()
Startet den Motor.
[slot] void QAudioEngine::stop()
Stellt den Motor ab.
© 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.
