En esta página

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

void pause()
void play()
void stop()

Señales

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.

ConstanteValorDescripción
QSpatialSound::DistanceModel::Logarithmic0El volumen disminuye de forma logarítmica con la distancia.
QSpatialSound::DistanceModel::Linear1El volumen disminuye linealmente con la distancia.
QSpatialSound::DistanceModel::ManualAttenuation2La 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:

ConstanteValorDescripción
QSpatialSound::Infinite-1Reproducción infinita
QSpatialSound::Once1Reproducció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.