There is a lot of overlap between the datarefs and commands; very often there is both a dataref (telling information about some part of the sim) and a command (which takes action to change some part of the sim). Which should you use?
Here are some general guidelines:
- If you want to set up a joystick or keyboard, you have to use a command. The joystick and keyboard configuration dialog box lets you associate actions with a keystroke or button press, not information!
- If you need to show the status of a system (E.g. “is the landing gear down”) use a dataref. I will cover this issue in more detail in part 3, but basically only datarefs show you information.
The ambiguous case is whether to use a dataref write or a command to change a system when both exist.
- If there is a command that exactly does what you want to do, prefer the command over the dataref. For example, it is better to arm the autopilot using the commands than the datarefs. Changing the autopilot state often involves changing a lot of variables at once in complex ways. When you issue the command, that work is done for you, correctly, every time.
- If the command is not really suitable for your purpose, use a dataref. For example, to change the engine throttle position, do not use the command
sim/engines/throttle_up to move it up “a little bit.” Use the dataref sim/cockpit2/engine/actuators/throttle_ratio to set the throttle to the precise position you want. The throttle-up command exists so that users with no joystick or mouse wheel can fly with the keyboard by pressing the F1-F2 keys (bound to throttle-up, throttle-down). It is not meant to precisely control the throttle position!
(I will discuss why there are so much overlap between commands and datarefs in part 4.)
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:
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:
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?
On the menu this morning: first a whiny rant, then a nerdy one.
Someone pointed me at this post. Before I go into my geeky diatribe about leveraging code, a quick note: it is true that at this point Austin is working heavily on the iPhone – probably more on the iPhone than the desktop. It is also true (but not mentioned) that Laminar is investing more man power into X-Plane for the desktop now than it ever has in the past. (With the iPhone we’ve grown our workload with a second “front” for products, but we’ve increased staffing a little bit too.)
It is also true that X-Plane 9 free updates have been less frequent. This doesn’t mean there’s less code going into them – it just means that we’re doing 4-5 months of coding and 3 months of beta instead of 2 months of codindg and 1 month of beta. I’m not sure if this is better or why it is happening (each release has to be individually planned for the circumstances) but one observation:
Given how many video cards and drivers are out there and how they react differently to the X-Plane code, I wouldn’t want a beta process less than 2-3 months, because I want to know that it’s had time to run on a wide variety of hardware. If our beta has to be at least 2-3 months, then a 3-month release cycle would have us in beta all the time!
My whiny rant (the short version) is this: Laminar Research isn’t in a position (as a company selling a product) to post all of the details of how our business operates internally. So posts that say “Laminar should do X” (where X is a business decision) drive me a bit nuts, because I can’t post a reasonable reply.
Now here’s my real point: development for the desktop and the iPhone are not a zero sum game. Clearly we leveraged the desktop sim to create the iPhone app. But it goes both ways; work on the iPhone also benefits the desktop.
Here is one example: when beta 8 comes out, Plane-Maker’s “export to object” will a much more complete OBJ, in OBJ8 format, with animations already in place for things like wing controls surfaces!
That’s a feature that people have been asking about for a while – both to make CSL objects* and as a way to save time when moving from a Plane-Maker drawn plane toa custom one. (You would first export an animated OBJ8, then start adding details in a 3-d modeling program. With beta 8, you won’t have to rebuild your control surfaces from scratch.)
But…it’s also a feature that is critical to the iPhone! The iPhone version of X-Plane uses animated OBJ8 files as well; this feature helped us internally to prepare planes for the iPhone version, but it’s also a requested feature from our authors.
So my response to those who say that the iPhone has taken away from X-Plane development is that it is not true – not only because we are developing more heavily for the desktop, but because sometimes iPhone development is for the desktop.
* I do not remember whether the current compiled versions of libXplaneMP use OBJ7 or OBJ8 objects. Since libXplaneMP uses the OBJ code from XPTools, it should be (relatively) straight forward to update libXplaneMP and the clients that use it to use OBJ8 directly. In the meantime, you can use ObjConverter to convert an exported OBJ8 back to OBJ7 for CSL use.
I’ve been hacking at the scenery tools over the last few days…and I think we’re making some progress. I mention this because it can be hard to see the work getting done – there is nothing for months, then a new version of a tool. (Well, now you can watch the code change as it happens. If you don’t think this like watching paint dry, you might be a geek!) I also mention it because two of the biggest improvements aren’t my own – they’re insanely helpful user contributions.
The AC3D Plugin
Version 3.2 is now in beta. Version 3.2 catches the plugin up with all of the latest OBJ tricks, including dataref-controlled LIT levels, manipulators, hard surfaces, etc. This might be more useful for airplane modelers than scenery modelers, but I think the variable _LIT channels can be used for some interesting scenery effects too.
WorldEditor
WED 1.1 will go beta once X-Plane 930 is out of beta, and will feature (very primitive) overlay editing. It’s not a thing of beauty (yet) – the overlay editing features are leaner than the airport editing tools were. But 1.1 will allow you to edit an overlay and airport in one workspace.
I can tell you now that the area where WED 1.1 is weak is preview. But I don’t want to hold off the ability to edit overlays in WED “at all” just because it’s not as nice as it could be (and someday will be).
It should be possible to work on an overlay project in both WED and OverlayEditor – for example, you could build a taxiway layout in WED, using the overlay capabilities for custom pavement and lines, but use OverlayEditor to place 3-d objects (with a 3-d view).
MeshTool
To be blunt, MeshTool in its current form is really hard to use. Part of that is expected – MeshTool is a “back-end” tool like DSF2Text, aimed to simplify the problem of creating base a base mesh for some other program. But even as a back-end, MeshTool is difficult to use because it has bugs in its polygon processing, which often result in cryptic and hard-to-diagnose crashes when used with even relatively simple input data.
The good news is that I have my base mesh generation code running with a new polygon processing library (
CGAL) – the switchover from my old buggy code to CGAL was done by Andrew and contributed back as a patch. I’ve been throwing all sorts of weird data at the polygon cutting algorithms and they are rock solid.
The mesh generation code is part of MeshTool, so the next build of MeshTool will feature these processing improvements. That’s where Janos’ extensive work on the build environment comes in – he’s basically turned the scenery code from a big pile of my mad ramblings into a sane multi-platform project. This will mean a much simpler, faster process for releasing tools, particularly on Windows and Linux.
(Previously once I got a tool working, I would have to waste a few days trying to get the code to work on Windows too, slowing the whole process down.)
I expect to recut the “scenery tool” pack (that is, MeshTool, DSF2Text, and all of those other smaller apps) some time during WED beta, after 930 goes final. If all goes well, there should be native versions of the command-line tools for Linux.
MeshTool Needs a UI
Fixing MeshTool’s polygon processing is necessary, but not at all sufficient to make it a useful tool; to be really useful, it needs a real user interface. I think there are two strong possibilities for this:
- WED could develop base mesh editing. Under this scheme, you would be able to draw land use polygons in WED and create a “DEM” object for the elevation.
- MeshTool could be an output option for QGIS (via some kind of plugin or script).
I don’t know which it will be yet. The advantage of WED is that an author could have all scenery elements in one place. The advantage of QGIS is that it contains advanced GIS features that I will probably never put in WED. It may be that QGIS’s UI is simply not intuitive to less advanced users – I don’t have good perspective on this.
Posted in Tools
by
Ben Supnik |
I just posted the new X-Plane AC3D plugin (3.2 beta 1). For the info, please subscribe to the x-plane-scenery yahoo mailing list. I will post links on the scenery website once the plugin has undergone more testing; during early beta I only need a few testers to tell me I broke things.
Please read the README that comes with the download completely!
An important note for anyone using an existing .ac file to make airplanes with panels:
The new plugin gives you direct control over manipulations. But older .ac files don’t have the manipulator set on any of the objects. Thus if you export your airplane, your panel texture will work, but the panel will not be clickable.
To fix this, for each object in the hierarchy that has panel texture, select the object, open the X-Plane Object Properties… dialog box, and change the manipulator from “None” to “Panel”. (If you don’t see this option, make your properties window a bit taller.)
Note that if you don’t need your panel to be clickable, setting the manipulator to “none” is slightly faster in X-Plane 930 and a lot faster in X-Plane 922.
Other details: you’ll need the Commands.txt and DataRefs.txt file from X-Plane’s Resources/plugins folder.
Panel sub-regions are now handled quite a bit differently – please be sure to read the README completely. If you were using the 3.1 plugin with panel regions, you may need to update your .ac file a bit.
Thanks to Janos (“sothis” on the .org) we now have a GIT repository of the scenery tools, with public browsing of the scenery tools code.
(Non-programmers – this basically means that source code updates for the scenery tools will now be available every hour, rather than every now and then when I get around to it. The rest of this post is for programmers.)
The X-Plane tools code have always been open source, in that the LR-created code is distributed under the MIT/X11 license (which basically says “do whatever you want, don’t sue us”). The public repository makes the process of getting the code a lot simpler:
- The master code is actually in CVS, but this public GIT repository is updated from CVS once an hour, so this code is very close to the latest we have.
- The full version history, tags, and other information that might be useful to a programmer are all present.
- The web interface supports online browsing of the code, as well as downloading a “snapshot” of the entire tree (as a zip, gz, or bz2 file).
Git is, to put it mildly, a confusing tool if you don’t already use it. However, the web interface allows you to simply fetch the code from a given date. If you are a git user, git cloning is supported via http, and we are working on getting the git daemon running too. The repo is read-only; if you want to send us a patch, contact me.
(Git users will note that most of my checkin comments are really lame. This is a bad habit that comes from using CVS too much. CVS’s checkin comments are per-file, not per-group, which makes them somewhat useless to search on. Typically CVS users rely heavily on tags. The bridge from CVS to git tries to group them into a single commit, which helps reveal the actions taken on the source code.)
In particular, when a new spec is being developed, during beta it may change. (During a beta of a future version, old specs won’t change.)
So…please do not release non-beta aircraft and scenery based on beta builds like 930.
Here’s an example: the current spec for attached objects is that the draw order is based first on lighting mode, then on the order listed in Plane-Maker.
It turns out that if we do that, polygon offset can’t be used in a number of weird cases. So the rules will have to change. I’m not sure what they will change to, but the decision will be finalized when 930 is finalized.
I receive a number of requests from authors for an attribute to tag an object as “needs maximum texture resolution” or “needs compression disabled” or “needs maximum anisotropic filtering”. The general idea is that the author wants to ensure a viewing environment that looks good.
For the most part, I am against these ideas – think of the two cases:
- If the attribute on the content is request for a relative improvement in resolution (e.g. set my object to one texture res higher than the rest of the world) then what we’ll have is an arms race – every author will set their content with this flag, and the result will be that the entire sim tends to run at one res setting higher than expected. The result: users without enough VRAM will turn their res settings down another notch and all the content will look like it did before.
- If the attribute on the content is a request for an absolute setting (e.g. load this texture at the highest resolution possible) some content will simply not run on some computers that do run X-Plane.
My general point is this: users run X-Plane with texture resolution, anisotropic filtering, and compression set to lower settings for a reason – because their hardware isn’t very fast! Forcing the sim to ignore the settings and run at a higher res won’t make the user’s video card any better – it will just take the framerate vs. visual quality tradeoff out of the hands of the user.
That’s a simplification of the issue – in fact I am sympathetic to the notion of differential settings – that is, we need to use more texture resolution for art elements that are closer to the viewer. The sim already improves airplane resolution a bit and cockpit resolution a lot. We set anisotropic filtering a bit higher on runways because they are viewed from a shallow view angle pretty much all the time during normal flight.
At this point I am looking at some more specific overrides for cockpit objects. In particular, modern cockpits are built out of many attached objects, and not just the “cockpit object” itself – reducing the resolution of these objects can make cockpit labels illegible.
If we do get extensions to improve resolution I can only say this: use them very, very sparingly! Adding the extension doesn’t improve the user’s hardware. If the user had the ability to run your airplane at extreme res without compression and 16x anisotropic filtering, he’d already be doing that!
In order to understand the vanishing point in Plane-Maker, we first have to look at field of view and the process by which X-Plane simulates a 3-d world on a 2-d monitor.
Field of View
Field of View is the angle that you get if you go from the left edge of your vision to your eye, then back up the right edge. In the case of a monitor, we can calculate this (depending on how far back I am sitting). For example, my 19″ LCD is 14.8 inches across the top; to have a 45 degree FOV I need to sit about 17.8 inches away from the monitor.
X-Plane lets you set the field of view. Imagine that you were sitting in front of a window on an airplane. As you put your face closer to the window, you can see more of the world outside. Effectively you are increasing your field of view. X-Plane works the same way – turning up the field of view parameter will increase the amount of “stuff” you can see.
Where Is The Horizon?
So where is the horizon? The answer is: it depends. Assuming you are looking straight forward, the most logical place to put the horizon is exactly half-way up the monitor. And this is what X-Plane does in any external view.
As you rotate your head up and down, the center of your vision changes relative to the horizon. But if you simply move your head up and down, the horizon doesn’t move. This is due to parallax. The closer an object is, the more it moves as you move your head. This is what lets me look “over” the dashboard of the car by sitting on a phone book: as my head goes higher, the dash board (close) appears a lot lower but the road (far) appears only a little bit lower. The horizon (very, very far away) doesn’t move at all.
This effect works in X-Plane. Try moving the view point up and down in a plane with a full 3-d cockpit, like the Cessna 172. As you move your head up and down, your ability to see the runway out the window will change.
2-D Panels
Things get weirder when we have a 2-d panel. A 2-d panel is sort of a flat image of what a 3-d cockpit might look like. We need some kind of correlation between the 2-d world and 3-d world…that is, where does the horizon appear through this 2-d panel. That location is the “vanishing point” in Plane-Maker.
Here’s where things get strange: what do we do when we scroll the panel? Do we move our head or tilt our head? The answer is: neither. Scrolling the 2-d panel simply scrolls the “window” within the 3-d world that we look through. This has the effect of moving the horizon (by the exact number of pixels the panel scrolled) without rotating your view point.
This isn’t necessarily the best way to scroll the panel, but it looks pretty good, and anything we do with 2-d panels is going to be an approximation.
And Now The Bug
Of course, there must be a bug in here somewhere…these blog posts are usually the result of an investigation into an edge-case in the sim. In X-Plane 930b6, we pick a vanishing point based on the 2-d panel when we are in 3-d cockpit mode.
Why would we do such a silly thing? Originally it was to keep the horizon from jumping when there is no 3-d cockpit object. This behavior is okay in that case, but here’s how we get burned: if the 2-d cockpit has to scroll, the vanishing point might be off the top of the screen. Authors who have made very large 2-d panels and separate 3-d cockpits see this as the 3-d viewpoint being stuck straight down. What’s happening is the vanishing point (and thus the center for the mouse) are off the top of the screen.
For beta 7 I am fixing this:
- If there is a 3-d cockpit object, the vanishing point will be the center of the screen, which is almost certainly the right thing to do for a real fully 3-d view.
- If there is no 3-d cockpit object (but instead X-Plane’s default of the 2-d panel floating in space) the vanishing point will match the 2-d view, but taking the default scroll position into account. This should keep the horizon at a reasonably sane point.
As a final note, it is possible to specify a 3-d panel without a 3-d cockpit object in X-Plane. Don’t make a plane like this. It’s a silly thing to do!
The code that decides what parts of the plane get drawn in what views is, to put it midly, byzantine. The code evolved, and in this process became more complex and convoluted.
One of the side effects was a series of bugs that couldn’t easily be fixed – typically it was a case where some new piece of code had to do some drawing, but the decisions on how to draw were being made by legacy code that had no business making those decisions.
So for beta 6 I rewrote that code.
Here’s what this means: if your airplane starts showing the wrong “stuff” in various views in beta 6, please send me the plane, and a description of what it does in 922 and 930b6.
The risk is that I may have missed some of the quirkier behaviors that 922 was capable of. My goal is to have 922’s behavior, but with clean code. So if things changed, please let me know!
