Struct RenderSessionHandle 

pub struct RenderSessionHandle { /* private fields */ }

Render session handle bound to the thread that attached it.

The session holds no Rust-level retention of its map. Native keeps the map alive instead: destroying a map fails while a session is attached to it.

Implementations

impl RenderSessionHandle

pub fn set_feature_state( &self, selector: &FeatureStateSelector, state: &[u8], ) -> Result<()>

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

pub fn get_feature_state( &self, selector: &FeatureStateSelector, ) -> Result<Vec<u8>>

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

pub fn remove_feature_state( &self, selector: &FeatureStateSelector, ) -> Result<()>

Removes per-feature state selected for this session.

pub fn query_rendered_features( &self, geometry: &RenderedQueryGeometry, options: Option<&RenderedFeatureQueryOptions>, ) -> Result<Vec<QueriedFeature>>

Copies rendered features from the latest render session state.

pub fn query_source_features( &self, source_id: &str, options: Option<&SourceFeatureQueryOptions>, ) -> Result<Vec<QueriedFeature>>

Copies source features from the latest render session state.

pub fn query_feature_extension( &self, source_id: &str, feature: &[u8], extension: &str, extension_field: &str, arguments: Option<&[u8]>, ) -> Result<Vec<u8>>

Queries a feature extension as UTF-8 JSON or GeoJSON bytes.

impl RenderSessionHandle

pub fn close(self) -> Result<(), HandleOperationError<Self>>

Explicitly destroys the render session.

Native destruction errors are returned. When destruction fails, the underlying native handle remains live so a later close can retry.

pub fn resize(&self, width: u32, height: u32, scale_factor: f64) -> Result<()>

Resizes this attached render session.

Surface and owned-texture sessions resize in place, keeping the renderer and its state. A scale factor change starts a new renderer with renderer-held state empty. Borrowed texture targets report an unsupported-feature error; hand over a new texture with the backend’s set_*_borrowed_texture_target method instead.

pub fn set_metal_surface_target( &self, descriptor: &MetalSurfaceDescriptor, ) -> Result<()>

Presents this attached surface session through a new surface, keeping this session’s renderer and its state.

The descriptor’s extent applies as a resize does. A context.device that is neither null nor this session’s device reports an invalid-argument error and leaves the current surface in place.

pub fn set_vulkan_surface_target( &self, descriptor: &VulkanSurfaceDescriptor, ) -> Result<()>

Presents this attached surface session through a new surface.

See RenderSessionHandle::set_metal_surface_target for what replacing a surface preserves. The outgoing VkSurfaceKHR must still be valid: this session holds a swapchain built from it, and Vulkan destroys every swapchain before its surface.

pub fn set_webgpu_surface_target( &self, descriptor: &WebGpuSurfaceDescriptor, ) -> Result<()>

Presents this attached surface session through a new WebGPU surface.

See RenderSessionHandle::set_metal_surface_target for what replacing a surface preserves. The replacement names the same device and format as the session attached with.

pub fn set_opengl_surface_target( &self, descriptor: &OpenGLSurfaceDescriptor, ) -> Result<()>

Presents this attached surface session through a new surface.

See RenderSessionHandle::set_metal_surface_target for what replacing a surface preserves. The new surface is made current on the next render, so a host may hand over a replacement for one it has already destroyed. A surface accepted here can still prove unusable, which the next render_update reports rather than this call.

pub fn set_metal_borrowed_texture_target( &self, descriptor: &MetalBorrowedTextureDescriptor, ) -> Result<()>

Renders this attached texture session into a new caller-owned texture, keeping this session’s renderer. A scale factor change starts a new renderer, as RenderSessionHandle::resize does.

The replacement must belong to the device this session attached with and carry the pixel format it attached with; otherwise this reports an error and leaves the current texture in place. The caller owns the replacement and keeps it valid until the next replacement, detach, or close. The outgoing texture is neither retained nor read here.

pub fn set_vulkan_borrowed_texture_target( &self, descriptor: &VulkanBorrowedTextureDescriptor, ) -> Result<()>

Renders this attached texture session into a new caller-owned image.

See RenderSessionHandle::set_metal_borrowed_texture_target for what replacing a target preserves. The replacement carries the format and both layouts this session attached with, since its render pass was built around them.

pub fn set_webgpu_borrowed_texture_target( &self, descriptor: &WebGpuBorrowedTextureDescriptor, ) -> Result<()>

Renders this attached texture session into a new caller-owned texture.

See RenderSessionHandle::set_metal_borrowed_texture_target for what replacing a target preserves. The replacement carries the format this session attached with, and belongs to the device it attached with.

pub fn set_opengl_borrowed_texture_target( &self, descriptor: &OpenGLBorrowedTextureDescriptor, ) -> Result<()>

Renders this attached texture session into a new caller-owned texture.

See RenderSessionHandle::set_metal_borrowed_texture_target for what replacing a target preserves. The replacement belongs to the context this session attached with, or one in its share group, and the host context must be current on this thread.

pub fn render_update(&self) -> Result<RenderUpdate>

Processes the latest map render update for this render target.

The map retains its latest update, so repeated calls re-render it and report RenderResult::Rendered again. Every other result names the wake to wait for: RenderResult::NoUpdate and RenderResult::SizePending resolve on a render-update-available event, and RenderResult::TargetNotReady resolves when the host changes the render target.

The returned RenderUpdate::needs_repaint reports whether the map asked for another frame while rendering this one, so a frame loop can re-arm without draining events first.

pub fn detach( self, ) -> Result<DetachedRenderSessionHandle, HandleOperationError<Self>>

Detaches backend-bound render resources from the map, consuming this handle and returning a close-only handle.

A detached session no longer reaches its map, so the map is free to close and the detached session stays destroyable afterwards.

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

Asks the session renderer to release cached resources where possible.

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

Clears renderer data for the session.

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

Dumps renderer debug logs through MapLibre Native logging.

pub fn texture_image_info(&self) -> Result<TextureImageInfo>

Returns CPU readback metadata for the most recently rendered texture frame.

pub fn read_premultiplied_rgba8_into( &self, data: &mut [u8], ) -> Result<TextureImageInfo>

Reads the most recently rendered texture frame as premultiplied RGBA8.

pub fn acquire_metal_owned_texture_frame( &self, ) -> Result<MetalOwnedTextureFrameHandle>

Acquires a borrowed Metal frame from a session-owned texture target.

pub fn acquire_vulkan_owned_texture_frame( &self, ) -> Result<VulkanOwnedTextureFrameHandle>

Acquires a borrowed Vulkan frame from a session-owned texture target.

pub fn acquire_webgpu_owned_texture_frame( &self, ) -> Result<WebGpuOwnedTextureFrameHandle>

Acquires a borrowed WebGPU frame from a session-owned texture target.

pub fn acquire_opengl_owned_texture_frame( &self, ) -> Result<OpenGLOwnedTextureFrameHandle>

Acquires a borrowed OpenGL frame from a session-owned texture target.

Trait Implementations

impl Debug for RenderSessionHandle

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

Formats the value using the given formatter.