Table of Contents

Class RenderSessionHandle

Namespace
Maplibre.NativeFfi
Assembly
Maplibre.NativeFfi.dll

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

public sealed class RenderSessionHandle : IDisposable, IAsyncDisposable
Inheritance
RenderSessionHandle
Implements
Inherited Members

Remarks

With a caller-graphics-thread driver, Ready, DetachAsync, BarrierAsync, and ResizeAsync progress only through ServiceDriverWork, so awaiting one on the graphics thread without servicing driver work never completes.

See mln_render_session in the C API reference.

Properties

Discarding

Submits each command without a completion. Native logs a failure as a warning, and the caller sees none.

public RenderSessionHandle.DiscardingCommands Discarding { get; }

Property Value

RenderSessionHandle.DiscardingCommands

Id

The native handle value. It stays readable after release.

public ulong Id { get; }

Property Value

ulong

IsClosed

Whether a release, dispose, or discard has ended the handle.

public bool IsClosed { get; }

Property Value

bool

Ready

Completes once the handle is ready, and faults with a MaplibreException when it fails to become ready.

public Task Ready { get; }

Property Value

Task

Methods

Abandon()

Stops the session right away, without running its pending graphics work.

public RenderAbandonResult Abandon()

Returns

RenderAbandonResult

Remarks

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.

AcquireFrame()

Takes the newest rendered frame from the session's texture ring, if one is ready.

public AcquiredFrameHandle? AcquireFrame()

Returns

AcquiredFrameHandle

Remarks

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.FrameAcquisition.
  • Status.TargetLost or Status.NativeError, as RenderSessionSnapshot.FailureStatus reports, when the session has failed.
  • Status.InvalidState when you detached, abandoned, released, or disposed the session.

BarrierAsync()

Ends the session's pending frame demands and waits for its earlier work.

public Task BarrierAsync()

Returns

Task

Remarks

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.

ClearDataAsync()

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

public Task ClearDataAsync()

Returns

Task

Remarks

See mln_render_session_clear_data in the C API reference.

Errors:

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

DemandFrame(FrameDemand)

Asks the session to render a frame.

public void DemandFrame(FrameDemand demand)

Parameters

demand FrameDemand

Remarks

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.DrainFrameResults() 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.FailureStatus 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.

DetachAsync()

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

public Task DetachAsync()

Returns

Task

Remarks

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.

Dispose()

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

public void Dispose()

Remarks

Use it from destructors and finalizers, and RenderSessionHandle.ReleaseAsync() 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.ServiceDriverWork() no longer accepts it.

See mln_render_session_dispose in the C API reference.

DrainFrameResults()

Takes the frame results that the session has queued.

public RenderFrameResult[] DrainFrameResults()

Returns

RenderFrameResult[]

Remarks

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.

DumpDebugLogsAsync()

Logs debugging information about the session's renderer.

public Task DumpDebugLogsAsync()

Returns

Task

Remarks

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.

GetCapabilities()

Reads what the session supports.

public RenderSessionCapabilities GetCapabilities()

Returns

RenderSessionCapabilities

Remarks

See mln_render_session_get_capabilities in the C API reference.

GetClusterChildrenAsync(string, uint)

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

public Task<string> GetClusterChildrenAsync(string sourceId, uint clusterId)

Parameters

sourceId string
clusterId uint

Returns

Task<string>

Remarks

clusterId 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 sourceId, or the source has no cluster clusterId.
  • Status.InvalidArgument when the source isn't a GeoJSON source with clustering turned on.

GetClusterExpansionZoomAsync(string, uint)

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

public Task<uint> GetClusterExpansionZoomAsync(string sourceId, uint clusterId)

Parameters

sourceId string
clusterId uint

Returns

Task<uint>

Remarks

clusterId 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.GetClusterChildrenAsync() 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 sourceId, or the source has no cluster clusterId.
  • Status.InvalidArgument when the source isn't a GeoJSON source with clustering turned on.

