Panel Graphics Map Display

This function creates a new map display instance. The display begins loading terrain tiles for the current aircraft position immediately. You can draw it as soon as tiles are available; before that, the draw call is a no-op.

The returned handle must be destroyed with XPLMDestroyMapDisplay when no longer needed. Handles are automatically destroyed when the owning plugin is unloaded.

-- returns XPLMMapDisplayRef -> assign to local/var
local my_mapDisplayRef = XPLMCreateMapDisplay(
    params     -- see XPLMCreateMap_t
)

See associated types:

• XPLMCreateMap_t

This function destroys a map display and frees all associated resources.

XPLMDestroyMapDisplay(
    map     -- XPLMMapDisplayRef
)

See associated types:

• XPLMMapDisplayRef

This function renders the map display directly into the active panel surface within the rectangle given by info. Map sets up its own projection to fit that rectangle, so no transform stack manipulation is needed.

info->layers controls which visual layers are rendered. Note that some layers are mutually exclusive, such as NEXRAD and EGPWS or NEXRAD and IR. The airport details layer is only visible at very close zoom levels.

This function must be called from within an avionics drawing callback. If terrain tiles have not finished loading yet, this function does nothing.

dataOverrides may be NULL, in which case the map follows the sim's own navigation display: centered on the user aircraft in the middle of the rectangle, rose radius half the shorter side of it, range taken from the EFIS range knob, and track-up or north-up according to the sim's map mode. The pilotIndex you created the map with selects which side's range and altitude are used.

XPLMMapDisplayDrawIn(
    map,              -- XPLMMapDisplayRef
    info,             -- see XPLMMapDrawInfo_t
    dataOverrides     -- see XPLMMapCustomData_t
)

See associated types:

• XPLMMapCustomData_t
• XPLMMapDisplayRef
• XPLMMapDrawInfo_t

Turns a latitude/longitude into a position in panel coordinates, for the map that info describes. This is the inverse of XPLMMapDisplayUnproject.

Pass the same info you draw that map with and you get the projection that draw call produces, whether you call this before or after XPLMMapDisplayDrawIn. So the usual pattern - project your symbols, draw the map, then draw the symbols on top - lines up exactly, with no need to cache anything between frames.

Unlike XPLMMapDisplayDrawIn, this does not have to be called from a drawing callback; it is equally valid from a click handler or a flight loop.

Returns 1 on success. Returns 0, leaving outX and outY untouched, if the map's terrain tiles have not loaded yet or if the point has no position on this map.

Note that the returned coordinates are in the same space as info's rectangle, and like that rectangle they do not account for the panel graphics transform stack.

Passing NULL for dataOverrides projects the sim's own navigation display view, the same one XPLMMapDisplayDrawIn draws with NULL.

-- returns int -> assign to local/var
local my_result = XPLMMapDisplayProject(
    map,              -- XPLMMapDisplayRef
    info,             -- see XPLMMapDrawInfo_t
    dataOverrides,    -- see XPLMMapCustomData_t
    latitude,         -- float
    longitude,        -- float
    outX,             -- float
    outY              -- float
)

See associated types:

• XPLMMapCustomData_t
• XPLMMapDisplayRef
• XPLMMapDrawInfo_t

Turns a position in panel coordinates back into a latitude/longitude, for the map that info describes. This is the inverse of XPLMMapDisplayProject.

Use this to turn a touch or click on your map into a place in the world - for picking a waypoint, or reading out the position under the cursor.

Unlike XPLMMapDisplayDrawIn, this does not have to be called from a drawing callback; it is equally valid from a click handler or a flight loop.

Returns 1 on success. Returns 0, leaving outLatitude and outLongitude untouched, if the map's terrain tiles have not loaded yet or if the point does not correspond to anywhere on the earth.

Passing NULL for dataOverrides projects the sim's own navigation display view, the same one XPLMMapDisplayDrawIn draws with NULL.

-- returns int -> assign to local/var
local my_result = XPLMMapDisplayUnproject(
    map,              -- XPLMMapDisplayRef
    info,             -- see XPLMMapDrawInfo_t
    dataOverrides,    -- see XPLMMapCustomData_t
    x,                -- float
    y,                -- float
    outLatitude,      -- float
    outLongitude      -- float
)

See associated types:

• XPLMMapCustomData_t
• XPLMMapDisplayRef
• XPLMMapDrawInfo_t

Returns how many pixels correspond to one meter at a given point on the map that info describes. Use it to size symbols and range rings so they stay correct as the range changes.

Returns 0 if the map's terrain tiles have not loaded yet.

Passing NULL for dataOverrides projects the sim's own navigation display view, the same one XPLMMapDisplayDrawIn draws with NULL.

-- returns float -> assign to local/var
local my_result = XPLMMapDisplayScaleMeter(
    map,              -- XPLMMapDisplayRef
    info,             -- see XPLMMapDrawInfo_t
    dataOverrides,    -- see XPLMMapCustomData_t
    x,                -- float
    y                 -- float
)

See associated types:

• XPLMMapCustomData_t
• XPLMMapDisplayRef
• XPLMMapDrawInfo_t

Returns the heading, in degrees clockwise from straight up on the display, at which true north lies at a given point on the map that info describes. ADD it to a true heading to get the angle to draw that heading at.

This accounts both for the map's own rotation - a heading-up map is turned to put the aircraft's nose at the top - and for the projection's convergence, which tilts north away from vertical as you move away from the map's center.

Returns 0 if the map's terrain tiles have not loaded yet.

Passing NULL for dataOverrides projects the sim's own navigation display view, the same one XPLMMapDisplayDrawIn draws with NULL.

-- returns float -> assign to local/var
local my_result = XPLMMapDisplayGetNorthHeading(
    map,              -- XPLMMapDisplayRef
    info,             -- see XPLMMapDrawInfo_t
    dataOverrides,    -- see XPLMMapCustomData_t
    x,                -- float
    y                 -- float
)

See associated types:

• XPLMMapCustomData_t
• XPLMMapDisplayRef
• XPLMMapDrawInfo_t

This function returns the lowest and highest altitude shown on the map's EGPWS terrain display.

Note that those altitudes are only available if the map has been drawn with the xplm_Map_EGPWS layer. If altitudes are not available, the function returns false, and the altitude pointers are not modified.

This function must be called from within an avionics drawing callback.

• map: the map display handle.
• min: a pointer to the minimum altitude.
• max: a pointer to the maximum altitude.

-- returns int -> assign to local/var
local my_result = XPLMMapDisplayGetTerrainAltitudes(
    map,    -- XPLMMapDisplayRef
    min,    -- float
    max     -- float
)

See associated types:

• XPLMMapDisplayRef