{ Copyright 2005-2012 Sandy Barbour and Ben Supnik All rights reserved. See license.txt for usage. X-Plane SDK Version: 2.1.1 } UNIT XPLMDisplay; INTERFACE { XPLM Display APIs - THEORY OF OPERATION This API provides the basic hooks to draw in X-Plane and create user interface. All X-Plane drawing is done in OpenGL. The X-Plane plug-in manager takes care of properly setting up the OpenGL context and matrices. You do not decide when in your code's execution to draw; X-Plane tells you when it is ready to have your plugin draw. X-Plane's drawing strategy is straightforward: every "frame" the screen is rendered by drawing the 3-d scene (dome, ground, objects, airplanes, etc.) and then drawing the cockpit on top of it. Alpha blending is used to overlay the cockpit over the world (and the gauges over the panel, etc.). There are two ways you can draw: directly and in a window. Direct drawing involves drawing to the screen before or after X-Plane finishes a phase of drawing. When you draw directly, you can specify whether x-plane is to complete this phase or not. This allows you to do three things: draw before x-plane does (under it), draw after x-plane does (over it), or draw instead of x-plane. To draw directly, you register a callback and specify what phase you want to intercept. The plug-in manager will call you over and over to draw that phase. Direct drawing allows you to override scenery, panels, or anything. Note that you cannot assume that you are the only plug-in drawing at this phase. Window drawing provides slightly higher level functionality. With window drawing you create a window that takes up a portion of the screen. Window drawing is always two dimensional. Window drawing is front-to-back controlled; you can specify that you want your window to be brought on top, and other plug-ins may put their window on top of you. Window drawing also allows you to sign up for key presses and receive mouse clicks. There are three ways to get keystrokes: If you create a window, the window can take keyboard focus. It will then receive all keystrokes. If no window has focus, X-Plane receives keystrokes. Use this to implement typing in dialog boxes, etc. Only one window may have focus at a time; your window will be notified if it loses focus. If you need to associate key strokes with commands/functions in your plug-in, use a hot key. A hoy is a key-specific callback. Hotkeys are sent based on virtual key strokes, so any key may be distinctly mapped with any modifiers. Hot keys can be remapped by other plug-ins. As a plug-in, you don't have to worry about what your hot key ends up mapped to; other plug-ins may provide a UI for remapping keystrokes. So hotkeys allow a user to resolve conflicts and customize keystrokes. If you need low level access to the keystroke stream, install a key sniffer. Key sniffers can be installed above everything or right in front of the sim. } USES XPLMDefs; {$A4} {$IFDEF MSWINDOWS} {$DEFINE DELPHI} {$ENDIF} {___________________________________________________________________________ * DRAWING CALLBACKS ___________________________________________________________________________} { Basic drawing callbacks, for low level intercepting of render loop. The purpose of drawing callbacks is to provide targeted additions or replacements to x-plane's graphics environment (for example, to add extra custom objects, or replace drawing of the AI aircraft). Do not assume that the drawing callbacks will be called in the order implied by the enumerations. Also do not assume that each drawing phase ends before another begins; they may be nested. } { XPLMDrawingPhase This constant indicates which part of drawing we are in. Drawing is done from the back to the front. We get a callback before or after each item. Metaphases provide access to the beginning and end of the 3d (scene) and 2d (cockpit) drawing in a manner that is independent of new phases added via x-plane implementation. WARNING: As X-Plane's scenery evolves, some drawing phases may cease to exist and new ones may be invented. If you need a particularly specific use of these codes, consult Austin and/or be prepared to revise your code as X-Plane evolves. } TYPE XPLMDrawingPhase = ( { This is the earliest point at which you can draw in 3-d. } xplm_Phase_FirstScene = 0 { Drawing of land and water. } ,xplm_Phase_Terrain = 5 { Drawing runways and other airport detail. } ,xplm_Phase_Airports = 10 { Drawing roads, trails, trains, etc. } ,xplm_Phase_Vectors = 15 { 3-d objects (houses, smokestacks, etc. } ,xplm_Phase_Objects = 20 { External views of airplanes, both yours and the AI aircraft. } ,xplm_Phase_Airplanes = 25 { This is the last point at which you can draw in 3-d. } ,xplm_Phase_LastScene = 30 { This is the first phase where you can draw in 2-d. } ,xplm_Phase_FirstCockpit = 35 { The non-moving parts of the aircraft panel. } ,xplm_Phase_Panel = 40 { The moving parts of the aircraft panel. } ,xplm_Phase_Gauges = 45 { Floating windows from plugins. } ,xplm_Phase_Window = 50 { The last change to draw in 2d. } ,xplm_Phase_LastCockpit = 55 {$IFDEF XPLM200} { 3-d Drawing for the local map. Use regular OpenGL coordinates to draw in } { this phase. } ,xplm_Phase_LocalMap3D = 100 {$ENDIF} {$IFDEF XPLM200} { 2-d Drawing of text over the local map. } ,xplm_Phase_LocalMap2D = 101 {$ENDIF} {$IFDEF XPLM200} { Drawing of the side-profile view in the local map screen. } ,xplm_Phase_LocalMapProfile = 102 {$ENDIF} ); PXPLMDrawingPhase = ^XPLMDrawingPhase; { XPLMDrawCallback_f This is the prototype for a low level drawing callback. You are passed in the phase and whether it is before or after. If you are before the phase, return 1 to let x-plane draw or 0 to suppress x-plane drawing. If you are after the phase 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 'local' coordinates for 3d drawing and panel coordinates for 2d drawing. The OpenGL state (texturing, etc.) will be unknown. } XPLMDrawCallback_f = FUNCTION( inPhase : XPLMDrawingPhase; inIsBefore : integer; inRefcon : pointer) : integer; cdecl; { XPLMKeySniffer_f This is the prototype for a low level key-sniffing function. Window-based UI _should not use this_! The windowing system provides high-level mediated keyboard access. By comparison, the key sniffer provides low level keyboard access. Key sniffers are provided to allow libraries to provide non-windowed user interaction. For example, the MUI library uses a key sniffer to do pop-up text entry. inKey is the character pressed, inRefCon is a value you supply during registration. Return 1 to pass the key on to the next sniffer, the window mgr, x-plane, or whomever is down stream. Return 0 to consume the key. Warning: this API declares virtual keys as a signed character; however the VKEY #define macros in XPLMDefs.h define the vkeys using unsigned values (that is 0x80 instead of -0x80). So you may need to cast the incoming vkey to an unsigned char to get correct comparisons in C. } XPLMKeySniffer_f = FUNCTION( inChar : char; inFlags : XPLMKeyFlags; inVirtualKey : char; inRefcon : pointer) : integer; cdecl; { XPLMRegisterDrawCallback This routine registers a low level drawing callback. Pass in the phase you want to be called for and whether you want to be called before or after. This routine returns 1 if the registration was successful, or 0 if the phase does not exist in this version of x-plane. You may register a callback multiple times for the same or different phases as long as the refcon is unique each time. } FUNCTION XPLMRegisterDrawCallback( inCallback : XPLMDrawCallback_f; inPhase : XPLMDrawingPhase; inWantsBefore : integer; inRefcon : pointer) : integer; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMUnregisterDrawCallback This routine unregisters a draw callback. You must unregister a callback for each time you register a callback if you have registered it multiple times with different refcons. The routine returns 1 if it can find the callback to unregister, 0 otherwise. } FUNCTION XPLMUnregisterDrawCallback( inCallback : XPLMDrawCallback_f; inPhase : XPLMDrawingPhase; inWantsBefore : integer; inRefcon : pointer) : integer; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMRegisterKeySniffer This routine registers a key sniffing callback. You specify whether you want to sniff before the window system, or only sniff keys the window system does not consume. You should ALMOST ALWAYS sniff non-control keys after the window system. When the window system consumes a key, it is because the user has "focused" a window. Consuming the key or taking action based on the key will produce very weird results. Returns 1 if successful. } FUNCTION XPLMRegisterKeySniffer( inCallback : XPLMKeySniffer_f; inBeforeWindows : integer; inRefcon : pointer) : integer; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMUnregisterKeySniffer This routine unregisters a key sniffer. You must unregister a key sniffer for every time you register one with the exact same signature. Returns 1 if successful. } FUNCTION XPLMUnregisterKeySniffer( inCallback : XPLMKeySniffer_f; inBeforeWindows : integer; inRefcon : pointer) : integer; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} {___________________________________________________________________________ * WINDOW API ___________________________________________________________________________} { Window API, for higher level drawing with UI interaction. Note: all 2-d (and thus all window drawing) is done in 'cockpit pixels'. Even when the OpenGL window contains more than 1024x768 pixels, the cockpit drawing is magnified so that only 1024x768 pixels are available. } { XPLMMouseStatus When the mouse is clicked, your mouse click routine is called repeatedly. It is first called with the mouse down message. It is then called zero or more times with the mouse-drag message, and finally it is called once with the mouse up message. All of these messages will be directed to the same window. } TYPE XPLMMouseStatus = ( xplm_MouseDown = 1 ,xplm_MouseDrag = 2 ,xplm_MouseUp = 3 ); PXPLMMouseStatus = ^XPLMMouseStatus; {$IFDEF XPLM200} { XPLMCursorStatus XPLMCursorStatus describes how you would like X-Plane to manage the cursor. See XPLMHandleCursor_f for more info. } XPLMCursorStatus = ( { X-Plane manages the cursor normally, plugin does not affect the cusrsor. } xplm_CursorDefault = 0 { X-Plane hides the cursor. } ,xplm_CursorHidden = 1 { X-Plane shows the cursor as the default arrow. } ,xplm_CursorArrow = 2 { X-Plane shows the cursor but lets you select an OS cursor. } ,xplm_CursorCustom = 3 ); PXPLMCursorStatus = ^XPLMCursorStatus; {$ENDIF} { XPLMWindowID This is an opaque identifier for a window. You use it to control your window. When you create a window, you will specify callbacks to handle drawing and mouse interaction, etc. } XPLMWindowID = pointer; PXPLMWindowID = ^XPLMWindowID; { XPLMDrawWindow_f This function handles drawing. You are passed in your window and its refcon. Draw the window. You can use XPLM functions to find the current dimensions of your window, etc. When this callback is called, the OpenGL context will be set properly for cockpit drawing. NOTE: Because you are drawing your window over a background, you can make a translucent window easily by simply not filling in your entire window's bounds. } XPLMDrawWindow_f = PROCEDURE( inWindowID : XPLMWindowID; inRefcon : pointer); cdecl; { XPLMHandleKey_f This function is called when a key is pressed or keyboard focus is taken away from your window. If losingFocus is 1, you are losign the keyboard focus, otherwise a key was pressed and inKey contains its character. You are also passewd your window and a refcon. Warning: this API declares virtual keys as a signed character; however the VKEY #define macros in XPLMDefs.h define the vkeys using unsigned values (that is 0x80 instead of -0x80). So you may need to cast the incoming vkey to an unsigned char to get correct comparisons in C. } XPLMHandleKey_f = PROCEDURE( inWindowID : XPLMWindowID; inKey : char; inFlags : XPLMKeyFlags; inVirtualKey : char; inRefcon : pointer; losingFocus : integer); cdecl; { XPLMHandleMouseClick_f You receive this call when the mouse button is pressed down or released. Between then these two calls is a drag. You receive the x and y of the click, your window, and a refcon. Return 1 to consume the click, or 0 to pass it through. WARNING: passing clicks through windows (as of this writing) causes mouse tracking problems in X-Plane; do not use this feature! } XPLMHandleMouseClick_f = FUNCTION( inWindowID : XPLMWindowID; x : integer; y : integer; inMouse : XPLMMouseStatus; inRefcon : pointer) : integer; cdecl; {$IFDEF XPLM200} { XPLMHandleCursor_f The SDK calls your cursor status callback when the mouse is over your plugin window. Return a cursor status code to indicate how you would like X-Plane to manage the cursor. If you return xplm_CursorDefault, the SDK will try lower-Z-order plugin windows, then let the sim manage the cursor. Note: you should never show or hide the cursor yourself - these APIs are typically reference-counted and thus cannot safely and predictably be used by the SDK. Instead return one of xplm_CursorHidden to hide the cursor or xplm_CursorArrow/xplm_CursorCustom to show the cursor. If you want to implement a custom cursor by drawing a cursor in OpenGL, use xplm_CursorHidden to hide the OS cursor and draw the cursor using a 2-d drawing callback (after xplm_Phase_Window is probably a good choice). If you want to use a custom OS-based cursor, use xplm_CursorCustom to ask X-Plane to show the cursor but not affect its image. You can then use an OS specific call like SetThemeCursor (Mac) or SetCursor/LoadCursor (Windows). } XPLMHandleCursor_f = FUNCTION( inWindowID : XPLMWindowID; x : integer; y : integer; inRefcon : pointer) : XPLMCursorStatus; cdecl; {$ENDIF} {$IFDEF XPLM200} { XPLMHandleMouseWheel_f The SDK calls your mouse wheel callback when one of the mouse wheels is turned within your window. Return 1 to consume the mouse wheel clicks or 0 to pass them on to a lower window. (You should consume mouse wheel clicks even if they do nothing if your window appears opaque to the user.) 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). } XPLMHandleMouseWheel_f = FUNCTION( inWindowID : XPLMWindowID; x : integer; y : integer; wheel : integer; clicks : integer; inRefcon : pointer) : integer; cdecl; {$ENDIF} {$IFDEF XPLM200} { XPLMCreateWindow_t The XPMCreateWindow_t structure defines all of the parameters used to create a window using XPLMCreateWindowEx. 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! } XPLMCreateWindow_t = RECORD structSize : integer; left : integer; top : integer; right : integer; bottom : integer; visible : integer; drawWindowFunc : XPLMDrawWindow_f; handleMouseClickFunc : XPLMHandleMouseClick_f; handleKeyFunc : XPLMHandleKey_f; handleCursorFunc : XPLMHandleCursor_f; handleMouseWheelFunc : XPLMHandleMouseWheel_f; refcon : pointer; END; PXPLMCreateWindow_t = ^XPLMCreateWindow_t; {$ENDIF} { XPLMGetScreenSize This routine returns the size of the size of the X-Plane OpenGL window in pixels. Please note that this is not the size of the screen when doing 2-d drawing (the 2-d screen is currently always 1024x768, and graphics are scaled up by OpenGL when doing 2-d drawing for higher-res monitors). This number can be used to get a rough idea of the amount of detail the user will be able to see when drawing in 3-d. } PROCEDURE XPLMGetScreenSize( outWidth : Pinteger; { Can be nil } outHeight : Pinteger); { Can be nil } {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMGetMouseLocation This routine returns the current mouse location in cockpit pixels. The bottom left corner of the display is 0,0. Pass NULL to not receive info about either parameter. } PROCEDURE XPLMGetMouseLocation( outX : Pinteger; { Can be nil } outY : Pinteger); { Can be nil } {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMCreateWindow This routine creates a new window. Pass in the dimensions and offsets to the window's bottom left corner from the bottom left of the screen. You can specify whether the window is initially visible or not. Also, you pass in three callbacks to run the window and a refcon. This function returns a window ID you can use to refer to the new window. NOTE: windows do not have "frames"; you are responsible for drawing the background and frame of the window. Higher level libraries have routines which make this easy. } FUNCTION XPLMCreateWindow( inLeft : integer; inTop : integer; inRight : integer; inBottom : integer; inIsVisible : integer; inDrawCallback : XPLMDrawWindow_f; inKeyCallback : XPLMHandleKey_f; inMouseCallback : XPLMHandleMouseClick_f; inRefcon : pointer) : XPLMWindowID; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} {$IFDEF XPLM200} { XPLMCreateWindowEx This routine creates a new window - you pass in an XPLMCreateWindow_t structure with all of the fields set in. You must set the structSize of the structure to the size of the actual structure you used. Also, you must provide funtions for every callback - you may not leave them null! (If you do not support the cursor or mouse wheel, use functions that return the default values.) The numeric values of the XPMCreateWindow_t structure correspond to the parameters of XPLMCreateWindow. } FUNCTION XPLMCreateWindowEx( inParams : PXPLMCreateWindow_t) : XPLMWindowID; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} {$ENDIF} { XPLMDestroyWindow This routine destroys a window. The callbacks are not called after this call. Keyboard focus is removed from the window before destroying it. } PROCEDURE XPLMDestroyWindow( inWindowID : XPLMWindowID); {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMGetWindowGeometry This routine returns the position and size of a window in cockpit pixels. Pass NULL to not receive any paramter. } PROCEDURE XPLMGetWindowGeometry( inWindowID : XPLMWindowID; outLeft : Pinteger; { Can be nil } outTop : Pinteger; { Can be nil } outRight : Pinteger; { Can be nil } outBottom : Pinteger); { Can be nil } {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMSetWindowGeometry This routine allows you to set the position or height aspects of a window. } PROCEDURE XPLMSetWindowGeometry( inWindowID : XPLMWindowID; inLeft : integer; inTop : integer; inRight : integer; inBottom : integer); {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMGetWindowIsVisible This routine returns whether a window is visible. } FUNCTION XPLMGetWindowIsVisible( inWindowID : XPLMWindowID) : integer; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMSetWindowIsVisible This routine shows or hides a window. } PROCEDURE XPLMSetWindowIsVisible( inWindowID : XPLMWindowID; inIsVisible : integer); {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMGetWindowRefCon This routine returns a windows refcon, the unique value you can use for your own purposes. } FUNCTION XPLMGetWindowRefCon( inWindowID : XPLMWindowID) : pointer; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMSetWindowRefCon This routine sets a window's reference constant. Use this to pass data to yourself in the callbacks. } PROCEDURE XPLMSetWindowRefCon( inWindowID : XPLMWindowID; inRefcon : pointer); {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMTakeKeyboardFocus This routine gives a specific window keyboard focus. Keystrokes will be sent to that window. Pass a window ID of 0 to pass keyboard strokes directly to X-Plane. } PROCEDURE XPLMTakeKeyboardFocus( inWindow : XPLMWindowID); {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMBringWindowToFront This routine brings the window to the front of the Z-order. Windows are brought to the front when they are created...beyond that you should make sure you are front before handling mouse clicks. } PROCEDURE XPLMBringWindowToFront( inWindow : XPLMWindowID); {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMIsWindowInFront This routine returns true if you pass inthe ID of the frontmost visible window. } FUNCTION XPLMIsWindowInFront( inWindow : XPLMWindowID) : integer; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} {___________________________________________________________________________ * HOT KEYS ___________________________________________________________________________} { Hot Keys - keystrokes that can be managed by others. } { XPLMHotKey_f Your hot key callback simply takes a pointer of your choosing. } TYPE XPLMHotKey_f = PROCEDURE( inRefcon : pointer); cdecl; { XPLMHotKeyID Hot keys are identified by opaque IDs. } XPLMHotKeyID = pointer; PXPLMHotKeyID = ^XPLMHotKeyID; { XPLMRegisterHotKey This routine registers a hot key. You specify your preferred key stroke virtual key/flag combination, a description of what your callback does (so other plug-ins can describe the plug-in to the user for remapping) and a callback function and opaque pointer to pass in). A new hot key ID is returned. During execution, the actual key associated with your hot key may change, but you are insulated from this. } FUNCTION XPLMRegisterHotKey( inVirtualKey : char; inFlags : XPLMKeyFlags; inDescription : Pchar; inCallback : XPLMHotKey_f; inRefcon : pointer) : XPLMHotKeyID; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMUnregisterHotKey This API unregisters a hot key. You can only register your own hot keys. } PROCEDURE XPLMUnregisterHotKey( inHotKey : XPLMHotKeyID); {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMCountHotKeys Returns the number of current hot keys. } FUNCTION XPLMCountHotKeys: integer; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMGetNthHotKey Returns a hot key by index, for iteration on all hot keys. } FUNCTION XPLMGetNthHotKey( inIndex : integer) : XPLMHotKeyID; {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMGetHotKeyInfo Returns information about the hot key. Return NULL for any parameter you don't want info about. The description should be at least 512 chars long. } PROCEDURE XPLMGetHotKeyInfo( inHotKey : XPLMHotKeyID; outVirtualKey : Pchar; { Can be nil } outFlags : PXPLMKeyFlags; { Can be nil } outDescription : Pchar; { Can be nil } outPlugin : PXPLMPluginID); { Can be nil } {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} { XPLMSetHotKeyCombination XPLMSetHotKeyCombination remaps a hot keys keystrokes. You may remap another plugin's keystrokes. } PROCEDURE XPLMSetHotKeyCombination( inHotKey : XPLMHotKeyID; inVirtualKey : char; inFlags : XPLMKeyFlags); {$IFDEF DELPHI} cdecl; external 'XPLM.DLL'; {$ELSE} cdecl; external ''; {$ENDIF} IMPLEMENTATION END.