QSpatialSound Class
3D 공간의 사운드 오브젝트. 더 보기...
| 헤더: | #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
청취자와의 거리에 따라 사운드의 볼륨을 조절하는 방법을 정의합니다.
| Constant | 값 | 설명 |
|---|---|---|
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 로 축소되기 시작합니다. 크기보다 작은 거리에서는 볼륨이 일정하고 컷오프 거리보다 큰 거리에서는 볼륨이 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이면 청취자와 매우 가까운 거리에서 사운드 신호의 볼륨이 약 20dB 증가합니다.
기능에 액세스합니다:
| 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
3D 공간에서 음원의 위치를 정의합니다. 단위는 기본적으로 센티미터입니다.
기능에 액세스합니다:
| QVector3D | position() const |
| void | setPosition(QVector3D pos) |
알림 신호:
| void | positionChanged() |
QAudioEngine::distanceScale 를참조하세요 .
rotation : QQuaternion
3D 공간에서 음원의 방향을 정의합니다.
기능에 액세스합니다:
| 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 공간에 배치할 수 있으며 청취자와 가까울수록 더 크게 들립니다.
[override virtual noexcept] QSpatialSound::~QSpatialSound()
음원을 삭제합니다.
QAudioEngine *QSpatialSound::engine() const
이 리스너와 연관된 엔진을 반환합니다.
[slot] void QSpatialSound::pause()
사운드 재생을 일시 중지합니다. play ()를 호출하면 재생이 계속됩니다.
[slot] void QSpatialSound::play()
사운드 재생을 시작합니다. 사운드가 이미 재생 중이면 아무 작업도 수행하지 않습니다.
[slot] void QSpatialSound::stop()
사운드 재생을 중지하고 현재 위치와 현재 루프 횟수를 0으로 초기화합니다. play()를 호출하면 사운드 파일의 시작 부분부터 재생이 시작됩니다.
© 2025 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.
