Initialization and general control functions for XPMP2. More...

#include <string>
#include <cmath>
#include "XPLMDefs.h"

Classes
struct	XPMPPlanePosition_t
	This data structure contains the basic position info for an aircraft. More...

union	xpmp_LightStatus
	Defines, which lights of the aircraft are on. More...

struct	XPMPPlaneSurfaces_t
	External physical configuration of the plane. More...

struct	XPMPPlaneRadar_t
	defines information about an aircraft visible to radar. More...

struct	XPMPInfoTexts_t
	Textual information of planes to be passed on via shared dataRefs to other plugins. More...

struct	xpmp_LightStatus.__unnamed2__

Namespaces
	XPMP2

Macros
Configuration Sections
Config section is defined for legacy reasons only
#define	XPMP_CFG_SEC_MODELS "models"
	Config section "models". More...

#define	XPMP_CFG_SEC_PLANES "planes"
	Config section "planes". More...

#define	XPMP_CFG_SEC_SOUND "sound"
	Config section "sound". More...

#define	XPMP_CFG_SEC_DEBUG "debug"
	Config section "debug". More...

Configuration Items
Configuration Items are unique in itself even without considering the configuration section
#define	XPMP_CFG_ITM_REPLDATAREFS "replace_datarefs"
	Config key: Replace dataRefs in OBJ8 files upon load, creating new OBJ8 files for XPMP2 (defaults to OFF!) More...

#define	XPMP_CFG_ITM_REPLTEXTURE "replace_texture"
	Config key: Replace textures in OBJ8 files upon load if needed (specified on the OBJ8 line in xsb_aircraft.txt), creating new OBJ8 files. More...

#define	XPMP_CFG_ITM_CLAMPALL "clamp_all_to_ground"
	Config key: Ensure no plane sinks below ground, no matter of XPMP2::Aircraft::bClampToGround. More...

#define	XPMP_CFG_ITM_HANDLE_DUP_ID "handle_dup_id"
	Config key: Boolean: If XPMP2::Aircraft::modeS_id already exists then assign a new unique one, overwrites XPMP2::Aircraft::modeS_id. More...

#define	XPMP_CFG_ITM_SUPPORT_REMOTE "support_remote"
	Config key: Support remote connections? `<0` force off, `0` default: on if in a networked or multiplayer setup, `>0` force on. More...

#define	XPMP_CFG_ITM_CONTR_MIN_ALT "contrail_min_alt"
	Config key: Minimum altitude in feet for automatic contrail generation. More...

#define	XPMP_CFG_ITM_CONTR_MAX_ALT "contrail_max_alt"
	Config key: Maximum altitude in feet for automatic contrail generation, set both min and max altitude to `0` to switch off automatic contrails. More...

#define	XPMP_CFG_ITM_CONTR_LIFE "contrail_life_time"
	Config key: Default maximum lifetime of contrail puffs in seconds, determines contrail length. More...

#define	XPMP_CFG_ITM_CONTR_MULTI "contrail_multiple"
	Config key: Boolean: Shall multiple contrails be auto-created (one per engine), or just one (to safe FPS)? More...

#define	XPMP_CFG_ITM_ACTIVATE_SOUND "activate_sound"
	Config key: Activate Sound upon initial startup? (No effect later) More...

#define	XPMP_CFG_ITM_FMOD_INSTANCE "force_fmod_instance"
	Config key: Never use XP's FMOD instance, always create our own. More...

#define	XPMP_CFG_ITM_MUTE_ON_PAUSE "mute_on_pause"
	Config key: Mute all sound temporarily while X-Plane is in a paused state? More...

#define	XPMP_CFG_ITM_LOGLEVEL "log_level"
	Config key: General level of logging into `Log.txt` (0 = Debug, 1 = Info, 2 = Warning, 3 = Error, 4 = Fatal) More...

#define	XPMP_CFG_ITM_MODELMATCHING "model_matching"
	Config key: Write information on model matching and sound selection into `Log.txt` More...

Sound Macros
#define	XP_SOUND_ELECTRIC "Electric"

#define	XP_SOUND_HIBYPASSJET "HiBypassJet"

#define	XP_SOUND_LOBYPASSJET "LoBypassJet"

#define	XP_SOUND_TURBOPROP "Turboprop"

#define	XP_SOUND_PROP_AIRPLANE "PropAirplane"

#define	XP_SOUND_PROP_HELI "PropHeli"

#define	XP_SOUND_REVERSE_THRUST "ReverseThrust"

#define	XP_SOUND_ROLL_RUNWAY "RollRunway"

#define	XP_SOUND_FLAP "Flap"

#define	XP_SOUND_GEAR "Gear"

Typedefs
typedef unsigned int	XPMPLightsPattern
	Light flash pattern (unused in XPMP2) More...

typedef unsigned	XPMPPlaneID
	Unique ID for an aircraft created by a plugin. More...

typedef int(*	XPMPIntPrefsFuncTy) (const char _section, const char _key, int _default)
	Definition for the type of configuration callback function. More...

typedef XPMPPlaneCallbackResult(*	XPMPPlaneData_f) (XPMPPlaneID inPlane, XPMPPlaneDataType inDataType, void ioData, void inRefcon)
	Callback function your plugin provides to return updated plane data. More...

typedef void(*	XPMPPlaneNotifier_f) (XPMPPlaneID inPlaneID, XPMPPlaneNotification inNotification, void *inRefcon)
	Type of the callback function you provide, called when one of the events defined in XPMPPlaneNotification happens. More...

typedef void(*	XPMPRenderPlanes_f) (int inIsBlend, void *inRef)
	The original libxplanemp allowed to override rendering; no longer supported. More...

Enumerations
enum	{ xpmp_Lights_Pattern_Default = 0 , xpmp_Lights_Pattern_EADS = 1 , xpmp_Lights_Pattern_GA = 2 }
	Light flash patterns. More...

enum	XPMPTransponderMode { xpmpTransponderMode_Standby , xpmpTransponderMode_Mode3A , xpmpTransponderMode_ModeC , xpmpTransponderMode_ModeC_Low , xpmpTransponderMode_ModeC_Ident }
	These enumerations define the way the transponder of a given plane is operating. More...

enum	XPMPPlaneDataType { xpmpDataType_Position = 1L << 1 , xpmpDataType_Surfaces = 1L << 2 , xpmpDataType_Radar = 1L << 3 , xpmpDataType_InfoTexts = 1L << 4 }
	This enum defines the different categories of aircraft information we can query about. More...

enum	XPMPPlaneCallbackResult { xpmpData_Unavailable = 0 , xpmpData_Unchanged = 1 , xpmpData_NewData = 2 }
	Definfes the different responses to asking for information. More...

enum	XPMPPlaneNotification { xpmp_PlaneNotification_Created = 1 , xpmp_PlaneNotification_ModelChanged = 2 , xpmp_PlaneNotification_Destroyed = 3 }
	Events that trigger a notification callback. More...

