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:
- sim/cockpit2/ which provides a new set of datarefs for cockpit modeling via OBJ animation and generic instruments.
- 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!
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 1280×1024, then ATTR_cockpit rounds it to 2048×1024. 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 1024×1024 pixels of panel texture, two cockpit regions are better than one 2048×1024 – some graphics cards hit a performance cliff when a cockpit or region exceeds 1024×1024.
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.
I’m back from vacation and trying to catch up on email and close out 920. I’ve received a number of emails regarding the 3-d cockpit, the big questions being:
- What can I do about the lousy lighting for 3-d object textures and 3-d panel textures via ATTR_cockpit_region?
- Can I use the new 2-d panel spot lights in the 3-d cockpit?
The answer is unfortunately “not much for now” and “no”. Let me explain what’s going on with the 3-d cockpit and what we’re thinking for a long term strategy.
First, I try to organize my feature work around one part of the sim for each patch. 920 is a bit too big of a patch for us (featuring both a lot of cockpit/instrument work and some big rendering engine changes). Austin has been on the road a lot this year, and in his absence I went a little nutty. I wanted to do some work on the 3-d cockpit, but it’s different code, and with 920 in beta so long, this work will have to wait.
3-d Lighting
Our long term approach to the 3-d cockpit is “real 3-d lighting”. By that I mean: multiple light sources, acting on all of the cockpit geometry based on 3-d positioning. This means a few things:
- Providing some way to specify multiple light sources inside the cockpit, as well as how they are controlled (e.g. how do you dim the flood light)?
- Specifying which attached objects are considered part of the interior of the plane vs. the exterior.
- Providing a way to provide emissive lighting vs. elements that must be lit by light sources.
The 3-d cockpit lighting environment must work the same for the panel texture and object textures. This is necessary to keep the brightness of the finished cockpit consistent between the two textures sources. With the current 3-d system (e.g. what you can do in 864) often the brightness of the panel texture and the rest of the object don’t match.
To this end, ATTR_cockpit_region, which is targeted at the new system, gives you the same lighting model for the object texture and panel texture. Now that model isn’t very useful right now, but it will get better with future patches, and it will always be consistent.
Why Not 2-D Panel Lighting
We can’t use the new 2-d panel lighting features (spot lights), etc. because they are not scalable. Most of the advanced 3-d cockpits I have looked at use a lot of textures, quite possibly several 1024×1024 object textures, as well as a panel texture.
Now the panel texture is very expensive, so there is a penalty for letting it be any bigger than necessary. Given this, we’d only have two options:
- Provide the 2-d spot light features on the OBJ textures, effectively making them dynamic. This would be very expensive, performance-wise.
- Have authors only use one huge panel texture. This would limit them to 2048×2048 and be really slow.
If we don’t provide the spot lighting features for all panel textures then we have the problem of inconsistent lighting, which makes the feature fairly useless.
So instead I have withheld spot lighting (and _LIT replacement textures) from the 3-d panel; the cockpit object will instead end up featuring real 3-d light sources to create these kinds of effects in a 3-d correct manner.
The idea here is to avoid providing features that will be unnecessary, inferior, slow, or unsupportable in the future. Otherwise such a “stop-gap” measure would just end up breaking existing airplanes.
So for now, the 864 system for 3-d cockpits still works as it always did. It will be at least one more patch before 3-d cockpits get a serious upgrade.
For X-Plane 920, I modified the HUD code to draw the HUD into the 3-d cockpit’s panel texture. This turned out not to be such a good idea. The problem is one of opting in: if we change the behavior of the sim without authors being able to “opt in” to that new behavior, we break old planes.
The first plane we’ve seen with this problem is the F-22. The F-22 uses a 3-d object for the cockpit all the time (even in 2-d), and uses the 2-d panel simply for texturing. (In this sense, the F-22 is ahead of its time – this structure gives some of the advantages of the new 3-d panel texture).
The problem is that the F-22 uses the panel texture to map the 2-d HUD to the 3-d HUD, with the expectation that only the HUD background (and not the writing) will appear. The sim then draws the HUD on top. When we start burning the HUD into the panel texture, we get two HUDs.
To fix this, we won’t draw the HUD to the panel texture if you have a real 3-d cockpit object. This change will go into beta six or seven.
I may eliminate the HUD on the default 777 as well…the problems with this feature are numerous:
- As discussed above, for any plane with an existing 3-d object, adding the HUD is more likely to break the plane than add value..authors could not plan for this.
- For a plane with no cockpit object like the 777 the HUD may not be very well aligned with anything – it’s just a 2-d drawing.
- Even if the HUD texture is useful, because the HUD is drawn to a texture, the result is blurry and unfocused due to texture filtering.
In other words, even for new authors I don’t think that drawing the HUD to a texture is a good way to make a HUD.
I’ve blogged about this before, but…let me be totally clear:
Don’t use ATTR_cockpit in objects that are not one of the two cockpit objects for your airplane.
Don’t use ATTR_cockpit in the attached misc. objects for your plane – move the parts of the mesh that require ATTR_cockpit into the cockpit object.
Don’t use ATTR_cockpit in scenery objects.
The
OBJ spec basically says as much when it says “don’t use cockpit features” outside of cockpits.
Now what goes wrong if you violate this varies with the betas vs. X-Plane 8, but I can tell you this: no version of X-Plane has ever shipped that will correctly handle ATTR_cockpit in attached objects for all cases. There’s always been bugs in this not-such-a-good-idea code path; it’s just the severity has varied over time.
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 1024×1024 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 2048×2048 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 1024×1024 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.).
In X-Plane 9 betas 2, you can use the livery system to provide alternate textures for misc objects attached to your plane, but not the cockpit objects. Beta 3 will address this, allowing cockpit objects to reference the livery system too. We’ll get some examples posted for how this all works soon.
Austin and I were discussing this last night – here’s a few thoughts on the difference between the misc. objects and the cockpit object:
- Because you can have multiple misc. objects, you can effectively use more than one texture for your airplane. These days plane designers want a lot more than one texture.
- We’re working on optimizations for attached objects – basically by breaking your plane carefully into a few objects, you may be able to optimize frame-rate. A lot of this code is not in the sim yet, but will go into a later beta.
- Using multiple objects with different LODs is a much more efficient way to improve fps than simply having multiple LODs of the entire plane.
For example, make an interior object with a low LOD (0-500 meters) and an interior texture. Attach it. Then make an exterior object with an exterior texture and a longer LOD (0-50000 meters). When you back away from the plane, X-Plane can entirely skip the interior object, which means that neither the geometry nor texture have to be moved to VRAM. That’s a big performance win.
The cockpit object is also different:
- The cockpit object induces the sim to make a texture out of the 2-d panel. (And it is the only object where the panel texture is legal.)
- Mouse-click analysis is only done on the cockpit object. If you load up the cockpit object with all of the animation for your landing gear, X-Plane has to wade through all of that animation to update the mouse cursor in the 3-d cockpit.
- The cockpit object can be swapped for an alternate object in the exterior view (we’ll provide more control of this for misc objects soon).
So my general advice is: use the cockpit object only for the real panel itself!
However, we have provided livery support. You can’t livery the 2-d panel, and the livery system is not meant to reskin cockpits, but there are probably some planes out there that used the cockpit objet to model exterior plane features (from before we had misc objects). The livery system in beta 4 will let you reskin these planes without changing how your obects work.
Panels and airplanes aren’t really my thing. But we’re using the OBJ engine more and more in aircraft, blurring the lines between scenery code and aircraft code.
In X-Plane you can actually use the panel texture in any object. Pleaes don’t do this! There are two cases:
Airplane Objects
With X-Plane 860 you can attach many objects to an aircraft. But…you should only use the panel texture in the cockpit object.
The cockpit object is special! It is the only object that gets mouse-click tested. In the future we will decide how much of the 2-d panel to render to a texure (for the 3-d cockpit) based on the cockpit object. So…don’t use the panel texture in your other aircraft objects. Put your panel-textured triangles in the panel object.
(You should do this anyway; switching to the panel texture creates a new batch*, so using it in a lot of separate objects is bad for framerate.)
Scenery Objects
Technically you can also use the panel texture in scenery objects. This is really just a big hack — all of the issues with optimzation apply to this case, plus: how can you even know the layout of the panel texture in scenery? Don’t do this!
* “Batch” is the technical term in the game development and authoring world for a set of triangles that can be drawn by the graphics card via single CPU command. While graphics cards can process tons and tons of triangles, the number of batches they can process is limited by CPU and bus speed, which advance much more slowly. Generally the number of batches is the limiting factor in X-Plane’s framerate.
It’s easy to see how many batches your OBJ8 contains: open the file and count the number of “TRIS” and “LINES” commands at the end. Ignoring lights, the sum of the TRIS and LINES commands is the number of batches! (HINT: fewer is better, and only one batch is great!)
