Implementation of serving TCAS target dataRef updates. More...

#include "XPMP2.h"

Classes
struct	XPMP2::multiDataRefsTy
	Keeps the dataRef handles for one of the up to 19 legacy AI/Multiplayer slots ("sim/multiplayer/position") More...

struct	XPMP2::infoDataRefsTy
	Keeps the dataRef handles for one of the up to 63 shared data slots ("sim/multiplayer/position/plane#...") More...

union	XPMP2::TcasLightsTy
	A structure simplifying communicaton with sim/cockpit2/tcas/targets/position/lights. More...

struct	XPMP2::TcasLightsTy::BitsTy

Namespaces
	XPMP2

Macros
#define	INFO_AI_CONTROL "Have control now over AI/Multiplayer planes"

#define	INFO_AI_CONTROL_ENDS "Released control of AI/Multiplayer planes"

#define	INFO_REMOTE_CLIENT_AI "XPMP2 Remote Client controls TCAS. We don't need control as our planes will show up there."

#define	WARN_NO_AI_CONTROL "%s controls TCAS / AI. %s could NOT acquire control, our planes might NOT appear on TCAS or 3rd party apps."

#define	DEBUG_AI_SLOT_ASSIGN "Aircraft %llu: ASSIGNING AI Slot %d (%s, %s, %s)"

#define	DEBUG_AI_SLOT_RELEASE "Aircraft %llu: RELEASING AI Slot %d (%s, %s, %s)"

#define	MSG_ADD_DATAREF 0x01000000
	Message to DRE/DRT to inform about dataRefs. More...

#define	SET_DR(ty, dr) XPLMSetData##ty(drTcas##dr, v##dr.data(), 1, (int)v##dr.size())

#define	FIND_PLANE_DR(membVar, dataRefTxt, PlaneNr)

#define	SHARE_PLANE_DR(membVar, dataRefTxt, PlaneNr)

#define	UNSHARE_PLANE_DR(membVar, dataRefTxt, PlaneNr)

Typedefs
typedef std::map< float, XPMPPlaneID >	XPMP2::mapAcByDistTy
	Map of Aircrafts, sorted by (priority-biased) distance. More...

Functions
void	XPMP2::AIMultiClearAIDataRefs (multiDataRefsTy &drM, bool bDeactivateToZero)
	Resets all actual values of the AI/multiplayer dataRefs of one plane to something initial. More...

void	XPMP2::AIMultiClearInfoDataRefs (infoDataRefsTy &drI)
	Clears the shared info dataRefs. More...

bool	XPMP2::GoTCASOverride ()
	Are we going to new (TCAS override) or the old way? More...

bool	XPMP2::GoTCASWake ()
	Can we use the XP12 wake support system? More...

size_t	XPMP2::AIUpdateMultiplayerDataRefs ()
	The old way: Update Multiplayer dataRefs directly. More...

size_t	XPMP2::AIUpdateTCASTargets ()
	The modern way: Use TCAS override and update TCAS targets. More...

void	XPMP2::AIAssignSlots (size_t fromSlot, size_t toSlot)
	Assigns slots, ie. planes to places in gSlots. More...

void	XPMP2::AIMultiUpdate ()
	Updates all TCAS target dataRefs, both standard X-Plane, as well as additional shared dataRefs for text publishing. More...

int	XPMP2::AIMultiControlPlaneCount (XPLMDrawingPhase, int inIsBefore, void *)
	Callback to toggle aircraft count ("TCAS hack") More...

void	XPMP2::AIMultiClearTcasDataRefs ()
	Clears the key (mode_s) of the TCAS target dataRefs. More...

void	XPMP2::AIMultiInitAllDataRefs (bool bDeactivateToZero)
	Reset all (controlled) multiplayer dataRef values of all planes. More...

void	XPMP2::AIMultiInformDREs ()
	Inform DRE and DRT of our shared dataRefs. More...

void	XPMP2::AIMultiInit ()
	Initialize the module. More...

void	XPMP2::AIMultiCleanup ()
	Grace cleanup. More...

const char *	XPMPMultiplayerEnable (void(_callback)(void ), void *_refCon)
	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...

Variables
constexpr float	XPMP2::FAR_AWAY_VAL_GL = 9999999.9f
	Don't dare using NAN...but with this coordinate for x/y/z a plane should be far out and virtually invisible. More...

constexpr float	XPMP2::AISLOT_CHANGE_PERIOD = 15.0f
	How often do we reassign AI slots? [seconds]. More...

constexpr int	XPMP2::AI_PRIO_MULTIPLIER = 10 * M_per_NM
	How much distance does each AIPrio add? More...

float	XPMP2::F_NULL [10] = { 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f}
	A constant array of zero values supporting quick array initialization. More...

constexpr int	XPMP2::XPLM_PHASE_AIRPLANES = 25
	The drawing phase "xplm_Phase_Airplanes" is deprecated in XP11.50 upwards, but we need it in earlier versions to fake TCAS. More...

const char *	XPMP2::DATA_REF_EDITORS []

std::vector< std::string >	XPMP2::vecDREdataRefStr
	list of dataRef strings to be send to the editors More...

constexpr size_t	XPMP2::SDR_CSLMODEL_TXT_SIZE = 40
	Number of characters to be allowed for CSL model text. More...

