Category: Plugins

Plugins: Do Not Register Drawing Callbacks That Do Not Draw

Plugin developers: the title says it all – don’t register a drawing callback that doesn’t actually draw anything.

When I write it like that, it sounds a little bit silly, but some plugins register a drawing callback on startup, because they might draw something – but then only do the drawing when certain things happen. I am guilty of this myself – libxplanemp registers its drawing callbacks at init time even if there are no multiplayer planes to draw.

Most plugins did this for simplicity and to avoid any strange rules about when you could register things – the original 1.0 SDK was a lot pickier than what we have now. And back in 1537 when the French invaded Flanders, the cost of a no-op a draw callback was pretty cheap – just the cost of the function call-out and a few instructions of book keeping.

Over time, as X-Plane’s renderer has become more complex, this has become not the case. X-Plane now does some significant work to save and restore GL state when we hit a drawing callback, and that overhead is going to become significantly more expensive when we move to Vulkan/Metal.

To optimize this, Tyler modified the drawing callback code in 11.10 – starting with 11.10 if we find that no plugin has registered a given drawing callback, we skip the entire process, including the OpenGL book keeping.

So if your plugin goes in and registers a callback for every single drawing callback type then we have to fall back to the slow path, carefully stashing our GL state and prepping for your running at each drawing callback point.

Here’s my guidance:

  1. Never register for a drawing callback you’re not going to use.
  2. Do delay registering for a drawing callback until it is possible to need it.
  3. Don’t try to optimize your drawing callbacks by registering and de-registering per frame.

So as an example, it would be reasonable for a multiplayer API to register a drawing callback when the first airplane enters the system and then keep it around until the last airplane goes away, even if that airplane is off screen.

(The reason for that last rule is: if we have to make an expensive graphics transition once we discover that drawing callbacks will be needed, we don’t want to get thrashed by drawing callbacks disappearing and then re-appearing over and over.)

Posted in Development, Plugins by | 13 Comments

Manipulators and VR Part 1: From Mouse to Mechanism

For airplane authors, the biggest question VR brings up is: what do I have to do to my aircraft to make this work? This is the first of three posts explaining not only how manipulation works with VR, but why we made our decisions and how we got here. Bear with me – this will end with specific recommendations for what to do with your aircraft.

A Long Time Ago…

Old-timers like me will remember that when the 3-d cockpit first came out, almost all of the “brains” of it were powered by clicking on the 2-d panel, which was “mapped” to the 3-d cockpit.  X-Plane would find out where your mouse click intersected the 3-d cockpit, find the texture location on that triangle, and map that back to the 2-d panel.

This seemed pretty cool when it came out 15 years ago, but as authors started making more sophisticated 3-d cockpits, it became clear that we needed a way to specify how the mouse worked directly with the 3-d cockpit shape, because the mapping back to the 2-d wouldn’t allow the user to do basic things like dragging a throttle.

Thus in X-Plane 9 we added the first set of manipulators – tags on the 3-d mesh of a cockpit specifying what happens when the user clicks on it. The manipulator could specify a dataref to modify, a command to actuate, and some data about what kind of mouse click operation was happening.

The key words here are mouse click. The original manipulators were designed entirely in terms of a mouse on a 2-d screen; they were designed to be exactly as powerful as a 2-d panel system, which was of coarse also totally mouse-centric. The relationship between the generic instruments and the original manipulators is pretty tight.

Moving to Mechanisms

The good part of the original manipulator system was that it was very flexible – mouse-centric handlers were a low level tool around which authors could do whatever they wanted.

The down-side of this design was that mouse-centric handlers were a low level tool around which authors could do whatever we want. We examined our own default fleet of a dozen or so aircraft and found that no two aircraft’s cockpits operated the same way, and almost all of them had at least some aspect that was hard to use – a poor manipulator choice for the job.

Knobs were, in particular, quite difficult – the original 2-d panel system used click-and-hold over a knob to actuate it, but authors working in 3-d had often used drag actions to do knobs, and the drag actions would respond differently depending on camera angle. We received approximately 8,452,124 bug reports that the knobs in the 747 were hard to use specifically because of this.