Functions
Initialization
const char *	XPMPMultiplayerInitLegacyData (const char inCSLFolder, const char inPluginName, const char resourceDir, XPMPIntPrefsFuncTy inIntPrefsFunc=nullptr, const char inDefaultICAO=nullptr, const char *inPluginLogAcronym=nullptr)
	Deprecated legacy initialization of XPMP2. More...

const char *	XPMPMultiplayerInit (const char inPluginName, const char resourceDir, XPMPIntPrefsFuncTy inIntPrefsFunc=nullptr, const char inDefaultICAO=nullptr, const char inPluginLogAcronym=nullptr)
	Initializes the XPMP2 library. This shall be your first call to the library. More...

void	XPMPSetPluginName (const char inPluginName, const char inPluginLogAcronym=nullptr)
	Overrides the plugin's name to be used in Log output. More...

void	XPMPMultiplayerCleanup ()
	Clean up the multiplayer library. More...

bool	XPMPContrailsAutoEnabled ()
	Are automatic Contrails enabled? More...

bool	XPMPContrailsAvailable ()
	Are Contrails available? More...

const char *	XPMPMultiplayerOBJ7SupportEnable (const char *inTexturePath)
	Used to set the light textures for old OBJ7 models. More...

Sound
bool	XPMPSoundEnable (bool bEnable=true)
	Enable/Disable Sound. More...

bool	XPMPSoundIsEnabled ()
	Is Sound enabled? More...

void	XPMPSoundSetMasterVolume (float fVol=1.0f)
	Set Master Volume. More...

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

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. More...

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

AI / Multiplayer plane control
const char *	XPMPMultiplayerEnable (void(_callback)(void )=nullptr, void *_refCon=nullptr)
	Tries to grab control of TCAS targets (formerly known as AI/multiplayer) from X-Plane. More...

void	XPMPMultiplayerDisable ()
	Release TCAS targets control. More...

bool	XPMPHasControlOfAIAircraft ()
	Has XPMP2 control of TCAS targets? More...

CSL Package Handling
const char *	XPMPLoadCSLPackage (const char *inCSLFolder)
	Loads CSL packages from the given folder, searching up to 5 folder levels deep. More...

void	XPMPLoadPlanesIfNecessary ()
	Legacy function only provided for backwards compatibility. Does not actually do anything. More...

int	XPMPGetNumberOfInstalledModels ()
	Returns the number of loaded CSL models. More...

void	XPMPGetModelInfo (int inIndex, const char outModelName, const char outIcao, const char outAirline, const char outLivery)
	Fetch information about a CSL model identified by an index. More...

void	XPMPGetModelInfo2 (int inIndex, std::string &outModelName, std::string &outIcao, std::string &outAirline, std::string &outLivery)
	Fetch information about a CSL model identified by an index. More...

int	XPMPModelMatchQuality (const char inICAO, const char inAirline, const char *inLivery)
	Tests model match quality based on the given parameters. More...

bool	XPMPIsICAOValid (const char *inICAO)
	Is `inICAO` a valid ICAO aircraft type designator? More...

size_t	XPMPAddModelDataRef (const std::string &dataRef)
	Add a user-defined dataRef to the list of dataRefs supported by every plane. More...

Plane Creation API
XPMPPlaneID	XPMPCreatePlane (const char inICAOCode, const char inAirline, const char inLivery, XPMPPlaneData_f inDataFunc, void inRefcon, XPMPPlaneID inModeS_id=0)
	Creates a new plane. More...

XPMPPlaneID	XPMPCreatePlaneWithModelName (const char inModelName, const char inICAOCode, const char inAirline, const char inLivery, XPMPPlaneData_f inDataFunc, void *inRefcon, XPMPPlaneID inModeS_id=0)
	Creates a new plane, providing a specific CSL model name. More...

void	XPMPDestroyPlane (XPMPPlaneID _id)
	[Deprecated] Removes a plane previously created with XPMPCreatePlane() More...

void	XPMPSetPlaneVisibility (XPMPPlaneID _id, bool _bVisible)
	Show/Hide the aircraft temporarily without destroying the object. More...

int	XPMPChangePlaneModel (XPMPPlaneID inPlaneID, const char inICAOCode, const char inAirline, const char *inLivery)
	Perform model matching again and change the CSL model to the resulting match. More...

int	XPMPGetPlaneModelName (XPMPPlaneID inPlaneID, char *outTxtBuf, int outTxtBufSize)
	Return the name of the model, with which the given plane is rendered. More...

void	XPMPGetPlaneICAOAndLivery (XPMPPlaneID inPlane, char outICAOCode, char outLivery)
	Returns ICAO aircraft type designator and livery of the given plane. More...

XPMPPlaneCallbackResult	XPMPGetPlaneData (XPMPPlaneID inPlane, XPMPPlaneDataType inDataType, void *outData)
	Unsupported, don't use. More...

int	XPMPGetPlaneModelQuality (XPMPPlaneID inPlane)
	Returns the match quality of the currently used model, or `-1` if `inPlane` is invalid. More...

long	XPMPCountPlanes (void)
	Returns the number of planes in existence. More...

XPMPPlaneID	XPMPGetNthPlane (long index)
	Returns the plane ID of the Nth plane. More...

XPMP2::Aircraft *	XPMPGetAircraft (XPMPPlaneID _id)
	Returns the underlying aircraft object, or `nullptr` if `_id` is invalid. More...

void	XPMPSetDefaultPlaneICAO (const char _acIcaoType, const char _carIcaoType=nullptr)
	Define default aircraft and ground vehicle ICAO types. More...

Plane Observation API
void	XPMPRegisterPlaneNotifierFunc (XPMPPlaneNotifier_f inFunc, void *inRefcon)
	Registers a callback, which is called when one of the events defined in XPMPPlaneNotification happens. More...

void	XPMPUnregisterPlaneNotifierFunc (XPMPPlaneNotifier_f inFunc, void *inRefcon)
	Unregisters a notification callback. Both function pointer and refcon must match what was registered. More...

Plane Rendering API
void	XPMPSetPlaneRenderer (XPMPRenderPlanes_f inRenderer, void *inRef)
	The original libxplanemp allowed to override rendering; no longer supported. More...

void	XPMPDumpOneCycle (void)
	Legacy debug-support function, no longer supported. More...

void	XPMPEnableAircraftLabels (bool _enable=true)
	Enable or disable drawing of labels with the aircraft. More...

void	XPMPDisableAircraftLabels ()
	Disable drawing of labels with the aircraft. More...

bool	XPMPDrawingAircraftLabels ()
	Returns if labels are currently configured to be drawn. More...

void	XPMPSetAircraftLabelDist (float _dist_nm, bool _bCutOffAtVisibility=true)

void	XPMPEnableMap (bool _bEnable, bool _bLabels=true)
	Enable or disable the drawing of aircraft icons on X-Plane's map. More...

Variables
constexpr XPMPPlaneID	MIN_MODE_S_ID = 0x00000001
	Minimum allowed XPMPPlaneID / mode S id. More...

