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

#include "XPMP2.h"
#include <cstring>

Namespaces
	XPMP2

Macros
#define	ERR_RSRC_DIR_INVALID "Resource directory too short: %s"

#define	ERR_RSRC_DIR_UNAVAIL "Resource directory '%s' does not exist!"

#define	ERR_RSRC_FILE_UNAVAIL "File '%s' is missing in resource directory '%s'"

#define	INFO_DEFAULT_ICAO "Default ICAO aircraft type now is %s"

#define	INFO_CAR_ICAO "Ground vehicle ICAO type now is %s"

#define	INFO_LOAD_CSL_PACKAGE "Loading CSL package from %s"

Functions
const char *	XPMP2::XPMPValidateResourceFiles (const char *resourceDir)
	Validate all required files are available in the resource directory. More...

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

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

void	XPMPSetPluginName (const char inPluginName, const char inPluginLogAcronym)
	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 *)
	Used to set the light textures for old OBJ7 models. 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...

XPMPPlaneID	XPMPCreatePlane (const char inICAOCode, const char inAirline, const char inLivery, XPMPPlaneData_f inDataFunc, void inRefcon, XPMPPlaneID inModeS_id)
	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)
	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 _id, const char inICAO, 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, XPMPPlaneDataType, void *)
	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 ()
	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)
	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	XPMP2::XPMPSendNotification (const Aircraft &plane, XPMPPlaneNotification _notification)
	Send a notification to all observers. More...

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

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

void	XPMPInitDefaultPlaneRenderer (void)
	Was an internal libxplanemp functions. More...

void	XPMPDefaultPlaneRenderer (int)
	Was an internal libxplanemp functions. More...

void	XPMPDeinitDefaultPlaneRenderer (void)
	Was an internal libxplanemp functions. More...

Detailed Description

Initialization and general control functions for XPMP2.

Author: Birger Hoppe

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

Macro Definition Documentation

◆ ERR_RSRC_DIR_INVALID

#define ERR_RSRC_DIR_INVALID "Resource directory too short: %s"

◆ ERR_RSRC_DIR_UNAVAIL

#define ERR_RSRC_DIR_UNAVAIL "Resource directory '%s' does not exist!"

◆ ERR_RSRC_FILE_UNAVAIL

#define ERR_RSRC_FILE_UNAVAIL "File '%s' is missing in resource directory '%s'"

◆ INFO_CAR_ICAO

#define INFO_CAR_ICAO "Ground vehicle ICAO type now is %s"

◆ INFO_DEFAULT_ICAO

#define INFO_DEFAULT_ICAO "Default ICAO aircraft type now is %s"

◆ INFO_LOAD_CSL_PACKAGE

#define INFO_LOAD_CSL_PACKAGE "Loading CSL package from %s"

Function Documentation

◆ 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

◆ 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

◆ XPMPDefaultPlaneRenderer()

void XPMPDefaultPlaneRenderer ( int is_blend )

Was an internal libxplanemp functions.

Deprecated:: No longer supported.

◆ XPMPDeinitDefaultPlaneRenderer()

void XPMPDeinitDefaultPlaneRenderer ( void )

Was an internal libxplanemp functions.

Deprecated:: No longer supported.

◆ XPMPDestroyPlane()

void XPMPDestroyPlane ( XPMPPlaneID _id )

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

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

◆ XPMPDumpOneCycle()

void XPMPDumpOneCycle ( void )

Legacy debug-support function, no longer supported.

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

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

◆ XPMPInitDefaultPlaneRenderer()

void XPMPInitDefaultPlaneRenderer ( void )

Was an internal libxplanemp functions.

Deprecated:: No longer supported.

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

◆ 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

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

◆ 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

Namespaces

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ERR_RSRC_DIR_INVALID

◆ ERR_RSRC_DIR_UNAVAIL

◆ ERR_RSRC_FILE_UNAVAIL

◆ INFO_CAR_ICAO

◆ INFO_DEFAULT_ICAO

◆ INFO_LOAD_CSL_PACKAGE

Function Documentation

◆ XPMPChangePlaneModel()

◆ XPMPCountPlanes()

◆ XPMPCreatePlane()

◆ XPMPCreatePlaneWithModelName()

◆ XPMPDefaultPlaneRenderer()

◆ XPMPDeinitDefaultPlaneRenderer()

◆ XPMPDestroyPlane()

◆ XPMPDumpOneCycle()

◆ XPMPGetAircraft()

◆ XPMPGetModelInfo()

◆ XPMPGetModelInfo2()

◆ XPMPGetNthPlane()

◆ XPMPGetNumberOfInstalledModels()

◆ XPMPGetPlaneData()

◆ XPMPGetPlaneICAOAndLivery()

◆ XPMPGetPlaneModelName()

◆ XPMPGetPlaneModelQuality()

◆ XPMPInitDefaultPlaneRenderer()

◆ XPMPIsICAOValid()

◆ XPMPLoadCSLPackage()

◆ XPMPLoadPlanesIfNecessary()

◆ XPMPModelMatchQuality()

◆ XPMPMultiplayerCleanup()

◆ XPMPMultiplayerInit()

◆ XPMPMultiplayerInitLegacyData()

◆ XPMPMultiplayerOBJ7SupportEnable()

◆ XPMPRegisterPlaneNotifierFunc()

◆ XPMPSetDefaultPlaneICAO()

◆ XPMPSetPlaneRenderer()

◆ XPMPSetPlaneVisibility()

◆ XPMPSetPluginName()

◆ XPMPUnregisterPlaneNotifierFunc()