Sound for aircraft. More...

#include "XPMP2.h"

Classes
struct	XPMP2::SoundDefTy
	Definition of how sound is handled based on dataRef values (type) More...

Namespaces
namespace	XPMP2

Macros
#define	LOAD_XP_FUNC(FCT)

#define	ADD_SND(s, f, l)

#define	ADD_CONE(s, f, l, cd, cp, cia, coa, cov)

Typedefs
typedef XPLM_API FMOD_CHANNEL *	XPMP2::f_XPLMPlayPCMOnBus(void audioBuffer, uint32_t bufferSize, FMOD_SOUND_FORMAT soundFormat, int freqHz, int numChannels, int loop, XPLMAudioBus audioType, XPLMPCMComplete_f inCallback, void inRefcon)

typedef XPLM_API FMOD_RESULT	XPMP2::f_XPLMStopAudio(FMOD_CHANNEL *fmod_channel)

typedef XPLM_API FMOD_RESULT	XPMP2::f_XPLMSetAudioPosition(FMOD_CHANNEL fmod_channel, FMOD_VECTOR position, FMOD_VECTOR *velocity)

typedef XPLM_API FMOD_RESULT	XPMP2::f_XPLMSetAudioFadeDistance(FMOD_CHANNEL *fmod_channel, float min_fade_distance, float max_fade_distance)

typedef XPLM_API FMOD_RESULT	XPMP2::f_XPLMSetAudioVolume(FMOD_CHANNEL *fmod_channel, float source_volume)

typedef XPLM_API FMOD_RESULT	XPMP2::f_XPLMSetAudioCone(FMOD_CHANNEL fmod_channel, float inside_angle, float outside_angle, float outside_volume, FMOD_VECTOR orientation)

Functions
FMOD_VECTOR	XPMP2::FmodHeadPitch2Vec (const float head, const float pitch)
	Convert heading/pitch to normalized x/y/z vector.

bool	XPMP2::XPSoundIsAvail ()
	Are XP12 sound functions available?

bool	XPMP2::XPSoundLoadFctPtr ()
	Tries to find all the new XP12 sound functions, available as of XP12.04.

int	XPMP2::SoundLoadXPSounds ()
	Load fixed set of X-Plane-internal sounds.

const char *	XPMP2::SoundEventTxt (Aircraft::SoundEventsTy e)
	Return a text for the values of Aircraft::SoundEventsTy.

void	XPMP2::FmodHeadPitchRoll2Normal (const float head, const float pitch, const float roll, FMOD_VECTOR &vecDir, FMOD_VECTOR &vecNorm)
	Convert heading/pitch to normal x/y/z vector.

void	XPMP2::FmodNormalizeHeadingPitch (float &head, float &pitch)
	Normalize Pitch/Heading.

void	XPMP2::SoundInit ()
	Initialize the sound module and load the sounds.

void	XPMP2::SoundUpdatesBegin ()
	Prepare for this frame's updates, which are about to start.

void	XPMP2::SoundUpdatesDone ()
	Tell FMOD that all updates are done.

void	XPMP2::SoundCleanup ()
	Graceful shoutdown.

bool	XPMPSoundEnable (bool bEnable)
	Enable/Disable Sound.

bool	XPMPSoundIsEnabled ()
	Is Sound enabled?

void	XPMPSoundSetMasterVolume (float fVol)
	Set Master Volume.

void	XPMPSoundMute (bool bMute)
	Mute all sounds (temporarily)

const char *	XPMPSoundAdd (const char sName, const char filePath, bool bLoop, float coneDir, float conePitch, float coneInAngle, float coneOutAngle, float coneOutVol)
	Add a sound that can later be referenced from an XPMP2::Aircraft.

const char *	XPMPSoundEnumerate (const char prevName, const char *ppFilePath)
	Enumerate all sounds, including the internal ones.

bool	XPMPSoundGetAudioDeviceName (int i, std::string &devName)
	List all possible audio devices if using separate FMOD instance.

bool	XPMPSoundSetAudioDeviceName (const std::string &deviceName)
	Set the sound output device if using a separate FMOD instance.

bool	XPMPSoundSetAudioDevice (int i)
	Set the sound output device if using a separate FMOD instance.

int	XPMPSoundGetActiveAudioDevice (std::string *pDevName)
	Returns the index and name of the active audio device.

Variables
SoundSystem *	XPMP2::gpSndSys = nullptr
	The sound system in use.

