XPLMMap

Indicates the visual style being drawn by the map. In X-Plane, the user can choose between a number of map types, and different map types may have use a different visual representation for the same elements (for instance, the visual style of the terrain layer changes drastically between the VFR and IFR layers), or certain layers may be disabled entirely in some map types (e.g., localizers are only visible in the IFR low-enroute style).

Indicates the type of map layer you are creating. Fill layers will always be drawn beneath markings layers.

Indicates whether a map element should be match its rotation to the map itself, or to the user interface. For instance, the map itself may be rotated such that "up" matches the user's aircraft, but you may want to draw a text label such that it is always rotated zero degrees relative to the user's perspective. In that case, you would have it draw with UI orientation.

Returns: XPLMMapLayerID

This routine creates a new map layer. You pass in an XPLMCreateMapLayer_t structure with all of the fields defined. You must set the structSize of the structure to the size of the actual structure you used. Returns NULL if the layer creation failed. This happens most frequently because the map you specified in your XPLMCreateMapLayer_t::mapToCreateLayerIn field doesn't exist (that is, if XPLMMapExists() returns 0 for the specified map). You can use XPLMRegisterMapCreationHook() to get a notification each time a new map is opened in X-Plane, at which time you can create layers in it.

Returns: boolean

Destroys a map layer you created (calling your XPLMMapWillBeDeletedCallback_f if applicable). Returns true if a deletion took place.

Returns: (returns nothing)

Registers your callback to receive a notification each time a new map is constructed in X-Plane. This callback is the best time to add your custom map layer using XPLMCreateMapLayer(). Note that you will not be notified about any maps that already exist---you can use XPLMMapExists() to check for maps that were created previously.

Returns: boolean

Returns true if the map with the specified identifier already exists in X-Plane. In that case, you can safely call XPLMCreateMapLayer() specifying that your layer should be added to that map.

Returns: (returns nothing)

Enables plugin-created map layers to draw PNG icons using X-Plane's built-in icon drawing functionality. Only valid from within an XPLMIconDrawingCallback_t (but you can request an arbitrary number of icons to be drawn from within your callback). X-Plane will automatically manage the memory for your texture so that it only has to be loaded from disk once as long as you continue drawing it per-frame. (When you stop drawing it, the memory may purged in a "garbage collection" pass, require a load from disk in the future.) Instead of having X-Plane draw a full PNG, this method allows you to use UV coordinates to request a portion of the image to be drawn. This allows you to use a single texture load (of an icon sheet, for example) to draw many icons. Doing so is much more efficient than drawing a dozen different small PNGs. The UV coordinates used here treat the texture you load as being comprised of a number of identically sized "cells". You specify the width and height in cells (ds and dt, respectively), as well as the coordinates within the cell grid for the sub-image you'd like to draw. Note that you can use different ds and dt values in subsequent calls with the same texture sheet. This enables you to use icons of different sizes in the same sheet if you arrange them properly in the PNG. This function is only valid from within an XPLMIconDrawingCallback_t (but you can request an arbitrary number of icons to be drawn from within your callback).

Returns: (returns nothing)

Enables plugin-created map layers to draw text labels using X-Plane's built-in labeling functionality. Only valid from within an XPLMMapLabelDrawingCallback_f (but you can request an arbitrary number of text labels to be drawn from within your callback).

Returns: {k} with keys: x, y

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.)

Output table keys:

Returns: {k} with keys: latitude, longitude

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.)

Output table keys:

Returns: number

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.)

Returns: number

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.)