From X-Plane SDK
Jump to: navigation, search

Warning This page is pretty old and may be out of date. Some of what has been proposed has already been done with the introduction of the SDK 2.0 API.

This is a proposed evolution plan for the API from 1.0 to 1.1. This is not a declaration of what will happen, it is a proposal about what could happen.

The X-Plane plugin 1.1 API will be an evolution of the 1.0 API that adds additional features and addresses some of the SDK's limitations. The 1.1 API will be available starting at a certain version of X-Plane forward. (Hint: if this strategy seems like a rip-off of how MS migrates the Win32 APIs, you're right...it is.)

There is no set timeframe for the 1.1 API; we're still in the brainstorming phase.

Function changes in the 1.1 API=

Functions in the SDK will fall into three catagories:

  1. Functions available in the 1.0 SDK that are available in the 1.1 SDK as well. (This will be nearly all functions from the 1.0 SDK.
  2. Functions that are deprecated. These functions will be available in the 1.0 and 1.1 SDK, but we strongly discouragae you from using them.
  3. New 1.1 functions, available only in the 1.1 SDK.

No function APIs will be changed; where a change is needed, a new secondary function will be added that provides access to augmented functionality.

To manage these functions, the SDK headers will now require the definition of a __compatibility mode__ enumeration. This enumeration will define what kind of plugin you are building:

  • A 1.0 plugin. Only 1.0 functions (deprecated or not) are available. This plugin will run on any version of x-plane.
  • A 1.1 plugin. Only non-deprecated1.0 functions and 1.1 functions are available. This is ideal for 1.1 developers. If you use a 1.1 function, you will need a 1.1 version of x-plane.
  • A 1.1 legacy plugin. All functions included deprecated 1.0 functions are available. This isn't recommended, becuase it means you've moved forward to using new functions without cleaning up old nasty ones, but it will be provied. If you use a 1.1 function, you will need a 1.1 version of x-plane.
  • A 1.1/1.0 hybrid function. In this mode, you have access to 1.0 functions (deprecated and not), but not 1.1 functions, but you __do__ have access to 1.1 enumerations and constants. The idea here is that you will use 1.1 functions by selectively finding them in the DLL __if__ they are present, and gracefully fall back on old behavior. Your plugin will work on any version of x-plane, but behavior may vary.

You will have three ways to link your plugin: 1. You can link against the old 1.0 library. Your plugin must not use any 1.1 functions, and will run on any version of x-plane. 2. You can link against the new 1.1 library. Your plugin may use 1.1 functions, and you will need a version of x-plane that supports 1.1 plugins. 3. You can link against the 1.0 library, but use a routine to dynamically fetch new functions if they are present. Your plugin will run on any version of x-plane.

Dynamically fetching functions

With X-Plane 1.1 we will provide a routine to access functions by name in the SDK. You will receive a function pointer or NULL if the running version of x-plane doesn't provide that function. This allows a plugin to run on old versions of x-plane but use new features when available.

But there is a problem....how do you in a 1.0 plugin fetch a function if we are adding this capability in the 1.1 APIs? Doh! The answer is that we will provide the code for this function in source, so that you can compile it directly into your plugin and run it. The function will detect the plugin SDK version in the sim on the fly and "do the right thing" to fetch your functions for you.

API Style changes

Functions that need augmentation (for example, XPLMCreateWindow may in the 1.1 feature allow an optional mouse wheel callback) will be handled by creating a new function, XPLMCreateWindowEx, with a new parameter list. The new function is recommended for plugins that will only run on the 1.1 APi.

Where possible, functions will take structure pointers instead of parameters, to allow for parameters to be added later. These structures will feature the size of the structure as the first parameter; by filling this in your plugin tells the SDK what features it knows about. For example, the new create window might have a structure like this:

typedef struct {
   int structSize;
   XPLMMouseClickHandler_f clickHandler;
   XPLMKeyPressHandler_f keyHandler;
   XPLMMouseWheelHandler_f wheelHandler;
} XPLMCreateWindowInfo_t;
XPLMWindowID XPLMCreateWindowEx(XPLMCreateWindow_t * inInfo);

By filling in a struct size of 16 in your code (via something like:

XPLMCreateWindow_t createInfo = { 0 };
createInfo.structSize = sizeof(createInfo);

you tell the SDK that you know about the first three callbacks. A future API can add more callbacks and your plugin can take advantage of them.

Other changes

Where possible we will be evolving parts of the SDK that enumerate dynamic sim-defined behaviro to be string-based.

To clarify: currently datarefs are strings, so your plugin can use the latest datarefs at any point, but must check to make sure the dataref exists. (For example, sim/cockpit/autopilot/autopilot_state only exists in 7.10 and later.)

But keyboard command enums (xplm_key_ enums) are fixed in the headers, and new ones are not available as Austin adds new features.

To alleviate this, commands like XPLMCommandKeyStroke will have some way to take dynamic content, e.g.

if (!XPLMCommandKeyStrokeEx("autopilot_filghtlevel_change"))
    // The SDK doesn't know what the flight level change command is.  Do something else.