constexpr XPMPPlaneID	MAX_MODE_S_ID = 0x00FFFFFF
	Maximum allowed XPMPPlaneID / mode S id. More...

Detailed Description

Initialization and general control functions for XPMP2.

Note: This file bases on and should be largely compile-compatible to the header provided with the original libxplanemp.; Some functions are marked deprecated, reason is given with each function. They are only provided for backward compatibility.

This is one of two main header files for using XPMP2. (The other is XPMPAircraft.h). XPMP2 is a library allowing an X-Plane plugin to have planes rendered in X-Plane's 3D world based on OBJ8 CSL models, which need to be installed separately. The plugin shall subclass XPMP2::Aircraft and override the abstract virtual function XPMP2::Aircraft::UpdatePosition() to provide updated position and attitude information. XPMP2 takes care of reading and initializaing CSL models, instanciating and updating the aircraft objects in X-Plane, display in a map layer, provisioning information via X-Plane's TCAS targets and AI/multiplayer (and more) dataRefs.

See also: For more developer's information see https://twinfan.github.io/XPMP2/; Sample and "How to" available, see https://twinfan.github.io/XPMP2/HowTo.html; For TCAS Override approach see https://developer.x-plane.com/article/overriding-tcas-and-providing-traffic-information/; For a definition of ICAO aircraft type designators see https://www.icao.int/publications/DOC8643/Pages/Search.aspx; For a list of ICAO airline/operator codes see https://en.wikipedia.org/wiki/List_of_airline_codes

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!

Author: Ben Supnik and Chris Serio

Copyright: Copyright (c) 2004, Ben Supnik and Chris Serio.

Author: Birger Hoppe

Copyright: (c) 2020-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

◆ XPMPPlanePosition_t

struct XPMPPlanePosition_t

This data structure contains the basic position info for an aircraft.

XPMPPosition_t

Note: This structure is only used with deprecated concepts (class XPCAircraft and direct use of callback functions.); There is no notion of aircraft velocity or acceleration; you will be queried for your position every rendering frame. Higher level APIs can use velocity and acceleration.

Class Members
int	aiPrio	Priority for AI/TCAS consideration, the lower the earlier.
bool	clampToGround	enables ground-clamping for this aircraft (can be expensive, see XPMP2::Aircraft::bClampToGround)
double	elevation	current altitude of aircraft [ft above MSL]
float	heading	heading [degrees]
char	label[32]	label to show with the aircraft
float	label_color[4]	label base color (RGB), defaults to yellow
double	lat	current position of aircraft (latitude)
double	lon	current position of aircraft (longitude)
int	multiIdx	OUT: set by XPMP2 to inform application about TCAS target index in use [1..63], with [1..19] also being available via classic multiplayer dataRefs, `< 1` means 'none'.
float	offsetScale	how much of the surface contact correction offset should be applied [0..1]
float	pitch	pitch [degrees, psitive up]
float	roll	roll [degrees, positive right]
long	size	size of structure

◆ xpmp_LightStatus

union xpmp_LightStatus

Defines, which lights of the aircraft are on.

Note: This structure is only used with deprecated concepts (class XPCAircraft and direct use of callback functions.)

Class Members
struct xpmp_LightStatus	__unnamed__
unsigned int	lightFlags	this defaults to taxi \| beacon \| nav lights on

◆ XPMPPlaneSurfaces_t

struct XPMPPlaneSurfaces_t

External physical configuration of the plane.

Note: This structure is only used with deprecated concepts (class XPCAircraft and direct use of callback functions.)

This data structure will contain information about the external physical configuration of the plane, things you would notice if you are seeing it from outside. This includes flap position, gear position, etc.

Class Members
float	engRotDegree	engine rotation angle (degrees 0..360)
float	engRotRpm	engine rotation speed (rpm)
float	flapRatio	flap extension ratio [0..1]
float	gearPosition	gear position [0..1]
xpmp_LightStatus	lights	status of lights
float	propRotDegree	prop rotation angle (degrees 0..360)
float	propRotRpm	prop rotation speed (rpm)
float	reversRatio	thrust reversers ratio
long	size	structure size
float	slatRatio	slats extension ratio [0..1]
float	speedBrakeRatio	speed brake extension ratio [0..1]
float	spoilerRatio	spoiler extension ratio [0..1]
float	thrust	thrust ratio [0..1]
float	tireDeflect	tire deflection (meters)
float	tireRotDegree	tire rotation angle (degrees 0..360)
float	tireRotRpm	tire rotation speed (rpm)
bool	touchDown	just now is moment of touch down?
float	wingSweep	wing sweep ratio [0..1]
float	yokeHeading	yoke heading ratio [0..1]
float	yokePitch	yoke pitch ratio [0..1]
float	yokeRoll	yoke roll ratio [0..1]

◆ XPMPPlaneRadar_t

struct XPMPPlaneRadar_t

defines information about an aircraft visible to radar.

Class Members
long	code	current radar code, published via dataRef `sim/cockpit2/tcas/targets/modeC_code`
XPMPTransponderMode	mode	current radar mode, if not `xpmpTransponderMode_Standby` then is plane considered for TCAS display
long	size	structure size

◆ XPMPInfoTexts_t

struct XPMPInfoTexts_t

Textual information of planes to be passed on via shared dataRefs to other plugins.

The texts are not used within XPMP2 in any way, just passed on to dataRefs

Class Members
char	airline[40]	airline, human readable
char	aptFrom[5]	Origin airport (ICAO)
char	aptTo[5]	Destination airport (ICAO)
char	flightNum[10]	flight number
char	icaoAcType[5]	ICAO aircraft type designator, 3-4 chars.
char	icaoAirline[4]	ICAO airline code.
char	manufacturer[40]	a/c manufacturer, human readable
char	model[40]	a/c model, human readable
long	size	structure size
char	tailNum[10]	registration, tail number

◆ xpmp_LightStatus.unnamed2

struct xpmp_LightStatus.__unnamed2__

Class Members
unsigned int	bcnLights: 1	beacon on?
XPMPLightsPattern	flashPattern: 4	light pattern (unused in XPMP2)
unsigned int	landLights: 1	landing lights on?
unsigned int	navLights: 1	navigation lights on?
unsigned int	strbLights: 1	strobe lights on?
unsigned int	taxiLights: 1	taxi lights on?
unsigned int	timeOffset: 16	time offset to avoid lights across planes blink in sync (unused in XPMP2)

Macro Definition Documentation

◆ XP_SOUND_ELECTRIC

#define XP_SOUND_ELECTRIC "Electric"

◆ XP_SOUND_FLAP

#define XP_SOUND_FLAP "Flap"

◆ XP_SOUND_GEAR

#define XP_SOUND_GEAR "Gear"

◆ XP_SOUND_HIBYPASSJET

#define XP_SOUND_HIBYPASSJET "HiBypassJet"

◆ XP_SOUND_LOBYPASSJET

#define XP_SOUND_LOBYPASSJET "LoBypassJet"

