Skip to main content

​
Overview

Graphical content displayed in the MapScene is organized into layers. Each layer can contain one or more layer objects that define what to render and where to place it in the map’s coordinate space.
Layers are the fundamental building blocks for displaying content on your map.

​
Layer Architecture

Before a new frame is drawn, the MapScene queries all added layers for their render configuration, specifying which graphics need to be drawn and in which order.

​
LayerInterface

All layers implement the LayerInterface, which provides core functionality: 
class LayerInterface {
public:
    virtual void update() = 0;
    virtual std::vector<std::shared_ptr<RenderPassInterface>> buildRenderPasses() = 0;
    virtual void onAdded(const std::shared_ptr<MapInterface> & mapInterface, 
                         int32_t layerIndex) = 0;
    virtual void onRemoved() = 0;
    
    virtual void pause() = 0;
    virtual void resume() = 0;
    virtual void hide() = 0;
    virtual void show() = 0;
    
    virtual void setAlpha(float alpha) = 0;
    virtual float getAlpha() = 0;
    
    virtual void setMaskingObject(const std::shared_ptr<MaskingObjectInterface> & maskingObject) = 0;
    virtual void setScissorRect(const std::optional<RectI> & scissorRect) = 0;
    
    // ...
};

​
Managing Layers

Layers are managed through the MapInterface: 
// Add a layer to the top
mapInterface->addLayer(myLayer);

// Insert at specific position
mapInterface->insertLayerAt(myLayer, 0);

// Insert relative to other layers
mapInterface->insertLayerAbove(newLayer, existingLayer);
mapInterface->insertLayerBelow(newLayer, existingLayer);

// Remove a layer
mapInterface->removeLayer(myLayer);

// Get all layers
auto layers = mapInterface->getLayers();
Layer order matters! Layers added later are drawn on top of earlier layers.

​
Available Layer Types

The Maps Core provides several built-in layer types:

​
Tiled2dMapRasterLayer

Raster Tile Layer

Displays map tiles from raster sources
The most common layer type for displaying base maps from tile servers. 
auto config = std::make_shared<Tiled2dMapLayerConfig>(
    "my-layer",
    tileUrl,
    coordinateSystem,
    zoomLevels,
    bounds
);

auto tileLayer = std::make_shared<Tiled2dMapRasterLayer>(
    config,
    tileLoaders
);

mapInterface->addLayer(tileLayer->asLayerInterface());
Key Features:
  • Hierarchical tile loading
  • Automatic zoom level selection
  • Tile caching
  • Loading of tiles based on camera position
Configuration:
​
Tiled2dMapLayerConfig
object
required
Defines coordinate system, bounds, zoom levels, and tile URL pattern
​
TextureLoaderInterface
interface
required
Loads tile images from URLs or local sources
See shared/public/Tiled2dMapRasterLayer.h:38 for full implementation.

​
PolygonLayer

Polygon Layer

Renders filled polygons
Display areas, buildings, zones, and other polygon features. 
auto polygonLayer = std::make_shared<PolygonLayer>();

// Add polygons
PolygonInfo polygon;
polygon.identifier = "building-1";
polygon.coordinates = {/* vector of coordinates */};
polygon.fillColor = Color(1.0, 0.0, 0.0, 0.5); // red with 50% opacity

polygonLayer->add(polygon);
mapInterface->addLayer(polygonLayer->asLayerInterface());
Methods: 
virtual void add(const PolygonInfo & polygon);
virtual void addAll(const std::vector<PolygonInfo> & polygons);
virtual void remove(const PolygonInfo & polygon);
virtual void clear();
virtual void setPolygons(const std::vector<PolygonInfo> & polygons, const Vec3D & origin);
See shared/public/PolygonLayer.h:25 for full implementation.

​
LineLayer

Line Layer

Renders lines and polylines
Display roads, routes, boundaries, and paths. 
auto lineLayer = std::make_shared<LineLayer>();

// Create line info
auto lineInfo = LineInfo::create(
    "route-1",
    coordinates,
    lineStyle
);

lineLayer->add(lineInfo);
mapInterface->addLayer(lineLayer->asLayerInterface());
Methods: 
virtual void add(const std::shared_ptr<LineInfoInterface> & line);
virtual void remove(const std::shared_ptr<LineInfoInterface> & line);
virtual void setLines(const std::vector<std::shared_ptr<LineInfoInterface>> & lines);
virtual void clear();
Features:
  • Dashed lines
  • Line width and color
  • Cap and join styles
  • Animated line styles
See shared/public/LineLayer.h:26 for full implementation.

​
IconLayer

Icon Layer

Displays icons and markers
Place markers, symbols, and icons on the map. 
auto iconLayer = IconLayerInterface::create();

// Add an icon
auto iconInfo = IconInfo::create(
    "marker-1",
    coordinate,
    iconTexture,
    iconSize
);

iconLayer->add(iconInfo);
mapInterface->addLayer(iconLayer->asLayerInterface());
Methods: 
virtual void add(const std::shared_ptr<IconInfoInterface> & icon);
virtual void addList(const std::vector<std::shared_ptr<IconInfoInterface>> & icons);
virtual void remove(const std::shared_ptr<IconInfoInterface> & icon);
virtual void removeIdentifier(const std::string & identifier);
virtual void clear();

