Microsoft Flight Simulator 2004: A Century of Flight Software Development Kit

Copyright 2004 Microsoft Corporation. All rights reserved.

Air Traffic Information for Panel Gauges

November 2003

Contents
Air Traffic Information for Panel Gauges.........................................................................................................1 November 2003......................................................................................................................................................1 Contents..................................................................................................................................................................2 Introduction...........................................................................................................................................................3 Required Files........................................................................................................................................................3 Overview.................................................................................................................................................................3 Example..................................................................................................................................................................4 Reference................................................................................................................................................................6 Appendix..............................................................................................................................................................12

Introduction
Traffic information systems such as traffic collision and avoidance systems (TCAS) and mode S transponders display information and alerts about to nearby air traffic that may pose a collision hazard. This document describes how to query for air traffic information from within a panel gauge to allow the simulation of TCAS, mode S transponders, or other traffic information systems in Flight Simulator. This document assumes familiarity with how to write a gauge in C++ using the techniques described in the Flight Simulator Panel SDK.

Required Files
This SDK includes two files that must be used in addition to the files included with the Panel SDK: 1. TrafficInfo.dll. This DLL should be installed to Flight Simulators modules subdirectory (e.g., C:\Program Files\Microsoft Games\Flight Simulator 9\Modules). 2. ITrafficInfo.h. This C++ header file is required to compile gauges that query for air traffic information and defines the interface through which the queries are performed.

Overview
Several steps are required when writing gauge code to query for air traffic information. The steps are summarized below but will be described in more detail in the example section of this document. 1. Include gauges.h and ITrafficInfo.h. 2. Query the panel system for the traffic information interface (ITrafficInfo). All further queries will be made using this interface. 3. Query for the identifiers of the aircraft variables required, such as position, altitude, and airspeed. 4. Query for the identifiers of the units of measure required for use with the aircraft variables, such as degrees, feet, and knots. 5. Query for a list of aircraft near the user or some arbitrary point in space. 6. Query each aircraft for the required variables. 7. Display the results. Perform steps 2-4 only once during gauge initialization. Repeat steps 5-7 as required to update the gauge display. In general, do not repeat steps 5-7 more than one or two times per second or the performance of Flight Simulator may degrade.

Example
This example finds up to 100 of the nearest aircraft to the user whose engine(s) are running. If a multiplayer session is active, it finds the nearest 100 aircraft regardless of the engine state. (The example assumes that you already have the C++ code for a working gauge and can insert the example code into your gauge code in the appropriate locations.) 1. Include gauges.h and ITrafficInfo.h.
#include "gauges.h" #include "ITrafficInfo.h"

2. Query the panel system for the traffic information interface (ITrafficInfo). All further queries will be made using this interface.
// get the panel callback interface IPanelCCallback* pPanelCallback = panel_get_registered_c_callback(TRAFFIC_INFO_INTERFACE_NAME); if (pPanelCallback == NULL) { // Error: Unable to find registered callback // Add your own error handler here } // get the TCAS info interface ITrafficInfo* pTrafficInfo = static_cast<ITrafficInfo*>(pPanelCallback>QueryInterface(TRAFFIC_INFO_INTERFACE_NAME)); if (pTrafficInfo == NULL) { // Error: Unable to query interface ITrafficInfo // Add your own error handler here }

3. Query for the identifiers of the aircraft variables required, such as position, altitude and airspeed. The full list of available aircraft variables can be found in the appendix.
// lookup some aircraft variable identifiers ENUM idVarLatitude = pTrafficInfo->QueryAircraftVarEnum("PLANE LATITUDE"); ENUM idVarLongitude = pTrafficInfo->QueryAircraftVarEnum("PLANE LONGITUDE"); ENUM idVarTrueAltitude = pTrafficInfo->QueryAircraftVarEnum("PLANE ALTITUDE"); ENUM idVarIndicatedAltitude = pTrafficInfo->QueryAircraftVarEnum("INDICATED ALTITUDE"); ENUM idVarTrueHeading = pTrafficInfo->QueryAircraftVarEnum("PLANE HEADING DEGREES TRUE"); ENUM idVarGroundSpeed = pTrafficInfo->QueryAircraftVarEnum("GROUND VELOCITY"); ENUM idVarVerticalSpeed = pTrafficInfo->QueryAircraftVarEnum("VELOCITY WORLD Y"); ENUM idVarTailNumber = pTrafficInfo->QueryAircraftVarEnum("ATC ID"); ENUM idVarCombustion = pTrafficInfo->QueryAircraftVarEnum("ENG COMBUSTION");

