render_target.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_queue_lock
struct	mln_render_session_attach_options
struct	mln_render_session_capabilities
struct	mln_gpu_sync
struct	mln_metal_context_descriptor
struct	mln_vulkan_context_descriptor
struct	mln_webgpu_context_descriptor
struct	mln_wgl_context_descriptor
struct	mln_egl_context_descriptor
struct	mln_webgl_context_descriptor
union	mln_opengl_context_descriptor_data
struct	mln_opengl_context_descriptor

Macros
#define	MLN_VULKAN_NON_DISPATCHABLE_HANDLE_NULL   UINT64_C(0)
#define	MLN_TEXTURE_RING_MAX_DEPTH   8

Typedefs
typedef uint64_t	mln_vulkan_non_dispatchable_handle
typedef enum mln_render_driver_kind	mln_render_driver_kind
typedef enum mln_render_session_capability_flag	mln_render_session_capability_flag
typedef void(*)	mln_queue_lock_callback(void *user_data)
typedef struct mln_queue_lock	mln_queue_lock
typedef struct mln_render_session_attach_options	mln_render_session_attach_options
typedef struct mln_render_session_capabilities	mln_render_session_capabilities
typedef enum mln_gpu_sync_kind	mln_gpu_sync_kind
typedef struct mln_gpu_sync	mln_gpu_sync
typedef struct mln_metal_context_descriptor	mln_metal_context_descriptor
typedef struct mln_vulkan_context_descriptor	mln_vulkan_context_descriptor
typedef struct mln_webgpu_context_descriptor	mln_webgpu_context_descriptor
typedef enum mln_opengl_context_provider_flag	mln_opengl_context_provider_flag
typedef enum mln_opengl_context_platform	mln_opengl_context_platform
typedef enum mln_opengl_context_ownership	mln_opengl_context_ownership
typedef enum mln_opengl_client_api	mln_opengl_client_api
typedef struct mln_wgl_context_descriptor	mln_wgl_context_descriptor
typedef struct mln_egl_context_descriptor	mln_egl_context_descriptor
typedef enum mln_webgl_context_kind	mln_webgl_context_kind
typedef struct mln_webgl_context_descriptor	mln_webgl_context_descriptor
typedef union mln_opengl_context_descriptor_data	mln_opengl_context_descriptor_data
typedef struct mln_opengl_context_descriptor	mln_opengl_context_descriptor

Enumerations
enum	mln_render_driver_kind : uint32_t { MLN_RENDER_DRIVER_CORE_WORKER = 1U , MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD = 2U }
enum	mln_render_session_capability_flag : uint32_t
enum	mln_gpu_sync_kind : uint32_t { MLN_GPU_SYNC_CPU_COMPLETE = 0U , MLN_GPU_SYNC_OPENGL_FENCE = 3U }
enum	mln_opengl_context_provider_flag : uint32_t { }
enum	mln_opengl_context_platform : uint32_t { MLN_OPENGL_CONTEXT_PLATFORM_UNSPECIFIED = 0u , MLN_OPENGL_CONTEXT_PLATFORM_WGL = 1u , MLN_OPENGL_CONTEXT_PLATFORM_EGL = 2u , MLN_OPENGL_CONTEXT_PLATFORM_WEBGL = 3u }
enum	mln_opengl_context_ownership : uint32_t { MLN_OPENGL_CONTEXT_OWNERSHIP_SHARED = 0u , MLN_OPENGL_CONTEXT_OWNERSHIP_DEDICATED = 1u }
enum	mln_opengl_client_api : uint32_t { MLN_OPENGL_CLIENT_API_UNSPECIFIED = 0u , MLN_OPENGL_CLIENT_API_GL = 1u , MLN_OPENGL_CLIENT_API_GLES = 2u }
enum	mln_webgl_context_kind : uint32_t { MLN_WEBGL_CONTEXT_EXISTING = 0U , MLN_WEBGL_CONTEXT_TRANSFERRED_CANVAS = 1U }