GetClusterLeavesAsync(string, uint, uint, uint)

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

public Task<string> GetClusterLeavesAsync(string sourceId, uint clusterId, uint limit, uint offset)

Parameters

sourceId string
clusterId uint
limit uint
offset uint

Returns

Task<string>

Remarks

clusterId 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.GetClusterChildrenAsync() 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 sourceId, or the source has no cluster clusterId.
  • Status.InvalidArgument when the source isn't a GeoJSON source with clustering turned on.

GetFailure()

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

public string GetFailure()

Returns

string

Remarks

RenderSessionSnapshot.FailureStatus 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.

GetSnapshot()

Reads the session's current state.

public RenderSessionSnapshot GetSnapshot()

Returns

RenderSessionSnapshot

Remarks

See mln_render_session_get_snapshot in the C API reference.

QueryRenderedFeaturesAsync(RenderedQueryGeometry, RenderedFeatureQueryOptions?)

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

public Task<RenderedFeature[]> QueryRenderedFeaturesAsync(RenderedQueryGeometry geometry, RenderedFeatureQueryOptions? options = null)

Parameters

geometry RenderedQueryGeometry
options RenderedFeatureQueryOptions

Returns

Task<RenderedFeature[]>

Remarks

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.

QuerySourceFeaturesAsync(string, SourceFeatureQueryOptions?)

Finds the features of the source named sourceId.

public Task<SourceFeature[]> QuerySourceFeaturesAsync(string sourceId, SourceFeatureQueryOptions? options = null)

Parameters

sourceId string
options SourceFeatureQueryOptions

Returns

Task<SourceFeature[]>

Remarks

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.

ReadTextureAsync()

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

public Task<TextureReadbackResult> ReadTextureAsync()

Returns

Task<TextureReadbackResult>

Remarks

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.

ReduceMemoryUseAsync()

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

public Task ReduceMemoryUseAsync()

Returns

Task

Remarks

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.

ReleaseAsync()

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

public Task ReleaseAsync()

Returns

Task

Remarks

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.ServiceDriverWork(), 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.

ReleaseTargetAsync()

Lets go of the session's surface or textures, and keeps the rest of the session.

public Task ReleaseTargetAsync()

Returns

Task

Remarks

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.

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.

ResizeAsync(LogicalSize)

Resizes the session's target and its map.

public Task<CommandCompletion> ResizeAsync(LogicalSize logicalSize)

Parameters

logicalSize LogicalSize

Returns

Task<CommandCompletion>

Remarks

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.

ServiceDriverWork()

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

public void ServiceDriverWork()

Remarks

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

With a caller-graphics-thread driver, Ready, DetachAsync, BarrierAsync, and ResizeAsync progress only through ServiceDriverWork, so awaiting one on the graphics thread without servicing driver work never completes.

See mln_render_session_service_driver_work in the C API reference.

SetAndroidSurfaceTargetAsync(AndroidSurfaceReplacement)

Replaces the Android window that the session presents to.

public Task SetAndroidSurfaceTargetAsync(AndroidSurfaceReplacement replacement)

Parameters

replacement AndroidSurfaceReplacement

Returns

Task

Remarks

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

See mln_render_session_set_android_surface_target in the C API reference.

Errors:

  • Status.InvalidArgument when surface has no window, such as after the platform destroyed it.
  • Status.Unsupported when, in a Vulkan build, the new window needs a different color format or pre-rotation support than the old one. Attach a new session instead.
  • Status.NativeError when the library can't create the window's surface.

SetFramePacer(FramePacerHandle?)

Sets the frame pacer that demands the session's frames.

public void SetFramePacer(FramePacerHandle? pacer = null)

Parameters

pacer FramePacerHandle

Remarks

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.FailureStatus reports, when the session has failed.
  • Status.InvalidState when you attached the session with a redraw wake, or detached, abandoned, released, or disposed it.

