QAudioEngine Class
QAudioEngine gère un champ sonore tridimensionnel. En savoir plus...
| En-tête : | #include <QAudioEngine> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio) target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake : | QT += spatialaudio |
| Hérite de : | QObject |
Types publics
| enum | OutputMode { Surround, Stereo, Headphone } |
Propriétés
|
|
Fonctions publiques
| 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) |
Emplacements publics
Signaux
| void | distanceScaleChanged() |
| void | masterVolumeChanged() |
| void | outputDeviceChanged() |
| void | outputModeChanged() |
| void | pausedChanged() |
Description détaillée
Vous pouvez utiliser une instance de QAudioEngine pour gérer un champ sonore en trois dimensions. Un champ sonore est défini par plusieurs objets ` QSpatialSound ` qui définissent un son à un emplacement spécifié dans l'espace 3D. Vous pouvez également ajouter des superpositions stéréo à l'aide de ` QAmbientSound`.
Vous pouvez utiliser QAudioListener pour définir la position de la personne qui écoute le champ sonore par rapport aux sources sonores. Les sources sonores seront moins audibles si l'auditeur est plus éloigné de la source. Elles seront également mappées vers les haut-parleurs correspondants en fonction de la direction entre l'auditeur et la source.
QAudioEngine propose deux modes de sortie. Le premier mode restitue le champ sonore sur un ensemble de haut-parleurs, qu’il s’agisse d’une paire de haut-parleurs stéréo ou d’une configuration surround. Le second mode offre une expérience sonore 3D immersive lors de l’utilisation d’un casque.
La perception de la localisation sonore dépend principalement de deux facteurs. Le premier facteur est lié aux différences de temps d’arrivée des ondes sonores entre l’oreille gauche et l’oreille droite. Le second facteur résulte des différentes façons dont les sons provenant de directions variées créent divers types de réflexions au niveau de nos oreilles et de notre tête. Pour plus de détails, consultez https://en.wikipedia.org/wiki/Sound_localization.
Le moteur audio spatial simule ces différences de temps et ces réflexions à l’aide de fonctions de transfert liées à la tête (HRTF, voir https://en.wikipedia.org/wiki/Head-related_transfer_function). Les fonctions utilisées simulent ces effets pour les oreilles et la tête d’une personne moyenne. Elles offrent une expérience de localisation sonore 3D de qualité et immersive pour la plupart des utilisateurs lorsqu’ils portent un casque.
Le moteur est assez polyvalent et vous permet de définir les propriétés de la pièce et les paramètres de réverbération afin de simuler différents types de pièces.
Les sources sonores peuvent également être masquées, ce qui atténue le son provenant de ces sources.
Le moteur audio utilise un système de coordonnées exprimé en centimètres par défaut. Les axes sont alignés sur le système de coordonnées classique utilisé en 3D. L’axe x positif pointe vers la droite, l’axe y positif vers le haut et l’axe z positif vers l’arrière.
Documentation sur les types de membres
enum QAudioEngine::OutputMode
| Constante | Valeur | Description |
|---|---|---|
QAudioEngine::Surround | 0 | Adapte les sons à la configuration des haut-parleurs du périphérique de sortie. Il s'agit généralement d'une configuration stéréo ou surround. Remarque : OutputMode ::Surround désactive la lecture des QAmbientSound |
QAudioEngine::Stereo | 1 | Adaptez les sons à la configuration stéréo des haut-parleurs du périphérique de sortie. Cela ignorera tout haut-parleur supplémentaire et n'utilisera que les canaux gauche et droit pour créer un rendu stéréo du champ sonore. |
QAudioEngine::Headphone | 2 | Utilisez la spatialisation pour casque afin de créer un effet audio 3D lorsque vous écoutez le champ sonore au casque |
Documentation des propriétés
distanceScale : float
Définit l'échelle du système de coordonnées utilisé par le moteur audio spatial. Par défaut, toutes les unités sont exprimées en centimètres, conformément aux unités par défaut utilisées par Qt Quick 3D.
Définissez l'échelle de distance sur QAudioEngine::DistanceScaleMeter pour obtenir des unités en mètres.
Fonctions d'accès :
| float | distanceScale() const |
| void | setDistanceScale(float scale) |
Signal de notification :
| void | distanceScaleChanged() |
masterVolume : float
Définit ou renvoie le volume utilisé pour générer le champ sonore.
Fonctions d'accès :
| float | masterVolume() const |
| void | setMasterVolume(float volume) |
Signal de notification :
| void | masterVolumeChanged() |
outputDevice : QAudioDevice
Définit ou renvoie le périphérique utilisé pour la lecture du champ sonore.
Fonctions d'accès :
| QAudioDevice | outputDevice() const |
| void | setOutputDevice(const QAudioDevice &device) |
Signal de notification :
| void | outputDeviceChanged() |
outputMode : OutputMode
Définit ou récupère le mode de sortie actuel du moteur.
Fonctions d'accès :
| QAudioEngine::OutputMode | outputMode() const |
| void | setOutputMode(QAudioEngine::OutputMode mode) |
Signal de notification :
| void | outputModeChanged() |
Voir également QAudioEngine::OutputMode.
paused : bool
Met en pause le moteur audio spatial.
Fonctions d'accès :
| bool | paused() const |
| void | setPaused(bool paused) |
Signal de notification :
| void | pausedChanged() |
Documentation des fonctions membres
QAudioEngine::QAudioEngine()
[explicit] QAudioEngine::QAudioEngine(QObject *parent)
[explicit] QAudioEngine::QAudioEngine(int sampleRate, QObject *parent = nullptr)
Crée un moteur audio spatial à l'aide de ` parent`, s'il existe.
Le moteur fonctionnera avec une fréquence d'échantillonnage définie par sampleRate. Si aucune fréquence n'est fournie, la valeur par défaut est 44100 (44,1 kHz).
Les contenus sonores qui ne sont pas fournis à cette fréquence d'échantillonnage seront automatiquement rééchantillonnés à sampleRate lors de leur traitement par le moteur. La fréquence d'échantillonnage par défaut convient dans la plupart des cas, mais vous pouvez définir une fréquence différente si la plupart de vos fichiers audio sont échantillonnés à une fréquence différente, ce qui vous permettra d'éviter une charge supplémentaire sur le processeur liée au rééchantillonnage.
[override virtual noexcept] QAudioEngine::~QAudioEngine()
Détruit le moteur audio spatial.
[slot] void QAudioEngine::pause()
Met la lecture en pause.
[slot] void QAudioEngine::resume()
Reprend la lecture.
bool QAudioEngine::roomEffectsEnabled() const
Renvoie « true » si les effets de salle sont activés.
Voir aussi setRoomEffectsEnabled().
int QAudioEngine::sampleRate() const
Renvoie la fréquence d'échantillonnage avec laquelle le moteur a été configuré.
void QAudioEngine::setRoomEffectsEnabled(bool enabled)
Active les effets de pièce tels que les échos et la réverbération.
Active les effets de pièce si la variable « enabled » a la valeur « true ». Les effets de pièce ne s'appliquent que si vous créez un ou plusieurs objets « QAudioRoom » et que l'auditeur se trouve à l'intérieur d'au moins une de ces pièces. Si l'auditeur se trouve à l'intérieur de plusieurs pièces, c'est celle dont le volume est le plus petit qui sera utilisée.
Voir également roomEffectsEnabled().
[slot] void QAudioEngine::start()
Démarre le moteur.
[slot] void QAudioEngine::stop()
Arrête le moteur.
© 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.
