Avionics API
The Avionics API allows you to customize the drawing and behaviour of the built-in cockpit devices (GNS, G1000, etc.), and create your own cockpit devices. For built-in devices, you can draw before and/or after X-Plane does, and optionally prevent X-Plane from drawing the screen at all. Customized built-in devices and custom devices are available in the 3D cockpit as well as in the form of pop-up/pop-out windows.
The API also allows you to receive mouse interaction events for your device (click down, drag, and up, mouse wheel
scroll, cursor) for both screen and bezel. While these always work when the device is popped-up in its window, you must
add a ATTR_manip_device manipulator on top of your screen in order to receive mouse events from the 3D cockpit.
You can also use the avionics API to control the state and location of cockpit devices' pop-up windows.
When working with avionics devices, all co-ordinates you receive when drawing or dealing with click events are in texels. The x-axis grows right, the y-axis grows up. In bezel callbacks, the origin is at the bottom left corner of the bezel. In screen callbacks, the origin is at the bottom-left of the screen. X-Plane takes care of scaling your screen and bezel if the user pops out the device's window: you should always draw your screen and bezel as if they were at the size you specified when registering callbacks or creating a device.
XPLMDeviceID
enum
This constant indicates the device we want to override or enhance. We can get a callback before or after each item.
| Name | Value | Description |
|---|---|---|
| xplm_device_GNS430_1 | 0 | GNS430, pilot side. |
| xplm_device_GNS430_2 | 1 | GNS430, copilot side. |
| xplm_device_GNS530_1 | 2 | GNS530, pilot side. |
| xplm_device_GNS530_2 | 3 | GNS530, copilot side. |
| xplm_device_CDU739_1 | 4 | generic airliner CDU, pilot side. |
| xplm_device_CDU739_2 | 5 | generic airliner CDU, copilot side. |
| xplm_device_G1000_PFD_1 | 6 | G1000 Primary Flight Display, pilot side. |
| xplm_device_G1000_MFD | 7 | G1000 Multifunction Display. |
| xplm_device_G1000_PFD_2 | 8 | G1000 Primary Flight Display, copilot side. |
| xplm_device_CDU815_1 | 9 | Primus CDU, pilot side. |
| xplm_device_CDU815_2 | 10 | Primus CDU, copilot side. |
| xplm_device_Primus_PFD_1 | 11 | Primus Primary Flight Display, pilot side. |
| xplm_device_Primus_PFD_2 | 12 | Primus Primary Flight Display, copilot side. |
| xplm_device_Primus_MFD_1 | 13 | Primus Multifunction Display, pilot side. |
| xplm_device_Primus_MFD_2 | 14 | Primus Multifunction Display, copilot side. |
| xplm_device_Primus_MFD_3 | 15 | Primus Multifunction Display, central. |
| xplm_device_Primus_RMU_1 | 16 | Primus Radio Management Unit, pilot side. |
| xplm_device_Primus_RMU_2 | 17 | Primus Radio Management Unit, copilot side. |
| xplm_device_MCDU_1 | 18 | Airbus MCDU, pilot side. |
| xplm_device_MCDU_2 | 19 | Airbus MCDU, copilot side. |
| xplm_device_MCDU_3 | 24 | Airbus MCDU 3. |
XPLMAvionicsCallback_f
callback
This is the prototype for drawing callbacks for customized built-in device. You are passed in the device you are enhancing/replacing, and (if this is used for a built-in device that you are customizing) whether it is before or after X-Plane drawing. If you are before X-Plane, return true to let X-Plane draw or false to suppress X-Plane drawing. If you are called after X-Plane, the return value is ignored.
Refcon is a unique value that you specify when registering the callback, allowing you to slip a pointer to your own data to the callback.
Upon entry the OpenGL context will be correctly set up for you and OpenGL will be in panel coordinates for 2d drawing. The OpenGL state (texturing, etc.) will be unknown.
typedef int (* XPLMAvionicsCallback_f)(
XPLMDeviceID inDeviceID,
int inIsBefore,
void * inRefcon
);
XPLMAvionicsMouse_f
callback XPLM410
Mouse click callback for clicks into your screen or (2D-popup) bezel, useful if the device you are making simulates a touch-screen the user can click in the 3d cockpit, or if your pop-up's bezel has buttons that the user can click. Return true to consume the event, or false to let X-Plane process it (for stock avionics devices).
typedef int (* XPLMAvionicsMouse_f)(
int x,
int y,
XPLMMouseStatus inMouse,
void * inRefcon
);
XPLMAvionicsMouseWheel_f
callback XPLM410
Mouse wheel callback for scroll actions into your screen or (2D-popup) bezel, useful if your bezel has knobs that can be turned using the mouse wheel, or if you want to simulate pinch-to-zoom on a touchscreen. Return true to consume the event, or false to let X-Plane process it (for stock avionics devices). The number of "clicks" indicates how far the wheel was turned since the last callback. The wheel is 0 for the vertical axis or 1 for the horizontal axis (for OS/mouse combinations that support this).
typedef int (* XPLMAvionicsMouseWheel_f)(
int x,
int y,
int wheel,
int clicks,
void * inRefcon
);
XPLMAvionicsCursor_f
callback XPLM410
Cursor callback that decides which cursor to show when the mouse is over your screen or (2D-popup) bezel. Return xplm_CursorDefault to let X-Plane use which cursor to show, or other values to force the cursor to a particular one (see XPLMCursorStatus).
typedef XPLMCursorStatus (* XPLMAvionicsCursor_f)(
int x,
int y,
void * inRefcon
);
XPLMAvionicsKeyboard_f
callback XPLM410
Key callback called when your device is popped up and you've requested to capture the keyboard. Return true to consume the event, or false to let X-Plane process it (for stock avionics devices).
typedef int (* XPLMAvionicsKeyboard_f)(
char inKey,
XPLMKeyFlags inFlags,
char inVirtualKey,
void * inRefcon,
int losingFocus
);
XPLMAvionicsID
typedef
This is an opaque identifier for an avionics display that you enhance or replace. When you register your callbacks (via XPLMRegisterAvionicsCallbacksEx()) or create a new device (via XPLMCreateAvionicsDevice()), you will specify drawing and mouse callbacks, and get back such a handle.
typedef void * XPLMAvionicsID;
XPLMCustomizeAvionics_t
struct
The XPLMCustomizeAvionics_t structure defines all of the parameters used to replace or enhance built-in simulator avionics devices using XPLMRegisterAvionicsCallbacksEx(). The structure will be expanded in future SDK APIs to include more features. Always set the structSize member to the size of your struct in bytes!
typedef struct {
int structSize;
XPLMDeviceID deviceId;
XPLMAvionicsCallback_f drawCallbackBefore;
XPLMAvionicsCallback_f drawCallbackAfter;
XPLMAvionicsMouse_f bezelClickCallback;
XPLMAvionicsMouse_f bezelRightClickCallback;
XPLMAvionicsMouseWheel_f bezelScrollCallback;
XPLMAvionicsCursor_f bezelCursorCallback;
XPLMAvionicsMouse_f screenTouchCallback;
XPLMAvionicsMouse_f screenRightTouchCallback;
XPLMAvionicsMouseWheel_f screenScrollCallback;
XPLMAvionicsCursor_f screenCursorCallback;
XPLMAvionicsKeyboard_f keyboardCallback;
userref refcon;
int native;
} XPLMCustomizeAvionics_t;
XPLMRegisterAvionicsCallbacksEx
function
This routine registers your callbacks for a built-in device. This returns a handle. If the returned handle is NULL, there was a problem interpreting your input, most likely the struct size was wrong for your SDK version. If the returned handle is not NULL, your callbacks will be called according to schedule as long as your plugin is not deactivated, or unloaded, or you call XPLMUnregisterAvionicsCallbacks().
Note that you cannot register new callbacks for a device that is not a built-in one (for example a device that you have created, or a device another plugin has created).
XPLM_API XPLMAvionicsIDXPLMRegisterAvionicsCallbacksEx(
XPLMCustomizeAvionics_t * inParams
);
XPLMGetAvionicsHandle
function
This routine registers no callbacks for a built-in cockpit device, but returns a handle which allows you to interact with it using the Avionics Device API. Use this if you do not wish to intercept drawing, clicks and touchscreen calls to a device, but want to interact with its popup programmatically. This is equivalent to calling XPLMRegisterAvionicsCallbackEx() with NULL for all callbacks.
XPLM_API XPLMAvionicsIDXPLMGetAvionicsHandle(
XPLMDeviceID inDeviceID
);
XPLMUnregisterAvionicsCallbacks
function
This routine unregisters your callbacks for a built-in device. You should only call this for handles you acquired from XPLMRegisterAvionicsCallbacksEx(). They will no longer be called.
XPLM_API void XPLMUnregisterAvionicsCallbacks(
XPLMAvionicsID inAvionicsId
);
XPLMAvionicsScreenCallback_f
callback XPLM410
This is the prototype for drawing callbacks for custom devices' screens. Refcon is a unique value that you specify when creating the device, allowing you to slip a pointer to your own data to the callback.
Upon entry the OpenGL context will be correctly set up for you and OpenGL will be in panel coordinates for 2d drawing. The OpenGL state (texturing, etc.) will be unknown. X-Plane does not clear your screen for you between calls - this means you can re-use portions to save drawing, but otherwise you must call glClear() to erase the screen's contents.
typedef void (* XPLMAvionicsScreenCallback_f)(
void * inRefcon
);
XPLMAvionicsBezelCallback_f
callback XPLM410
This is the prototype for drawing callbacks for custom devices' bezel. You are passed in the red, green, and blue values you can optinally use for tinting your bezel accoring to ambiant light.
Refcon is a unique value that you specify when creating the device, allowing you to slip a pointer to your own data to the callback.
Upon entry the OpenGL context will be correctly set up for you and OpenGL will be in panel coordinates for 2d drawing. The OpenGL state (texturing, etc.) will be unknown.
typedef void (* XPLMAvionicsBezelCallback_f)(
float inAmbiantR,
float inAmbiantG,
float inAmbiantB,
void * inRefcon
);
XPLMAvionicsBrightness_f
callback XPLM410
This is the prototype for screen brightness callbacks for custom devices. If you provide a callback, you can return the ratio of the screen's maximum brightness that the simulator should use when displaying the screen in the 3D cockpit.
inRheoValue is the current ratio value (between 0 and 1) of the instrument brightness rheostat to which the device is bound.
inAmbientBrightness is the value (between 0 and 1) that the callback should return for the screen to be at a usable brightness based on ambient light (if your device has a photo cell and automatically adjusts its brightness, you can return this and your screen will be at the optimal brightness to be readable, but not blind the pilot).
inBusVoltsRatio is the ratio of the nominal voltage currently present on the bus to which the device is bound, or -1 if the device is not bound to the current aircraft.
Refcon is a unique value that you specify when creating the device, allowing you to slip a pointer to your own data to the callback.
typedef float (* XPLMAvionicsBrightness_f)(
float inRheoValue,
float inAmbiantBrightness,
float inBusVoltsRatio,
void * inRefcon
);
XPLMCreateAvionics_t
struct XPLM410
The XPLMCreateAvionics_t structure defines all of the parameters used to generate your own glass cockpit device by using XPLMCreateAvionicsEx(). The structure will be expanded in future SDK APIs to include more features. Always set the structSize member to the size of your struct in bytes!
typedef struct {
int structSize;
int screenWidth;
int screenHeight;
int bezelWidth;
int bezelHeight;
int screenOffsetX;
int screenOffsetY;
bool drawOnDemand;
XPLMAvionicsBezelCallback_f bezelDrawCallback;
XPLMAvionicsScreenCallback_f drawCallback;
XPLMAvionicsMouse_f bezelClickCallback;
XPLMAvionicsMouse_f bezelRightClickCallback;
XPLMAvionicsMouseWheel_f bezelScrollCallback;
XPLMAvionicsCursor_f bezelCursorCallback;
XPLMAvionicsMouse_f screenTouchCallback;
XPLMAvionicsMouse_f screenRightTouchCallback;
XPLMAvionicsMouseWheel_f screenScrollCallback;
XPLMAvionicsCursor_f screenCursorCallback;
XPLMAvionicsKeyboard_f keyboardCallback;
XPLMAvionicsBrightness_f brightnessCallback;
char const* deviceID;
char const * deviceName;
userref refcon;
int native;
} XPLMCreateAvionics_t;
XPLMCreateAvionicsEx
function XPLM410
Creates a new cockpit device to be used in the 3D cockpit. You can call this at any time: if an aircraft referencing your device is loaded before your plugin, the simulator will make sure to retroactively map your display into it.
When you are done with the device, and at least before your plugin is unloaded, you should destroy the device using XPLMDestroyAvionics().
XPLM_API XPLMAvionicsIDXPLMCreateAvionicsEx(
XPLMCreateAvionics_t * inParams
);
XPLMDestroyAvionics
function XPLM410
Destroys the cockpit device and deallocates its screen's memory. You should only ever call this for devices that you created using XPLMCreateAvionicsEx(), not X-Plane' built-ine devices you have customised.
XPLM_API void XPLMDestroyAvionics(
XPLMAvionicsID inHandle
);
XPLMIsAvionicsBound
function XPLM410
Returns true (1) if the cockpit device with the given handle is used by the current aircraft.
XPLM_API int XPLMIsAvionicsBound(
XPLMAvionicsID inHandle
);
XPLMSetAvionicsBrightnessRheo
function XPLM410
Sets the brightness setting's value, between 0 and 1, for the screen of the cockpit device with the given handle.
If the device is bound to the current aircraft, this is a shortcut to setting the brightness rheostat value using the sim/cockpit2/switches/instrument_brightness_ratio[] dataref; this sets the slot in the instrument_brightness_ratio array to which the device is bound.
If the device is not currently bound, the device keeps track of its own screen brightness rheostat, allowing you to control the brightness even though it isn't connected to the instrument_brightness_ratio dataref.
XPLM_API void XPLMSetAvionicsBrightnessRheo(
XPLMAvionicsID inHandle,
float brightness
);
XPLMGetAvionicsBrightnessRheo
function XPLM410
Returns the brightness setting value, between 0 and 1, for the screen of the cockpit device with the given handle.
If the device is bound to the current aircraft, this is a shortcut to getting the brightness rheostat value from the `sim/cockpit2/switches/instrument_brightness_ratio[]` dataref; this gets the slot in the `instrument_brightness_ratio` array to which the device is bound.
If the device is not currently bound, this returns the device's own brightness rheostat value.
XPLM_API float XPLMGetAvionicsBrightnessRheo(
XPLMAvionicsID inHandle
);
XPLMGetAvionicsBusVoltsRatio
function XPLM410
Returns the ratio of the nominal voltage (1.0 means full nominal voltage) of the electrical bus to which the given avionics device is bound, or -1 if the device is not bound to the current aircraft.
XPLM_API float XPLMGetAvionicsBusVoltsRatio(
XPLMAvionicsID inHandle
);
XPLMIsCursorOverAvionics
function XPLM410
Returns true (1) if the mouse is currently over the screen of cockpit device with the given handle. If they are not NULL, the optional x and y arguments are filled with the co-ordinates of the mouse cursor in device co-ordinates.
XPLM_API int XPLMIsCursorOverAvionics(
XPLMAvionicsID inHandle,
int * outX, /* Can be NULL */
int * outY /* Can be NULL */
);
XPLMAvionicsNeedsDrawing
function XPLM410
Tells X-Plane that your device's screen needs to be re-drawn. If your device is marked for on-demand drawing, X-Plane will call your screen drawing callback before drawing the next simulator frame. If your device is already drawn every frame, this has no effect.
XPLM_API void XPLMAvionicsNeedsDrawing(
XPLMAvionicsID inHandle
);
XPLMSetAvionicsPopupVisible
function XPLM410
Shows or hides the popup window for a cockpit device.
Visibility is independent of where the popup is drawn (in the X-Plane window, popped out as an OS window, or mapped to a VR floating window): the popup always remains in whichever target mode you most recently selected, and toggling visibility just shows or hides it there.
XPLM_API void XPLMSetAvionicsPopupVisible(
XPLMAvionicsID inHandle,
int inVisible
);
XPLMIsAvionicsPopupVisible
function XPLM410
Returns true (1) if the popup window for a cockpit device is visible.
XPLM_API int XPLMIsAvionicsPopupVisible(
XPLMAvionicsID inHandle
);
XPLMPopOutAvionics
function XPLM410
Pops out the window for a cockpit device, making it a first-class window in the operating system, separate from the X-Plane window.
Popping out and being mapped to VR are mutually exclusive: if the device is currently mapped to VR (XPLMIsAvionicsMappedToVR() is true), calling this routine clears its VR mapping before popping out.
XPLM_API void XPLMPopOutAvionics(
XPLMAvionicsID inHandle
);
XPLMIsAvionicsPoppedOut
function XPLM410
Returns true (1) if the popup window for a cockpit device is popped out as a first-class OS window.
This is true if and only if you have most recently asked the popup to be popped out (via XPLMPopOutAvionics()) and it has not since been mapped to VR (via XPLMSetAvionicsMappedToVR()).
XPLM_API int XPLMIsAvionicsPoppedOut(
XPLMAvionicsID inHandle
);
XPLMSetAvionicsMappedToVR
function XPLM440
Maps a custom cockpit device's popup window to a VR floating window in the headset, or returns it from VR back to the X-Plane window. Pass 1 to map to VR, 0 to unmap.
The VR window shows the device's bezel and screen at their intrinsic size, as supplied via XPLMCreateAvionicsEx(). Avionics in VR are not user-resizable.
Mapping to VR and being popped out as an OS window are mutually exclusive: calling this with inMapped=1 on a popped-out device clears its pop-out state, and calling XPLMPopOutAvionics() on a VR-mapped device clears its VR mapping. This mirrors the relationship between xplm_WindowPopOut and xplm_WindowVR for XPLMWindow.
VR mapping is independent of popup visibility (XPLMSetAvionicsPopupVisible). Mapping a hidden popup to VR leaves it hidden until you make it visible.
Has no effect (and logs a warning) if VR is not currently running on the headset, or if the device was not created via XPLMCreateAvionicsEx() (built-in avionics cannot be VR-mapped).
XPLM_API void XPLMSetAvionicsMappedToVR(
XPLMAvionicsID inHandle,
int inMapped
);
XPLMIsAvionicsMappedToVR
function XPLM440
Returns true (1) if the popup window for a cockpit device is currently mapped to a VR floating window.
This is true if and only if you have most recently asked the device to be mapped to VR (via XPLMSetAvionicsMappedToVR()) and it has not since been unmapped, popped out, or had VR shut down beneath it.
XPLM_API int XPLMIsAvionicsMappedToVR(
XPLMAvionicsID inHandle
);
XPLMTakeAvionicsKeyboardFocus
function XPLM410
This routine gives keyboard focus to the popup window of a custom cockpit device, if it is visible.
XPLM_API void XPLMTakeAvionicsKeyboardFocus(
XPLMAvionicsID inHandle
);
XPLMHasAvionicsKeyboardFocus
function XPLM410
Returns true (1) if the popup window for a cockpit device has keyboard focus.
XPLM_API int XPLMHasAvionicsKeyboardFocus(
XPLMAvionicsID inHandle
);
XPLMGetAvionicsGeometry
function XPLM410
Returns the bounds of a cockpit device's popup window in the X-Plane coordinate system.
XPLM_API void XPLMGetAvionicsGeometry(
XPLMAvionicsID inHandle,
int * outLeft, /* Can be NULL */
int * outTop, /* Can be NULL */
int * outRight, /* Can be NULL */
int * outBottom /* Can be NULL */
);
XPLMSetAvionicsGeometry
function XPLM410
Sets the size and position of a cockpit device's popup window in the X-Plane coordinate system.
XPLM_API void XPLMSetAvionicsGeometry(
XPLMAvionicsID inHandle,
int inLeft,
int inTop,
int inRight,
int inBottom
);
XPLMGetAvionicsGeometryOS
function XPLM410
Returns the bounds of a cockpit device's popped-out window.
XPLM_API void XPLMGetAvionicsGeometryOS(
XPLMAvionicsID inHandle,
int * outLeft, /* Can be NULL */
int * outTop, /* Can be NULL */
int * outRight, /* Can be NULL */
int * outBottom /* Can be NULL */
);
XPLMSetAvionicsGeometryOS
function XPLM410
Sets the size and position of a cockpit device's popped-out window.
XPLM_API void XPLMSetAvionicsGeometryOS(
XPLMAvionicsID inHandle,
int inLeft,
int inTop,
int inRight,
int inBottom
);