Create a map

A map belongs to a runtime. The thread that creates the runtime becomes the owner thread for the runtime and every map under it. Create both on the thread that will pump them.

One runtime serves any number of maps and holds the shared work: the scheduler, the event queue, the network stack, and one cache database.

create-map.c

mln_runtime_options options = mln_runtime_options_default();

// A filesystem path keeps cached tiles across runs of the host. The default,
// ":memory:", discards them when the runtime is destroyed.
options.cache_path = cache_path;

return mln_runtime_create(&options, out_runtime);

Choose the options that outlive the call

Three map options are fixed at creation: the scale factor, the map mode, and FastPFOR decoding.

The scale factor selects the sprites, glyphs, and raster tiles that the map downloads. Set it to the display density that the map will use. A render target has its own scale factor for geometry. Attaching a target with a different value logs a warning and continues to load imagery at the map’s density.

create-map.c

mln_map_options options = mln_map_options_default();

// Replaced by the render target's extent at the first attach. Until then it
// is the viewport that camera and projection queries answer against.
options.width = width;
options.height = height;

// Fixed for the map's life. It selects sprites, glyphs, and raster tiles.
options.scale_factor = scale_factor;

return mln_map_create(runtime, &options, out_map);

The width and height set the viewport until the first render target attaches. That target’s extent then replaces them. Before the first attach, camera and projection queries use the initial width and height.

A continuous map redraws as data arrives and the camera moves. Use this mode for an on-screen map. A static map produces one image per request, and a tile map produces one image for a single tile.

create-map.c

mln_map_options options = mln_map_options_default();
options.width = width;
options.height = height;
options.scale_factor = 1.0;
options.map_mode = MLN_MAP_MODE_STATIC;

return mln_map_create(runtime, &options, out_map);

FastPFOR decoding applies to every MapLibre Tiles source that the map loads. Enable it at creation when your tile sets use that encoding.

Release in order

Destroy a map before the runtime that owns it. A runtime with live maps reports an invalid-state status.

create-map.c

mln_map_destroy(map);
mln_runtime_destroy(runtime);