◆ XP_SOUND_PROP_AIRPLANE

#define XP_SOUND_PROP_AIRPLANE "PropAirplane"

◆ XP_SOUND_PROP_HELI

#define XP_SOUND_PROP_HELI "PropHeli"

◆ XP_SOUND_REVERSE_THRUST

#define XP_SOUND_REVERSE_THRUST "ReverseThrust"

◆ XP_SOUND_ROLL_RUNWAY

#define XP_SOUND_ROLL_RUNWAY "RollRunway"

◆ XP_SOUND_TURBOPROP

#define XP_SOUND_TURBOPROP "Turboprop"

◆ XPMP_CFG_ITM_ACTIVATE_SOUND

#define XPMP_CFG_ITM_ACTIVATE_SOUND "activate_sound"

Config key: Activate Sound upon initial startup? (No effect later)

◆ XPMP_CFG_ITM_CLAMPALL

#define XPMP_CFG_ITM_CLAMPALL "clamp_all_to_ground"

Config key: Ensure no plane sinks below ground, no matter of XPMP2::Aircraft::bClampToGround.

◆ XPMP_CFG_ITM_CONTR_LIFE

#define XPMP_CFG_ITM_CONTR_LIFE "contrail_life_time"

Config key: Default maximum lifetime of contrail puffs in seconds, determines contrail length.

◆ XPMP_CFG_ITM_CONTR_MAX_ALT

#define XPMP_CFG_ITM_CONTR_MAX_ALT "contrail_max_alt"

Config key: Maximum altitude in feet for automatic contrail generation, set both min and max altitude to 0 to switch off automatic contrails.

◆ XPMP_CFG_ITM_CONTR_MIN_ALT

#define XPMP_CFG_ITM_CONTR_MIN_ALT "contrail_min_alt"

Config key: Minimum altitude in feet for automatic contrail generation.

◆ XPMP_CFG_ITM_CONTR_MULTI

#define XPMP_CFG_ITM_CONTR_MULTI "contrail_multiple"

Config key: Boolean: Shall multiple contrails be auto-created (one per engine), or just one (to safe FPS)?

◆ XPMP_CFG_ITM_FMOD_INSTANCE

#define XPMP_CFG_ITM_FMOD_INSTANCE "force_fmod_instance"

Config key: Never use XP's FMOD instance, always create our own.

◆ XPMP_CFG_ITM_HANDLE_DUP_ID

#define XPMP_CFG_ITM_HANDLE_DUP_ID "handle_dup_id"

Config key: Boolean: If XPMP2::Aircraft::modeS_id already exists then assign a new unique one, overwrites XPMP2::Aircraft::modeS_id.

◆ XPMP_CFG_ITM_LOGLEVEL

#define XPMP_CFG_ITM_LOGLEVEL "log_level"

Config key: General level of logging into Log.txt (0 = Debug, 1 = Info, 2 = Warning, 3 = Error, 4 = Fatal)

◆ XPMP_CFG_ITM_MODELMATCHING

#define XPMP_CFG_ITM_MODELMATCHING "model_matching"

Config key: Write information on model matching and sound selection into Log.txt

◆ XPMP_CFG_ITM_MUTE_ON_PAUSE

#define XPMP_CFG_ITM_MUTE_ON_PAUSE "mute_on_pause"

Config key: Mute all sound temporarily while X-Plane is in a paused state?

◆ XPMP_CFG_ITM_REPLDATAREFS

#define XPMP_CFG_ITM_REPLDATAREFS "replace_datarefs"

Config key: Replace dataRefs in OBJ8 files upon load, creating new OBJ8 files for XPMP2 (defaults to OFF!)

◆ XPMP_CFG_ITM_REPLTEXTURE

#define XPMP_CFG_ITM_REPLTEXTURE "replace_texture"

Config key: Replace textures in OBJ8 files upon load if needed (specified on the OBJ8 line in xsb_aircraft.txt), creating new OBJ8 files.

◆ XPMP_CFG_ITM_SUPPORT_REMOTE

#define XPMP_CFG_ITM_SUPPORT_REMOTE "support_remote"

Config key: Support remote connections? <0 force off, 0 default: on if in a networked or multiplayer setup, >0 force on.

◆ XPMP_CFG_SEC_DEBUG

#define XPMP_CFG_SEC_DEBUG "debug"

Config section "debug".

◆ XPMP_CFG_SEC_MODELS

#define XPMP_CFG_SEC_MODELS "models"

Config section "models".

◆ XPMP_CFG_SEC_PLANES

#define XPMP_CFG_SEC_PLANES "planes"

Config section "planes".

◆ XPMP_CFG_SEC_SOUND

#define XPMP_CFG_SEC_SOUND "sound"

Config section "sound".

Typedef Documentation

◆ XPMPIntPrefsFuncTy

typedef int(* XPMPIntPrefsFuncTy) (const char *_section, const char *_key, int _default)

Definition for the type of configuration callback function.

The plugin using XPMP2 can provide such a callback function via XPMPMultiplayerInit(). It will be called max. every 2s to fetch each of the following configuration values:

section | key                 | type | default | description
------- | ------------------- | ---- | ------- | -------------------------------------------------------------------------
models | replace_datarefs    | int |    0    | Replace dataRefs in OBJ8 files upon load, creating new OBJ8 files for XPMP2 (defaults to OFF!)
models | replace_texture     | int |    1    | Replace textures in OBJ8 files upon load if needed (specified on the OBJ8 line in xsb_aircraft.txt), creating new OBJ8 files
planes | clamp_all_to_ground | int |    1    | Ensure no plane sinks below ground, no matter of XPMP2::Aircraft::bClampToGround
planes | handle_dup_id       | int |    0    | Boolean: If XPMP2::Aircraft::modeS_id already exists then assign a new unique one, overwrites XPMP2::Aircraft::modeS_id
planes | support_remote      | int |    0    | 3-state integer: Support remote connections? <0 force off, 0 default: on if in a networked or multiplayer setup, >0 force on
planes | contrail_min_alt    | int | 25000 | Minimum altitude in feet for automatic contrail generation
planes | contrail_max_alt    | int | 45000 | Maximum altitude in feet for automatic contrail generation, set both min and max altitude to 0 to switch off automatic contrails
planes | contrail_life_time  | int |   25    | Default maximum lifetime of contrail puffs in seconds, determines contrail length
planes | contrail_multiple   | int |    0    | Boolean: Shall multiple contrails be auto-created (one per engine), or just one (to safe FPS)?
sound   | activate_sound      | int |    1    | Activate Sound upon initial startup? (No effect later)
sound   | force_fmod_instance | int |    0    | Never use XP's FMOD instance, always create our own
sound   | mute_on_pause       | int |    1    | Mute all sound temporarily while X-Plane is in a paused state?
debug   | log_level           | int |    2    | General level of logging into Log.txt (0 = Debug, 1 = Info, 2 = Warning, 3 = Error, 4 = Fatal)
debug   | model_matching      | int |    0    | Write information on model matching and sound selection into Log.txt

