Data Structures
struct	mln_image_stretch
struct	mln_image_content
struct	mln_style_source_tile_info
struct	mln_style_source_info
struct	mln_style_layer_info
struct	mln_geojson_source_options
struct	mln_canonical_tile_id
struct	mln_custom_geometry_source_options
struct	mln_custom_mvt_vector_source_options
struct	mln_premultiplied_rgba8_image
struct	mln_style_image_options
struct	mln_style_image_info
struct	mln_style_transition_options

Typedefs
typedef enum mln_style_source_type	mln_style_source_type
typedef enum mln_style_source_info_field	mln_style_source_info_field
typedef enum mln_style_tile_scheme	mln_style_tile_scheme
typedef enum mln_style_vector_tile_encoding	mln_style_vector_tile_encoding
typedef enum mln_style_raster_dem_encoding	mln_style_raster_dem_encoding
typedef struct mln_image_stretch	mln_image_stretch
typedef struct mln_image_content	mln_image_content
typedef enum mln_style_image_text_fit	mln_style_image_text_fit
typedef enum mln_style_layer_visibility	mln_style_layer_visibility
typedef enum mln_geojson_source_option_field	mln_geojson_source_option_field
typedef enum mln_custom_geometry_source_option_field	mln_custom_geometry_source_option_field
typedef enum mln_custom_mvt_vector_source_option_field	mln_custom_mvt_vector_source_option_field
typedef enum mln_style_image_option_field	mln_style_image_option_field
typedef enum mln_style_image_info_field	mln_style_image_info_field
typedef enum mln_style_transition_option_field	mln_style_transition_option_field
typedef struct mln_style_source_tile_info	mln_style_source_tile_info
typedef struct mln_style_source_info	mln_style_source_info
typedef struct mln_style_layer_info	mln_style_layer_info
typedef struct mln_geojson_source_options	mln_geojson_source_options
typedef struct mln_canonical_tile_id	mln_canonical_tile_id
typedef void(*)	mln_custom_source_fetch_tile_callback(void *user_data, mln_canonical_tile_id tile_id)
typedef void(*)	mln_custom_source_cancel_tile_callback(void *user_data, mln_canonical_tile_id tile_id)
typedef struct mln_custom_geometry_source_options	mln_custom_geometry_source_options
typedef struct mln_custom_mvt_vector_source_options	mln_custom_mvt_vector_source_options
typedef struct mln_premultiplied_rgba8_image	mln_premultiplied_rgba8_image
typedef struct mln_style_image_options	mln_style_image_options
typedef struct mln_style_image_info	mln_style_image_info
typedef struct mln_style_transition_options	mln_style_transition_options

Enumerations
enum	mln_style_source_type : uint32_t
enum	mln_style_source_info_field : uint32_t { MLN_STYLE_SOURCE_INFO_URL = 1U << 0U , MLN_STYLE_SOURCE_INFO_TILEJSON = 1U << 1U , MLN_STYLE_SOURCE_INFO_BOUNDS = 1U << 2U , MLN_STYLE_SOURCE_INFO_TILE_SIZE = 1U << 3U , MLN_STYLE_SOURCE_INFO_VECTOR_ENCODING = 1U << 4U , MLN_STYLE_SOURCE_INFO_RASTER_ENCODING = 1U << 5U , MLN_STYLE_SOURCE_INFO_ATTRIBUTION = 1U << 6U }
enum	mln_style_tile_scheme : uint32_t
enum	mln_style_vector_tile_encoding : uint32_t
enum	mln_style_raster_dem_encoding : uint32_t
enum	mln_style_image_text_fit : uint32_t
enum	mln_style_layer_visibility : uint32_t
enum	mln_geojson_source_option_field : uint32_t
enum	mln_custom_geometry_source_option_field : uint32_t
enum	mln_custom_mvt_vector_source_option_field : uint32_t
enum	mln_style_image_option_field : uint32_t
enum	mln_style_image_info_field : uint32_t { MLN_STYLE_IMAGE_INFO_CONTENT = 1U << 0U , MLN_STYLE_IMAGE_INFO_TEXT_FIT_WIDTH = 1U << 1U , MLN_STYLE_IMAGE_INFO_TEXT_FIT_HEIGHT = 1U << 2U }
enum	mln_style_transition_option_field : uint32_t

