Let Your Eyes Adjust

This is a feature I looked at putting into X-Plane 9, but it turned out that it affects so many different parts of the sim (and has to be done all-or-nothing) that it got kicked to v10. Consider these two pictures of the default B777 (the lighting was not adjusted, only the time of day):



The night image looks pretty, but what's wrong with the day image? The answer is: the small panel post lights in the night image are still casting a fair amount of light in the day image. And the result looks silly. But why?

The answer is: in real life your pupils would contract in the sun, letting in less light. The sun is really rather bright, so the daytime panel would still look normal, but the apparent power of those posts lights would be a lot less, because your eyes are less sensitive. In other words, the relative strength of the sun and post lights is wrong in the second image.

Computer monitors don't have a huge dynamic range for how much brightness they can put out. So we can't hope to display the absolute brightness of the scene correctly. Instead we need to make everything brighter at night (to simulate your night vision) and dimmer during the day, like this:




In this set of images, the night image is matched precisely to the previous one, but as the sun comes out, the apparent brightness of all lit textures has been scaled down to simulate the effect of your eye becoming less sensitive due to the flood of sunlight.

What's good about the compensated image is that the weird artifacts from the post lights are gone; the relative strength of the post lights is really low in relative terms.

What happened to the EFIS and moving map? The answer is that they too are not as apparently bright relative to the sun as they would be at night.

There is one hitch here: plenty of real airplanes have light sensors for various avionics; the avionics will automatically turn up their brightness during the day. So it is possible (I am no expert on the 777) that in the real plane, as the sun rises, you might not have to adjust your instrument brightness; the sensor would do it for you. The pictures above illustrate what you would see if no automatic adjustment is made.

Auto-adjustment presents a challenge: currently two wrongs make a right. We don't auto-adjust the brightness of instruments, but we don't simulate the apparent visual brightness relative to the sun, and the result are instruments that look adequately bright at all times of day without user adjustment.

I think in the productized version of this feature, authors will have two options for anything lit:

• Tie the lit instrument/texture to an auto-adjusting rheostat (e.g. brightness 1 + auto adjustment) or
  
• Tie the lit instrument to the "raw" rheostat (e.g. brightness 1).

The tricky part will be finding the right mapping for legacy airplanes into the new system.

Performance of Panel Texture vs. 3-d Cockpit

I sometimes get questions from authors considering how much to rely on a 2-d panel mapped to 3-d via the panel texture vs. a true 3-d panel. I can't comment on what will look best, but I can comment on the relative performance characteristics of both techniques, and the answer might surprise you: in some cases you'll get better performance by modeling directly in 3-d.

The 2-D Way

When you use the panel texture to make an object, X-Plane goes through a lot of steps to create the final result:

1. Your panel has to be rendered in 2-d. We atlas your panel textures, but we don't necessarily order them optimally - we don't know the optimal order. Each generic instrument is at least one batch, perhaps even two. Those batches have very low vertex count, and the vertices are stored non-optimally on the CPU. There may be a fair number of texture changes between instruments.
2. If you use ATTR_cockpit_region, we then go back and do the same thing...again! Why? Well, we need your panel's raw color ("albedo" to graphics nerds) and the emissive light given off by anything self-lit separately, so that we can do correct 3-d lighting.
3. Both of these are rendered to an off-screen texture that the video driver will feeel obligated to preserve at all costs, putting pressure on VRAM.
4. Only when all that is done do we begin drawing your object, with the usual batches to change to panel texture and change back, perform animations, etc.

If this seems expensive, that's because it is. Periodically users send me airplanes to look at their performance, and lately I've been seeing a lot more problems with 2-d panels (that fuel 3-d cockpits) being the performance bottleneck, not the 3-d modeling itself.

The 3-d Way

What if we want to go 3-d? Well, we're going to "eat" a lot more of what your 3-d pit already has:

• You'll need a lot more animations to move all of those parts.
• You'll need new batches with ATTR_lit_level to dial up and down various lighting levels.

But you do get some advantages:

• Geometry in objects is processed about as optimally as we possibly can. All of that work we've done on the rendering engine to make OBJs fast is available in your cockpit. So you can increase 3-d detail 'for free'.
  
