Split spatial audio out into a lib of its own

Move the classes from src/multimedia/spatial into its own
QtSpatialAudio library.

This is required to keep Qt Multimedia compatible with the
requirements from the KDE Free Qt Foundation agreement, as
well as to keep license compatibility with existing applications
licensed under GPLv2 that are using Qt Multimedia.

Moving the classes into a module of their own required a few
additional changes to ensure we generate proper documentation
for the new spatial audio module.

To align the API between C++ and QML, the QML import was also
renamed to QtQuick3D.SpatialAudio.

Change-Id: Ia3f9ac5e1edac4b1e07d3302d7a229ada5bdc038
Reviewed-by: Paul Olav Tvete <paul.tvete@qt.io>
(cherry picked from commit c403e775f60a5d02e761904342ac243be1f22597)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

27 files changed, 58 insertions, 54 deletions

diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index 573b1c7c3..7c3b8b2dc 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -1,6 +1,9 @@
 qt_examples_build_begin(EXTERNAL_BUILD)
 
 add_subdirectory(multimedia)
+if (QT_FEATURE_spatialaudio)
+    add_subdirectory(spatialaudio)
+endif()
 add_subdirectory(multimediawidgets)
 
 qt_examples_build_end()
diff --git a/examples/examples.pro b/examples/examples.pro
index 979671672..5d1718718 100644
--- a/examples/examples.pro
+++ b/examples/examples.pro
@@ -1,3 +1,3 @@
 TEMPLATE = subdirs
-SUBDIRS += multimedia multimediawidgets
+SUBDIRS += multimedia multimediawidgets spatialaudio
 
diff --git a/examples/multimedia/CMakeLists.txt b/examples/multimedia/CMakeLists.txt
index 44b701120..6123c7994 100644
--- a/examples/multimedia/CMakeLists.txt
+++ b/examples/multimedia/CMakeLists.txt
@@ -10,7 +10,6 @@ if(TARGET Qt::Widgets)
     endif()
     qt_internal_add_example(audiosource)
     qt_internal_add_example(audiooutput)
-    qt_internal_add_example(spatialaudio)
 endif()
 if(TARGET Qt::Quick)
     qt_internal_add_example(declarative-camera)
diff --git a/examples/multimedia/audiodevices/doc/src/audiodevices.qdoc b/examples/multimedia/audiodevices/doc/src/audiodevices.qdoc
index 4ff9d7f80..f8ef8394a 100644
--- a/examples/multimedia/audiodevices/doc/src/audiodevices.qdoc
+++ b/examples/multimedia/audiodevices/doc/src/audiodevices.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-    \example multimedia/audiodevices
+    \example audiodevices
     \title Audio Devices Example
     \ingroup multimedia_examples
     \brief Testing the available audio devices and their configuration.
diff --git a/examples/multimedia/audiooutput/doc/src/audiooutput.qdoc b/examples/multimedia/audiooutput/doc/src/audiooutput.qdoc
index 6aaf0639d..4478f4861 100644
--- a/examples/multimedia/audiooutput/doc/src/audiooutput.qdoc
+++ b/examples/multimedia/audiooutput/doc/src/audiooutput.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-    \example multimedia/audiooutput
+    \example audiooutput
     \title Audio Output Example
     \ingroup multimedia_examples
     \brief Enabling audio playback using the QAudioSink class.
diff --git a/examples/multimedia/audiorecorder/doc/src/audiorecorder.qdoc b/examples/multimedia/audiorecorder/doc/src/audiorecorder.qdoc
index c96066687..5d8ddc626 100644
--- a/examples/multimedia/audiorecorder/doc/src/audiorecorder.qdoc
+++ b/examples/multimedia/audiorecorder/doc/src/audiorecorder.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-    \example multimedia/audiorecorder
+    \example audiorecorder
     \title Audio Recorder Example
     \ingroup multimedia_examples
     \brief Discovering the available devices and supported codecs.
diff --git a/examples/multimedia/audiosource/doc/src/audiosource.qdoc b/examples/multimedia/audiosource/doc/src/audiosource.qdoc
index 4c89dbeae..0a47a0018 100644
--- a/examples/multimedia/audiosource/doc/src/audiosource.qdoc
+++ b/examples/multimedia/audiosource/doc/src/audiosource.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-    \example multimedia/audiosource
+    \example audiosource
     \title Audio Source Example
     \ingroup multimedia_examples
     \brief Recording audio using the QAudioSource class.