Functions
mln_gpu_sync	mln_gpu_sync_default (void)
mln_render_session_attach_options	mln_render_session_attach_options_default (void)
mln_status	mln_logical_extent_physical_size (mln_logical_extent extent, uint32_t *out_width, uint32_t *out_height, mln_diagnostic *out_diagnostic)
uint32_t	mln_opengl_supported_context_provider_mask (void)

Detailed Description

Shared public C API declarations for render target descriptors.

Macro Definition Documentation

MLN_TEXTURE_RING_MAX_DEPTH

#define MLN_TEXTURE_RING_MAX_DEPTH   8

The most slots a texture ring holds, owned or borrowed.

MLN_VULKAN_NON_DISPATCHABLE_HANDLE_NULL

#define MLN_VULKAN_NON_DISPATCHABLE_HANDLE_NULL   UINT64_C(0)

Null Vulkan non-dispatchable handle.

Typedef Documentation

mln_egl_context_descriptor

typedef struct mln_egl_context_descriptor mln_egl_context_descriptor

EGL context fields shared by OpenGL render targets.

mln_gpu_sync

typedef struct mln_gpu_sync mln_gpu_sync

Backend synchronization copied by frame access and release calls.

OpenGL ownership and lifetimes follow MLN_GPU_SYNC_OPENGL_FENCE.

mln_gpu_sync_kind

typedef enum mln_gpu_sync_kind mln_gpu_sync_kind

Synchronization payload kind for acquired texture frames.

mln_metal_context_descriptor

typedef struct mln_metal_context_descriptor mln_metal_context_descriptor

Metal backend context fields shared by Metal render targets.

mln_opengl_client_api

typedef enum mln_opengl_client_api mln_opengl_client_api

OpenGL client API a dedicated EGL session creates its context for.

mln_opengl_context_descriptor

typedef struct mln_opengl_context_descriptor mln_opengl_context_descriptor

OpenGL backend context fields shared by OpenGL render targets.

mln_opengl_context_descriptor_data

typedef union mln_opengl_context_descriptor_data mln_opengl_context_descriptor_data

Backend-specific OpenGL context data.

mln_opengl_context_ownership

typedef enum mln_opengl_context_ownership mln_opengl_context_ownership

How a session's OpenGL context relates to its driver thread and host graphics state.

A shared session leaves the thread as it found it: every render makes the session context current and restores whatever was current before. The session context joins the host share group named by the descriptor, so a host may hand the session a texture and sample it from its own context.

A dedicated session joins no share group and leaves its context current after a render instead of restoring what was current before. A render that finds another context current makes its own current again, so several dedicated sessions can share one thread, and the host can use its own context between renders. Teardown releases the session context from the thread and restores nothing.

mln_opengl_context_platform

typedef enum mln_opengl_context_platform mln_opengl_context_platform

OpenGL platform context provider used by a context descriptor.

mln_opengl_context_provider_flag

typedef enum mln_opengl_context_provider_flag mln_opengl_context_provider_flag

OpenGL context providers supported by this build.

mln_queue_lock

typedef struct mln_queue_lock mln_queue_lock

Host lock on the graphics queue that a session shares with its host, copied by a successful attach.

Vulkan requires the host to synchronize every call that uses a queue. A Vulkan session submits to the context's graphics_queue. A host that also uses that queue must pass a lock here and take the same lock around its own queue calls. The callbacks may run on the graphics thread or the thread that abandons the session. Each queue submission or presentation holds the lock only for that call, never across a wait.

Both callbacks are null to disable the lock, or both are set. A disabled lock must not carry release_user_data. A session without a lock assumes that the host leaves the queue alone while the session is attached.

The callbacks must not call the C API; each status-returning function returns MLN_STATUS_INVALID_STATE when a callback calls it. The host must not hold the lock while calling the C API or waiting on a thread that does. Sessions sharing a queue must use the same host mutex.

Native code calls release_user_data once, after the session can no longer invoke the callbacks.

mln_queue_lock_callback

