Plugin-Drawn Objects Do Not Exist

Version 2.0 of the plugin API (available in all versions of X-Plane 9) introduces three new routines that, for the first time, allow plugins to work with OBJs.

XPLMLoadObject and XPLMUnloadObject load an OBJ file (a model mesh) into memory, and then purge it when done. That part most users understand. The routine that causes confusion is XPLMDrawObjects. When you draw an OBJ with XPLMDrawObjects, you are not creating anything long-lasting or persistent in the world. Your object will be visible for one frame on screen, and then will disappear unless your draw it again. Your object is not part of any of the physics calculations.

To put this in perspective: when you make a new window using the Widgets API, the window is persistent - it exists until (1) you delete it or (2) your plugin is unloaded for some reason. You don't have to do anything per frame to "maintain" the window - you make it and it exists.

Objects are not like that. You cannot make an object "exist" in the X-Plane world - you can only draw it once per frame using the drawing callbacks. Essentially the draw-objects API is a lower level API.

Building a Layered System

Plugins operate in a layered environment, with lower level code on the bottom and your plugin at the top. The layer stack might only be 2 layers deep (XPLM on the bottom, plugin on top), or there might be several layers. Consider XSquawkBox:

• The UI is drawn using the XPWidgets API. The XPWidgets API gets its drawing from the XPUIGraphics API, and the XPUIGraphics API changes OpenGL state using the XPLMGraphics API. So we've built up a layered system: basic OpenGL supports drawing, drawing supports user interface, user interface supports the plugin.
• Similarly, multiplayer is done using a library that isn't part of the basic plugin system (but is open source): libXplaneMP. So here the XPLM supports drawing airplanes, libXplaneMP uses that to create a full multiplayer API, then XSquawkBox uses it.

The alternative to a layered system would be a "monolithic" one. Under a monolithic system, the only API for airplanes would be libXplaneMP, and the only way to create user interface would be widgets. Sandy and I usually prefer the layered approach because it provides a lot more flexibility. If you like widgets, great, use them. If not, no problem - roll your own on top of XPLMDisplay.

The Plugin System Is a Foundation

When Sandy and I cannot provide all of the layers, we have a strong bias toward providing the bottom layer, for an obvious reason: if the bottom layer isn't in the plugin system, it may be impossible for anyone else to create it. So typically if we have a choice between a high level vs. low level API, we'll put the low level API in first.

This is precisely what is happening with object drawing - we have the low level API ("draw an object") but not the high level one ("create an object in the scenery system"). Since we have provided the lowest level, it is possible to code persistent objects in your plugin by layering on top of our API. By comparison, had we only provided "create an object" it would be pretty close to impossible to draw an object for one frame - if you didn't want a scenery object, the API would be inflexible and useless.