QSpatialSound Class
Un objeto sonoro en el espacio 3D. Más...
| Encabezado: | #include <QSpatialSound> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio) target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake: | QT += spatialaudio |
| Heredado de: | QObject |
Tipos públicos
| enum class | DistanceModel { Logarithmic, Linear, ManualAttenuation } |
| enum | Loops { Infinite, Once } |
Propiedades
|
|
Funciones públicas
| 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 |
Ranuras públicas
Señales
| 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() |
Descripción detallada
QSpatialSound representa un objeto audible en el espacio 3D. Se puede definir su posición y orientación en el espacio, establecer el sonido que reproduce y definir el volumen del objeto.
El objeto puede presentar diferentes comportamientos de atenuación, emitir sonido principalmente en una dirección o de forma esférica, y comportarse como si estuviera oculto por algún otro objeto.
Documentación sobre los tipos de miembros
enum class QSpatialSound::DistanceModel
Define cómo varía el volumen del sonido en función de la distancia al oyente.
| Constante | Valor | Descripción |
|---|---|---|
QSpatialSound::DistanceModel::Logarithmic | 0 | El volumen disminuye de forma logarítmica con la distancia. |
QSpatialSound::DistanceModel::Linear | 1 | El volumen disminuye linealmente con la distancia. |
QSpatialSound::DistanceModel::ManualAttenuation | 2 | La atenuación se define manualmente mediante la propiedad « manualAttenuation ». |
enum QSpatialSound::Loops
Te permite controlar el bucle de reproducción del sonido mediante los siguientes valores:
| Constante | Valor | Descripción |
|---|---|---|
QSpatialSound::Infinite | -1 | Reproducción infinita |
QSpatialSound::Once | 1 | Reproducción única |
Documentación de la propiedad
autoPlay : bool
Determina si el sonido debe reproducirse automáticamente cuando se especifica una fuente.
El valor por defecto es « true ».
Funciones de acceso:
| bool | autoPlay() const |
| void | setAutoPlay(bool autoPlay) |
Señal de notificación:
| void | autoPlayChanged() |
directivity : float
Define la directividad de la fuente de sonido. Un valor de 0 implica que el sonido se emite por igual en todas las direcciones, mientras que un valor de 1 implica que la fuente emite sonido principalmente hacia delante.
Los valores válidos están comprendidos entre 0 y 1; el valor por defecto es 0.
Funciones de acceso:
| float | directivity() const |
| void | setDirectivity(float alpha) |
Señal de notificación:
| void | directivityChanged() |
directivityOrder : float
Define el orden de la directividad de la fuente sonora. Un orden más alto implica una localización más precisa del cono sonoro.
El valor mínimo y predeterminado de esta propiedad es 1.
Funciones de acceso:
| float | directivityOrder() const |
| void | setDirectivityOrder(float alpha) |
Señal de notificación:
| void | directivityOrderChanged() |
distanceCutoff : float
Define una distancia más allá de la cual el sonido procedente de la fuente se cortará. Si el oyente se encuentra más lejos del objeto sonoro que la distancia de corte, ya no se oirá.
Funciones de acceso:
| float | distanceCutoff() const |
| void | setDistanceCutoff(float cutoff) |
Señal de notificación:
| void | distanceCutoffChanged() |
distanceModel : DistanceModel
Define el modelo de distancia para esta fuente de sonido. El volumen comienza a reducirse progresivamente desde size hasta distanceCutoff. El volumen es constante para distancias inferiores a «size» y es cero para distancias superiores a la distancia de corte.
Funciones de acceso:
| QSpatialSound::DistanceModel | distanceModel() const |
| void | setDistanceModel(QSpatialSound::DistanceModel model) |
Señal de notificación:
| void | distanceModelChanged() |
Véase también QSpatialSound::DistanceModel.
loops : int
Determina cuántas veces se reproduce el sonido antes de que el reproductor se detenga. Establece el valor en « QSpatialSound::Infinite » para reproducir el sonido actual en bucle de forma indefinida.
El valor por defecto es « 1 ».
Funciones de acceso:
| int | loops() const |
| void | setLoops(int loops) |
Señal de notificación:
| void | loopsChanged() |
manualAttenuation : float
Define un factor de atenuación manual si la opción « distanceModel » está configurada en « QSpatialSound::DistanceModel::ManualAttenuation ».
Funciones de acceso:
| float | manualAttenuation() const |
| void | setManualAttenuation(float attenuation) |
Señal del notificador:
| void | manualAttenuationChanged() |
nearFieldGain : float
Define la ganancia en campo cercano de la fuente de sonido. Los valores válidos están comprendidos entre 0 y 1. Una ganancia en campo cercano de 1 aumentará el volumen de la señal de sonido en aproximadamente 20 dB a distancias muy cercanas al oyente.
Funciones de acceso:
| float | nearFieldGain() const |
| void | setNearFieldGain(float gain) |
Señal de notificación:
| void | nearFieldGainChanged() |
occlusionIntensity : float
Define en qué medida el objeto está ocluido. El valor 0 indica que el objeto no está ocluido en absoluto, mientras que el valor 1 indica que la fuente de sonido está totalmente ocluida por otro objeto.
Un objeto totalmente ocluido seguirá siendo audible, pero se atenuarán especialmente las frecuencias más altas. Además, el objeto seguirá participando en la generación de reverberación y reflexiones en la sala.
Se pueden utilizar valores superiores a 1 para atenuar aún más el sonido directo procedente de la fuente.
El valor por defecto es 0.
Funciones de acceso:
| float | occlusionIntensity() const |
| void | setOcclusionIntensity(float occlusion) |
Señal de notificación:
| void | occlusionIntensityChanged() |
position : QVector3D
Define la posición de la fuente de sonido en el espacio 3D. Las unidades predeterminadas son los centímetros.
Funciones de acceso:
| QVector3D | position() const |
| void | setPosition(QVector3D pos) |
Señal de notificación:
| void | positionChanged() |
Véase también QAudioEngine::distanceScale.
rotation : QQuaternion
Define la orientación de la fuente de sonido en el espacio 3D.
Funciones de acceso:
| QQuaternion | rotation() const |
| void | setRotation(const QQuaternion &q) |
Señal de notificación:
| void | rotationChanged() |
size : float
Define el tamaño de la fuente sonora. Si el oyente se encuentra más cerca del objeto sonoro que el tamaño indicado, el volumen se mantendrá constante. El tamaño también se utiliza para los cálculos de oclusión, en los que las fuentes de gran tamaño pueden quedar parcialmente ocultas por una pared.
Funciones de acceso:
| float | size() const |
| void | setSize(float size) |
Señal de notificación:
| void | sizeChanged() |
source : QUrl
El archivo fuente del sonido que se va a reproducir.
Funciones de acceso:
| QUrl | source() const |
| void | setSource(const QUrl &url) |
Señal de notificación:
| void | sourceChanged() |
volume : float
Define el volumen del sonido.
Los valores entre 0 y 1 atenúan el sonido, mientras que los valores superiores a 1 proporcionan un aumento adicional de la ganancia.
Funciones de acceso:
| float | volume() const |
| void | setVolume(float volume) |
Señal de notificación:
| void | volumeChanged() |
Documentación de funciones de miembro
[explicit] QSpatialSound::QSpatialSound(QAudioEngine *engine)
Crea una fuente de sonido espacial para engine. El objeto se puede colocar en el espacio 3D y su volumen será mayor cuanto más cerca esté del oyente.
Nota: Debe invocarse con un QAudioEngine
[override virtual noexcept] QSpatialSound::~QSpatialSound()
Destruye la fuente de sonido.
QAudioEngine *QSpatialSound::engine() const
Devuelve el motor asociado a este oyente.
[slot] void QSpatialSound::pause()
Detiene la reproducción de sonido. Al llamar a play() se reanudará la reproducción.
[slot] void QSpatialSound::play()
Comienza a reproducir el sonido. No hace nada si el sonido ya se está reproduciendo.
[slot] void QSpatialSound::stop()
Detiene la reproducción del sonido y restablece la posición actual y el contador de repeticiones a 0. Al llamar a ` play()` se iniciará la reproducción desde el principio del archivo de sonido.
© 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.