SetMetalBorrowedTextureTargetAsync(MetalBorrowedTextureReplacement)

Replaces the Metal textures that a borrowed ring renders into.

public Task SetMetalBorrowedTextureTargetAsync(MetalBorrowedTextureReplacement replacement)

Parameters

replacement MetalBorrowedTextureReplacement

Returns

Task

Remarks

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

See mln_render_session_set_metal_borrowed_texture_target in the C API reference.

Errors:

  • Status.Unsupported when the new textures have a different pixel format than the old ones. Attach a new session to change it.

SetMetalSurfaceTargetAsync(MetalSurfaceReplacement)

Replaces the Metal layer that the session renders to.

public Task SetMetalSurfaceTargetAsync(MetalSurfaceReplacement replacement)

Parameters

replacement MetalSurfaceReplacement

Returns

Task

Remarks

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

See mln_render_session_set_metal_surface_target in the C API reference.

SetOpenGlBorrowedTextureTargetAsync(OpenGlBorrowedTextureReplacement)

Replaces the OpenGL textures that a borrowed ring renders into.

public Task SetOpenGlBorrowedTextureTargetAsync(OpenGlBorrowedTextureReplacement replacement)

Parameters

replacement OpenGlBorrowedTextureReplacement

Returns

Task

Remarks

Use it to resize the ring, or to give the session textures again after RenderSessionHandle.ReleaseTargetAsync(). 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.

SetOpenGlSurfaceTargetAsync(OpenGlSurfaceReplacement)

Replaces the OpenGL surface that the session presents to.

public Task SetOpenGlSurfaceTargetAsync(OpenGlSurfaceReplacement replacement)

Parameters

replacement OpenGlSurfaceReplacement

Returns

Task

Remarks

Use it to give the session a surface again after RenderSessionHandle.ReleaseTargetAsync(), 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.

SetVulkanBorrowedTextureTargetAsync(VulkanBorrowedTextureReplacement)

Replaces the Vulkan images that a borrowed ring renders into.

public Task SetVulkanBorrowedTextureTargetAsync(VulkanBorrowedTextureReplacement replacement)

Parameters

replacement VulkanBorrowedTextureReplacement

Returns

Task

Remarks

Use it to resize the ring, or to give the session images again after RenderSessionHandle.ReleaseTargetAsync(). 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.

SetVulkanSurfaceTargetAsync(VulkanSurfaceReplacement)

Replaces the Vulkan surface that the session presents to.

public Task SetVulkanSurfaceTargetAsync(VulkanSurfaceReplacement replacement)

Parameters

replacement VulkanSurfaceReplacement

Returns

Task

Remarks

Use it to give the session a surface again after RenderSessionHandle.ReleaseTargetAsync(), 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.

SetWaylandSurfaceTargetAsync(WaylandSurfaceReplacement)

Replaces the Wayland surface that the session presents to.

public Task SetWaylandSurfaceTargetAsync(WaylandSurfaceReplacement replacement)

Parameters

replacement WaylandSurfaceReplacement

Returns

Task

Remarks

Use it to give the session a surface again after RenderSessionHandle.ReleaseTargetAsync(), 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.

SetWin32WindowTargetAsync(Win32WindowReplacement)

Replaces the Win32 window that the session presents to.

public Task SetWin32WindowTargetAsync(Win32WindowReplacement replacement)

Parameters

replacement Win32WindowReplacement

Returns

Task

Remarks

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

See mln_render_session_set_win32_window_target in the C API reference.

Errors:

  • Status.InvalidArgument when window isn't a window, or, in an OpenGL build, already has another pixel format.
  • Status.InvalidState when window is minimized or has no client area.
  • Status.InvalidState when window was minimized before the replacement ran.
  • Status.Unsupported when, in a Vulkan build, the new window 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 window.

ToString()

Names the handle's type, its Id, and whether it is closed.

public override string ToString()

Returns

string