Some smaller API fixes to QSpatialAudioSoundSource

Try to improve/clarify naming of properties.

Change-Id: Idd610a95a196c127bfa0922f5a711ab2e483dcbf
Reviewed-by: Piotr Srebrny <piotr.srebrny@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

6 files changed, 74 insertions, 67 deletions

diff --git a/examples/multimedia/spatialaudio/main.cpp b/examples/multimedia/spatialaudio/main.cpp
index 27c1bfa16..e7ba56962 100644
--- a/examples/multimedia/spatialaudio/main.cpp
+++ b/examples/multimedia/spatialaudio/main.cpp
@@ -79,8 +79,8 @@ public:
         grid->addWidget(new QLabel(tr("Distance (0 - 10 meter):")), 3, 0);
         grid->addWidget(distance, 3, 1);
         occlusion = new QSlider(Qt::Horizontal);
-        occlusion->setRange(0, 200);
-        grid->addWidget(new QLabel(tr("Occlusion (0 - 2):")), 4, 0);
+        occlusion->setRange(0, 400);
+        grid->addWidget(new QLabel(tr("Occlusion (0 - 4):")), 4, 0);
         grid->addWidget(occlusion, 4, 1);
 
         roomDimension = new QSlider(Qt::Horizontal);
@@ -162,7 +162,7 @@ private slots:
     void fileChanged(const QString &file)
     {
         sound->setSource(QUrl::fromLocalFile(file));
-        sound->setMinimumDistance(5);
+        sound->setSize(5);
     }
     void openFileDialog()
     {
diff --git a/src/multimedia/spatial/qspatialaudiosoundsource.cpp b/src/multimedia/spatial/qspatialaudiosoundsource.cpp
index 2fd6ecef1..7384d85ee 100644
--- a/src/multimedia/spatial/qspatialaudiosoundsource.cpp
+++ b/src/multimedia/spatial/qspatialaudiosoundsource.cpp
@@ -158,7 +158,9 @@ float QSpatialAudioSoundSource::volume() const
 /*!
     \property QSpatialAudioSoundSource::distanceModel
 
-    Defines distance model for this sound source.
+    Defines distance model for this sound source. The volume starts scaling down
+    from \l size to \l distanceCutoff. The volume is constant for distances smaller
+    than size and zero for distances larger than the cutoff distance.
 
     \sa QSpatialAudioSoundSource::DistanceModel
  */
@@ -190,7 +192,7 @@ void QSpatialAudioSoundSourcePrivate::updateDistanceModel()
         break;
     }
 
-    ep->api->SetSourceDistanceModel(sourceId, dm, minDistance, maxDistance);
+    ep->api->SetSourceDistanceModel(sourceId, dm, size, distanceCutoff);
 }
 
 void QSpatialAudioSoundSourcePrivate::updateRoomEffects()
@@ -230,7 +232,7 @@ void QSpatialAudioSoundSourcePrivate::updateRoomEffects()
         };
         // Very rough approximation, use the size of the source plus twice the size of our head.
         // One could probably improve upon this.
-        const float transitionDistance = minDistance + 0.4;
+        const float transitionDistance = size + 0.4;
         QSpatialAudioRoom::Wall walls[3];
         walls[X] = direction.x() > 0 ? QSpatialAudioRoom::RightWall : QSpatialAudioRoom::LeftWall;
         walls[Y] = direction.y() > 0 ? QSpatialAudioRoom::FrontWall : QSpatialAudioRoom::BackWall;
@@ -303,46 +305,47 @@ QSpatialAudioSoundSource::DistanceModel QSpatialAudioSoundSource::distanceModel(
 }
 
 /*!
-    \property QSpatialAudioSoundSource::minimumDistance
+    \property QSpatialAudioSoundSource::size
 
-    Defines a minimum distance for the sound source. If the listener is closer to the sound
-    object than the minimum distance, volume will stay constant and the sound source won't
-    be localized in space.
+    Defines the size of the sound source. If the listener is closer to the sound
+    object than the size, volume will stay constant. The size is also used to for
+    occlusion calculations, where large sources can be partially occluded by a wall.
  */
-void QSpatialAudioSoundSource::setMinimumDistance(float min)
+void QSpatialAudioSoundSource::setSize(float min)
 {
-    if (d->minDistance == min)
+    if (d->size == min)
         return;
-    d->minDistance = min;
+    d->size = min;
 
     d->updateDistanceModel();
-    emit minimumDistanceChanged();
+    emit sizeChanged();
 }
 
