Data Structures
struct	mln_dma_buf_format
struct	mln_dma_buf_ring_descriptor
struct	mln_dma_buf_plane
struct	mln_dma_buf_frame

Typedefs
typedef struct mln_dma_buf_format	mln_dma_buf_format
typedef struct mln_dma_buf_ring_descriptor	mln_dma_buf_ring_descriptor
typedef struct mln_dma_buf_plane	mln_dma_buf_plane
typedef struct mln_dma_buf_frame	mln_dma_buf_frame

Functions
mln_status	mln_map_attach_dma_buf_ring (mln_map map, const mln_dma_buf_ring_descriptor descriptor, mln_vulkan_device device, const mln_render_session_attach_options options, mln_render_session out_session, const mln_completion completion, mln_diagnostic *out_diagnostic)
mln_status	mln_acquired_frame_get_dma_buf (mln_acquired_frame frame, mln_dma_buf_frame out_frame, mln_diagnostic out_diagnostic)

Detailed Description

Render into dmabufs on Linux and FreeBSD.

Typedef Documentation

◆ mln_dma_buf_format

typedef struct mln_dma_buf_format mln_dma_buf_format

A DRM format and modifier that you can import.

◆ mln_dma_buf_frame

typedef struct mln_dma_buf_frame mln_dma_buf_frame

The dmabuf of an acquired frame.

◆ mln_dma_buf_plane

typedef struct mln_dma_buf_plane mln_dma_buf_plane

Where one plane of a dmabuf keeps its data.

◆ mln_dma_buf_ring_descriptor

typedef struct mln_dma_buf_ring_descriptor mln_dma_buf_ring_descriptor

A ring of dmabufs that the library allocates, for mln_map_attach_dma_buf_ring().

Each buffer has the map's size in pixels and a format and modifier from formats. The library renders only DRM_FORMAT_ABGR8888 and DRM_FORMAT_ARGB8888. A modifier can give a buffer more planes than its format has, such as a plane of compression metadata, and the library takes any such modifier that its GPU can render into and share.

Function Documentation

◆ mln_acquired_frame_get_dma_buf()

mln_status mln_acquired_frame_get_dma_buf	(	mln_acquired_frame	frame,
		mln_dma_buf_frame *	out_frame,
		mln_diagnostic *	out_diagnostic )

Gets the dmabuf of an acquired frame.

Wait for mln_acquired_frame_get_producer_sync() 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.

Returns:

MLN_STATUS_TARGET_LOST when the session failed, or you detached, abandoned, or disposed it.

Lifetimes: The planes in out_frame, and their file descriptors, stay valid until you release or discard the frame, or the session is abandoned or disposed. A view from mln_acquired_frame_view_begin() keeps them valid until mln_acquired_frame_view_end().

◆ mln_map_attach_dma_buf_ring()

mln_status mln_map_attach_dma_buf_ring	(	mln_map	map,
		const mln_dma_buf_ring_descriptor *	descriptor,
		mln_vulkan_device	device,
		const mln_render_session_attach_options *	options,
		mln_render_session *	out_session,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Creates a session that renders the map into a ring of dmabufs that the library allocates.

Acquire each frame with mln_render_session_acquire_frame(), and get its buffer with mln_acquired_frame_get_dma_buf(). mln_render_session_resize() gives the ring new buffers of the new size.

A Vulkan build renders with device, or, when device is null, with a device that the library creates. An OpenGL build uses an EGL context of its own, and device must be null. Attach with MLN_RENDER_DRIVER_CORE_WORKER.

For a reader that waits on no sync file, such as a Wayland compositor without explicit synchronization, attach without MLN_GPU_SYNC_KIND_FLAG_SYNC_FD in mln_render_session_attach_options.producer_sync_kinds, so that each frame finishes before you acquire it. Keep each frame acquired until its reader is done with the buffer. Give the ring 3 buffers, so the session can render while you hold two frames.