map.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_map_options
struct	mln_screen_point
struct	mln_edge_insets
struct	mln_camera_options
struct	mln_unit_bezier
struct	mln_animation_options
struct	mln_camera_fit_options
struct	mln_vec3
struct	mln_quaternion
struct	mln_free_camera_options
struct	mln_lat_lng
struct	mln_feature_state_selector
struct	mln_lat_lng_bounds
struct	mln_bound_options
struct	mln_offline_tile_pyramid_region_definition
struct	mln_offline_geometry_region_definition
struct	mln_offline_region_definition
struct	mln_offline_region_info
struct	mln_projected_meters
struct	mln_projection_mode
struct	mln_map_viewport_options
struct	mln_map_tile_options

Typedefs
typedef enum mln_camera_option_field	mln_camera_option_field
typedef enum mln_animation_option_field	mln_animation_option_field
typedef enum mln_camera_fit_option_field	mln_camera_fit_option_field
typedef enum mln_bound_option_field	mln_bound_option_field
typedef enum mln_free_camera_option_field	mln_free_camera_option_field
typedef enum mln_projection_mode_field	mln_projection_mode_field
typedef enum mln_map_debug_option	mln_map_debug_option
typedef enum mln_north_orientation	mln_north_orientation
typedef enum mln_constrain_mode	mln_constrain_mode
typedef enum mln_viewport_mode	mln_viewport_mode
typedef enum mln_map_viewport_option_field	mln_map_viewport_option_field
typedef enum mln_tile_lod_mode	mln_tile_lod_mode
typedef enum mln_map_tile_option_field	mln_map_tile_option_field
typedef enum mln_map_mode	mln_map_mode
typedef struct mln_map_options	mln_map_options
typedef struct mln_screen_point	mln_screen_point
typedef struct mln_edge_insets	mln_edge_insets
typedef struct mln_camera_options	mln_camera_options
typedef struct mln_unit_bezier	mln_unit_bezier
typedef struct mln_animation_options	mln_animation_options
typedef struct mln_camera_fit_options	mln_camera_fit_options
typedef struct mln_vec3	mln_vec3
typedef struct mln_quaternion	mln_quaternion
typedef struct mln_free_camera_options	mln_free_camera_options
typedef struct mln_lat_lng	mln_lat_lng
typedef enum mln_feature_state_selector_field	mln_feature_state_selector_field
typedef struct mln_feature_state_selector	mln_feature_state_selector
typedef struct mln_lat_lng_bounds	mln_lat_lng_bounds
typedef struct mln_bound_options	mln_bound_options
typedef struct mln_offline_tile_pyramid_region_definition	mln_offline_tile_pyramid_region_definition
typedef struct mln_offline_geometry_region_definition	mln_offline_geometry_region_definition
typedef struct mln_offline_region_definition	mln_offline_region_definition
typedef struct mln_offline_region_info	mln_offline_region_info
typedef struct mln_projected_meters	mln_projected_meters
typedef struct mln_projection_mode	mln_projection_mode
typedef struct mln_map_viewport_options	mln_map_viewport_options
typedef struct mln_map_tile_options	mln_map_tile_options

Enumerations
enum	mln_camera_option_field : uint32_t
enum	mln_animation_option_field : uint32_t
enum	mln_camera_fit_option_field : uint32_t
enum	mln_bound_option_field : uint32_t { MLN_BOUND_OPTION_BOUNDS = 1U << 0U , MLN_BOUND_OPTION_MIN_ZOOM = 1U << 1U , MLN_BOUND_OPTION_MAX_ZOOM = 1U << 2U , MLN_BOUND_OPTION_MIN_PITCH = 1U << 3U , MLN_BOUND_OPTION_MAX_PITCH = 1U << 4U , MLN_BOUND_OPTION_UNBOUNDED = 1U << 5U }
enum	mln_free_camera_option_field : uint32_t
enum	mln_projection_mode_field : uint32_t
enum	mln_map_debug_option : uint32_t
enum	mln_north_orientation : uint32_t
enum	mln_constrain_mode : uint32_t
enum	mln_viewport_mode : uint32_t
enum	mln_map_viewport_option_field : uint32_t
enum	mln_tile_lod_mode : uint32_t
enum	mln_map_tile_option_field : uint32_t
enum	mln_map_mode : uint32_t { MLN_MAP_MODE_CONTINUOUS = 0 , MLN_MAP_MODE_STATIC = 1 , MLN_MAP_MODE_TILE = 2 }
enum	mln_feature_state_selector_field : uint32_t

