Document the coordinate system being used by QAudioEngine

And fix the example to correctly position the sound source around
the listener.

Change-Id: I66035e22a47902552f08e3dac0cb1ee31608bb59
Reviewed-by: Paul Olav Tvete <paul.tvete@qt.io>

4 files changed, 26 insertions, 9 deletions

diff --git a/examples/multimedia/spatialaudio/main.cpp b/examples/multimedia/spatialaudio/main.cpp
index 5124be431..b49396013 100644
--- a/examples/multimedia/spatialaudio/main.cpp
+++ b/examples/multimedia/spatialaudio/main.cpp
@@ -146,17 +146,17 @@ private slots:
         float d = distance->value();
 
         float x = d*sin(az)*cos(el);
-        float y = d*cos(az)*cos(el);
-        float z = d*sin(el);
+        float y = d*sin(el);
+        float z = -d*cos(az)*cos(el);
         sound->setPosition({x, y, z});
     }
     void newOcclusion()
     {
         sound->setOcclusionIntensity(occlusion->value()/100.);
     }
-    void useHeadphoneChanged(int state)
+    void modeChanged()
     {
-        engine.setOutputMode(state ? QAudioEngine::Headphone : QAudioEngine::Normal);
+        engine.setOutputMode(mode->currentData().value<QAudioEngine::OutputMode>());
     }
     void fileChanged(const QString &file)
     {
diff --git a/src/multimedia/spatial/qaudioengine.cpp b/src/multimedia/spatial/qaudioengine.cpp
index db3bfc80e..c88251b34 100644
--- a/src/multimedia/spatial/qaudioengine.cpp
+++ b/src/multimedia/spatial/qaudioengine.cpp
@@ -323,11 +323,15 @@ QVector3D QAudioEnginePrivate::listenerPosition() const
     effects for an average persons ears and head. It provides a good and immersive 3D sound localization
     experience for most persons when using headphones.
 
-    The engine is rather versatile allowing you to define amd emulate room properties and reverb settings emulating
+    The engine is rather versatile allowing you to define room properties and reverb settings to emulate
     different types of rooms.
 
     Sound sources can also be occluded dampening the sound coming from those sources.
 
+    The audio engine uses a coordinate system that is in centimeters by default. The axes are aligned with the
+    typical coordinate system used in 3D. Positive x points to the right, positive y points up and positive z points
+    backwards.
+
 */
 
 /*!
diff --git a/src/multimedia/spatial/qaudioroom.cpp b/src/multimedia/spatial/qaudioroom.cpp
index 0edbd2b97..adb35d67f 100644
--- a/src/multimedia/spatial/qaudioroom.cpp
+++ b/src/multimedia/spatial/qaudioroom.cpp
@@ -103,6 +103,15 @@ struct {
 
 }
 
+// make sure the wall definitions agree with resonance audio
+
+static_assert(QAudioRoom::LeftWall == 0);
+static_assert(QAudioRoom::RightWall == 1);
+static_assert(QAudioRoom::Floor == 2);
+static_assert(QAudioRoom::Ceiling == 3);
+static_assert(QAudioRoom::FrontWall == 4);
+static_assert(QAudioRoom::BackWall == 5);
+
 float QAudioRoomPrivate::wallOcclusion(QAudioRoom::Wall wall) const
 {
     return m_wallOcclusion[wall] < 0 ? occlusionAndDampening[roomProperties.material_names[wall]].occlusion : m_wallOcclusion[wall];
@@ -203,10 +212,10 @@ QAudioRoom::~QAudioRoom()
 
     \value LeftWall Left wall (negative x)
     \value RightWall Right wall (positive x)
-    \value BackWall Back wall (negative y)
-    \value FrontWall Front wall (positive y)
-    \value Floor Bottom wall (negative z)
-    \value Ceiling Top wall (positive z)
+    \value Floor Bottom wall (negative y)
+    \value Ceiling Top wall (positive y)
+    \value FrontWall Front wall (negative z)
+    \value BackWall Back wall (positive z)
 */
 
 
diff --git a/src/multimediaquick3d/qquick3daudioengine.cpp b/src/multimediaquick3d/qquick3daudioengine.cpp
index 9a4770817..5bf7608af 100644
--- a/src/multimediaquick3d/qquick3daudioengine.cpp
+++ b/src/multimediaquick3d/qquick3daudioengine.cpp
@@ -67,6 +67,10 @@ static QAudioEngine *globalEngine = nullptr;
     using head related impulse reponse functions (see also https://en.wikipedia.org/wiki/Sound_localization)
     to localize the sound in 3D space when using headphones and create a spatial audio effect through
     headphones.
+
+    As the rest of Qt Quick 3D, the audio engine uses a coordinate system that is in centimeters by default.
+    The axes are defined so that positive x points to the right, positive y points up and positive z points
+    backwards.
 */