typedef void(*) mln_queue_lock_callback(void *user_data)

Takes or returns the host's lock on the queue that a session shares with it. Native code relies on the lock being held or released when the call returns.

mln_render_driver_kind

typedef enum mln_render_driver_kind mln_render_driver_kind

Execution placement for one render session.

mln_render_session_attach_options

typedef struct mln_render_session_attach_options mln_render_session_attach_options

Common attachment policy copied before an attach call returns.

Every backend attachment call requires *out_session to be MLN_HANDLE_NULL on entry. MLN_STATUS_OK transfers an ATTACHING session to the caller and accepts its completion. A non-OK return leaves *out_session unchanged and invokes no completion. Hosts may service caller-driver work before attachment completes. A failed completion still requires mln_render_session_detach() or mln_render_session_abandon() before mln_render_session_release().

mln_render_session_capabilities

typedef struct mln_render_session_capabilities mln_render_session_capabilities

Driver and target capabilities fixed for one attached render session.

mln_render_session_capability_flag

typedef enum mln_render_session_capability_flag mln_render_session_capability_flag

Optional render-session capabilities.

mln_vulkan_context_descriptor

typedef struct mln_vulkan_context_descriptor mln_vulkan_context_descriptor

Vulkan backend context fields shared by Vulkan render targets.

mln_vulkan_non_dispatchable_handle

typedef uint64_t mln_vulkan_non_dispatchable_handle

Bit pattern of a Vulkan non-dispatchable handle.

It carries either native representation of the handle, a pointer or a uint64_t. Zero represents VK_NULL_HANDLE.

mln_webgl_context_descriptor

typedef struct mln_webgl_context_descriptor mln_webgl_context_descriptor

WebGL context fields shared by OpenGL render targets in the browser.

mln_webgl_context_kind

typedef enum mln_webgl_context_kind mln_webgl_context_kind

WebGL context placement.

mln_webgpu_context_descriptor

typedef struct mln_webgpu_context_descriptor mln_webgpu_context_descriptor

WebGPU backend context fields shared by WebGPU render targets.

mln_wgl_context_descriptor

typedef struct mln_wgl_context_descriptor mln_wgl_context_descriptor

WGL context fields shared by OpenGL render targets on Windows.

Enumeration Type Documentation

mln_gpu_sync_kind

enum mln_gpu_sync_kind : uint32_t

Synchronization payload kind for acquired texture frames.

Enumerator
MLN_GPU_SYNC_CPU_COMPLETE	The host needs no synchronization object. The work completed, or on WebGPU was submitted to the device's queue, before the frame became acquirable or before the release call. As producer synchronization of an acquired frame: on Metal, Vulkan, and OpenGL, the producer's GPU writes to the frame's texture completed before the frame became acquirable. On OpenGL, a host that samples the texture from another context of the share group binds it again after acquisition. On WebGPU, the writes were submitted to the device's queue, which orders them before any work that the host submits afterwards. As consumer synchronization: the host's GPU reads completed before the release call, or on WebGPU were submitted to the device's queue before it.
MLN_GPU_SYNC_OPENGL_FENCE	GLsync in the shared EGL or WGL context's share group, used only by a caller-graphics-thread driver. object is nonzero. A producer fence is a flushed GL_SYNC_GPU_COMMANDS_COMPLETE fence. Before reading the texture, the host queues glWaitSync(object, 0, GL_TIMEOUT_IGNORED) in a context in that share group and binds the texture again. A CPU read instead waits with glClientWaitSync. EGL targets use GLsync, not EGLSync. The session owns producer fences. The host borrows one until it releases or disposes the acquired frame and must never delete it. A view scope extends that borrowing. The host inserts a consumer fence after its reads and calls glFlush in that context before releasing the frame. A successful release transfers the fence to the session, which waits on it before it renders into the slot again. Target loss invalidates frame access and may retain consumer fences until process exit. Abandon performs no graphics cleanup and may retain producer and consumer fences until process exit. The host finishes its GPU reads before destroying borrowed textures.