• Your lit geometry can be drawn in a single pass (we don't need to prepare two separate lit textures). So for example a needle would take three batches via the panel-texture route (a batch to rotate the needle for albedo, a second batch to draw the rotated night needle, and a third batch to draw the resulting texture in 3-d) but only one if you use the OBJ directly.
• Since you organize your textures for OBJs, you can guarantee that all of the cockpit stuff is together, saving texture thrash.
• You can use normal maps to add per pixel detail to your cockpit; panel textured geometry cannot be normal mapped.
  

A Balancing Act

Given the high cost of panel texture relative to native OBJ drawing, you'd think going native OBJ would be a no-brainer, right? Well, not quite.

A needle is an easy case: you can model a needle using a rotation animation, so your implementation in an OBJ and our generic instrument are quite similar. Same with the throttle lever generic instrument.

But what about a "glass pie indicator"? What about a moving map? What about a rotary?

There are some generic instruments that have "movement" for which there is no equivalent OBJ technique. With these generics, the generic instrument/panel code may be able to render the generic quite a bit more directly than your OBJ can simulate the same effect.

This is my suggestion on a cut-off: if you can directly model a generic instrument with an OBJ (needles, throttles, and other "simple moving things"), consider 3-d. If you would have to use a lot of extra texture space, copies of your mesh, or a lot of show-hides, use the panel texture.

Your goal should not be to eliminate the use of panel texture. But if you can cut panel texture down to a single 1024 x 1024 region from a larger area, you'll probably see a performance win or a reduction in your airplane's system requirements.

Performance Test First

Final thought: before you invest months in a complex cockpit design, mock up the "work-load" X-Plane must do and performance test it! For an OBJ, simply make one moving instrument and duplicate the mesh to get the number of expected animations. For the panel, drag out a bunch of instruments, make custom textures and just paint junk into them with photoshop. The goal is to make X-Plane do the same amount of work as it will in the final version. Then fly your test panel on target computers and observe performance.

The 3-d Panel Is Not Always Necessary

There is no need to use the 3-d panel if you only want 3-d cockpit.

That might be the most counter-intuitive statement in the entire universe. Let's break it down and see what's going on. Originally we had the 2-D panel. The 2-D panel was where you put your instruments for interior views. When 3-d cockpit support was added, the 2-D panel was used to create the panel texture - that is, the instruments texture for the 3-D cockpit.

Thiat worked for a while, but as handles became more complex, screens became larger, and as 3-D cockpits became a more complex, authors started to run into the system's limitations. If the author wanted to create a huge panel, then the panel texture for the 3-D cockpit was huge. Furthermore, texture space for the instruments in the 3-D cockpit was wasted because the 2-D panel had to have windows on it.

With X-Plane and 9 we added the 3-D panel to fix these problems. The 3-D panel is a second panel whose sole purpose is to provide instruments as a texture for the 3-D cockpit. When you have a 2-D panel and a 3-D panel, the 2-D panel is used to draw the panel in 2-D viewing modes and 3-D panel is used only to create the panel texture for the 3-D cockpit. With this setup the 2-D panel can be huge, and the 3-D panel can be small and compact with no windows.

The 3-D panel solves a second problem as well. Often the overhead panel is drawn in perspective on the 2-D panel this perspective view is useless for texturing a true 3-D cockpit. With a 2-D panel and a 3-D panel, the author can draw the overhead in perspective for the 2-D panel, and orthographically for the 3-D panel.

Now here's where things get complicated: if an airplane has no 3-D panel the 2-D panel is used for both the 2-D view and the 3-D cockpit. But some airplanes have only a 3-D cockpit. In this case, there is no reason to use the 3-D panel at all. You can simply use the 2-D panel for texturing the 3-D cockpit and not worry about the user seeing it; in a 3-D only plane the user will only see the panel as a texture for the 3-D cockpit.

This setup is confusing in name: how can you have a 2-D panel used for a 3-D cockpits? But it is an allowed configuration. In fact, it was the only configuration allowed in X-Plane 8.

In summary: a 3-D cockpit can use the 2-D panel or 3-D panel as its panel texture. If an airplane has no 2-D panel, then the 2-D panel can be used for the 3-D cockpits without problems. In this situation and there is no need for a 3-D panel.

(It might be better to think of the 2-D panel and three panels simply add his two panels so that you can have two different versions of the panel. The names to the panel and 3-D panel are really just labels.)

Popup Panels?

X-Plane doesn't natively and directly support popup panels, but that doesn't mean you can't pop them up. Generic instruments have a dataref-driven set of show-hide fields. (The "filters".)

Now what you might not have realized is: groups have filters too! So you can hide an entire group with one filter, and you can put premade instruments in the group.

So...even though the FMS is a premade instrument with no filter fields, by grouping it you can show and hide it.

Important: the backgrounds of instruments are not shown or hidden. So if you want to do this, customize the FMS to have a transparent background, and use a generic rotary to put a real background behind it. The rotary goes in the group, and thus it can show and hide.

One more tip: clicking in 2-d goes through one instrument to another, for historical reasons. So if you pop up an instrument, you might want to hide the instruments it popped up over so clicks don't affect them.

Custom Plugin Instruments

A quick tip to anyone using OpenGL and a plugin to make custom instruments. (The most common case of this I can imagine is customized glass displays, where it may not be practical to use 10,000 generic instruments, and the display being emulated is basically a computer display.)

OpenGL is not pixel exact, its per-primitive anti-aliasing (e.g. draw me a smooth line) is inconsistent and weird, and you probably won't have full-screen anti-aliasing on your panel. (FSAA is out of your control, as X-Plane sets up the panel render.

For this reason, I recommend "texture anti-aliasing". Basically in this technique you draw everything as rectangles, - for your lines, you use textures that have alpha at the edge. The linear intepollation of the texture forms the anti-aliased edge.*

For a detailed examination of the problem, I recommend this page. (arekkusu is a freaking genius and his treatment of the problem is very thorough!) I have also tried to explain how the hell OpenGL decides what it's going to draw here. There are a few important cases where you can be pretty sure about what OpenGL will draw, and a lot of cases where you're playing pixel roulette.

The "texture" technique also has the advantage that it leads nicely into the use of texture artwork. For example, if you need a line with an arrow-head, well, you're already drawing a line as a textured rectangle with pixels in the center and alpha on the sides. Just ask your artist to draw an arrow-head in photoshop!

* Texture FSAA actually produces better results than FSAA (with non-AA pixels). The reason is that FSAA produces a finite number of intermediate alpha levels. The number of finite levels depends on the FSAA scheme, but it is always discrete levels, hence 16x FSAA looking better than 2x. By comparison, when we use textures, we get a smooth linear blend between our transparent and opaque pixels, giving us the smoothest possible anti-aliasing.

Where Did All of Those Lights Come From?

Javier posted a video of his CRJ on the dev list today. I have not tried the plane, but there is no question from the video that it looks really good. What makes the video look so nice is the careful management of light. Part of this comes from careful modeling in 3-d, and part of it comes from maxing out all of X-Plane's options for light.

But...what are the options for light on an airplane? I don't know what Javier has done in this case, but I can give you a laundry list of ways to get lighting effects into X-Plane.

Model In 3-D

To really have convincing light, the first thing you have to do is model in 3-d. There is no substitute - for lighting to look convincing, X-Plane needs to know the true shape of the exterior and interior of the plane, so that all light sources are directionally correct. X-Plane has a very large capacity for OBJ triangles, so when working in a tight space like the cockpit, use them wisely and the cockpit will look good under a range of conditions.

You can augment this with normal maps in 940. Normal maps may or may not be useful for bumpiness, but they also allow you to control the shininess on a per-pixel basis. By carefully controlling the shininess of various surfaces in synchronization with the base texture, you can get specular hilights where they are expected.

The 2-D Panel

First, if you want good lighting, you need to use panel regions. When you use a panel texture in a 3-d cockpit with ATTR_cockpit, X-Plane simply provides a texture that exactly matches the 2-d cockpit. Since the lighting on the 2-d cockpit is not directional, this is going to look wrong.

When you use ATTR_cockpit_region, X-Plane uses new next-gen lighting calculations, and builds a daytime panel texture and a separate emissive panel texture. These are combined taking into account all 3-d lighting (the sun and cockpit interior lights - see below). The result will be correct lighting in all cases.

Even if you don't need more than one region and havea simple 1024x1024 or 2048x1024 3-d panel, use ATTR_cockpit_region - you'll need it for high quality lighting.

The 2-d panel provides a shadow map and gray-scale illumination masks. Don't use them for 3-d work! The 2-d "global lighting" masks are designed for the 2-d case only. They are optimized to run on minimal hardware. They don't provide the fidelity for high quality 3-d lighting - they can have artifacts with overlays, there is latency in applying them, and they eat VRAM like you wouldn't believe. I strongly recommend against using them as a source of lighting for a 3-d cockpit.

To put this another way, you really want to have all global illumination effects be applied "in 3-d", so that the relative position of 3-d surfaces is taken into account. You can't do this with the 2d masks.

The 2-d panel lets you specify a lighting model for every overlay of every instrument - either:

• "Mechanical" or "Swapped" - this basically means the instrument provides no light of its own - it just reflects light from external sources.
• "Back-Lit" or "Additive" - this means the instrument has two textures. The non-lit texture reflects external light, and the lit texture glows on its own.
  
• "Glass" - the instrument is strictly emissive.

You can use 2-d overlays not only for instruments but also to create the lighting effect within instruments, e.g. the back-lighting on a steam gauge's markings, or the back-lighting on traced labels for an overhead panel.

2-d overlays take their lighting levels from one of sixteen "instrument brightness" rheostats. You can carefully allocate these 16 rheostats to provide independent lighting for various parts of the panel.

The 3-d Cockpit

The 3-d cockpit allows you to specify 3 omni or directional lights. These can be placed anywhere in the plane, affect all interior objects, and can be tinted and controlled by any dataref. Use them carefully - what they give you is a real sense of "depth". In particular, the 3-d lights are applied after animation. If a part of the cockpit moves from outside the light to into the light, the moving mesh will correctly change illumination. This is something you cannot do with pre-baked lighting (e.g. a _LIT texture).

Finally, ATTR_light_level is the secret weapon of lighting. ATTR_light_level lets you manually control the brightness of _LIT texture for a given submesh within an OBJ. There are a lot of tricks you can do with this:

• If you know how to pre-render lighting, you can pre-render the glow from a light onto your object into your _LIT texture, and then tie the brightness of the _LIT texture to a dataref. The result will be the appearance of a glow on your 3-d mesh as the light brightens. Because the lighting effect is pre-calculated, you can render an effect that is very high quality.
• You can create back-lit instruments in 3-d and link the _LIT texture to an instrument brightness knob.
• You can create illumination effects on the aircraft fuselage and tie them to the brightness of a beacon or strobe.

There are two limitations of ATTR_light_level to be aware of:

1. Any given triangle in your mesh can only be part of a single ATTR_light_level group. So you can't have multiple lighting effects on the same part of a mesh. Plan your mesh carefully to avoid conflicts. (Example: you can't have a glow on the tail that is white for strobes and red for beacons - you can only bake one glow into your _LIT texture.)
2. ATTR_light_level is not available on the panel texture. For the panel texture, use instrument brightness to control the brightness of the various instruments.

I have a sample plane that demonstrate a few of these tricks; I will try to post it on the wiki over the next few days.

Glass vs. Glass (Translucent)

In Plane-Maker you will see that there are two "glass" lighting modes for instruments - one called "glass" and the other called "glass (translucent)".

What's the difference?  The difference is how they respond to their lighting rheostat being turned down.

• Glass becomes dim by mixing the RGB colors of the overlays toward black.
• Glass (tranlsucent) becomes dim by mixing the alpha channel of the overlays toward transparent.

Which one do you want?  It depends on what you are doing.  The rules I suggest are:

• Use "glass" if you are using the layer as a "mask" to block elements behind it.
• Use "glass (translucent) if you are using the layer as an "overlay" to draw on top of other elements.

Masks for Glass Instruments

X-Plane's panel system does not have true "masking" based on a bitmap.  You can clip an instrument to its rectangular region, but most masks are made by overlaying another layer or instrument on top of the moving parts.  Examples include the circular mask for the moving map and the outside of the artificial horizon dial.

If you are using ATTR_cockpit then what you see in the OBJ is just like what you see in the 2-d panel, and the masking problem is simple: pick a mask that matches your background.  In particular, if the back of the panel is black, your mask must be black; if the back of your panel has a gradient, the mask must contain a copy of a slice of the gradient.

But there are two cases where this rule does not work the way you might expect.

Masks for 2-d Spotlights

The 2-d spotlight textures (panel-2, panel-3, etc.) have a strange property: they light the background of the panel (the "burned in layer") per-pixel but the overlays are lit per vertex. This is a cheat to keep the frame-rate high.

Normally this is not a problem - the moving parts are small and look different enough from the background that the lighting mismatch is not visible.  But if you have a mask in the 2-d panel and spot lights, it will not match!

Unfortunately there is not much you can do about this.  The only thing you can do is to keep the spotlight color uniform over the entire mask region.

Masks for Cockpit Regions

When you use ATTR_cockpit_region, the lighting model for your 3-d cockpit changes: instead of drawing the panel (as you saw it in 2-d), X-Plane calculates the albedo (day-time) and emissive ("_LIT") components of the panel separately and then combines them with real 3-d lighting.

The good news is that the spot light problem is no longer a problem.  Since the spot lights are 3-d and are applied to these final "panel textures", a mask that matches the background will blend perfectly.

But in order to mask, you need to know which part of the panel texture you are masking (albedo or emissive!).  If you are masking the albedo texture (e.g. a mechanical artificial horizon), create a mask that looks just like the panel background.

But for a glass instrument, the moving parts go into the emissive layer.  Your mask must be pure black!  Where did I get that from?  The emissive layer adds light to the object.  Black is an absence of adding light.  So pure black 'erases' any light-only elements (which include all glass EFIS instruments, etc.).

One nice thing about this strategy: you can build a custom glass instrument (with a black mask) and put it over any background. This means you can reuse your art assets no matter how they are positioned on the panel.

A Modern Cessna

With X-Plane 930 beta 8, we finally integrated the latest version of Max's Cessna 172 SP. Grab the new beta and try it - he's added a number of new features that demonstrate some of the newer X-Plane 9 airplane features.

• Real 3-d lighting in the 3-d cockpit. Note how the map light tends to illuminate only some of the cockpit as it fades out.
• 2-d back-lighting on all of the major steam gauges.
• A bunch of parts can now be dragged in 3-d, including the door handles. This is done via manipulators.
  
• Walls! In 3-d cockpit viewer mode you won't be able to leave the airplane until you actually open the doors. The cockpit viewpoint is constrained.
• The model has the glass parts separated out for correct shadowing, and the glass works correctly from all viewpoints.
• Panel uses cockpit regions for accurate lighting.
  

The cirrus jet has been similarly updated. I plan to use the Cessna for a series of tutorials showing how to use these recent X-Plane features.

DataRefs Vs. Commands I: What's The Difference

What is the difference between a dataref and a command? They serve different purposes in X-Plane, but it's easy to get them confused, especially because the names can look so similar. If you only take one thing away from this comparison, it should be:

• Datarefs are information.
  
• Commands are actions.

Datarefs

A dataref is a single bit of published information. For example, the user's indicated airspeed, as seen by the pilot, is a dataref, stored in:

sim/cockpit2/gauges/indicators/airspeed_kts_pilot

Datarefs have names that do not change. Datarefs made available by X-Plane start with sim/ while datarefs made available by plugins start with another prefix. Datarefs have been in X-Plane since the release of the plugin system in version 6.70.

You can always read a dataref, but sometimes you can change it. Trying to change a dataref usually has one of three actions:

• If the dataref is not writable at all, nothing happens.
  
• If the dataref is writable, it will change.
  
• Sometimes a dataref may be writable, but only after changing some other sim configuration. For example, you can only "write" to the control surface deflection datarefs after setting the control surface override dataref to 1. (If you don't set this override, X-Plane will constantly write its own ideas of the control surface positions to the control surface datarefs and your changes will be lost.)

You can read and write datarefs:

• With the DataRefEditor plugin (if you just need to find some information).
  
• Via generic instruments.
  
• Via OBJ8 animations and manipulators.
  
• Via a plugin via the XPLMDataAccess APIs.
  

Commands

A command is an action that the sim can take on your behalf. For example, the command

sim/autopilot/altitude_arm

arms the autopilot for altitude hold.

Like datarefs, commands have permanent names, starting with sim/ for X-Plane or other prefixes for plugins. Commands have been available in X-Plane since version 9.0.

You can always actuate a command, but there is no guarantee that it will do anything. For example, the engine starter command won't start the engine if the plane has electrical starters and the battery is dead.

You can use commands by:

• Binding them to your joystick and keyboard, in the joystick settings dialog box.
  
• Using a generic trigger instrument.
  
• Using a manipulator in an OBJ.
  
• Using the XPLMUtilties APIs - these are SDK 2.0 features.

Plugins

Plugins can add both new datarefs and new commands to the sim. Plugins can also change the behavior of all built-in sim commands, and can change the information in some datarefs.

Where Do I Find Datarefs And Commands

X-Plane's default commands and datarefs are listed in the text files Commands.txt and Datarefs.txt in the Resources/plugins folder. (Note: providing the command list is new to X-Plane 930.) The dataref list is also available on the X-Plane SDK Wiki.

Up next: when should I use a command and when should I use a dataref?

The Dangers of Wandering in the Desert

I have been trying to put documentation on the X-Plane Wiki, and use this blog for announcements and "the inside story", rather than letting the blog turn into a poor-man's users manual. An aircraft developer asked me via email whether there was a blog entry on some of the pitfalls of the v9 panel lighting system. There is not, and the lighting system is under-documented. I will be working on improving the documents over the next few weeks, but the point of this blog entry is: "how did we get here?"

I am a huge fan of incremental software improvement. That's the subject of another blog post (perhaps on another blog), but for now I'll say this: all changes to the rendering engine since version 8.0 have been incremental ones, and yet if you were to look at the code, you wouldn't see a series of band-aids taped on top of each other. Each incremental change leaves the rendering code "fully updated", as if it had been written yesterday. I start each new scenery feature by first reshaping the existing code into the most useful form for what we want to have in the future, and then coding the new feature is relatively simple.

But this strategy has an Achilles heal; if the code being refactored has a public interface (whether it is a file format or programming API), then all of the intermediate steps in the journey become requirements for future products in order to maintain backward compatibility.

This is not a problem as long as the programmer knows where he is going. The danger comes when one of the intermediate steps is actually a step in the wrong direction, and becomes dead weight around a future design.

A Reasonable Progression: OBJ

The OBJ 800 file format has had a reasonable progression* since its birth in version 8. It has gained a number of new features, but each one has generalized and made more powerful previous ideas, such that "legacy behaviors" are not so painful. Some examples:

• Hard surfaces may now be decks (e.g. you can fly under them) or not, and you can specify what kind of hard surface you have. The original hard surface command was simply "it's hard" or "it's not". But viewed under the lense of the new scenery system, that old hard surface command implicitly implied "the surface is smooth" and "the hard surface is not a deck". So the new hard surface command is a more general version of the old one, which continues to work under the new system.
• Animations in version 9 can be key framed; in version 8 you simply specify start and end values. But start and end values are just like having two key frames. So viewed under the lense of the new scenery system, all animations are key framed; older objects always just have two key frames. The new key framed commands are a more powerful, more general version of the old ones.

I can't say that the relatively pain-free evolution of OBJ files over the last 4 years comes from good design or genius on my part - in truth it's probably just good luck. But I think one thing has helped me keep the new OBJ extensions relatively sane: most of them are conceived several months before they make it into X-Plane.

I have a scenery system to-do list that will last me at least another four years; most of it is filled with things that Sergio has asked for. This to-do list acts as sort of a road map for future scenery system extensions; for any possible OBJ change, I can look at it relative to the other todo items and ask: "is this extension going to play nicely with things to come?"

(As a side note, this is one of the reasons why there are not light maps in any of the X-Plane modeling formats. Light maps don't play well with a number of other scenery system extensions. I want to resolve the conflict between these future additions before they go into the sim.)

Wandering In the Desert

By comparison, the evolution of the panel system in version 9 has been more like wandering in the desert than a straight line toward a goal. Repeatedly, I put features into the panel system without a clear roadmap of where we would end up or how they would work together. The result is what you see now when looking over the panel documents: complexity and chaos.

Basically there are several major changes to the panel system that affect each other in strange ways:

1. A more complex lighting model on the 2-d panel in version 920. (That is, the 3 2-d spot lights, and generic instruments with back-lit, mechanical, or glass lighting.)
2. A more complex lighting model in the 3-d cockpit in version 930. (That is, 3-d spot lights, ATTR_cocpkit_region and generic instruments with back-lit, mechanical, or glass lighting.)
3. A separate panel used only to provide texture to the 3-d cockpit. (That is, the 3-d panel.)
   

The problem is the order that they were invented: first ATTR_cockpit_region, then the 3-d cockpit, then back-lit generic instruments, then 2-d spot lights, and then 3-d spot lights.

The result is two sources of confusion:

• Some combinations of features simply don't work together. Since all of the features appear to be independent, I sometimes get bug reports on these. For example, you can't use the 2-d spot lights on the 3-d panel. This is not a bug, it is by design! I will explain why some of these limits exist in future blog posts.
• Among the remaining combinations that do work together, there are a lot of choices about how to structure a plane - too many choices!

This second point is a tricky one: X-Plane has to continue to support whatever set of features was available for any given release (864, 900, 920, 930) so that older planes continue to work. But some of those combinations (e.g. the ones that exist in version 900) don't make a lot of sense for new planes made in 930.

I am open to ideas on how to solve this. I intend to document a "correct formula" for a modern plane, perhaps with tutorials, on the Wiki. I am also considering programming Plane-Maker to flag unusual combinations of features as a warning when saving 930 planes.

Either way, I fear I've learned my lesson from the panel system: incremental improvement of code is only a good idea if the programmer knows where he is going! Next time I will use Google Maps. :-)

* I suppose that whether you think the OBJ 800's evolution has been reasonable depends on your standards for file formats. OBJ 800 absolutely does show growing pains. I would only say: consider the number of revisions and the change in the hardware platform OBJ 800 feeds when you consider its stretch marks.

Broken Panels

I have found the cause of a rather serious bug in Plane-Maker: sometimes instruments disappear from the hierarchy (but are still visible in the main window).

The problem is that the cut-paste facility, when used with multiple-instrument selections, was corrupting the hierarchy information.  Because of the way instrument hierarchies are managed, this corruption persists - even if it isn't visible.  So if you manage to ungroup everything, it looks okay until you work more, then the instruments disappear again!

This is a really bad bug of mine, particularly since a panel is such a time investment.  Here is what we'll be able to do in 930 to get around this:

1. A new "flatten panel" command simply ungroups everything and completely cleans the hierarchy.  All corruption of hierarchy is fixed with this command, finally exposing every instrument.  From that point on, you can then re-group and things should be okay.
2. I am fixing the cut-paste commands to not trash the hierarchy, and I am looking for any more hierarchy-corruption problems.
3. 930 has export/import of instrument groups to text files.  So another way around instrument corruption problems would be to export the panel to a text file, fix the grouping problems (which is a matter of moving the GROUP/END_GROUP lines) and then re-importing.  If you do not have a selection, the entire panel is exported, including any hidden items in the hierarchy.

I believe that text-based panel import/export will also be useful for sharing individual instruments (or clusters of grouped generic instruments), archiving work, and making large-scale changes using search-and-replace.

Two Squashed Bugs for 930

These two issues have been discussed a lot in the forums, so I thought I'd mention them:

First, I finally found and nuked that star-burst pattern in the rain.  It turns out that for some textures, compression was destroying the lower res mip-maps, causing the geometry that the rain drops are drawn on to show up as that starburst pattern.  It should be fixed for 930 beta 1.

Second, it turns out that the code that converts the 900-format generic instruments to 920-format generic instruments* was being run on the user's airplane whenever a multiplayer airplane older than version 920 was being run.  That could cause generic instruments to disappear, appear incorrectly, or just crash the sim, because the aircraft data in the user's plane (once the user is flying) is already in 920 format...if you interpret it as 900 format again, you get non-sense.  

I am fixing this for 930 beta 1; there may be other bugs relating to multiplayer and generics, so we'll see if this fixes most of the problems, or others crop up.  The panel system is essentially "global" (that is, there is one panel for the user in all of x-plane) but the instrument data is per-plane...so there is always a risk of code mistakes where the multiplayer planes affect the user's panel.

When will 930 beta 1 be out?  I don't know.  Hopefully pretty soon - when bug fixes make it into the blog, we're usually in the push to get to beta.  But I'm working on features on a few fronts, so it's hard to say which ones will be done first.

* X-Plane 920 revised the ACF format from version 900.  The file format for generic instruments was pretty much completely changed to accommodate new features like key frames.  920 has code that converts the 900 generic instruments into 920.  For example, simple key frame tables are built out of the older offset-scale parameters per instrument.

Fixing Panel Editing in AC3D

The X-Plane export plugin for AC3D doesn't handle panel textures very well.  The current plugin tries to identify cases where you have used your panel background as a texture - this queues it to generate ATTR_cockpit.  This scheme has a number of problems:

1. The search paths for the panel background are not up-to-date.  The plugin doesn't know about the new naming conventions or the cockpit_3d folder.
2. The scheme doesn't address panel regions at all - there is some support for them but it doesn't work well.
3. Most important: panel editing is not WYSIWYG.  Since you are using the panel background as your texture, you can't actually see where all the moving parts are!  Doh!

That last point is perhaps the most important one, and it is why, for the next version of the plugin, I am introducing panel previews.

Basically a panel preview is a screenshot of your panel with the instruments on it, sitting in your cockpit_3d/-PANELS- folder.  AC3D will recognize and use the panel preview when possible.  This will solve problems (1) and (3) - there will be only one naming convention for previews, and they will be screenshots of the panel in action, so you can texture with a preview of the instruments.

Plane-Maker 930 will contain a facility to generate panel previews; if you are using X-Plane 920, you can generate the preview manually by taking a screenshot in X-Plane.

For panel regions, we will have one preview file for each region (e.g. Panel_preview0.png, panel_preview1.png).  This addresses issue 2 - usage of the region previews will invoke ATTR_cockpit_region.

Finally,  I am moving the panel sub-region information from the preferences to the .ac file (hopefully) so that it will be saved with your plane.

Hopefully this will make a work-flow which is much simpler.  To make a 3-d cockpit you will simply pick "generate previews" in Plane-Maker, and then start using the previews as textures.

The "Airplane Modeling" Datarefs

I have blogged about this before, but I will try to create one simple explanation of what's going on with sim/cockpit2 and sim/flightmodel2 datarefs.

Sandy and I (with the help of others who helped compile the list) created "new" datarefs (first released with X-Plane 9) , aimed at airplane modelers. These new sections are:

1. sim/cockpit2/ which provides a new set of datarefs for cockpit modeling via OBJ animation and generic instruments.
2. sim/flightmodel2/ which provides a new set of datarefs for airplane exterior modeling via OBJ animation.

These datarefs sometimes include new data that was not available in version 8, and sometimes they simply provide a second dataref with the same information. Why duplicate datarefs? The new datarefs have some special properties, so I wanted to have a complete set of datarefs for modelers with these new properties.

Skip to the end for the rules of thumb on how to use them.

Clean Naming

The new datarefs are designed to have longer, less confusing names; the old datarefs contained a lot of abbreviations - potentially acceptable for programmers (who are used to seeing things like fstat and chgrp on a regular basis) but not good for modelers who do not speek English as a first language. The new datarefs have long names and are more consistent in their conventions. They also contain complete documentation.

Array Sizes

You will see the array dimension of some of the new datarefs as symbolic constants, e.g. [engine] instead of [8]. This is because the dataref generation system we use knows that these new datarefs sometimes track the maximum number of parts in the aircraft structure. This tagging means that it is much simpler for Sandy and I to adjust the datarefs when Austin increases part maximums.

With the old datarefs, if Austin allows for 10 engines, Sandy and I must search for every [8] dataref and decide if it must be [10] - some will be per-engine and need to change, some will be per-battery and will not! With the new system, we simply redefine the "engine" constant to 10 and the datarefs adjust.

(Note that if your plugin really needs to run dynamically with any number of engines, the best thing to do is to read the array size using XPLMGetDatavX.)

Failure Support

There are two ways to view a dataref: before system failures (such that the dataref reflects simulated physical reality) and after system failures (such that the dataref reflects pilot indications). For example, when the pitot tube ices up, the pre-failure airspeed reflects how fast you are flying; the post-failure airspeed reflects how much crud is in your pitot tube.

Pre-failure datarefs are appropriate for animating the exterior of the airplane. For example, if the gear indicator light fails but the gear is working, you want to animate your landing gear based on the real (pre-failure) gear position, so that the gear really does look like it's down from an outside view.

Post-failure datarefs are appropriate for animating the cockpit. For example, you want to use that post-failure indicated airspeed for your air speed indicator, so that pitot ice will affect your generic instruments and animations, as well as the built-in instruments.

The new datarefs are designed to clearly provide two different views:

• sim/cockpit2/ are all post-failure whenever possible, and are thus appropriate for cockpit modeling.
• sim/flightmodel2/ are all pre-failure, and thus are appropriate for external airplane modeling.

Be careful not to swap them! You should always be using sim/flightmodel2/ for your aircraft and sim/cockpit2/ for your cockpit. If the dataref you need is in one and not the other, email me and I will add it to the right place.

Correct Multiplayer Behavior

The older datarefs all return data about the user's airplane. However if you build an object, attached to an ACF, and that ACF is loaded for a multiplayer plane, you will get incorrect results -- the user will see his own plane's actions visualized on the multiplayer plane.

The new sim/cockpit2/ and sim/flightmodel2/ datarefs handle this case correctly: they return data about whichever airplane is being drawn. Thus if your object is attached to airplane number 5 in a multiplayer session, that's the airplane that will animate your control surfaces.

(Plugin developers - outside airplane drawing, these datarefs return information about the user's flight.)

For this reason, you should always use sim/cockpit2/ and sim/flightmodel2/ - not the older sim/cockpit and sim/flightmodel/ datarefs. If the dataref you want is only in the old sections but not the new ones, email me!

What Dataref Do I Use?

Here's the rule of thumb:

• If you are targeting X-Plane 6/7/8, you must use sim/cockpit and sim/flightmodel, otherwise
• If you are targeting X-Plane 9, use sim/cockpit2 for your generic instruments and 3-d cockpit. Use sim/flightmodel2 for your attached objects.

That's all there is to it!

ATTR_cockpit_region - Are We Confused Yet?

The choice of panels (2-d panel vs. 3-d panel) for your cockpit and the choice of OBJ commands (ATTR_cockpit vs. ATTR_cockpit_region) both affect how your 3-d cockpit looks.  Since these two techniques can both be varied, there are a lot of combinations, and 920RC2 does not have the right behavior.  (RC3 will fix this I think.)

2-d vs. 3-d Panel

The 3-d panel is a new flat panel whose purpose is to provide the image for ATTR_cockpit or ATTR_cockpit region.  Building a new panel for 3-d has a few advantages:

• The instruments can be packed together - no need for windows or other texture-wasting elements.  This can help reduce panel size -- panel size is expensive when using ATTR_cockpit_texture.
• The 3-d panel can be smaller than the 2-d panel; having a huge panel feed the 3-d object is slow.
• Instruments that are drawn with perspective in the 2-d panel can be redrawn orthographically, which is more useful for texturing real 3-d overhead panels.

Because the 3-d panel is meant only to be used as part of a 3-d cockpit object, spot lights and flood lights are not available, nor is a night-lit alternative.  Why not?

• Such customized 2-d lighting would not match the rest of the 3-d cockpit visually.
• We will eventually have a more global lighting solution.

Basically I don't want to provide features that will clash with the future implementation and eat framerate!  The 3-d panel is aimed at next-generation content.

ATTR_cockpit vs. ATTR_cockpit_region

ATTR_cockpit_region provides a new alternate panel texturing path that gets rid of legacy behavior for improved performance and image quality.

• ATTR_cockpit_region requires the region be a power of 2, which saves VRAM.  (If your panel is 1280x1024, then ATTR_cockpit rounds it to 2048x1024.  Yuck!)
• ATTR_cockpit_region grabs the lit and unlit elements of the panel separately, and can thus provide lighting that is consistent with the rest of OBJ.
• ATTR_cockpit_region does not preserve transparency (which isn't a good way to model a 3-d cockpit performance wise) - removing the alpha feature improves framerate and saves VRAM.
• ATTR_cockpit_region lets you pick out parts of a panel to texture only what you need.

This last point is less important now that we have 3-d panels (ATTR_cockpit_region came first) - it was meant to let you pick out a small subset of a large size 2-d panel, skipping windows.  But if, for example, you need more than 1024x1024 pixels of panel texture, two cockpit regions are better than one 2048x1024 - some graphics cards hit a performance cliff when a cockpit or region exceeds 1024x1024.

Expected Behaviors:

(Under all situations, the instrument brightness rheostats should be preserved correctly.)

ATTR_cockpit + 2-d panel:

• The 3-d cockpit should look exactly like the 2-d cockpit.
  
• The 2-d panel is used as source.
  
• Panel transparency is preserved.
  
• Spot/flood lighting effects are available and work.
  
• Flood color is the forward flood color.
• The panel texture and object texture may not look the same under some lighting conditions.

ATTR_cockpit + 3-d panel:

• The 3-d panel is used as source.
  
• Transparency is preserved.
  
• Spot lights are not available, but flood flights work.
  
• Flood color is the side flood color.
• The panel texture and object texture may not look the same under some lighting conditions.

ATTR_cockpit_region + 2-d panel:

• The 2-d panel is used as source.
  
• Transparency is not available.
  
• Spot and flood lights are not available.
• Panel and object texture colors should match under all lighting conditions.

ATTR_cockpit_region + 3-d panel:

• The 3-d panel is used as source.
  
• Transparency is not available.
  
• Spot and flood lights are not available.
  
• Panel and object texture colors should match under all lighting conditions.

The Future

Basically both the 3-d panel and ATTR_cockpit_region are aimed at next-generation cockpits - they both strip legacy features to provide a clean platform for real 3-d cockpits.  The expectation is:

• Global lighting will be applied to all 3-d geometry - panel texture and object texture. Non-emissive lighting (spot lights, flood lights) will apply to everything.
• Windows will be built using geometry, not alpha.
• The panel texture can be minimized by packing a 3-d panel and using regions.  Manipulators let you provide interaction to regular object geometry.

Why Don't Skewed Instruments Skew the Background?

With X-Plane 9.20 you can stretch the shape of generic instruments, to create instruments that appear to be in perspective.  But why does this effect apply only to the overlays and not the burned-in backgrounds?  Two reasons:

1. Some planes are made by cutting out photographs of real cockpits.  So the source imagery may already be distorted.  The current feature distorts only the moving parts that have to be dynamically distorted, but lets you use pre-distorted imagery from a photo.
2. Our distortion might not be as nice as what can be done with high-end image editors like PhotoShop.  By pre-distorting the image you can get the best image quality.

And of course, the implicit reason 3 is that I'm lazy. ;-)

Airplanes - How it Fits Together

Here's a summary of the new airplane features in 9.0 (and some coming). Hopefully this will give you an idea of what new capabilities are available for modeling planes in X-Plane 9. This list will sound like a broken record - virtually all of these features are optional; you don't have to recut your finished airplanes to use them in version 9.

2-d vs. 3-d Panel

You may have noticed the new "3-d panel" option in PlaneMaker 9. This allows you to build a separate panel for the purpose of providing the texture to ATTR_cockpit (or ATTR_cockpit_region). You can then:

• Provide alternate instrument artwork in a cockpit_3d folder. (This lets you have perspective artwork for the 2-d cockpit and orthogonal artwork for the 3-d cockpit.)
• Pack your instruments together tightly to save space. (There is a real cost to large panels, so using a 1024x1024 panel for the cockpit object is a lot better.)

The 3-d panel is strictly optional, fully replaces the 2-d panel only for cockpit objects, and is activated by providing a custom panel background in a cockpit_3d folder. (See the "Example Plane-Widescreen+objects" plane in beta 19.)

ATTR_cockpit_region

Cockpit regions are an alternative to using the entire 2-d panel to texture your objects. They provide a few advantages:

• Performance. By requiring a power of 2 and allowing you to use a sub-area of the panel, cockpit regions avoid a lot of wasted computing that ATTR_cockpit can cause.
• Next-gen lighting. Unlike ATTR_cockpit, real 3-d lighting is applied to the panel when you use this attribute. This means that you will get a gradual decrease in light on your geometry (correct based on the angle of the sun) that matches the rest of the object.

Please note that you can mix and match which way you get your cockpit texture and whether you use the 2-d or 3-d panel feature (above) independently. However, you can only use ATTR_cockit or ATTR_cockpit_region in your airplane, not boht. ATTR_cockpit is still supported.

Generic Instruments

Generic instruments let you build instruments that follow some basic shapes (needles, tapes, etc.) that can be tied to any dataref. This both lets you customize particular instruments very precisely or create an instrument driven by a plugin dataref. These instruments are optional in version 9 - the old "premade" instruments are still supported.

New Datarefs

X-Plane 9 provides new datarefs targeted at airplane authors. The datarefs are better organized and have clearer names. But the old datarefs still exist, so legacy planes do not have to be updated.

Generally the entire cockpit should use only sim/cockpit2/ datarefs, and the plane exterior should use only sim/flightmodel2/ datarefs.

One special feature of these two sections: if your plane is used as an AI plane, these datarefs will animate the plane with the AI plane's control deflections, not the user's control deflections. So using these datarefs fixes the "AI animation" problem.

Plugins in Aircraft Folder

Version 9 airplanes may have a plugins folder (inside the ACF package) with fat plugins inside them. If you develop a plugin for your airplane, consider packaging it this way -- this will allow your users to install the airplane with a single unzip for all platforms and no extra "drag-this-file-here".

Plugins in the airplane folder is optional - you don't have to provide a plugin, and plugins that are installed in the main Resources/plugins folder will still work. Still, I encourage you to use this feature because it makes the install process a lot simpler. The X-Plane SDK website will have documentation on fat plugins.

Liveries Folder

X-Plane 9 features a new "liveries" folder. Liveries (replacement exterior paint for airplanes and their attached objects) can be placed in packages in the liveries folder to greatly simplify the process of repainting an aircraft. See the "Example Plane-Widescreen+Objects" for an example.

While the liveries feature is optional, I strongly encourage anyone doing repaints to adopt it. Liveries can be switched by the user in the sim without any file manipulation; there is thus no risk of accidentally deleting or breaking an aircraft.

Large 2-d Panels

In X-Plane 9, a panel can be up to 2048x2048 in size. You pick the dimensions. The panel will scroll horizontally if necessary.

Note that if you use the new 3-d panel feature, the 2-d and 3-d panel do not have to be the same size. I would recommend a large 2-d panel (to fill large monitors) and a smaller 1024x1024 3-d panel (for performance).

Hiding Parts

X-Plane 9 will allow you to hide aircraft parts. Many v8 planes use OBJs to model the plane geometry, and use a transparent ACF texture to hide the ACF. Setting the parts to "not drawn" saves the CPU time that X-Plane would spend drawing the airplane, and is thus more efficient.

Keyframes

X-Plane 9 supports key-framed animation; this is useful for the scenery system, but for airplanes it allows for much more complex and realistic animation. OBJs that don't have key frames still work.

Manipulators

This is a feature coming in the future: the ability to control how the user clicks and interacts with the cockpit object in detail. In X-Plane 9.0 we only support clicking on cockpit-textured geometry; manipulators will make features like draggable handles a lot more workable.

Global Illumination

X-Plane 9 does not yet offer a lot of control of the in-cockpit lighting environment; we'll be working on this in future versions. These features will be opt-in...that is, you'll have to change your model to get the new features, and old planes will work the way they always used to. It is likely that you'll have to use "modern" airplane-building techniques to use these new features (meaning OBJs, named or custom lights, lego brick instruments ,etc.).

When Can You Not Use DDS?

There are a few cases where you cannot use DDS files in X-Plane:

1. Airplane 2-d panels (any layer - base, lit, -1 shadow layer, 2-d or 3-d).
2. Airplane instrument images.
   
3. Bitmap-based region specification referenced in a library.txt file.
4. Any gray-scale/alpha-only texture (e.g. mask files in the scenery system).
   

Beta 17 is treating cases 1 & 2 as an error; beta 18 will simply stop looking for DDS files in those cases.

Please note that airplane panels and instruments are not compressed right now, so there would be no performance benefit to using DDS in these cases. (If anything, PNG has smaller file size when compression is not used.) If we ever allow compressed panel textures, we'll probably allow DDS panels at the same time.

Case 3 is just a particular version of case 4 - that is, the region bitmap is black and white (1 channel) so DDS provides no benefit. Use a gray-scale no-alpha PNG!

It's Time to Try Nine

If you create plugins, airplanes, or scenery for X-Plane and haven't tried your add-ons with X-Plane, please do so soon!! It's much easier for us to fix backward-compatibility problems while we're still in beta. Beta 14 introduced some bugs (that should be fixed in beta 15 real soon) but I think we're reaching the point where you can do compatibility testing.

We're working on a public Linux beta - see here.