QSpatialSound Class
Un objet sonore dans l'espace 3D. En savoir plus...
| En-tête : | #include <QSpatialSound> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio) target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake : | QT += spatialaudio |
| Hérite de : | 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 un espace 3D. Vous pouvez définir sa position et son orientation dans l'espace, choisir le son qu'il émet et définir son volume.
L'objet peut présenter différents comportements d'atténuation, émettre du son principalement dans une direction ou de manière sphérique, et se comporter comme s'il était masqué par un autre objet.
Documentation sur les types de membres
enum class QSpatialSound::DistanceModel
Définit la manière dont le volume sonore varie en fonction de la distance par rapport à l'auditeur.
| Constante | Valeur | Description |
|---|---|---|
QSpatialSound::DistanceModel::Logarithmic | 0 | Le volume diminue de manière logarithmique en fonction de la distance. |
QSpatialSound::DistanceModel::Linear | 1 | Le volume diminue de manière linéaire en fonction de la distance. |
QSpatialSound::DistanceModel::ManualAttenuation | 2 | L'atténuation est définie manuellement à l'aide de la propriété « manualAttenuation ». |
enum QSpatialSound::Loops
Vous permet de contrôler la boucle de lecture du son à l'aide des valeurs suivantes :
| Constante | Valeur | Description |
|---|---|---|
QSpatialSound::Infinite | -1 | Lecture en boucle infinie |
QSpatialSound::Once | 1 | Lecture unique |
Documentation sur les propriétés
autoPlay : bool
Détermine si la lecture du son doit démarrer automatiquement 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 uniforme dans toutes les directions, tandis qu'une valeur de 1 signifie que la source émet principalement le son vers l'avant.
Les valeurs valides sont comprises entre 0 et 1 ; la valeur par défaut est 0.
Fonctions d'accès :
| float | directivity() const |
| void | setDirectivity(float alpha) |
Signal de notification :
| void | directivityChanged() |
directivityOrder : float
Définit l'ordre de directivité de la source sonore. Un ordre plus élevé implique une localisation plus précise du cône sonore.
La valeur minimale et la valeur par défaut de cette propriété sont 1.
Fonctions d'accès :
| float | directivityOrder() const |
| void | setDirectivityOrder(float alpha) |
Signal de notification :
| void | directivityOrderChanged() |
distanceCutoff : float
Définit une distance au-delà de laquelle le son provenant de la source sera coupé. Si l'auditeur se trouve à une distance de l'objet sonore supérieure à la distance de coupure, celui-ci 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 diminue progressivement de size à distanceCutoff. Le volume reste constant pour les distances inférieures à « size » et vaut zéro 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 le nombre de fois où le son est lu avant que le lecteur ne s'arrête. Définissez cette option sur « QSpatialSound::Infinite » pour lire le son actuel en boucle indéfiniment.
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 l'option « distanceModel » est définie 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 en champ proche de la source sonore. Les valeurs valides sont comprises entre 0 et 1. Un gain en champ proche de 1 augmentera le volume du signal sonore d'environ 20 dB à 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'occlusion de l'objet. La valeur 0 signifie que l'objet n'est pas du tout occlus, tandis que la valeur 1 signifie que la source sonore est entièrement occluse par un autre objet.
Un objet entièrement masqué restera audible, mais les fréquences aiguës, en particulier, seront atténuées. De plus, l'objet continuera à contribuer à la création de la réverbération et des réflexions dans la pièce.
Des valeurs supérieures à 1 sont possibles pour 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 de notification :
| void | occlusionIntensityChanged() |
position : QVector3D
Définit la position de la source sonore dans l'espace 3D. Les unités sont exprimées en centimètres par défaut.
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 se trouve plus près de l'objet sonore que cette taille, le volume restera constant. La taille est également utilisée pour les calculs d'occlusion, dans lesquels les sources de grande taille peuvent être partiellement masquées par un mur.
Fonctions d'accès :
| float | size() const |
| void | setSize(float size) |
Signal de notification :
| void | sizeChanged() |
source : QUrl
Fichier source du son à lire.
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 de notification :
| void | volumeChanged() |
Documentation des fonctions membres
[explicit] QSpatialSound::QSpatialSound(QAudioEngine *engine)
Crée une source sonore spatiale pour engine. L'objet peut être placé dans l'espace 3D et son volume augmentera à mesure qu'il se rapprochera de l'auditeur.
Remarque : doit être appelé avec un QAudioEngine
[override virtual noexcept] QSpatialSound::~QSpatialSound()
Détruit la source sonore.
QAudioEngine *QSpatialSound::engine() const
Renvoie le moteur associé à cet écouteur.
[slot] void QSpatialSound::pause()
Met la lecture audio en pause. L'appel de la méthode play() permet de reprendre 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 courante ainsi que le nombre de boucles en cours. L'appel de la fonction ` play()` relancera la lecture depuis le début du fichier audio.
© 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.
