XLua2 API Ref XPLMMap Latest - 4.4.0-d4

Map Layer Creation And Destruction

Enables the creation of new map layers. Layers are created for a particular instance of the X-Plane map. For instance, if you want your layer to appear in both the normal map interface and the Instructor Operator Station (IOS), you would need two separate calls to XPLMCreateMapLayer(), with two different values for your XPLMCreateMapLayer_t::layer_name.

Your layer's lifetime will be determined by the lifetime of the map it is created in. If the map is destroyed (on the X-Plane side), your layer will be too, and you'll receive a callback to your XPLMMapWillBeDeletedCallback_f.

XPLMMapLayerType

enum

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

Name	Value	Description
xplm_MapLayer_Fill	0	A layer that draws "fill" graphics, like weather patterns, terrain, etc. Fill layers frequently cover a large portion of the visible map area.
xplm_MapLayer_Markings	1	A layer that provides markings for particular map features, like NAVAIDs, airports, etc. Even dense markings layers cover a small portion of the total map area.

XPLM_MAP_USER_INTERFACE

define

Globally unique identifier for X-Plane's Map window, used as the mapToCreateLayerIn parameter in XPLMCreateMapLayer_t

#define XPLM_MAP_USER_INTERFACE "XPLM_MAP_USER_INTERFACE"

XPLM_MAP_USER_INTERFACE  -- "XPLM_MAP_USER_INTERFACE"

XPLM_MAP_IOS

define

Globally unique identifier for X-Plane's Instructor Operator Station window, used as the mapToCreateLayerIn parameter in XPLMCreateMapLayer_t

#define XPLM_MAP_IOS "XPLM_MAP_IOS"

XPLM_MAP_IOS  -- "XPLM_MAP_IOS"

XPLMCreateMapLayer_t

struct

This structure defines all of the parameters used to create a map layer using XPLMCreateMapLayer. The structure will be expanded in future SDK APIs to include more features. Always set the structSize member to the size of your struct in bytes!

Each layer must be associated with exactly one map instance in X-Plane. That map, and that map alone, will call your callbacks. Likewise, when that map is deleted, your layer will be as well.

local My_CreateMapLayer_t = {
    structSize             = 0,       -- int
    mapToCreateLayerIn     = "",      -- string
    layerType              = nil,     -- XPLMMapLayerType
    willBeDeletedCallback  = nil,     -- see XPLMMapWillBeDeletedCallback_f
    prepCacheCallback      = nil,     -- see XPLMMapPrepareCacheCallback_f
    drawCallback           = nil,     -- see XPLMMapDrawingCallback_f
    iconCallback           = nil,     -- see XPLMMapIconDrawingCallback_f
    labelCallback          = nil,     -- see XPLMMapLabelDrawingCallback_f
    showUiToggle           = false,   -- boolean
    layerName              = "",      -- string
    refcon                 = nil,     -- any Lua var/table
}

See available callback(s):

XPLMCreateMapLayer

function

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 XPLMMapLayerID -> assign to local/var
local my_mapLayerID = XPLMCreateMapLayer(
    inParams     -- see XPLMCreateMapLayer_t
)

See associated types:

XPLMCreateMapLayer_t

XPLMDestroyMapLayer

function

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

-- returns boolean -> assign to local/var
local my_result = XPLMDestroyMapLayer(
    inLayer     -- XPLMMapLayerID
)

See associated types:

XPLMMapLayerID

XPLMMapCreatedCallback_f

callback

A callback to notify your plugin that a new map has been created in X-Plane. This is the best time to add a custom map layer using XPLMCreateMapLayer().

No OpenGL drawing is permitted within this callback.

function my_MapCreatedCallback_callback(
    mapIdentifier,    -- string
    inRefcon          -- any Lua var/table
)
    -- your code here
end

XPLMRegisterMapCreationHook

function

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.

XPLMRegisterMapCreationHook(
    callback,    -- see XPLMMapCreatedCallback_f
    inRefcon     -- any Lua var/table
)

See associated types:

XPLMMapCreatedCallback_f

XPLMMapExists

function

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 boolean -> assign to local/var
local my_result = XPLMMapExists(
    mapIdentifier     -- string
)