FMOD_RESULT	XPMP2::gFmodRes = FMOD_OK
	last FMOD result code, needed by the following macro, better don't rely on anywhere else

constexpr float	XPMP2::FMOD_3D_MAX_DIST = 10000.0f
	Value used for 3D max distance, which doesn't have much of a function for the inverse roll-off model used here.

constexpr int	XPMP2::EXP_COMP_SKIP_CYCLES = 10
	In how many cycles to skip expensive computations?

f_XPLMPlayPCMOnBus *	XPMP2::gpXPLMPlayPCMOnBus = nullptr

f_XPLMStopAudio *	XPMP2::gpXPLMStopAudio = nullptr

f_XPLMSetAudioPosition *	XPMP2::gpXPLMSetAudioPosition = nullptr

f_XPLMSetAudioFadeDistance *	XPMP2::gpXPLMSetAudioFadeDistance = nullptr

f_XPLMSetAudioVolume *	XPMP2::gpXPLMSetAudioVolume = nullptr

f_XPLMSetAudioCone *	XPMP2::gpXPLMSetAudioCone = nullptr

Detailed Description

Sound for aircraft.

Sound for aircraft, based on the FMOD library.

As of X-Plane 12.04, X-Plane's SDK offers an interface into X-Plane's FMOD system. If available these functions are loaded dynamically (to stay compatible to XP11). If not available then either FMOD can be used directly if built including FMOD (see SoundFMOD.cpp) or no sound is available.

Author: Birger Hoppe

Copyright: (c) 2022 Birger Hoppe; Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Note: If built with INCLUDE_FMOD_SOUND=1 then Audio Engine is FMOD Core API by Firelight Technologies Pty Ltd. Understand FMOD licensing and attribution requirements first!

See also: FMOD Core API Guide https://fmod.com/docs/2.02/api/core-guide.html

FMOD's C interface is used exclusively (and not the C++ ABI). This is to ease handling of dynamic libaries between versions (XP11 is using FMOD 1.x while XP12 has upgraded to 2.x) and allows compiling with MingW.

Some functionality looks like immitating FMOD's SoundGroup, but 3D positioning was unstable when used via SoundGroup, and the cone functionality did not work at all, so this file handles all sound channels individually.

Note: If linking to the logging version of the FMOD API library (the one ending in L) and specifying a config item log_level of 0 = Debug (see XPMPIntPrefsFuncTy) while initializing sound, ie. typically during the first call to XPMPMultiplayerInit(), then FMOD logging output is added to X-Plane's Log.txt.

Author: Birger Hoppe

Copyright: (c) 2022 Birger Hoppe; Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Class Documentation

◆ XPMP2::SoundDefTy

struct XPMP2::SoundDefTy

Definition of how sound is handled based on dataRef values (type)

Class Members
bool	bSndLoop = true	Sound to be played in a loop while value is large than `valMin`? Otherwise a single sound upon detection of a change of value.
float(Aircraft::*)() const	pVal = nullptr	Function return the value to observe, typically a dataRef value.
float	valMax = NAN	Only used to control volume, which raises for `*pVal` between `valMin` and `valMax`
float	valMin = NAN	Sound to be played if `*pVal > valMin`

Macro Definition Documentation

◆ ADD_CONE

#define ADD_CONE	(	s,
		f,
		l,
		cd,
		cp,
		cia,
		coa,
		cov )

Value:

if (!XPMPSoundAdd(s,f,l,cd,cp,cia,coa,cov)[0]) ++n;

XPMPSoundAdd

const char * XPMPSoundAdd(const char *sName, const char *filePath, bool bLoop, float coneDir, float conePitch, float coneInAngle, float coneOutAngle, float coneOutVol)

Add a sound that can later be referenced from an XPMP2::Aircraft.

Definition Sound.cpp:1148

◆ ADD_SND

#define ADD_SND	(	s,
		f,
		l )

Value:

if (!XPMPSoundAdd(s,f,l)[0]) ++n;

◆ LOAD_XP_FUNC

#define LOAD_XP_FUNC ( FCT )

Value:

gp ## FCT = (f_ ## FCT*) XPLMFindSymbol (#FCT); \

