We’re working now on updating the map drawing SDK for compatibility with X-Plane 11.
This post is a request for comments from programmers who write plugins that used to draw to the map—it is not a place for general feature requests for the map, or for off topic comments. (And off topic comments will be deleted.)
Background: What broke the map drawing in the first place?
Long story short, the map has changed drastically since the X-Plane 10 version—it didn’t just get a fresh coat of paint.
The biggest obstacle to backward compatibility comes from the fact that we now use an honest-to-God cartographical map projection for map coordinates. Moreover, the map projection changes for different map types—the normal map UI uses a transverse Mercator projection, while the GPS units use a stereographic projection. For that reason alone, just “splatting” old drawing code on top of the new map would not give you the results you want… the old OpenGL local (x, y, z) coordinates do not have a straightforward mapping to the new projected latitude/longitude locations.
A second major change is the fact that the map can now rotate to match the heading of the user’s aircraft. Unless you like the possibility of your map labels being printed upside down, this requires awareness of the map’s rotation and the fact that north isn’t necessarily “up”.
The final big change comes from the draw order. The map is now very strongly divided into layers, and we draw in 3 stages:
- Backgrounds (e.g., terrain)
- Icons (e.g., airports, NAVAIDs, etc.)
- Labels
An individual layer can draw in any or all stages. (For instance, the airports layer draws both airport icons and labels for each icon.) We draw each stage from the bottom layer up, beginning with the terrain at the bottom, then the NAVAIDs & airports somewhere in the middle, and then finishing with the aircraft at the very top. This layering ensures that bigger or less important elements don’t cover up smaller or more important elements—your aircraft, for instance, will always be visible (and selectable), even if it’s in the exact same place as a fix or NAVAID. Likewise, the label for your element will always be visible even if the actual icon is obscured by something above it. (In practice, of course, readability is going to be poor if you have labels overlapping, but that’s not really solvable without much more powerful cartographical tools than we have now.)
While it’s not essential that plugin drawing code respect the layering draw order, it would certainly be nice—it would allow you to ensure that a) your plugin-drawn layer doesn’t cover more important info, and b) less important info doesn’t cover your layer.
Proposed API
With all that in mind, our proposed API for map drawing looks like this:
- Plugin code would call the SDK to create a new map layer. To do so, you would provide:
- An optional drawing callback for OpenGL drawing (which would be layered beneath all built-in icons & text, but above things like X-Plane’s terrain drawing).
- OpenGL drawing here is more or less a “free for all,” with one exception: manipulating the Z buffer is not allowed, due to our reliance on the Z buffer as a means of preserving layer ordering.
- An optional icon callback, where you would provide a set of PNG icons to be drawn, along with their heading, opacity, etc., and X-Plane would “splat” them onto the map above all built-in icon types except the aircraft
- An optional label callback, where you would provide a set of strings for X-Plane to draw above all built-in labels except the aircraft label
- An optional “prepare cache” callback, called whenever the map’s total bounds change (e.g., when the scenery loader loads new DSFs). This allows you to keep your drawing callbacks fast, since you can cache only the data you need for drawing in the current area.
- A flag to indicate whether you’d like your new layer to be disablable from the UI (if so, we would add a checkbox to the right-hand sidebar like we have now for the flight path and compass rose)
- Drawing, icon, & label callbacks would receive:
- The currently visible bounds of the map
- The current zoom level of the map
- The map units per unit of UI coordinates (useful for drawing text at a fixed size regardless of map scale)
- If your layer is drawing in the standard X-Plane map window, this is map units per boxel; if you’re drawing within the GPS unit, it’s map units per “virtual device pixel,” whose size in real screen pixels is of course fluid since the user can move the camera relative to the GPS in the panel.
- The map’s current mode (currently one of either sectional, low enroute, and high enroute)
- An opaque handle that provides access to the new projection APIs. The projection APIs would provide the following functions:
- project a latitude & longitude into map coordinates for drawing
- unproject an (x, y) pair of map coordinates into a latitude & longitude
- get the scale, in map coordinates, of 1 meter at a given (x, y)
- get the heading (in degrees clockwise from “up”) corresponding to north on the map for a given (x, y)—this is necessary since the X-Plane 11 map can be rotated to match your aircraft’s orientation
- Relative ordering of plugin-created layers would not be guaranteed. So, if you had two plugins which drew the same icon in the same place, but one drew in red and the other in blue, we would make no guarantees about which color the user saw. (And, indeed, some users may see red and others may see blue.)
Questions we have
While the proposal above meets what we believe the needs of third-party developers to be, we almost certainly haven’t considered every use case for this API. (And it’s possible we’re missing important features even for the use cases we have considered!)
To that end, here are some question you, dear plugin developer, can answer for us:
- What’s your use case for the map drawing API?
- Does the proposal above sound workable for your use case? (If not, what’s missing, or what would you change?)
- Do you like the idea of allowing plugin developers to specify whether their new layer is togglable from the standard map UI? (If not, why, and what policy would you like to see instead?)
- Do you have a use case for click selection and click-and-drag functionality in your plugin-created map layers? (This isn’t on the table for the initial update to the map API, but it’s a possibility for future updates.)
We have a new video tutorial on using FMOD to add custom sounds to X-Plane 11. This simple tutorial shows how to add a snapshot and an event in FMOD.
The video also has a permanent home on the video page of this site, and on the X-Plane YouTube channel.
As always, let us know your thoughts in the comments and if you have requests for other tutorials. I’m starting to get the hang of creating movies, and if you don’t troll me too hard about the quality I might make more. 😉
With X-Plane 11.02 the built-in GPS and FMS units for X-Plane 11 aircraft will also display heliports and seaplane bases. While this change is obviously needed badly for the helicopter flying community, improperly configured fixed-wing aircraft might suddenly feel themselves confronted with unsuitable options in the nearest airport selection pages and on the moving map.
Filter criteria
Every X-Plane aircraft has three parameters for airport and runway filtering that can be used to configure the moving map. These settings have existed for a long time, influenced which airports were displayed on the moving map, and kind of worked with the X-Plane 10 GPS as well. X-Plane 11 completely broke those settings for airplanes using the new X430/530 GPS, and not all aircraft authors go through the trouble of setting them up correctly.
X-Plane 11.02 correctly filters airports for GPS and FMS use as well as for the moving map based on these parameters. Because the GPS now also displays heliports and seaplane bases, it is important to set these filter parameters correctly in Plane Maker, to prevent unecessary clutter on the map.
The three settings are:
- Only Airports on Map – If not checked, the GPS and moving maps will show helipads and seaports. Check when you do not want those to show up in the nearest airport list on the GPS
- Only Paved Runways on Map – If not checked, the GPS and moving maps will show airports with no solid runways like grass, gravel and water surfaces
- Minimum Runway Length to Show on Map – This will filter out airports where the longest runway is shorter than this distance
Note that the these settings work on a per-airport basis. That means:
- At an airport with both runways and helipads, the helipads will still be shown regardless of setting.
- At an airport with both paved and grass or water runways, both runways will still be shown.
- In other words, airports are filtered out if they ONLY have helipads, or ONLY soft runways
- For seaplanes, leave the “Only Airports” box unchecked but enter a runway length number in order to supress the heliports.
If you already set these parameters in the past and they worked in X-Plane 10, there’s nothing for you to do. If you never bothered to set them, and suddenly see places inappropriate for landing show up in your built-in GPS, that is why.
To get this beta you’ll need to run the updater and click “Check for New Betas” – we won’t ever prompt you to install a beta when you have a final release of X-Plane. Here’s the Release Notes. Please file bugs using the Bug Reporter!
11.02 is a small maintenance patch. Our main focuses were:
- Performance tuning we could do without too much technical risk. (We’ll do the more adventurous stuff in 11.10.)
- Fine tuning the various SDKs.
- Bug Fixes.
As a small beta, I’m hoping the entire beta period will be less than two weeks.
X-Plane 11.02 should be out this week; we’re down to one bug, whose fix I am verifying now. There have been a number of questions about performance, so to start, here is some info on three things we’ve done to make 11.02 faster than 11.01.
8-bit Water. The dynamic FFT-based ocean wave textures we stream in X-Plane 11 are floating point textures in 11.01 (F32 on the CPU, F16 on the GPU). This was an easy decision for getting the tech working, but as it turns out, transferring the textures to the GPU is slow, particularly on the NVidia drivers.*
For 11.02, Sidney has rewritten the shaders to cope with 8-bit waves. The results look almost the same, but the amount of data transferred is 4x smaller, and more importantly, 8-bit RGBA is the path most likely to be handled well by the driver, so this should be a win.
Sidney also wrote some code to transfer the textures asynchronously, but we’re holding off until 11.10 for that, as it may require debugging or behave weirdly on some drivers.
Faster Car Bucketing. The cars have always cost more CPU than they should, and profiling indicated that 90% of the work was in moving the cars around in our scenery system as they drove. The code to “rebucket” them has been modified and is now significantly cheaper. We are not turning the car density up yet (it’s not that fast), but at this point with the cars at the highest setting we ship, they now take 2-3 ms total to compute, which means they have no frame rate impact. I’d like to bring the density up in the future if we can get further performance wins, which I think we can.
Better Core Scheduling. If you’ve been reading carefully, you should be shouting at the screen about now about how the hell something that takes 2-3 ms total is “free” – 3 ms means that if you were running at 60 fps you’re down to 50. That’s not free?
I am declaring the cars free because they now run in parallel to the flight model, and it’s very likely that the total flight model work takes at least 2-3 ms, even without AI planes. The third optimization is a big cleanup of the multi-core scheduling that we do within a frame.
X-Plane uses multiple cores both to load background scenery as you fly and to speed up some calculations within a frame. As of now, the major “per frame” multi-core computations are:
- The flight model (if you have more than one aircraft – we can’t multi-core a single plane).
- DSF scenery maintenance (not super expensive, but does get multi-core acceleration).
- Car computation (typically uses 1-2 cores at most).
- FFT water calculations for the next frame (uses up to four cores).
X-Plane 11.01 was not scheduling these particularly well – here’s a picture.
What you’re seeing is X-Plane kicking off the FFT water too early, and that work blocks X-plane from completing AI aircraft calculations. The big red bar up top is the sim waiting (and FPS dying) because the AI planes weren’t done in time.
(The bottom ‘track’ with nothing on it is an IO thread that’s waiting in case we need to do UDP I/O. Since I had IO off, it is efficiently sleeping. This profile is on a 4-core machine so we couldn’t have stuck work down there.)
Here’s 11.02:
We start the (newly optimized) cars as early as possible so they complete at about the same time as the flight model; we get all DSF work done immediately, and we don’t start water until the very end. In the meantime, the main thread is free to go do the actual frame rendering.
This is just an incremental step for multi-core use; we have been steadily adding more multi-core work for the last few years, and we’ll be adding more in future X-Plane 11 updates. For example, X-Plane 10.50 re-structured the renderer, separating the work of discovering what to draw (“culling”) from the work of actually drawing. In X-Plane 11, we can do that culling on multiple cores, improving total framerate.
I don’t have great numbers on what kind of performance change you’ll see in 11.02; it’s actually hard to measure the improvements here with the FPS test because the FPS test runs a replay (and not the actual flight model) and doesn’t run long enough to generate car traffic. But we think it should be a good incremental improvement.
* It is not a bug that this case was slow for the NVidia driver; no OpenGL driver is contractually obligated to do anything in a particular time frame. It was slightly surprising in that NVidia seems to go farther than other GL vendors to optimize less common and less efficient code paths.
NVidia does normally allow for complete threading of CPU-side driver work, so it’s possible they thought there was no need to optimize this case directly since it would be on a worker thread; by comparison, Apple does not use a general worker thread for their driver but does use a worker thread for all CPU-based texture transfers, at least as far as we can tell by profiling X-Plane.
The FMOD development guide now contains a link to the FMOD starter project generator.
If you want to make an aircraft that is FMOD enhanced, you must start with this starter project! If you already have an FMOD project, please copy the events into this new starter project.
When can an FMOD project be shared?
- Use only one starter project for an entire family of .acf files that share an ACF folder. These ACF files will share the master bank in the FMOD folder, so you need one project for all aircraft. (Each aircraft gets its own .snd file in the FMOD folder.)
- You must use a new starter project fore each aircraft in a new folder – you should never have a single project with banks copied into two different FMOD folders!
We are working on more documentation on how to use FMOD, but with the sample project, you have everything you need to create an FMOD-enhanced aircraft.
X-Plane 11.01 is now final, both via our installer and Steam. We’re going to do one more bug fix release (11.02); at this point it looks like Gateway airports will go into a separate 11.05 release to give authors a little bit more time to work with WED 1.6, but we’re still discussing this internally.
In terms of timelines and releases:
- Small bug fixes, fixes for aircraft SDKs, and small, tactical performance improvements will make it into X-Plane 11.02.
- Big things like an XPLM revision to pop out windows, fixing the weapon API, the G1000, and more invasive performance improvements as we move toward next-gen rendering APIs will have to wait for 11.10.
That’s a lot of stuff in that second bullet point – there is basically no chance that all of that will make it into 11.10; we have enough long term efforts going on at once that some will go into 11.10 and some into 11.20 or something later. I don’t even know which of those things will be in 11.10 – basically, what’s ready around when we get to 11.10 will be released, and we’ll do another release when more features build up.
Hot off the presses – first draft today: new docs on Using FMOD With X-Plane Aircraft and a file format spec for those .snd files you need to tie FMOD To your aircraft.
This is a first draft, so please: use the comments section to ask questions about FMOD only. I’m going to do something a little bit unusual and delete off-topic comments on this post so the entire comments thread is FMOD specific. FMOD integration with X-Plane is complicated, so it would be really useful to know what needs more explaining.
There is one more piece of the FMOD puzzle that is missing – Tyler is working on it now and hopefully we’ll have it live soon: the FMOD starter project.
The short version is: to get an FMOD project that will properly integrate with X-Plane and other third party FMOD aircraft, you need to get a starter project from us – it will come with the mix buses already in place and set up for X-Plane to use them; you can just add signal processing, etc.
What makes this tricky is: everyone needs a unique starter project or else multiple FMOD aircraft won’t be able to coexist. (And that would be sad – one of the really cool thing about FMOD-enhanced aircraft is that you can finally hear the AI aircraft. It adds a ton of depth and realism.)
Tyler is working on a download link that dynamically creates a unique FMOD starter document to avoid FMOD conflicts between AI aircraft. I’ll post when this is up and running.
In the meantime, the docs hopefully answer some questions about how aircraft like the Cessna work.
Right now FMOD can only be used to add sound to aircraft, but we are looking at adding FMOD to scenery, as well as our own ground vehicles.
X-Plane 11.01 release candidate two is now available – on Steam too! We hope this is the one.
Here’s one more before-and-after view – the new fog applied correctly to lighting spill and billboards.
11.01 should go final too and then we’ll move on to 11.02 – we have more bug fixes to get out and a performance improvement for NVidia Windows hardware.
We posted an X-Plane 11.01 release candidate today.
- The good news: it fixes the XPLM navigation buffer overruns that were crashing plugins. So that should be a big win for people using plugins with the beta.
- The bad news: we found and fixed the flashing cloud shadows bug after the RC went out.
So we’ll do an RC2 with the cloud shadow fix over the weekend. We have a bunch of bugs we kicked to an 11.02, so that we could get the 11.01 fixes to everyone. We’re also looking to make WED 1.6b2 uploadable to the gateway so we can push out more gateway airports.
Posted in News
by
Ben Supnik |
