1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page spatialaudiooverview.html
6\title Spatial Audio Overview
7\brief Support for spatial audio.
8\ingroup explanations-graphicsandmultimedia
10The Qt Spatial Audio API provides a number of classes that allow the creation of
11three dimensional sound scene. It is defined by objects located in 3D space
12that emit sound and surrounding geometry that can be modelled using
13one or several rooms. Finally a listener can be placed into this
14sound scene at a specified position and orientation.
16There are both C++ and QML APIs that can be used.
18\section1 Creating a sound scene
20To create the sound scene, one first instantiates a \l QAudioEngine. This engine
21processes input sound data and geometries to create a realistic
22representation of the sound scene as it would be experienced by a person placed
23at a specific location inside the scene.
25The \l QAudioEngine::OutputMode property can be used to optimize the output either
26for headphones using binaural (virtual 3D) rendering or for a stereo or surround speaker
29The output device can be selected using \l QAudioEngine::outputDevice property.
31Once the engine is set up, we can place various sound objects into the scene by creating
32\l QSpatialSound objects and specifying a url to a sound file using the \l
33QSpatialSound::source property.
35\l QAudioListener can be used to define the position and orientation of a person
36listening to the sound scene. At max one listener per engine can be used. If no listener
37is specified, the engine assumes that the listener is at the origin of the coordinate system
38facing into a positive z direction, with positive y pointing upwards.
40In addition to sound sources and a listener, you can define a geometry that influences how the
41sound is being experienced by the listener through a set of \l QAudioRoom objects. Rooms
42are rectangular and support a wide variety of materials for each wall giving a different experience
43with different sound reflections and reverb. Room effects will get applied if the listener is
44located inside one of the rooms. If he is inside multiple rooms, the room with the smallest
45geometrical volume will take precedence.
47If you need some stereo overlay that is independent of the position and orientation of
48the listener (such as background music or a voice-over), you can use
49\l QAmbientSound to create the sound overlay.
51For a small QWidget based example showcasing one audio source that can be moved around in a room, have
52a look at the \l {audiopanning}{Spacial Audio Panning Example}.
54\section1 Reference Documentation
58\annotatedlist spatialaudio
62\annotatedlist quick3d_spatialaudio