Detailed Description

Implementation of serving TCAS target dataRef updates.

Updates the up to 63 slots of X-Plane's defined TCAS targets, which are in turn synced with the 19 "legacy" multiplayer slots, which in turn many other plugins (like TCAS implementations or map tools) read to learn about any multiplayer aircraft.
Also serves shared dataRefs for publishing text information, which is not X-Plane standard but originally suggested by FSTramp. However, the post and file, in which he suggested this addition, is no longer available on forums.x-plane.org. Still, XPMP2 fullfills the earlier definition.

See also: X-Plane 11.50 Beta 8 introduced a new way of informing X-Plane of TCAS targets, see here a blog entry for details: https://developer.x-plane.com/article/overriding-tcas-and-providing-traffic-information/

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.

Class Documentation

◆ XPMP2::TcasLightsTy

union XPMP2::TcasLightsTy

A structure simplifying communicaton with sim/cockpit2/tcas/targets/position/lights.

Class Members
struct BitsTy	b
int	i	the full integer value

◆ XPMP2::TcasLightsTy::BitsTy

struct XPMP2::TcasLightsTy::BitsTy

Class Members
bool	beacon: 1	Beacon lights.
bool	land: 1	Landing lights.
bool	nav: 1	Navigation lights.
bool	strobe: 1	Strobe lights.
bool	taxi: 1	Taxi lights.

Macro Definition Documentation

◆ DEBUG_AI_SLOT_ASSIGN

#define DEBUG_AI_SLOT_ASSIGN "Aircraft %llu: ASSIGNING AI Slot %d (%s, %s, %s)"

◆ DEBUG_AI_SLOT_RELEASE

#define DEBUG_AI_SLOT_RELEASE "Aircraft %llu: RELEASING AI Slot %d (%s, %s, %s)"

◆ FIND_PLANE_DR

#define FIND_PLANE_DR	(	membVar,
		dataRefTxt,
		PlaneNr
	)

Value:

snprintf(buf,sizeof(buf),"sim/multiplayer/position/plane%u_" dataRefTxt,PlaneNr); \

drM.membVar = XPLMFindDataRef(buf);

◆ INFO_AI_CONTROL

#define INFO_AI_CONTROL "Have control now over AI/Multiplayer planes"

◆ INFO_AI_CONTROL_ENDS

#define INFO_AI_CONTROL_ENDS "Released control of AI/Multiplayer planes"

◆ INFO_REMOTE_CLIENT_AI

#define INFO_REMOTE_CLIENT_AI "XPMP2 Remote Client controls TCAS. We don't need control as our planes will show up there."

◆ MSG_ADD_DATAREF

#define MSG_ADD_DATAREF 0x01000000

Message to DRE/DRT to inform about dataRefs.

◆ SET_DR

#define SET_DR	(	ty,
		dr
	)	XPLMSetData##ty(drTcas##dr, v##dr.data(), 1, (int)v##dr.size())

◆ SHARE_PLANE_DR

#define SHARE_PLANE_DR	(	membVar,
		dataRefTxt,
		PlaneNr
	)

Value:

    snprintf(buf,sizeof(buf),"sim/multiplayer/position/plane%u_" dataRefTxt,PlaneNr);   \
    if (XPLMShareData(buf, xplmType_Data, NULL, NULL)) {                                \
        drI.membVar = XPLMFindDataRef(buf);                                             \
        vecDREdataRefStr.push_back(buf);                                                \
    }                                                                                   \
    else drI.membVar = NULL;

◆ UNSHARE_PLANE_DR

#define UNSHARE_PLANE_DR	(	membVar,
		dataRefTxt,
		PlaneNr
	)

Value:

    snprintf(buf,sizeof(buf),"sim/multiplayer/position/plane%u_" dataRefTxt,PlaneNr);       \
    XPLMUnshareData(buf, xplmType_Data, NULL, NULL);                           \
    drI.membVar = NULL;

◆ WARN_NO_AI_CONTROL

#define WARN_NO_AI_CONTROL "%s controls TCAS / AI. %s could NOT acquire control, our planes might NOT appear on TCAS or 3rd party apps."

Function Documentation

◆ XPMPHasControlOfAIAircraft()

bool XPMPHasControlOfAIAircraft ( )

Has XPMP2 control of TCAS targets?

See also: XPMPMultiplayerEnable()

◆ 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

Classes

Namespaces

Macros

Typedefs

Functions

Variables

Detailed Description

Class Documentation

◆ XPMP2::TcasLightsTy

◆ XPMP2::TcasLightsTy::BitsTy

Macro Definition Documentation

◆ DEBUG_AI_SLOT_ASSIGN

◆ DEBUG_AI_SLOT_RELEASE

◆ FIND_PLANE_DR

◆ INFO_AI_CONTROL

◆ INFO_AI_CONTROL_ENDS

◆ INFO_REMOTE_CLIENT_AI

◆ MSG_ADD_DATAREF

◆ SET_DR

◆ SHARE_PLANE_DR

◆ UNSHARE_PLANE_DR

◆ WARN_NO_AI_CONTROL

Function Documentation

◆ XPMPHasControlOfAIAircraft()

◆ XPMPMultiplayerDisable()

◆ XPMPMultiplayerEnable()