map.h File Reference
Go to the source code of this file.
Data Structures | |
| struct | mln_logical_extent |
| struct | mln_map_options |
| struct | mln_screen_point |
| struct | mln_edge_insets |
| struct | mln_lat_lng |
| struct | mln_camera_options |
| struct | mln_unit_bezier |
| struct | mln_camera_transition_end |
| struct | mln_camera_transition_handler |
| struct | mln_animation_options |
| struct | mln_camera_delta |
| struct | mln_camera_update |
| struct | mln_camera_fit_options |
| struct | mln_vec3 |
| struct | mln_quaternion |
| struct | mln_free_camera_options |
| 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 |
| union | mln_offline_region_definition_data |
| 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_view |
| struct | mln_map_tile_options |
| struct | mln_map_snapshot |
| struct | mln_camera_query_result |
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_delta
| typedef struct mln_camera_delta mln_camera_delta |
One atomic relative camera update.
Each selected component resolves against the camera as it stands when the command runs. Immediate deltas therefore compose exactly, however many are queued. An animated delta starts from the value a running transition has reached and replaces that component's transition, so queue animated deltas only after the previous one has rendered or finished.
OFFSET pans first, in the current camera's logical pixels: the content moves by offset, so positive x moves it right and positive y moves it down, and a pointer drag delta passes through unchanged. The pan stops short of the horizon. SCALE, BEARING, and PITCH then change the camera about anchor when ANCHOR is set, keeping the coordinate under anchor in the panned camera fixed, or about the center otherwise. ANCHOR requires SCALE, BEARING, or PITCH. ANCHOR combines with OFFSET only for an immediate delta, one whose animation selects no DURATION or a zero duration; a two-finger gesture passes its centroid movement as offset and its new centroid as anchor. An animated bearing change takes the shorter way around.
fields may be zero, in which case the delta changes only the gesture phase and its animation's end handler runs at once. gesture_phase is applied around the camera write, as in mln_camera_update. The command copies this struct before returning.
◆ mln_camera_delta_field
| typedef enum mln_camera_delta_field mln_camera_delta_field |
Field mask values for mln_camera_delta.
◆ 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 by snapshots and camera updates.
◆ mln_camera_query_result
| typedef struct mln_camera_query_result mln_camera_query_result |
Camera result borrowed for an ordered camera-query completion.
◆ mln_camera_transition_end
| typedef struct mln_camera_transition_end mln_camera_transition_end |
The end of one camera command's transitions, borrowed for the callback.
◆ mln_camera_transition_end_callback
| typedef void(*) mln_camera_transition_end_callback(void *user_data, const mln_camera_transition_end *end) |
Receives the end of one camera command's transitions.
A handler in queue mode queues a copy as an mln_camera_transition_end_delivery instead.
◆ mln_camera_transition_handler
| typedef struct mln_camera_transition_handler mln_camera_transition_handler |
Callback or queue state that one camera command copies to report the end of its transitions.
A handler with neither a callback nor a queue is disabled, and a disabled handler must not carry release_user_data. See mln_animation_options.end_handler for when the callback runs.
◆ mln_camera_transition_outcome
How the transitions of one camera command ended.
◆ mln_camera_update
| typedef struct mln_camera_update mln_camera_update |
One atomic absolute camera update.
The command copies this struct before returning.
◆ mln_camera_update_mode
| typedef enum mln_camera_update_mode mln_camera_update_mode |
Camera transition behavior for mln_camera_update.
◆ 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
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_gesture_phase
| typedef enum mln_gesture_phase mln_gesture_phase |
Gesture boundary carried atomically with a camera update or delta.
The phase is applied around the camera write and is reported by mln_map_snapshot.gesture_in_progress.
◆ 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_logical_extent
| typedef struct mln_logical_extent mln_logical_extent |
Logical extent in UI pixels and the device-pixel scale.
◆ 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_snapshot
| typedef struct mln_map_snapshot mln_map_snapshot |
Immutable map state copied from the latest published generation.
Every field is unkeyed, fixed-size map state that changes only through this map's own commands or through load progress. Each map command that runs publishes a new generation and reports it through its completion, when it has one, even when the command changes nothing or fails, so a snapshot whose generation is at or past a completion observes that command.
◆ 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_view
| typedef struct mln_map_view mln_map_view |
Everything that a projection depends on: the transform that a published snapshot or a rendered frame describes.
Every member is set on output. mln_map_projection_create() reads every member and requires every field of each nested struct, except MLN_CAMERA_OPTION_ANCHOR, which it ignores. Camera constraints are map policy and stay out of the view, because no conversion reads them.
A later version may append members. mln_map_snapshot and mln_render_frame_result embed the view as their last member, so their own size versions that growth.
◆ 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_definition_data
| typedef union mln_offline_region_definition_data mln_offline_region_definition_data |
Offline region definition data.
◆ mln_offline_region_info
| typedef struct mln_offline_region_info mln_offline_region_info |
Region data delivered by an offline completion.
The record and every pointer it carries, including the definition's style URL and geometry and the metadata bytes, are borrowed for the duration of the completion callback.
◆ 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.
These control the live map render transform. Geographic coordinates retain their 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, from the top-left of the viewport with y growing downward.
◆ 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_delta_field
| enum mln_camera_delta_field : uint32_t |
Field mask values for mln_camera_delta.
◆ 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_camera_transition_outcome
| enum mln_camera_transition_outcome : uint32_t |
How the transitions of one camera command ended.
| Enumerator | |
|---|---|
| MLN_CAMERA_TRANSITION_OUTCOME_COMPLETED | Every property of the command reached its target, or a later camera write replaced it. |
| MLN_CAMERA_TRANSITION_OUTCOME_CANCELLED | mln_map_cancel_transitions(), mln_map_cancel_camera_transition(), or MLN_GESTURE_PHASE_CANCEL ended the transitions, or the command failed before it started them. |
| MLN_CAMERA_TRANSITION_OUTCOME_CLOSED | The map closed before the transitions ended. |
◆ mln_camera_update_mode
| enum mln_camera_update_mode : uint32_t |
Camera transition behavior for mln_camera_update.
◆ 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_gesture_phase
| enum mln_gesture_phase : uint32_t |
Gesture boundary carried atomically with a camera update or delta.
The phase is applied around the camera write and is reported by mln_map_snapshot.gesture_in_progress.
| Enumerator | |
|---|---|
| MLN_GESTURE_PHASE_NONE | The update carries no gesture boundary and leaves the flag as it is. |
| MLN_GESTURE_PHASE_BEGIN | Marks a gesture as in progress before the camera write. It does not cancel running transitions; use mln_map_cancel_transitions() for that. |
| MLN_GESTURE_PHASE_UPDATE | Keeps the gesture marked as in progress before the camera write. |
| MLN_GESTURE_PHASE_END | Clears the gesture flag after the camera write. |
| MLN_GESTURE_PHASE_CANCEL | Cancels transitions running after the camera write, then clears the gesture flag. |
◆ 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 |
◆ 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_logical_extent_default()
| mln_logical_extent mln_logical_extent_default | ( | void | ) |
Returns a 256 by 256 logical extent with one device pixel per UI pixel.
◆ mln_map_begin_command_group()
| mln_status mln_map_begin_command_group | ( | mln_map | map, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Begins a command group, which holds this map's render updates until the group ends.
Each command publishes at most one render update. A group combines several commands, such as adding a layer and setting its filter, so that no frame shows only some of them. Commands accepted between this call and the matching mln_map_end_command_group() still commit one at a time, and each completion and snapshot reports its own commit. The render updates of those commands, and of loading and transitions meanwhile, stay unpublished, and the end of the outermost group publishes the latest one. Groups nest. A command that fails inside a group leaves the group open and leaves the other commands applied.
While a group is open the map publishes no render update, including those that camera changes, gestures, resource loading, and transitions raise, so attached render targets show nothing new. A render-session resize, and a still image already in flight, finish only after the group ends. Submit the commands and the matching end without waiting for any completion in between, and submit the end on every path, including when a command between them fails to submit.
Returns:
- MLN_STATUS_OK when the command 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 command acceptance fails.
◆ mln_map_dispose()
| mln_status mln_map_dispose | ( | mln_map | map, |
| mln_diagnostic * | out_diagnostic ) |
Consumes a map handle without observing its asynchronous retirement.
Attached sessions retain the map until they detach or retire. A successful call consumes the handle before returning. A failed call retains caller ownership. Teardown may allocate; allocation failure after acceptance terminates the process.
Returns:
- MLN_STATUS_OK when the handle was consumed.
- MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle.
- MLN_STATUS_INVALID_STATE when map has been released or is already closing.
◆ mln_map_end_command_group()
| mln_status mln_map_end_command_group | ( | mln_map | map, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Ends the innermost command group that mln_map_begin_command_group() began.
Ending the outermost group publishes the latest render update that the group held, and the snapshot that this command publishes reports that update in latest_render_update_generation.
Returns:
- MLN_STATUS_OK when the command 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 command acceptance fails.
Completes with:
- MLN_STATUS_INVALID_STATE when map has no open command group.
◆ mln_map_get_feature_state()
| mln_status mln_map_get_feature_state | ( | mln_map | map, |
| const mln_feature_state_selector * | selector, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts an ordered read of per-feature state from this map.
selector->source_id and selector->feature_id are copied before return. The read observes every map command accepted before it and copies the map store, not the last rendered frame, so it does not require a render session or a loaded source. The completion borrows UTF-8 bytes holding one JSON object for the callback. Missing feature state is reported as an empty object.
Returns:
- MLN_STATUS_OK when the read was accepted.
- MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, selector is null or invalid, selector lacks MLN_FEATURE_STATE_SELECTOR_FEATURE_ID, or completion is invalid.
- MLN_STATUS_INVALID_STATE when map has been released, or the runtime is closing.
- MLN_STATUS_NATIVE_ERROR when native code fails.
◆ mln_map_get_loaded_style_json()
| mln_status mln_map_get_loaded_style_json | ( | mln_map | map, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts an ordered copy of the last successfully parsed style document.
The completion borrows the copied UTF-8 bytes for the callback.
Returns:
- MLN_STATUS_OK when the query is 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.
Completes with:
- MLN_STATUS_NATIVE_ERROR when the copy fails.
◆ mln_map_get_snapshot()
| mln_status mln_map_get_snapshot | ( | mln_map | map, |
| mln_map_snapshot * | out_snapshot, | ||
| mln_diagnostic * | out_diagnostic ) |
Copies the map's latest published snapshot.
Returns:
- MLN_STATUS_OK on success.
- MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, or out_snapshot is null or undersized.
- MLN_STATUS_INVALID_STATE when map has been released.
- MLN_STATUS_NATIVE_ERROR when native code fails.
◆ mln_map_get_style_url()
| mln_status mln_map_get_style_url | ( | mln_map | map, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts an ordered copy of the last requested style URL.
The completion borrows the copied UTF-8 bytes for the callback.
Returns:
- MLN_STATUS_OK when the query is 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.
Completes with:
- MLN_STATUS_NATIVE_ERROR when the copy fails.
◆ mln_map_options_default()
| mln_map_options mln_map_options_default | ( | void | ) |
Returns map options initialized for this C API version.
◆ mln_map_release()
| mln_status mln_map_release | ( | mln_map | map, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Releases a map asynchronously.
A successful call consumes the public handle before returning. The completion runs after previously accepted work is terminal, the native map can no longer call the host, and map-owned callback state has been released. Backend worker and graphics-resource cleanup may continue after completion. The completion state follows the one-shot ownership contract. Teardown may allocate; allocation failure after acceptance terminates the process.
Returns:
- MLN_STATUS_OK when release was accepted and the handle was consumed.
- 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 already closing or still has an attached render session.
- MLN_STATUS_NATIVE_ERROR when the completion could not be allocated.
◆ mln_map_remove_feature_state()
| mln_status mln_map_remove_feature_state | ( | mln_map | map, |
| const mln_feature_state_selector * | selector, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Removes per-feature state from this map.
selector->source_id is required. selector->feature_id and selector->state_key are optional. Passing both removes one state key from one feature. Passing only feature_id removes all state for that feature. Passing neither removes all feature state for the source/source-layer. The accepted command requests a map repaint.
Returns:
- MLN_STATUS_OK when the command was accepted.
- MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, selector is null or invalid, selector has MLN_FEATURE_STATE_SELECTOR_STATE_KEY without MLN_FEATURE_STATE_SELECTOR_FEATURE_ID, or completion is invalid.
- MLN_STATUS_INVALID_STATE when map has been released, or the runtime is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_map_request_repaint()
| mln_status mln_map_request_repaint | ( | mln_map | map, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Requests a repaint for a continuous map.
A continuous map also publishes a render update on its own when style data, resources, the camera, or a transition changes. A host keeps a frame demand with MLN_FRAME_DEMAND_WAIT_FOR_UPDATE pending and arms the next one as each result arrives to render updates as the map publishes them.
Returns:
- MLN_STATUS_OK when the request 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 map is not continuous or is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_map_request_still_image()
| mln_status mln_map_request_still_image | ( | mln_map | map, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Requests one still image for a static or tile map.
Keep servicing the selected render driver while this request is pending. Submit frame demands with mln_render_session_request_frame() and drain their terminal results with mln_render_session_drain_frame_results(). A caller-graphics-thread driver also requires calls to mln_render_session_service_driver_work() on its graphics thread. Any demand may complete the image, but only with a fully loaded frame that rendered the update this request published or a later one; a frame of an earlier update never does. That frame may be acquired or read back after the completion runs.
Returns:
- MLN_STATUS_OK when the request 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 map is not in MLN_MAP_MODE_STATIC or MLN_MAP_MODE_TILE, or is closing.
- MLN_STATUS_NATIVE_ERROR when native code fails.
Completes with:
- MLN_STATUS_INVALID_STATE when a still-image request was already pending when this request ran, or when the map had an open command group.
- MLN_STATUS_CANCELLED when the map closes before the image is produced.
- MLN_STATUS_NATIVE_ERROR when rendering the image fails.
◆ mln_map_resize()
| mln_status mln_map_resize | ( | mln_map | map, |
| mln_logical_extent | extent, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Submits the sole post-creation logical extent update.
extent.scale_factor must equal the scale factor the map was created with; only width and height may change. A render session sizes the map to its target: attaching a target, replacing it, and mln_render_session_resize() each submit this command with the target's width and height when the call is accepted. An attach that then fails, or a replacement that the driver then refuses, leaves the map at the size that the target named. While a render session is attached, a direct map resize completes with MLN_STATUS_INVALID_STATE; size the map through the session instead. The completion reports terminal disposition and the snapshot generation that the resize published. Resizes apply in acceptance order, so the last one accepted sets the size. A resize to the map's current width and height changes nothing and publishes no render update.
Returns:
- MLN_STATUS_OK when the resize was accepted.
- MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle; extent has a zero width or height, or a scale_factor that is not finite and positive; extent.scale_factor differs from the value the map was created with; or completion is invalid.
- MLN_STATUS_INVALID_STATE when map has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
Completes with:
- MLN_STATUS_NATIVE_ERROR when applying the size fails.
◆ mln_map_set_event_mask()
| mln_status mln_map_set_event_mask | ( | mln_map | map, |
| uint64_t | mask, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Selects which map-originated event types this map queues.
This call accepts only bits in MLN_RUNTIME_EVENT_MASK_ALL. It reads the bits in MLN_RUNTIME_EVENT_MASK_ALL_MAP_EVENTS and ignores runtime-scoped bits, so MLN_RUNTIME_EVENT_MASK_ALL selects every map-originated type. mln_map_get_snapshot() reports the last committed mask.
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.
Select every event type the host reads. These types carry state a host reaches no other way:
- MLN_RUNTIME_EVENT_MASK_MAP_LOADING_FAILED and MLN_RUNTIME_EVENT_MASK_MAP_RENDER_ERROR carry native failure text.
Style commands report application failures through their completions regardless of this mask.
Returns:
- MLN_STATUS_OK when the command is accepted.
- MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, mask contains an unknown bit, or completion is invalid.
- MLN_STATUS_INVALID_STATE when map has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_map_set_feature_state()
| mln_status mln_map_set_feature_state | ( | mln_map | map, |
| const mln_feature_state_selector * | selector, | ||
| mln_buffer_view | state, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Submits a copied per-feature-state command.
selector->source_id, selector->feature_id, and state are copied before return. state must contain one UTF-8 JSON object and is validated before return. The command writes the object's keys and leaves the feature's other keys unchanged. The committed command requests a map repaint.
Feature state belongs to the map and applies to the next render update, including the first presented frame that contains the source. mln_map_get_feature_state() reads the map's state.
Returns:
- MLN_STATUS_OK when the command was accepted.
- MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, selector is null or invalid, selector lacks MLN_FEATURE_STATE_SELECTOR_FEATURE_ID, state is empty, invalid JSON, or not an object, or completion is invalid.
- MLN_STATUS_INVALID_STATE when map has been released, or the runtime is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_map_set_style_json()
| mln_status mln_map_set_style_json | ( | mln_map | map, |
| mln_buffer_view | json, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Queues an inline style JSON command.
The function copies json before returning acceptance. The completion reports committed or failed application. Style loading events continue to report later resource and parse results after a committed command.
The map's first loaded style moves the camera to the style's center, zoom, bearing, and pitch, unless the host moved the camera first. Later style loads leave the camera unchanged.
Returns:
- MLN_STATUS_OK when the command was accepted.
- MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, json.data is null, json.size is zero, or completion is invalid.
- MLN_STATUS_INVALID_STATE when map has been released, or the runtime is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
Completes with:
- MLN_STATUS_NATIVE_ERROR when style parsing or application fails.
◆ mln_map_set_style_url()
| mln_status mln_map_set_style_url | ( | mln_map | map, |
| mln_buffer_view | url, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Queues a style URL command.
The function copies url before returning acceptance. The completion reports committed or failed application. Style loading events continue to report network, decode, and parse results after a committed command.
The map's first loaded style moves the camera to the style's center, zoom, bearing, and pitch, unless the host moved the camera first. Later style loads leave the camera unchanged.
Returns:
- MLN_STATUS_OK when the command was accepted.
- MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle, url has null data with a nonzero size or contains embedded NUL, or completion is invalid.
- MLN_STATUS_INVALID_STATE when map has been released, or the runtime is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_runtime_create_map()
| mln_status mln_runtime_create_map | ( | mln_runtime | runtime, |
| const mln_map_options * | options, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts creation of a map on the runtime.
Input is copied before this function returns. The completion value points to one mln_map handle when status is MLN_STATUS_OK.
Returns:
- MLN_STATUS_OK when the creation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle; options is null, undersized, or carries an invalid field; options->initial_extent has a zero width or height, or a scale_factor that is not finite and positive; or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when native code fails.
Completes with:
- MLN_STATUS_NATIVE_ERROR when map creation fails.
◆ mln_runtime_create_offline_region()
| mln_status mln_runtime_create_offline_region | ( | mln_runtime | runtime, |
| const mln_offline_region_definition * | definition, | ||
| const uint8_t * | metadata, | ||
| size_t | metadata_size, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts creating an offline region.
Input strings, GeoJSON geometry bytes, and metadata are copied before this call returns. A successful completion borrows one mln_offline_region_info value, valid only for the duration of the callback.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, definition is null or malformed, metadata is null with a non-zero metadata_size, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK and one region record.
- MLN_STATUS_UNSUPPORTED when the stored definition type is unsupported.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
◆ mln_runtime_delete_offline_region()
| mln_status mln_runtime_delete_offline_region | ( | mln_runtime | runtime, |
| mln_offline_region_id | region_id, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Deletes an offline region.
Resources that another region also uses stay offline. The region's other resources become ambient cache, which the ambient cache budget then trims. The completion reports the terminal status and carries no value.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK when the region was deleted.
- MLN_STATUS_NOT_FOUND when no region carries region_id.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
◆ mln_runtime_get_offline_region()
| mln_status mln_runtime_get_offline_region | ( | mln_runtime | runtime, |
| mln_offline_region_id | region_id, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts getting one offline region by ID.
A successful completion borrows zero or one mln_offline_region_info value, depending on whether the region exists, valid only for the duration of the callback. A missing region completes successfully with no value, as every read of a whole object does; operations on one region complete with MLN_STATUS_NOT_FOUND instead.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK and zero or one region record.
- MLN_STATUS_UNSUPPORTED when the stored definition type is unsupported.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
◆ mln_runtime_get_offline_region_status()
| mln_status mln_runtime_get_offline_region_status | ( | mln_runtime | runtime, |
| mln_offline_region_id | region_id, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts getting the current download status for an offline region.
A successful completion borrows one mln_offline_region_status value, valid only for the duration of the callback.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK and one status value.
- MLN_STATUS_NOT_FOUND when no region carries region_id.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
◆ mln_runtime_invalidate_offline_region()
| mln_status mln_runtime_invalidate_offline_region | ( | mln_runtime | runtime, |
| mln_offline_region_id | region_id, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Invalidates cached resources for an offline region.
The completion reports the terminal status and carries no value.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK when the region's resources were invalidated.
- MLN_STATUS_NOT_FOUND when no region carries region_id.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
◆ mln_runtime_list_offline_regions()
| mln_status mln_runtime_list_offline_regions | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts listing the offline regions in the runtime database.
A successful completion borrows value_count mln_offline_region_info values, value_size bytes apart, valid only for the duration of the callback.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK and one record per stored region.
- MLN_STATUS_UNSUPPORTED when a stored definition type is unsupported.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
◆ mln_runtime_merge_offline_regions()
| mln_status mln_runtime_merge_offline_regions | ( | mln_runtime | runtime, |
| mln_buffer_view | side_database_path, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts merging offline regions from another MapLibre offline database.
side_database_path must identify an existing, readable MapLibre offline database whose schema version matches this library. The runtime opens the database read-only and leaves its contents unchanged. Keep the file present and unchanged until the completion runs.
The merge copies only tiles and resources assigned to a region. It does not accept an MBTiles database, which uses a different schema.
The call copies side_database_path. A path that names no existing readable database file is rejected with MLN_STATUS_INVALID_ARGUMENT before acceptance. Format, schema, and later filesystem errors reach the completion as a non-OK status and diagnostic.
A successful completion borrows value_count mln_offline_region_info values, value_size bytes apart and one per merged region, valid only for the duration of the callback.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, side_database_path has null data with a nonzero size, contains embedded NUL, or names no readable database file, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK and one record per merged region.
- MLN_STATUS_UNSUPPORTED when a merged definition type is unsupported.
- MLN_STATUS_NATIVE_ERROR when the merge fails, including a schema mismatch.
◆ mln_runtime_set_offline_region_download_state()
| mln_status mln_runtime_set_offline_region_download_state | ( | mln_runtime | runtime, |
| mln_offline_region_id | region_id, | ||
| uint32_t | state, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Sets an offline region's native download state.
Register observation separately with mln_runtime_set_offline_region_observed() to receive progress and error events. The completion reports the terminal status and carries no value.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, state is not an mln_offline_region_download_state value, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK when the download state was set.
- MLN_STATUS_NOT_FOUND when no region carries region_id.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
◆ mln_runtime_set_offline_region_observed()
| mln_status mln_runtime_set_offline_region_observed | ( | mln_runtime | runtime, |
| mln_offline_region_id | region_id, | ||
| bool | observed, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Enables or disables runtime events for an offline region.
An observed region reports progress and errors as runtime events. Disabling observation prevents future events for this region and leaves queued events unchanged. The completion reports the terminal status and carries no value.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK when observation was changed.
- MLN_STATUS_NOT_FOUND when no region carries region_id.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
◆ mln_runtime_update_offline_region_metadata()
| mln_status mln_runtime_update_offline_region_metadata | ( | mln_runtime | runtime, |
| mln_offline_region_id | region_id, | ||
| const uint8_t * | metadata, | ||
| size_t | metadata_size, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts updating opaque binary metadata for an offline region.
Metadata bytes are copied before this call returns. A successful completion borrows one mln_offline_region_info value carrying the updated region, valid only for the duration of the callback.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, metadata is null with a non-zero metadata_size, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK and one region record.
- MLN_STATUS_NOT_FOUND when no region carries region_id.
- MLN_STATUS_UNSUPPORTED when the stored definition type is unsupported.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
Generated by
1.18.0