QSpatialSound Class
Ein Klangobjekt im 3D-Raum. Mehr...
| Überschrift: | #include <QSpatialSound> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio) target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake: | QT += spatialaudio |
| Erbt von: | 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() |
Ausführliche Beschreibung
QSpatialSound stellt ein hörbares Objekt im 3D-Raum dar. Sie können dessen Position und Ausrichtung im Raum festlegen, den wiedergegebenen Ton bestimmen und die Lautstärke des Objekts festlegen.
Das Objekt kann unterschiedliche Dämpfungsverhalten aufweisen, den Ton hauptsächlich in eine Richtung oder sphärisch ausstrahlen und sich so verhalten, als würde es von einem anderen Objekt verdeckt.
Dokumentation zu den Mitgliedstypen
enum class QSpatialSound::DistanceModel
Legt fest, wie sich die Lautstärke in Abhängigkeit von der Entfernung zum Zuhörer verändert.
| Konstant | 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 zunehmender Entfernung ab. |
QSpatialSound::DistanceModel::ManualAttenuation | 2 | Die Dämpfung wird manuell über die Eigenschaft „ manualAttenuation “ festgelegt. |
enum QSpatialSound::Loops
Ermöglicht Ihnen, die Wiederholungsschleife der Tonwiedergabe mithilfe der folgenden Werte zu steuern:
| Konstant | Wert | Beschreibung |
|---|---|---|
QSpatialSound::Infinite | -1 | Endlos wiedergeben |
QSpatialSound::Once | 1 | Einmal abspielen |
Eigenschaftsdokumentation
autoPlay : bool
Legt fest, ob die Wiedergabe des Sounds automatisch starten soll, sobald eine Quelle angegeben wird.
Der Standardwert ist „ true “.
Zugriffsfunktionen:
| bool | autoPlay() const |
| void | setAutoPlay(bool autoPlay) |
Benachrichtigungssignal:
| void | autoPlayChanged() |
directivity : float
Legt die Richtwirkung der Schallquelle fest. Der Wert 0 bedeutet, dass der Schall gleichmäßig in alle Richtungen abgestrahlt wird, während der Wert 1 bedeutet, dass die Quelle den Schall hauptsächlich nach vorne abstrahlt.
Gültige Werte liegen zwischen 0 und 1, der Standardwert ist 0.
Zugriffsfunktionen:
| float | directivity() const |
| void | setDirectivity(float alpha) |
Benachrichtigungssignal:
| void | directivityChanged() |
directivityOrder : float
Legt die Ordnung der Richtcharakteristik der Schallquelle fest. Eine höhere Ordnung bedeutet eine präzisere Lokalisierung des Schallkegels.
Der Mindestwert und der Standardwert für diese Eigenschaft ist 1.
Zugriffsfunktionen:
| float | directivityOrder() const |
| void | setDirectivityOrder(float alpha) |
Benachrichtigungssignal:
| void | directivityOrderChanged() |
distanceCutoff : float
Legt eine Entfernung fest, jenseits derer der von der Quelle kommende Ton abfällt. Befindet sich der Zuhörer weiter vom Klangobjekt entfernt als die festgelegte Abklingentfernung, ist der Ton nicht mehr hörbar.
Zugriffsfunktionen:
| float | distanceCutoff() const |
| void | setDistanceCutoff(float cutoff) |
Benachrichtigungssignal:
| void | distanceCutoffChanged() |
distanceModel : DistanceModel
Definiert das Entfernungsmodell für diese Schallquelle. Die Lautstärke wird von size bis distanceCutoff schrittweise verringert. Bei Entfernungen, die kleiner als „size“ sind, bleibt die Lautstärke konstant, bei Entfernungen, die größer als die „cutoff distance“ sind, beträgt sie null.
Zugriffsfunktionen:
| QSpatialSound::DistanceModel | distanceModel() const |
| void | setDistanceModel(QSpatialSound::DistanceModel model) |
Benachrichtigungssignal:
| void | distanceModelChanged() |
Siehe auch QSpatialSound::DistanceModel.
loops : int
Legt fest, wie oft der Ton abgespielt wird, bevor der Player stoppt. Setzen Sie den Wert auf „ QSpatialSound::Infinite “, um den aktuellen Ton endlos in einer Schleife 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 “ gesetzt ist.
Zugriffsfunktionen:
| float | manualAttenuation() const |
| void | setManualAttenuation(float attenuation) |
Benachrichtigungssignal:
| void | manualAttenuationChanged() |
nearFieldGain : float
Legt die Nahfeldverstärkung für die Schallquelle fest. Gültige Werte liegen zwischen 0 und 1. Eine Nahfeldverstärkung von 1 erhöht die Lautstärke des Tonsignals um ca. 20 dB bei Entfernungen, die sehr nahe am Hörer liegen.
Zugriffsfunktionen:
| float | nearFieldGain() const |
| void | setNearFieldGain(float gain) |
Benachrichtigungssignal:
| void | nearFieldGainChanged() |
occlusionIntensity : float
Legt fest, inwieweit das Objekt verdeckt ist. Der Wert 0 bedeutet, dass das Objekt überhaupt nicht verdeckt ist, während der Wert 1 bedeutet, dass die Schallquelle vollständig von einem anderen Objekt verdeckt ist.
Ein vollständig verdecktes Objekt ist zwar weiterhin hörbar, jedoch werden insbesondere höhere Frequenzen gedämpft. Zudem trägt das Objekt weiterhin zur Erzeugung von Hall und Reflexionen im Raum bei.
Werte größer als 1 sind möglich, um den von der Quelle kommenden Direktschall weiter zu dämpfen.
Der Standardwert ist 0.
Zugriffsfunktionen:
| float | occlusionIntensity() const |
| void | setOcclusionIntensity(float occlusion) |
Benachrichtigungssignal:
| void | occlusionIntensityChanged() |
position : QVector3D
Legt die Position der Schallquelle im 3D-Raum fest. Die Einheiten sind standardmäßig in Zentimetern angegeben.
Zugriffsfunktionen:
| QVector3D | position() const |
| void | setPosition(QVector3D pos) |
Benachrichtigungssignal:
| void | positionChanged() |
Siehe auch QAudioEngine::distanceScale.
rotation : QQuaternion
Legt die Ausrichtung der Schallquelle im 3D-Raum fest.
Zugriffsfunktionen:
| QQuaternion | rotation() const |
| void | setRotation(const QQuaternion &q) |
Benachrichtigungssignal:
| void | rotationChanged() |
size : float
Legt die Größe der Schallquelle fest. Befindet sich der Zuhörer näher am Schallobjekt als diese Größe, bleibt die Lautstärke konstant. Die Größe wird außerdem für Okklusionsberechnungen herangezogen, bei denen große Schallquellen teilweise durch eine Wand verdeckt werden können.
Zugriffsfunktionen:
| float | size() const |
| void | setSize(float size) |
Benachrichtigungssignal:
| 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
Legt die Lautstärke des Tons fest.
Werte zwischen 0 und 1 dämpfen den Ton, während Werte über 1 für eine zusätzliche Verstärkung sorgen.
Zugriffsfunktionen:
| float | volume() const |
| void | setVolume(float volume) |
Benachrichtigungssignal:
| void | volumeChanged() |
Dokumentation der Member-Funktionen
[explicit] QSpatialSound::QSpatialSound(QAudioEngine *engine)
Erstellt 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.
Hinweis: Muss mit einem gültigen QAudioEngine
[override virtual noexcept] QSpatialSound::~QSpatialSound()
Zerstört die Schallquelle.
QAudioEngine *QSpatialSound::engine() const
Gibt die Engine zurück, die diesem Listener zugeordnet ist.
[slot] void QSpatialSound::pause()
Hält die Tonwiedergabe an. Durch den Aufruf von ` play()` wird die Wiedergabe fortgesetzt.
[slot] void QSpatialSound::play()
Die Wiedergabe des Tons wird gestartet. Es geschieht nichts, wenn der Ton bereits abgespielt wird.
[slot] void QSpatialSound::stop()
Beendet die Soundwiedergabe und setzt die aktuelle Position sowie die aktuelle Schleifenanzahl auf 0 zurück. Durch den Aufruf von ` play()` wird die Wiedergabe am Anfang der Sounddatei gestartet.
© 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.
