QSpatialSound Class
Ein Klangobjekt im 3D-Raum. Mehr...
| Kopfzeile: | #include <QSpatialSound> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio)target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake: | QT += spatialaudio |
| Vererbt: | QObject |
Öffentliche Typen
| enum class | DistanceModel { Logarithmic, Linear, ManualAttenuation } |
| enum | Loops { Infinite, Once } |
Eigenschaften
|
|
Öffentliche Funktionen
| QSpatialSound(QAudioEngine *engine) | |
| virtual | ~QSpatialSound() override |
| bool | autoPlay() const |
| float | directivity() const |
| float | directivityOrder() const |
| float | distanceCutoff() const |
| QSpatialSound::DistanceModel | distanceModel() const |
| QAudioEngine * | engine() const |
| int | loops() const |
| float | manualAttenuation() const |
| float | nearFieldGain() const |
| float | occlusionIntensity() const |
| QVector3D | position() const |
| QQuaternion | rotation() const |
| void | setAutoPlay(bool autoPlay) |
| void | setDirectivity(float alpha) |
| void | setDirectivityOrder(float alpha) |
| void | setDistanceCutoff(float cutoff) |
| void | setDistanceModel(QSpatialSound::DistanceModel model) |
| void | setLoops(int loops) |
| void | setManualAttenuation(float attenuation) |
| void | setNearFieldGain(float gain) |
| void | setOcclusionIntensity(float occlusion) |
| void | setPosition(QVector3D pos) |
| void | setRotation(const QQuaternion &q) |
| void | setSize(float size) |
| void | setSource(const QUrl &url) |
| void | setVolume(float volume) |
| float | size() const |
| QUrl | source() const |
| float | volume() const |
Öffentliche Slots
Signale
| void | autoPlayChanged() |
| void | directivityChanged() |
| void | directivityOrderChanged() |
| void | distanceCutoffChanged() |
| void | distanceModelChanged() |
| void | loopsChanged() |
| void | manualAttenuationChanged() |
| void | nearFieldGainChanged() |
| void | occlusionIntensityChanged() |
| void | positionChanged() |
| void | rotationChanged() |
| void | sizeChanged() |
| void | sourceChanged() |
| void | volumeChanged() |
Detaillierte Beschreibung
QSpatialSound stellt ein hörbares Objekt im 3D-Raum dar. Sie können seine Position und Orientierung im Raum bestimmen, den Ton, den es abspielt, festlegen und eine Lautstärke für das Objekt definieren.
Das Objekt kann ein unterschiedliches Dämpfungsverhalten haben, Schall hauptsächlich in eine Richtung oder sphärisch abstrahlen und sich so verhalten, als ob es von einem anderen Objekt verdeckt wird.
Dokumentation der Mitgliedstypen
enum class QSpatialSound::DistanceModel
Legt fest, wie die Lautstärke des Schalls mit dem Abstand zum Hörer skaliert.
| Konstante | Wert | Beschreibung |
|---|---|---|
QSpatialSound::DistanceModel::Logarithmic | 0 | Die Lautstärke nimmt logarithmisch mit der Entfernung ab. |
QSpatialSound::DistanceModel::Linear | 1 | Die Lautstärke nimmt linear mit der Entfernung ab. |
QSpatialSound::DistanceModel::ManualAttenuation | 2 | Die Dämpfung wird manuell über die Eigenschaft manualAttenuation definiert. |
enum QSpatialSound::Loops
Ermöglicht die Steuerung der Tonwiedergabeschleife anhand der folgenden Werte:
| Konstante | Wert | Beschreibung |
|---|---|---|
QSpatialSound::Infinite | -1 | Unendliche Wiedergabe |
QSpatialSound::Once | 1 | Einmalig abspielen |
Eigenschaft Dokumentation
autoPlay : bool
Legt fest, ob der Ton automatisch abgespielt werden soll, wenn eine Quelle angegeben wird.
Der Standardwert ist true.
Zugriffsfunktionen:
| bool | autoPlay() const |
| void | setAutoPlay(bool autoPlay) |
Melder-Signal:
| void | autoPlayChanged() |
directivity : float
Bestimmt die Richtwirkung der Schallquelle. Ein Wert von 0 bedeutet, dass der Schall gleichmäßig in alle Richtungen abgestrahlt wird, während ein Wert von 1 bedeutet, dass die Quelle den Schall hauptsächlich in Vorwärtsrichtung abstrahlt.
Gültige Werte liegen zwischen 0 und 1, der Standardwert ist 0.
Zugriffsfunktionen:
| float | directivity() const |
| void | setDirectivity(float alpha) |
Melder-Signal:
| void | directivityChanged() |
directivityOrder : float
Bestimmt die Ordnung der Richtwirkung der Schallquelle. Eine höhere Ordnung bedeutet eine schärfere Lokalisierung des Schallkegels.
Der Mindestwert und Standardwert für diese Eigenschaft ist 1.
Zugriffsfunktionen:
| float | directivityOrder() const |
| void | setDirectivityOrder(float alpha) |
Anmelder-Signal:
| void | directivityOrderChanged() |
distanceCutoff : float
Legt eine Entfernung fest, ab der der von der Quelle kommende Schall abgeschnitten wird. Befindet sich der Zuhörer weiter vom Klangobjekt entfernt als die Abschaltdistanz, ist es nicht mehr hörbar.
Zugriff auf Funktionen:
| float | distanceCutoff() const |
| void | setDistanceCutoff(float cutoff) |
Melder-Signal:
| void | distanceCutoffChanged() |
distanceModel : DistanceModel
Definiert das Abstandsmodell für diese Schallquelle. Die Lautstärke wird von size auf distanceCutoff herunterskaliert. Die Lautstärke ist konstant für Entfernungen kleiner als size und Null für Entfernungen größer als die cutoff distance.
Zugriffsfunktionen:
| QSpatialSound::DistanceModel | distanceModel() const |
| void | setDistanceModel(QSpatialSound::DistanceModel model) |
Melder-Signal:
| void | distanceModelChanged() |
Siehe auch QSpatialSound::DistanceModel.
loops : int
Bestimmt, wie oft der Sound abgespielt wird, bevor der Player stoppt. Setzen Sie den Wert auf QSpatialSound::Infinite, um den aktuellen Sound in einer Endlosschleife abzuspielen.
Der Standardwert ist 1.
Zugriffsfunktionen:
| int | loops() const |
| void | setLoops(int loops) |
Benachrichtigungssignal:
| void | loopsChanged() |
manualAttenuation : float
Legt einen manuellen Dämpfungsfaktor fest, wenn distanceModel auf QSpatialSound::DistanceModel::ManualAttenuation eingestellt ist.
Zugriffsfunktionen:
| float | manualAttenuation() const |
| void | setManualAttenuation(float attenuation) |
Melder-Signal:
| void | manualAttenuationChanged() |
nearFieldGain : float
Bestimmt die Nahfeldverstärkung für die Schallquelle. Gültige Werte liegen zwischen 0 und 1. Eine Nahfeldverstärkung von 1 erhöht die Lautstärke des Schallsignals um ca. 20 dB bei sehr geringen Abständen zum Hörer.
Zugriffsfunktionen:
| float | nearFieldGain() const |
| void | setNearFieldGain(float gain) |
Signalgebersignal:
| void | nearFieldGainChanged() |
occlusionIntensity : float
Legt fest, wie stark das Objekt verdeckt ist. 0 bedeutet, dass das Objekt überhaupt nicht verdeckt ist, 1 bedeutet, dass die Schallquelle vollständig von einem anderen Objekt verdeckt ist.
Ein vollständig verdecktes Objekt ist immer noch hörbar, aber insbesondere höhere Frequenzen werden gedämpft. Darüber hinaus ist das Objekt immer noch an der Erzeugung von Hall und Reflexionen im Raum beteiligt.
Werte größer als 1 sind möglich, um den von der Quelle kommenden Direktschall weiter zu dämpfen.
Die Voreinstellung ist 0.
Zugriffsfunktionen:
| float | occlusionIntensity() const |
| void | setOcclusionIntensity(float occlusion) |
Anmelder-Signal:
| void | occlusionIntensityChanged() |
position : QVector3D
Bestimmt die Position der Schallquelle im 3D-Raum. Die Einheiten sind standardmäßig in Zentimetern.
Zugriffsfunktionen:
| QVector3D | position() const |
| void | setPosition(QVector3D pos) |
Melder-Signal:
| void | positionChanged() |
Siehe auch QAudioEngine::distanceScale.
rotation : QQuaternion
Bestimmt die Ausrichtung der Schallquelle im 3D-Raum.
Zugriffsfunktionen:
| QQuaternion | rotation() const |
| void | setRotation(const QQuaternion &q) |
Anmelder-Signal:
| void | rotationChanged() |
size : float
Bestimmt die Größe der Schallquelle. Wenn der Zuhörer näher am Schallobjekt ist als die Größe, bleibt die Lautstärke konstant. Die Größe wird auch für Verdeckungsberechnungen verwendet, bei denen große Quellen teilweise von einer Wand verdeckt werden können.
Zugriffsfunktionen:
| float | size() const |
| void | setSize(float size) |
Anmelder-Signal:
| void | sizeChanged() |
source : QUrl
Die Quelldatei für den abzuspielenden Ton.
Zugriffsfunktionen:
| QUrl | source() const |
| void | setSource(const QUrl &url) |
Benachrichtigungssignal:
| void | sourceChanged() |
volume : float
Bestimmt die Lautstärke des Klangs.
Werte zwischen 0 und 1 dämpfen den Klang, während Werte über 1 eine zusätzliche Anhebung bewirken.
Zugriffsfunktionen:
| float | volume() const |
| void | setVolume(float volume) |
Melder-Signal:
| void | volumeChanged() |
Member Function Dokumentation
[explicit] QSpatialSound::QSpatialSound(QAudioEngine *engine)
Erzeugt eine räumliche Klangquelle für engine. Das Objekt kann im 3D-Raum platziert werden und wird umso lauter, je näher es sich am Zuhörer befindet.
[override virtual noexcept] QSpatialSound::~QSpatialSound()
Zerstört die Klangquelle.
QAudioEngine *QSpatialSound::engine() const
Gibt die mit diesem Hörer verbundene Engine zurück.
[slot] void QSpatialSound::pause()
Hält die Tonwiedergabe an. Wenn Sie play() aufrufen, wird die Wiedergabe fortgesetzt.
[slot] void QSpatialSound::play()
Startet die Wiedergabe des Tons. Führt nichts aus, wenn der Ton bereits abgespielt wird.
[slot] void QSpatialSound::stop()
Stoppt die Tonwiedergabe und setzt die aktuelle Position und den aktuellen Schleifenzähler auf 0 zurück. Der Aufruf von play() startet die Wiedergabe am Anfang der Tondatei.
© 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.