// Animations
virtual void animateIconScale(const std::string & identifier, 
                              float from, float to, 
                              float duration, int32_t repetitions);
See shared/public/IconLayerInterface.h:15 for full implementation.

​
TextLayer

Text Layer

Renders text labels
Display labels, annotations, and textual information. 
auto textLayer = TextLayer::create();

// Add text
auto textInfo = TextInfo::create(
    "label-1",
    coordinate,
    "Label Text",
    fontInfo,
    textColor
);

textLayer->add(textInfo);
mapInterface->addLayer(textLayer->asLayerInterface());

​
Tiled2dMapVectorLayer

Vector Tile Layer

Renders vector tiles with styling
Display styled vector tiles (e.g., Mapbox Vector Tiles). 
auto vectorConfig = std::make_shared<Tiled2dMapVectorLayerConfig>(
    layerName,
    tileUrl,
    coordinateSystem,
    zoomInfo,
    styleJson
);

auto vectorLayer = Tiled2dMapVectorLayer::create(vectorConfig, loaders);
mapInterface->addLayer(vectorLayer->asLayerInterface());

​
Layer Lifecycle

1

Creation

Create a layer instance
2

Configuration

Configure the layer with content (objects, tiles, etc.)
3

Add to Map

Add the layer to the map using addLayer() or related methods
4

onAdded Callback

The layer receives onAdded() callback with map interface and layer index
5

Update Loop

Each frame: update() is called, then buildRenderPasses() provides render instructions
6

Removal

Remove the layer with removeLayer(), which triggers onRemoved() callback

​
Layer Objects

Layers contain layer objects that define individual graphical elements: 
// Example: Polygon layer object
class Polygon2dLayerObject {
    std::string identifier;
    std::vector<Coord> coordinates;
    Color fillColor;
    // Graphics primitive reference
};
Layer objects typically include:
  • Unique identifier
  • Coordinate information
  • Visual styling (color, size, etc.)
  • Reference to graphics primitive

​
Layer Control

​
Visibility

// Hide layer (keeps it in memory)
layer->hide();

// Show layer
layer->show();

​
Opacity

// Set layer opacity (0.0 = transparent, 1.0 = opaque)
layer->setAlpha(0.5f);

float currentAlpha = layer->getAlpha();

​
Masking

// Apply a mask to clip layer content
auto mask = std::make_shared<PolygonMaskObject>(maskCoordinates);
layer->setMaskingObject(mask);

​
Scissor Rectangle

// Limit rendering to a specific screen rectangle
RectI scissorRect(x, y, width, height);
layer->setScissorRect(scissorRect);

// Remove scissor
layer->setScissorRect(std::nullopt);

​
Layer Ready State

Layers can report their ready state for offscreen rendering: 
LayerReadyState state = layer->isReadyToRenderOffscreen();

switch(state) {
    case LayerReadyState::READY:
        // Layer is ready
        break;
    case LayerReadyState::NOT_READY:
        // Layer is still loading
        break;
    case LayerReadyState::ERROR:
        // Layer encountered an error
        break;
}

​
Layer Callbacks

Many layers support callback interfaces for interaction: 
// Example: Polygon layer callbacks
class MyPolygonCallback : public PolygonLayerCallbackInterface {
public:
    void onPolygonClicked(const PolygonInfo & polygon) override {
        // Handle polygon click
    }
};

auto callback = std::make_shared<MyPolygonCallback>();
polygonLayer->setCallbackHandler(callback);

​
Custom Layers

You can create custom layers by implementing LayerInterface: 
class MyCustomLayer : public LayerInterface {
public:
    void update() override {
        // Update layer state
    }
    
    std::vector<std::shared_ptr<RenderPassInterface>> buildRenderPasses() override {
        // Build render passes for this frame
        return renderPasses;
    }
    
    void onAdded(const std::shared_ptr<MapInterface> & mapInterface, 
                 int32_t layerIndex) override {
        this->mapInterface = mapInterface;
        // Initialize layer resources
    }
    
    // Implement other required methods...
};
Custom layers give you complete control over rendering and can implement any visualization you need.

​
Best Practices

Place base map layers (raster/vector tiles) first, then overlays (polygons, lines), and finally markers/icons/text on top.
Limit the number of objects in a layer. Use tiled layers for large datasets. Consider hiding or removing layers that aren’t currently needed.
Remove layers when they’re no longer needed. Clear layer contents with clear() before removing to free resources immediately.
Use callback interfaces to handle user interactions. Make layers non-clickable with setLayerClickable(false) when interaction isn’t needed.

​
Platform Examples

val polygonLayer = PolygonLayer()

val polygon = PolygonInfo(
    identifier = "area-1",
    coordinates = coordinates,
    fillColor = Color(1.0f, 0.0f, 0.0f, 0.5f)
)

polygonLayer.add(polygon)
mapInterface.addLayer(polygonLayer.asLayerInterface())

// Control visibility
polygonLayer.hide()
polygonLayer.setAlpha(0.5f)

Architecture

Understand the SDK structure

Camera

Control what layers are visible

Coordinate Systems

Position layer objects correctly

Build docs developers (and LLMs) love

Get started for freeTalk to us