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
Signale
void | distanceScaleChanged() |
void | masterVolumeChanged() |
void | outputDeviceChanged() |
void | outputModeChanged() |
void | pausedChanged() |
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
Konstante | Wert | Beschreibung |
---|---|---|
QAudioEngine::Surround | 0 | Ordnet die Klänge der Lautsprecherkonfiguration des Ausgabegeräts zu. Dies ist normalerweise eine Stereo- oder Surround-Lautsprecherkonfiguration. |
QAudioEngine::Stereo | 1 | Ordnet 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::Headphone | 2 | Verwenden 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.