XPMP2
X-Plane multiplayer library 2 - using instancing
Classes | Namespaces | Macros | Typedefs | Enumerations | Functions | Variables
XPMPMultiplayer.h File Reference

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

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

Go to the source code of this file.

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

#define XPMP_CFG_SEC_MODELS   "models"
 Config section "models". More...
 
#define XPMP_CFG_SEC_PLANES   "planes"
 Config section "planes". More...
 
#define XPMP_CFG_SEC_DEBUG   "debug"
 Config section "debug". More...
 
#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_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 into Log.txt More...
 

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

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...
 
const char * XPMPMultiplayerOBJ7SupportEnable (const char *inTexturePath)
 Used to set the light textures for old OBJ7 models. More...
 
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...
 
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...
 
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::AircraftXPMPGetAircraft (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...
 
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...
 
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/
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
Author
Ben Supnik and Chris Serio
Author
Birger Hoppe

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

◆ 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_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 into Log.txt

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

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
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 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
_sectionConfiguration section, ie. group of values, any of the XPMP_CFG_SEC_... values
_keyAny of the XPMP_CFG_ITM_* values to indicate which config value is to be returned.
_defaultA 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
inPlaneID of the plane, for which data is requested
inDataTypeThe type of data that is requested, see XPMPPlaneDataType
[out]ioDataA pointer to a structure XPMP2 provides, for you to fill the data into. For its type see XPMPPlaneDataType.
inRefconThe 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
inPlaneIDIdentifies the affected plane
inNotificationThe event that took place
inRefconA 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
Not changed to proper enum type as it is used in bitfields in 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

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

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

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

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
inPlaneIDWhich plane to change?
inICAOCodeICAO aircraft type designator, like 'A320', 'B738', 'C172'
inAirlineICAO airline code, like 'BAW', 'DLH', can be an empty string
inLiverySpecial livery designator, can be an empty string
Returns
Match quality, the lower the better / -1 if inPlaneID is invalid

◆ 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
inICAOCodeICAO aircraft type designator, like 'A320', 'B738', 'C172'
inAirlineICAO airline code, like 'BAW', 'DLH', can be an empty string
inLiverySpecial livery designator, can be an empty string
inDataFuncCallback function called by XPMP2 to fetch updated data
inRefconA 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
inModelNameCSL Model name (id) to use, or nullptr if normal matching using the next 3 parameters shall be applied
inICAOCodeICAO aircraft type designator, like 'A320', 'B738', 'C172'
inAirlineICAO airline code, like 'BAW', 'DLH', can be an empty string
inLiverySpecial livery designator, can be an empty string
inDataFuncCallback function called by XPMP2 to fetch updated data
inRefconA 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
_bEnableEnable or disable entire map functionality
_bLabelsIf 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
inIndexNumber between 0 and `XPMPGetNumberOfInstalledModels()-1
[out]outModelNameReceives pointer to model name (id). Optional, can be nullptr.
[out]outIcaoReceives pointer to ICAO aircraft type designator. Optional, can be nullptr.
[out]outAirlineReceives pointer to ICAO airline code. Optional, can be nullptr.
[out]outLiveryReceives 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
inIndexNumber between 0 and `XPMPGetNumberOfInstalledModels()-1
[out]outModelNameReceives model name (id)
[out]outIcaoReceives ICAO aircraft designator
[out]outAirlineReceives ICAO airline code
[out]outLiveryReceives 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
inPlaneIDIdentifies 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
outTxtBufSizeSize 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
inCSLFolderRoot 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
inICAOICAO aircraft type designator, optional, can be nullptr
inAirlineICAO airline code, optional, can be nullptr
inLiverySpecial 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
inPluginNameYour plugin's name, mainly used as map layer name and for logging
resourceDirThe 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
inFuncPointer to your callback function
inRefconA 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_nmMaximum label distance in nm, default is 3, minimum is 1
_bCutOffAtVisibilityShall 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
_acIcaoTypeDefault ICAO aircraft type designator, used when matching returns nothing
_carIcaoTypeType 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
inPluginNameYour 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.

◆ XPMPUnregisterPlaneNotifierFunc()

void XPMPUnregisterPlaneNotifierFunc ( XPMPPlaneNotifier_f  inFunc,
void *  inRefcon 
)

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

Parameters
inFuncPointer to your callback function
inRefconA 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.