Functions
mln_status	mln_runtime_offline_region_create_start (mln_runtime runtime, const mln_offline_region_definition *definition, const uint8_t *metadata, size_t metadata_size, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_get_start (mln_runtime runtime, mln_offline_region_id region_id, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_regions_list_start (mln_runtime runtime, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_regions_merge_database_start (mln_runtime runtime, const char *side_database_path, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_update_metadata_start (mln_runtime runtime, mln_offline_region_id region_id, const uint8_t *metadata, size_t metadata_size, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_get_status_start (mln_runtime runtime, mln_offline_region_id region_id, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_set_observed_start (mln_runtime runtime, mln_offline_region_id region_id, bool observed, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_set_download_state_start (mln_runtime runtime, mln_offline_region_id region_id, uint32_t state, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_invalidate_start (mln_runtime runtime, mln_offline_region_id region_id, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_delete_start (mln_runtime runtime, mln_offline_region_id region_id, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_create_take_result (mln_runtime runtime, mln_offline_operation_id operation_id, mln_offline_region_snapshot *out_region)
mln_status	mln_runtime_offline_region_get_take_result (mln_runtime runtime, mln_offline_operation_id operation_id, mln_offline_region_snapshot *out_region, bool *out_found)
mln_status	mln_runtime_offline_regions_list_take_result (mln_runtime runtime, mln_offline_operation_id operation_id, mln_offline_region_list *out_regions)
mln_status	mln_runtime_offline_regions_merge_database_take_result (mln_runtime runtime, mln_offline_operation_id operation_id, mln_offline_region_list *out_regions)
mln_status	mln_runtime_offline_region_update_metadata_take_result (mln_runtime runtime, mln_offline_operation_id operation_id, mln_offline_region_snapshot *out_region)
mln_status	mln_runtime_offline_region_get_status_take_result (mln_runtime runtime, mln_offline_operation_id operation_id, mln_offline_region_status *out_status)
mln_status	mln_offline_region_snapshot_get (mln_offline_region_snapshot snapshot, mln_offline_region_info *out_info)
void	mln_offline_region_snapshot_destroy (mln_offline_region_snapshot snapshot)
mln_status	mln_offline_region_list_count (mln_offline_region_list list, size_t *out_count)
mln_status	mln_offline_region_list_get (mln_offline_region_list list, size_t index, mln_offline_region_info *out_info)
void	mln_offline_region_list_destroy (mln_offline_region_list list)
mln_map_options	mln_map_options_default (void)
mln_status	mln_map_create (mln_runtime runtime, const mln_map_options *options, mln_map *out_map)
mln_status	mln_map_get_size (mln_map map, uint32_t *out_width, uint32_t *out_height, double *out_scale_factor)
mln_status	mln_map_request_repaint (mln_map map)
mln_status	mln_map_request_still_image (mln_map map)
mln_status	mln_map_destroy (mln_map map)
mln_status	mln_map_set_style_url (mln_map map, const char *url)
mln_status	mln_map_set_style_json (mln_map map, mln_buffer_view json)
mln_status	mln_map_copy_loaded_style_json (mln_map map, uint8_t *out_json, size_t json_capacity, size_t *out_json_size)
mln_status	mln_map_copy_style_url (mln_map map, char *out_url, size_t url_capacity, size_t *out_url_size)
mln_status	mln_map_set_event_mask (mln_map map, uint64_t mask)
mln_status	mln_map_get_event_mask (mln_map map, uint64_t *out_mask)

Detailed Description

Public C API declarations for map lifecycle, shared types, and offline regions.

Typedef Documentation

mln_animation_option_field

typedef enum mln_animation_option_field mln_animation_option_field

Field mask values for mln_animation_options.

mln_animation_options

typedef struct mln_animation_options mln_animation_options

Optional animation controls for camera transitions.

mln_bound_option_field

typedef enum mln_bound_option_field mln_bound_option_field

Field mask values for mln_bound_options.

mln_bound_options

typedef struct mln_bound_options mln_bound_options

Optional map camera constraint fields.

mln_camera_fit_option_field

typedef enum mln_camera_fit_option_field mln_camera_fit_option_field

Field mask values for mln_camera_fit_options.

mln_camera_fit_options

typedef struct mln_camera_fit_options mln_camera_fit_options

Optional fitting controls for camera-for-viewport queries.

mln_camera_option_field

typedef enum mln_camera_option_field mln_camera_option_field

Field mask values for mln_camera_options.

mln_camera_options

typedef struct mln_camera_options mln_camera_options

Camera fields used for snapshots and camera commands.

mln_constrain_mode

typedef enum mln_constrain_mode mln_constrain_mode

Map constraint modes used by mln_map_viewport_options.

mln_edge_insets

typedef struct mln_edge_insets mln_edge_insets

Screen-space inset in logical map pixels.

mln_feature_state_selector

typedef struct mln_feature_state_selector mln_feature_state_selector

Feature-state source, feature, and key selector.

mln_feature_state_selector_field

typedef enum mln_feature_state_selector_field mln_feature_state_selector_field

Optional fields for mln_feature_state_selector.

mln_free_camera_option_field

typedef enum mln_free_camera_option_field mln_free_camera_option_field

Field mask values for mln_free_camera_options.

mln_free_camera_options

typedef struct mln_free_camera_options mln_free_camera_options

Free camera position and orientation in MapLibre Native camera space.

mln_lat_lng

typedef struct mln_lat_lng mln_lat_lng

Geographic coordinate in degrees used by map and projection APIs.

mln_lat_lng_bounds

typedef struct mln_lat_lng_bounds mln_lat_lng_bounds

Geographic bounds in degrees.

mln_map_debug_option

typedef enum mln_map_debug_option mln_map_debug_option

Debug overlay mask values for mln_map_set_debug_options().

mln_map_mode

typedef enum mln_map_mode mln_map_mode

Map rendering modes used when creating a map.

mln_map_options

typedef struct mln_map_options mln_map_options

Options used when creating a map.

mln_map_tile_option_field

typedef enum mln_map_tile_option_field mln_map_tile_option_field

Field mask values for mln_map_tile_options.

mln_map_tile_options

typedef struct mln_map_tile_options mln_map_tile_options

Tile prefetch and LOD tuning controls.

mln_map_viewport_option_field

typedef enum mln_map_viewport_option_field mln_map_viewport_option_field

Field mask values for mln_map_viewport_options.

mln_map_viewport_options

typedef struct mln_map_viewport_options mln_map_viewport_options

Live map viewport and render-transform controls.

mln_north_orientation

typedef enum mln_north_orientation mln_north_orientation

Map north orientation values used by mln_map_viewport_options.

mln_offline_geometry_region_definition

typedef struct mln_offline_geometry_region_definition mln_offline_geometry_region_definition

Geometry offline region definition.

mln_offline_region_definition

typedef struct mln_offline_region_definition mln_offline_region_definition

Tagged offline region definition.

mln_offline_region_info

typedef struct mln_offline_region_info mln_offline_region_info

Region data view returned from a snapshot or list handle.

mln_offline_tile_pyramid_region_definition

typedef struct mln_offline_tile_pyramid_region_definition mln_offline_tile_pyramid_region_definition

Tile-pyramid offline region definition.

mln_projected_meters

typedef struct mln_projected_meters mln_projected_meters

Lower-level Spherical Mercator projected-meter coordinate.

Map coordinate conversion APIs use mln_lat_lng. This type is only for Mercator helper functions.

mln_projection_mode

typedef struct mln_projection_mode mln_projection_mode

MapLibre axonometric rendering options used for snapshots and commands.

MapLibre Native names this native type ProjectionMode. It controls the live map render transform, not the geographic coordinate model.

mln_projection_mode_field

typedef enum mln_projection_mode_field mln_projection_mode_field

Field mask values for MapLibre axonometric rendering options.

mln_quaternion

typedef struct mln_quaternion mln_quaternion

Quaternion stored as x, y, z, w components.

mln_screen_point

typedef struct mln_screen_point mln_screen_point

Screen-space point in logical map pixels.

mln_tile_lod_mode

typedef enum mln_tile_lod_mode mln_tile_lod_mode

Tile LOD algorithms used by mln_map_tile_options.

mln_unit_bezier

typedef struct mln_unit_bezier mln_unit_bezier

Cubic easing curve for animated camera transitions.

mln_vec3

typedef struct mln_vec3 mln_vec3

Three-component vector used by free camera options.

mln_viewport_mode

typedef enum mln_viewport_mode mln_viewport_mode

Viewport orientation modes used by mln_map_viewport_options.

Enumeration Type Documentation

mln_animation_option_field

enum mln_animation_option_field : uint32_t

Field mask values for mln_animation_options.

mln_bound_option_field

enum mln_bound_option_field : uint32_t

Field mask values for mln_bound_options.

Enumerator
MLN_BOUND_OPTION_BOUNDS	Selects mln_bound_options.bounds as a geographic constraint that the camera center stays inside. Mutually exclusive with MLN_BOUND_OPTION_UNBOUNDED.
MLN_BOUND_OPTION_UNBOUNDED	Selects the unbounded geographic constraint, which leaves every camera center unconstrained and lets the map pan freely across the antimeridian. This differs from world bounds of -90/-180 to 90/180, which clamp longitude to that range. Mutually exclusive with MLN_BOUND_OPTION_BOUNDS, and leaves mln_bound_options.bounds unread.

mln_camera_fit_option_field

enum mln_camera_fit_option_field : uint32_t

Field mask values for mln_camera_fit_options.

mln_camera_option_field

enum mln_camera_option_field : uint32_t

Field mask values for mln_camera_options.

mln_constrain_mode

enum mln_constrain_mode : uint32_t

Map constraint modes used by mln_map_viewport_options.

mln_feature_state_selector_field

enum mln_feature_state_selector_field : uint32_t

Optional fields for mln_feature_state_selector.

mln_free_camera_option_field

enum mln_free_camera_option_field : uint32_t

Field mask values for mln_free_camera_options.

mln_map_debug_option

enum mln_map_debug_option : uint32_t

Debug overlay mask values for mln_map_set_debug_options().

mln_map_mode

enum mln_map_mode : uint32_t

Map rendering modes used when creating a map.

Enumerator
MLN_MAP_MODE_CONTINUOUS	Continuously updates as data arrives and map state changes.
MLN_MAP_MODE_STATIC	Produces one-off still images of an arbitrary viewport.
MLN_MAP_MODE_TILE	Produces one-off still images for a single tile.

mln_map_tile_option_field

enum mln_map_tile_option_field : uint32_t

Field mask values for mln_map_tile_options.

mln_map_viewport_option_field

enum mln_map_viewport_option_field : uint32_t

Field mask values for mln_map_viewport_options.

mln_north_orientation

enum mln_north_orientation : uint32_t

Map north orientation values used by mln_map_viewport_options.

mln_projection_mode_field

enum mln_projection_mode_field : uint32_t

Field mask values for MapLibre axonometric rendering options.

mln_tile_lod_mode

enum mln_tile_lod_mode : uint32_t

Tile LOD algorithms used by mln_map_tile_options.

mln_viewport_mode

enum mln_viewport_mode : uint32_t

Viewport orientation modes used by mln_map_viewport_options.

Function Documentation

mln_map_copy_loaded_style_json()

mln_status mln_map_copy_loaded_style_json	(	mln_map	map,
		uint8_t *	out_json,
		size_t	json_capacity,
		size_t *	out_json_size )

Copies the style document this map's style was last parsed from.

This is a state snapshot of the loaded document, not a serialization of the live style. The bytes are the document the style loader last parsed successfully: the bytes passed to mln_map_set_style_json(), or the response body fetched for mln_map_set_style_url(). Runtime mutations through the style APIs, such as adding a layer or setting a paint property, do not change it, and a failed parse leaves the previously parsed document in place.

A copy of the document is byte-for-byte identical to the bytes that were passed to mln_map_set_style_json(), so a host may hand it back to that function unchanged.

out_json may be null only when json_capacity is 0, which is a size probe that reports the required length and succeeds. *out_json_size receives the byte length before the capacity is checked, so a caller learns the size from a call that could not fit the document. The bytes are not null-terminated, so an exact-length buffer is sufficient.

A reported size of 0 means no document has been parsed: no style has been loaded yet, or every load so far failed to parse. A parsed document is never empty.

Returns:

• MLN_STATUS_OK on success, including a size probe.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live, out_json is null with non-zero capacity, json_capacity is too small for a non-null buffer, or out_json_size is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_copy_style_url()

mln_status mln_map_copy_style_url	(	mln_map	map,
		char *	out_url,
		size_t	url_capacity,
		size_t *	out_url_size )

Copies the URL this map's style was last requested from.

Unlike mln_map_copy_loaded_style_json(), this is live rather than load-time state: mln_map_set_style_url() records the URL when the request is made, before the response arrives or the document parses, and mln_map_set_style_json() clears it. The document reports what was last parsed while the URL reports what was last requested, so the two can disagree while a load is in flight or after one fails.

out_url may be null only when url_capacity is 0, which is a size probe that reports the required length and succeeds. *out_url_size receives the byte length before the capacity is checked. The bytes are not null-terminated, so an exact-length buffer is sufficient.

A reported size of 0 means no URL bytes are available. That covers a style loaded from inline JSON, a map that has loaded no style, and a URL load requested with an empty string, which mln_map_set_style_url() accepts. These cases are not distinguishable through this entry point.

Returns:

• MLN_STATUS_OK on success, including a size probe.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live, out_url is null with non-zero capacity, url_capacity is too small for a non-null buffer, or out_url_size is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_create()

mln_status mln_map_create	(	mln_runtime	runtime,
		const mln_map_options *	options,
		mln_map *	out_map )

Creates a map handle on the runtime owner thread.

On success, the runtime owner thread becomes the map owner thread.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, out_map is null, *out_map is not null, or options are invalid, which includes an event_mask bit outside MLN_RUNTIME_EVENT_MASK_ALL.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_destroy()

mln_status mln_map_destroy

(

mln_map

map

)

Destroys a map handle on its owner thread.

The map must not have an attached render session.

Destruction also discards this map's queued events, including queued style loading failures. There is no flush and no terminal event, so the last state a host mirrored from events can stay behind the map's final state. Snapshot whatever state the host needs while the map is still live, and let teardown proceed without awaiting an event for this map. A batch that a host already drained holds copies, so it stays readable after this call.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not a live map handle.
• MLN_STATUS_INVALID_STATE when map still has an attached render target session.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_get_event_mask()

mln_status mln_map_get_event_mask	(	mln_map	map,
		uint64_t *	out_mask )

Reports which map-originated event types this map queues.

The value is the mask last set, including bits outside MLN_RUNTIME_EVENT_MASK_ALL_MAP_EVENTS that this map ignores. A map that has not been narrowed reports MLN_RUNTIME_EVENT_MASK_ALL as this library defines it.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not a live map handle, or out_mask is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_get_size()

mln_status mln_map_get_size	(	mln_map	map,
		uint32_t *	out_width,
		uint32_t *	out_height,
		double *	out_scale_factor )

Copies the map's current logical viewport size and its pixel ratio.

The size starts at mln_map_options.width and height, and follows the attach and resize rules documented there. The scale factor is mln_map_options.scale_factor, fixed for the lifetime of the map and independent of any render target's scale factor; compare the two before attaching or resizing a render session to keep them in agreement.

This is a state snapshot. All three out-parameters are required.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live, or out_width, out_height, or out_scale_factor is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_options_default()

mln_map_options mln_map_options_default

(

void

)

Returns map options initialized for this C API version.

mln_map_request_repaint()

mln_status mln_map_request_repaint

(

mln_map

map

)

Requests a repaint for a continuous map.

Continuous maps also invalidate automatically when style data, resources, camera, or transitions change. Ask attached render targets to process the latest update when mln_runtime_drain_events() reports MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE. That type is the map's only invalidation report, so select it in the event mask of every rendered map. Repaint requests do not produce MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FINISHED or MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FAILED events.

Returns:

• MLN_STATUS_OK when the request was accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live.
• MLN_STATUS_INVALID_STATE when map is not in MLN_MAP_MODE_CONTINUOUS.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_request_still_image()

mln_status mln_map_request_still_image

(

mln_map

map

)

Requests one still image for a static or tile map.

Pump the runtime and drain runtime events for this map until MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FINISHED or MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FAILED is reported. Those two types are the only completion reports, so select both in the map's event mask. While the request is pending, process each MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE event from this map. Render targets use mln_render_session_render_update(). Surface targets present directly. A render-update call can report a result other than MLN_RENDER_RESULT_RENDERED before the next update is available; keep pumping and draining in that case. After MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FINISHED, use the latest successful texture update when the host needs image bytes or a backend texture.

Returns:

• MLN_STATUS_OK when the request was accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live.
• MLN_STATUS_INVALID_STATE when map is not in MLN_MAP_MODE_STATIC or MLN_MAP_MODE_TILE, or when a still-image request is already pending.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_set_event_mask()

mln_status mln_map_set_event_mask	(	mln_map	map,
		uint64_t	mask )

Selects which map-originated event types this map queues.

MapLibre Native reports map state through the observer callbacks behind these events, and this mask decides which of them become queued events. An event of an unselected type is never built and never queued, so it reaches no batch and raises no wake flag.

This call reads the bits in MLN_RUNTIME_EVENT_MASK_ALL_MAP_EVENTS and ignores the rest, so MLN_RUNTIME_EVENT_MASK_ALL selects every map-originated type. mln_map_get_event_mask() reports the value last set, so a host reads it, changes one bit, and writes it back.

A map that has not been narrowed selects every map-originated event type this library reports, which covers types a caller's header may not declare. A new mask applies to later events and keeps the events already queued.

One unread render-update event covers every invalidation queued behind it, compared against the queue tail. Leaving out a type that used to arrive between two render updates makes those two updates adjacent, so they coalesce into one.

Select every event type the host reads. These types carry state a host reaches no other way:

• MLN_RUNTIME_EVENT_MASK_MAP_RENDER_UPDATE_AVAILABLE is the map's only invalidation report. See mln_map_request_repaint().
• MLN_RUNTIME_EVENT_MASK_MAP_STILL_IMAGE_FINISHED and MLN_RUNTIME_EVENT_MASK_MAP_STILL_IMAGE_FAILED are the only reports that a still-image request finished. See mln_map_request_still_image().
• MLN_RUNTIME_EVENT_MASK_MAP_CAMERA_TRANSITION_FINISHED carries the transition identity a caller set on an animation, and MLN_RUNTIME_EVENT_MASK_MAP_CAMERA_DID_CHANGE distinguishes a completed transition from a cancelled one. See mln_animation_options.transition_id.
• MLN_RUNTIME_EVENT_MASK_MAP_LOADING_FAILED and MLN_RUNTIME_EVENT_MASK_MAP_RENDER_ERROR carry native failure text.

mln_map_set_style_url() and mln_map_set_style_json() report a style failure that MapLibre raises inside the call through their return status and a thread diagnostic, whatever this mask selects.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not a live map handle, or mask holds a bit outside MLN_RUNTIME_EVENT_MASK_ALL.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_set_style_json()

mln_status mln_map_set_style_json	(	mln_map	map,
		mln_buffer_view	json )

Loads inline style JSON through MapLibre Native style APIs.

This is a map command. The return status reports synchronous acceptance or failure. Later native success and failure are reported through runtime events. Malformed JSON can fail synchronously and still enqueue a loading-failed event.

Returns:

• MLN_STATUS_OK when the load request was accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is null, not live, or json is empty or has a nonzero size with a null data pointer.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when a synchronous native error is reported or an internal exception is converted to status.

mln_map_set_style_url()

mln_status mln_map_set_style_url	(	mln_map	map,
		const char *	url )

Loads a style URL through MapLibre Native style APIs.

This is a map command. The return status reports synchronous acceptance or failure. Later native success and failure are reported through runtime events. A URL that is unreachable, malformed, or serves invalid style content is still accepted synchronously; every such failure arrives later as a style loading-failed event, so hosts report style URL errors from the event stream rather than from this return status.

Returns:

• MLN_STATUS_OK when the load request was accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is null, not live, or url is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when a synchronous native error is reported or an internal exception is converted to status.

mln_offline_region_list_count()

mln_status mln_offline_region_list_count	(	mln_offline_region_list	list,
		size_t *	out_count )

Gets the number of regions in a list handle.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when list is null or not live, or out_count is null.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_offline_region_list_destroy()

void mln_offline_region_list_destroy

(

mln_offline_region_list

list

)

Destroys an offline region list handle. Null is accepted as a no-op.

mln_offline_region_list_get()

mln_status mln_offline_region_list_get	(	mln_offline_region_list	list,
		size_t	index,
		mln_offline_region_info *	out_info )

Copies a region data view for one list entry.

On success, out_info receives pointers into list-owned storage. Those pointers remain valid until the list is destroyed.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when list is null or not live, index is out of range, out_info is null, or out_info->size is too small.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_offline_region_snapshot_destroy()

void mln_offline_region_snapshot_destroy

(

mln_offline_region_snapshot

snapshot

)

Destroys an offline region snapshot handle. Null is accepted as a no-op.

mln_offline_region_snapshot_get()

mln_status mln_offline_region_snapshot_get	(	mln_offline_region_snapshot	snapshot,
		mln_offline_region_info *	out_info )

Copies a region data view out of a snapshot handle.

On success, out_info receives pointers into snapshot-owned storage. Those pointers remain valid until the snapshot is destroyed.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when snapshot is null or not live, out_info is null, or out_info->size is too small.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_region_create_start()

mln_status mln_runtime_offline_region_create_start	(	mln_runtime	runtime,
		const mln_offline_region_definition *	definition,
		const uint8_t *	metadata,
		size_t	metadata_size,
		mln_offline_operation_id *	out_operation_id )

Starts creating an offline region.

Input strings, GeoJSON geometry bytes, and metadata are copied before this call returns. Completion is reported through MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED. On successful completion, call mln_runtime_offline_region_create_take_result() to take the snapshot.

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, definition is null or invalid, metadata is null with a non-zero size, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_region_create_take_result()

mln_status mln_runtime_offline_region_create_take_result	(	mln_runtime	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_snapshot *	out_region )

Takes the snapshot result from a completed offline region create operation.

Must only be called after the matching mln_runtime_offline_region_create_start() operation has completed successfully (MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED with result status MLN_STATUS_OK). The caller owns the returned snapshot handle and must destroy it with mln_offline_region_snapshot_destroy().

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard(). Taking or discarding a result also removes that operation's undrained completion event. The thread diagnostic carries a failed operation's error text.

Returns:

• MLN_STATUS_OK when the result was taken and out_region was set.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match a region snapshot.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_region is null.

mln_runtime_offline_region_delete_start()

mln_status mln_runtime_offline_region_delete_start	(	mln_runtime	runtime,
		mln_offline_region_id	region_id,
		mln_offline_operation_id *	out_operation_id )

Deletes an offline region.

Completion is reported through MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED.

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_region_get_start()

mln_status mln_runtime_offline_region_get_start	(	mln_runtime	runtime,
		mln_offline_region_id	region_id,
		mln_offline_operation_id *	out_operation_id )

Starts getting an offline region snapshot by ID.

Completion is reported through MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED. On successful completion, call mln_runtime_offline_region_get_take_result().

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_region_get_status_start()

mln_status mln_runtime_offline_region_get_status_start	(	mln_runtime	runtime,
		mln_offline_region_id	region_id,
		mln_offline_operation_id *	out_operation_id )

Starts getting the current completed/download status for an offline region.

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_region_get_status_take_result()

mln_status mln_runtime_offline_region_get_status_take_result	(	mln_runtime	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_status *	out_status )

Takes the status struct from a completed offline region get-status operation.

Must only be called after the matching mln_runtime_offline_region_get_status_start() operation has completed successfully. The caller provides a pre-allocated mln_offline_region_status struct which is filled by this function.

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard(). Taking or discarding a result also removes that operation's undrained completion event. The thread diagnostic carries a failed operation's error text.

Returns:

• MLN_STATUS_OK when the result was taken and out_status was filled.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match a region status.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_status is null.

mln_runtime_offline_region_get_take_result()

mln_status mln_runtime_offline_region_get_take_result	(	mln_runtime	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_snapshot *	out_region,
		bool *	out_found )

Takes the snapshot result from a completed offline region get operation.

Must only be called after the matching mln_runtime_offline_region_get_start() operation has completed successfully. The caller owns the returned snapshot handle and must destroy it with mln_offline_region_snapshot_destroy().

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard(). Taking or discarding a result also removes that operation's undrained completion event. The thread diagnostic carries a failed operation's error text.

Returns:

• MLN_STATUS_OK when the result was taken; out_found indicates whether a region existed for the requested ID.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match an optional region snapshot.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, out_region is null, or out_found is null.

mln_runtime_offline_region_invalidate_start()

mln_status mln_runtime_offline_region_invalidate_start	(	mln_runtime	runtime,
		mln_offline_region_id	region_id,
		mln_offline_operation_id *	out_operation_id )

Invalidates cached resources for an offline region.

Completion is reported through MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED.

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_region_set_download_state_start()

mln_status mln_runtime_offline_region_set_download_state_start	(	mln_runtime	runtime,
		mln_offline_region_id	region_id,
		uint32_t	state,
		mln_offline_operation_id *	out_operation_id )

Sets an offline region's native download state.

Register observation separately with mln_runtime_offline_region_set_observed_start() to receive progress and error events.

Completion is reported through MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED.

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, state is not a mln_offline_region_download_state value, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_region_set_observed_start()

mln_status mln_runtime_offline_region_set_observed_start	(	mln_runtime	runtime,
		mln_offline_region_id	region_id,
		bool	observed,
		mln_offline_operation_id *	out_operation_id )

Enables or disables runtime events for an offline region.

Observer callbacks are copied into runtime events. Disabling observation also discards queued events for this region.

Completion is reported through MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED.

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_region_update_metadata_start()

mln_status mln_runtime_offline_region_update_metadata_start	(	mln_runtime	runtime,
		mln_offline_region_id	region_id,
		const uint8_t *	metadata,
		size_t	metadata_size,
		mln_offline_operation_id *	out_operation_id )

Starts updating opaque binary metadata for an offline region.

On successful completion, call mln_runtime_offline_region_update_metadata_take_result().

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, metadata is null with a non-zero size, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_region_update_metadata_take_result()

mln_status mln_runtime_offline_region_update_metadata_take_result	(	mln_runtime	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_snapshot *	out_region )

Takes the snapshot result from a completed offline region update-metadata operation.

Must only be called after the matching mln_runtime_offline_region_update_metadata_start() operation has completed successfully. The caller owns the returned snapshot handle and must destroy it with mln_offline_region_snapshot_destroy().

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard(). Taking or discarding a result also removes that operation's undrained completion event. The thread diagnostic carries a failed operation's error text.

Returns:

• MLN_STATUS_OK when the result was taken and out_region was set.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match a region snapshot.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_region is null.

mln_runtime_offline_regions_list_start()

mln_status mln_runtime_offline_regions_list_start	(	mln_runtime	runtime,
		mln_offline_operation_id *	out_operation_id )

Starts listing offline region snapshots in the runtime database.

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_regions_list_take_result()

mln_status mln_runtime_offline_regions_list_take_result	(	mln_runtime	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_list *	out_regions )

Takes the region list from a completed offline regions list operation.

Must only be called after the matching mln_runtime_offline_regions_list_start() operation has completed successfully. The caller owns the returned list handle and must destroy it with mln_offline_region_list_destroy().

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard(). Taking or discarding a result also removes that operation's undrained completion event. The thread diagnostic carries a failed operation's error text.

Returns:

• MLN_STATUS_OK when the result was taken and out_regions was set.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match a region list.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_regions is null.

mln_runtime_offline_regions_merge_database_start()

mln_status mln_runtime_offline_regions_merge_database_start	(	mln_runtime	runtime,
		const char *	side_database_path,
		mln_offline_operation_id *	out_operation_id )

Starts merging offline regions from another database path.

The side database may be upgraded in place by native code and must be writable when native merge requires it.

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, side_database_path is null, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_regions_merge_database_take_result()

mln_status mln_runtime_offline_regions_merge_database_take_result	(	mln_runtime	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_list *	out_regions )

Takes the region list from a completed offline database merge operation.

Must only be called after the matching mln_runtime_offline_regions_merge_database_start() operation has completed successfully. The caller owns the returned list handle and must destroy it with mln_offline_region_list_destroy().

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard(). Taking or discarding a result also removes that operation's undrained completion event. The thread diagnostic carries a failed operation's error text.

Returns:

• MLN_STATUS_OK when the result was taken and out_regions was set.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match a region list.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_regions is null.