MapLibre Native C API
Public C ABI for the MapLibre Native wrapper.
Loading...
Searching...
No Matches
render_session.h File Reference

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 }

Functions

mln_status mln_render_session_get_capabilities (mln_render_session session, mln_render_session_capabilities *out_capabilities, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_get_snapshot (mln_render_session session, mln_render_session_snapshot *out_snapshot, mln_diagnostic *out_diagnostic)
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)
mln_status mln_render_session_demand_frame (mln_render_session session, const mln_frame_demand *demand, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_set_frame_pacer (mln_render_session session, mln_frame_pacer pacer, mln_diagnostic *out_diagnostic)
void mln_frame_pacer_release (mln_frame_pacer pacer)
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)
void mln_render_frame_batch_release (mln_render_frame_batch batch)
mln_status mln_render_session_acquire_frame (mln_render_session session, mln_acquired_frame *out_frame, mln_diagnostic *out_diagnostic)
mln_status mln_acquired_frame_get_result (mln_acquired_frame frame, mln_render_frame_result *out_result, mln_diagnostic *out_diagnostic)
mln_status mln_acquired_frame_get_producer_sync (mln_acquired_frame frame, mln_gpu_sync *out_sync, mln_diagnostic *out_diagnostic)
mln_status mln_acquired_frame_release (mln_acquired_frame frame, const mln_gpu_sync *consumer_completion, mln_diagnostic *out_diagnostic)
mln_status mln_acquired_frame_view_begin (mln_acquired_frame frame, void **out_scope, mln_diagnostic *out_diagnostic)
void mln_acquired_frame_view_end (void *scope)
mln_status mln_render_session_resize (mln_render_session session, mln_logical_size logical_size, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_release_target (mln_render_session session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_barrier (mln_render_session session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_reduce_memory_use (mln_render_session session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_clear_data (mln_render_session session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_dump_debug_logs (mln_render_session session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_service_driver_work (mln_render_session session, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_detach (mln_render_session session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_abandon (mln_render_session session, mln_render_abandon_result *out_result, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_release (mln_render_session session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_dispose (mln_render_session session, mln_diagnostic *out_diagnostic)
mln_status mln_acquired_frame_discard (mln_acquired_frame frame, mln_diagnostic *out_diagnostic)

Detailed Description

Render a map's frames to an attached target, and manage the session.

Macro Definition Documentation

◆ MLN_FRAME_DEMAND_TOKEN_STILL_IMAGE

#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 Documentation

◆ mln_frame_demand

typedef struct mln_frame_demand mln_frame_demand

A demand for one frame.

◆ 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.

◆ mln_frame_demand_flags

typedef uint32_t mln_frame_demand_flags

A set of mln_frame_demand_flag bits.

◆ mln_frame_pacer_option_field

The optional settings of a frame pacer.

◆ mln_frame_pacer_option_fields

◆ mln_frame_pacer_options

typedef struct mln_frame_pacer_options mln_frame_pacer_options

Options for creating a frame pacer.

◆ mln_render_abandon_disposition

What mln_render_session_abandon() did with a session's graphics objects.

◆ mln_render_abandon_result

typedef struct mln_render_abandon_result mln_render_abandon_result

◆ mln_render_frame_batch_view

typedef struct mln_render_frame_batch_view mln_render_frame_batch_view

The frame results that mln_render_session_drain_frame_results() took.

◆ mln_render_frame_result

typedef struct mln_render_frame_result mln_render_frame_result

How one frame demand finished.

◆ mln_render_result

How a frame demand finished.

◆ mln_render_session_snapshot

typedef struct mln_render_session_snapshot mln_render_session_snapshot

The state of a render session at one moment.

◆ mln_render_session_state

Where a render session is in its life.

Enumeration Type Documentation

◆ mln_frame_demand_flag

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.

Enumerator
MLN_FRAME_DEMAND_FORCE 

Draws a frame even when nothing changed since the last one. It can't be combined with MLN_FRAME_DEMAND_WAIT_FOR_UPDATE.

MLN_FRAME_DEMAND_WAIT_FOR_UPDATE 

When the map has nothing new to draw, waits for its next update instead of finishing with MLN_RENDER_RESULT_NO_UPDATE.

◆ mln_frame_pacer_option_field

The optional settings of a frame pacer.

Enumerator
MLN_FRAME_PACER_OPTION_MAXIMUM_FRAMES_PER_SECOND 

◆ mln_render_abandon_disposition

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.

◆ mln_render_result

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.

◆ mln_render_session_state

enum mln_render_session_state : uint32_t

Where a render session is in its life.

Enumerator
MLN_RENDER_SESSION_STATE_ATTACHING 
MLN_RENDER_SESSION_STATE_ATTACHED 
MLN_RENDER_SESSION_STATE_DETACHING 
MLN_RENDER_SESSION_STATE_DETACHED 
MLN_RENDER_SESSION_STATE_FAILED 
MLN_RENDER_SESSION_STATE_ABANDONED 

Function Documentation

◆ mln_acquired_frame_discard()

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_acquired_frame_get_producer_sync()

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:

  • MLN_STATUS_TARGET_LOST when the session failed, or you detached, abandoned, or disposed it.

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_acquired_frame_get_result()

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_acquired_frame_release()

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_acquired_frame_view_begin()

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:

  • MLN_STATUS_TARGET_LOST when the session failed, or you detached, abandoned, or disposed it.

Lifetimes: Pass out_scope to mln_acquired_frame_view_end().

◆ mln_acquired_frame_view_end()

void mln_acquired_frame_view_end ( void * scope)

Ends a view that mln_acquired_frame_view_begin() began.

◆ mln_frame_pacer_release()

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.

◆ mln_render_frame_batch_release()

void mln_render_frame_batch_release ( mln_render_frame_batch batch)

Frees a batch of frame results.

◆ mln_render_session_abandon()

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_render_session_acquire_frame()

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_UNSUPPORTED when the session lacks MLN_RENDER_SESSION_CAPABILITY_FRAME_ACQUISITION.
  • MLN_STATUS_TARGET_LOST or MLN_STATUS_NATIVE_ERROR, as mln_render_session_snapshot.failure_status reports, when the session has failed.
  • MLN_STATUS_INVALID_STATE when you detached, abandoned, released, or disposed the session.

◆ mln_render_session_barrier()

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_TARGET_LOST when the session loses its target before the barrier runs.

◆ mln_render_session_clear_data()

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_TARGET_LOST when the session loses its target before the work runs.

◆ mln_render_session_demand_frame()

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_TARGET_LOST or MLN_STATUS_NATIVE_ERROR, as mln_render_session_snapshot.failure_status reports, when the session has failed.
  • MLN_STATUS_INVALID_STATE when you detached, abandoned, released, or disposed the session, or discarded a frame from every texture of its ring.

◆ mln_render_session_detach()

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_TARGET_LOST when the session loses its target before the detach runs.

◆ mln_render_session_dispose()

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_render_session_drain_frame_results()

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_render_session_dump_debug_logs()

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_TARGET_LOST when the session loses its target before the work runs.

◆ mln_render_session_get_capabilities()

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_render_session_get_failure()

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_render_session_get_snapshot()

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_render_session_reduce_memory_use()

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_TARGET_LOST when the session loses its target before the work runs.

◆ mln_render_session_release()

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_INVALID_STATE while you hold one of the session's acquired frames. Release or discard them first.

◆ mln_render_session_release_target()

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:

  • MLN_STATUS_UNSUPPORTED when the session renders offscreen or into Android hardware buffers, dmabufs, DXGI shared textures, or IOSurfaces that it allocates.

Completes with:

  • MLN_STATUS_UNSUPPORTED when the target is a WebGL canvas.
  • MLN_STATUS_TARGET_LOST when the session loses its target before the release runs.

◆ mln_render_session_resize()

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:

  • MLN_STATUS_UNSUPPORTED when the session renders into a borrowed ring. Give it new textures of the new size instead.

Completes with:

  • MLN_STATUS_TARGET_LOST when the session loses its target before the resize applies.

◆ mln_render_session_service_driver_work()

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_render_session_set_frame_pacer()

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:

  • MLN_STATUS_TARGET_LOST or MLN_STATUS_NATIVE_ERROR, as mln_render_session_snapshot.failure_status reports, when the session has failed.
  • MLN_STATUS_INVALID_STATE when you attached the session with a redraw wake, or detached, abandoned, released, or disposed it.