So during X-Plane 10, we added some new manipulators to X-Plane, and they had a very different philosophy: the manipulator described what was happening in the simulated aircraft, and X-Plane picked a mouse behavior to make that work. The new manipulators described knobs that turned and switches that either flipped left-right or up-down.  These manipulators reacted to the scroll wheel automatically because X-Plane knows what the knob is and therefore what a reasonable scroll-wheel interaction should be. (By comparison, with the old-style manipulators, the author has to specify what a reasonable scroll-wheel action is.)

Real Interaction Things Before It Was Cool

As it turns out, mechanism-centric manipulators are a lot better for VR than mouse-centric ones. Consider two cases:

  • The 2-d axis manipulator (ATTR_manip_drag_xy) specifies what happens when the mouse moves up-down and left-right, relative to the screen. What on earth does that mean in VR? Even if we made something that tracks up-down and left-right relative to the screens of the HMD, the results would be completely weird because the “thing” in the cockpit would not move the way your hand was moving. With a mouse, a mis-match between mouse and aircraft isn’t surprising, but in VR, it’s weird to reach out and touch something and have it behave the wrong way.
  • The knob manipulator. It describes a knob that does things when turned clockwise or counter-clockwise.  This is pretty easy to deal with – you click it with your controller and turn your wrist clock-wise or counter-clockwise and it turns.  Because we know what the mechanism is (and not just what the mouse should do) we can make a good decision about how to handle this manipulator in VR.

As it turns out, we ran into this problem of not doing what to do with the mouse, and needing to know what the mechanism was before we even started looking at VR. The exact same problem (“I want to touch the 3-d cockpit as if it was a thing and have it respond in the expected way”) exists in VR and on X-Plane Mobile!

Because X-Plane mobile runs on a touch screen and you have your physical finger on a switch, there are a lot of cases where the switch has to track really well and work the right way.  If the switch goes up and down, you want to flick your finger up to turn the switch on; if it goes left-right you want to flick left and right, and anything else is astonishing.

So X-Plane mobile set us on this path toward mechanism-based manipulators, and VR further drove us in that direction, since both have the same physical, non-mouse environment where a user directly interacts with the 3-d cockpit.

Guidance For Authors

So as an author, what should you do when working on a 3-d cockpit? My answer is: use some of the manipulators, but not others, to model the way things work in 3-d.

Use these manipulators ALWAYS

These manipulators are the best way to create certain physical mechanisms – use them every time this case applies to your aircraft.

ATTR_manip_drag_axis. Use this for a physical mechanism that slides along a linear path, like the throttle handle of a Cessna.

ATTR_manip_drag_rotate. Use this for a physical mechanism that rotates around a fixed point, like the throttle handles of a 737, or a trim wheel.  (Prefer this to the old technique of putting a drag axis along the edge of the throttle handles.)

ATTR_manip_noop. Use this to make a manipulator that blocks the mechanism behind it from being touched, e.g. the safety guard plate over a switch.

ATTR_manip_command. Use this for push buttons that actuate momentarily while a button is held down, like a button to motor a starter that you push in and hold down.

ATTR_manip_command_knob, ATTR_manip_command_switch_up_down, ATTR_manip_command_switch_left_right. Use these for knobs and switches with 3 or more positions that rotate or move. Pick the right manipulator for the mechanism!

ATTR_manip_axis_knob, ATTR_manip_axis_switch_up_down, ATTR_manip_axis_switch_left_right. These provide an alternative to the above manipulators when you must use a dataref. We recommend commands over datarefs any time you have a choice; the command system provides better interoperability between custom plugins, custom aircraft, and custom hardware.

ATTR_manip_command_switch_left_right2, ATTR_manip_command_switch_up_down2, ATTR_manip_command_knob2. Use these for knobs and switches with exactly two positions. You can use these to get a simple click-to-toggle with the mouse (quicker and easier for mouse users) while getting real 3-d movement in VR.

Use These Manipulators Sometimes

These manipulators are not perfect fits with physical motions and may require tweaking for VR, but they’re the best options we have now for certain problems. Try to use something from the always list instead if you can. Do not use these manipulators if the mechanism you are simulating matches something from the list above.

ATTR_manip_drag_xy. This is the only 2-axis drag we have, and is the best choice for eye-ball vents and the yoke. The yoke is special-cased in VR and should be based off of a 2-d xy manipulator. We are looking into more powerful multi-dimensional manipulation in VR, but this work won’t be complete for 10.20.

ATTR_manip_command_axis. This manipulator runs a command once based on moving a lever down or up. You should probably use a drag axis or command up-down switch, but there may be some odd mechanisms in aircraft where this manipulator is a good fit. It should not be your first-choice go-to manipulator.

ATTR_manip_push, ATTR_manip_radio, ATTR_manip_toggle. These manipulators can serve as alternatives for push-button style controls when you absolutely have to write to a dataref and not use a command.  WARNING: Do not ever use these manipulators for things that move, e.g. don’t use these for banana switches, spinning knobs, or things like that.

Do not use these manipulators

These manipulators were for mouse-centric movement and should be replaced with knob or switch manipulators.

ATTR_manip_delta, ATTR_manip_wrap. These were designed to simulate knobs by click-and-hold – use the knob manipulators instead.

ATTR_manip_drag_axis_pix. This was designed to simulate a knob by click-and-drag – use the knob manipulators instead.

We Love Commands

As you may have noticed from this list and the ever-growing size of X-Plane’s built-in command list, we love commands – they have become our go-to mechanism for our aircraft. Commands have a few advantages over data-refs:

  1. There is a clear design in the plugin system for changing a command’s behavior. So a third party aircraft can easily “take over” the existing engine start command.  This is very, very difficult to accomplish via datarefs.
  2. Commands can be mapped directly to joystick and keyboard hardware. There is no way to bind a joystick to a dataref.*
  3. Commands can be mapped to sound to capture the act of the user “doing” the thing, regardless of whether it works. For example, if you want the click of the starter switch regardless of whether the starter motor engages (maybe the battery is dead), commands make this easy to do. Often there is no dataref for ‘the user is trying but it’s not working’.

In X-Plane 11 we’ve been moving to commands to get our planes ready for VR, the new manipulators, and FMOD sound all at once.

In the next post I’ll cover some of the issues specific to VR and the 3-d cockpit.



* Developers who write plugins that provide external interfaces to X-Plane: make sure you have a way to provide access to commands and not just datarefs!  There are things you can do only with commands and not datarefs.

Posted in Cockpits, Development, Plugins, VR by | 12 Comments

New Plugin Packaging for the SDK 3.0

This is a small feature but for plugin developers it may make a huge difference in work-flow.

In the plugin system up to version 2.1 (everything we’ve shipped through X-Plane 11.05) plugins are packed like this:


This has one problem: every plugin on your install is either named mac.xpl, win.xpl, or lin.xpl.

And as it turns out, pretty much every debugging tool ever assumes that each DLL will have its own unique name because it’d be crazy to do otherwise. The decision to make the file name in the fat plugin structure the OS was a really dumb one by me.

With version 3.0 of the SDK, you can now pack like this:


and with that format, each plugin’s name makes its DLL unique.

This should fix a bunch of things:

  • You’ll be able to start X-Plane via X-code to debug your plugin without all hell breaking loose.
  • Back traces on Windows debugging tools should make the plugin executing clear even without symbols.
  • Any kind of memory map dump (including those in Apple crash reports) will unambiguously show what plugin code is loaded into what memory address.

The existing 2.0 format (fat plugins shown above) and 1.0 format (thin plugins, supported only in the global plugins folder) will continue to work indefinitely – they’re still there.

But if you are going to target X-Plane 11.10 and use the new plugin system features, you may want to use the new packaging and save yourself some debugging chaos.

Posted in Development, Plugins by | 10 Comments

XPlane2Blender v3.4.0-beta.5 arrives

Download here:

Change Log

New Features

Build Version Numbers

XPlane2Blender’s new version number system will allow us to debug .blend and .obj file even faster. It should also make making updates to the data model easier to implement.

  • Every exported .obj file’s footer contains information about the addon version, when it was compiled, and why. For example: 3.4.0-beta.5+1.20170922151901

A break down of the components

  • 3.4.0: The traditional Blend addon number
  • beta: The type of build cycle we’re in. Other choices you may see are dev (a developer build), alpha, rc (for full release)
  • 5: the build type version we’re on. Since this is beta 5, the build type version is 5.

