XPLM 2.1 Release Notes

From X-Plane SDK
Jump to: navigation, search

This document lists the new features in the 2.1 revision of the X-Plane plugin API. The 2.1 API is available to plugins running with X-Plane 10.0 or newer. See the Download page to download the headers.

64-Bit Clean Headers

With the new 2.1 SDK release, some C types have been altered to create an ABI that will function correctly in up-coming 64-bit versions of X-Plane. This SDK does not allow you to build 64-bit plugins, but it does allow you to migrate you C types to be ready for 64 bits. The changes do not affect the compiled layout of existing plugins, so no mandatory change is required; see 64 Bit for more details.

Plugins in Scenery Packs

With the 2.1 API, a fat plugin may be stored in a scenery pack as well as in an aircraft or the global Resources folder. To put a plugin in a scenery pack, create a "plugins" folder in your scenery pack, and install a fat plugin into that new plugins folder. Non-fat plugins are not allowed in scenery packs.

Scenery-pack-based plugins are currently loaded up front at startup and run for the entirety of X-Plane's operation, so be sure not to use resources when the user's plane is not within your plugin's region.

Implementation Cleanup and Modernization

The 2.1 API comes with a number of "under-the-hood" modernizations that make it easier to write callbacks; if you know you will be targeting X-Plane 10.0 or later, this can help speed development.

Re-entrant Callbacks

Starting with 2.1 API, all subsystems are now safe for re-entrant calls from a single thread. In the older X-Plane SDK implementations, calling one API from the callback registered by another in the same subsystem could cause a crash. Example: registering a flight loop callback from a flight loop callback was not supported.

You can now safely make API calls that create or delete internal callbacks, objects or resources from any callback.

UTF8-friendly implementation

All X-Plane SDK APIs are now UTF8-friendly and should handle any non-ASCII characters that X-Plane handles. (See below.)

Ability to Select Native Paths

Traditionally the X-Plane SDK uses a "native" 8-bit file path:

  • On Mac, this is an HFS file path with MacRoman encoding, and the : directory separator.
  • On Windows, this is a DOS path with the local code page for non-ASCII characters, and \ as the directory separator.
  • On Linux, this is a Unix path with UTF8 encoding and / as a directory separator.

Starting in the new 2.1 API, you can enable a new feature key called "XPLM_USE_NATIVE_PATHS". When this is enabled, all operating systems will provide UTF8 encoded paths with / as the directory separator and Unix-style full paths (with a drive letter for Windows). This has a few advantages:

  • It is completely unicode safe.
  • On OS X, it means you can use the native BSD APIs directly with file paths; no more HFS-Unix transcoding via CFString and CFURL.

See XPLM_Feature_Keys for how to "opt in" to native paths.

Duplicate Signatures Rejected

The X-Plane SDK version 2.1 will no longer load plugins with duplicate signatures; the second loading instance will be rejected.

New APIs

Several new APIs have been added to the 2.1 API.

Post-FM Callback

The flight loop API features a new set of calls for creating and destroying flight loop callbacks. These new APIs work with an explicit reference handle (a XPLMFlightLoopID). See XPLMCreateFlightLoop, XPLMDestroyFlightLoop, and XPLMScheduleFlightLoop.

Unlike previous flight loops, the new APIs let you schedule a flight loop to run either before or after the sim's flight loop, allowing for more data-processing flexibility.

Thread-Safe Task Schedule

The new API XPLMScheduleFlightLoop can be called from threads other than the thread your plugin is called on. This means that you can "wake up" a flight loop callback directly from a worker thread without having to create your own message queue or inter-thread synchronization message. See the XPLMScheduleFlightLoop for the conditions under which you can do this.

Menu Item Delete

The menu API now features a new XPLMRemoveMenuItem call to remove existing menus.

Async Object Load

The scenery APIs feature a new way to load OBJ files. XPLMLoadObjectAsync takes an object and calls your plugin back later after asynchronously loading your object. Since OBJ load can take up to a few seconds, this lets plugins load objects on the fly without hurting framerate.

New Messages

The new APIs introduce two new messages:

  • XPLM_MSG_LIVERY_LOADED. This message is sent to your plugin after a new livery is loaded. The parameter is the aircraft number for which the livery is loaded, casted to a pointer.
  • XPLM_MSG_WILL_WRITE_PREFS. This message is sent before the sim writes preferences. If your plugin has altered datarefs that would normally be persisted to the preferences file, this callback gives you a chance to reset those datarefs before the preferences file goes out to disk.