-float QSpatialAudioSoundSource::minimumDistance() const
+float QSpatialAudioSoundSource::size() const
 {
-    return d->minDistance;
+    return d->size;
 }
 
 /*!
-    \property QSpatialAudioSoundSource::maximumDistance
+    \property QSpatialAudioSoundSource::distanceCutoff
 
-    Defines a maximum distance for the sound source. If the listener is further away from
-    the sound object than the maximum distance it won't be audible anymore.
+    Defines a distance beyond which sound coming from the source will cutoff.
+    If the listener is further away from the sound object than the cutoff
+    distance it won't be audible anymore.
  */
-void QSpatialAudioSoundSource::setMaximumDistance(float max)
+void QSpatialAudioSoundSource::setDistanceCutoff(float max)
 {
-    if (d->maxDistance == max)
+    if (d->distanceCutoff == max)
         return;
-    d->maxDistance = max;
+    d->distanceCutoff = max;
 
     d->updateDistanceModel();
-    emit maximumDistanceChanged();
+    emit distanceCutoffChanged();
 }
 
-float QSpatialAudioSoundSource::maximumDistance() const
+float QSpatialAudioSoundSource::distanceCutoff() const
 {
-    return d->maxDistance;
+    return d->distanceCutoff;
 }
 
 /*!
diff --git a/src/multimedia/spatial/qspatialaudiosoundsource.h b/src/multimedia/spatial/qspatialaudiosoundsource.h
index 818512c68..e4e8d010c 100644
--- a/src/multimedia/spatial/qspatialaudiosoundsource.h
+++ b/src/multimedia/spatial/qspatialaudiosoundsource.h
@@ -56,8 +56,8 @@ class Q_MULTIMEDIA_EXPORT QSpatialAudioSoundSource : public QObject
     Q_PROPERTY(QQuaternion rotation READ rotation WRITE setRotation NOTIFY rotationChanged)
     Q_PROPERTY(float volume READ volume WRITE setVolume NOTIFY volumeChanged)
     Q_PROPERTY(DistanceModel distanceModel READ distanceModel WRITE setDistanceModel NOTIFY distanceModelChanged)
-    Q_PROPERTY(float minimumDistance READ minimumDistance WRITE setMinimumDistance NOTIFY minimumDistanceChanged)
-    Q_PROPERTY(float maximumDistance READ maximumDistance WRITE setMaximumDistance NOTIFY maximumDistanceChanged)
+    Q_PROPERTY(float size READ size WRITE setSize NOTIFY sizeChanged)
+    Q_PROPERTY(float distanceCutoff READ distanceCutoff WRITE setDistanceCutoff NOTIFY distanceCutoffChanged)
     Q_PROPERTY(float manualAttenuation READ manualAttenuation WRITE setManualAttenuation NOTIFY manualAttenuationChanged)
     Q_PROPERTY(float occlusionIntensity READ occlusionIntensity WRITE setOcclusionIntensity NOTIFY occlusionIntensityChanged)
     Q_PROPERTY(float directivity READ directivity WRITE setDirectivity NOTIFY directivityChanged)
@@ -105,11 +105,11 @@ public:
     void setDistanceModel(DistanceModel model);
     DistanceModel distanceModel() const;
 
-    void setMinimumDistance(float min);
-    float minimumDistance() const;
+    void setSize(float min);
+    float size() const;
 
-    void setMaximumDistance(float max);
-    float maximumDistance() const;
+    void setDistanceCutoff(float max);
+    float distanceCutoff() const;
 
     void setManualAttenuation(float attenuation);
     float manualAttenuation() const;
@@ -136,8 +136,8 @@ Q_SIGNALS:
     void rotationChanged();
     void volumeChanged();
     void distanceModelChanged();
-    void minimumDistanceChanged();
-    void maximumDistanceChanged();
+    void sizeChanged();
+    void distanceCutoffChanged();
     void manualAttenuationChanged();
     void occlusionIntensityChanged();
     void directivityChanged();
diff --git a/src/multimedia/spatial/qspatialaudiosoundsource_p.h b/src/multimedia/spatial/qspatialaudiosoundsource_p.h
index 3986857d0..83bd2d232 100644
--- a/src/multimedia/spatial/qspatialaudiosoundsource_p.h
+++ b/src/multimedia/spatial/qspatialaudiosoundsource_p.h
@@ -76,15 +76,15 @@ public:
     QVector3D pos;
     QQuaternion rotation;
     QSpatialAudioSoundSource::DistanceModel distanceModel = QSpatialAudioSoundSource::DistanceModel_Logarithmic;
-    float minDistance = .1;
-    float maxDistance = 50.;
-    float manualAttenuation = 0;
-    float occlusionIntensity = 0.;
-    float directivity = 0.;
-    float directivityOrder = 1.;
-    float nearFieldGain = 0.;
-    float wallDampening = 1.;
-    float wallOcclusion = 0.;
+    float size = .1f;
+    float distanceCutoff = 50.f;
+    float manualAttenuation = 0.f;
+    float occlusionIntensity = 0.f;
+    float directivity = 0.f;
+    float directivityOrder = 1.f;
+    float nearFieldGain = 0.f;
+    float wallDampening = 1.f;
+    float wallOcclusion = 0.f;
 
     void updateDistanceModel();
     void updateRoomEffects();
diff --git a/src/multimediaquick3d/qquick3dspatialaudiosoundsource.cpp b/src/multimediaquick3d/qquick3dspatialaudiosoundsource.cpp
index ff2fdebf4..2409871dd 100644
--- a/src/multimediaquick3d/qquick3dspatialaudiosoundsource.cpp
+++ b/src/multimediaquick3d/qquick3dspatialaudiosoundsource.cpp
@@ -66,8 +66,8 @@ QQuick3DSpatialAudioSoundSource::QQuick3DSpatialAudioSoundSource()
     connect(m_sound, &QSpatialAudioSoundSource::sourceChanged, this, &QQuick3DSpatialAudioSoundSource::sourceChanged);
     connect(m_sound, &QSpatialAudioSoundSource::volumeChanged, this, &QQuick3DSpatialAudioSoundSource::volumeChanged);
     connect(m_sound, &QSpatialAudioSoundSource::distanceModelChanged, this, &QQuick3DSpatialAudioSoundSource::distanceModelChanged);
-    connect(m_sound, &QSpatialAudioSoundSource::minimumDistanceChanged, this, &QQuick3DSpatialAudioSoundSource::minimumDistanceChanged);
-    connect(m_sound, &QSpatialAudioSoundSource::maximumDistanceChanged, this, &QQuick3DSpatialAudioSoundSource::maximumDistanceChanged);
+    connect(m_sound, &QSpatialAudioSoundSource::sizeChanged, this, &QQuick3DSpatialAudioSoundSource::sizeChanged);
+    connect(m_sound, &QSpatialAudioSoundSource::distanceCutoffChanged, this, &QQuick3DSpatialAudioSoundSource::distanceCutoffChanged);
     connect(m_sound, &QSpatialAudioSoundSource::manualAttenuationChanged, this, &QQuick3DSpatialAudioSoundSource::manualAttenuationChanged);
     connect(m_sound, &QSpatialAudioSoundSource::occlusionIntensityChanged, this, &QQuick3DSpatialAudioSoundSource::occlusionIntensityChanged);
     connect(m_sound, &QSpatialAudioSoundSource::directivityChanged, this, &QQuick3DSpatialAudioSoundSource::directivityChanged);
@@ -119,6 +119,9 @@ float QQuick3DSpatialAudioSoundSource::volume() const
     \qmlproperty enumeration SpatialAudioSoundSource::distanceModel
 
     Defines how the volume of the sound scales with distance to the listener.
+    The volume starts scaling down
+    from \l size to \l distanceCutoff. The volume is constant for distances smaller
+    than size and zero for distances larger than the cutoff distance.
 
     \table
     \header \li Property value
@@ -142,36 +145,37 @@ QQuick3DSpatialAudioSoundSource::DistanceModel QQuick3DSpatialAudioSoundSource::
 }
 
 /*!
-    \qmlproperty float SpatialAudioSoundSource::minimumDistance
+    \qmlproperty float SpatialAudioSoundSource::size
 
-    Defines a minimum distance for the sound source. If the listener is closer to the sound
-    object than the minimum distance, volume will stay constant and the sound source won't
-    be localized in space.
+    Defines the size of the sound source. If the listener is closer to the sound
+    object than the size, volume will stay constant. The size is also used to for
+    occlusion calculations, where large sources can be partially occluded by a wall.
  */