4. Query for the identifiers of the units of measure required for use with the aircraft variables, such as degrees, feet and knots. The full list of available units of measure can be found in Units.doc in the Panel SDK.
// lookup some unit ids ENUM idUnitsFeet = pTrafficInfo->QueryUnitEnum("FEET"); ENUM idUnitsBool = pTrafficInfo->QueryUnitEnum("BOOL"); ENUM idUnitsDegrees = pTrafficInfo->QueryUnitEnum("DEGREES"); ENUM idUnitsKnots = pTrafficInfo->QueryUnitEnum("KNOTS"); ENUM idUnitsFPM = pTrafficInfo->QueryUnitEnum("FEET PER MINUTE");

5. Query for a list of the 100 aircraft nearest to the user within 10 nautical miles.
// query for the 100 nearest aircraft within 10 nautical miles of the user const FLOAT64 C_QUERY_RADIUS_METERS = 10.0 * 1852.0; // in meters const int C_MAX_NUM_AIRCRAFT = 100; UINT32 aAircraftIds[C_MAX_NUM_AIRCRAFT]; UINT32 nAircraft = pTrafficInfo->QueryAircraftNearUser(C_QUERY_RADIUS_METERS, C_MAX_NUM_AIRCRAFT, aAircraftIds);

6. Query each aircraft for the required variables. The query above will always include the user aircraft. To skip the user aircraft, query for the value of the "IS USER SIM" variable and ignore any aircraft with a non-zero value in the loop below.
// query properties of each aircraft for (UINT32 i = 0; i < nAircraft; i++) { UINT32 uAircraftId = aAircraftIds[i]; // get latitude in degrees FLOAT64 dLatDeg = 0; if (!pTrafficInfo->AircraftVarGetFloat(uAircraftId, idVarLatitude, idUnitsDegrees, &dLatDeg)) continue; // get longitude in degrees FLOAT64 dLonDeg = 0; if (!pTrafficInfo->AircraftVarGetFloat(uAircraftId, idVarLongitude, idUnitsDegrees, &dLonDeg)) continue; // get true heading in degrees FLOAT64 dHdgDeg = 0; if (!pTrafficInfo->AircraftVarGetFloat(uAircraftId, idVarTrueHeading, idUnitsDegrees, &dHdgDeg)) continue; // handle multiplayer aircraft differently from non-multiplayer aircraft FLOAT64 dAltFeet = 0; FLOAT64 dGroundSpeedKnots = 0; FLOAT64 dVerticalSpeedFPM = 0; STRINGZ szTailNumber[16] = ""; PCSTRINGZ pszTailNumber = szTailNumber; if (!pTrafficInfo->IsMultiplayerActive()) { // non-multiplayer // get engine combustion state FLOAT64 dCombustion = 0; if (!pTrafficInfo->AircraftVarGetFloat(uAircraftId, idVarCombustion, idUnitsBool, &dCombustion, 1)) continue; // skip aircraft whose engines aren't running if (dCombustion == 0) continue; // get indicated altitude if (!pTrafficInfo->AircraftVarGetFloat(uAircraftId, idVarIndicatedAltitude, idUnitsFeet, &dAltFeet)) continue; // get ground speed if (!pTrafficInfo->AircraftVarGetFloat(uAircraftId, idVarGroundSpeed, idUnitsKnots, &dGroundSpeedKnots)) continue; // get vertical speed if (!pTrafficInfo->AircraftVarGetFloat(uAircraftId, idVarVerticalSpeed, idUnitsFPM, &dVerticalSpeedFPM))

continue; // get tail number if (!pTrafficInfo->AircraftVarGetString(uAircraftId, idVarTailNumber, szTailNumber, LENGTHOF(szTailNumber))) continue; } else { // special handling for multiplayer // get true altitude since indicated isn't available if (!pTrafficInfo->AircraftVarGetFloat(uAircraftId, idVarTrueAltitude, idUnitsFeet, &dAltFeet)) continue; // ground speed not available for multiplayer aircraft // vertical speed not available for multiplayer aircraft // get player name since tail number isn't available pszTailNumber = pTrafficInfo->GetPlayerName(uAircraftId);

7. Add your code here to display the aircraft data.

// // // // // // // dLatDeg dLonDeg dAltFeet dHdgDeg dGroundSpeedKnots dVerticalSpeedFPM pszTailNumber

Reference
This section documents the members of the ITrafficInfo interface.

ITrafficInfo::AircraftGetDatabaseInfo
The AircraftGetDatabaseInfo function gets the name of the traffic database file from which an aircraft was instantiated. It also returns the instance key that uniquely identifies the aircraft within the database file.

Syntax
BOOL ITrafficInfo::AircraftVarGetFloat( UINT32 uAircraftId, PSTRINGZ pszFileName, UINT32 uFileNameMax, UINT32* puInstanceKey ) const;