Note: There is no immediate requirement to check the value of _section in your implementation. _key by itself is unique. Compare it with any of the XPMP_CFG_ITM_* values and return your value.

Parameters

_section	Configuration section, ie. group of values, any of the `XPMP_CFG_SEC_...` values
_key	Any of the `XPMP_CFG_ITM_*` values to indicate which config value is to be returned.
_default	A default provided by XPMP2. Have your callback return `_default` if you don't want to explicitely set a value or don't know the `_key`.

Returns: Your callback shall return your config value for config item _key

◆ XPMPLightsPattern

typedef unsigned int XPMPLightsPattern

Light flash pattern (unused in XPMP2)

◆ XPMPPlaneData_f

typedef XPMPPlaneCallbackResult(* XPMPPlaneData_f) (XPMPPlaneID inPlane, XPMPPlaneDataType inDataType, void *ioData, void *inRefcon)

Callback function your plugin provides to return updated plane data.

Note: This type is only used with deprecated concepts (direct use of callback functions.)

This functions is called by XPMP2 once per cycle per plane per data type. Your implementation returns the requested data, so that XPMP2 can move and update the associated aircraft instance.

Parameters

	inPlane	ID of the plane, for which data is requested
	inDataType	The type of data that is requested, see XPMPPlaneDataType
[out]	ioData	A pointer to a structure XPMP2 provides, for you to fill the data into. For its type see XPMPPlaneDataType.
	inRefcon	The refcon value you provided when creating the plane

◆ XPMPPlaneID

typedef unsigned XPMPPlaneID

Unique ID for an aircraft created by a plugin.

Note: In XPMP2 this value is no longer a pointer to an internal memory address, but will directly be used as modeS_id in the new TCAS override approach.

◆ XPMPPlaneNotifier_f

typedef void(* XPMPPlaneNotifier_f) (XPMPPlaneID inPlaneID, XPMPPlaneNotification inNotification, void *inRefcon)

Type of the callback function you provide, called when one of the events defined in XPMPPlaneNotification happens.

Parameters

inPlaneID	Identifies the affected plane
inNotification	The event that took place
inRefcon	A refcon that you provided in XPMPRegisterPlaneNotifierFunc()

◆ XPMPRenderPlanes_f

typedef void(* XPMPRenderPlanes_f) (int inIsBlend, void *inRef)

The original libxplanemp allowed to override rendering; no longer supported.

Deprecated:: Unsupported in XPMP2. The type definition is available to stay compile-time compatible, but the callback will not be called.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Light flash patterns.

Note: Unused in XPMP2; Now changed to proper enum type as it is used in bitfields in XPMP2::xpmp_LightStatus, which causes misleading, non-suppressable warnings in gcc:
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=51242

Enumerator
xpmp_Lights_Pattern_Default	Jets: one strobe flash, short beacon (-——*—)
xpmp_Lights_Pattern_EADS	Airbus+EADS: strobe flashes twice (----—-–), short beacon.
xpmp_Lights_Pattern_GA	GA: one strobe flash, long beacon (------——)

◆ XPMPPlaneCallbackResult

enum XPMPPlaneCallbackResult

Definfes the different responses to asking for information.

Note: This enum is only used with deprecated concepts (class XPCAircraft and direct use of callback functions.)

Enumerator
xpmpData_Unavailable
xpmpData_Unchanged
xpmpData_NewData

◆ XPMPPlaneDataType

enum XPMPPlaneDataType

This enum defines the different categories of aircraft information we can query about.

Note: While these enums are defined in a way that they could be combined together, there is no place, which makes use of this possibility. Each value will be used individually only. Because of this, the definition has been changed in XPMP2 to an actual enum type for clarity.; This enum is only used with deprecated concepts (class XPCAircraft and direct use of callback functions.)

Enumerator
xpmpDataType_Position	position data in XPMPPlanePosition_t
xpmpDataType_Surfaces	physical appearance in XPMPPlaneSurfaces_t
xpmpDataType_Radar	radar information in XPMPPlaneRadar_t
xpmpDataType_InfoTexts	informational texts in XPMPInfoTexts_t

◆ XPMPPlaneNotification

enum XPMPPlaneNotification

Events that trigger a notification callback.

Enumerator
xpmp_PlaneNotification_Created	a plane was just created
xpmp_PlaneNotification_ModelChanged	a plane's model changed
xpmp_PlaneNotification_Destroyed	a plane is about to be destroyed

◆ XPMPTransponderMode

enum XPMPTransponderMode

These enumerations define the way the transponder of a given plane is operating.

Note: Only information used by XPMP2 is "mode != xpmpTransponderMode_Standby", in which case the plane is considered for TCAS display.

Enumerator
xpmpTransponderMode_Standby	transponder is in standby, not currently sending -> aircraft not visible on TCAS
xpmpTransponderMode_Mode3A	transponder is on
xpmpTransponderMode_ModeC	transponder is on
xpmpTransponderMode_ModeC_Low	transponder is on
xpmpTransponderMode_ModeC_Ident	transponder is on

Function Documentation

◆ XPMPAddModelDataRef()

size_t XPMPAddModelDataRef ( const std::string & dataRef )

Add a user-defined dataRef to the list of dataRefs supported by every plane.

All planes created by XPMP2 define the same set of dataRefs. See XPMP2::DR_VALS for the definitions that come pre-defined with XPMP2. Here you can add more dataRefs that you want to set in your XPMP2::Aircraft::UpdatePosition() implementation.

Returns: The functions returns the array index you need to use in the XPMP2::Aircraft::v array to provide the actual value. Or 0 when an error occured.

Note: There is a duplication check: Adding an already existing dataRef, no matter if XPMP2-predefined or by the plugin will return the already existing index.; Can only be called while no plane exists as it influence the size of important data arrays. Returns 0 if called while planes exist.; Can only be called from XP's main thread as XPLM SDK functions are called. Returns 0 if called from a worker thread.; User-defined dataRefs are not transfered to the XPMP2 Remote Client for display on network-connected X-Plane instances.

◆ XPMPChangePlaneModel()

int XPMPChangePlaneModel	(	XPMPPlaneID	inPlaneID,
		const char *	inICAOCode,
		const char *	inAirline,
		const char *	inLivery
	)

Perform model matching again and change the CSL model to the resulting match.

Note: Effectively calls XPMP2::Aircraft::ChangeModel(), so if you have the aircraft object, prefer calling that function directly.

Parameters

inPlaneID	Which plane to change?
inICAOCode	ICAO aircraft type designator, like 'A320', 'B738', 'C172'
inAirline	ICAO airline code, like 'BAW', 'DLH', can be an empty string
inLivery	Special livery designator, can be an empty string

Returns: Match quality, the lower the better / -1 if inPlaneID is invalid

◆ XPMPContrailsAutoEnabled()

bool XPMPContrailsAutoEnabled ( )

Are automatic Contrails enabled?