-void QQuick3DSpatialAudioSoundSource::setMinimumDistance(float min)
+void QQuick3DSpatialAudioSoundSource::setSize(float min)
 {
-    m_sound->setMinimumDistance(min);
+    m_sound->setSize(min);
 }
 
-float QQuick3DSpatialAudioSoundSource::minimumDistance() const
+float QQuick3DSpatialAudioSoundSource::size() const
 {
-    return m_sound->minimumDistance();
+    return m_sound->size();
 }
 
 /*!
-    \qmlproperty float SpatialAudioSoundSource::maximumDistance
+    \qmlproperty float SpatialAudioSoundSource::distanceCutoff
 
-    Defines a maximum distance for the sound source. If the listener is further away from
-    the sound object than the maximum distance it won't be audible anymore.
+    Defines a distance beyond which sound coming from the source will cutoff.
+    If the listener is further away from the sound object than the cutoff
+    distance it won't be audible anymore.
  */
-void QQuick3DSpatialAudioSoundSource::setMaximumDistance(float max)
+void QQuick3DSpatialAudioSoundSource::setDistanceCutoff(float max)
 {
-    m_sound->setMaximumDistance(max);
+    m_sound->setDistanceCutoff(max);
 }
 
-float QQuick3DSpatialAudioSoundSource::maximumDistance() const
+float QQuick3DSpatialAudioSoundSource::distanceCutoff() const
 {
-    return m_sound->maximumDistance();
+    return m_sound->distanceCutoff();
 }
 
 /*!
diff --git a/src/multimediaquick3d/qquick3dspatialaudiosoundsource_p.h b/src/multimediaquick3d/qquick3dspatialaudiosoundsource_p.h
index 29c74d21e..9cc835fe9 100644
--- a/src/multimediaquick3d/qquick3dspatialaudiosoundsource_p.h
+++ b/src/multimediaquick3d/qquick3dspatialaudiosoundsource_p.h
@@ -50,8 +50,8 @@ class QQuick3DSpatialAudioSoundSource : public QQuick3DNode
     Q_PROPERTY(QUrl source READ source WRITE setSource NOTIFY sourceChanged)
     Q_PROPERTY(float volume READ volume WRITE setVolume NOTIFY volumeChanged)
     Q_PROPERTY(DistanceModel distanceModel READ distanceModel WRITE setDistanceModel NOTIFY distanceModelChanged)
-    Q_PROPERTY(float minimumDistance READ minimumDistance WRITE setMinimumDistance NOTIFY minimumDistanceChanged)
-    Q_PROPERTY(float maximumDistance READ maximumDistance WRITE setMaximumDistance NOTIFY maximumDistanceChanged)
+    Q_PROPERTY(float size READ size WRITE setSize NOTIFY sizeChanged)
+    Q_PROPERTY(float distanceCutoff READ distanceCutoff WRITE setDistanceCutoff NOTIFY distanceCutoffChanged)
     Q_PROPERTY(float manualAttenuation READ manualAttenuation WRITE setManualAttenuation NOTIFY manualAttenuationChanged)
     Q_PROPERTY(float occlusionIntensity READ occlusionIntensity WRITE setOcclusionIntensity NOTIFY occlusionIntensityChanged)
     Q_PROPERTY(float directivity READ directivity WRITE setDirectivity NOTIFY directivityChanged)
@@ -81,11 +81,11 @@ public:
     void setDistanceModel(DistanceModel model);
     DistanceModel distanceModel() const;
 
-    void setMinimumDistance(float min);
-    float minimumDistance() const;
+    void setSize(float min);
+    float size() const;
 
-    void setMaximumDistance(float max);
-    float maximumDistance() const;
+    void setDistanceCutoff(float max);
+    float distanceCutoff() const;
 
     void setManualAttenuation(float attenuation);
     float manualAttenuation() const;
@@ -124,8 +124,8 @@ Q_SIGNALS:
     void sourceChanged();
     void volumeChanged();
     void distanceModelChanged();
-    void minimumDistanceChanged();
-    void maximumDistanceChanged();
+    void sizeChanged();
+    void distanceCutoffChanged();
     void manualAttenuationChanged();
     void occlusionIntensityChanged();
     void directivityChanged();