Map Projections

As of X-Plane 11, the map draws using true cartographic projections, and different maps may use different projections. Thus, to draw at a particular latitude and longitude, you must first transform your real-world coordinates into map coordinates.

The map projection is also responsible for giving you the current scale of the map. That is, the projection can tell you how many map units correspond to 1 meter at a given point.

Finally, the map projection can give you the current rotation of the map. Since X-Plane 11 maps can rotate to match the heading of the aircraft, the map's rotation can potentially change every frame.

XPLMMapProject

function

Projects a latitude/longitude into map coordinates. This is the inverse of XPLMMapUnproject().

Only valid from within a map layer callback (one of XPLMMapPrepareCacheCallback_f, XPLMMapDrawingCallback_f, XPLMMapIconDrawingCallback_f, or XPLMMapLabelDrawingCallback_f.)

XPLM_API void       XPLMMapProject(
                         XPLMMapProjectionID  projection,
                         double               latitude,
                         double               longitude,
                         float *              outX,
                         float *              outY
                    );

XPLMMapUnproject

function

Transforms map coordinates back into a latitude and longitude. This is the inverse of XPLMMapProject().

Only valid from within a map layer callback (one of XPLMMapPrepareCacheCallback_f, XPLMMapDrawingCallback_f, XPLMMapIconDrawingCallback_f, or XPLMMapLabelDrawingCallback_f.)

XPLM_API void       XPLMMapUnproject(
                         XPLMMapProjectionID  projection,
                         float                mapX,
                         float                mapY,
                         double *             outLatitude,
                         double *             outLongitude
                    );

XPLMMapScaleMeter

function

Returns the number of map units that correspond to a distance of one meter at a given set of map coordinates.

Only valid from within a map layer callback (one of XPLMMapPrepareCacheCallback_f, XPLMMapDrawingCallback_f, XPLMMapIconDrawingCallback_f, or XPLMMapLabelDrawingCallback_f.)

XPLM_API float      XPLMMapScaleMeter(
                         XPLMMapProjectionID  projection,
                         float                mapX,
                         float                mapY
                    );

XPLMMapGetNorthHeading

function

Returns the heading (in degrees clockwise) from the positive Y axis in the cartesian mapping coordinate system to true north at the point passed in. You can use it as a clockwise rotational offset to align icons and other 2-d drawing with true north on the map, compensating for rotations in the map due to projection.

Only valid from within a map layer callback (one of XPLMMapPrepareCacheCallback_f, XPLMMapDrawingCallback_f, XPLMMapIconDrawingCallback_f, or XPLMMapLabelDrawingCallback_f.)

XPLM_API float      XPLMMapGetNorthHeading(
                         XPLMMapProjectionID  projection,
                         float                mapX,
                         float                mapY
                    );