Go to the source code of this file.
Typedefs | |
| typedef enum mln_render_result | mln_render_result |
Enumerations | |
| enum | mln_render_result : uint32_t { MLN_RENDER_RESULT_RENDERED = 0 , MLN_RENDER_RESULT_NO_UPDATE , MLN_RENDER_RESULT_SIZE_PENDING , MLN_RENDER_RESULT_TARGET_NOT_READY } |
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, mln_render_result *out_result, bool *out_needs_repaint) |
| mln_status | mln_render_session_projection_create (mln_render_session session, mln_map_projection *out_projection) |
| 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) |
Detailed Description
Public C API declarations for render sessions.
Typedef Documentation
◆ mln_render_result
| typedef enum mln_render_result mln_render_result |
Outcome of a successful mln_render_session_render_update() call.
Enumeration Type Documentation
◆ mln_render_result
| enum mln_render_result : uint32_t |
Outcome of a successful mln_render_session_render_update() call.
Function Documentation
◆ mln_render_session_clear_data()
| mln_status mln_render_session_clear_data | ( | mln_render_session | session | ) |
Clears renderer data for the session.
The next frame rebuilds renderer data and restores the map's feature state. Continuous maps publish a render update. Static and tile maps rebuild when the host requests a still image.
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_projection_create()
| mln_status mln_render_session_projection_create | ( | mln_render_session | session, |
| mln_map_projection * | out_projection ) |
Creates a standalone projection from the session's last rendered update.
Call on the session owner thread after mln_render_session_render_update() reports MLN_RENDER_RESULT_RENDERED, before rendering another frame or changing the target. Creation is also allowed while an owned texture frame is acquired. Pair the projection with that frame and its presentation extent. The snapshot describes render coordinates; GPU completion and presentation follow the render target's synchronization contract.
The session captures the full transform of the update passed to the renderer. Later live-map changes and render calls that produce no frame preserve this snapshot. Resize and target replacement invalidate it until a frame renders into the new target.
The returned helper owns a separate copy of the transform. It remains usable after later renders, target changes, detach, and destruction of the session or map. Its projection and camera operations are synchronous and serialized across threads, as for mln_map_projection_create(). Destroy it with mln_map_projection_destroy().
Returns:
- MLN_STATUS_OK on success; *out_projection receives an owned handle.
- MLN_STATUS_INVALID_ARGUMENT when session is null or not live, out_projection is null, or *out_projection is not null.
- MLN_STATUS_INVALID_STATE when the session is detached or its current target has no rendered projection.
- MLN_STATUS_WRONG_THREAD when called outside the session owner thread.
- MLN_STATUS_NATIVE_ERROR 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_render_update()
| mln_status mln_render_session_render_update | ( | mln_render_session | session, |
| mln_render_result * | out_result, | ||
| bool * | out_needs_repaint ) |
Renders the map's latest render update into the session's render target.
Drains queued render-thread work before deciding whether a frame is needed. A surface session presents the frame. A texture session writes it into the target texture. Each update renders once per target. Resize and target replacement allow the latest update to render again. For a surface expose on a continuous map, call mln_map_request_repaint() and pump the runtime; for a static map, request another still image.
*out_result reports which of these outcomes the call reached, and each one names the wake that a host waits for before it calls again:
- MLN_RENDER_RESULT_RENDERED means the target holds a new frame. Gate a frame loop on MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE.
- MLN_RENDER_RESULT_NO_UPDATE means the call produced no frame. The latest update already rendered, the map has no update yet, a static map is waiting for style or tile data, or the Metal backend has not created an owned texture. Wait for MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE.
- MLN_RENDER_RESULT_SIZE_PENDING means the session resized and the map, which applies its size on its own thread, is still behind. The map publishes an update for the new size on its own, so wait for the next MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE.
- MLN_RENDER_RESULT_TARGET_NOT_READY means the render target had no frame available, such as a Metal surface whose next drawable is nil or an Android Vulkan surface whose swapchain had no free image within the acquire bound. No map update resolves this, so wait for a host event that changes the target, or back off and retry.
In MLN_MAP_MODE_STATIC, pump a resize through the map before requesting the still image. The session applies its extent on the map's owner thread, and a still image requested before that lands reports MLN_RENDER_RESULT_SIZE_PENDING.
*out_needs_repaint reports the renderer's need for another frame, such as during a paint transition. It is true only when *out_result is MLN_RENDER_RESULT_RENDERED. It matches the needs_repaint field of MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_FINISHED. Camera animations advance separately on the map's owner thread. Pump the runtime and gate rendering on MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE to receive fresh updates for both camera animations and renderer transitions.
Returns:
- MLN_STATUS_OK on success, with *out_result and *out_needs_repaint set.
- MLN_STATUS_INVALID_ARGUMENT when session is null or not live, or out_result or out_needs_repaint 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; hand a replacement over with the mln_*_borrowed_texture_set_target() function for the backend. See texture.h.
The session renderer survives a resize, carrying the tile pyramid, glyph and image atlases, and symbol placement across to the new size. A scale_factor that differs from the session's current value retires the renderer instead, because its shaders are compiled for a fixed pixel ratio, and renderer-held tile and atlas state starts empty on the next mln_render_session_render_update(). Map state such as camera, style, sources, and feature state survives either way. The session pushes map feature state into a replacement renderer on the next render update.
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.
Generated by
1.13.2