if (!gp ## FCT) return false;

Function Documentation

◆ XPMPSoundAdd()

const char * XPMPSoundAdd	(	const char *	sName,
		const char *	filePath,
		bool	bLoop,
		float	coneDir = NAN,
		float	conePitch = NAN,
		float	coneInAngle = NAN,
		float	coneOutAngle = NAN,
		float	coneOutVol = NAN )

Add a sound that can later be referenced from an XPMP2::Aircraft.

XPMP2 loads a number of default sounds from what X-Plane ships. This function allows to add your own. It will try to load the sound immediately.

Parameters

sName	A descriptive name, used as a key to refer to this sound later
filePath	Path to the sound file; a relative path is relative to `resourceDir` as set by XPMPMultiplayerInit()
bLoop	Is this sound to be played in a loop?
coneDir	[opt] Which direction relative to plane's heading does the cone point to? (180 would be typical for jet engines)
conePitch	[opt] Which pitch does the cone point to (up/down)? (0 would be typical, ie. level with the plane)
coneInAngle	[opt] Inside cone angle. This is the angle spread within which the sound is unattenuated.
coneOutAngle	[opt] Outside cone angle. This is the angle spread outside of which the sound is attenuated to its `coneOutVol`.
coneOutVol	[opt] Cone outside volume.

Returns: Empty string in case of success, otherwise a human-readable error message.

◆ XPMPSoundEnable()

bool XPMPSoundEnable ( bool bEnable = true )

Enable/Disable Sound.

Enable or disable sound support. The default on startup is controlled by the configuration item sound / activate_sound, which in turn defaults to 1.

Returns: Is sound now available? (Could still be false even in case of activation if there was a problem during sound initialization or if it was too early too link into XP's sound system)

◆ XPMPSoundEnumerate()

const char * XPMPSoundEnumerate	(	const char *	prevName,
		const char **	ppFilePath = nullptr )

Enumerate all sounds, including the internal ones.

Parameters

	prevName	`nullptr` or empty string to start from beginning, last returned name to continue with next sound
[out]	ppFilePath	(optional) Receives pointer to file path

Returns: Next sound's name.

Note: String pointers can change any frame. If you want to use the strings longer than immediately, make yourself a string copy.

◆ XPMPSoundGetActiveAudioDevice()

int XPMPSoundGetActiveAudioDevice ( std::string * pDevName = nullptr )

Returns the index and name of the active audio device.

Parameters

[out] pDevName (Optional) A pointer to a std::string that receives the audio device's name

Returns: the index of the active audio device

◆ XPMPSoundGetAudioDeviceName()

bool XPMPSoundGetAudioDeviceName	(	int	i,
		std::string &	devName )

List all possible audio devices if using separate FMOD instance.

Parameters

	i	0-based index of the device name to fetch
[out]	devName	Name of the audio device

Returns: if i was valid and devName is filled; call with increasing i until false is returned

◆ XPMPSoundIsEnabled()

bool XPMPSoundIsEnabled ( )

Is Sound enabled?

◆ XPMPSoundMute()

void XPMPSoundMute ( bool bMute )

Mute all sounds (temporarily)

Parameters

bMute Mute (true) or unmute (false)?

◆ XPMPSoundSetAudioDevice()

bool XPMPSoundSetAudioDevice ( int i )

Set the sound output device if using a separate FMOD instance.

Parameters

i	The device to use as output, see XPMPSoundGetAudioDevices()

Returns: if i was in range

◆ XPMPSoundSetAudioDeviceName()

bool XPMPSoundSetAudioDeviceName ( const std::string & deviceName )

Set the sound output device if using a separate FMOD instance.

Parameters

deviceName The name of the device to use as output, obtain via XPMPSoundGetAudioDevices()

Returns: if device name was found

◆ XPMPSoundSetMasterVolume()

void XPMPSoundSetMasterVolume ( float fVol = 1.0f )

Set Master Volume.

Parameters

fVol	Volume level. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.

Classes

Namespaces

Macros

Typedefs

Functions

Variables

Detailed Description

Class Documentation

◆ XPMP2::SoundDefTy

Macro Definition Documentation

◆ ADD_CONE

◆ ADD_SND

◆ LOAD_XP_FUNC

Function Documentation

◆ XPMPSoundAdd()

◆ XPMPSoundEnable()

◆ XPMPSoundEnumerate()

◆ XPMPSoundGetActiveAudioDevice()

◆ XPMPSoundGetAudioDeviceName()

◆ XPMPSoundIsEnabled()

◆ XPMPSoundMute()

◆ XPMPSoundSetAudioDevice()

◆ XPMPSoundSetAudioDeviceName()

◆ XPMPSoundSetMasterVolume()