QSpatialSound Class
Un objeto sonoro en el espacio 3D. Más...
| Cabecera: | #include <QSpatialSound> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio)target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake: | QT += spatialaudio |
| Hereda: | 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 emite y definir un volumen para el objeto.
El objeto puede tener diferentes comportamientos de atenuación, emitir sonido principalmente en una dirección o esféricamente, y comportarse como si estuviera ocluido por algún otro objeto.
Documentación de los tipos de miembros
enum class QSpatialSound::DistanceModel
Define cómo escala el volumen del sonido con la distancia al oyente.
| Constante | Valor | Descripción |
|---|---|---|
QSpatialSound::DistanceModel::Logarithmic | 0 | El volumen disminuye logarítmicamente 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
Le permite controlar el bucle de reproducción de sonido utilizando los siguientes valores:
| Constante | Valor | Descripción |
|---|---|---|
QSpatialSound::Infinite | -1 | Reproducción infinita |
QSpatialSound::Once | 1 | Reproducir una vez |
Documentación de propiedades
autoPlay : bool
Determina si el sonido debe empezar a 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 del notificador:
| 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 en la dirección 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 del notificador:
| 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 nítida del cono sonoro.
El valor mínimo y por defecto de esta propiedad es 1.
Funciones de acceso:
| float | directivityOrder() const |
| void | setDirectivityOrder(float alpha) |
Señal notificadora:
| void | directivityOrderChanged() |
distanceCutoff : float
Define una distancia a partir de la cual el sonido procedente de la fuente se corta. Si el oyente está más lejos del objeto sonoro que la distancia de corte, éste dejará de ser audible.
Funciones de acceso:
| float | distanceCutoff() const |
| void | setDistanceCutoff(float cutoff) |
Señal de aviso:
| void | distanceCutoffChanged() |
distanceModel : DistanceModel
Define el modelo de distancia para esta fuente de sonido. El volumen empieza a bajar de size a distanceCutoff. El volumen es constante para distancias menores que el tamaño y cero para distancias mayores que la distancia de corte.
Funciones de acceso:
| QSpatialSound::DistanceModel | distanceModel() const |
| void | setDistanceModel(QSpatialSound::DistanceModel model) |
Señal notificadora:
| 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. Establézcalo en QSpatialSound::Infinite para reproducir el sonido actual en bucle para siempre.
El valor por defecto es 1.
Funciones de acceso:
| int | loops() const |
| void | setLoops(int loops) |
Señal del notificador:
| void | loopsChanged() |
manualAttenuation : float
Define un factor de atenuación manual si distanceModel está ajustado a QSpatialSound::DistanceModel::ManualAttenuation.
Funciones de acceso:
| float | manualAttenuation() const |
| void | setManualAttenuation(float attenuation) |
Señal de aviso:
| void | manualAttenuationChanged() |
nearFieldGain : float
Define la ganancia de campo cercano para la fuente de sonido. Los valores válidos están entre 0 y 1. Una ganancia de campo cercano de 1 aumentará el volumen de la señal sonora en aproximadamente 20 dB para distancias muy cercanas al oyente.
Funciones de acceso:
| float | nearFieldGain() const |
| void | setNearFieldGain(float gain) |
Señal del avisador:
| void | nearFieldGainChanged() |
occlusionIntensity : float
Define el grado de oclusión del objeto. 0 implica que el objeto no está ocluido en absoluto, 1 implica que la fuente de sonido está totalmente ocluida por otro objeto.
Un objeto totalmente ocluido seguirá siendo audible, pero se amortiguará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.
Es posible utilizar valores superiores a 1 para amortiguar 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 del notificador:
| void | occlusionIntensityChanged() |
position : QVector3D
Define la posición de la fuente de sonido en el espacio 3D. Por defecto, las unidades están en centímetros.
Funciones de acceso:
| QVector3D | position() const |
| void | setPosition(QVector3D pos) |
Señal del notificador:
| void | positionChanged() |
Véase también QAudioEngine::distanceScale.
rotation : QQuaternion
Define la orientación de la fuente sonora en el espacio 3D.
Funciones de acceso:
| QQuaternion | rotation() const |
| void | setRotation(const QQuaternion &q) |
Señal del notificador:
| void | rotationChanged() |
size : float
Define el tamaño de la fuente sonora. Si el oyente está más cerca del objeto sonoro que el tamaño, el volumen se mantendrá constante. El tamaño también se utiliza para los cálculos de oclusión, en los que las fuentes grandes pueden quedar parcialmente ocluidas por una pared.
Funciones de acceso:
| float | size() const |
| void | setSize(float size) |
Señal del notificador:
| 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 aviso:
| 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 del notificador:
| void | volumeChanged() |
Documentación de las funciones miembro
[explicit] QSpatialSound::QSpatialSound(QAudioEngine *engine)
Crea una fuente de sonido espacial para engine. El objeto puede colocarse en un espacio tridimensional y será más fuerte cuanto más cerca esté del oyente.
[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 del sonido. Llamando a play() continuará la reproducción.
[slot] void QSpatialSound::play()
Inicia la reproducción del 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 la cuenta de bucles actual a 0. Si se llama a play(), la reproducción comenzará al 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.
