xplane-sys 4.0.109

Low-level bindings for the X-Plane plugin SDK
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

#ifndef _XPLMInstance_h_
#define _XPLMInstance_h_

/***************************************************************************
 * XPLMInstance
 ***************************************************************************/
/*
 * 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.)
 *
 */

#include "XPLMDefs.h"
#include "XPLMScenery.h"

#ifdef __cplusplus
extern "C" {
#endif

/***************************************************************************
 * Instance Creation and Destruction
 ***************************************************************************/
/*
 * Registers and unregisters instances.
 *
 */


/*
 * XPLMInstanceRef
 * 
 * An opaque handle to an instance.
 *
 */
typedef void * XPLMInstanceRef;

/*
 * XPLMCreateInstance
 * 
 * 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.
 *
 */
XPLM_API XPLMInstanceRef XPLMCreateInstance(
                         XPLMObjectRef        obj,
                         const char **        datarefs);

/*
 * XPLMDestroyInstance
 * 
 * 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.
 *
 */
XPLM_API void       XPLMDestroyInstance(
                         XPLMInstanceRef      instance);

/***************************************************************************
 * Instance Manipulation
 ***************************************************************************/

/*
 * XPLMInstanceSetPosition
 * 
 * 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.
 *
 */
XPLM_API void       XPLMInstanceSetPosition(
                         XPLMInstanceRef      instance,
                         const XPLMDrawInfo_t * new_position,
                         const float *        data);

#ifdef __cplusplus
}
#endif

#endif