|
MapLibre Native C API
Public C ABI for the MapLibre Native wrapper.
|
Go to the source code of this file.
Data Structures | |
| struct | mln_frame_demand |
| struct | mln_render_frame_result |
| struct | mln_render_frame_batch_view |
| struct | mln_render_session_snapshot |
| struct | mln_render_abandon_result |
| struct | mln_frame_pacer_options |
Macros | |
| #define | MLN_FRAME_DEMAND_TOKEN_STILL_IMAGE UINT64_MAX |
Typedefs | |
| typedef enum mln_render_result | mln_render_result |
| typedef enum mln_render_session_state | mln_render_session_state |
| typedef enum mln_frame_demand_flag | mln_frame_demand_flag |
| typedef uint32_t | mln_frame_demand_flags |
| typedef struct mln_frame_demand | mln_frame_demand |
| typedef struct mln_render_frame_result | mln_render_frame_result |
| typedef struct mln_render_frame_batch_view | mln_render_frame_batch_view |
| typedef struct mln_render_session_snapshot | mln_render_session_snapshot |
| typedef enum mln_render_abandon_disposition | mln_render_abandon_disposition |
| typedef struct mln_render_abandon_result | mln_render_abandon_result |
| typedef enum mln_frame_pacer_option_field | mln_frame_pacer_option_field |
| typedef uint32_t | mln_frame_pacer_option_fields |
| typedef struct mln_frame_pacer_options | mln_frame_pacer_options |
Enumerations | |
| enum | mln_render_result : uint32_t { MLN_RENDER_RESULT_RENDERED = 0 , MLN_RENDER_RESULT_NO_UPDATE = 1 , MLN_RENDER_RESULT_TARGET_NOT_READY = 2 , MLN_RENDER_RESULT_SUPERSEDED = 3 , MLN_RENDER_RESULT_FAILED = 4 } |
| enum | mln_render_session_state : uint32_t { MLN_RENDER_SESSION_STATE_ATTACHING = 1U , MLN_RENDER_SESSION_STATE_ATTACHED = 2U , MLN_RENDER_SESSION_STATE_DETACHING = 3U , MLN_RENDER_SESSION_STATE_DETACHED = 4U , MLN_RENDER_SESSION_STATE_FAILED = 5U , MLN_RENDER_SESSION_STATE_ABANDONED = 6U } |
| enum | mln_frame_demand_flag : uint32_t { MLN_FRAME_DEMAND_FORCE = 1U << 0U , MLN_FRAME_DEMAND_WAIT_FOR_UPDATE = 1U << 2U } |
| enum | mln_render_abandon_disposition : uint32_t { MLN_RENDER_ABANDON_DISPOSITION_CLEAN = 0U , MLN_RENDER_ABANDON_DISPOSITION_QUARANTINED = 1U } |
| enum | mln_frame_pacer_option_field : uint32_t { MLN_FRAME_PACER_OPTION_MAXIMUM_FRAMES_PER_SECOND = 1U << 0U } |
Render a map's frames to an attached target, and manage the session.
| #define MLN_FRAME_DEMAND_TOKEN_STILL_IMAGE UINT64_MAX |
The token of the frame results that a session adds when it renders an image for mln_map_request_still_image(). Your own demands can't use it.
| typedef struct mln_frame_demand mln_frame_demand |
A demand for one frame.
| typedef enum mln_frame_demand_flag mln_frame_demand_flag |
How a frame demand behaves.
Without flags, a demand draws a frame when the map changed since the last one, and otherwise finishes with MLN_RENDER_RESULT_NO_UPDATE. A session with a surface target shows each frame that it draws.
| typedef uint32_t mln_frame_demand_flags |
A set of mln_frame_demand_flag bits.
| typedef enum mln_frame_pacer_option_field mln_frame_pacer_option_field |
The optional settings of a frame pacer.
| typedef uint32_t mln_frame_pacer_option_fields |
A set of mln_frame_pacer_option_field bits.
| typedef struct mln_frame_pacer_options mln_frame_pacer_options |
Options for creating a frame pacer.
What mln_render_session_abandon() did with a session's graphics objects.
| typedef struct mln_render_abandon_result mln_render_abandon_result |
The outcome of mln_render_session_abandon().
| typedef struct mln_render_frame_batch_view mln_render_frame_batch_view |
The frame results that mln_render_session_drain_frame_results() took.
| typedef struct mln_render_frame_result mln_render_frame_result |
How one frame demand finished.
| typedef enum mln_render_result mln_render_result |
How a frame demand finished.
| typedef struct mln_render_session_snapshot mln_render_session_snapshot |
The state of a render session at one moment.
| typedef enum mln_render_session_state mln_render_session_state |
Where a render session is in its life.
| enum mln_frame_demand_flag : uint32_t |
How a frame demand behaves.
Without flags, a demand draws a frame when the map changed since the last one, and otherwise finishes with MLN_RENDER_RESULT_NO_UPDATE. A session with a surface target shows each frame that it draws.
| enum mln_frame_pacer_option_field : uint32_t |
| enum mln_render_abandon_disposition : uint32_t |
What mln_render_session_abandon() did with a session's graphics objects.
| Enumerator | |
|---|---|
| MLN_RENDER_ABANDON_DISPOSITION_CLEAN | |
| MLN_RENDER_ABANDON_DISPOSITION_QUARANTINED | It kept some objects that it couldn't destroy safely. They stay allocated until the process exits. |
| enum mln_render_result : uint32_t |
How a frame demand finished.
| Enumerator | |
|---|---|
| MLN_RENDER_RESULT_RENDERED | |
| MLN_RENDER_RESULT_NO_UPDATE | The map had nothing new to draw. |
| MLN_RENDER_RESULT_TARGET_NOT_READY | The target couldn't take a frame, such as while a window is hidden or destroyed, or after mln_render_session_release_target(). Demand a frame again later. |
| MLN_RENDER_RESULT_SUPERSEDED | A later demand with the same flags replaced this one. |
| MLN_RENDER_RESULT_FAILED | The session failed, and mln_render_session_get_failure() reports why. Once mln_render_session_release() completes, you can attach a new session. |
| enum mln_render_session_state : uint32_t |
| mln_status mln_acquired_frame_discard | ( | mln_acquired_frame | frame, |
| mln_diagnostic * | out_diagnostic ) |
Gives up an acquired frame without saying when your GPU stops reading it.
Because your GPU may still read the frame's texture, the session never renders into that texture again.
| mln_status mln_acquired_frame_get_producer_sync | ( | mln_acquired_frame | frame, |
| mln_gpu_sync * | out_sync, | ||
| mln_diagnostic * | out_diagnostic ) |
Reads what to wait for before you read an acquired frame's texture.
Returns:
Lifetimes: The object that out_sync names belongs to the session. It stays valid until you release or discard the frame, or the session is abandoned or disposed.
| mln_status mln_acquired_frame_get_result | ( | mln_acquired_frame | frame, |
| mln_render_frame_result * | out_result, | ||
| mln_diagnostic * | out_diagnostic ) |
Reads the frame result of an acquired frame.
It succeeds until you release or discard the frame, whatever the session's state.
| mln_status mln_acquired_frame_release | ( | mln_acquired_frame | frame, |
| const mln_gpu_sync * | consumer_completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Gives an acquired frame back to the session once you're done reading it.
consumer_completion says when your GPU work that reads the texture finishes. Pass MLN_GPU_SYNC_CPU_COMPLETE when that work has already finished. The session waits for that point before it renders into the texture again. If that wait fails, such as for an OpenGL fence outside the session's share group, the session fails.
Returns:
Lifetimes: On success, the session takes ownership of a sync file descriptor or an OpenGL fence that consumer_completion names.
| mln_status mln_acquired_frame_view_begin | ( | mln_acquired_frame | frame, |
| void ** | out_scope, | ||
| mln_diagnostic * | out_diagnostic ) |
Keeps an acquired frame's texture and sync objects in place while you use them.
Until mln_acquired_frame_view_end() ends the view, mln_acquired_frame_release() and mln_render_session_abandon() fail with MLN_STATUS_BUSY.
Returns:
Lifetimes: Pass out_scope to mln_acquired_frame_view_end().
| void mln_acquired_frame_view_end | ( | void * | scope | ) |
Ends a view that mln_acquired_frame_view_begin() began.
| void mln_frame_pacer_release | ( | mln_frame_pacer | pacer | ) |
Releases a frame pacer.
Render sessions that use the pacer stay paced until you release them or set another pacer.
| void mln_render_frame_batch_release | ( | mln_render_frame_batch | batch | ) |
Frees a batch of frame results.
| mln_status mln_render_session_abandon | ( | mln_render_session | session, |
| mln_render_abandon_result * | out_result, | ||
| mln_diagnostic * | out_diagnostic ) |
Stops the session right away, without running its pending graphics work.
Use it when the target's graphics objects are going away and a detach can't finish first. Pending work completes with MLN_STATUS_TARGET_LOST, and pending frame demands finish with MLN_RENDER_RESULT_TARGET_NOT_READY. Once the call returns, the library no longer uses your graphics objects, and you can attach another session to the map. Release the session afterward.
Abandon keeps the session's OpenGL and WebGPU objects until the process exits, and reports how many it kept. Detach the session instead to free them.
Returns:
| mln_status mln_render_session_acquire_frame | ( | mln_render_session | session, |
| mln_acquired_frame * | out_frame, | ||
| mln_diagnostic * | out_diagnostic ) |
Takes the newest rendered frame from the session's texture ring, if one is ready.
Older frames that you haven't acquired are dropped, and the session can render over a frame before you acquire it. While you hold a frame in every texture of the ring, new frames wait until you release one. When no frame is ready, it succeeds and writes the null handle.
Returns:
| mln_status mln_render_session_barrier | ( | mln_render_session | session, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Ends the session's pending frame demands and waits for its earlier work.
Frame demands that haven't started, including those that wait for a map update, finish with MLN_RENDER_RESULT_NO_UPDATE.
Completes with:
| mln_status mln_render_session_clear_data | ( | mln_render_session | session, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Clears the data that the session's renderer holds, such as loaded tiles, and draws the map again.
Completes with:
| mln_status mln_render_session_demand_frame | ( | mln_render_session | session, |
| const mln_frame_demand * | demand, | ||
| mln_diagnostic * | out_diagnostic ) |
Asks the session to render a frame.
The frame shows the map commands that you sent before the call, except the changes that an open command group holds back.
You can call it once the attach call returns. While the attach runs, the demand waits for it to complete. Every demand finishes with one frame result that carries its token, and mln_render_session_drain_frame_results() takes it. A demand without MLN_FRAME_DEMAND_FORCE replaces each pending demand with the same flags.
Returns:
| mln_status mln_render_session_detach | ( | mln_render_session | session, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Detaches the session from its map and frees its graphics objects.
Release every acquired frame first. Pending frame demands finish with MLN_RENDER_RESULT_TARGET_NOT_READY. Once the detach completes, the library no longer uses your graphics objects, and you can attach another session to the map. Release the session afterward.
Completes with:
| mln_status mln_render_session_dispose | ( | mln_render_session | session, |
| mln_diagnostic * | out_diagnostic ) |
Releases the session in any state, and finishes in the background.
Use it from destructors and finalizers, and mln_render_session_release() elsewhere. It ends the session as a release does, except that it abandons a session whose frames you hold, which ends those frames. Keep servicing a session driven by MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD until mln_render_session_service_driver_work() no longer accepts it.
| mln_status mln_render_session_drain_frame_results | ( | mln_render_session | session, |
| mln_render_frame_batch * | out_batch, | ||
| mln_render_frame_batch_view * | out_view, | ||
| mln_diagnostic * | out_diagnostic ) |
Takes the frame results that the session has queued.
When no result is queued, it succeeds and writes the null handle and an empty view.
Lifetimes: out_view stays valid until you pass out_batch to mln_render_frame_batch_release().
| mln_status mln_render_session_dump_debug_logs | ( | mln_render_session | session, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Logs debugging information about the session's renderer.
Completes with:
| mln_status mln_render_session_get_capabilities | ( | mln_render_session | session, |
| mln_render_session_capabilities * | out_capabilities, | ||
| mln_diagnostic * | out_diagnostic ) |
Reads what the session supports.
| mln_status mln_render_session_get_failure | ( | mln_render_session | session, |
| char * | out_message, | ||
| size_t | message_capacity, | ||
| size_t * | out_message_length, | ||
| mln_diagnostic * | out_diagnostic ) |
Reads the message of the error that made the session fail.
mln_render_session_snapshot.failure_status reports the error's status. The message is empty while the session hasn't failed, and doesn't change once it fails.
Lifetimes: The function writes the message and a terminating NUL to out_message only when message_capacity is greater than the message's length. It always sets out_message_length to the length without the NUL.
| mln_status mln_render_session_get_snapshot | ( | mln_render_session | session, |
| mln_render_session_snapshot * | out_snapshot, | ||
| mln_diagnostic * | out_diagnostic ) |
Reads the session's current state.
| mln_status mln_render_session_reduce_memory_use | ( | mln_render_session | session, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Frees memory that the session's renderer can rebuild, such as caches.
Completes with:
| mln_status mln_render_session_release | ( | mln_render_session | session, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Releases the session, detaching it first when it is attached.
Pending frame demands finish with MLN_RENDER_RESULT_TARGET_NOT_READY. Once the release completes, the library no longer uses your graphics objects, and you can attach another session to the map.
A session driven by MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD detaches at your next mln_render_session_service_driver_work(), so keep servicing it until the release completes. When the session isn't attached, such as while it attaches or after it fails, or when you release or dispose its map before that service, the release abandons it as mln_render_session_abandon() does.
Returns:
| mln_status mln_render_session_release_target | ( | mln_render_session | session, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Lets go of the session's surface or textures, and keeps the rest of the session.
Use it when the platform takes a surface away, such as when your app goes to the background. Release every acquired frame first. Frame demands that are still pending, and later ones until you give the session a new target, finish with MLN_RENDER_RESULT_TARGET_NOT_READY. Once the release completes, you can destroy the old target. An Android or OpenHarmony window can go away sooner, as mln_map_attach_android_surface() and mln_map_attach_ohos_surface() say.
Returns:
Completes with:
| mln_status mln_render_session_resize | ( | mln_render_session | session, |
| mln_logical_size | logical_size, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Resizes the session's target and its map.
The session renders at the map's scale factor. Release every acquired frame first.
Returns:
Completes with:
| mln_status mln_render_session_service_driver_work | ( | mln_render_session | session, |
| mln_diagnostic * | out_diagnostic ) |
Runs the session's ready graphics work on your graphics thread.
Use it with MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD, and call it from the same thread every time. Call it each time mln_render_session_attach_options.driver_work_wake is called, even while you demand no frames, until a detach, release, or disposal of the session finishes. It returns once no work is ready.
It accepts a released or disposed session until that release or disposal finishes.
| mln_status mln_render_session_set_frame_pacer | ( | mln_render_session | session, |
| mln_frame_pacer | pacer, | ||
| mln_diagnostic * | out_diagnostic ) |
Sets the frame pacer that demands the session's frames.
At the first display refresh after the session has something new to draw, pacer demands a frame without flags and with token 0. One pacer can serve many sessions. A null pacer stops pacing the session. You can call it once the attach call returns.
Returns: