Merge from Perforce 2023-12-15 14:13:58.026562

README.md

@@ -1,18 +1,17 @@
-% Steam Audio 4.4.1
-% Valve Corporation
+# Steam Audio 4.5.0
 
-Supported Platforms
--------------------
+Valve Corporation
+
+## Supported Platforms
 
 Steam Audio supports Windows (32 bit and 64 bit), Linux (32 bit and 64 bit), macOS, and Android (armv7, arm64, x86, x64) platforms.
 
-Supported Integrations
-----------------------
+## Supported Integrations
 
 Steam Audio supports Unity 2017.3+, Unreal Engine 4.27+, and FMOD Studio 2.0+.
 
-Additional Links
-----------------
+## Additional Links
+
 - [Steam Audio Homepage](https://valvesoftware.github.io/steam-audio)
 - [Downloads & Documentation](https://valvesoftware.github.io/steam-audio/downloads.html)
 - [Community Forum](http://steamcommunity.com/app/596420/discussions/)

fmod/CMakeLists.txt

@@ -3,7 +3,7 @@
 
 cmake_minimum_required(VERSION 3.17)
 
-project(Phonon VERSION 4.4.1)
+project(Phonon VERSION 4.5.0)
 
 set(CMAKE_CXX_STANDARD 14)
 set(CMAKE_MODULE_PATH "${CMAKE_HOME_DIRECTORY}/build")
@@ -22,6 +22,8 @@ elseif (APPLE AND CMAKE_SYSTEM_NAME STREQUAL "Darwin")
     set(IPL_OS_MACOS TRUE)
 elseif (ANDROID)
     set(IPL_OS_ANDROID TRUE)
+elseif (APPLE AND CMAKE_SYSTEM_NAME STREQUAL "iOS")
+    set(IPL_OS_IOS TRUE)
 endif()
 
 # CPU architecture detection
@@ -42,6 +44,8 @@ elseif (IPL_OS_ANDROID)
     elseif (CMAKE_ANDROID_ARCH STREQUAL "x86_64")
         set(IPL_CPU_X64 TRUE)
     endif()
+elseif (IPL_OS_IOS)
+    set(IPL_CPU_ARMV8 TRUE)
 endif()
 
 
@@ -77,6 +81,9 @@ endif()
 if (IPL_OS_ANDROID)
     add_definitions(-DIPL_OS_ANDROID)
 endif()
+if (IPL_OS_IOS)
+    add_definitions(-DIPL_OS_IOS)
+endif()
 
 if (IPL_CPU_X86)
     add_definitions(-DIPL_CPU_X86)
@@ -132,6 +139,7 @@ endif()
 # macOS flags
 if (IPL_OS_MACOS)
     set(CMAKE_OSX_ARCHITECTURES "x86_64;arm64")
+    set(CMAKE_OSX_DEPLOYMENT_TARGET "10.13")
 endif()
 
 # Android flags
@@ -140,6 +148,9 @@ if (IPL_OS_ANDROID)
     add_link_options(-static-libstdc++)
 endif()
 
+# iOS flags
+# todo
+
 
 #
 # DEPENDENCIES

fmod/build/SteamAudioHelpers.cmake

@@ -26,6 +26,8 @@ function (get_local_lib_path LIB_PATH)
 		elseif (IPL_CPU_X64)
 			set(${LIB_PATH} ${CMAKE_HOME_DIRECTORY}/lib/android-x64 PARENT_SCOPE)
 		endif()
+	elseif (IPL_OS_IOS)
+		set(${LIB_PATH} ${CMAKE_HOME_DIRECTORY}/lib/ios PARENT_SCOPE)
 	endif()
 endfunction()
 
@@ -54,6 +56,8 @@ function (get_bin_subdir BIN_SUBDIR)
 		elseif (IPL_CPU_X64)
 			set(${BIN_SUBDIR} android-x64 PARENT_SCOPE)
 		endif()
+	elseif (IPL_OS_IOS)
+		set(${BIN_SUBDIR} ios PARENT_SCOPE)
 	endif()
 endfunction()
 
@@ -103,6 +107,11 @@ function (add_executable_or_apk name)
     endif()
   else()
     add_executable(${name} ${ARGN})
+	if (IPL_OS_IOS)
+		set_target_properties(${name} PROPERTIES MACOSX_BUNDLE_GUI_IDENTIFIER com.valve.${name})
+		set_target_properties(${name} PROPERTIES MACOSX_BUNDLE_BUNDLE_VERSION 1.0.0)
+		set_target_properties(${name} PROPERTIES MACOSX_BUNDLE_SHORT_VERSION_STRING 1.0.0)
+	endif()
   endif()
 endfunction()
 
@@ -118,6 +127,8 @@ function (install_executable_or_apk name dir)
 			set(arch x64)
 		endif()
 		install(FILES ${CMAKE_HOME_DIRECTORY}/build/android/${name}/build/outputs/apk/${name}-${arch}-debug.apk DESTINATION ${dir} RENAME ${name}.apk)
+	elseif (IPL_OS_IOS)
+		install(TARGETS ${name} BUNDLE DESTINATION ${dir})
 	else()
 		install(TARGETS ${name} RUNTIME DESTINATION ${dir})
 	endif()

fmod/build/build.py

@@ -22,7 +22,7 @@ def detect_host_system():
 # Parses the command line.
 def parse_command_line(host_system):
     parser = argparse.ArgumentParser()
-    parser.add_argument('-p', '--platform', help = "Target operating system.", choices = ['windows', 'osx', 'linux', 'android'], type = str.lower, default = host_system)
+    parser.add_argument('-p', '--platform', help = "Target operating system.", choices = ['windows', 'osx', 'linux', 'android', 'ios'], type = str.lower, default = host_system)
     parser.add_argument('-t', '--toolchain', help = "Compiler toolchain. (Windows only)", choices = ['vs2013', 'vs2015', 'vs2017', 'vs2019', 'vs2022'], type = str.lower, default = 'vs2019')
     parser.add_argument('-a', '--architecture', help = "CPU architecture.", choices = ['x86', 'x64', 'armv7', 'arm64'], type = str.lower, default = 'x64')
     parser.add_argument('-c', '--configuration', help = "Build configuration.", choices = ['debug', 'release'], type = str.lower, default = 'release')
@@ -34,7 +34,7 @@ def parse_command_line(host_system):
 def build_subdir(args):
     if args.platform == 'windows':
         return "-".join([args.platform, args.toolchain, args.architecture])
-    elif args.platform == 'osx':
+    elif args.platform in ['osx', 'ios']:
         return args.platform
     elif args.platform in ['linux', 'android']:
         return "-".join([args.platform, args.architecture, args.configuration])
@@ -43,7 +43,7 @@ def build_subdir(args):
 def bin_subdir(args):
     if args.platform in ['windows', 'linux', 'android']:
         return "-".join([args.platform, args.architecture])
-    elif args.platform == 'osx':
+    elif args.platform in ['osx', 'ios']:
         return "-".join([args.platform])
 
 # Returns the root directory of the repository.
@@ -68,7 +68,7 @@ def generator_name(args):
         elif args.toolchain == 'vs2022':
             generator = 'Visual Studio 17 2022'
         return generator + suffix
-    elif args.platform == 'osx':
+    elif args.platform in ['osx', 'ios']:
         return 'Xcode'
     elif args.platform in ['linux', 'android']:
         return 'Unix Makefiles'
@@ -114,6 +114,10 @@ def cmake_generate(args):
             cmake_args += ['-DCMAKE_ANDROID_NDK=' + os.environ.get('ANDROID_NDK')]
             cmake_args += ['-DCMAKE_MAKE_PROGRAM=' + os.environ.get('ANDROID_NDK') + '/prebuilt/windows-x86_64/bin/make.exe']
 
+    # On iOS, specify the toolchain file.
+    if args.platform in ['ios']:
+        cmake_args += ['-DCMAKE_TOOLCHAIN_FILE=' + root_dir() + '/build/toolchain_ios.cmake']
+
     # On Linux and Android, specify the build configuration at generate-time.
     if args.platform in ['linux', 'android']:
         cmake_args += ['-DCMAKE_BUILD_TYPE=' + config_name(args)]
@@ -146,7 +150,7 @@ def cmake_generate(args):
 def cmake_build(args):
     cmake_args = ['--build', '.']
 
-    if args.platform in ['windows', 'osx']:
+    if args.platform in ['windows', 'osx', 'ios']:
         cmake_args += ['--config', config_name(args)]
 
     run_cmake('cmake', cmake_args)
@@ -155,7 +159,7 @@ def cmake_build(args):
 def cmake_install(args):
     cmake_args = ['--install', '.']
 
-    if args.platform in ['windows', 'osx']:
+    if args.platform in ['windows', 'osx', 'ios']:
         cmake_args += ['--config', config_name(args)]
 
     run_cmake('cmake', cmake_args)
@@ -164,7 +168,7 @@ def cmake_install(args):
 def cmake_package(args):
     cmake_args = ['-G', 'ZIP']
 
-    if args.platform in ['windows', 'osx']:
+    if args.platform in ['windows', 'osx', 'ios']:
         cmake_args += ['-C', config_name(args)]
 
     run_cmake('cpack', cmake_args)

fmod/build/toolchain_ios.cmake

@@ -0,0 +1,11 @@
+#
+# Copyright (c) Valve Corporation. All rights reserved.
+#
+
+set(CMAKE_SYSTEM_NAME iOS)
+set(CMAKE_OSX_ARCHITECTURES arm64)
+set(CMAKE_OSX_DEPLOYMENT_TARGET 11.0)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE BOTH)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY BOTH)
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM BOTH)
+set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE BOTH)

