Functions
mln_status	mln_render_session_resize (mln_render_session *session, uint32_t width, uint32_t height, double scale_factor)

mln_status	mln_render_session_render_update (mln_render_session session, bool out_rendered)

mln_status	mln_render_session_detach (mln_render_session *session)

mln_status	mln_render_session_destroy (mln_render_session *session)

mln_status	mln_render_session_reduce_memory_use (mln_render_session *session)

mln_status	mln_render_session_clear_data (mln_render_session *session)

mln_status	mln_render_session_dump_debug_logs (mln_render_session *session)

mln_status	mln_render_session_set_feature_state (mln_render_session session, const mln_feature_state_selector selector, const mln_json_value *state)

mln_status	mln_render_session_get_feature_state (mln_render_session session, const mln_feature_state_selector selector, mln_json_snapshot **out_state)

mln_status	mln_render_session_remove_feature_state (mln_render_session session, const mln_feature_state_selector selector)

mln_status	mln_json_snapshot_get (const mln_json_snapshot snapshot, const mln_json_value *out_value)

void	mln_json_snapshot_destroy (mln_json_snapshot *snapshot)

Detailed Description

Public C API declarations for render sessions.

Function Documentation

◆ mln_json_snapshot_destroy()

void mln_json_snapshot_destroy ( mln_json_snapshot * snapshot )

Destroys a JSON snapshot handle. Null is accepted as a no-op.

◆ mln_json_snapshot_get()

mln_status mln_json_snapshot_get	(	const mln_json_snapshot *	snapshot,
		const mln_json_value **	out_value )

Borrows the root JSON value from a snapshot handle.

The returned pointer and all nested pointers remain valid until the snapshot is destroyed.

Returns:

MLN_STATUS_OK on success.
MLN_STATUS_INVALID_ARGUMENT when snapshot is null or not live, or out_value is null.
MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

◆ mln_render_session_clear_data()

mln_status mln_render_session_clear_data ( mln_render_session * session )

Clears renderer data for the session.

Returns:

MLN_STATUS_OK on success.
MLN_STATUS_INVALID_ARGUMENT when session is null or not live.
MLN_STATUS_INVALID_STATE when the session is detached or no renderer has been created for the session yet.
MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
MLN_STATUS_NATIVE_ERROR when the render backend reports no renderer backend, or when an internal exception is converted to status.

◆ mln_render_session_destroy()

mln_status mln_render_session_destroy ( mln_render_session * session )

Destroys a render session handle.

If the session is still attached, this function detaches it first.

Returns:

MLN_STATUS_OK on success.
MLN_STATUS_INVALID_ARGUMENT when session is null or not live.
MLN_STATUS_INVALID_STATE when a texture frame is acquired.
MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

◆ mln_render_session_detach()

mln_status mln_render_session_detach ( mln_render_session * session )

Detaches backend-bound render resources from the map while keeping the session handle live for destruction.

After detach, resize, render, readback, acquire, and renderer maintenance operations return MLN_STATUS_INVALID_STATE.

Returns:

MLN_STATUS_OK on success.
MLN_STATUS_INVALID_ARGUMENT when session is null or not live.
MLN_STATUS_INVALID_STATE when already detached or a texture frame is acquired.
MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

◆ mln_render_session_dump_debug_logs()

mln_status mln_render_session_dump_debug_logs ( mln_render_session * session )

Dumps renderer debug logs for the session through MapLibre Native logging.

Returns:

MLN_STATUS_OK on success.
MLN_STATUS_INVALID_ARGUMENT when session is null or not live.
MLN_STATUS_INVALID_STATE when the session is detached or no renderer has been created for the session yet.
MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
MLN_STATUS_NATIVE_ERROR when the render backend reports no renderer backend, or when an internal exception is converted to status.

◆ mln_render_session_get_feature_state()

mln_status mln_render_session_get_feature_state	(	mln_render_session *	session,
		const mln_feature_state_selector *	selector,
		mln_json_snapshot **	out_state )

Copies per-feature state from a render source in this render session.

The session renderer must already exist. selector->source_id and selector->feature_id are borrowed for the duration of the call. On success, *out_state receives an owned snapshot handle. Use mln_json_snapshot_get() to borrow its root JSON object value, and destroy it with mln_json_snapshot_destroy(). Missing native source or feature state is reported as an empty object snapshot.

Returns:

MLN_STATUS_OK on success.
MLN_STATUS_INVALID_ARGUMENT when session is null or not live, selector is null or invalid, selector lacks MLN_FEATURE_STATE_SELECTOR_FEATURE_ID, out_state is null, or *out_state is not null.
MLN_STATUS_INVALID_STATE when the session is detached or no renderer has been created for the session yet.
MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
MLN_STATUS_NATIVE_ERROR when the render backend reports no renderer backend, or when an internal exception is converted to status.

◆ mln_render_session_reduce_memory_use()

mln_status mln_render_session_reduce_memory_use ( mln_render_session * session )

Asks the session renderer to release cached resources where possible.

Returns:

MLN_STATUS_OK on success.
MLN_STATUS_INVALID_ARGUMENT when session is null or not live.
MLN_STATUS_INVALID_STATE when the session is detached or no renderer has been created for the session yet.
MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
MLN_STATUS_NATIVE_ERROR when the render backend reports no renderer backend, or when an internal exception is converted to status.

◆ mln_render_session_remove_feature_state()

mln_status mln_render_session_remove_feature_state	(	mln_render_session *	session,
		const mln_feature_state_selector *	selector )

Removes per-feature state from a render source in this render session.

The session renderer must already exist. 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 on success.
MLN_STATUS_INVALID_ARGUMENT when session is null or not live, selector is null or invalid, or selector has MLN_FEATURE_STATE_SELECTOR_STATE_KEY without MLN_FEATURE_STATE_SELECTOR_FEATURE_ID.
MLN_STATUS_INVALID_STATE when the session is detached or no renderer has been created for the session yet.
MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
MLN_STATUS_NATIVE_ERROR when the render backend reports no renderer backend, or when an internal exception is converted to status.

◆ mln_render_session_render_update()

mln_status mln_render_session_render_update	(	mln_render_session *	session,
		bool *	out_rendered )

Processes the latest map render update for an attached render session.

Surface sessions render and present through their native surface. Texture sessions render into their texture target.

On success, *out_rendered reports whether the latest available map render update was rendered. The map retains its latest update, so repeated calls re-render it and report true again; hosts use this to redraw on demand after resize or surface expose, and gate frame-driven loops on MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE instead of the return value. *out_rendered is false when no frame was rendered: the map has not published a render update yet, or the renderer skipped producing a frame for the latest update (for example the Metal texture backend before content is ready). Both are normal during startup; keep pumping the runtime and call again when an update is reported.

Returns:

MLN_STATUS_OK on success, with *out_rendered set.
MLN_STATUS_INVALID_ARGUMENT when session is null or not live, or out_rendered is null.
MLN_STATUS_INVALID_STATE when the session is detached or a texture frame is currently acquired.
MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
MLN_STATUS_NATIVE_ERROR when the render backend reports no renderer backend, or when an internal exception is converted to status.

◆ mln_render_session_resize()

mln_status mln_render_session_resize	(	mln_render_session *	session,
		uint32_t	width,
		uint32_t	height,
		double	scale_factor )

Resizes an attached render session.

Width and height are logical map dimensions. The scale_factor value maps them to physical backend pixels. Resizing sets the map size, so the map viewport and the render target extent stay the same value.

Surface and session-owned texture sessions resize in place. Caller-owned borrowed texture targets return MLN_STATUS_UNSUPPORTED because the texture is sized by its owner; follow a host whose target changed by destroying the session with mln_render_session_destroy() (or releasing the map slot with mln_render_session_detach()), recreating the texture, and attaching a new session. A map holds at most one attached session, so detach or destroy the old session before attaching the replacement.

Resizing discards the session renderer, which is rebuilt on the next mln_render_session_render_update(). Renderer-held state, including feature state set through mln_render_session_set_feature_state(), does not survive. Map state such as camera, style, and sources lives on the map and survives both resize and reattach.

Passing a scale_factor that differs from the map's mln_map_options scale_factor logs a warning; see mln_map_options.

Returns:

MLN_STATUS_OK on success.
MLN_STATUS_INVALID_ARGUMENT when session is null or not live, dimensions are zero, scale_factor is non-positive or non-finite, or scaled dimensions are too large.
MLN_STATUS_INVALID_STATE when the session is detached or a texture frame is currently acquired.
MLN_STATUS_UNSUPPORTED when resizing is not supported by the session kind or mode, such as a caller-owned borrowed texture target.
MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

◆ mln_render_session_set_feature_state()

mln_status mln_render_session_set_feature_state	(	mln_render_session *	session,
		const mln_feature_state_selector *	selector,
		const mln_json_value *	state )

Sets per-feature state on a render source for this render session.

The session renderer must already exist; call mln_render_session_render_update() once after loading style data before using feature state. selector->source_id and selector->feature_id are borrowed for the duration of the call. state must be a JSON object descriptor and is copied before return. The accepted command requests a map repaint.

Returns:

MLN_STATUS_OK on success.
MLN_STATUS_INVALID_ARGUMENT when session is null or not live, selector is null or invalid, selector lacks MLN_FEATURE_STATE_SELECTOR_FEATURE_ID, state is null or not an object, state contains invalid descriptor data, or state contains non-finite numbers.
MLN_STATUS_INVALID_STATE when the session is detached or no renderer has been created for the session yet.
MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
MLN_STATUS_NATIVE_ERROR when the render backend reports no renderer backend, or when an internal exception is converted to status.

Functions

Detailed Description

Function Documentation

◆ mln_json_snapshot_destroy()

◆ mln_json_snapshot_get()

◆ mln_render_session_clear_data()

◆ mln_render_session_destroy()

◆ mln_render_session_detach()

◆ mln_render_session_dump_debug_logs()

◆ mln_render_session_get_feature_state()

◆ mln_render_session_reduce_memory_use()

◆ mln_render_session_remove_feature_state()

◆ mln_render_session_render_update()

◆ mln_render_session_resize()

◆ mln_render_session_set_feature_state()