Struct RenderSessionHandle 

pub struct RenderSessionHandle { /* private fields */ }

Owns one native handle.

A render session draws a map into a surface or a texture.

See mln_render_session in the C API reference.

Implementations

impl RenderSessionHandle

pub fn id(&self) -> u64

Returns the native handle value.

impl RenderSessionHandle

pub fn abandon(&self) -> Result<RenderAbandonResult>

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 Status::TargetLost, and pending frame demands finish with RenderResult::TargetNotReady. 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.

See mln_render_session_abandon in the C API reference.

pub fn acquire_frame(&self) -> Result<Option<AcquiredFrameHandle>>

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.

See mln_render_session_acquire_frame in the C API reference.

Errors

• Status::Unsupported when the session lacks RenderSessionCapabilityFlag::FRAME_ACQUISITION.
• Status::TargetLost or Status::NativeError, as RenderSessionSnapshot::failure_status reports, when the session has failed.
• Status::InvalidState when you detached, abandoned, released, or disposed the session.

pub fn barrier(&self) -> Result<NativeFuture<()>>

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 RenderResult::NoUpdate.

See mln_render_session_barrier in the C API reference.

Errors

• Status::TargetLost when the session loses its target before the barrier runs.

pub fn clear_data(&self) -> Result<NativeFuture<()>>

Clears the data that the session’s renderer holds, such as loaded tiles, and draws the map again.

See mln_render_session_clear_data in the C API reference.

Errors

• Status::TargetLost when the session loses its target before the work runs.

pub fn demand_frame(&self, demand: &FrameDemand) -> Result<()>

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 RenderSessionHandle::drain_frame_results() takes it. A demand without FrameDemandFlag::FORCE replaces each pending demand with the same flags.

See mln_render_session_demand_frame in the C API reference.

Errors

• Status::TargetLost or Status::NativeError, as RenderSessionSnapshot::failure_status reports, when the session has failed.
• Status::InvalidState when you detached, abandoned, released, or disposed the session, or discarded a frame from every texture of its ring.

pub fn detach(&self) -> Result<NativeFuture<()>>

Detaches the session from its map and frees its graphics objects.

Release every acquired frame first. Pending frame demands finish with RenderResult::TargetNotReady. 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.

See mln_render_session_detach in the C API reference.

Errors

• Status::TargetLost when the session loses its target before the detach runs.

pub fn dispose(self) -> Result<RetiringRenderSession, ReleaseError<Self>>

Releases the session in any state, and finishes in the background.

Use it from destructors and finalizers, and RenderSessionHandle::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 RenderDriverKind::CallerGraphicsThread until RenderSessionHandle::service_driver_work() no longer accepts it.

See mln_render_session_dispose in the C API reference.

pub fn drain_frame_results(&self) -> Result<Vec<RenderFrameResult>>

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.

See mln_render_session_drain_frame_results in the C API reference.

pub fn dump_debug_logs(&self) -> Result<NativeFuture<()>>

Logs debugging information about the session’s renderer.

See mln_render_session_dump_debug_logs in the C API reference.

Errors

• Status::TargetLost when the session loses its target before the work runs.

pub fn get_capabilities(&self) -> Result<RenderSessionCapabilities>

Reads what the session supports.

See mln_render_session_get_capabilities in the C API reference.

pub fn get_cluster_children( &self, source_id: &str, cluster_id: u32, ) -> Result<NativeFuture<String>>

Reads the children of a cluster in a clustered GeoJSON source.

cluster_id is the “cluster_id” property of a cluster feature. The result is a GeoJSON feature collection of the clusters and points that the cluster splits into at the next zoom level.

The query reads the source’s data from the session’s most recent render attempt, so a change to the data shows once the session tries to render again.

A cluster ID belongs to one version of the source’s data. After the data changes, feature queries can return IDs from the earlier version until the source’s tiles reload, and such an ID completes with Status::NotFound or names a different cluster. Query the features again for current IDs.

See mln_render_session_get_cluster_children in the C API reference.

Errors

• Status::NotFound when the session’s most recent render attempt had no source named source_id, or the source has no cluster cluster_id.
• Status::InvalidArgument when the source isn’t a GeoJSON source with clustering turned on.

pub fn get_cluster_expansion_zoom( &self, source_id: &str, cluster_id: u32, ) -> Result<NativeFuture<u32>>

