QSpatialSound Class
Un objet sonore dans l'espace 3D. Plus d'informations...
| En-tête : | #include <QSpatialSound> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio)target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake : | QT += spatialaudio |
| Héritages : | QObject |
Types publics
| enum class | DistanceModel { Logarithmic, Linear, ManualAttenuation } |
| enum | Loops { Infinite, Once } |
Propriétés
|
|
Fonctions publiques
| 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 |
Emplacements publics
Signaux
| 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() |
Description détaillée
QSpatialSound représente un objet sonore dans l'espace 3D. Vous pouvez définir sa position et son orientation dans l'espace, définir le son qu'il joue et définir un volume pour l'objet.
L'objet peut avoir différents comportements d'atténuation, émettre le son principalement dans une direction ou de manière sphérique, et se comporter comme s'il était occulté par un autre objet.
Documentation sur les types de membres
enum class QSpatialSound::DistanceModel
Définit la manière dont le volume du son varie en fonction de la distance de l'auditeur.
| Constante | Valeur | Description |
|---|---|---|
QSpatialSound::DistanceModel::Logarithmic | 0 | Le volume diminue logarithmiquement avec la distance. |
QSpatialSound::DistanceModel::Linear | 1 | Le volume diminue linéairement avec la distance. |
QSpatialSound::DistanceModel::ManualAttenuation | 2 | L'atténuation est définie manuellement à l'aide de la propriété manualAttenuation. |
enum QSpatialSound::Loops
Permet de contrôler la boucle de lecture du son à l'aide des valeurs suivantes :
| Constante | Valeur | Description |
|---|---|---|
QSpatialSound::Infinite | -1 | Lecture infinie |
QSpatialSound::Once | 1 | Lecture unique |
Propriété Documentation
autoPlay : bool
Détermine si le son doit automatiquement commencer à jouer lorsqu'une source est spécifiée.
La valeur par défaut est true.
Fonctions d'accès :
| bool | autoPlay() const |
| void | setAutoPlay(bool autoPlay) |
Signal de notification :
| void | autoPlayChanged() |
directivity : float
Définit la directivité de la source sonore. Une valeur de 0 signifie que le son est émis de manière égale dans toutes les directions, tandis qu'une valeur de 1 signifie que la source émet principalement le son dans la direction avant.
Les valeurs valides sont comprises entre 0 et 1, la valeur par défaut étant 0.
Fonctions d'accès :
| float | directivity() const |
| void | setDirectivity(float alpha) |
Signal du notificateur :
| void | directivityChanged() |
directivityOrder : float
Définit l'ordre de directivité de la source sonore. Un ordre plus élevé implique une localisation plus nette du cône sonore.
La valeur minimale et par défaut de cette propriété est 1.
Fonctions d'accès :
| float | directivityOrder() const |
| void | setDirectivityOrder(float alpha) |
Signal du notificateur :
| void | directivityOrderChanged() |
distanceCutoff : float
Définit une distance au-delà de laquelle le son provenant de la source sera coupé. Si l'auditeur est plus éloigné de l'objet sonore que la distance de coupure, il ne sera plus audible.
Fonctions d'accès :
| float | distanceCutoff() const |
| void | setDistanceCutoff(float cutoff) |
Signal de notification :
| void | distanceCutoffChanged() |
distanceModel : DistanceModel
Définit le modèle de distance pour cette source sonore. Le volume commence à diminuer de size à distanceCutoff. Le volume est constant pour les distances inférieures à la taille et nul pour les distances supérieures à la distance de coupure.
Fonctions d'accès :
| QSpatialSound::DistanceModel | distanceModel() const |
| void | setDistanceModel(QSpatialSound::DistanceModel model) |
Signal de notification :
| void | distanceModelChanged() |
Voir également QSpatialSound::DistanceModel.
loops : int
Détermine combien de fois le son est joué avant que le lecteur ne s'arrête. La valeur QSpatialSound::Infinite permet de jouer le son actuel en boucle à l'infini.
La valeur par défaut est 1.
Fonctions d'accès :
| int | loops() const |
| void | setLoops(int loops) |
Signal de notification :
| void | loopsChanged() |
manualAttenuation : float
Définit un facteur d'atténuation manuel si distanceModel est réglé sur QSpatialSound::DistanceModel::ManualAttenuation.
Fonctions d'accès :
| float | manualAttenuation() const |
| void | setManualAttenuation(float attenuation) |
Signal de notification :
| void | manualAttenuationChanged() |
nearFieldGain : float
Définit le gain de champ proche pour la source sonore. Les valeurs valides sont comprises entre 0 et 1. Un gain de champ proche de 1 augmentera le volume du signal sonore d'environ 20 dB pour des distances très proches de l'auditeur.
Fonctions d'accès :
| float | nearFieldGain() const |
| void | setNearFieldGain(float gain) |
Signal de notification :
| void | nearFieldGainChanged() |
occlusionIntensity : float
Définit le degré d'occultation de l'objet. 0 signifie que l'objet n'est pas du tout occulté, 1 signifie que la source sonore est entièrement occultée par un autre objet.
Un objet totalement occulté sera toujours audible, mais les hautes fréquences seront particulièrement atténuées. En outre, l'objet participera toujours à la génération de la réverbération et des réflexions dans la pièce.
Des valeurs supérieures à 1 permettent d'atténuer davantage le son direct provenant de la source.
La valeur par défaut est 0.
Fonctions d'accès :
| float | occlusionIntensity() const |
| void | setOcclusionIntensity(float occlusion) |
Signal du notificateur :
| void | occlusionIntensityChanged() |
position : QVector3D
Définit la position de la source sonore dans l'espace 3D. L'unité par défaut est le centimètre.
Fonctions d'accès :
| QVector3D | position() const |
| void | setPosition(QVector3D pos) |
Signal de notification :
| void | positionChanged() |
Voir aussi QAudioEngine::distanceScale.
rotation : QQuaternion
Définit l'orientation de la source sonore dans l'espace 3D.
Fonctions d'accès :
| QQuaternion | rotation() const |
| void | setRotation(const QQuaternion &q) |
Signal de notification :
| void | rotationChanged() |
size : float
Définit la taille de la source sonore. Si l'auditeur est plus proche de l'objet sonore que la taille, le volume restera constant. La taille est également utilisée pour les calculs d'occlusion, lorsque de grandes sources peuvent être partiellement occultées par un mur.
Fonctions d'accès :
| float | size() const |
| void | setSize(float size) |
Signal du notificateur :
| void | sizeChanged() |
source : QUrl
Le fichier source du son à jouer.
Fonctions d'accès :
| QUrl | source() const |
| void | setSource(const QUrl &url) |
Signal de notification :
| void | sourceChanged() |
volume : float
Définit le volume du son.
Les valeurs comprises entre 0 et 1 atténuent le son, tandis que les valeurs supérieures à 1 augmentent le gain.
Fonctions d'accès :
| float | volume() const |
| void | setVolume(float volume) |
Signal du notificateur :
| void | volumeChanged() |
Member Function Documentation
[explicit] QSpatialSound::QSpatialSound(QAudioEngine *engine)
Crée une source sonore spatiale pour engine. L'objet peut être placé dans un espace 3D et sera d'autant plus fort qu'il sera proche de l'auditeur.
[override virtual noexcept] QSpatialSound::~QSpatialSound()
Détruit la source sonore.
QAudioEngine *QSpatialSound::engine() const
Renvoie le moteur associé à cet auditeur.
[slot] void QSpatialSound::pause()
Interrompt la lecture du son. L'appel de play() permet de poursuivre la lecture.
[slot] void QSpatialSound::play()
Lance la lecture du son. Ne fait rien si le son est déjà en cours de lecture.
[slot] void QSpatialSound::stop()
Arrête la lecture du son et remet à 0 la position et le nombre de boucles en cours. L'appel de play() démarre la lecture au début du fichier son.
© 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.