Configured in a consistent way to automatically show contrails? (Max Altitude > Min Altitude) If off, use XPMP2::Aircraft::ContrailTrigger() or XPMP2::Aircraft::ContrailRequest().

◆ XPMPContrailsAvailable()

bool XPMPContrailsAvailable ( )

Are Contrails available?

Could return false e.g. if Resources/Contrail/Contrail.obj could not be found or loaded.

◆ XPMPCountPlanes()

long XPMPCountPlanes ( void )

Returns the number of planes in existence.

◆ XPMPCreatePlane()

XPMPPlaneID XPMPCreatePlane	(	const char *	inICAOCode,
		const char *	inAirline,
		const char *	inLivery,
		XPMPPlaneData_f	inDataFunc,
		void *	inRefcon,
		XPMPPlaneID	inModeS_id = `0`
	)

Creates a new plane.

Deprecated:: Subclass XPMP2::Aircraft instead

Effectively calls XPMPCreatePlaneWithModelName() with inModelName = nullptr

Parameters

inICAOCode	ICAO aircraft type designator, like 'A320', 'B738', 'C172'
inAirline	ICAO airline code, like 'BAW', 'DLH', can be an empty string
inLivery	Special livery designator, can be an empty string
inDataFunc	Callback function called by XPMP2 to fetch updated data
inRefcon	A refcon value passed back to you in all calls to the `inDataFunc`
inModeS_id	(optional) Unique identification of the plane [0x01..0xFFFFFF], e.g. the 24bit mode S transponder code. XPMP2 assigns an arbitrary unique number of not given

◆ XPMPCreatePlaneWithModelName()

XPMPPlaneID XPMPCreatePlaneWithModelName	(	const char *	inModelName,
		const char *	inICAOCode,
		const char *	inAirline,
		const char *	inLivery,
		XPMPPlaneData_f	inDataFunc,
		void *	inRefcon,
		XPMPPlaneID	inModeS_id = `0`
	)

Creates a new plane, providing a specific CSL model name.

Deprecated:: Subclass XPMP2::Aircraft instead

Parameters

inModelName	CSL Model name (id) to use, or `nullptr` if normal matching using the next 3 parameters shall be applied
inICAOCode	ICAO aircraft type designator, like 'A320', 'B738', 'C172'
inAirline	ICAO airline code, like 'BAW', 'DLH', can be an empty string
inLivery	Special livery designator, can be an empty string
inDataFunc	Callback function called by XPMP2 to fetch updated data
inRefcon	A refcon value passed back to you in all calls to the `inDataFunc`
inModeS_id	(optional) Unique identification of the plane [0x01..0xFFFFFF], e.g. the 24bit mode S transponder code. XPMP2 assigns an arbitrary unique number of not given

◆ XPMPDestroyPlane()

void XPMPDestroyPlane ( XPMPPlaneID _id )

[Deprecated] Removes a plane previously created with XPMPCreatePlane()

Deprecated:: Delete subclassed XPMP2::Aircraft object instead.

◆ XPMPDisableAircraftLabels()

void XPMPDisableAircraftLabels ( )

Disable drawing of labels with the aircraft.

Effectively calls XPMPEnableAircraftLabels()

◆ XPMPDrawingAircraftLabels()

bool XPMPDrawingAircraftLabels ( )

Returns if labels are currently configured to be drawn.

◆ XPMPDumpOneCycle()

void XPMPDumpOneCycle ( void )

Legacy debug-support function, no longer supported.

Deprecated:: No longer supported as rendering is done by X-Plane's instancing

◆ XPMPEnableAircraftLabels()

void XPMPEnableAircraftLabels ( bool _enable = true )

Enable or disable drawing of labels with the aircraft.

◆ XPMPEnableMap()

void XPMPEnableMap	(	bool	_bEnable,
		bool	_bLabels = `true`
	)

Enable or disable the drawing of aircraft icons on X-Plane's map.

Parameters

_bEnable	Enable or disable entire map functionality
_bLabels	If map is enabled, shall also labels be drawn?

XPMP2 creates a separate Map Layer named after the plugin for this purposes. By default, the map functionality is enabled including label writing.

◆ XPMPGetAircraft()

XPMP2::Aircraft* XPMPGetAircraft ( XPMPPlaneID _id )

Returns the underlying aircraft object, or nullptr if _id is invalid.

◆ XPMPGetModelInfo()

void XPMPGetModelInfo	(	int	inIndex,
		const char **	outModelName,
		const char **	outIcao,
		const char **	outAirline,
		const char **	outLivery
	)

Fetch information about a CSL model identified by an index.

Note: Index numbers may change if more models are loaded, don't rely on them. Model name is unique.

Deprecated:: Instead, use XPMPGetModelInfo2().
This legacy function is defined with pointers to text arrays as return type. This is rather unsafe. XPMP2's internal maps and buffers may change if more models are loaded, hence pointers may become invalid. Don't rely on these pointers staying valid over an extended period of time.

Parameters

	inIndex	Number between `0` and `XPMPGetNumberOfInstalledModels()-1
[out]	outModelName	Receives pointer to model name (id). Optional, can be nullptr.
[out]	outIcao	Receives pointer to ICAO aircraft type designator. Optional, can be `nullptr`.
[out]	outAirline	Receives pointer to ICAO airline code. Optional, can be `nullptr`.
[out]	outLivery	Receives pointer to special livery string. Optional, can be `nullptr`.

◆ XPMPGetModelInfo2()

void XPMPGetModelInfo2	(	int	inIndex,
		std::string &	outModelName,
		std::string &	outIcao,
		std::string &	outAirline,
		std::string &	outLivery
	)

Fetch information about a CSL model identified by an index.

Note: Index numbers may change if more models are loaded, don't rely on them. Model name is unique.

Parameters

	inIndex	Number between `0` and `XPMPGetNumberOfInstalledModels()-1
[out]	outModelName	Receives model name (id)
[out]	outIcao	Receives ICAO aircraft designator
[out]	outAirline	Receives ICAO airline code
[out]	outLivery	Receives special livery string

◆ XPMPGetNthPlane()

XPMPPlaneID XPMPGetNthPlane ( long index )

Returns the plane ID of the Nth plane.

◆ XPMPGetNumberOfInstalledModels()

int XPMPGetNumberOfInstalledModels ( )

Returns the number of loaded CSL models.

◆ XPMPGetPlaneData()

XPMPPlaneCallbackResult XPMPGetPlaneData	(	XPMPPlaneID	inPlane,
		XPMPPlaneDataType	inDataType,
		void *	outData
	)

Unsupported, don't use.

Deprecated:: Not supported in XPMP2! In the legacy library this is actually more like an internal function, calling all callback functions for querying aircraft data (much like XPCAircraft::UpdatePosition() is now in XPMP2). I doubt that it was intended to be called from the outside in the first place.

Returns: Always xpmpData_Unavailable

◆ XPMPGetPlaneICAOAndLivery()

void XPMPGetPlaneICAOAndLivery	(	XPMPPlaneID	inPlane,
		char *	outICAOCode,
		char *	outLivery
	)

