Add support for rooms to the spatial audio engine

The new QSpatialAudioRoom class allows defining a room.
If the listener is inside the room, the properties of that
room will get enabled, giving us first order reflections
and reverb.

Multiple rooms can be defined and the engine will automatically
update the room to be used when the listener position changes.
If the listener is inside multiple rooms, the room with the
smallest volume will get chosen.

Updated the spatialaudio example to allow modifying some
of the room properties for testing.

Change-Id: I94ffe0a6b7e570c4ea77898e021d7fe042fb9b52
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

3 files changed, 465 insertions, 0 deletions

diff --git a/src/multimediaquick3d/CMakeLists.txt b/src/multimediaquick3d/CMakeLists.txt
index d03192f77..af4639df8 100644
--- a/src/multimediaquick3d/CMakeLists.txt
+++ b/src/multimediaquick3d/CMakeLists.txt
@@ -14,6 +14,7 @@ qt_internal_add_qml_module(Quick3DSpatialAudioPrivate
     INTERNAL_MODULE
     SOURCES
         qquick3dspatialaudiolistener.cpp qquick3dspatialaudiolistener_p.h
+        qquick3dspatialaudioroom.cpp qquick3dspatialaudioroom_p.h
         qquick3dspatialaudiosoundsource.cpp qquick3dspatialaudiosoundsource_p.h
         qquick3dspatialaudiostereosource.cpp qquick3dspatialaudiostereosource_p.h
         qquick3dspatialaudioengine.cpp qquick3dspatialaudioengine_p.h
diff --git a/src/multimediaquick3d/qquick3dspatialaudioroom.cpp b/src/multimediaquick3d/qquick3dspatialaudioroom.cpp
new file mode 100644
index 000000000..d50b9d0ab
--- /dev/null
+++ b/src/multimediaquick3d/qquick3dspatialaudioroom.cpp
@@ -0,0 +1,312 @@
+/****************************************************************************
+**
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Spatial Audio module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL-NOGPL2$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+#include <qquick3dspatialaudioroom_p.h>
+#include <qquick3dspatialaudioengine_p.h>
+#include <qspatialaudioroom.h>
+
+QT_BEGIN_NAMESPACE
+
+/*!
+    \qmltype SpatialAudioRoom
+
+    Defines a room for the spatial audio engine.
+
+    If the listener is inside a room, first order sound reflections and reverb
+    matching the rooms properties will get applied to the sound field.
+
+    A room is always square and defined by it's center position, it's orientation and dimensions.
+    Each of the 6 walls of the room can be made of different materials that will contribute
+    to the computed reflections and reverb that the listener will experience while being inside
+    the room.
+
+    If multiple rooms cover the same position, the engine will use the room with the smallest
+    volume.
+ */
+
+/*!
+    Constructs a QQuick3DSpatialAudioRoom for \a engine.
+ */
+QQuick3DSpatialAudioRoom::QQuick3DSpatialAudioRoom()
+{
+    m_room = new QSpatialAudioRoom(QQuick3DSpatialAudioEngine::getEngine());
+
+    connect(this, &QQuick3DNode::scenePositionChanged, this, &QQuick3DSpatialAudioRoom::updatePosition);
+    connect(this, &QQuick3DNode::sceneRotationChanged, this, &QQuick3DSpatialAudioRoom::updateRotation);
+    connect(m_room, &QSpatialAudioRoom::dimensionsChanged, this, &QQuick3DSpatialAudioRoom::dimensionsChanged);
+    connect(m_room, &QSpatialAudioRoom::rotationChanged, this, &QQuick3DSpatialAudioRoom::rotationChanged);
+    connect(m_room, &QSpatialAudioRoom::wallsChanged, this, &QQuick3DSpatialAudioRoom::wallsChanged);
+    connect(m_room, &QSpatialAudioRoom::reflectionGainChanged, this, &QQuick3DSpatialAudioRoom::reflectionGainChanged);
+    connect(m_room, &QSpatialAudioRoom::reverbGainChanged, this, &QQuick3DSpatialAudioRoom::reverbGainChanged);
+    connect(m_room, &QSpatialAudioRoom::reverbTimeChanged, this, &QQuick3DSpatialAudioRoom::reverbTimeChanged);
+    connect(m_room, &QSpatialAudioRoom::reverbBrightnessChanged, this, &QQuick3DSpatialAudioRoom::reverbBrightnessChanged);
+}
+
+/*!
+    Destroys the room.
+ */
+QQuick3DSpatialAudioRoom::~QQuick3DSpatialAudioRoom()
+{
+    delete m_room;
+}
+
+/*!
+    \enum SpatialAudioRoom::Material
+
+    Defines different materials that can be applied to the different walls of the room.
+
+    \value Transparent The side of the room is open and won't contribute to reflections or reverb.
+    \value AcousticCeilingTiles Acoustic tiles that suppress most reflections and reverb.
+    \value BrickBare A bare brick wall.
+    \value BrickPainted A painted brick wall.
+    \value ConcreteBlockCoarse A raw concrete wall
+    \value ConcreteBlockPainted A painted concrete wall
+    \value CurtainHeavy A heavy curtain. Will mostly reflect low frequencies
+    \value FiberGlassInsulation Fiber glass insulation. Only reflects very low frequencies
+    \value GlassThin A thin glass wall
+    \value GlassThick A thick glass wall
+    \value Grass Grass
+    \value LinoleumOnConcrete A Linoleum floor
+    \value Marble A marble floor
+    \value Metal Metal
+    \value ParquetOnConcrete Parquet wooden floor on concrete
+    \value PlasterRough Rough plaster
+    \value PlasterSmooth Smooth plaster
+    \value PlywoodPanel Plywodden panel
+    \value PolishedConcreteOrTile Polished concrete or tiles
+    \value Sheetrock Rock
+    \value WaterOrIceSurface Water or ice
+    \value WoodCeiling A wooden ceiling
+    \value WoodPanel Wooden panel
+    \value Uniform Artificial material giving uniform reflections on all frequencies
+*/
+
+
+/*!
+    \qmlproperty vector3D SpatialAudioRoom::dimensions
+
+    Defines the dimensions of the room in 3D space. All units are
+    assumed to be in meters.
+ */
+void QQuick3DSpatialAudioRoom::setDimensions(QVector3D dim)
+{
+    m_room->setDimensions(dim);
+}
+
+QVector3D QQuick3DSpatialAudioRoom::dimensions() const
+{
+    return m_room->dimensions();
+}
+
+/*!
+    \qmlproperty SpatialAudioRoom::Material SpatialAudioRoom::left
+
+    Sets the material to use for the left (negative x) of the room.
+ */
+void QQuick3DSpatialAudioRoom::setLeft(Material material)
+{
+    m_room->setWall(QSpatialAudioRoom::LeftWall, QSpatialAudioRoom::Material(material));
+}
+
+QQuick3DSpatialAudioRoom::Material QQuick3DSpatialAudioRoom::left() const
+{
+    return Material(m_room->wall(QSpatialAudioRoom::LeftWall));
+}
+
+/*!
+    \qmlproperty SpatialAudioRoom::Material SpatialAudioRoom::right
+
+    Sets the material to use for the right (positive x) of the room.
+ */
+void QQuick3DSpatialAudioRoom::setRight(Material material)
+{
+    m_room->setWall(QSpatialAudioRoom::RightWall, QSpatialAudioRoom::Material(material));
+}
+
+QQuick3DSpatialAudioRoom::Material QQuick3DSpatialAudioRoom::right() const
+{
+    return Material(m_room->wall(QSpatialAudioRoom::RightWall));
+}
+
+/*!
+    \qmlproperty SpatialAudioRoom::Material SpatialAudioRoom::front
+
+    Sets the material to use for the front (positive z) of the room.
+ */
+void QQuick3DSpatialAudioRoom::setFront(Material material)
+{
+    m_room->setWall(QSpatialAudioRoom::FrontWall, QSpatialAudioRoom::Material(material));
+}
+
+QQuick3DSpatialAudioRoom::Material QQuick3DSpatialAudioRoom::front() const
+{
+    return Material(m_room->wall(QSpatialAudioRoom::FrontWall));
+}
+
+/*!
+    \qmlproperty SpatialAudioRoom::Material SpatialAudioRoom::back
+
+    Sets the material to use for the back (negative z) of the room.
+ */
+void QQuick3DSpatialAudioRoom::setBack(Material material)
+{
+    m_room->setWall(QSpatialAudioRoom::BackWall, QSpatialAudioRoom::Material(material));
+}
+
+QQuick3DSpatialAudioRoom::Material QQuick3DSpatialAudioRoom::back() const
+{
+    return Material(m_room->wall(QSpatialAudioRoom::BackWall));
+}
+
+/*!
+    \qmlproperty SpatialAudioRoom::Material SpatialAudioRoom::floor
+
+    Sets the material to use for the floor of the room.
+ */
+void QQuick3DSpatialAudioRoom::setFloor(Material material)
+{
+    m_room->setWall(QSpatialAudioRoom::Floor, QSpatialAudioRoom::Material(material));
+}
+
+QQuick3DSpatialAudioRoom::Material QQuick3DSpatialAudioRoom::floor() const
+{
+    return Material(m_room->wall(QSpatialAudioRoom::Floor));
+}
+
+/*!
+    \qmlproperty SpatialAudioRoom::Material SpatialAudioRoom::ceiling
+
+    Sets the material to use for the ceiling of the room.
+ */
+void QQuick3DSpatialAudioRoom::setCeiling(Material material)
+{
+    m_room->setWall(QSpatialAudioRoom::Ceiling, QSpatialAudioRoom::Material(material));
+}
+
+QQuick3DSpatialAudioRoom::Material QQuick3DSpatialAudioRoom::ceiling() const
+{
+    return Material(m_room->wall(QSpatialAudioRoom::Ceiling));
+}
+
+/*!
+    \qmlproperty float SpatialAudioRoom::reflectionGain
+
+    A gain factor for reflections generated in this room. A value
+    from 0 to 1 will dampen reflections, while a value larger than 1
+    will apply a gain to reflections, making them louder.
+
+    The default is 1, a factor of 0 disables reflections. Negative
+    values are mapped to 0.
+ */
+void QQuick3DSpatialAudioRoom::setReflectionGain(float factor)
+{
+    m_room->setReflectionGain(factor);
+}
+
+float QQuick3DSpatialAudioRoom::reflectionGain() const
+{
+    return m_room->reflectionGain();
+}
+
+/*!
+    \qmlproperty float SpatialAudioRoom::reverbGain
+
+    A gain factor for reverb generated in this room. A value
+    from 0 to 1 will dampen reverb, while a value larger than 1
+    will apply a gain to the reverb, making it louder.
+
+    The default is 1, a factor of 0 disables reverb. Negative
+    values are mapped to 0.
+ */
+void QQuick3DSpatialAudioRoom::setReverbGain(float factor)
+{
+    m_room->setReverbGain(factor);
+}
+
+float QQuick3DSpatialAudioRoom::reverbGain() const
+{
+    return m_room->reverbGain();
+}
+
+/*!
+    \qmlproperty float SpatialAudioRoom::reverbTime
+
+    A factor to be applies to all reverb timings generated for this room.
+    Larger values will lead to longer reverb timings, making the room sound
+    larger.
+
+    The default is 1. Negative values are mapped to 0.
+ */
+void QQuick3DSpatialAudioRoom::setReverbTime(float factor)
+{
+    m_room->setReverbTime(factor);
+}
+
+float QQuick3DSpatialAudioRoom::reverbTime() const
+{
+    return m_room->reverbTime();
+}
+
+/*!
+    \qmlproperty float SpatialAudioRoom::reverbTime
+
+    A brightness factor to be applied to the generated reverb.
+    A positive value will increase reverb for higher frequencies and
+    dampen lower frequencies, a negative value does the reverse.
+
+    The default is 0.
+ */
+void QQuick3DSpatialAudioRoom::setReverbBrightness(float factor)
+{
+    m_room->setReverbBrightness(factor);
+}
+
+float QQuick3DSpatialAudioRoom::reverbBrightness() const
+{
+    return m_room->reverbBrightness();
+}
+
+void QQuick3DSpatialAudioRoom::updatePosition()
+{
+    m_room->setPosition(scenePosition());
+}
+
+void QQuick3DSpatialAudioRoom::updateRotation()
+{
+    m_room->setRotation(sceneRotation());
+}
+
+QT_END_NAMESPACE
diff --git a/src/multimediaquick3d/qquick3dspatialaudioroom_p.h b/src/multimediaquick3d/qquick3dspatialaudioroom_p.h
new file mode 100644
index 000000000..184365c29
--- /dev/null
+++ b/src/multimediaquick3d/qquick3dspatialaudioroom_p.h
@@ -0,0 +1,152 @@
+/****************************************************************************
+**
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Spatial Audio module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL-NOGPL2$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QQUICK3DSPATIALAUDIOROOM_H
+#define QQUICK3DSPATIALAUDIOROOM_H
+
+#include <private/qquick3dnode_p.h>
+#include <QtGui/qvector3d.h>
+#include <qspatialaudioroom.h>
+
+QT_BEGIN_NAMESPACE
+
+class QSpatialAudioEngine;
+class QSpatialAudioRoomPrivate;
+
+class QQuick3DSpatialAudioRoom : public QQuick3DNode
+{
+    Q_OBJECT
+    Q_PROPERTY(QVector3D position READ position WRITE setPosition NOTIFY positionChanged)
+    Q_PROPERTY(QVector3D dimensions READ dimensions WRITE setDimensions NOTIFY dimensionsChanged)
+    Q_PROPERTY(QQuaternion rotation READ rotation WRITE setRotation NOTIFY rotationChanged)
+    Q_PROPERTY(Material left READ left WRITE setLeft NOTIFY wallsChanged)
+    Q_PROPERTY(Material right READ right WRITE setRight NOTIFY wallsChanged)
+    Q_PROPERTY(Material front READ front WRITE setFront NOTIFY wallsChanged)
+    Q_PROPERTY(Material back READ back WRITE setBack NOTIFY wallsChanged)
+    Q_PROPERTY(Material floor READ floor WRITE setFloor NOTIFY wallsChanged)
+    Q_PROPERTY(Material ceiling READ ceiling WRITE setCeiling NOTIFY wallsChanged)
+    Q_PROPERTY(float reflectionGain READ reflectionGain WRITE setReflectionGain NOTIFY reflectionGainChanged)
+    Q_PROPERTY(float reverbGain READ reverbGain WRITE setReverbGain NOTIFY reverbGainChanged)
+    Q_PROPERTY(float reverbTime READ reverbTime WRITE setReverbTime NOTIFY reverbTimeChanged)
+    Q_PROPERTY(float reverbBrightness READ reverbBrightness WRITE setReverbBrightness NOTIFY reverbBrightnessChanged)
+    QML_NAMED_ELEMENT(SpatialAudioRoom)
+public:
+    QQuick3DSpatialAudioRoom();
+    ~QQuick3DSpatialAudioRoom();
+
+    enum Material {
+      Transparent,
+      AcousticCeilingTiles,
+      BrickBare,
+      BrickPainted,
+      ConcreteBlockCoarse,
+      ConcreteBlockPainted,
+      CurtainHeavy,
+      FiberGlassInsulation,
+      GlassThin,
+      GlassThick,
+      Grass,
+      LinoleumOnConcrete,
+      Marble,
+      Metal,
+      ParquetOnConcrete,
+      PlasterRough,
+      PlasterSmooth,
+      PlywoodPanel,
+      PolishedConcreteOrTile,
+      Sheetrock,
+      WaterOrIceSurface,
+      WoodCeiling,
+      WoodPanel,
+      Uniform,
+    };
+    Q_ENUM(Material)
+
+    void setDimensions(QVector3D pos);
+    QVector3D dimensions() const;
+
+    void setLeft(Material material);
+    Material left() const;
+
+    void setRight(Material material);
+    Material right() const;
+
+    void setFront(Material material);
+    Material front() const;
+
+    void setBack(Material material);
+    Material back() const;
+
+    void setFloor(Material material);
+    Material floor() const;
+
+    void setCeiling(Material material);
+    Material ceiling() const;
+
+    void setReflectionGain(float factor);
+    float reflectionGain() const;
+
+    void setReverbGain(float factor);
+    float reverbGain() const;
+
+    void setReverbTime(float factor);
+    float reverbTime() const;
+
+    void setReverbBrightness(float factor);
+    float reverbBrightness() const;
+
+Q_SIGNALS:
+    void positionChanged();
+    void dimensionsChanged();
+    void rotationChanged();
+    void wallsChanged();
+    void reflectionGainChanged();
+    void reverbGainChanged();
+    void reverbTimeChanged();
+    void reverbBrightnessChanged();
+
+protected Q_SLOTS:
+    void updatePosition();
+    void updateRotation();
+
+private:
+    QSpatialAudioRoom *m_room;
+};
+
+QT_END_NAMESPACE
+
+#endif