Blog

RFC: Plugin-Drawn Map Layers in X-Plane 11

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:

1. Backgrounds (e.g., terrain)
2. Icons (e.g., airports, NAVAIDs, etc.)
3. 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.)