Merge XP12 sound

CMakeLists.txt

@@ -29,7 +29,7 @@ else()
 endif()
 
 project(XPMP2
-        VERSION 3.2.1
+        VERSION 3.3.0
         DESCRIPTION "Multiplayer library for X-Plane 11 and 12")
 
 # Provide compile macros from the above project version definition
@@ -82,7 +82,7 @@ set_property(GLOBAL PROPERTY CXX_STANDARD 17)
 ################################################################################
 
 # Enable all X-Plane SDK APIs up to the newest version.
-add_compile_definitions(XPLM200=1 XPLM210=1 XPLM300=1 XPLM301=1 XPLM303=1)
+add_compile_definitions(XPLM200=1 XPLM210=1 XPLM300=1 XPLM301=1 XPLM303=1 XPLM400=1)
 
 # Define platform macros.
 add_compile_definitions(APL=$<BOOL:${APPLE}> IBM=$<BOOL:${WIN32}> LIN=$<AND:$<BOOL:${UNIX}>,$<NOT:$<BOOL:${APPLE}>>>)
@@ -162,6 +162,8 @@ add_library(XPMP2 STATIC
     src/RelatedDoc8643.cpp
     src/Remote.h
     src/Remote.cpp
+    src/Sound.h
+    src/Sound.cpp
     src/Utilities.h
     src/Utilities.cpp
     src/XPMP2.h
@@ -176,6 +178,7 @@ target_include_directories(XPMP2
 	PUBLIC
         ${CMAKE_CURRENT_SOURCE_DIR}/inc
     PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/lib/fmod/inc
 		${CMAKE_CURRENT_SOURCE_DIR}/lib/SDK/CHeaders/XPLM
 		${CMAKE_CURRENT_SOURCE_DIR}/src
 )
@@ -197,11 +200,10 @@ endif()
 # (The actual FMOD lib is not included here, that needs to be done by the plugin target)
 if(INCLUDE_FMOD_SOUND)
     # Compile options
-    add_compile_definitions(INCLUDE_FMOD_SOUND)
-    target_include_directories(XPMP2 PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/lib/fmod/inc)
+    add_compile_definitions(INCLUDE_FMOD_SOUND=1)
     target_sources(XPMP2 PRIVATE
-        src/Sound.h
-        src/Sound.cpp
+        src/SoundFMOD.h
+        src/SoundFMOD.cpp
     )
 endif()
 

README.md

@@ -23,9 +23,6 @@ of the library outdated...it is basically replaced by one line of code calling
 Concepts like the syntax of the `xsb_aircraft.txt` file or certainly the idea of an
 multi-pass matching to find a good model are retained, though re-implemented.
 
-Added is support for synchronizing planes across the network with the remote
-machines running the included [**XPMP2 Remote Client**](#XPMP2-Remote-Client-Synchronizing-Planes-across-the-Network).
-
 XPMP2 does no longer call any OpenGL function and hence does not require
 to be linked to an OpenGL library. The included XPMP2 Remote Client and
 XPMP2-Sample applications do not link to OpenGL.
@@ -52,11 +49,11 @@ to stay backward compatible.
 
 The XPMP2 library has been successfully tested with
 - X-Plane 11.5x under OpenGL, Vulkan, and Metal,
-- X-Plane 12 Alpha and Beta versions,
+- X-Plane 12,
 - the [XPMP2 Remote Client](#XPMP2-Remote-Client-Synchronizing-Planes-across-the-Network),
 - the [`XPMP2-Sample` plugin](https://github.com/TwinFan/XPMP2-Remote),
-- [LiveTraffic v2.20](https://forums.x-plane.org/index.php?/files/file/49749-livetraffic/)
-- [X-Pilot 1.3](http://xpilot-project.org/)
+- [LiveTraffic](https://forums.x-plane.org/index.php?/files/file/49749-livetraffic/)
+- [X-Pilot](http://xpilot-project.org/)
 - X-Plane version of [IVAO Altitude](https://www.ivao.aero/softdev/beta/altitudebeta.asp)
 - on Mac OS,
 - Windows, and
@@ -67,8 +64,8 @@ The XPMP2 library has been successfully tested with
 - XPMP2 implements [instancing](https://developer.x-plane.com/sdk/XPLMInstance/),
   so it **requires X-Plane 11.10** or later
 - CSL models in **OBJ8 format** (ie. older OBJ7 models are no longer supported)
-- Potentially an FMOD license if built with sound support, see below in
-  [Sound Support by FMOD](#sound-support-by-fmod)
+- Potentially an FMOD license if built with FMOD sound support, see 
+  [Sound Support](#sound-support)
 
 ## Documentation: See [GitHub pages](https://twinfan.github.io/XPMP2/) ##
 
@@ -137,18 +134,27 @@ precice results.
 
 Find [more details here](https://twinfan.github.io/XPMP2/Wake.html).
 
-### Sound Support by FMOD ###
+### Sound Support ###
 
 All displayed aircraft can produce sound in the 3D world for
 engine, reversers, taxiing, gear and flap movement.
 
-XPMP2's Audio Engine is FMOD Core API by Firelight Technologies Pty Ltd.
-Understand FMOD [licensing](https://www.fmod.com/licensing) and
-[attribution requirements](https://www.fmod.com/attribution) first,
-as they will apply to _your_ plugin if using XPMP2 with sound support.
+There are 2 options:
+- As of X-Plane 12.04, XPMP2 can use X-Plane's new
+  [Sound API](https://developer.x-plane.com/sdk/XPLMSound/) and hence
+  integrate sounds with X-Plane's own FMOD instance; this does not
+  need linking and licensing your plugin with FMOD, but is restricted
+  to rather simple forms of `.WAV` sound file formats.
+- When building with FMOD support directly, then XPMP2's Audio Engine is
+  FMOD Core API by Firelight Technologies Pty Ltd.
+  Understand FMOD [licensing](https://www.fmod.com/licensing) and
+  [attribution requirements](https://www.fmod.com/attribution) first,
+  as they will apply to _your_ plugin if using XPMP2 with sound support.
+
+Because of the FMOD licensing requirements, XPMP2 by default is built
+without FMOD library support, but always supports X-Plane 12's
+internal Sound API out of the box.
 
-Because of the licensing requirements, XPMP2 by default is built
-**without** sound support.
 See the [Sound Support documentation](https://twinfan.github.io/XPMP2/Sound.html)
 for details how to enable sound support and how to include it into your plugin.
 

XPMP2.xcodeproj/project.pbxproj

@@ -17,6 +17,8 @@
 		2541FA4E253CDD6700AEA532 /* Remote.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 2541FA4C253CDD6700AEA532 /* Remote.cpp */; };
 		255EC99228E3871100F99F93 /* Sound.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 255EC99028E3871100F99F93 /* Sound.cpp */; };
 		255EC99328E3871100F99F93 /* Sound.h in Headers */ = {isa = PBXBuildFile; fileRef = 255EC99128E3871100F99F93 /* Sound.h */; };
+		256C7F0D2A40E2820095A0B4 /* SoundFMOD.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 256C7F0B2A40E2820095A0B4 /* SoundFMOD.cpp */; };
+		256C7F0E2A40E2820095A0B4 /* SoundFMOD.h in Headers */ = {isa = PBXBuildFile; fileRef = 256C7F0C2A40E2820095A0B4 /* SoundFMOD.h */; };
 		256DC2F724F3141500C1595C /* CSLCopy.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 256DC2F624F3141500C1595C /* CSLCopy.cpp */; };
 		2575F45423EDFC5E00747524 /* Map.h in Headers */ = {isa = PBXBuildFile; fileRef = 2575F45223EDFC5E00747524 /* Map.h */; };
 		2575F45523EDFC5E00747524 /* Map.cpp in Sources */ = {isa = PBXBuildFile; fileRef = 2575F45323EDFC5E00747524 /* Map.cpp */; };
@@ -62,6 +64,9 @@
 		255EC99028E3871100F99F93 /* Sound.cpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; path = Sound.cpp; sourceTree = "<group>"; };
 		255EC99128E3871100F99F93 /* Sound.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = Sound.h; sourceTree = "<group>"; };
 		256C287925B4E6270033007D /* Toolchain-ubuntu-osxcross.cmake */ = {isa = PBXFileReference; lastKnownFileType = text; path = "Toolchain-ubuntu-osxcross.cmake"; sourceTree = "<group>"; };
+		256C7F0B2A40E2820095A0B4 /* SoundFMOD.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = SoundFMOD.cpp; sourceTree = "<group>"; };
+		256C7F0C2A40E2820095A0B4 /* SoundFMOD.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = SoundFMOD.h; sourceTree = "<group>"; };
+		256C7F0F2A40E7970095A0B4 /* lib */ = {isa = PBXFileReference; lastKnownFileType = folder; path = lib; sourceTree = "<group>"; };
 		256DC2F524F3090B00C1595C /* Obj8DataRefs.txt */ = {isa = PBXFileReference; lastKnownFileType = text; path = Obj8DataRefs.txt; sourceTree = "<group>"; };
 		256DC2F624F3141500C1595C /* CSLCopy.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = CSLCopy.cpp; sourceTree = "<group>"; };
 		256F4687255C9A6A00FBE18A /* XPMP2.example.prf */ = {isa = PBXFileReference; lastKnownFileType = text; path = XPMP2.example.prf; sourceTree = "<group>"; };
@@ -82,6 +87,12 @@
 		2599B92123BF63F600F92BB5 /* XPMP2.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = XPMP2.h; sourceTree = "<group>"; };
 		25AE8CB323E376E1000BE21E /* 2D.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = 2D.cpp; sourceTree = "<group>"; };
 		25AE8CB423E376E2000BE21E /* 2D.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = 2D.h; sourceTree = "<group>"; };
+		25B8D14A2A50CF2A00D8DAE9 /* SharedDataRefs.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = SharedDataRefs.md; sourceTree = "<group>"; };
+		25B8D14B2A50CF2A00D8DAE9 /* Wake.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = Wake.md; sourceTree = "<group>"; };
+		25B8D14C2A50CF2A00D8DAE9 /* Contrails.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = Contrails.md; sourceTree = "<group>"; };
+		25B8D14D2A50CF2B00D8DAE9 /* CopyingObjFiles.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = CopyingObjFiles.md; sourceTree = "<group>"; };
+		25B8D14E2A50CF2B00D8DAE9 /* Sound.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = Sound.md; sourceTree = "<group>"; };
+		25B8D14F2A50CF2B00D8DAE9 /* Remote.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = Remote.md; sourceTree = "<group>"; };
 		25D1D25523C9285300D20D58 /* README.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = README.md; sourceTree = "<group>"; };
 		25D680B123BE936B00C83CC5 /* Info.plist */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
 		25D680B623BE95FB00C83CC5 /* XPCAircraft.h */ = {isa = PBXFileReference; explicitFileType = sourcecode.cpp.h; fileEncoding = 4; path = XPCAircraft.h; sourceTree = "<group>"; };
@@ -122,8 +133,9 @@
 				252C01F723E6D64F007C231F /* docker */,
 				25D680BD23BE9B7900C83CC5 /* docs */,
 				25D680B523BE95FB00C83CC5 /* inc */,
-				2596FD462447226700C6A41E /* Resources */,
 				25D680BC23BE9B5700C83CC5 /* src */,
+				256C7F0F2A40E7970095A0B4 /* lib */,
+				2596FD462447226700C6A41E /* Resources */,
 				25D86CC6253E285E00424494 /* Frameworks */,
 				2502C16923BE3CFC00578919 /* Products */,
 			);
@@ -199,6 +211,8 @@
 				2541FA4B253CDD6700AEA532 /* Remote.h */,
 				255EC99028E3871100F99F93 /* Sound.cpp */,
 				255EC99128E3871100F99F93 /* Sound.h */,
+				256C7F0B2A40E2820095A0B4 /* SoundFMOD.cpp */,
+				256C7F0C2A40E2820095A0B4 /* SoundFMOD.h */,
 				25EC1C4523BF7569000940BB /* Utilities.cpp */,
 				25EC1C4623BF7569000940BB /* Utilities.h */,
 				2599B92123BF63F600F92BB5 /* XPMP2.h */,
@@ -212,14 +226,20 @@
 			children = (
 				25019BCB24919A1500355472 /* BackwardsCompatibility.md */,
 				25019BC924919A1500355472 /* Building.md */,
+				25B8D14C2A50CF2A00D8DAE9 /* Contrails.md */,
+				25B8D14D2A50CF2B00D8DAE9 /* CopyingObjFiles.md */,
 				25019BC724919A1500355472 /* CSLdataRefs.md */,
 				25019BCA24919A1500355472 /* Deploying.md */,
 				25019BC624919A1500355472 /* HowTo.md */,
 				2574E0052457842A000E8156 /* html */,
 				2574E00424578419000E8156 /* index.md */,
 				25D680BF23BE9BB900C83CC5 /* MainPage.md */,
 				25019BCC24919A1600355472 /* Matching.md */,
+				25B8D14F2A50CF2B00D8DAE9 /* Remote.md */,
+				25B8D14A2A50CF2A00D8DAE9 /* SharedDataRefs.md */,
+				25B8D14E2A50CF2B00D8DAE9 /* Sound.md */,
 				25019BC824919A1500355472 /* TCAS.md */,
+				25B8D14B2A50CF2A00D8DAE9 /* Wake.md */,
 				25D680BE23BE9BB900C83CC5 /* XPMP2.doxygen */,
 				25997FB62476A33E00F36447 /* XSBAircraftFormat.md */,
 			);
@@ -251,6 +271,7 @@
 				25D680B923BE95FB00C83CC5 /* XPCAircraft.h in Headers */,
 				255EC99328E3871100F99F93 /* Sound.h in Headers */,
 				252C01F523E62040007C231F /* AIMultiplayer.h in Headers */,
+				256C7F0E2A40E2820095A0B4 /* SoundFMOD.h in Headers */,
 				25338212253A39060090E0B3 /* Network.h in Headers */,
 				2541FA4D253CDD6700AEA532 /* Remote.h in Headers */,
 				2541FA46253C902200AEA532 /* XPMPRemote.h in Headers */,
@@ -351,6 +372,7 @@
 				2575F45523EDFC5E00747524 /* Map.cpp in Sources */,
 				25338211253A39060090E0B3 /* Network.cpp in Sources */,
 				25F070792956406100065969 /* Contrail.cpp in Sources */,
+				256C7F0D2A40E2820095A0B4 /* SoundFMOD.cpp in Sources */,
 				2599B91923BF636E00F92BB5 /* Aircraft.cpp in Sources */,
 				255EC99228E3871100F99F93 /* Sound.cpp in Sources */,
 			);
@@ -423,6 +445,7 @@
 					"XPLM300=1",
 					"XPLM301=1",
 					"XPLM303=1",
+					"XPLM400=1",
 					"XPMP2_VER_MAJOR=${XPMP2_VER_MAJOR}",
 					"XPMP2_VER_MINOR=${XPMP2_VER_MINOR}",
 					"XPMP2_VER_PATCH=${XPMP2_VER_PATCH}",
@@ -457,8 +480,8 @@
 					lib/fmod/inc,
 				);
 				XPMP2_VER_MAJOR = 3;
-				XPMP2_VER_MINOR = 2;
-				XPMP2_VER_PATCH = 1;
+				XPMP2_VER_MINOR = 3;
+				XPMP2_VER_PATCH = 0;
 				XPSDK_ROOT = lib/SDK;
 			};
 			name = Debug;
@@ -525,6 +548,7 @@
 					"XPLM300=1",
 					"XPLM301=1",
 					"XPLM303=1",
+					"XPLM400=1",
 					"XPMP2_VER_MAJOR=${XPMP2_VER_MAJOR}",
 					"XPMP2_VER_MINOR=${XPMP2_VER_MINOR}",
 					"XPMP2_VER_PATCH=${XPMP2_VER_PATCH}",
@@ -558,8 +582,8 @@
 					lib/fmod/inc,
 				);
 				XPMP2_VER_MAJOR = 3;
-				XPMP2_VER_MINOR = 2;
-				XPMP2_VER_PATCH = 1;
+				XPMP2_VER_MINOR = 3;
+				XPMP2_VER_PATCH = 0;
 				XPSDK_ROOT = lib/SDK;
 			};
 			name = Release;

docs/Sound.md

@@ -1,17 +1,49 @@
+## Sound Support by X-Plane 12
+
+As of X-Plane 12.04, X-Plane support a new
+[Sound API](https://developer.x-plane.com/sdk/XPLMSound/),
+which allows to have sounds played integrated with X-Plane's sound environment,
+utilizing X-Plane's FMOD instance. Sounds created by XPMP2
+are part of X-Plane's "Environment" set of sounds. Hence, sound volume
+is controlled by the "Environment" slider in X-Plane's
+[Sound settings](https://x-plane.com/manuals/desktop/#configuringthesound).
+
+### XP11 compatibility maintained
+
+XPMP2 [dynamically finds and loads the symbols](https://developer.x-plane.com/sdk/XPLMUtilities/#XPLMFindSymbol)
+to the Sound API functions. This way binary compatibility with XP11 is maintained.
+Although XPMP2 builds with `XPLM400` defined, the resulting binaries
+work in both XP11 and XP12. Certainly, sound is only available in XP12,
+in XP11 planes are shown but emit no sound.
+If you want to support sound in XP11, too, you can link with FMOD directly,
+[see below](#sound-support-by-fmod).
+
+### `WAV` with certain sample formats only
+
+X-Plane's Sound API is rather simple. The biggest drawback is that it requires
+the caller to prepare PCM16 data in memory before playing. That means
+XPMP2 needs to read sound files and unpack data into memory.
+So far, XPMP2 implemented only support for `WAV` files
+containing INT8, INT16, IEEE32 (Float), or IEEE64 (Double) sample data
+for a maximum 2 channels (ie. mono or stereo).
+These are rather common `WAV` formats, though. They are sufficient
+to read X-Plane-provided files from `X-Plane/Resources/sounds` for the
+standard sounds XPMP2 supports immediately.
+
 ## Sound Support by FMOD
 
-XPMP2's Audio Engine is FMOD Core API by Firelight Technologies Pty Ltd.
+Alternatively, XPMP2 also supports being linked with the FMOD library directly,
+this way making sound possible also under XP11. Even in XP12, usage
+of its own FMOD instance can be forced via
+configuration key `XPMP_CFG_ITM_FMOD_INSTANCE`.
 
-While X-Plane supports and uses FMOD, too, for aircraft-specific sounds,
-XPMP2 cannot make use of any X-Plane functionality to produce the sounds
-as X-Plane at the moment does not allow to dynamically add sounds
-to instanced objects.
+if built with FMOD library support, then
+XPMP2's Audio Engine is FMOD Core API by Firelight Technologies Pty Ltd.
 
-Instead, XPMP2 creates its own fully indepent instance of the FMOD system.
+This way, XPMP2 creates its own fully indepent instance of the FMOD system.
 This also means that XPMP2 has to provide FMOD with all spacial information
 for each aircraft's sound to create a proper 3D sound illusion
-relative to the user's current camera position. Which opens a totally new
-space for potential bugs...
+relative to the user's current camera position.
 
 ### Register with FMOD and Download
 
@@ -25,8 +57,8 @@ at least for Windows and Mac (if you ship on those platforms).
 
 ### Building XPMP2 with FMOD Sound Support
 
-Due to above licencing requirements,
-sound support is only included if XPMP2 is consciously built with
+Due to above licencing requirements, FMOD sound library support
+is only included if XPMP2 is consciously built with
 CMake cache entry `INCLUDE_FMOD_SOUND`, which in turn defines a
 compile-time macro by the same name, e.g. by doing
 ```
@@ -122,7 +154,7 @@ If your plugin supports X-Plane 11 under Windows, then from the downloaded FMOD
 you need to ship `api/core/lib/x64/fmod.dll` in the plugin's `win_x64` folder.
 See [Deploying](Deploying.html) for details.
 
-### Default Sounds
+## Default Sounds
 
 Your are **not required** to provide any sound-specific coding in your plugin.
 As a matter of fact, the XPMP2-Sample plugin has no single line of code
@@ -162,22 +194,22 @@ The sounds' volume additionally depends on the number of engines,
 which while obvious for the engine sounds is generally an ok indicator
 for the plane's size and hence volume.
 
-### Controlling Sound
+## Controlling Sound
 
 Here are your options to influence sound.
 
-#### Enable/Disable
+### Enable/Disable
 
 Beside using `XPMPSoundEnable()` directly, you can also provides values
 for configuration items `XPMP_CFG_ITM_ACTIVATE_SOUND` and
 `XPMP_CFG_ITM_MUTE_ON_PAUSE` in your configuration callback.
 
-#### General Volume
+### General Volume
 
 `XPMPSoundSetMasterVolume()` and `XPMPSoundMute()` allow controlling
 the volume of XPMP2's sounds generally across all aircraft.
 
-#### Add your own Sounds
+### Add your own Sounds
 
 `XPMPSoundAdd()` allows you to add your own sounds.
 Sounds can be looping (like engine sounds, which play continuously)
@@ -194,7 +226,7 @@ the actual aircraft orientation. The other three cone-specific
 parameters are passed through to FMOD
 (see [set3DConeSettings](https://www.fmod.com/docs/api/core-api-sound.html#sound_set3dconesettings)).
 
-#### Override virtual `Aircraft` member functions
+### Override virtual `Aircraft` member functions
 
 For more control over the sounds your aircraft emit you can override
 `Aircraft`'s virtual member functions: