I want to revisit the question of whether (and how) the livery system should be extended. In particular, it is my opinion that the livery system should not be extended to allow:
- Replacement of OBJs used for modeling the airplane or cockpit.
- Alternate or modified ACFs*.
- Generally, the livery system shouldn’t be used for changing the plane’s behavior – it’s just paint!
I have commented previously in three parts that the livery system is meant to make easy the integration of third party paint without (a) violating copyright, (b) requiring byzantine installation instructions or (c) requiring the painter and original author to coordinate. I have received requests from a number of very talented airplane authors, asking for the livery system to cover a whole range of new features, most of them involving configuration. I will try to explain in this post how I think should should be handled.
First, to be clear: an aircraft file is the .acf file that contains the X-Plane specific data needed to simulate the plane; the aircraft package is the folder containing that .acf file. A livery is a painting scheme for the 3-d model of the airplane, and a configuration is an instance of a plane with certain features, e.g. with or without G1000, with P&W; vs. Rolls Royce engines, etc.
Configurations of an aircraft should be created by putting more than one aircraft file
(.acf) in a single aircraft package. Because the graphic and sound resources needed for the aircraft are accessed relative to the .acf file, you can build a family of aircraft with some common aspects and some unique aspects to each plane.
Files used by an aircraft fall into three broad categories:
- Files found by a fixed formula using the .acf name, e.g. be20_paint.png. Let’s call these “file-specific”.
- Files found by a fixed formula without using the .acf name, e.g. the contents of the aircraft plugins folder. Let’s call these “package specific”.
- Files that are explicitly named in the .acf file, like airfoils and OBJs. Let’s call these “flexible” (since this naming scheme could be used in any way).
Here’s how the important files in an aircraft break down:
- The aircraft paint scheme is file specific.
- The aircraft panel background is package specific (but you can effectively have each file use a different panel background by setting the panel type differently for each plane).
- Sounds are actually either, which effectively makes them flexible. Non-generic instruments are package-specific.
- Objects, generic instruments and airfoils are flexible.
In other words, if you can live with duplicating your aircraft paint files (and I suspect that in most cases either the plane is built by objects, or the modifications in each configuration warrant paint changes anyway), then every other feature can be set to package or file specific, allowing you to build a group of aircraft around a single real-world plane.
Now if there are aspects of a multi-configuration aircraft package that don’t work right now, we can look at possible changes to the sim to make this work. But it appears to me that just about everything necessary to make multiple configurations is already available in the sim now.
As a final note, the question here (livery vs. multi-file aircraft pack for configurations) is one of file formats, and thus of data organization and contracts between authors and programmers. It is not a question of user interface. The user interface can be reshaped to make multi-aircraft packages look like liveries, or liveries look like multi-aircraft packages. But I suspect that most of the interest in extended liveries is on the file-format side.
* The one exception for liveries is the tail number — given the strange state where the tail number, as painted into the livery, is also written into the ACF, it wouldn’t be bad to be able to override this property. Some people are already doing this using plugins.
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.
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:
- 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.
- 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. 😉
Posted in Panels
by
Ben Supnik |
I don’t usually blog about plugin issues, but this one falls into limbo, somewhere between plugins, aircraft design and OBJ animation. This is written for plugin developers; if you don’t write plugins, you can tune out.
Plugin Drawing
Plugin drawing is documented in a few tech notes – I strongly recommend reading them all.
The basic idea is this: to draw in a plugin, you register a callback. X-Plane tells you “it’s time to draw” and you draw.
The first rule of drawing callbacks is: you only draw. You don’t do anything else.
The second rule of drawing callbacks is: you only draw. You don’t do anything else.
There are a number of good reasons for this.
- You don’t know how many times, or in what order the callbacks will be called! You might be called four times per frame or none. So doing flight model calculations in a draw callback is a bad idea.
- Drawing has to be fast. In the drawing code we are trying to stuff the GPU to the gills with work to do. Drawing time is not a good time to go off and do other expensive calculations.When we look at the interaction of the CPU and GPU, we know that the flight model takes some pure CPU time, and we can improve efficiency by queuing an expensive OpenGL operation before we hit that CPU-only phase. If your plugin is doing its real calculations during draw time, our pipelining gets thrown off.
- We’re continually increasing the parallelism of the sim via threads to take advantage of multiple cores. But plugins are single threaded by definition. This means that plugin interaction points will (in the future sim) halt parallel operation and slow overall performance. When we design parallel operation, we can try to optimize our design to avoid this “halt” case, but if you are doing something strange (like flight calculations in a draw loop) you’re more likely to fall off the “fast path”.
Surprise
Now here’s the surprising thing: your dataref callback is actually a drawing callback, sort of!
Object datarefs are called back during object drawing. Therefore they have all of the above problems that drawing callbacks have. Here is my recommendation:
If you create a custom dataref that is used by an OBJ for animation, return a cached value from a variable in the dataref, and update that variable from the flight loop.
This avoids the risk of your “systems modeling” code being called more than once per frame, etc.
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 in the past about the difference between key frames to animate changes to a dataref and key frames to animate an event. Simply put, key frames let you relate the position of your mesh to a dataref value, but they do not let you start a sequence of animations based on a change to a dataref.
In other words, you can make an aniamtion that puts the gear handle up when the gear dataref is 0 and down when the dataref is 1. If that dataref were ever 0.5 you’ d see something in the middle. (This dataref will always be 0 or 1 though.)
But you can’t use animation to make the handle slowly move from up to down over a few seconds when the dataref instantly jumps from 0 to 1. If the dataref moves instantly, so does your animation. There can be no time delay between the dataref and animation.
To get this “triggered sequence” effect, you need something else to detect the event and create a dataref that moves slowly. That something could be a plugin; X-Plane also provides a built-in mechanism: the “misc. slider”.
In an attempt to put the information somewhere useful, I have described the feature on the X-Plane wiki.
No Spare Datarefs (Usually)
In that last blog post I went on a rant about “spare” datarefs. Basically people would ask us to make some datarefs that did absolutely nothing, simply to wire parts of their panels and animations together.
And while I’m going off on a tangent about authoring and datarefs, we will not be adding any “spare” datarefs.
Well, the slider_on and slider_ratio datarefs are sort of “spare” datarefs – they’re 24 slots that have no default function.
I relented on my usual hard-line position on this (and a few other) datarefs for two reasons:
- These datarefs are tied to a real (albeit really simple) bit of simulation code – that is, the code that moves the sliders over time. We had to add these datarefs to make the slider mechanism accessible.
- Because sliders are an airplane feature, there is a logical scope: the person who writes the airplane gets to decide what the sliders do, and no one else gets to muck with them. (Since the cycle time is an aircraft file attribute, no one else could sanely hope to utilize them.)
I still maintain my original position that if you need a dataref that doesn’t exist at all, you should use a plugin to create it.
Someone in the X-Plane community can write a (really simple) open-source plugin whose sole purpose is to create trivial datarefs for aircraft use from a text configuration file, letting aircraft authors make as many datarefs as they need. (It is possible that this plugin exists and I just don’t know about it.)
Aircraft authors: to make sure that datarefs from differing add-ons do not have name conflicts, Sandy and I established a registry of plugin dataref prefixes. If you are going to add custom datarefs to your airplane, be sure to register a prefix, and only use that prefix. Do not start your datarefs with sim/XXX – that prefix is for X-Plane’s use only.
(Side note: the X-Plane SDK website has been under some kind of automated attack for the last week or so with lots of bogus user sign-ups. I haven’t had time to address this properly; if you are not registered on the SDK Wiki, I may not be able to approve new sign-ups for a few more days.)
I am in Boston visiting family for the 4th of July, so there are a few compatibility bugs that I have seen but probably won’t be able to fix for a few days. Austin is still cranking out betas. So if new betas come out and these are not fixed, don’t panic – they are definitely on my todo list.
- Sceneries converted via FS2XPlane crash on load. It looks like this is due to a bug in the new threaded texture loader – I think you can work around this by turning off “load scenery in the background” in the rendering settings (but then loads will be slow). I have found the area where the bug occurs but haven’t isolated it.
- A user submitted a plane to us that crashes Plane-Maker on open – the panel code gets confused. I haven’t isolated it yet. If you have planes you’ve made, save the pre-920 versions!
- I think Benedikt’s x737 plugin should start working again in beta 2.
X-Plane 920 will have a pile of new panel features…this video shows the new “spot light” system. Basically you can define up to 3 gray-scale masks that define lit regions on your panel. 3 separate rheostats control the lighting levels independently.
//www.youtube.com/get_player
I was excited when Blogger got its own video facility – saves me the hassle of keeping YouTube account active. Unfortunately the video quality is, well, “web-ish” at best. What you’re supposed to see is independent control of instrument lighting, panel and dash lighting, and flood lighting.
The performance hit is pretty tame:
- The system works by recomputing the panel texture from sources when lighting or panel brightness conditions change. That doesn’t happen that often, so most of the time, the system costs nothing.
- Panel layers are RLE compressed in RAM when not in use, so they aren’t that big.
- If you have more than one core, the lighting recompute happens on the second core, which makes it virtually unnoticeable.
So the only case you’d notice this is if you crank the panel light rheostat really fast or fast-foward time (from light to dark) on a single-core machine.
