QSpatialSound Class
3차원 공간에 있는 사운드 객체. 더 보기...
| 헤더: | #include <QSpatialSound> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio) target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake: | QT += spatialaudio |
| 상속: | QObject |
공개 유형
| enum class | DistanceModel { Logarithmic, Linear, ManualAttenuation } |
| enum | Loops { Infinite, Once } |
속성
|
|
공개 함수
| 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 |
공개 슬롯
신호
| 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() |
상세 설명
QSpatialSound는 3D 공간 내의 청각적 객체를 나타냅니다. 공간 내에서의 위치와 방향을 정의하고, 재생할 사운드를 설정하며, 객체의 음량을 정의할 수 있습니다.
이 객체는 다양한 감쇠 특성을 가질 수 있으며, 주로 한 방향으로 또는 구형으로 소리를 방출할 수 있고, 다른 객체에 의해 가려진 것처럼 행동할 수도 있습니다.
멤버 유형 문서
enum class QSpatialSound::DistanceModel
소리의 음량이 청취자와의 거리에 따라 어떻게 변화하는지를 정의합니다.
| 상수 | 값 | 설명 |
|---|---|---|
QSpatialSound::DistanceModel::Logarithmic | 0 | 소리의 크기는 거리에 따라 대수적으로 감소합니다. |
QSpatialSound::DistanceModel::Linear | 1 | 거리에 따라 볼륨이 선형적으로 감소합니다. |
QSpatialSound::DistanceModel::ManualAttenuation | 2 | 감쇠는 ‘ manualAttenuation ’ 속성을 사용하여 수동으로 정의됩니다. |
enum QSpatialSound::Loops
다음 값을 사용하여 사운드 재생 루프를 제어할 수 있습니다:
| 상수 | 값 | 설명 |
|---|---|---|
QSpatialSound::Infinite | -1 | 무한 반복 재생 |
QSpatialSound::Once | 1 | 한 번만 재생 |
속성 설명
autoPlay : bool
소스가 지정되면 소리가 자동으로 재생될지 여부를 결정합니다.
기본값은 ` true`입니다.
액세스 함수:
| bool | autoPlay() const |
| void | setAutoPlay(bool autoPlay) |
알림 신호:
| void | autoPlayChanged() |
directivity : float
음원의 지향성을 정의합니다. 값이 0이면 소리가 모든 방향으로 균등하게 방출되는 것을 의미하며, 값이 1이면 음원이 주로 정방향으로 소리를 방출하는 것을 의미합니다.
유효한 값은 0에서 1 사이이며, 기본값은 0입니다.
액세스 함수:
| float | directivity() const |
| void | setDirectivity(float alpha) |
알림 신호:
| void | directivityChanged() |
directivityOrder : float
음원의 지향성 차수를 정의합니다. 차수가 높을수록 음뿔의 위치 파악이 더 정확해집니다.
이 속성의 최소값이자 기본값은 1입니다.
액세스 함수:
| float | directivityOrder() const |
| void | setDirectivityOrder(float alpha) |
알림 신호:
| void | directivityOrderChanged() |
distanceCutoff : float
음원이 내는 소리가 더 이상 들리지 않게 되는 거리를 정의합니다. 청취자가 소스 오브젝트로부터 컷오프 거리보다 더 멀리 떨어져 있으면 소리가 더 이상 들리지 않습니다.
액세스 함수:
| float | distanceCutoff() const |
| void | setDistanceCutoff(float cutoff) |
알림 신호:
| void | distanceCutoffChanged() |
distanceModel : DistanceModel
이 음원에 대한 거리 모델을 정의합니다. 음량은 size 에서 distanceCutoff 로 점차 감소합니다. 거리가 ‘size’보다 작을 때는 음량이 일정하게 유지되며, ‘cutoff distance’보다 클 때는 음량이 0이 됩니다.
액세스 함수:
| QSpatialSound::DistanceModel | distanceModel() const |
| void | setDistanceModel(QSpatialSound::DistanceModel model) |
알림 신호:
| void | distanceModelChanged() |
QSpatialSound::DistanceModel도 참조하십시오 .
loops : int
플레이어가 중지되기 전까지 소리가 재생되는 횟수를 결정합니다. ‘ QSpatialSound::Infinite ’로 설정하면 현재 소리가 무한히 반복 재생됩니다.
기본값은 1 입니다.
액세스 함수:
| int | loops() const |
| void | setLoops(int loops) |
알림 신호:
| void | loopsChanged() |
manualAttenuation : float
distanceModel 가 QSpatialSound::DistanceModel::ManualAttenuation 로 설정된 경우 수동 감쇠 계수를 정의합니다.
액세스 기능:
| float | manualAttenuation() const |
| void | setManualAttenuation(float attenuation) |
알림 신호:
| void | manualAttenuationChanged() |
nearFieldGain : float
음원의 근거리 이득을 정의합니다. 유효한 값은 0에서 1 사이입니다. 근거리 이득을 1로 설정하면 청취자와 매우 가까운 거리에서 음향 신호의 음량이 약 20 dB 증가합니다.
액세스 기능:
| float | nearFieldGain() const |
| void | setNearFieldGain(float gain) |
알림 신호:
| void | nearFieldGainChanged() |
occlusionIntensity : float
객체가 얼마나 가려지는지를 정의합니다. 0은 객체가 전혀 가려지지 않음을, 1은 음원이 다른 객체에 의해 완전히 가려짐을 의미합니다.
완전히 가려진 물체도 여전히 소리가 들리지만, 특히 고주파 대역의 소리는 감쇠됩니다. 또한, 해당 물체는 여전히 실내의 잔향과 반사음을 생성하는 데 기여합니다.
1보다 큰 값을 설정하면 음원에서 나오는 직접음을 더욱 약화시킬 수 있습니다.
기본값은 0입니다.
액세스 함수:
| float | occlusionIntensity() const |
| void | setOcclusionIntensity(float occlusion) |
알림 신호:
| void | occlusionIntensityChanged() |
position : QVector3D
3차원 공간에서 음원의 위치를 정의합니다. 기본 단위는 센티미터입니다.
액세스 함수:
| QVector3D | position() const |
| void | setPosition(QVector3D pos) |
알림 신호:
| void | positionChanged() |
QAudioEngine::distanceScale도 참조하십시오 .
rotation : QQuaternion
3차원 공간에서 음원의 방향을 정의합니다.
액세스 함수:
| QQuaternion | rotation() const |
| void | setRotation(const QQuaternion &q) |
알림 신호:
| void | rotationChanged() |
size : float
음원의 크기를 정의합니다. 청취자가 음원보다 이 크기보다 더 가까이 있을 경우, 음량은 일정하게 유지됩니다. 또한 이 크기는 가림 현상 계산에도 사용되며, 이 경우 큰 음원은 벽에 의해 부분적으로 가려질 수 있습니다.
액세스 함수:
| float | size() const |
| void | setSize(float size) |
알림 신호:
| void | sizeChanged() |
source : QUrl
재생할 사운드의 소스 파일입니다.
액세스 함수:
| QUrl | source() const |
| void | setSource(const QUrl &url) |
알림 신호:
| void | sourceChanged() |
volume : float
소리의 음량을 설정합니다.
0에서 1 사이의 값은 소리를 감쇠시키고, 1보다 큰 값은 추가적인 게인 부스트를 제공합니다.
액세스 함수:
| float | volume() const |
| void | setVolume(float volume) |
알림 신호:
| void | volumeChanged() |
멤버 함수 문서
[explicit] QSpatialSound::QSpatialSound(QAudioEngine *engine)
engine 용 공간 음원을 생성합니다. 이 오브젝트는 3D 공간에 배치할 수 있으며, 청취자에게 가까울수록 소리가 더 크게 들립니다.
참고: 유효한 QAudioEngine
[override virtual noexcept] QSpatialSound::~QSpatialSound()
음원을 파괴합니다.
QAudioEngine *QSpatialSound::engine() const
이 리스너와 연결된 엔진을 반환합니다.
[slot] void QSpatialSound::pause()
소리 재생을 일시 중지합니다. ` play()`를 호출하면 재생을 계속합니다.
[slot] void QSpatialSound::play()
소리 재생을 시작합니다. 소리가 이미 재생 중이라면 아무 작업도 수행하지 않습니다.
[slot] void QSpatialSound::stop()
사운드 재생을 중지하고 현재 위치와 현재 루프 횟수를 0으로 재설정합니다. ` play()`를 호출하면 사운드 파일의 시작 부분부터 재생을 시작합니다.
© 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.
