Calls release(), for await using.
Hosts without Symbol.asyncDispose, such as ArkTS, leave it undefined.
Calls dispose(), for using.
Hosts without Symbol.dispose, such as ArkTS, leave it undefined.
ReadonlyidThe native handle value. It stays readable after release.
ReadonlyreadySettles once the session is ready, and rejects with a MaplibreError when
it fails to become ready. Asynchronous calls on the session before then
wait for it. A rejection that nothing awaits isn't reported as unhandled.
The commands of this owner that discard their outcomes.
Whether a release, dispose, or discard has ended the handle.
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.
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.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.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.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.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.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.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.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.serviceDriverWork() no longer accepts it.
See mln_render_session_dispose in the
C API reference.
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.
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.Reads what the session supports.
See mln_render_session_get_capabilities in the
C API reference.
Reads the children of a cluster in a clustered GeoJSON source.
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.Reads the zoom level at which a cluster of a clustered GeoJSON source splits.
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.getClusterChildren() 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.Reads the points in a cluster of a clustered GeoJSON source.
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.getClusterChildren() 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.Reads the message of the error that made the session fail.
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.
Reads the session's current state.
See mln_render_session_get_snapshot in the
C API reference.
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.
Optionaloptions: RenderedFeatureQueryOptionsFinds the features of the source named sourceId.
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.
Optionaloptions: SourceFeatureQueryOptionsReads 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.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.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.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.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.attachAndroidSurface() and
MapHandle.attachOhosSurface() 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.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.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.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.
See mln_render_session_service_driver_work in the
C API reference.
Replaces the Android window that the session presents to.
Use it to give the session a window again after
RenderSessionHandle.releaseTarget(), 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.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.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.Optionalpacer: FramePacerHandleReplaces the Metal textures that a borrowed ring renders into.
Use it to resize the ring, or to give the session textures again after
RenderSessionHandle.releaseTarget(). 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.Replaces the Metal layer that the session renders to.
Use it to give the session a layer again after
RenderSessionHandle.releaseTarget(), 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.
Replaces the OpenHarmony window that the session presents to.
Use it to give the session a window again after
RenderSessionHandle.releaseTarget(), 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_ohos_surface_target in the
C API reference.
Errors:
Status.invalidArgument when no surface in this process has
OhosSurfaceReplacement.surfaceId, 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.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.releaseTarget(). 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.
Replaces the OpenGL surface that the session presents to.
Use it to give the session a surface again after
RenderSessionHandle.releaseTarget(), 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.
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.releaseTarget(). 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.
Replaces the Vulkan surface that the session presents to.
Use it to give the session a surface again after
RenderSessionHandle.releaseTarget(), 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.Replaces the Wayland surface that the session presents to.
Use it to give the session a surface again after
RenderSessionHandle.releaseTarget(), 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.Replaces the WebGPU textures that a borrowed ring renders into.
Use it to resize the ring, or to give the session textures again after
RenderSessionHandle.releaseTarget(). Release every acquired frame first.
Once the replacement completes, the session no longer uses the old
textures.
See mln_render_session_set_web_gpu_borrowed_texture_target in the
C API reference.
Replaces the WebGPU surface that the session presents to.
Use it to give the session a surface again after
RenderSessionHandle.releaseTarget(), 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_web_gpu_surface_target in the
C API reference.
Replaces the Win32 window that the session presents to.
Use it to give the session a window again after
RenderSessionHandle.releaseTarget(), 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.Names the owner's type, its handle ID, and whether it is closed.
A render session draws a map into a surface or a texture.
See
mln_render_sessionin the C API reference.