The elements after the + are generally less meaningful to the average user

  • 1: The version of the data model (the properties and settings for XPlane2Blender, used for comparing changes
  • 20170922151901: The “build number” date this source code was packaged and released in the form of YYYYMMDDHHMMSS in UTC.

The build version number is partially shown (elements after the + are hidden) in the scene settings under Composite Normal-Textures, potentially along with warnings about the stability of the build you are using.


When starting this version of the beta, you will see this:

A future stable version of 3.4.0 for the general public will show this:
Notice the green check mark and lack of any warnings.

In a future pre-alpha cycle for 3.4.1, two types of people will see the following:

  1. A developer writing and testing unreleased code
  2. Someone who didn’t head the warning against using such code, or get scared off by the nuclear symbol and extra warning about a lack of a build number

It is the worst case scenario for stability and traceability, hence the nuclear symbol.

Why the extra warning about a lack of a build number?

A lack of a build number indicates that you do not have a good dialog (e-mail, chat, this release page, or other channels) with a knowledgeable and attentive developer. This means your work is more likely to be run through a bad version of the code and damaged, or your bugs will be harder to diagnose and repair.
In this case, despite the code appearing to come from a stable era of the code near a release, there is potential for something to be wrong and have very poor ways of tracing what it could be – hence the lack of green check mark and big red warning symbol.

If you see some new pre-alpha feature you’d like to try, just ask us about it first. Going forward, we want to start with a dialog about potential dangers, testing, and intentions of an incomplete feature rather than an autopsy later on. Don’t be scared, we always love hearing from users before there is a problem, not after!

Build Version History

Also, all .blend files will be keeping a log of every different version of XPlane2Blender that they are opened and saved with. This is automatic and needs no involvement from the user. Those who are curious can look in the Plugin Development Tools section at the bottom of the scene settings and see the history of their file.

Note: This does not record any history data about Blender versions, other addon versions used, timestamps opened or saved, or changes made to it (including XPlane2Blender settings changes). It is purely useful as a debugging tool, and is not fool proof.

This .blend file started as a legacy 3.4.0 pre-beta.5 file, and was then with a copy of 3.4.0-beta.5, with no build number. Then it was used with 3.3.12, then finally, used with a build of 3.4.0-beta.5 created on 09/18/2017 at 01:27:30am.

One could use this information to guess what transformations the data could possibly have gone through along each step of its journey.

Posted in Development, Plugins by | 1 Comment

Plugin Compatibility and New XPLM 3.0 Features

Tyler posted about some of the new features coming to the X-Plane SDK version 3.0 API (available with 11.10 once we find the last bug and move it somewhere else). Here’s how compatibility works for the windowing system.

First, since the 2.0 SDK, XPLMCreateWindowEx has taken all of its arguments in a structure, a XPLMCreateWindow_t. That structure, in turn has a structSize variable that is meant to be initialized like this:

XPLMCreateWindow_t my_win = { 0 };
my_win.structSize = sizeof(my_win);
my_win.froblinator = xplmFull_Of_Eels; // etc.

Now when we revise the SDK, the size of the XPLMCreateWindow_t structure grows when you #define XPLM300. This results in new plugins compiled with the new SDK sending in a large struct (with more callbacks) and older plugins compiled against the old SDK sending in a small struct.

This is how the SDK “knows” what SDK you are using and provides new behavior to new plugins but provides compatible behavior to existing plugins, compiled years ago.

(This technique isn’t in any way new or unique to the X-Plane SDK – you can tell by the coding conventions that it is cough, cough, borrowed from the Win32 SDK.)

Posted in Development, Plugins by | 8 Comments

Two “Gotchas” Developing Plugins

These both come from third party developers – one I was aware of and one was completely new to me.

The Debug Heap Is Slow

Veteran Windows C++ developers know this, but if you don’t spend a lot of time with MSVC, this might be new.

The default configuration of MSVC is to force use of the debug heap when the debugger is attached; this applies even to release builds of binaries that aren’t yours.

What this means is: if you do nothing else but start your plugin “inside” X-Plane, X-Plane will use Microsoft’s debug heap.

We avoid doing this internally because it is really, really, really slow. The debug heap provides some great tracking for finding memory problems, but the cost is really, really slow load time.

The fix is simple: add _NO_DEBUG_HEAP=1 to the environment variables for your debugger. You can do this in the control panel as shown in the linked article, or you can add it to MSVC’s debugger properties.

Other Things To Go Fast

As a side tangent, when debugging a plugin, find ways to load X-Plane faster. A few things that can help:

  • Turn off AI aircraft.
  • Pick a simple aircraft to fly (e.g. not the 747).
  • Go somewhere without scenery (or without much scenery, e.g. PMDY).
  • If you have to have scenery, turn 3-d all the way off.

My Plugin Won’t Reload

We receive periodic bug reports that plugins won’t reload on Windows. This is miserable for you as a third party developer – it means rebooting the sim instead of just reloading your plugin. But why does it happen?

I thought we had a bug, but a third party developer found this:

I did searched the registry for the names I’ve used for X-Plane 11 folder and found this items at
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windws NT\CurrentVersion\AppCompatFlags\Layers

Each name used was included there with “$IgnoreFreeLibrary<win.xpl>”
value, after removing them and restarting X-Plane I got able to compile the plugin using the names again.

I have not found any official Microsoft documentation on this, just a lot of ranting from really annoyed programmers who want to know why the hell Microsoft would do this. If anyone has better Google-Fu than me and can find official docs, please do share. So what follows is my wild speculation of what’s going on.

In some old version of Windows, FreeLibrary probably didn’t actually (or immediately) free a DLL under certain circumstances. Application developers then wrote buggy apps that relied on this behavior, e.g. they freed a library while it was in use and their app didn’t crash.

Microsoft updated Windows and made FreeLibrary do what it says on the label, always, and old buggy apps started crashing left and right.

Microsoft, being Microsoft, did not say “you app developers are idiots, why don’t you go rewrite your buggy apps”. Instead, they added a feature to the App Compatibility Wizard that watches your app and, if it crashes after a DLL was unloaded and the moon is the right shade of Rondele, it adds a registry key marking this library as “never to be unloaded, even if this app says so”.

From that point on, the app doesn’t crash because the old semantics of FreeLibrary (“ha ha ha, you don’t mean that do you”) are restored in that one case.

The above is entirely made up – it’s my mental model for what might have happened, unless Raymond Chen someday gives us some back story.

Still, you can see what has gone wrong here – Windows decided that for compatibility reasons, plugins should not actually be unloaded, and since all of your DLLs are named win.xpl, this one plugin crash has caused plugins to never be unloaded. Thus the plugin unload/reload never releases the DLL and you can’t swap in new code.

Nuke the registry key and you’re back in business, at least until you crash again.


Posted in Development, Plugins by | 9 Comments

New SDK Features Coming in X-Plane 11.10

The upcoming X-Plane 11.10 release (and before you ask, we’ll let you know as soon as we have an ETA! 🙂 ) will include Version 3.0 of the X-Plane SDK (XPLM).

NB: The code samples linked below will not work yet—in part because X-Plane 11.10 isn’t in beta yet, and in part because we haven’t updated the sample code downloads with the new XPLM300 headers. But, that doesn’t mean you can’t look at the code itself right now!

There are a handful of really important features here for plugin developers:

  • Instanced drawing (via the new XPLMInstance header). This is a really important one for improving plugin drawing performance. More info on the theory behind this in Ben’s recent post. The good news for developers still working on X-Plane 10 plugins is that we’ve created a “wrapper” to provide backward compatibility with old versions of the SDK. Using the wrapper, you don’t get the performance benefit that you’d see in X-Plane 11, but you’ll at least be able to use the same API. See the sample project here.
  • Map APIs (via the new XPLMMap header). Based on our RFC, this provides an interface for drawing text labels, PNG icons, and arbitrary OpenGL within the X-Plane 11 maps. See the sample project here.
  • Two minor features for menus (in the XPLMMenus API; see the new menu SDK sample for examples):
    • Aircraft-specific menus. Plugins that get loaded with the user’s aircraft will now have access to XPLMFindAircraftMenu(), to which you can append new menu items or submenus.
    • Menu items that show keyboard shortcuts. When you add a menu item via XPLMAppendMenuItemWithCommand(), if the user has a key bound to that command, the key will be displayed on the right-hand side of the menu, just like X-Plane’s native menus.
  • More joystick axes & buttons, to match X-Plane 11.10’s support for 20 USB devices (up from the previous cap of 10).
  • Lots and lots of new features for plugin-created UI in the XPLMDisplay API, including:
    • Support for styling windows like the built-in X-Plane 11 windows (sample project here)
    • Support for “popping out” windows into first-class OS windows (demoed in the same sample project above)
    • Support for automatic UI scaling of all drawing in your window (this comes for free in all windows created with XPLMCreateWindowEx that are compiled against the XPLM300 API)—this means users with hi-DPI/4k monitors who have set a 150% or 200% scale for the X-Plane UI will get the experience they do with built-in windows.
    • Support for windows that automatically “stick” to certain edges of the screen, via the XPLMSetWindowGravity() API (sample project here)

Just to be 100% clear, to get any of these features (with the exception of the backward-compatibility wrapper for instanced drawing, of course), you’ll need to compile against the XPLM300 API.

[Edited to add:] Using the XPLM300 API is 100% optional. Old plugins will continue to function, and you could even write new plugins and compile them against the old API (I’m not sure why you would you want to…), and they’ll work in X-Plane 11.10 and beyond.

Posted in Plugins by | 27 Comments

XPlane2Blender v3.4.0-beta1 is out!

XPlane2Blender v3.4.0-beta1 is out!

The next version of XPlane2Blender is right around the corner, come test it! Highlights of this release are Optimized Animations, Increased Usability, and X-Plane 11 OBJ8 features (mainly Blend Glass mode and Normal Metalness). Read more about what has been changed on the release page and download it!

(Link to beta removed until major breaking bug has been fixed. Make backups of files before using any beta product.)

As with any beta, make backups before using a partially tested product. We don’t predict there should be anything breaking in it, but its never a bad idea to be safe.

Bugs and feed back on Github is preferred over this comment section, but most of all I want to hear your feedback. To stay focused, only comments related to XPlane2Blender, the beta, and Blender will be responded to for this section. The status of other 3D Modeling Plugins/VR/Weather Systems/etc is off topic.

Posted in Aircraft & Modeling, Development, Modeling, Plugins by | 9 Comments

In the Long Term, Plugins Shouldn’t Draw In 3-D Directly

Plugins can use OpenGL to draw directly inside X-Plane; this capability is almost fifteen years old and goes back to X-Plane 6. Plugin drawing typically falls into four categories:

  1. Drawing user interface (floating windows, HUD-like UI, map details, etc.).
  2. Drawing custom panel instruments (particularly 2-d glass displays).
  3. Drawing effects in 3-d (custom smoke or fire, or maybe diagram marks showing lift).
  4. Drawing solid stuff in 3-d (e.g. pushback trucks, parts of the airplane, etc.).

These first two use cases work pretty well; the third case works barely, and the last one is a bit of a train wreck.

Problems With Plugin Drawing

OpenGL an 3-d hardware was very different when Sandy and I created the original plugin SDK 1.0. Hardware had a fixed function pipeline built into the GPU itself, and your computer had one CPU core, so the issues I’m going to describe weren’t a problem back then. Here are some problems with plugin drawing:

  1. Increasing overhead just to draw. It used to be that we could just send a message to the plugin system at “good times” and let drawing happen. X-Plane now has to do a bunch of work to prepare OpenGL for plugin use; this synchronization work slows down X-Plane, and it’s getting worse as X-Plane’s internal design diverges from the canonical OpenGL 1.5 pipeline. (Example: we have to copy our matrices into the fixed function pipeline matrices before we call you, then copy them back if you call us with a drawing routine. Slow!)
  2. Plugins don’t have access to the fastest drawing paths. The less our drawing looks like OpenGL 1.5, the less efficient plugins are in comparison to X-Plane. This is getting worse over time too. (For example: if we want to render two VR eyes at once, we have to call your plugin twice, once for each one.)
  3. Plugins don’t have access to our lighting environment or G-Buffer formats, and thus can’t easily draw in a way that integrates with our 3-d world. This is getting worse as our rendering engine becomes more complicated.

So…this is not fantastic. The first two use cases (UI and panel) aren’t that badly affected because the two of them require only 2 or 3 call-outs to plugins, drawing in a very simple manner.  The second two (3-d use cases) are quite problematic.

These costs are going to get worse when X-Plane moves to Metal and Vulkan drives; the cost of syncing over to OpenGL will be higher, plugins won’t even be drawing on the fastest APIs, and we may have to do some expensive texture synchronization.

Fixing The Problem

My goal isn’t to completely eliminate the costs of plugin drawing; rather just to minimize the costs by providing better alternatives for common tasks.

So in the long term, my plan is to add something to the SDK that we should have had for a while: the ability to create persistent object and effect systems in the X-Plane world.

Right now if you want to draw an object, you call XPLMDrawObjects – hopefully you’re doing this from just the right callbacks, but if you get this wrong, I forgive you; the rules for how to do this correctly in the v10 and v11 renderers are insanely complex, because the plugin API was invented fifteen years ago.

In the future, you will be able to simply create an object and X-Plane will draw it at all the right times, for any rendering mode, handling all of the special cases for HDR, shadows, reflections, you name it. You’ll just need to tell us when it moves. The same idea can be applied to particle systems for effects.

The one open issue with this scheme is how animation will work. Currently animations is handled by reading datarefs – if you want to animate multiple instances from a plugin, you have to figure out (inside your dataref handler!) which instance is being drawn and return the right animation values.

Not only is this a complicated mess, but it’s also slow; it requires us to call your dataref callback many times from inside the drawing loop, slowing everything down.

What I’d like to have in the future is some kind of ‘animation block’ where:

  1. Your plugin queries the object to find out which animation values it needs.
  2. Each time you update a particular instance of that object, you provide a packed block of the values of all of those animations.
  3. We use the block directly and never have to call datarefs.

This technique isn’t just faster, it also is easier to make multi-core and will play nicely when we can instance animation in the future.

The time frame for this is “during the v11 run hopefully” – that is, a new object API is not going to be in 11.0, and I can’t guarantee when it will be. I expect to support the old way (XPLMDrawObject and drawing hooks) at least through the entire v11 run, if not longer; our expected failure mode is ‘if you do it the old way, the sim might be really slow’. The new APIs will be designed to be completely friendly with multi-monitor, VR, Vulcan, and multicore.


Posted in Development, Plugins by | 49 Comments

Mac Issues: SASL Crashes and Red Lines

I have two updates on Mac-specific bugs. Windows users, now is a good time to go get another cup of coffee. Update: it looks like neither of these bugs can be fixed or bypassed within X-Plane, so they could be with us for a while. So I am adding instructions on work-arounds for Mac users.

Red Red Lines

There is a bug on recent Nvidia cards (specific to OS X) where, at high rendering settings, you’ll see a red outline around the horizon. At this point I believe that this is a driver bug.

Here’s the interesting part: this bug is fixed in the Mac drivers that Nvidia provides. (Yes – NVidia provides a driver you can run on your Mac instead of the OS X shipping one.)

Now here’s the down-side, before you go install this thing. When I used this driver, I managed to repeatedly hang my entire machine while using X-Plane. This doesn’t happen using Apple’s driver.  So at this point I’d say “use at your own risk.”

(In Nvidia’s defense, the driver is targeted at after-market PCIe cards for pro users; use in a RetinaBook is “beta” and that’s what I did.)

We don’t have a work-around for the red line bug in sim – if I did, I’d have applied it. So this bug will probably be in 1040, and it will be up to you to either try the NV driver, wait for an Apple fix, or use different rendering settings.

Options for Work-Around:

  • Turn down shadow settings until the artifacts go away or
  • Install the Nvidia drivers and enable them in the menu bar control panel. (In the driver picker, pick OS X and you’ll find Mac after-market drivers.)

Crash Changing Planes or Quitting

Updated 11/20/15: this bug has been fixed – see here for the details.

If you get a crash when changing aircraft or quitting X-Plane, and the plane you were flying uses SASL, please don’t file a bug with me or send me a crash log. The crash is SASL crashing inside OpenAL. The crash is specific to El Capitan, and we don’t know what causes it.

This one is an area of on-going investigation; you can basically live with the annoyance of “crashing” out of every SASL aircraft or not use El Capitan. You already know how I feel about being an early adopter to new operating systems.

Options for Work-Around:

The problem is that the crash is when you unload an aircraft running SASL, so the bug appears to be “loading any plane crashes” – it’s really the unloading of the aircraft before that is causing a problem.  So the work-around is:

  1. Launch X-Plane.
  2. Pick Quick Flight and enable “Show this window on every startup of X-Plane”.
  3. Quit X-Plane – it may crash since you are unloading a SASL aircraft.
  4. When you re-start X-Plane, pick the default Cessna and you will no longer be “stuck”.

If you are stuck on El Capitan and you need to fly SASL aircraft and you are seeing crashes, my suggestion is to keep Quick Flight enabled at startup. If you have Yosemite and fly SASL-enhanced aircraft, I suggest not upgrading.

Posted in News, Plugins by | 21 Comments