SDKVersioning

From X-Plane SDK
Jump to: navigation, search

This technote describes how the X-Plane 2.0 API changes are implemented, and how to use them in your plugin.

Extensions of the API

The 2.0 API changes all take the form of extensions, in three forms:

  • New enums and values that can be passed into existing functions.
  • New functions (that either add new functionality or provide extended versions of existing APIs).
  • New items at the end of structures.

Typically functions that extend APIs have the form XPLMCreateWindowEx.

Structures that can be extended have a struct size (in bytes) as their first parameter; by indicating how long the structure is, your plugin indicates which version of the structure it is working with.

Effect on 1.0 plugins

1.0 plugins do not require any modification to run under X-Plane 9 (or any 2.0 API-capable host). Plugins will continue to find an XPLM DLL with all of the needed entry points.

Plugins compiled and linked against the 1.0 SDK (that is, the SDK materials distributed previously) experience no change in their compile environment.

Using the 2.0 headers

In order to compile new code for the 2.0 API you will need to:

  • Replace your copy of the 1.0 SDK headers with the 2.0 SDK headers, so you have access to the new functions and enums.

NOTE - You will need to #define XPLM200 (before including the headers) to enable the new APIs.

The purpose of the XPLM200 flag is to allow you to easily build plugins that are restricted to the 1.0 SDK or 2.0 SDK from one (new) set of headers.

Linking 2.0 plugins

For Mac and Linux, plugins simply leave SDK symbols unresolved - they are found at runtime. So for these operating systems, no materials are needed to link a 2.0 plugin.

Windows plugins will need the import library from the 2.0 SDK to link when new symbols are used. If a Windows plugin links against the 2.0 SDK but only uses 1.0 symbols (e.g. if XPLM200 is not defined) then your plugin will load on systems that only support 1.0 plugins.

Creating a 1.0 plugin that uses 2.0 APIs.

Normally 1.0 plugins will run everywhere (but cannot use new functions) while 2.0 plugins have access to all functions (but can only run in X-Plane 9). But it is possible to create a plugin that runs on older versions of X-Plane and uses new functions when they are available. This is not easy, and not recommended unless you are an advanced programmer with experience with dynamic linking.

  • The plugin does not define XPLM200.
  • The plugin uses GetProcAddress or dlsym to locate new function calls by name (and passes in new enums explicitly by value).
  • The plugin must check the SDK version number to be sure new enums will work, and the return value of GetProcAddress or dlsym to be sure that functions are found.