Table of Contents

Class AcquiredFrameHandle

Namespace
Maplibre.NativeFfi
Assembly
Maplibre.NativeFfi.dll

A rendered frame that the caller holds to read or show.

public sealed class AcquiredFrameHandle
Inheritance
AcquiredFrameHandle
Inherited Members

Remarks

See mln_acquired_frame in the C API reference.

Properties

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

Methods

Discard()

Gives up an acquired frame without saying when your GPU stops reading it.

public void Discard()

Remarks

Because your GPU may still read the frame's texture, the session never renders into that texture again.

See mln_acquired_frame_discard in the C API reference.

GetResult()

Reads the frame result of an acquired frame.

public RenderFrameResult GetResult()

Returns

RenderFrameResult

Remarks

It succeeds until you release or discard the frame, whatever the session's state.

See mln_acquired_frame_get_result in the C API reference.

Release(GpuSync)

Gives an acquired frame back to the session once you're done reading it.

public void Release(GpuSync consumerCompletion)

Parameters

consumerCompletion GpuSync

Remarks

consumerCompletion says when your GPU work that reads the texture finishes. Pass GpuSyncKind.CpuComplete when that work has already finished. The session waits for that point before it renders into the texture again. If that wait fails, such as for an OpenGL fence outside the session's share group, the session fails.

See mln_acquired_frame_release in the C API reference.

Errors:

  • Status.Unsupported when RenderSessionCapabilities.ConsumerSyncKinds lacks the kind of consumerCompletion.

ToString()

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

public override string ToString()

Returns

string

WithAndroidHardwareBuffer(Action<AndroidHardwareBufferFrameView>)

Gets the Android hardware buffer of an acquired frame.

public void WithAndroidHardwareBuffer(Action<AndroidHardwareBufferFrameView> callback)

Parameters

callback Action<AndroidHardwareBufferFrameView>

Remarks

Wait for AcquiredFrameHandle.WithProducerSync() before you read the buffer. Once you release or discard the frame, the session may render into the buffer again. A reference that you take with AHardwareBuffer_acquire keeps the buffer's memory, but not its contents.

See mln_acquired_frame_get_android_hardware_buffer in the C API reference.

Errors:

  • Status.TargetLost when the session failed, or you detached, abandoned, or disposed it.

WithDmaBuf(Action<DmaBufFrameView>)

Gets the dmabuf of an acquired frame.

public void WithDmaBuf(Action<DmaBufFrameView> callback)

Parameters

callback Action<DmaBufFrameView>

Remarks

Wait for AcquiredFrameHandle.WithProducerSync() before you read the buffer. Once you release or discard the frame, the session may render into the buffer again. You can map a buffer with DRM_FORMAT_MOD_LINEAR, which has one plane, with mmap, and bracket your reads with DMA_BUF_IOCTL_SYNC.

The session owns the planes' file descriptors, so don't close them. To keep the buffer after you release the frame, duplicate each file descriptor with dup. A duplicate keeps the buffer's memory, but not its contents.

See mln_acquired_frame_get_dma_buf in the C API reference.

Errors:

  • Status.TargetLost when the session failed, or you detached, abandoned, or disposed it.

WithDxgiSharedTexture(Action<DxgiSharedTextureFrameView>)

Gets the DXGI shared texture of an acquired frame.

public void WithDxgiSharedTexture(Action<DxgiSharedTextureFrameView> callback)

Parameters

callback Action<DxgiSharedTextureFrameView>

Remarks

Wait for AcquiredFrameHandle.WithProducerSync() before you read the texture. Once you release or discard the frame, the session may render into the texture again. Open the handle with ID3D11Device1::OpenSharedResource1 or ID3D12Device::OpenSharedHandle. A texture that you open keeps its memory, but not its contents.

The session owns the handle, so don't close it. To keep the handle after you release the frame, duplicate it with DuplicateHandle.

See mln_acquired_frame_get_dxgi_shared_texture in the C API reference.

Errors:

  • Status.TargetLost when the session failed, or you detached, abandoned, or disposed it.

WithIoSurface(Action<IoSurfaceFrameView>)

Gets the IOSurface of an acquired frame.

public void WithIoSurface(Action<IoSurfaceFrameView> callback)

Parameters

callback Action<IoSurfaceFrameView>

Remarks

Wait for AcquiredFrameHandle.WithProducerSync() before you read the surface. Once you release or discard the frame, the session may render into the surface again. For an API that takes a CVPixelBuffer, wrap the surface with CVPixelBufferCreateWithIOSurface. A reference that you take with CFRetain, or a pixel buffer that wraps the surface, keeps the surface's memory, but not its contents.

See mln_acquired_frame_get_io_surface in the C API reference.

Errors:

  • Status.TargetLost when the session failed, or you detached, abandoned, or disposed it.

WithMetalTexture(Action<MetalTextureFrameView>)

Gets the Metal texture of an acquired frame.

public void WithMetalTexture(Action<MetalTextureFrameView> callback)

Parameters

callback Action<MetalTextureFrameView>

Remarks

See mln_acquired_frame_get_metal_texture in the C API reference.

Errors:

  • Status.TargetLost when the session failed, or you detached, abandoned, or disposed it.

WithOpenGlTexture(Action<OpenGlTextureFrameView>)

Gets the OpenGL texture of an acquired frame.

public void WithOpenGlTexture(Action<OpenGlTextureFrameView> callback)

Parameters

callback Action<OpenGlTextureFrameView>

Remarks

See mln_acquired_frame_get_open_gl_texture in the C API reference.

Errors:

  • Status.TargetLost when the session failed, or you detached, abandoned, or disposed it.

WithProducerSync(Action<GpuSyncView>)

Reads what to wait for before you read an acquired frame's texture.

public void WithProducerSync(Action<GpuSyncView> callback)

Parameters

callback Action<GpuSyncView>

Remarks

See mln_acquired_frame_get_producer_sync in the C API reference.

Errors:

  • Status.TargetLost when the session failed, or you detached, abandoned, or disposed it.

WithVulkanTexture(Action<VulkanTextureFrameView>)

Gets the Vulkan image of an acquired frame.

public void WithVulkanTexture(Action<VulkanTextureFrameView> callback)

Parameters

callback Action<VulkanTextureFrameView>

Remarks

See mln_acquired_frame_get_vulkan_texture in the C API reference.

Errors:

  • Status.TargetLost when the session failed, or you detached, abandoned, or disposed it.