Functions
mln_status	mln_map_set_global_state_property (mln_map map, mln_buffer_view property_name, mln_buffer_view value, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_get_global_state (mln_map map, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_geojson_source_options	mln_geojson_source_options_default (void)
mln_custom_geometry_source_options	mln_custom_geometry_source_options_default (void)
mln_custom_mvt_vector_source_options	mln_custom_mvt_vector_source_options_default (void)
mln_premultiplied_rgba8_image	mln_premultiplied_rgba8_image_default (void)
mln_style_image_options	mln_style_image_options_default (void)
mln_style_transition_options	mln_style_transition_options_default (void)
mln_status	mln_map_add_style_source_json (mln_map map, mln_buffer_view source_id, mln_buffer_view source_json, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_remove_style_source (mln_map map, mln_buffer_view source_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_get_style_source (mln_map map, mln_buffer_view source_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_style_source_volatile (mln_map map, mln_buffer_view source_id, bool is_volatile, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_list_style_sources (mln_map map, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_add_geojson_source_url (mln_map map, mln_buffer_view source_id, mln_buffer_view url, const mln_geojson_source_options options, const mln_completion completion, mln_diagnostic *out_diagnostic)
mln_status	mln_geojson_source_data_create (mln_buffer_view data, const mln_geojson_source_options options, mln_geojson_source_data out_data, mln_diagnostic *out_diagnostic)
void	mln_geojson_source_data_release (mln_geojson_source_data data)
mln_status	mln_map_add_geojson_source_data (mln_map map, mln_buffer_view source_id, mln_geojson_source_data data, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_geojson_source_url (mln_map map, mln_buffer_view source_id, mln_buffer_view url, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_geojson_source_data (mln_map map, mln_buffer_view source_id, mln_geojson_source_data data, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_geojson_source_synchronous_tiling (mln_map map, mln_buffer_view source_id, bool enabled, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_add_custom_geometry_source (mln_map map, mln_buffer_view source_id, const mln_custom_geometry_source_options options, const mln_completion completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_set_custom_geometry_source_tile_data (mln_map map, mln_buffer_view source_id, mln_canonical_tile_id tile_id, mln_buffer_view data, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_custom_geometry_source_tile_error (mln_map map, mln_buffer_view source_id, mln_canonical_tile_id tile_id, mln_buffer_view message, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_invalidate_custom_geometry_source_tile (mln_map map, mln_buffer_view source_id, mln_canonical_tile_id tile_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_invalidate_custom_geometry_source_region (mln_map map, mln_buffer_view source_id, mln_lat_lng_bounds bounds, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_add_custom_mvt_vector_source (mln_map map, mln_buffer_view source_id, const mln_custom_mvt_vector_source_options options, const mln_completion completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_set_custom_mvt_vector_source_tile_data (mln_map map, mln_buffer_view source_id, mln_canonical_tile_id tile_id, mln_buffer_view data, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_custom_mvt_vector_source_tile_error (mln_map map, mln_buffer_view source_id, mln_canonical_tile_id tile_id, mln_buffer_view message, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_invalidate_custom_mvt_vector_source_tile (mln_map map, mln_buffer_view source_id, mln_canonical_tile_id tile_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_style_image (mln_map map, mln_buffer_view image_id, const mln_premultiplied_rgba8_image image, const mln_style_image_options options, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_remove_style_image (mln_map map, mln_buffer_view image_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_get_style_image (mln_map map, mln_buffer_view image_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_add_image_source_url (mln_map map, mln_buffer_view source_id, const mln_lat_lng coordinates, size_t coordinate_count, mln_buffer_view url, const mln_completion completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_add_image_source_image (mln_map map, mln_buffer_view source_id, const mln_lat_lng coordinates, size_t coordinate_count, const mln_premultiplied_rgba8_image image, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_image_source_url (mln_map map, mln_buffer_view source_id, mln_buffer_view url, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_image_source_image (mln_map map, mln_buffer_view source_id, const mln_premultiplied_rgba8_image image, const mln_completion completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_set_image_source_coordinates (mln_map map, mln_buffer_view source_id, const mln_lat_lng coordinates, size_t coordinate_count, const mln_completion completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_get_image_source_coordinates (mln_map map, mln_buffer_view source_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_add_style_layer_json (mln_map map, mln_buffer_view layer_json, mln_buffer_view before_layer_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_remove_style_layer (mln_map map, mln_buffer_view layer_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_get_style_layer (mln_map map, mln_buffer_view layer_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_list_style_layers (mln_map map, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_move_style_layer (mln_map map, mln_buffer_view layer_id, mln_buffer_view before_layer_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_get_style_layer_json (mln_map map, mln_buffer_view layer_id, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_style_light_json (mln_map map, mln_buffer_view light_json, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_style_light_property (mln_map map, mln_buffer_view property_name, mln_buffer_view value, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_get_style_light_property (mln_map map, mln_buffer_view property_name, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_style_transition_options (mln_map map, const mln_style_transition_options options, const mln_completion completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_get_style_transition_options (mln_map map, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_set_style_layer_property (mln_map map, mln_buffer_view layer_id, mln_buffer_view property_name, mln_buffer_view value, const mln_completion completion, mln_diagnostic out_diagnostic)
mln_status	mln_map_get_style_layer_property (mln_map map, mln_buffer_view layer_id, mln_buffer_view property_name, const mln_completion completion, mln_diagnostic out_diagnostic)

Detailed Description

Public C API declarations for style sources, layers, and images.

Every map mutation is a command. It copies input bytes, arrays, option structs, and image pixels before returning and applies them in runtime submission order. Each function lists submission and completion failures separately. Its completion reports committed, superseded, failed, or cancelled disposition. A command that ran, whether it committed or failed, completes with the map snapshot generation that it published, so a caller can fence a later mln_map_get_snapshot() on it.

Every query is ordered. It copies its inputs before returning and observes all commands accepted earlier by the runtime. Its completion borrows the typed result for the duration of the callback.

A query that reads a whole source, layer, or image by ID completes successfully with no value when no object has that ID. A query that reads one member of an object completes with MLN_STATUS_NOT_FOUND when the object is missing, as a command on it does, and completes with no value only when the object exists and lacks that member, such as a layer without a filter.

All declarations in this header are callable from any thread.

Typedef Documentation

◆ mln_canonical_tile_id

typedef struct mln_canonical_tile_id mln_canonical_tile_id

Canonical tile identity used by custom geometry and custom MVT vector source callbacks.

◆ mln_custom_geometry_source_option_field

typedef enum mln_custom_geometry_source_option_field mln_custom_geometry_source_option_field

Field mask values for mln_custom_geometry_source_options.

◆ mln_custom_geometry_source_options

typedef struct mln_custom_geometry_source_options mln_custom_geometry_source_options

Options for custom geometry sources.

◆ mln_custom_mvt_vector_source_option_field

typedef enum mln_custom_mvt_vector_source_option_field mln_custom_mvt_vector_source_option_field

Field mask values for mln_custom_mvt_vector_source_options.

◆ mln_custom_mvt_vector_source_options

typedef struct mln_custom_mvt_vector_source_options mln_custom_mvt_vector_source_options

Options for custom MVT vector sources.

◆ mln_custom_source_cancel_tile_callback

typedef void(*) mln_custom_source_cancel_tile_callback(void *user_data, mln_canonical_tile_id tile_id)

Cancels a request for one tile of a custom geometry or custom MVT vector source, best effort.

A source in queue mode queues a copy as an mln_custom_source_tile_delivery instead.

◆ mln_custom_source_fetch_tile_callback

typedef void(*) mln_custom_source_fetch_tile_callback(void *user_data, mln_canonical_tile_id tile_id)

Requests one tile of a custom geometry or custom MVT vector source.

A source in queue mode queues a copy as an mln_custom_source_tile_delivery instead.

◆ mln_geojson_source_option_field

typedef enum mln_geojson_source_option_field mln_geojson_source_option_field

Field mask values for mln_geojson_source_options.

◆ mln_geojson_source_options

typedef struct mln_geojson_source_options mln_geojson_source_options

Options for GeoJSON sources, indexed and rendered at a fixed 512-pixel tile size.

These options are fixed for the source's lifetime. URL updates preserve them, and prepared data updates require matching options.

◆ mln_image_content

typedef struct mln_image_content mln_image_content

Content-box insets in image pixels, measured from the image's top-left.

MapLibre places a symbol's text inside this box when icon-text-fit applies.

◆ mln_image_stretch

typedef struct mln_image_stretch mln_image_stretch

One stretchable interval along an image axis, in image pixels.

MapLibre scales only the stretchable intervals when it resizes the image, so the pixels outside them keep their size. An interval runs from a lower from to a higher to, and the intervals along one axis run in increasing order without overlapping. mln_map_set_style_image() rejects intervals that break that shape.

◆ mln_premultiplied_rgba8_image

typedef struct mln_premultiplied_rgba8_image mln_premultiplied_rgba8_image

Caller-owned premultiplied RGBA8 image pixels.

◆ mln_style_image_info

typedef struct mln_style_image_info mln_style_image_info

One complete runtime style image, borrowed for a completion callback.

pixels and the stretch arrays remain valid until the completion callback returns. A masked member whose bit is absent from fields is zero.

◆ mln_style_image_info_field

typedef enum mln_style_image_info_field mln_style_image_info_field

Field mask values for mln_style_image_info.

◆ mln_style_image_option_field

typedef enum mln_style_image_option_field mln_style_image_option_field

Field mask values for mln_style_image_options.

◆ mln_style_image_options

typedef struct mln_style_image_options mln_style_image_options

Options for runtime style images.

◆ mln_style_image_text_fit

typedef enum mln_style_image_text_fit mln_style_image_text_fit

How a stretchable image fits text along one axis.

◆ mln_style_layer_info

typedef struct mln_style_layer_info mln_style_layer_info

One style layer, borrowed for a completion callback.

Every view stays valid until the callback returns.

◆ mln_style_layer_visibility

typedef enum mln_style_layer_visibility mln_style_layer_visibility

Layer visibility values used by the visibility setter and layer info.

◆ mln_style_raster_dem_encoding

typedef enum mln_style_raster_dem_encoding mln_style_raster_dem_encoding

DEM raster encoding values.

◆ mln_style_source_info

typedef struct mln_style_source_info mln_style_source_info

Complete metadata of one style source, borrowed for a completion callback.

Views and arrays remain valid until the completion callback returns. A masked member whose bit is absent from fields is zero.

◆ mln_style_source_info_field

typedef enum mln_style_source_info_field mln_style_source_info_field

Fields available in mln_style_source_info.

◆ mln_style_source_tile_info

typedef struct mln_style_source_tile_info mln_style_source_tile_info

Inline TileJSON metadata of a tile source.

mln_style_source_info carries it when fields contains TILEJSON.

◆ mln_style_source_type

typedef enum mln_style_source_type mln_style_source_type

Style source type values returned by source metadata queries.

◆ mln_style_tile_scheme

typedef enum mln_style_tile_scheme mln_style_tile_scheme

Tile URL coordinate scheme values.

◆ mln_style_transition_option_field

typedef enum mln_style_transition_option_field mln_style_transition_option_field

Field mask values for mln_style_transition_options.

◆ mln_style_transition_options

typedef struct mln_style_transition_options mln_style_transition_options

Global style transition options.

These control how the style animates paint property changes and whether symbol placement changes cross-fade. They are distinct from camera animation options, which time camera moves.

A paint property's own style-spec transition, such as "fill-color-transition", overrides these for that property. These apply to every property that declares none.

◆ mln_style_vector_tile_encoding

typedef enum mln_style_vector_tile_encoding mln_style_vector_tile_encoding

Vector tile encoding values.

Enumeration Type Documentation

◆ mln_custom_geometry_source_option_field

enum mln_custom_geometry_source_option_field : uint32_t

Field mask values for mln_custom_geometry_source_options.

◆ mln_custom_mvt_vector_source_option_field

enum mln_custom_mvt_vector_source_option_field : uint32_t

Field mask values for mln_custom_mvt_vector_source_options.

◆ mln_geojson_source_option_field

enum mln_geojson_source_option_field : uint32_t

Field mask values for mln_geojson_source_options.

◆ mln_style_image_info_field

enum mln_style_image_info_field : uint32_t

Field mask values for mln_style_image_info.

Enumerator
MLN_STYLE_IMAGE_INFO_CONTENT	The image declares a content box.
MLN_STYLE_IMAGE_INFO_TEXT_FIT_WIDTH	The image declares a horizontal text-fit mode.
MLN_STYLE_IMAGE_INFO_TEXT_FIT_HEIGHT	The image declares a vertical text-fit mode.

◆ mln_style_image_option_field

enum mln_style_image_option_field : uint32_t

Field mask values for mln_style_image_options.

◆ mln_style_image_text_fit

enum mln_style_image_text_fit : uint32_t

How a stretchable image fits text along one axis.

◆ mln_style_layer_visibility

enum mln_style_layer_visibility : uint32_t

Layer visibility values used by the visibility setter and layer info.

◆ mln_style_raster_dem_encoding

enum mln_style_raster_dem_encoding : uint32_t

DEM raster encoding values.

◆ mln_style_source_info_field

enum mln_style_source_info_field : uint32_t

Fields available in mln_style_source_info.

Enumerator
MLN_STYLE_SOURCE_INFO_URL	The source retains a URL.
MLN_STYLE_SOURCE_INFO_TILEJSON	The tile source was defined with an inline TileJSON description.
MLN_STYLE_SOURCE_INFO_BOUNDS	The inline TileJSON description contains geographic bounds.
MLN_STYLE_SOURCE_INFO_TILE_SIZE	The source exposes a tile size.
MLN_STYLE_SOURCE_INFO_VECTOR_ENCODING	The source exposes a vector tile encoding.
MLN_STYLE_SOURCE_INFO_RASTER_ENCODING	The source exposes a DEM raster encoding.
MLN_STYLE_SOURCE_INFO_ATTRIBUTION	The source carries an attribution string, which may be empty.

◆ mln_style_source_type

enum mln_style_source_type : uint32_t

Style source type values returned by source metadata queries.

◆ mln_style_tile_scheme

enum mln_style_tile_scheme : uint32_t

Tile URL coordinate scheme values.

◆ mln_style_transition_option_field

enum mln_style_transition_option_field : uint32_t

Field mask values for mln_style_transition_options.

◆ mln_style_vector_tile_encoding

enum mln_style_vector_tile_encoding : uint32_t

Vector tile encoding values.

Function Documentation

◆ mln_custom_geometry_source_options_default()

mln_custom_geometry_source_options mln_custom_geometry_source_options_default ( void )

Returns default custom geometry source options.

◆ mln_custom_mvt_vector_source_options_default()

mln_custom_mvt_vector_source_options mln_custom_mvt_vector_source_options_default ( void )

Returns default custom MVT vector source options.

◆ mln_geojson_source_data_create()

mln_status mln_geojson_source_data_create	(	mln_buffer_view	data,
		const mln_geojson_source_options *	options,
		mln_geojson_source_data *	out_data,
		mln_diagnostic *	out_diagnostic )

Prepares GeoJSON source data for installation on a map.

data contains UTF-8 GeoJSON. data and options are borrowed for the call. Preparation finishes before return. options may be null for defaults and must match the options of every source the data is installed on.

When options enable clustering, the data must be a feature collection whose every feature carries point geometry. Data that does not is rejected, and the diagnostic names the constraint.

The prepared data is immutable and independent of any map or runtime. Preparation, installation, and release may happen on different threads.

*out_data must be MLN_HANDLE_NULL on entry. On success it receives an owned handle the host releases with mln_geojson_source_data_release(). Installing the data borrows the handle, so one prepared handle may be installed on any number of sources and released at any time afterward.

Returns:

MLN_STATUS_OK on success.
MLN_STATUS_INVALID_ARGUMENT when data is empty or invalid, options is invalid, out_data is null or *out_data is not MLN_HANDLE_NULL, or clustering is enabled and the data is a bare geometry or a single feature, or a feature carries geometry other than a point.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_geojson_source_data_release()

void mln_geojson_source_data_release ( mln_geojson_source_data data )

Releases prepared GeoJSON source data.

Callable from any thread. A null or already-released handle is a no-op. Sources the data was installed on keep their own reference, so releasing the handle preserves each source.

◆ mln_geojson_source_options_default()

mln_geojson_source_options mln_geojson_source_options_default ( void )

Returns default GeoJSON source options.

◆ mln_map_add_custom_geometry_source()

mln_status mln_map_add_custom_geometry_source	(	mln_map	map,
		mln_buffer_view	source_id,
		const mln_custom_geometry_source_options *	options,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Adds a custom geometry source.

source_id is borrowed for the call. options is borrowed for the call, but the callback function pointers and user_data pointer are retained by value. The callback functions and user_data must remain valid until the source is removed, the style is replaced, or the map is destroyed, and until any in-flight callback invocation has returned. For URL loads, style replacement occurs when the new style loads, not when the load request is accepted. For inline JSON loads, style replacement completes when mln_map_set_style_json() commits.

fetch_tile and cancel_tile may run on arbitrary native worker threads, may be concurrent with runtime and map calls. The style command functions in this header may be called directly from these callbacks. Callbacks must not block waiting for command execution. Every callback returns normally; see mln_user_data_release. cancel_tile is best-effort and may be repeated or race with fetch_tile.

Custom geometry sources belong to the current style. Replacing the style drops sources that were added to the previous style.

A host that owns callback state frees it in options.release_user_data, which this API invokes once after it stops referencing user_data. See mln_custom_geometry_source_options.release_user_data.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, options is null or invalid, or options sets neither or both of fetch_tile and queue.
MLN_STATUS_INVALID_STATE when map or options->queue has been released, or the map is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when a source already has that ID. This API runs release_user_data once.

◆ mln_map_add_custom_mvt_vector_source()

mln_status mln_map_add_custom_mvt_vector_source	(	mln_map	map,
		mln_buffer_view	source_id,
		const mln_custom_mvt_vector_source_options *	options,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Adds a custom MVT vector source.

source_id is borrowed for the call. options is borrowed for the call, but the callback function pointers and user_data pointer are retained by value. The callback functions and user_data must remain valid until the source is removed, the style is replaced, or the map is destroyed, and until any in-flight callback invocation has returned. For URL loads, style replacement occurs when the new style loads, not when the load request is accepted. For inline JSON loads, style replacement completes when mln_map_set_style_json() commits.

fetch_tile and cancel_tile may run on arbitrary native worker threads, may be concurrent with runtime and map calls. The style command functions in this header, including the tile-delivery commands below, may be called directly from these callbacks. Callbacks must not block waiting for command execution. Every callback returns normally; see mln_user_data_release. cancel_tile is best-effort and may be repeated or race with fetch_tile.

Custom MVT vector sources belong to the current style. Replacing the style drops sources that were added to the previous style. A layer that draws this source names a source-layer that exists inside the MVT bytes the host delivers.

A host that owns callback state frees it in options.release_user_data, which this API invokes once after it stops referencing user_data. See mln_custom_mvt_vector_source_options.release_user_data.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, options is null or invalid, or options sets neither or both of fetch_tile and queue.
MLN_STATUS_INVALID_STATE when map or options->queue has been released, or the map is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when a source already has that ID. This API runs release_user_data once.

◆ mln_map_add_geojson_source_data()

mln_status mln_map_add_geojson_source_data	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_geojson_source_data	data,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Adds a GeoJSON source with prepared inline data.

source_id is borrowed for the call. data names a live handle from mln_geojson_source_data_create(); the call borrows the handle, and the source adopts the options the data was prepared with, fixed for the lifetime of the source.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, or data is an invalid handle.
MLN_STATUS_INVALID_STATE when map or data has been released, or the map is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when a source already has that ID.

◆ mln_map_add_geojson_source_url()

mln_status mln_map_add_geojson_source_url	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_buffer_view	url,
		const mln_geojson_source_options *	options,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Adds a GeoJSON source with URL data.

source_id, url, and options are borrowed for the call. The source loads GeoJSON from url through MapLibre Native's resource system. options may be null for defaults, and the options are fixed for the lifetime of the source.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id or url is invalid or empty, or options is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when a source already has that ID, or the options cannot be converted.

◆ mln_map_add_image_source_image()

mln_status mln_map_add_image_source_image	(	mln_map	map,
		mln_buffer_view	source_id,
		const mln_lat_lng *	coordinates,
		size_t	coordinate_count,
		const mln_premultiplied_rgba8_image *	image,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Adds an image source with inline image pixels.

source_id, coordinates, image, and image pixels are borrowed for the call. coordinates must contain exactly four coordinates in top-left, top-right, bottom-right, bottom-left order. The coordinates and pixels are copied before return.

Image sources belong to the current style. Loading another style URL or JSON document drops sources that were added to the previous style.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, coordinates is null or invalid, coordinate_count is not 4, image is invalid, image pixels are null, image dimensions or stride are invalid, or image byte_length is too small.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when a source already has that ID.

◆ mln_map_add_image_source_url()

mln_status mln_map_add_image_source_url	(	mln_map	map,
		mln_buffer_view	source_id,
		const mln_lat_lng *	coordinates,
		size_t	coordinate_count,
		mln_buffer_view	url,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Adds an image source that loads its image from a URL.

source_id, coordinates, and url are borrowed for the call. coordinates must contain exactly four coordinates in top-left, top-right, bottom-right, bottom-left order. The strings and coordinates are copied before return. Later URL load or decode failures are reported through runtime events.

Image sources belong to the current style. Loading another style URL or JSON document drops sources that were added to the previous style.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id or url is invalid or empty, coordinates is null or invalid, or coordinate_count is not 4.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when a source already has that ID.

◆ mln_map_add_style_layer_json()

mln_status mln_map_add_style_layer_json	(	mln_map	map,
		mln_buffer_view	layer_json,
		mln_buffer_view	before_layer_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Adds one style layer from a full style-spec layer JSON object.

layer_json and before_layer_id are borrowed for the call. layer_json must contain id and type members. Passing an empty before_layer_id appends the layer; otherwise the layer is inserted before that existing layer.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, layer_json is empty or invalid, before_layer_id is invalid, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when before_layer_id is non-empty and no style layer has it, or the layer requires a source no style source has.
MLN_STATUS_INVALID_ARGUMENT when the layer JSON cannot be converted, or a layer already has the JSON's id, or the source does not support the layer type.

◆ mln_map_add_style_source_json()

mln_status mln_map_add_style_source_json	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_buffer_view	source_json,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Adds one style source from a style-spec source JSON object.

Vector sources with a TileJSON URL accept minzoom, maxzoom, and encoding ("mvt" or "mlt") in the source JSON. These fields override the loaded TileJSON. For example: {"type":"vector","url":"https://tiles.example/source.json", "minzoom":2,"maxzoom":14,"encoding":"mlt"}.

source_id and source_json are borrowed for the call and copied before return. source_json is the object that appears under sources[source_id] in a style document.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, source_json is empty or invalid, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when a source already has that ID, or the source JSON cannot be converted.

◆ mln_map_get_global_state()

mln_status mln_map_get_global_state	(	mln_map	map,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Queries the global-state JSON object, including style defaults. Completion borrows one mln_buffer_view for the duration of the callback.

Returns:

MLN_STATUS_OK when accepted.
MLN_STATUS_INVALID_ARGUMENT for an invalid map handle or completion.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_map_get_image_source_coordinates()

mln_status mln_map_get_image_source_coordinates	(	mln_map	map,
		mln_buffer_view	source_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Copies image source coordinates.

The completion borrows four mln_lat_lng values in top-left, top-right, bottom-right, bottom-left order.

Returns:

MLN_STATUS_OK when the query was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not an image source.

◆ mln_map_get_style_image()

mln_status mln_map_get_style_image	(	mln_map	map,
		mln_buffer_view	image_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Copies one complete runtime style image.

A found image completes with one borrowed mln_style_image_info that includes its pixels and stretch intervals. A missing image completes successfully with no value. Copy retained pixels and intervals before the callback returns.

Returns:

MLN_STATUS_OK when the query was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, image_id is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_map_get_style_layer()

mln_status mln_map_get_style_layer	(	mln_map	map,
		mln_buffer_view	layer_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Copies the complete metadata of one style layer.

A found layer completes with one borrowed mln_style_layer_info whose id is the requested ID. A missing layer completes successfully with no value. Copy retained views before the callback returns.

Returns:

MLN_STATUS_OK when the query was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, layer_id is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_map_get_style_layer_json()

mln_status mln_map_get_style_layer_json	(	mln_map	map,
		mln_buffer_view	layer_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Serializes one style layer as a full style-spec layer JSON object.

A found layer completes with one borrowed mln_buffer_view. A missing layer completes successfully with no value.

Returns:

MLN_STATUS_OK when the query was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, layer_id is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_map_get_style_layer_property()

mln_status mln_map_get_style_layer_property	(	mln_map	map,
		mln_buffer_view	layer_id,
		mln_buffer_view	property_name,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Serializes one layer property as a style-spec JSON value.

A defined property completes with one borrowed mln_buffer_view. An undefined property completes successfully with no value.

Paint and layout property names are unprefixed. The root keys filter, source, source-layer, minzoom, and maxzoom use the layer's serialized values. An unset filter, an empty source or source-layer, and an unbounded minzoom or maxzoom complete successfully with no value.

Returns:

MLN_STATUS_OK when the query was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, layer_id or property_name is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style layer has that ID.

◆ mln_map_get_style_light_property()

mln_status mln_map_get_style_light_property	(	mln_map	map,
		mln_buffer_view	property_name,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Serializes one style light property as a style-spec JSON value.

A defined property completes with one borrowed mln_buffer_view. An undefined property completes successfully with no value.

Returns:

MLN_STATUS_OK when the query was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, property_name is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_map_get_style_source()

mln_status mln_map_get_style_source	(	mln_map	map,
		mln_buffer_view	source_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Copies the complete metadata of one style source.

A found source completes with one borrowed mln_style_source_info that includes its attribution, URL, and inline TileJSON tile URLs. A missing source completes successfully with no value. Copy retained views before the callback returns.

Returns:

MLN_STATUS_OK when the query was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_map_get_style_transition_options()

mln_status mln_map_get_style_transition_options	(	mln_map	map,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Reads the style's global transition options.

The completion borrows the last-known transition configuration. Duration and delay report through their field-mask bits and may be unset.

A map that has loaded no style yet reports duration and delay unset. A style carrying no "transition" member reports a 300 millisecond duration, while a style carrying one reports only the members that object names, so a style whose transition declares a delay alone reports no duration. Read the field-mask bits rather than assuming a loaded style sets either.

MLN_STYLE_TRANSITION_OPTION_ENABLE_PLACEMENT_TRANSITIONS is always set on return and reports nothing about the field.

Returns:

MLN_STATUS_OK when the query was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_map_invalidate_custom_geometry_source_region()

mln_status mln_map_invalidate_custom_geometry_source_region	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_lat_lng_bounds	bounds,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Invalidates custom geometry source data inside one geographic region.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, bounds is invalid, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not a custom geometry source.

◆ mln_map_invalidate_custom_geometry_source_tile()

mln_status mln_map_invalidate_custom_geometry_source_tile	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_canonical_tile_id	tile_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Invalidates custom geometry source data for one canonical tile.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, tile_id is invalid, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not a custom geometry source.

◆ mln_map_invalidate_custom_mvt_vector_source_tile()

mln_status mln_map_invalidate_custom_mvt_vector_source_tile	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_canonical_tile_id	tile_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Invalidates custom MVT vector source data for one canonical tile.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, tile_id is invalid, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not a custom MVT vector source.

◆ mln_map_list_style_layers()

mln_status mln_map_list_style_layers	(	mln_map	map,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts an ordered query of every style layer in style order.

The completion borrows value_count mln_style_layer_info values, value_size bytes apart, in style order. Copy retained entries and their views before the callback returns.

Returns:

MLN_STATUS_OK when the query was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_map_list_style_sources()

mln_status mln_map_list_style_sources	(	mln_map	map,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Lists every style source in style order.

The completion borrows value_count mln_style_source_info values, value_size bytes apart, one per source: the sources the style document declares, in its order, then added sources in the order they were added. Copy retained entries, their views, and their tile URLs before the callback returns.

Returns:

MLN_STATUS_OK when the query was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_map_move_style_layer()

mln_status mln_map_move_style_layer	(	mln_map	map,
		mln_buffer_view	layer_id,
		mln_buffer_view	before_layer_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Moves one style layer before another layer or to the top.

layer_id and before_layer_id are borrowed for the call. Passing an empty before_layer_id moves the layer to the top of the style order.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, layer_id is invalid or empty, before_layer_id is invalid, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style layer has layer_id, or before_layer_id is non-empty and no style layer has it.

◆ mln_map_remove_style_image()

mln_status mln_map_remove_style_image	(	mln_map	map,
		mln_buffer_view	image_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Removes one runtime style image by ID.

image_id is borrowed for the call. The command commits when an image with that ID existed and was removed.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, image_id is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no runtime style image has that ID.

◆ mln_map_remove_style_layer()

mln_status mln_map_remove_style_layer	(	mln_map	map,
		mln_buffer_view	layer_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Removes one style layer by ID.

layer_id is borrowed for the call. The command commits when a layer with that ID existed and was removed.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, layer_id is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style layer has that ID.

◆ mln_map_remove_style_source()

mln_status mln_map_remove_style_source	(	mln_map	map,
		mln_buffer_view	source_id,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Removes one style source by ID.

source_id is borrowed for the call. The command commits when a source with that ID existed and was removed.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_STATE when the source exists but a layer still uses it.

◆ mln_map_set_custom_geometry_source_tile_data()

mln_status mln_map_set_custom_geometry_source_tile_data	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_canonical_tile_id	tile_id,
		mln_buffer_view	data,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Sets custom geometry source data for one canonical tile.

source_id and the UTF-8 GeoJSON data are borrowed for the call and copied before return.

MapLibre ignores the data unless fetch_tile requested that tile and cancel_tile has not cancelled it since. This call still returns MLN_STATUS_OK after validation.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, tile_id is invalid, data is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the data is not valid GeoJSON, or the source is not a custom geometry source.

◆ mln_map_set_custom_geometry_source_tile_error()

mln_status mln_map_set_custom_geometry_source_tile_error	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_canonical_tile_id	tile_id,
		mln_buffer_view	message,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Reports a custom geometry source error for one canonical tile.

source_id and the UTF-8 diagnostic message are borrowed for the call. The function copies accepted bytes before return. An empty message is accepted.

MapLibre ignores the error unless fetch_tile requested that tile and cancel_tile has not cancelled it since. This call still returns MLN_STATUS_OK after validation. The tile stays failed until the host delivers its data or invalidates it, which fetches it again.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, tile_id is invalid, message is a null pointer with a nonzero size, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not a custom geometry source.

◆ mln_map_set_custom_mvt_vector_source_tile_data()

mln_status mln_map_set_custom_mvt_vector_source_tile_data	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_canonical_tile_id	tile_id,
		mln_buffer_view	data,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Sets custom MVT vector source data for one canonical tile.

source_id and the MVT protobuf bytes are borrowed for the call. The function copies accepted bytes before return. A zero-length view, including a null pointer with size 0, is an empty tile.

MapLibre ignores the bytes unless fetch_tile requested that tile and cancel_tile has not cancelled it since. This call still returns MLN_STATUS_OK after validation.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, tile_id is invalid, data is a null pointer with a nonzero size, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not a custom MVT vector source.

◆ mln_map_set_custom_mvt_vector_source_tile_error()

mln_status mln_map_set_custom_mvt_vector_source_tile_error	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_canonical_tile_id	tile_id,
		mln_buffer_view	message,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Reports a custom MVT vector source error for one canonical tile.

source_id and the UTF-8 diagnostic message are borrowed for the call. The function copies accepted bytes before return. An empty message is accepted.

MapLibre ignores the error unless fetch_tile requested that tile and cancel_tile has not cancelled it since. This call still returns MLN_STATUS_OK after validation. The tile stays failed until the host delivers its data or invalidates it, which fetches it again.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, tile_id is invalid, message is a null pointer with a nonzero size, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not a custom MVT vector source.

◆ mln_map_set_geojson_source_data()

mln_status mln_map_set_geojson_source_data	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_geojson_source_data	data,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Updates one GeoJSON source with prepared inline data.

source_id is borrowed for the call. data names a live handle from mln_geojson_source_data_create(); the call borrows the handle and retains prepared data before returning.

The data must have been prepared with options equal to the options the source was added with. Cluster aggregation expressions compare by parsed equality, so equivalent cluster_properties JSON matches regardless of formatting. A mismatch is rejected.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, data is an invalid handle, or completion is invalid.
MLN_STATUS_INVALID_STATE when map or data has been released, or the map is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not a GeoJSON source, or the data was prepared with options that do not match the source's options.

◆ mln_map_set_geojson_source_synchronous_tiling()

mln_status mln_map_set_geojson_source_synchronous_tiling	(	mln_map	map,
		mln_buffer_view	source_id,
		bool	enabled,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Overrides one GeoJSON source's synchronous tiling at runtime.

source_id is borrowed for the call. While enabled is true, the source behaves as if its options had set synchronous_tiling; false restores the option the source was added with. The override applies to render updates after the command commits.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not a GeoJSON source.

◆ mln_map_set_geojson_source_url()

mln_status mln_map_set_geojson_source_url	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_buffer_view	url,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Updates one GeoJSON source to load data from a URL.

source_id and url are borrowed for the call. The source keeps the mln_geojson_source_options it was added with.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id or url is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not a GeoJSON source.

◆ mln_map_set_global_state_property()

mln_status mln_map_set_global_state_property	(	mln_map	map,
		mln_buffer_view	property_name,
		mln_buffer_view	value,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Submits a global-state JSON value. JSON null restores the style default.

Returns:

MLN_STATUS_OK when accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, property_name is invalid, value is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when value is not valid JSON.
MLN_STATUS_INVALID_STATE when the style has not loaded.

◆ mln_map_set_image_source_coordinates()

mln_status mln_map_set_image_source_coordinates	(	mln_map	map,
		mln_buffer_view	source_id,
		const mln_lat_lng *	coordinates,
		size_t	coordinate_count,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Updates image source coordinates.

coordinates is borrowed for the call and copied before return, and must contain exactly four coordinates in top-left, top-right, bottom-right, bottom-left order.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, coordinates is null or invalid, coordinate_count is not 4, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not an image source.

◆ mln_map_set_image_source_image()

mln_status mln_map_set_image_source_image	(	mln_map	map,
		mln_buffer_view	source_id,
		const mln_premultiplied_rgba8_image *	image,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Updates an image source with inline image pixels.

source_id, image, and image pixels are borrowed for the call and copied before return.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, image is invalid, image pixels are null, image dimensions or stride are invalid, image byte_length is too small, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not an image source.

◆ mln_map_set_image_source_url()

mln_status mln_map_set_image_source_url	(	mln_map	map,
		mln_buffer_view	source_id,
		mln_buffer_view	url,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Updates an image source to load its image from a URL.

source_id and url are borrowed for the call. Later URL load or decode failures are reported through runtime events.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id or url is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.
MLN_STATUS_INVALID_ARGUMENT when the source is not an image source.

◆ mln_map_set_style_image()

mln_status mln_map_set_style_image	(	mln_map	map,
		mln_buffer_view	image_id,
		const mln_premultiplied_rgba8_image *	image,
		const mln_style_image_options *	options,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Sets one runtime style image.

image_id, image, and image pixels are borrowed for the call and copied before return. If image_id already exists, the image is replaced when the command commits.

Runtime style images belong to the current style. Loading another style URL or JSON document drops images that were added to the previous style.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, image_id is invalid or empty, image or options is invalid, image pixels are null, image dimensions or stride are invalid, or image byte_length is too small.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

◆ mln_map_set_style_layer_property()

mln_status mln_map_set_style_layer_property	(	mln_map	map,
		mln_buffer_view	layer_id,
		mln_buffer_view	property_name,
		mln_buffer_view	value,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Sets one layer property using its MapLibre style-spec property name.

layer_id, property_name, and value are borrowed for the call. value is a style-spec JSON value; expressions use style-spec expression JSON arrays. Paint and layout property names are unprefixed. The root keys filter, source, source-layer, minzoom, and maxzoom are also supported.

JSON null clears a filter and resets minzoom or maxzoom to an unbounded range (-INFINITY or INFINITY). For paint and layout properties, JSON null restores the property's default. source and source-layer take JSON strings; an empty source-layer string clears it. A source ID may name a source that has not been added yet. Zoom values are rounded to single precision.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, layer_id or property_name is invalid or empty, value is empty or invalid, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style layer has that ID.
MLN_STATUS_INVALID_ARGUMENT when the property name is unknown for that layer, the value cannot be converted for that property, or source or source-layer is set on a layer type that takes no source.

◆ mln_map_set_style_light_json()

mln_status mln_map_set_style_light_json	(	mln_map	map,
		mln_buffer_view	light_json,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Sets the style light from a style-spec light JSON object.

light_json is borrowed for the call.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, light_json is empty or invalid, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when the light JSON cannot be converted.

◆ mln_map_set_style_light_property()

mln_status mln_map_set_style_light_property	(	mln_map	map,
		mln_buffer_view	property_name,
		mln_buffer_view	value,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Sets one style light property using its MapLibre style-spec property name.

property_name and value are borrowed for the call. value is a style-spec JSON value.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, property_name is invalid or empty, value is empty or invalid, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when the property name is unknown, or the value cannot be converted for that property.

◆ mln_map_set_style_source_volatile()

mln_status mln_map_set_style_source_volatile	(	mln_map	map,
		mln_buffer_view	source_id,
		bool	is_volatile,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Sets whether one style source stores fetched tiles in the persistent cache.

source_id is copied before acceptance. When is_volatile is true, sources that fetch tiles stop storing them in persistent storage. Other source types retain the value for inspection without changing how they load. The change applies when the command commits and is visible through mln_map_get_style_source as is_volatile.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, source_id is invalid or empty, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_NOT_FOUND when no style source has that ID.

◆ mln_map_set_style_transition_options()

mln_status mln_map_set_style_transition_options	(	mln_map	map,
		const mln_style_transition_options *	options,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Sets the style's global transition options.

options is borrowed for the call and copied before return. When the command commits, omitted duration and delay fields clear the style-wide override. The command replaces the whole transition configuration.

Loading a style replaces these options with the ones that style declares, so a host that overrides them applies the override after the style loads.

Returns:

MLN_STATUS_OK when the command was accepted.
MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, options is null or undersized, or completion is invalid.
MLN_STATUS_INVALID_STATE when map has been released or is closing.
MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

MLN_STATUS_INVALID_ARGUMENT when options->fields contains unknown bits, or an enabled duration or delay is negative, non-finite, or too long to represent. A rejected command changes nothing.
MLN_STATUS_NATIVE_ERROR when applying the options fails.

◆ mln_premultiplied_rgba8_image_default()

mln_premultiplied_rgba8_image mln_premultiplied_rgba8_image_default ( void )

Returns a default premultiplied RGBA8 image descriptor.

◆ mln_style_image_options_default()

mln_style_image_options mln_style_image_options_default ( void )

Returns default runtime style image options.

◆ mln_style_transition_options_default()

mln_style_transition_options mln_style_transition_options_default ( void )

Returns default global style transition options.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ mln_canonical_tile_id

◆ mln_custom_geometry_source_option_field

◆ mln_custom_geometry_source_options

◆ mln_custom_mvt_vector_source_option_field

◆ mln_custom_mvt_vector_source_options

◆ mln_custom_source_cancel_tile_callback

◆ mln_custom_source_fetch_tile_callback

◆ mln_geojson_source_option_field

◆ mln_geojson_source_options

◆ mln_image_content

◆ mln_image_stretch

◆ mln_premultiplied_rgba8_image

◆ mln_style_image_info

◆ mln_style_image_info_field

◆ mln_style_image_option_field

◆ mln_style_image_options

◆ mln_style_image_text_fit

◆ mln_style_layer_info

◆ mln_style_layer_visibility

◆ mln_style_raster_dem_encoding

◆ mln_style_source_info

◆ mln_style_source_info_field

◆ mln_style_source_tile_info

◆ mln_style_source_type

◆ mln_style_tile_scheme

◆ mln_style_transition_option_field

◆ mln_style_transition_options

◆ mln_style_vector_tile_encoding

Enumeration Type Documentation

◆ mln_custom_geometry_source_option_field

◆ mln_custom_mvt_vector_source_option_field

◆ mln_geojson_source_option_field

◆ mln_style_image_info_field

◆ mln_style_image_option_field

◆ mln_style_image_text_fit

◆ mln_style_layer_visibility

◆ mln_style_raster_dem_encoding

◆ mln_style_source_info_field

◆ mln_style_source_type

◆ mln_style_tile_scheme

◆ mln_style_transition_option_field

◆ mln_style_vector_tile_encoding

Function Documentation

◆ mln_custom_geometry_source_options_default()

◆ mln_custom_mvt_vector_source_options_default()

◆ mln_geojson_source_data_create()

◆ mln_geojson_source_data_release()

◆ mln_geojson_source_options_default()

◆ mln_map_add_custom_geometry_source()

◆ mln_map_add_custom_mvt_vector_source()

◆ mln_map_add_geojson_source_data()

◆ mln_map_add_geojson_source_url()

◆ mln_map_add_image_source_image()

◆ mln_map_add_image_source_url()

◆ mln_map_add_style_layer_json()

◆ mln_map_add_style_source_json()

◆ mln_map_get_global_state()

◆ mln_map_get_image_source_coordinates()

◆ mln_map_get_style_image()

◆ mln_map_get_style_layer()

◆ mln_map_get_style_layer_json()

◆ mln_map_get_style_layer_property()

◆ mln_map_get_style_light_property()

◆ mln_map_get_style_source()

◆ mln_map_get_style_transition_options()

◆ mln_map_invalidate_custom_geometry_source_region()

◆ mln_map_invalidate_custom_geometry_source_tile()

◆ mln_map_invalidate_custom_mvt_vector_source_tile()

◆ mln_map_list_style_layers()

◆ mln_map_list_style_sources()

◆ mln_map_move_style_layer()

◆ mln_map_remove_style_image()

◆ mln_map_remove_style_layer()

◆ mln_map_remove_style_source()