From X-Plane SDK
Revision as of 04:17, 2 September 2009 by Bsupnik (wiki cleanup)
Here are some guidelines for how to keep your plugin compatible with future versions of X-Plane:
- Read all the TechNotes - they contain valuable info on how to use the APIs.
- Be sure to use XPLMWorldToLocal and XPLMLocalTToWorld for coordinate conversions - don't write the math yourself. (See ScreenCoordinates.)
- Use the panel position datarefs to draw to the panel - do not assume you know where the panel is or what the coordinate system is. (See ScreenCoordinates.)
- Use drawing callbacks for drawing, not processing. There is no guarantee of what the drawing callback order will be or how many times per frame they will be called. Use the flight loop callbacks for per-frame processing!
- Don't abuse the drawing callbacks - see DrawingRules for more info.
- Don't abuse OpenGL state - if you leave state unset and it "seems okay" in the sim today, it will probably cause corruption or a crash tomorrow. See DrawingRules for how to correctly handle state.
- The SDK is not thread safe - do not assume it is. If you use a thread and things "seem okay", that just means you got lucky - your plugin will explode later.
- Always check datarefs for NULL values - any dataref could be deprecated in the future.
- Defer initialization - the SDK is in a weird state the first time the sim loads - see DeferredInitialization.
- Read the font metrics to arrange elements based on SDK drawing. The sim font changed from X-Plane 6 to 7 and will change again in the future.
- Look out for APIs that may be scheduled for removal. See WhatsGoingAway for possible candidates.
- Don't depend on writing to unwritable datarefs. In X-Plane 8 and earlier, this would sometimes work, but an unwritable dataref is an indication that writing to the dataref is probably not a good idea.
- Do not pass any non-ASCII characters to any plugin routines that require a string. Do not assume that output from the SDK can correctly contain extended characters. Do not assume that a particular encoding might be behind 8-bit strings!
- Do not write to sim flight model datarefs from drawing callbacks - see the above note about abusing drawing callbacks. This one can produce inconsistent visual output (since the flight model might be drawn multiple times for multiple rendering passes, changing the flight model between drawing passes is a bad idea.)
- Do not make any assumptions about "handles" and opaque references returned by the SDK. They are of type void * to guarantee that they are at least as large as a pointer type in memory - not because they are necessarily pointers. Do not assume that you can dereference them, validate them via virtual memory validity tests (e.g. IsBadReadPtr) or try to interpret them as either an index or memory block. Do not assume that handles will repeat values, provide unique values, etc. The only guarantee on an opaque handle is that for any two objects that are instantiated at the same time, they will not have the same handle value.