fmod/doc/build-instructions.rst

@@ -58,6 +58,10 @@ To build the Android plugin, you will need:
 -   Android SDK for platform 25 (Android 7.1 Nougat) or later (https://developer.android.com/studio)
 -   Android NDK (install using the Android SDK Manager)
 
+To build the iOS plugin, you will need:
+
+-   Xcode 14.0 or later (install from the Mac App Store)
+
 To build the documentation, you will need:
 
 -   Sphinx (https://www.sphinx-doc.org)
@@ -94,18 +98,20 @@ On macOS, this will generate an Xcode project (``build/osx/Phonon.xcodeproj``) a
 
 On Android, this will generate a Makefile for 32-bit ARM (``build/android-armv7-release/Makefile``) and build it.
 
+On iOS, this will generate an Xcode project (``build/ios/Phonon.xcodeproj``) and build it in the Release configuration.
+
 If CMake cannot generate the build system due to missing dependencies, you can run CMake directly and adjust settings that control where CMake looks for dependencies, and which targets it builds.
 
 The Steam Audio build script (``build.py``) lets you specify the following command line parameters to control its behavior:
 
     -p, --platform NAME
-        Specifies the target platform. Valid options are ``windows``, ``linux``, ``osx``, and ``android``. Default is the current host platform.
+        Specifies the target platform. Valid options are ``windows``, ``linux``, ``osx``, ``android``, and ``ios``. Default is the current host platform.
 
     -t, --toolchain NAME
         Specifies the compiler version (on Windows only). Valid options are ``vs2013``, ``vs2015``, ``vs2017``, ``vs2019``. Default is ``vs2015``.
 
     -a, --architecture NAME
-        Specifies the CPU architecture to build for. Valid options are ``x86`` (32-bit Intel, available on Windows, Linux, and Android), ``x64`` (64-bit Intel, available on Windows, Linux, macOS, and Android), ``armv7`` (32-bit ARM, available on Android), and ``arm64`` (64-bit ARM, available on Android). Default is ``x64`` for Windows, Linux, and macOS; and ``armv7`` for Android.
+        Specifies the CPU architecture to build for. Valid options are ``x86`` (32-bit Intel, available on Windows, Linux, and Android), ``x64`` (64-bit Intel, available on Windows, Linux, macOS, and Android), ``armv7`` (32-bit ARM, available on Android), and ``arm64`` (64-bit ARM, available on Android and iOS). Default is ``x64`` for Windows, Linux, and macOS; ``armv7`` for Android; and ``arm64`` for iOS.
 
     -c, --configuration NAME
         Specifies the build configuration. Valid options are ``debug`` and ``release``. Default is ``release``.
@@ -140,6 +146,14 @@ Toolchain File                          Platform
 ``build/toolchain_android_x64.cmake``   64-bit Intel
 ======================================= ============
 
+When building for iOS, Steam Audio provides the following toolchain files that you can use:
+
+======================================= ============
+Toolchain File                          Platform
+======================================= ============
+``build/toolchain_ios.cmake``           64-bit ARM
+======================================= ============
+
 Below are some of the CMake options you may want to configure:
 
 ==============================  ======================================================================

fmod/doc/getting-started.rst

@@ -1,6 +1,8 @@
 Getting Started
 ===============
 
+.. highlight:: c++
+
 Requirements
 ------------
 
@@ -12,6 +14,7 @@ The Steam Audio FMOD Studio integration supports the following platforms:
 -  Linux (32-bit and 64-bit, tested with Ubuntu 18.04 LTS)
 -  macOS 10.7 or later (64-bit Intel)
 -  Android 5.0 or later (32-bit ARM, 64-bit ARM, 32-bit Intel)
+-  iOS 11.0 or later (64-bit ARM)
 
 
 Add Steam Audio to your FMOD Studio project
@@ -65,6 +68,18 @@ If you are using Unity as your game engine, see the Unity tab below. If you are
 
         .. image:: media/unity_fmodsettings.png
 
+        If you are building for iOS, do the following instead:
+
+        1.  In Unity's main menu, click **FMOD** > **Edit Settings**.
+        2.  Under **Static Plugins**, click **Add Plugin**.
+        3.  In the text box that appears, enter ``FMOD_SteamAudio_Spatialize_GetDSPDescription``.
+        4.  Click **Add Plugin** again.
+        5.  In the text box that appears, enter ``FMOD_SteamAudio_MixerReturn_GetDSPDescription``.
+        6.  Click **Add Plugin** again.
+        7.  In the text box that appears, enter ``FMOD_SteamAudio_Reverb_GetDSPDescription``.
+
+        You can configure these static plugins as a platform-specific override for iOS, while using the ``phonon_fmod`` dynamic plugin on other platforms. For more information on how to do this, refer to the documentation for the FMOD Studio Unity integration.
+
         .. rubric:: Configure the Steam Audio Unity integration to use FMOD Studio
 
         1.  In Unity's main menu, click **Steam Audio** > **Settings**.
@@ -91,6 +106,29 @@ If you are using Unity as your game engine, see the Unity tab below. If you are
 
         .. image:: media/unreal_fmodsettings.png
 
+        If you are building for iOS, the version of the FMOD Studio Unreal Engine plugin you are using may not correctly initialize static DSP plugins, leading to errors at runtime. As a workaround, you can modify the ``Source/FMODStudio/Private/FMODStudioModule.cpp`` file in the FMOD Studio plugin's root directory:
+
+        1.  Near the top of the file, after all the ``#include`` directives, add::
+
+                #if PLATFORM_IOS
+                extern "C" {
+                FMOD_DSP_DESCRIPTION* F_CALL FMOD_SteamAudio_Spatialize_GetDSPDescription();
+                FMOD_DSP_DESCRIPTION* F_CALL FMOD_SteamAudio_MixerReturn_GetDSPDescription();
+                FMOD_DSP_DESCRIPTION* F_CALL FMOD_SteamAudio_Reverb_GetDSPDescription();
+                }
+                #endif
+
+        2.  Next, in the ``FFMODStudioModule::CreateStudioSystem`` function, add the following lines after the code for loading dynamic plugins::
+
+                #if PLATFORM_IOS
+                    unsigned int Handle = 0;
+                    lowLevelSystem->registerDSP(FMOD_SteamAudio_Spatialize_GetDSPDescription(), &Handle);
+                    lowLevelSystem->registerDSP(FMOD_SteamAudio_MixerReturn_GetDSPDescription(), &Handle);
+                    lowLevelSystem->registerDSP(FMOD_SteamAudio_Reverb_GetDSPDescription(), &Handle);
+                #endif
+
+        This issue may be fixed in a newer version of FMOD Studio.
+
         .. rubric:: Configure the Steam Audio Unreal Engine plugin to use FMOD Studio
 
         1.  In Unreal's main menu, click **Edit** > **Project Settings**.
@@ -104,16 +142,31 @@ If you are using Unity as your game engine, see the Unity tab below. If you are
 
         .. rubric:: Load the Steam Audio FMOD Studio integration
 
-        1.  When initializing FMOD Studio in your game engine, call ``FMOD::System::loadPlugin`` to load the Steam Audio FMOD Studio integration. The plugin files can be found in the ``steamaudio_fmod.zip`` file you downloaded earlier. The file name of the plugin depends on the platform:
+        When initializing FMOD Studio in your game engine, call ``FMOD::System::loadPlugin`` to load the Steam Audio FMOD Studio integration. The plugin files can be found in the ``steamaudio_fmod.zip`` file you downloaded earlier. The file name of the plugin depends on the platform:
+
+        -   Windows 32-bit: ``lib/windows-x86/phonon_fmod.dll``
+        -   Windows 64-bit: ``lib/windows-x64/phonon_fmod.dll``
+        -   Linux 32-bit: ``lib/linux-x86/libphonon_fmod.so``
+        -   Linux 64-bit: ``lib/linux-x64/libphonon_fmod.so``
+        -   macOS: ``lib/osx/libphonon_fmod.dylib``
+        -   Android ARMv7 (32-bit): ``lib/android-armv7/libphonon_fmod.so``
+        -   Android ARMv8/AArch64 (64-bit): ``lib/android-armv8/libphonon_fmod.so``
+        -   Android x86 (32-bit): ``lib/android-x86/libphonon_fmod.so``
+
+        On iOS, instead of calling ``FMOD::System::loadPlugin``, you will have to statically link to ``lib/ios/libphonon_fmod.a`` and use ``FMOD::System::registerDSP`` to register each of the Steam Audio DSP plugins. For example::
+
+            extern "C" {
+            FMOD_DSP_DESCRIPTION* F_CALL FMOD_SteamAudio_Spatialize_GetDSPDescription();
+            FMOD_DSP_DESCRIPTION* F_CALL FMOD_SteamAudio_MixerReturn_GetDSPDescription();
+            FMOD_DSP_DESCRIPTION* F_CALL FMOD_SteamAudio_Reverb_GetDSPDescription();
+            }
+
+            FMOD::System* system = ...; // initialized elsewhere
 
-            -   Windows 32-bit: ``lib/windows-x86/phonon_fmod.dll``
-            -   Windows 64-bit: ``lib/windows-x64/phonon_fmod.dll``
-            -   Linux 32-bit: ``lib/linux-x86/libphonon_fmod.so``
-            -   Linux 64-bit: ``lib/linux-x64/libphonon_fmod.so``
-            -   macOS: ``lib/osx/libphonon_fmod.dylib``
-            -   Android ARMv7 (32-bit): ``lib/android-armv7/libphonon_fmod.so``
-            -   Android ARMv8/AArch64 (64-bit): ``lib/android-armv8/libphonon_fmod.so``
-            -   Android x86 (32-bit): ``lib/android-x86/libphonon_fmod.so``
+            unsigned int handle = 0;
+            system->registerDSP(FMOD_SteamAudio_Spatialize_GetDSPDescription(), &handle);
+            system->registerDSP(FMOD_SteamAudio_MixerReturn_GetDSPDescription(), &handle);
+            system->registerDSP(FMOD_SteamAudio_Reverb_GetDSPDescription(), &handle);
 
         .. rubric:: Initialize the Steam Audio FMOD Studio integration
 

fmod/include/phonon/phonon.h

@@ -108,6 +108,12 @@ typedef enum {
     IPL_SIMDLEVEL_NEON = IPL_SIMDLEVEL_SSE2,    /**< ARM NEON. Up to 4 simultaneous floating-point operations. */
 } IPLSIMDLevel;
 
+/** Additional flags for modifying the behavior of a Steam Audio context. */
+typedef enum {
+    IPL_CONTEXTFLAGS_VALIDATION,                /**< All API functions perform extra validation checks. NOTE: This imposes a significant performance penalty. */
+    IPL_CONTEXTFLAGS_FORCE_32BIT = 0x7fffffff,  /**< Force this enum to be 32 bits in size. */
+} IPLContextFlags;
+
 /** Prototype of a callback that logs a message generated by Steam Audio. This may be implemented in any suitable way,
     such as appending to a log file, displaying a dialog box, etc. The default behavior is to print to \c stdout.
  
@@ -157,6 +163,9 @@ typedef struct {
         in lower performance than expected. If you observe this in your application, set this
         parameter to `IPL_SIMDLEVEL_AVX2` or lower. */
     IPLSIMDLevel simdLevel;
+
+    /** Additional flags for modifying the behavior of the created context. */
+    IPLContextFlags flags;
 } IPLContextSettings;
 
 /** Creates a context object. A context must be created before creating any other API objects.

fmod/include/phonon/phonon_interfaces.h

@@ -45,7 +45,7 @@ class IContext
 
     virtual void release() = 0;
 
-    virtual void setTelemetryAPI(void* telemetryAPI) = 0;
+    virtual void setProfilerContext(void* profilerContext) = 0;
 
     virtual IPLVector3 calculateRelativeDirection(IPLVector3 sourcePosition,
                                                   IPLVector3 listenerPosition,