Returns ICAO aircraft type designator and livery of the given plane.

Deprecated:: This legacy function is defined in a rather unsafe way. Instead, use XPMPGetAircraft() and access PMP2::Aircraft::acIcaoType and XPMP2::Aircraft::acLivery directly.

◆ XPMPGetPlaneModelName()

int XPMPGetPlaneModelName	(	XPMPPlaneID	inPlaneID,
		char *	outTxtBuf,
		int	outTxtBufSize
	)

Return the name of the model, with which the given plane is rendered.

Note: Effectively calls XPMP2::Aircraft::GetModelName(), so if you have the aircraft object, prefer calling that function directly.

Parameters

	inPlaneID	Identifies the plane
[out]	outTxtBuf	(optional) Points to a character array to hold the model name. The returned C string is guaranteed to be zero-terminated. Pass in NULL to just receive the string's length
	outTxtBufSize	Size of that buffer

Returns: Length of the model name to return (not counting the terminating zero, independend of the passed-in buffer). -1 if inPlaneID is invalid

◆ XPMPGetPlaneModelQuality()

int XPMPGetPlaneModelQuality ( XPMPPlaneID inPlane )

Returns the match quality of the currently used model, or -1 if inPlane is invalid.

◆ XPMPHasControlOfAIAircraft()

bool XPMPHasControlOfAIAircraft ( )

Has XPMP2 control of TCAS targets?

See also: XPMPMultiplayerEnable()

◆ XPMPIsICAOValid()

bool XPMPIsICAOValid ( const char * inICAO )

Is inICAO a valid ICAO aircraft type designator?

◆ XPMPLoadCSLPackage()

const char* XPMPLoadCSLPackage ( const char * inCSLFolder )

Loads CSL packages from the given folder, searching up to 5 folder levels deep.

This function mainly searches the given folder for packages. It traverses all folders in search for xsb_aircraft.txt files. It will find all xsb_aircraft.txt files situated at or below the given root path, up to 5 levels deep.
As soon as such a file is found it is read and processed. Depth search then ends. (But searching parallel folders may still continue.)
The xsb_aircraft.txt is loaded and processed. Duplicate models (by package and CSL model name, tags EXPORT_NAME and OBJ8_AIRCRAFT) are ignored. For others the existence of the .obj file is validated, but not the existence of files in turn needed by the .obj file, like textures. If validated successfully the model is added to an internal catalogue.
Actual loading of objects is done later and asynchronously only when needed during aircraft creation.

Parameters

inCSLFolder Root folder to start the search.

◆ XPMPLoadPlanesIfNecessary()

void XPMPLoadPlanesIfNecessary ( )

Legacy function only provided for backwards compatibility. Does not actually do anything.

◆ XPMPModelMatchQuality()

int XPMPModelMatchQuality	(	const char *	inICAO,
		const char *	inAirline,
		const char *	inLivery
	)

Tests model match quality based on the given parameters.

Parameters

inICAO	ICAO aircraft type designator, optional, can be `nullptr`
inAirline	ICAO airline code, optional, can be `nullptr`
inLivery	Special livery text, optional, can be `nullptr`

Returns: Match quality, the lower the better

◆ XPMPMultiplayerCleanup()

void XPMPMultiplayerCleanup ( )

Clean up the multiplayer library.

This shall be your last call to XPMP2. Call this latest from XPluginStop for proper and controlled cleanup of resources used by XPMP2.

◆ XPMPMultiplayerDisable()

void XPMPMultiplayerDisable ( )

Release TCAS targets control.

Afterwards, XPMP2's aircraft will no longer appear on TCAS or on 3rd-party plugins relying on TCAS targets dataRefs.
Is called during XPMPMultiplayerCleanup() automatically.

◆ XPMPMultiplayerEnable()

const char* XPMPMultiplayerEnable	(	void()(void )	_callback = `nullptr`,
		void *	_refCon = `nullptr`
	)

Tries to grab control of TCAS targets (formerly known as AI/multiplayer) from X-Plane.

Only one plugin can have TCAS targets control at any one time. So be prepared to properly handle an non-empty response that indicates that you did not get control now. The returned message includes the name of the plugin currently having control.
If successful, XPMP2's aircraft will appear on TCAS and are available to 3rd-party plugins relying on TCAS tagrtes or multiplayer dataRefs.
Typically, a plugin calls this function just before the first aircraft are created. But it could also be bound to a menu item, for example.

Parameters

_callback	(optional) You can provide a callback function, which is called directly by X-Plane when control of TCAS targets is not successful now but becomes available later.
_refCon	(optional) A value just passed through to the callback.

See also: X-Plane SDK documentation on XPLMAcquirePlanes for more details about the callback.

Returns: Empty string on success, human-readable error message otherwise, includes name of plugin currently having TCAS tagrets control

◆ XPMPMultiplayerInit()

const char* XPMPMultiplayerInit	(	const char *	inPluginName,
		const char *	resourceDir,
		XPMPIntPrefsFuncTy	inIntPrefsFunc = `nullptr`,
		const char *	inDefaultICAO = `nullptr`,
		const char *	inPluginLogAcronym = `nullptr`
	)

Initializes the XPMP2 library. This shall be your first call to the library.

Note: Parameters changed compared to libxplanemp!

Parameters

inPluginName	Your plugin's name, mainly used as map layer name and for logging
resourceDir	The directory where XPMP2 finds all required supplemental files (`Doc8643.txt`, `MapIcons.png`, `related.txt`, optionally `Obj8DataRefs.txt`)
inIntPrefsFunc	(optional) A pointer to a callback function providing integer config values. See XPMPIntPrefsFuncTy for details.
inDefaultICAO	(optional) A fallback aircraft type if no type can be deduced otherwise for an aircraft.
inPluginLogAcronym	(optional) A short text to be used in log output. If not given then `inPluginName` is used also for this purpose.

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

Assume that this is XP's main thread

◆ XPMPMultiplayerInitLegacyData()

const char* XPMPMultiplayerInitLegacyData	(	const char *	inCSLFolder,
		const char *	inPluginName,
		const char *	resourceDir,
		XPMPIntPrefsFuncTy	inIntPrefsFunc = `nullptr`,
		const char *	inDefaultICAO = `nullptr`,
		const char *	inPluginLogAcronym = `nullptr`
	)

Deprecated legacy initialization of XPMP2.

Note: Parameters changed compared to libxplanemp!

Effectively calls, in this order, XPMPMultiplayerInit() and XPMPLoadCSLPackage().

See also: XPMPMultiplayerInit() and XPMPLoadCSLPackage() for details on the parameters.

◆ XPMPMultiplayerOBJ7SupportEnable()

const char* XPMPMultiplayerOBJ7SupportEnable ( const char * inTexturePath )

Used to set the light textures for old OBJ7 models.

Note: Unsupported with XPMP2, will always return "OBJ7 format is no longer supported"

◆ XPMPRegisterPlaneNotifierFunc()