diff --git a/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc b/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc
index 6aa8e8fa6..0fa547a93 100644
--- a/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc
+++ b/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-\example multimedia/declarative-camera
+\example declarative-camera
 \title QML Camera Example
 \ingroup multimedia_examples
 \ingroup camera_examples_qml
diff --git a/examples/multimedia/multimedia.pro b/examples/multimedia/multimedia.pro
index c58cb7b18..1f737a76c 100644
--- a/examples/multimedia/multimedia.pro
+++ b/examples/multimedia/multimedia.pro
@@ -11,8 +11,7 @@ qtHaveModule(widgets) {
         spectrum \
         audiorecorder \
         audiodevices \
-        audiooutput \
-        spatialaudio
+        audiooutput
 }
 
 qtHaveModule(quick) {
diff --git a/examples/multimedia/spatialaudio/spatialaudio.pro b/examples/multimedia/spatialaudio/spatialaudio.pro
deleted file mode 100644
index f9f316916..000000000
--- a/examples/multimedia/spatialaudio/spatialaudio.pro
+++ /dev/null
@@ -1,9 +0,0 @@
-TEMPLATE = app
-TARGET = spatialaudio
-
-QT += multimedia widgets
-
-SOURCES       = main.cpp
-
-target.path = $$[QT_INSTALL_EXAMPLES]/multimedia/spatialaudio
-INSTALLS += target
diff --git a/examples/multimedia/spectrum/doc/src/spectrum.qdoc b/examples/multimedia/spectrum/doc/src/spectrum.qdoc
index 6db616219..1b9c2d4e1 100644
--- a/examples/multimedia/spectrum/doc/src/spectrum.qdoc
+++ b/examples/multimedia/spectrum/doc/src/spectrum.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-    \example multimedia/spectrum
+    \example spectrum
     \title Spectrum Example
     \ingroup multimedia_examples
     \brief Analyzing a raw audio stream using the FFTReal library.
diff --git a/examples/multimedia/video/mediaplayer/doc/src/mediaplayer.qdoc b/examples/multimedia/video/mediaplayer/doc/src/mediaplayer.qdoc
index 56cf91596..be002fa72 100644
--- a/examples/multimedia/video/mediaplayer/doc/src/mediaplayer.qdoc
+++ b/examples/multimedia/video/mediaplayer/doc/src/mediaplayer.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-    \example multimedia/video/mediaplayer
+    \example video/mediaplayer
     \title QML Media Player Example
     \ingroup multimedia_examples
     \ingroup video_examples_qml
@@ -52,7 +52,7 @@
     In \c main.qml a MediaPlayer instance is connected to a VideoOutput to
     play back the video:
 
-    \quotefromfile multimedia/video/mediaplayer/main.qml
+    \quotefromfile video/mediaplayer/main.qml
     \skipto MediaPlayer
     \printuntil videoOutput: videoOutput
 
@@ -67,7 +67,7 @@
     application, viewing meta data, and the selection of available video, audio
     or subtitle tracks.
 
-    \quotefromfile multimedia/video/mediaplayer/PlayerMenuBar.qml
+    \quotefromfile video/mediaplayer/PlayerMenuBar.qml
     Accessing the mediaPlayer object is done through properties:
     \skipto required property
     \printuntil TracksInfo subtitleTracksInfo
@@ -87,7 +87,7 @@
     \image url.png
     While \c urlPopup handles prompting and capturing a url, it is the \c loadUrl
     function that interacts with \c mediaPlayer like so:
-    \quotefromfile multimedia/video/mediaplayer/PlayerMenuBar.qml
+    \quotefromfile video/mediaplayer/PlayerMenuBar.qml
     \skipto function loadUrl
     \printto function closeOverlays(){
 
@@ -97,7 +97,7 @@
     In the declaration of \c mediaPlayer, in \c main.qml, there is the function
     \c updateMetadata():
 
-    \quotefromfile multimedia/video/mediaplayer/main.qml
+    \quotefromfile video/mediaplayer/main.qml
     \skipto function updateMetadata(
     \printto }
 
@@ -106,7 +106,7 @@
     \printto onActiveTracksChanged: { updateMetadata() }
 
     Reading MetaData is done by the \c MetadataInfo type's \c read() function
-    \quotefromfile multimedia/video/mediaplayer/MetadataInfo.qml
+    \quotefromfile video/mediaplayer/MetadataInfo.qml
     \skipto function read(metadata) {
     \printto ListModel
 
@@ -116,7 +116,7 @@
     \youtube OqosZsDqvzQ
     This is defined in \c TracksInfo.qml and reading available tracks is done in
     a similar way to \c MetadataInfo:
-    \quotefromfile multimedia/video/mediaplayer/TracksInfo.qml
+    \quotefromfile video/mediaplayer/TracksInfo.qml
     \skipto function read(metadata
     \printto ListModel
 
@@ -126,7 +126,7 @@
 
     The \c onSelectectedTrackChanged signal, in each relevant \c TracksInfo
     instance in \c main.qml, is what makes changes to \c mediaPlayer like so:
-    \quotefromfile multimedia/video/mediaplayer/main.qml
+    \quotefromfile video/mediaplayer/main.qml
     \skipto id: audioTracksInfo
     \printuntil audioTracksInfo.selectedTrack
 
@@ -141,7 +141,7 @@
     \c main.qml.
 
     Here are the property definitions.
-    \quotefromfile multimedia/video/mediaplayer/PlaybackControl.qml
+    \quotefromfile video/mediaplayer/PlaybackControl.qml
     \skipto required property
     \printto property alias
 
@@ -172,7 +172,7 @@
 
     \c mediaTime uses MediaPlayer's \l{MediaPlayer::position}{position} property
     like so:
-    \quotefromfile multimedia/video/mediaplayer/PlaybackSeekControl.qml
+    \quotefromfile video/mediaplayer/PlaybackSeekControl.qml
     \skipto Text {
     \printto Slider
 
@@ -187,7 +187,7 @@
 
     This type is defined in \c PlaybackRateControl.qml like so:
 
-    \quotefromfile multimedia/video/mediaplayer/PlaybackRateControl.qml
+    \quotefromfile video/mediaplayer/PlaybackRateControl.qml
     \skipto Slider
     \printuntil text:
 
@@ -198,7 +198,7 @@
     of the AudioOutput instantiated within the MediaPlayer, which is
     instantiated in \c{main.qml}.
 
-    \quotefromfile multimedia/video/mediaplayer/AudioControl.qml
+    \quotefromfile video/mediaplayer/AudioControl.qml
     \skipto required
     \printuntil value: 100.0
 */
diff --git a/examples/multimedia/video/doc/images/qmlvideo-menu.jpg b/examples/multimedia/video/qmlvideo/doc/images/qmlvideo-menu.jpg
index 54ab877a1..54ab877a1 100644
--- a/examples/multimedia/video/doc/images/qmlvideo-menu.jpg
+++ b/examples/multimedia/video/qmlvideo/doc/images/qmlvideo-menu.jpg
diff --git a/examples/multimedia/video/doc/images/qmlvideo-overlay.jpg b/examples/multimedia/video/qmlvideo/doc/images/qmlvideo-overlay.jpg
index 6a0d48ae6..6a0d48ae6 100644
--- a/examples/multimedia/video/doc/images/qmlvideo-overlay.jpg
+++ b/examples/multimedia/video/qmlvideo/doc/images/qmlvideo-overlay.jpg
diff --git a/examples/multimedia/video/doc/src/qmlvideo.qdoc b/examples/multimedia/video/qmlvideo/doc/src/qmlvideo.qdoc
index b8ab25d03..cebaaed38 100644
--- a/examples/multimedia/video/doc/src/qmlvideo.qdoc
+++ b/examples/multimedia/video/qmlvideo/doc/src/qmlvideo.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-\example multimedia/video/qmlvideo
+\example video/qmlvideo
 \title QML Video Example
 \ingroup multimedia_examples
 \brief Transforming video and camera viewfinder content.
@@ -71,13 +71,13 @@ in the center of the screen) is implemented in the \c VideoBasic.qml file.  As
 you can see from the code, this makes use of a type of inheritance; a
 \c VideoBasic item ...
 
-\quotefromfile multimedia/video/qmlvideo/qml/qmlvideo/VideoBasic.qml
+\quotefromfile video/qmlvideo/qml/qmlvideo/VideoBasic.qml
 \skipto import
 \printuntil /^\}/
 
 ... is of type \c SceneBasic ...
 
-\quotefromfile multimedia/video/qmlvideo/qml/qmlvideo/SceneBasic.qml
+\quotefromfile video/qmlvideo/qml/qmlvideo/SceneBasic.qml
 \skipto import
 \printuntil contentType
 \dots
@@ -89,7 +89,7 @@ you can see from the code, this makes use of a type of inheritance; a
 
 ... which itself is a \c Scene:
 
-\quotefromfile multimedia/video/qmlvideo/qml/qmlvideo/Scene.qml
+\quotefromfile video/qmlvideo/qml/qmlvideo/Scene.qml
 \skipto import
 \printuntil root
 \dots
@@ -122,7 +122,7 @@ All that remains is to connect the afterRendering() signal of the QQuickView
 object to a JavaScript function, which will eventually call
 \c frequencyItem.notify():
 
-\quotefromfile multimedia/video/qmlvideo/main.cpp
+\quotefromfile video/qmlvideo/main.cpp
 \skipto QGuiApplication
 \printuntil ;
 \dots
diff --git a/examples/multimedia/video/recorder/doc/src/recorder.qdoc b/examples/multimedia/video/recorder/doc/src/recorder.qdoc
index 9ced09e74..574ab27b6 100644
--- a/examples/multimedia/video/recorder/doc/src/recorder.qdoc
+++ b/examples/multimedia/video/recorder/doc/src/recorder.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-    \example multimedia/video/recorder
+    \example video/recorder
     \title QML Recorder Example
     \ingroup multimedia_examples
     \ingroup video_examples_qml
diff --git a/examples/multimediawidgets/camera/doc/src/camera.qdoc b/examples/multimediawidgets/camera/doc/src/camera.qdoc
index 4db430fc3..3f84bb4cd 100644
--- a/examples/multimediawidgets/camera/doc/src/camera.qdoc
+++ b/examples/multimediawidgets/camera/doc/src/camera.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 /*!
 
-\example multimediawidgets/camera
+\example camera
 \title Camera Example
 \ingroup multimedia_examples
 \ingroup video_examples
diff --git a/examples/multimediawidgets/player/doc/src/player.qdoc b/examples/multimediawidgets/player/doc/src/player.qdoc
index dad969375..5e6c82bec 100644
--- a/examples/multimediawidgets/player/doc/src/player.qdoc
+++ b/examples/multimediawidgets/player/doc/src/player.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-    \example multimediawidgets/player
+    \example player
     \title Media Player Example
     \ingroup multimedia_examples
     \ingroup video_examples
diff --git a/examples/multimediawidgets/videographicsitem/doc/src/videographicsitem.qdoc b/examples/multimediawidgets/videographicsitem/doc/src/videographicsitem.qdoc
index 74fbf65cf..b9f4cc225 100644
--- a/examples/multimediawidgets/videographicsitem/doc/src/videographicsitem.qdoc
+++ b/examples/multimediawidgets/videographicsitem/doc/src/videographicsitem.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-    \example multimediawidgets/videographicsitem
+    \example videographicsitem
     \title Video Graphics Item Example
     \ingroup multimedia_examples
     \brief Streaming video on a graphics scene.
diff --git a/examples/multimediawidgets/videowidget/doc/src/videowidget.qdoc b/examples/multimediawidgets/videowidget/doc/src/videowidget.qdoc
index 25bf7b2e3..2195f8f73 100644
--- a/examples/multimediawidgets/videowidget/doc/src/videowidget.qdoc
+++ b/examples/multimediawidgets/videowidget/doc/src/videowidget.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-    \example multimediawidgets/videowidget
+    \example videowidget
     \title Video Widget Example
     \ingroup multimedia_examples
     \brief Implementing a video player widget.
diff --git a/examples/spatialaudio/CMakeLists.txt b/examples/spatialaudio/CMakeLists.txt
new file mode 100644
index 000000000..b066621e6
--- /dev/null
+++ b/examples/spatialaudio/CMakeLists.txt
@@ -0,0 +1 @@
+add_subdirectory(audiopanning)
diff --git a/examples/multimedia/spatialaudio/CMakeLists.txt b/examples/spatialaudio/audiopanning/CMakeLists.txt
index 9e6649fc8..75cf39fd1 100644
--- a/examples/multimedia/spatialaudio/CMakeLists.txt
+++ b/examples/spatialaudio/audiopanning/CMakeLists.txt
@@ -7,26 +7,26 @@ if(NOT DEFINED INSTALL_EXAMPLESDIR)
     set(INSTALL_EXAMPLESDIR "examples")
 endif()
 
-set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/multimedia/spatialaudio")
+set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/spatialaudio/audiopanning")
 
-find_package(Qt6 REQUIRED COMPONENTS Core Gui Multimedia Widgets)
+find_package(Qt6 REQUIRED COMPONENTS Core Gui SpatialAudio Widgets)
 
-qt_add_executable(spatialaudio
+qt_add_executable(audiopanning
     main.cpp
 )
 
-set_target_properties(spatialaudio PROPERTIES
+set_target_properties(audiopanning PROPERTIES
     WIN32_EXECUTABLE FALSE
     MACOSX_BUNDLE TRUE
 )
 
-target_link_libraries(spatialaudio PUBLIC
+target_link_libraries(audiopanning PUBLIC
     Qt::Core
-    Qt::Multimedia
+    Qt::SpatialAudio
     Qt::Widgets
 )
 
-install(TARGETS spatialaudio
+install(TARGETS audiopanning
     RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
     BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
     LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
diff --git a/examples/spatialaudio/audiopanning/audiopanning.pro b/examples/spatialaudio/audiopanning/audiopanning.pro
new file mode 100644
index 000000000..3b1cce652
--- /dev/null
+++ b/examples/spatialaudio/audiopanning/audiopanning.pro
@@ -0,0 +1,9 @@
+TEMPLATE = app
+TARGET = audiopanning
+
+QT += multimedia widgets spatialaudio
+
+SOURCES       = main.cpp
+
+target.path = $$[QT_INSTALL_EXAMPLES]/spatialaudio/audiopanning
+INSTALLS += target
diff --git a/examples/multimedia/spatialaudio/doc/images/spatialaudio-example.png b/examples/spatialaudio/audiopanning/doc/images/audiopanning-example.png
index 45c53975d..45c53975d 100644
--- a/examples/multimedia/spatialaudio/doc/images/spatialaudio-example.png
+++ b/examples/spatialaudio/audiopanning/doc/images/audiopanning-example.png
diff --git a/examples/multimedia/spatialaudio/doc/src/spatialaudio.qdoc b/examples/spatialaudio/audiopanning/doc/src/audiopanning.qdoc
index c6452a071..b1bb94d82 100644
--- a/examples/multimedia/spatialaudio/doc/src/spatialaudio.qdoc
+++ b/examples/spatialaudio/audiopanning/doc/src/audiopanning.qdoc
@@ -26,14 +26,13 @@
 ****************************************************************************/
 /*!
 
-\example multimedia/spatialaudio
-\title Spatial Audio Example
-\ingroup multimedia_examples
+\example audiopanning
+\title Spatial Audio Panning Example
 \ingroup spatialaudio_examples
 \meta {tag} {widgets}
 \brief Shows some of the capabilities of the spatial audio engine in Qt.
 
-The Spatial Audio Example demonstrates how you can use \l{Qt Multimedia} to
+The Spatial Audio Example demonstrates how you can use \l{Qt Spatial Audio} to
 place sound sources in 3D space and how positioning of the sound source and
 room properties affect the listening experience.
 
@@ -46,6 +45,6 @@ and reverb.
 Various other properties can also be modified such as the dimensions of a virtual
 room and the intensity of the room reflections and reverb.
 
-\image spatialaudio-example.png
+\image audiopanning-example.png
 
 */
diff --git a/examples/multimedia/spatialaudio/main.cpp b/examples/spatialaudio/audiopanning/main.cpp
index 8aa9bb672..434aabe6a 100644
--- a/examples/multimedia/spatialaudio/main.cpp
+++ b/examples/spatialaudio/audiopanning/main.cpp
@@ -48,7 +48,7 @@
 **
 ****************************************************************************/
 #include <QtWidgets/QtWidgets>
-#include <QtMultimedia/QtMultimedia>
+#include <QtSpatialAudio/QtSpatialAudio>
 
 class AudioWidget : public QWidget
 {
diff --git a/examples/spatialaudio/spatialaudio.pro b/examples/spatialaudio/spatialaudio.pro
new file mode 100644
index 000000000..80039c1a5
--- /dev/null
+++ b/examples/spatialaudio/spatialaudio.pro
@@ -0,0 +1,3 @@
+TEMPLATE = subdirs
+SUBDIRS += audiopanning
+