|
MapLibre Native C API
Public C ABI for the MapLibre Native wrapper.
|
Go to the source code of this file.
Move the camera, and set how the map shows and limits its view.
| mln_status mln_camera_for_tile | ( | mln_canonical_tile_id | tile, |
| mln_logical_size | logical_size, | ||
| mln_camera_options * | out_camera, | ||
| mln_diagnostic * | out_diagnostic ) |
Computes the camera that shows exactly one tile on a square map.
Jump a map in MLN_MAP_MODE_TILE to the camera to render tile, where logical_size is the map's size. The camera centers the tile, zooms until the tile fills the map, and looks straight down with north up and no padding. The map keeps its camera within its zoom limits, so for a deep tile, raise the maximum zoom past the camera's with mln_map_set_bounds().
Returns:
| mln_status mln_map_apply_camera_delta | ( | mln_map | map, |
| const mln_camera_delta * | delta, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Moves the camera relative to where it is, as a gesture does.
delta can pan the map's content by an offset on the screen, scale the zoom, and add to the bearing and pitch. An anchor keeps one screen point in place while the scale, bearing, or pitch changes. An anchor needs one of those changes, and combines with an offset only when the delta has no animation. The function finishes when the map applies the delta, before an animation ends.
A delta that replaces an animated one starts from where that animation left the camera, so the rest of the replaced change never happens. To reach an exact camera, use mln_map_update_camera().
A delta in the end phase can carry momentum, which keeps the camera moving from the gesture's release velocities and slows it on each rendered frame. The gesture lasts until the momentum ends: the snapshot keeps gesture_in_progress set, and camera events report MLN_CAMERA_CHANGE_SOURCE_MOMENTUM. With momentum, animation sets only transition_id and the end handler, which runs when the gesture ends.
A delta in the begin phase, mln_map_cancel_camera_transitions(), or a cancellation by that ID stops the momentum. A later command that sets a field stops only the parts of the momentum that move that field. On a tilted map, the pan moves the map's content the same distance on the screen in every direction.
| mln_status mln_map_camera_for_geometry | ( | mln_map | map, |
| mln_buffer_view | geometry, | ||
| const mln_camera_fit_options * | fit_options, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Computes a camera that fits a GeoJSON geometry in the map's view.
geometry is a GeoJSON geometry object with at least one coordinate, not a feature. The camera keeps the map's bearing and pitch unless fit_options sets them, and its zoom stays within the map's zoom limits.
Completes with:
| mln_status mln_map_camera_for_lat_lng_bounds | ( | mln_map | map, |
| mln_lat_lng_bounds | bounds, | ||
| const mln_camera_fit_options * | fit_options, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Computes a camera that fits bounds in the map's view.
The camera keeps the map's bearing and pitch unless fit_options sets them, and its zoom stays within the map's zoom limits.
Completes with:
| mln_status mln_map_camera_for_lat_lngs | ( | mln_map | map, |
| const mln_lat_lng * | coordinates, | ||
| size_t | coordinate_count, | ||
| const mln_camera_fit_options * | fit_options, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Computes a camera that fits coordinates in the map's view.
coordinates must not be empty. The camera keeps the map's bearing and pitch unless fit_options sets them, and its zoom stays within the map's zoom limits.
Completes with:
| mln_status mln_map_cancel_camera_transitions | ( | mln_map | map, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Stops every running camera animation where it is.
The end handler of each stopped animation reports MLN_CAMERA_TRANSITION_OUTCOME_CANCELLED.
| mln_status mln_map_cancel_camera_transitions_with_id | ( | mln_map | map, |
| uint64_t | transition_id, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Stops the running camera animations whose animation options set transition_id.
Other animations keep running. The end handler of each stopped animation reports MLN_CAMERA_TRANSITION_OUTCOME_CANCELLED.
| mln_status mln_map_dump_debug_logs | ( | mln_map | map, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Logs debugging information about the map's style and sources.
| mln_status mln_map_fit_camera_to_geometry | ( | mln_map | map, |
| mln_buffer_view | geometry, | ||
| const mln_camera_fit_update * | update, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Moves the camera to fit a GeoJSON geometry in the map's view, at once or with an animation.
geometry is a GeoJSON geometry object with at least one coordinate, not a feature. The camera is the one that mln_map_camera_for_geometry() computes after the commands sent before this one apply. The function finishes when the map applies the change, before an animation ends.
Completes with:
| mln_status mln_map_fit_camera_to_lat_lng_bounds | ( | mln_map | map, |
| mln_lat_lng_bounds | bounds, | ||
| const mln_camera_fit_update * | update, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Moves the camera to fit bounds in the map's view, at once or with an animation.
The camera is the one that mln_map_camera_for_lat_lng_bounds() computes after the commands sent before this one apply. The function finishes when the map applies the change, before an animation ends.
Completes with:
| mln_status mln_map_fit_camera_to_lat_lngs | ( | mln_map | map, |
| const mln_lat_lng * | coordinates, | ||
| size_t | coordinate_count, | ||
| const mln_camera_fit_update * | update, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Moves the camera to fit coordinates in the map's view, at once or with an animation.
coordinates must not be empty. The camera is the one that mln_map_camera_for_lat_lngs() computes after the commands sent before this one apply. The function finishes when the map applies the change, before an animation ends.
Completes with:
| mln_status mln_map_get_camera | ( | mln_map | map, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Reads the map's camera.
The query reads the camera after the map applies the commands sent before it.
| mln_status mln_map_lat_lng_bounds_for_camera | ( | mln_map | map, |
| const mln_camera_options * | camera, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Computes the area that the map would show with camera.
Camera fields that camera doesn't set come from the map's camera. The longitudes can fall outside -180 to 180, so a view across the antimeridian gives one continuous range.
| mln_status mln_map_set_bounds | ( | mln_map | map, |
| const mln_bound_options * | options, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Limits the camera's center to an area, and its zoom and pitch to ranges.
Limits that options doesn't set keep their current values. When the camera is outside the new limits, it moves inside them.
| mln_status mln_map_set_debug_flags | ( | mln_map | map, |
| mln_map_debug_flags | flags, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Draws debugging overlays, such as tile borders, on the map.
flags replaces the overlays set before.
| mln_status mln_map_set_free_camera_options | ( | mln_map | map, |
| const mln_free_camera_options * | options, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Places the camera at a position and orientation in space.
The map adjusts them to a camera that it can show. It stops running camera animations first, and their end handlers report MLN_CAMERA_TRANSITION_OUTCOME_CANCELLED.
| mln_status mln_map_set_projection_mode | ( | mln_map | map, |
| const mln_projection_mode_options * | options, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Sets whether the map draws in perspective or axonometric projection, and how much it skews the view.
Settings that options doesn't set keep their current values.
| mln_status mln_map_set_rendering_stats_view_enabled | ( | mln_map | map, |
| bool | enabled, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Shows or hides an overlay of rendering statistics on the map.
| mln_status mln_map_set_tile_options | ( | mln_map | map, |
| const mln_map_tile_options * | options, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Sets how the map chooses which tiles to load, and at what detail.
Settings that options doesn't set keep their current values.
| mln_status mln_map_set_viewport_options | ( | mln_map | map, |
| const mln_map_viewport_options * | options, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Sets how the map orients and constrains its view.
Settings that options doesn't set keep their current values.
| mln_status mln_map_update_camera | ( | mln_map | map, |
| const mln_camera_update * | update, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Moves the camera, at once or with an animation.
Camera fields that update doesn't set keep their values, and the update stops any running animation of the fields it sets. The function finishes when the map applies the update, before an animation ends. To learn when an animation ends, set an mln_camera_transition_handler in its animation options.