Reads the zoom level at which a cluster of a clustered GeoJSON source splits.

cluster_id is the “cluster_id” property of a cluster feature. At the result’s zoom level, the cluster splits into two or more clusters or points.

A cluster ID can go out of date as RenderSessionHandle::get_cluster_children() describes.

See mln_render_session_get_cluster_expansion_zoom in the C API reference.

Errors

• Status::NotFound when the session’s most recent render attempt had no source named source_id, or the source has no cluster cluster_id.
• Status::InvalidArgument when the source isn’t a GeoJSON source with clustering turned on.

pub fn get_cluster_leaves( &self, source_id: &str, cluster_id: u32, limit: u32, offset: u32, ) -> Result<NativeFuture<String>>

Reads the points in a cluster of a clustered GeoJSON source.

cluster_id is the “cluster_id” property of a cluster feature. The result is a GeoJSON feature collection of the original point features. It skips the first offset points and then holds up to limit of them, so a limit of 0 gives an empty collection.

A cluster ID can go out of date as RenderSessionHandle::get_cluster_children() describes.

See mln_render_session_get_cluster_leaves in the C API reference.

Errors

• Status::NotFound when the session’s most recent render attempt had no source named source_id, or the source has no cluster cluster_id.
• Status::InvalidArgument when the source isn’t a GeoJSON source with clustering turned on.

pub fn get_failure(&self) -> Result<String>

Reads the message of the error that made the session fail.

RenderSessionSnapshot::failure_status reports the error’s status. The message is empty while the session hasn’t failed, and doesn’t change once it fails.

See mln_render_session_get_failure in the C API reference.

pub fn get_snapshot(&self) -> Result<RenderSessionSnapshot>

Reads the session’s current state.

See mln_render_session_get_snapshot in the C API reference.

pub fn query_rendered_features( &self, geometry: &RenderedQueryGeometry, options: Option<&RenderedFeatureQueryOptions<'_>>, ) -> Result<NativeFuture<Vec<RenderedFeature>>>

Finds the features that the session drew in an area of the screen.

The query reads the last frame that the session rendered. A feature that several layers draw appears once for each layer.

See mln_render_session_query_rendered_features in the C API reference.

pub fn query_source_features( &self, source_id: &str, options: Option<&SourceFeatureQueryOptions<'_>>, ) -> Result<NativeFuture<Vec<SourceFeature>>>

Finds the features of the source named source_id.

The query covers only the tiles that the source has loaded for the current view. A source loads tiles only while a visible layer uses it.

See mln_render_session_query_source_features in the C API reference.

pub fn read_texture(&self) -> Result<NativeFuture<TextureReadbackResult>>

Reads the pixels of the last frame that the session rendered.

See mln_render_session_read_texture in the C API reference.

Errors

• Status::Unsupported when the session’s capabilities lack RenderSessionCapabilityFlag::READBACK.
• Status::InvalidState when the session hasn’t rendered a frame since it attached, resized, or changed its target.

pub fn reduce_memory_use(&self) -> Result<NativeFuture<()>>

Frees memory that the session’s renderer can rebuild, such as caches.

See mln_render_session_reduce_memory_use in the C API reference.

Errors

• Status::TargetLost when the session loses its target before the work runs.

pub fn release( self, ) -> Result<(NativeFuture<()>, RetiringRenderSession), ReleaseError<Self>>

Releases the session, detaching it first when it is attached.

Pending frame demands finish with RenderResult::TargetNotReady. 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 RenderDriverKind::CallerGraphicsThread detaches at your next RenderSessionHandle::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 RenderSessionHandle::abandon() does.

See mln_render_session_release in the C API reference.

Errors

• Status::InvalidState while you hold one of the session’s acquired frames. Release or discard them first.

pub fn release_target(&self) -> Result<NativeFuture<()>>

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 RenderResult::TargetNotReady. Once the release completes, you can destroy the old target. An Android or OpenHarmony window can go away sooner, as MapHandle::attach_android_surface() and MapHandle::attach_ohos_surface() say.

See mln_render_session_release_target in the C API reference.

Errors

• Status::Unsupported when the session renders offscreen or into Android hardware buffers, dmabufs, DXGI shared textures, or IOSurfaces that it allocates.
• Status::Unsupported when the target is a WebGL canvas.
• Status::TargetLost when the session loses its target before the release runs.

pub fn resize( &self, logical_size: LogicalSize, ) -> Result<NativeFuture<CommandCompletion>>

Resizes the session’s target and its map.

The session renders at the map’s scale factor. Release every acquired frame first.

See mln_render_session_resize in the C API reference.

Errors

• Status::Unsupported when the session renders into a borrowed ring. Give it new textures of the new size instead.
• Status::TargetLost when the session loses its target before the resize applies.

pub fn service_driver_work(&self) -> Result<()>

Runs the session’s ready graphics work on your graphics thread.

Use it with RenderDriverKind::CallerGraphicsThread, and call it from the same thread every time. Call it each time RenderSessionAttachOptions::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.

See mln_render_session_service_driver_work in the C API reference.

pub fn set_frame_pacer(&self, pacer: Option<&FramePacerHandle>) -> Result<()>

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.

See mln_render_session_set_frame_pacer in the C API reference.

Errors

• Status::TargetLost or Status::NativeError, as RenderSessionSnapshot::failure_status reports, when the session has failed.
• Status::InvalidState when you attached the session with a redraw wake, or detached, abandoned, released, or disposed it.

pub unsafe fn set_open_gl_borrowed_texture_target( &self, replacement: &OpenGlBorrowedTextureReplacement, ) -> Result<NativeFuture<()>>

Replaces the OpenGL textures that a borrowed ring renders into.

Use it to resize the ring, or to give the session textures again after RenderSessionHandle::release_target(). Release every acquired frame first. Once the replacement completes, the session no longer uses the old textures.

See mln_render_session_set_open_gl_borrowed_texture_target in the C API reference.

Safety

Native graphics objects must have the types, lifetimes, and synchronization required by the C operation.

pub unsafe fn set_open_gl_surface_target( &self, replacement: &OpenGlSurfaceReplacement, ) -> Result<NativeFuture<()>>

Replaces the OpenGL surface that the session presents to.

Use it to give the session a surface again after RenderSessionHandle::release_target(), to move it to another surface, or to resize it. Once the replacement completes, the session no longer uses the old surface.

See mln_render_session_set_open_gl_surface_target in the C API reference.

Safety

Native graphics objects must have the types, lifetimes, and synchronization required by the C operation.

pub unsafe fn set_vulkan_borrowed_texture_target( &self, replacement: &VulkanBorrowedTextureReplacement, ) -> Result<NativeFuture<()>>

Replaces the Vulkan images that a borrowed ring renders into.

Use it to resize the ring, or to give the session images again after RenderSessionHandle::release_target(). Release every acquired frame first. Once the replacement completes, the session no longer uses the old images.

See mln_render_session_set_vulkan_borrowed_texture_target in the C API reference.

Safety

Native graphics objects must have the types, lifetimes, and synchronization required by the C operation.

pub unsafe fn set_vulkan_surface_target( &self, replacement: &VulkanSurfaceReplacement, ) -> Result<NativeFuture<()>>

Replaces the Vulkan surface that the session presents to.

Use it to give the session a surface again after RenderSessionHandle::release_target(), to move it to another surface, or to resize it. Once the replacement completes, the session no longer uses the old surface.

See mln_render_session_set_vulkan_surface_target in the C API reference.

Errors

• Status::Unsupported when the new surface needs a different color format or pre-rotation support than the old one. Attach a new session instead.

Safety

Native graphics objects must have the types, lifetimes, and synchronization required by the C operation.

pub unsafe fn set_wayland_surface_target( &self, replacement: &WaylandSurfaceReplacement, ) -> Result<NativeFuture<()>>

Replaces the Wayland surface that the session presents to.

Use it to give the session a surface again after RenderSessionHandle::release_target(), to move it to another surface, or to resize it. Once the replacement completes, the session no longer uses the old surface.

See mln_render_session_set_wayland_surface_target in the C API reference.

Errors

• Status::Unsupported when, in a Vulkan build, the new surface needs a different color format than the old one. Attach a new session instead.
• Status::NativeError when the library can’t present to the new surface.

Safety

Native graphics objects must have the types, lifetimes, and synchronization required by the C operation.

impl RenderSessionHandle

pub fn discarding(&self) -> RenderSessionHandleDiscarding<'_>

Trait Implementations

impl Debug for RenderSessionHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.