mln_opengl_client_api

enum mln_opengl_client_api : uint32_t

OpenGL client API a dedicated EGL session creates its context for.

Enumerator
MLN_OPENGL_CLIENT_API_UNSPECIFIED	No client API is named.
MLN_OPENGL_CLIENT_API_GL	Desktop OpenGL, as EGL_OPENGL_API names it.
MLN_OPENGL_CLIENT_API_GLES	OpenGL ES, as EGL_OPENGL_ES_API names it.

mln_opengl_context_ownership

enum mln_opengl_context_ownership : uint32_t

How a session's OpenGL context relates to its driver thread and host graphics state.

A shared session leaves the thread as it found it: every render makes the session context current and restores whatever was current before. The session context joins the host share group named by the descriptor, so a host may hand the session a texture and sample it from its own context.

A dedicated session joins no share group and leaves its context current after a render instead of restoring what was current before. A render that finds another context current makes its own current again, so several dedicated sessions can share one thread, and the host can use its own context between renders. Teardown releases the session context from the thread and restores nothing.

Enumerator
MLN_OPENGL_CONTEXT_OWNERSHIP_SHARED	The session shares its thread with host graphics work.
MLN_OPENGL_CONTEXT_OWNERSHIP_DEDICATED	The session keeps its own OpenGL context current on its thread.

mln_opengl_context_platform

enum mln_opengl_context_platform : uint32_t

OpenGL platform context provider used by a context descriptor.

Enumerator
MLN_OPENGL_CONTEXT_PLATFORM_UNSPECIFIED	No OpenGL context provider is selected.
MLN_OPENGL_CONTEXT_PLATFORM_WEBGL	Emscripten WebGL context handle.

mln_opengl_context_provider_flag

enum mln_opengl_context_provider_flag : uint32_t

OpenGL context providers supported by this build.

Enumerator
MLN_OPENGL_CONTEXT_PROVIDER_FLAG_WEBGL	Browser WebGL context imported into an Emscripten module.

mln_render_driver_kind

enum mln_render_driver_kind : uint32_t

Execution placement for one render session.

Enumerator
MLN_RENDER_DRIVER_CORE_WORKER	Native code initializes, services, and tears down transferable graphics state on a library-owned thread.
MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD	The host services driver work on the thread or realm where its graphics context is current.

mln_render_session_capability_flag

enum mln_render_session_capability_flag : uint32_t

Optional render-session capabilities.

mln_webgl_context_kind

enum mln_webgl_context_kind : uint32_t

WebGL context placement.

Enumerator
MLN_WEBGL_CONTEXT_EXISTING	Use a host-created context on its current browser agent.
MLN_WEBGL_CONTEXT_TRANSFERRED_CANVAS	Transfer the canvas named by canvas_selector to a native worker and create a WebGL 2 context there.

Function Documentation

mln_gpu_sync_default()

mln_gpu_sync mln_gpu_sync_default

(

void

)

Returns CPU-complete synchronization for this C API version.

mln_logical_extent_physical_size()

mln_status mln_logical_extent_physical_size	(	mln_logical_extent	extent,
		uint32_t *	out_width,
		uint32_t *	out_height,
		mln_diagnostic *	out_diagnostic )

Computes the physical device-pixel size of a logical extent.

Each dimension is ceil(logical * scale_factor). Session-owned texture targets and surface targets are sized this way. Caller-owned borrowed texture targets state their physical size directly; see texture.h.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when extent has a zero width or height, or a scale_factor that is not finite and positive; out_width or out_height is null; or a scaled dimension exceeds UINT32_MAX.

mln_opengl_supported_context_provider_mask()

uint32_t mln_opengl_supported_context_provider_mask

(

void

)

Returns OpenGL context providers supported by this build.

mln_render_session_attach_options_default()

mln_render_session_attach_options mln_render_session_attach_options_default

(

void

)

Returns attachment options initialized for this C API version, with each field at its documented default.