Parameters
uAircraftId

[in] The identifier of the aircraft to query. Aircraft identifiers are obtained by calls to either ITrafficInfo::QueryAircraftNearPoint or ITrafficInfo::QueryAircraftNearUser. pszFileName [out] Pointer to a string buffer to receive the name of the traffic database file. uFileNameMax [in] Length of the buffer pointed to by pszFileName. puInstanceKey [out] Pointer to a variable to receive the instance key.

Return Value
If successful, this function returns TRUE. This function returns FALSE if the aircraft identifier is invalid.

ITrafficInfo::AircraftVarGetFloat
The AircraftVarGetFloat function gets the value of an aircraft floating point variable.

Syntax
BOOL ITrafficInfo::AircraftVarGetFloat( UINT32 uAircraftId, ENUM simvar, ENUM units, FLOAT64* pdValue, SINT32 index = 0 ) const;

Parameters
uAircraftId [in] The identifier of the aircraft to query. Aircraft identifiers are obtained by calls to either ITrafficInfo::QueryAircraftNearPoint or ITrafficInfo::QueryAircraftNearUser. simvar [in] The identifier of the aircraft variable to read. Variable identifiers are obtained by calls to ITrafficInfo::QueryAircraftVarEnum. units [in] The identifier of the units of measure desired for the value of the requested aircraft variable. Units of measure identifiers are obtained by calls to ITrafficInfo::QueryUnitEnum. pdValue [out] Address of a floating point variable to receive the value of the requested aircraft variable.

index [in, optional] One-based array index for array variables.

Return Value
If successful, this function returns TRUE. This function returns FALSE if the aircraft, variable, or unit identifiers are invalid or unavailable.

ITrafficInfo::AircraftVarGetString
The AircraftVarGetString function gets the value of an aircraft string (text) variable.

Syntax
BOOL ITrafficInfo::AircraftVarGetString( UINT32 uAircraftId, ENUM simvar pszBuffer, uBufferLength, index = 0 ) const;

Parameters
uAircraftId [in] The identifier of the aircraft to query. Aircraft identifiers are obtained by calls to either ITrafficInfo::QueryAircraftNearPoint or ITrafficInfo::QueryAircraftNearUser. simvar [in] The identifier of the aircraft variable to read. Variable identifiers are obtained by calls to ITrafficInfo::QueryAircraftVarEnum. pszBuffer [out] Address of a string buffer to receive the value of the request aircraft variable. uBufferLength [in] Maximum length of the buffer pointed to by pszBuffer. index [in, optional] One-based array index for array variables.

Return Value
If successful, this function returns TRUE. This function returns FALSE if the aircraft or variable identifiers are invalid or unavailable.

ITrafficInfo::IsMultiplayerActive
Use the IsMultiplayerActive function to determine whether a multiplayer session is active. During a multiplayer session, only a subset of the normal aircraft variables are available for

queries. See the appendix for a list of which aircraft variables are available during a multiplayer session.

Syntax
BOOL ITrafficInfo::IsMultiplayerActive() const;

Return Value
Returns TRUE if a multiplayer session is active and FALSE otherwise.

ITrafficInfo::GetPlayerName
The GetPlayerName function queries the multiplayer name assigned to an aircraft during a multiplayer session.

Syntax
PCSTRINGZ ITrafficInfo::GetPlayerName( UINT32 uAircraftId ) const;

Parameters
uAircraftId [in] The identifier of the aircraft to query. Aircraft identifiers are obtained by calls to either ITrafficInfo::QueryAircraftNearPoint or ITrafficInfo::QueryAircraftNearUser.

Return Value
During multiplayer sessions, returns a constant string pointer to an aircrafts multiplayer name. Returns a constant string pointer to an empty string outside of a multiplayer session.

ITrafficInfo::QueryAircraftNearPoint
The QueryAircraftNearPoint function creates a list of any aircraft, including the user aircraft, that fall within a given query region. The query region is defined by a center point and a radius. The list created by this function contains the identifiers of any aircraft, up to some caller-specified maximum number, that fall within the query region. The list is sorted so that the nearest aircraft appear first. This query is somewhat CPU intensive, so calls to this function should be limited to no more than one or two per second.

Syntax
UINT32 ITrafficInfo::QueryAircraftNearPoint( FLOAT64 dLatitudeDegrees, FLOAT64 dLongitudeDegrees, FLOAT64 dAltitudeMeters, FLOAT64 dRadiusMeters, UINT32 uMaxAircraftIds, UINT32* puAircraftIds ) const;

