XPLMInstance API

This API provides instanced drawing of X-Plane objects (.obj files). In contrast to old drawing APIs, which required you to draw your own objects per-frame, the instancing API allows you to simply register an OBJ for drawing, then move or manipulate it later (as needed).

This provides one tremendous benefit: it keeps all dataref operations for your object in one place. Because datarefs access may be done from the main thread only, allowing dataref access anywhere is a serious performance bottleneck for the simulator - the whole simulator has to pause and wait for each dataref access. This performance penalty will only grow worse as X-Plane moves toward an ever more heavily multithreaded engine.

The instancing API allows X-Plane to isolate all dataref manipulations for all plugin object drawing to one place, potentially providing huge performance gains.

Here’s how it works:

When an instance is created, it provides a list of all datarefs you want to manipulate for the OBJ in the future. This list of datarefs replaces the ad-hoc collections of dataref objects previously used by art assets. Then, per-frame, you can manipulate the instance by passing in a “block” of packed floats representing the current values of the datarefs for your instance. (Note that the ordering of this set of packed floats must exactly match the ordering of the datarefs when you created your instance.)

Instance Creation and Destruction

Registers and unregisters instances.

XPLMInstanceRef

typedef void * XPLMInstanceRef;

An opaque handle to an instance.

XPLMCreateInstance

XPLM_API XPLMInstanceRef XPLMCreateInstance(
                         XPLMObjectRef        obj,
                         const char **        datarefs);

XPLMCreateInstance creates a new instance, managed by your plug-in, and returns a handle to the instance. A few important requirements:

The object passed in must be fully loaded and returned from the XPLM before you can create your instance; you cannot pass a null obj ref, nor can you change the ref later.
If you use any custom datarefs in your object, they must be registered before the object is loaded. This is true even if their data will be provided via the instance dataref list.
The instance dataref array must be a valid pointer to a null-terminated array. That is, if you do not want any datarefs, you must pass a pointer to a one-element array containing a null item. You cannot pass null for the array itself.

XPLMDestroyInstance

XPLM_API void       XPLMDestroyInstance(
                         XPLMInstanceRef      instance);

XPLMDestroyInstance destroys and deallocates your instance; once called, you are still responsible for releasing the OBJ ref.

Tip: you can release your OBJ ref after you call XPLMCreateInstance as long as you never use it again; the instance will maintain its own reference to the OBJ and the object OBJ be deallocated when the instance is destroyed.

Instance Manipulation

XPLMInstanceSetPosition

XPLM_API void       XPLMInstanceSetPosition(
                         XPLMInstanceRef      instance,
                         const XPLMDrawInfo_t * new_position,
                         const float *        data);

Updates both the position of the instance and all datarefs you registered for it. Call this from a flight loop callback or UI callback.

DO_NOT call XPLMInstanceSetPosition from a drawing callback; the whole point of instancing is that you do not need any drawing callbacks. Setting instance data from a drawing callback may have undefined consequences, and the drawing callback hurts FPS unnecessarily.

The memory pointed to by the data pointer must be large enough to hold one float for every dataref you have registered, and must contain valid floating point data.

BUG: before X-Plane 11.50, if you have no dataref registered, you must still pass a valid pointer for data and not null.