Class AcquiredFrameHandle

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

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.

Reads the frame result of an acquired frame.

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.

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

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.

Gets the Android hardware buffer of an acquired frame.

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.

Gets the dmabuf of an acquired frame.

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.

Gets the DXGI shared texture of an acquired frame.

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.

Gets the IOSurface of an acquired frame.

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.

Gets the Metal texture of an acquired frame.

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.

Gets the OpenGL texture of an acquired frame.

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.

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

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.

Gets the Vulkan image of an acquired frame.

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.

Gets the WebGPU texture of an acquired frame.

See mln_acquired_frame_get_web_gpu_texture in the C API reference.

Errors:

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