void XPMPRegisterPlaneNotifierFunc	(	XPMPPlaneNotifier_f	inFunc,
		void *	inRefcon
	)

Registers a callback, which is called when one of the events defined in XPMPPlaneNotification happens.

Parameters

inFunc	Pointer to your callback function
inRefcon	A refcon passed through to your callback

◆ XPMPSetAircraftLabelDist()

void XPMPSetAircraftLabelDist	(	float	_dist_nm,
		bool	_bCutOffAtVisibility = `true`
	)

Configure maximum label distance and if labels shall be cut off at reported visibility

Parameters

_dist_nm	Maximum label distance in nm, default is 3, minimum is 1
_bCutOffAtVisibility	Shall labels not be drawn further away than XP's reported visibility?

◆ XPMPSetDefaultPlaneICAO()

void XPMPSetDefaultPlaneICAO	(	const char *	_acIcaoType,
		const char *	_carIcaoType = `nullptr`
	)

Define default aircraft and ground vehicle ICAO types.

Parameters

_acIcaoType	Default ICAO aircraft type designator, used when matching returns nothing
_carIcaoType	Type used to identify ground vehicels (internally defaults to "ZZZC")

◆ XPMPSetPlaneRenderer()

void XPMPSetPlaneRenderer	(	XPMPRenderPlanes_f	inRenderer,
		void *	inRef
	)

The original libxplanemp allowed to override rendering; no longer supported.

Deprecated:: Unsupported in XPMP2. The function is available to stay compile-time compatible, but it does nothing.

◆ XPMPSetPlaneVisibility()

void XPMPSetPlaneVisibility	(	XPMPPlaneID	_id,
		bool	_bVisible
	)

Show/Hide the aircraft temporarily without destroying the object.

◆ XPMPSetPluginName()

void XPMPSetPluginName	(	const char *	inPluginName,
		const char *	inPluginLogAcronym = `nullptr`
	)

Overrides the plugin's name to be used in Log output.

The same as providing a plugin name with XPMPMultiplayerInit(). If no name is provided, it defaults to the plugin's name as set in XPluginStart().

Note: Replaces the compile-time macro XPMP_CLIENT_LONGNAME needed in libxplanemp.

Parameters

inPluginName	Your plugin's name, used as map layer name, and as folder name under `Aircraft`
inPluginLogAcronym	(optional) A short text to be used in log output. If not given then `inPluginName` is used also for this purpse.

◆ 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.

◆ XPMPSoundIsEnabled()

bool XPMPSoundIsEnabled ( )

Is Sound enabled?

◆ XPMPSoundMute()

void XPMPSoundMute ( bool bMute )

Mute all sounds (temporarily)

Parameters

bMute Mute (true) or unmute (false)?

◆ 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.

◆ XPMPUnregisterPlaneNotifierFunc()

void XPMPUnregisterPlaneNotifierFunc	(	XPMPPlaneNotifier_f	inFunc,
		void *	inRefcon
	)

Unregisters a notification callback. Both function pointer and refcon must match what was registered.

Parameters

inFunc	Pointer to your callback function
inRefcon	A refcon passed through to your callback

Variable Documentation

◆ MAX_MODE_S_ID

constexpr XPMPPlaneID MAX_MODE_S_ID = 0x00FFFFFF

constexpr

Maximum allowed XPMPPlaneID / mode S id.

◆ MIN_MODE_S_ID

constexpr XPMPPlaneID MIN_MODE_S_ID = 0x00000001

constexpr

Minimum allowed XPMPPlaneID / mode S id.

Classes

Namespaces

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Class Documentation

◆ XPMPPlanePosition_t

◆ xpmp_LightStatus

◆ XPMPPlaneSurfaces_t

◆ XPMPPlaneRadar_t

◆ XPMPInfoTexts_t

◆ xpmp_LightStatus.__unnamed2__

Macro Definition Documentation

◆ XP_SOUND_ELECTRIC

◆ XP_SOUND_FLAP

◆ XP_SOUND_GEAR

◆ XP_SOUND_HIBYPASSJET

◆ XP_SOUND_LOBYPASSJET

◆ XP_SOUND_PROP_AIRPLANE

◆ XP_SOUND_PROP_HELI

◆ XP_SOUND_REVERSE_THRUST

◆ XP_SOUND_ROLL_RUNWAY

◆ XP_SOUND_TURBOPROP

◆ XPMP_CFG_ITM_ACTIVATE_SOUND

◆ XPMP_CFG_ITM_CLAMPALL

◆ XPMP_CFG_ITM_CONTR_LIFE

◆ XPMP_CFG_ITM_CONTR_MAX_ALT

◆ XPMP_CFG_ITM_CONTR_MIN_ALT

◆ XPMP_CFG_ITM_CONTR_MULTI

◆ XPMP_CFG_ITM_FMOD_INSTANCE

◆ XPMP_CFG_ITM_HANDLE_DUP_ID

◆ XPMP_CFG_ITM_LOGLEVEL

◆ XPMP_CFG_ITM_MODELMATCHING

◆ XPMP_CFG_ITM_MUTE_ON_PAUSE

◆ XPMP_CFG_ITM_REPLDATAREFS

◆ XPMP_CFG_ITM_REPLTEXTURE

◆ XPMP_CFG_ITM_SUPPORT_REMOTE

◆ XPMP_CFG_SEC_DEBUG

◆ XPMP_CFG_SEC_MODELS

◆ XPMP_CFG_SEC_PLANES

◆ XPMP_CFG_SEC_SOUND

Typedef Documentation

◆ XPMPIntPrefsFuncTy

◆ XPMPLightsPattern

◆ XPMPPlaneData_f

◆ XPMPPlaneID

◆ XPMPPlaneNotifier_f

◆ XPMPRenderPlanes_f

Enumeration Type Documentation

◆ anonymous enum

◆ XPMPPlaneCallbackResult

◆ XPMPPlaneDataType

◆ XPMPPlaneNotification

◆ XPMPTransponderMode

Function Documentation

◆ XPMPAddModelDataRef()

◆ XPMPChangePlaneModel()

◆ XPMPContrailsAutoEnabled()

◆ XPMPContrailsAvailable()

◆ XPMPCountPlanes()

◆ XPMPCreatePlane()

◆ XPMPCreatePlaneWithModelName()

◆ XPMPDestroyPlane()

◆ XPMPDisableAircraftLabels()

◆ XPMPDrawingAircraftLabels()

◆ XPMPDumpOneCycle()

◆ XPMPEnableAircraftLabels()

◆ XPMPEnableMap()

◆ XPMPGetAircraft()

◆ XPMPGetModelInfo()

◆ XPMPGetModelInfo2()

◆ XPMPGetNthPlane()

◆ XPMPGetNumberOfInstalledModels()

◆ XPMPGetPlaneData()

◆ XPMPGetPlaneICAOAndLivery()

◆ XPMPGetPlaneModelName()

◆ XPMPGetPlaneModelQuality()

◆ xpmp_LightStatus.unnamed2