1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-3.0-only
3#include <qquick3daudioengine_p.h>
4#include <qaudiodevice.h>
5
6QT_BEGIN_NAMESPACE
7
8static QAudioEngine *globalEngine = nullptr;
9
10/*!
11 \qmltype AudioEngine
12 \inqmlmodule QtQuick3D.SpatialAudio
13 \ingroup quick3d_spatialaudio
14 \ingroup multimedia_audio_qml
15
16 \brief AudioEngine manages sound objects inside a 3D scene.
17
18 AudioEngine manages sound objects inside a 3D scene. You can add
19 SpatialSound objects to the scene to define sounds that happen
20 at a specified location in 3D space. AmbientSound allows you to add
21 a stereo overlay (for example voice over or a sound track).
22
23 You can use AudioListener to define the position of the person listening
24 to the sound field relative to the sound sources. Sound sources will be less audible
25 if the listener is further away from source. They will also get mapped to the corresponding
26 loudspeakers depending on the direction between listener and source. In many cases, the
27 AudioListener object can simply be instantiated as a child object of the QtQuick3D.Camera
28 object.
29
30 Create AudioRoom objcects to simulate the sound (reflections and reverb) of a room with
31 certain dimensions and different types of walls.
32
33 AudioEngine does offer a mode where Qt is using simulating the effects of the ear
34 using head related impulse reponse functions (see also https://en.wikipedia.org/wiki/Sound_localization)
35 to localize the sound in 3D space when using headphones and create a spatial audio effect through
36 headphones.
37
38 As the rest of Qt Quick 3D, the audio engine uses a coordinate system that is in centimeters by default.
39 The axes are defined so that positive x points to the right, positive y points up and positive z points
40 backwards.
41*/
42
43
44QQuick3DAudioEngine::QQuick3DAudioEngine()
45{
46 auto *e = getEngine();
47 connect(sender: e, signal: &QAudioEngine::outputModeChanged, context: this, slot: &QQuick3DAudioEngine::outputModeChanged);
48 connect(sender: e, signal: &QAudioEngine::outputDeviceChanged, context: this, slot: &QQuick3DAudioEngine::outputDeviceChanged);
49 connect(sender: e, signal: &QAudioEngine::masterVolumeChanged, context: this, slot: &QQuick3DAudioEngine::masterVolumeChanged);
50}
51
52QQuick3DAudioEngine::~QQuick3DAudioEngine()
53{
54}
55
56/*!
57 \qmlproperty enumeration AudioEngine::outputMode
58
59 Sets or retrieves the current output mode of the engine.
60
61 \table
62 \header \li Property value
63 \li Description
64 \row \li Surround
65 \li Map the sounds to the loudspeaker configuration of the output device.
66 This is normally a stereo or surround speaker setup.
67 \row \li Stereo
68 \li Map the sounds to the stereo loudspeaker configuration of the output device.
69 This will ignore any additional speakers and only use the left and right channels
70 to create a stero rendering of the sound field.
71 \row \li Headphone
72 \li Use Headphone spatialization to create a 3D audio effect when listening
73 to the sound field through headphones.
74 \endtable
75 */
76
77void QQuick3DAudioEngine::setOutputMode(OutputMode mode)
78{
79 globalEngine->setOutputMode(QAudioEngine::OutputMode(mode));
80}
81
82QQuick3DAudioEngine::OutputMode QQuick3DAudioEngine::outputMode() const
83{
84 return OutputMode(globalEngine->outputMode());
85}
86
87/*!
88 \qmlproperty QtMultimedia.AudioDevice AudioEngine::outputDevice
89
90 Sets or returns the device that is being used for outputting the sound field.
91 */
92void QQuick3DAudioEngine::setOutputDevice(const QAudioDevice &device)
93{
94 globalEngine->setOutputDevice(device);
95}
96
97QAudioDevice QQuick3DAudioEngine::outputDevice() const
98{
99 return globalEngine->outputDevice();
100}
101
102/*!
103 \qmlproperty real AudioEngine::masterVolume
104
105 Sets or returns overall volume being used to render the sound field.
106 */
107void QQuick3DAudioEngine::setMasterVolume(float volume)
108{
109 globalEngine->setMasterVolume(volume);
110}
111
112float QQuick3DAudioEngine::masterVolume() const
113{
114 return globalEngine->masterVolume();
115}
116
117QAudioEngine *QQuick3DAudioEngine::getEngine()
118{
119 if (!globalEngine) {
120 globalEngine = new QAudioEngine;
121 globalEngine->start();
122 }
123 return globalEngine;
124}
125
126QT_END_NAMESPACE
127
128#include "moc_qquick3daudioengine_p.cpp"
129

source code of qtmultimedia/src/spatialaudioquick3d/qquick3daudioengine.cpp