Parameters
dLatitudeDegrees [in] Latitude of the query center point in degrees. dLongitudeDegrees [in] Longitude of the query center point in degrees. dAltitudeMeters [in] Altitude of the query center point in meters. dRadiusMeters [in] Radius of the query region in meters. uMaxAircraftIds [in] The maximum number of aircraft desired by the query, which should be less than or equal to the number of elements in the puAircraftIds array. puAircraftIds [out] Address of an array to receive the list of identifiers of any aircraft within the query region, sorted in nearest-first order.

Return Value
Returns the number of aircraft found within the query region, up to a maximum of uMaxAircraftIds.

ITrafficInfo::QueryAircraftNearUser
The QueryAircraftNearUser function creates a list of any aircraft, including the user aircraft, that fall within a given distance of the user aircraft. The list created by this function contains the identifiers of any aircraft, up to some caller-specified maximum number, that fall within the query region. The list is sorted so that the nearest aircraft appear first. This query is somewhat CPU intensive, so calls to this function should be limited to no more than one or two per second.

Syntax
UINT32 ITrafficInfo::QueryAircraftNearUser( FLOAT64 dRadiusMeters, UINT32 uMaxAircraftIds, UINT32* puAircraftIds ) const;

Parameters
dRadiusMeters [in] Radius of the query region in meters. uMaxAircraftIds

[in] The maximum number of aircraft desired by the query, which should be less than or equal to the number of elements in the puAircraftIds array. puAircraftIds [out] Address of an array to receive the list of identifiers of any aircraft within the query region, sorted in nearest-first order.

Return Value
Returns the number of aircraft found within the query region, up to a maximum of uMaxAircraftIds.

ITrafficInfo::QueryAircraftVarEnum
The QueryAircraftVarEnum function converts the string (text) name of an aircraft variable to a numerical identifier for use with the ITrafficInfo::AircraftVarGetFloat and ITrafficInfo::AircraftVarGetString functions. Once queried, an aircraft variable identifier is valid until Flight Simulator exits, so variables need only be queried once during gauge initialization.

Syntax
ENUM ITrafficInfo::QueryAircraftVarEnum( PCSTRINGZ pszAircraftVar ) const;

Parameters
pszAircraftVar The name of the aircraft variable to query. The list of available variables is in the appendix.

Return Value
The numerical identifier corresponding to the requested aircraft variable name. If the variable name is not recognized, this function returns zero.

ITrafficInfo::QueryUnitEnum
The QueryUnitEnum function converts the string (text) name of a unit of measure such as meters or feet to a numerical identifier for use with the ITrafficInfo::AircraftVarGetFloat function. Once queried, a unit identifier is valid until Flight Simulator exits, so units need only be queried once during gauge initialization.

Syntax
ENUM ITrafficInfo::QueryUnitEnum( PCSTRINGZ pszUnit ) const;

Parameters
pszUnit

The name of the unit of measure to query. The list of available units of measure can be found in Units.doc in the Panel SDK.

Return Value
The numerical identifier corresponding to the requested unit of measure. If the unit name is not recognized, this function returns -1.

Appendix
There are a number of aircraft variables that may be queried via the ITrafficInfo interface. Most of them are numeric variables but there are also a few string (text) variables. The user aircraft and any aircraft controlled by an artificial intelligence (AI) pilot support all of the variables in the tables below. However, multiplayer (MP) aircraft support only a limited subset of the normal aircraft variables as noted in the MP column in the tables below.

Position Variables
Variable Name PLANE PITCH DEGREES PLANE BANK DEGREES PLANE HEADING DEGREES MAGNETIC PLANE HEADING DEGREES TRUE PLANE LATITUDE PLANE LONGITUDE PLANE ALTITUDE PRESSURE ALTITUDE INDICATED ALTITUDE PLANE ALT ABOVE GROUND MP Comments

Speed Variables
Variable Name AIRSPEED INDICATED AIRSPEED MACH AIRSPEED TRUE GROUND VELOCITY TOTAL WORLD VELOCITY VELOCITY WORLD X VELOCITY WORLD Y VELOCITY WORLD Z MP Comments

Control Variables
Variable Name AILERON AVERAGE DEFLECTION ELEVATOR DEFLECTION RUDDER DEFLECTION SPOILERS LEFT POSITION SPOILERS RIGHT POSITION FLAPS HANDLE PERCENT GEAR HANDLE POSITION GENERAL ENG THROTTLE LEVER POSITION MP Comments

Miscellaneous Variables
Variable Name MAGVAR VISUAL MODEL RADIUS MP Comments Aircraft radius used by TrafficDatabaseBuilder

String Variables
Variable Name ATC AIRLINE ATC FLIGHT NUMBER ATC ID ATC MODEL ATC TYPE TITLE MP Comments

Aircraft tail number