texture.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_metal_owned_texture_descriptor
struct	mln_metal_borrowed_texture
struct	mln_metal_borrowed_texture_descriptor
struct	mln_metal_texture_frame
struct	mln_vulkan_owned_texture_descriptor
struct	mln_vulkan_borrowed_texture
struct	mln_vulkan_borrowed_texture_descriptor
struct	mln_vulkan_texture_frame
struct	mln_opengl_owned_texture_descriptor
struct	mln_opengl_borrowed_texture
struct	mln_opengl_borrowed_texture_descriptor
struct	mln_webgpu_owned_texture_descriptor
struct	mln_webgpu_borrowed_texture
struct	mln_webgpu_borrowed_texture_descriptor
struct	mln_webgpu_texture_frame
struct	mln_opengl_texture_frame
struct	mln_texture_image_info
struct	mln_texture_readback_result

Typedefs
typedef struct mln_metal_owned_texture_descriptor	mln_metal_owned_texture_descriptor
typedef struct mln_metal_borrowed_texture	mln_metal_borrowed_texture
typedef struct mln_metal_borrowed_texture_descriptor	mln_metal_borrowed_texture_descriptor
typedef struct mln_metal_texture_frame	mln_metal_texture_frame
typedef struct mln_vulkan_owned_texture_descriptor	mln_vulkan_owned_texture_descriptor
typedef struct mln_vulkan_borrowed_texture	mln_vulkan_borrowed_texture
typedef struct mln_vulkan_borrowed_texture_descriptor	mln_vulkan_borrowed_texture_descriptor
typedef struct mln_vulkan_texture_frame	mln_vulkan_texture_frame
typedef struct mln_opengl_owned_texture_descriptor	mln_opengl_owned_texture_descriptor
typedef struct mln_opengl_borrowed_texture	mln_opengl_borrowed_texture
typedef struct mln_opengl_borrowed_texture_descriptor	mln_opengl_borrowed_texture_descriptor
typedef struct mln_webgpu_owned_texture_descriptor	mln_webgpu_owned_texture_descriptor
typedef struct mln_webgpu_borrowed_texture	mln_webgpu_borrowed_texture
typedef struct mln_webgpu_borrowed_texture_descriptor	mln_webgpu_borrowed_texture_descriptor
typedef struct mln_webgpu_texture_frame	mln_webgpu_texture_frame
typedef struct mln_opengl_texture_frame	mln_opengl_texture_frame
typedef struct mln_texture_image_info	mln_texture_image_info
typedef struct mln_texture_readback_result	mln_texture_readback_result

Functions
mln_metal_owned_texture_descriptor	mln_metal_owned_texture_descriptor_default (void)
mln_metal_borrowed_texture_descriptor	mln_metal_borrowed_texture_descriptor_default (void)
mln_vulkan_owned_texture_descriptor	mln_vulkan_owned_texture_descriptor_default (void)
mln_vulkan_borrowed_texture_descriptor	mln_vulkan_borrowed_texture_descriptor_default (void)
mln_opengl_owned_texture_descriptor	mln_opengl_owned_texture_descriptor_default (void)
mln_opengl_borrowed_texture_descriptor	mln_opengl_borrowed_texture_descriptor_default (void)
mln_webgpu_owned_texture_descriptor	mln_webgpu_owned_texture_descriptor_default (void)
mln_webgpu_borrowed_texture_descriptor	mln_webgpu_borrowed_texture_descriptor_default (void)
mln_status	mln_map_attach_metal_owned_texture (mln_map map, const mln_metal_owned_texture_descriptor *descriptor, const mln_render_session_attach_options *options, mln_render_session *out_session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_attach_metal_borrowed_texture (mln_map map, const mln_metal_borrowed_texture_descriptor *descriptor, const mln_render_session_attach_options *options, mln_render_session *out_session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_attach_vulkan_owned_texture (mln_map map, const mln_vulkan_owned_texture_descriptor *descriptor, const mln_render_session_attach_options *options, mln_render_session *out_session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_attach_vulkan_borrowed_texture (mln_map map, const mln_vulkan_borrowed_texture_descriptor *descriptor, const mln_render_session_attach_options *options, mln_render_session *out_session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_attach_opengl_owned_texture (mln_map map, const mln_opengl_owned_texture_descriptor *descriptor, const mln_render_session_attach_options *options, mln_render_session *out_session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_attach_opengl_borrowed_texture (mln_map map, const mln_opengl_borrowed_texture_descriptor *descriptor, const mln_render_session_attach_options *options, mln_render_session *out_session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_attach_webgpu_owned_texture (mln_map map, const mln_webgpu_owned_texture_descriptor *descriptor, const mln_render_session_attach_options *options, mln_render_session *out_session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_map_attach_webgpu_borrowed_texture (mln_map map, const mln_webgpu_borrowed_texture_descriptor *descriptor, const mln_render_session_attach_options *options, mln_render_session *out_session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_render_session_set_metal_borrowed_texture_target (mln_render_session session, const mln_metal_borrowed_texture_descriptor *descriptor, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_render_session_set_vulkan_borrowed_texture_target (mln_render_session session, const mln_vulkan_borrowed_texture_descriptor *descriptor, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_render_session_set_opengl_borrowed_texture_target (mln_render_session session, const mln_opengl_borrowed_texture_descriptor *descriptor, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_render_session_set_webgpu_borrowed_texture_target (mln_render_session session, const mln_webgpu_borrowed_texture_descriptor *descriptor, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_render_session_read_texture (mln_render_session session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_acquired_frame_get_metal_texture (mln_acquired_frame frame, mln_metal_texture_frame *out_frame, mln_diagnostic *out_diagnostic)
mln_status	mln_acquired_frame_get_vulkan_texture (mln_acquired_frame frame, mln_vulkan_texture_frame *out_frame, mln_diagnostic *out_diagnostic)
mln_status	mln_acquired_frame_get_opengl_texture (mln_acquired_frame frame, mln_opengl_texture_frame *out_frame, mln_diagnostic *out_diagnostic)
mln_status	mln_acquired_frame_get_webgpu_texture (mln_acquired_frame frame, mln_webgpu_texture_frame *out_frame, mln_diagnostic *out_diagnostic)

Detailed Description

Public C API declarations for texture render targets.

Typedef Documentation

mln_metal_borrowed_texture

typedef struct mln_metal_borrowed_texture mln_metal_borrowed_texture

One caller-owned Metal texture of a borrowed texture ring.

mln_metal_borrowed_texture_descriptor

typedef struct mln_metal_borrowed_texture_descriptor mln_metal_borrowed_texture_descriptor

Metal attachment options for a borrowed texture target.

mln_metal_owned_texture_descriptor

typedef struct mln_metal_owned_texture_descriptor mln_metal_owned_texture_descriptor

Metal attachment options for an owned texture target.

mln_metal_texture_frame

typedef struct mln_metal_texture_frame mln_metal_texture_frame

Metal frame acquired from a texture ring.

mln_opengl_borrowed_texture

typedef struct mln_opengl_borrowed_texture mln_opengl_borrowed_texture

One caller-owned OpenGL texture of a borrowed texture ring.

mln_opengl_borrowed_texture_descriptor

typedef struct mln_opengl_borrowed_texture_descriptor mln_opengl_borrowed_texture_descriptor

OpenGL attachment options for a borrowed texture target.

mln_opengl_owned_texture_descriptor

typedef struct mln_opengl_owned_texture_descriptor mln_opengl_owned_texture_descriptor

OpenGL attachment options for an owned texture target.

mln_opengl_texture_frame

typedef struct mln_opengl_texture_frame mln_opengl_texture_frame

OpenGL frame acquired from a texture ring.

mln_texture_image_info

typedef struct mln_texture_image_info mln_texture_image_info

CPU image readback metadata for a texture target frame.

mln_texture_readback_result

typedef struct mln_texture_readback_result mln_texture_readback_result

Texture readback borrowed for a completion callback.

mln_vulkan_borrowed_texture

typedef struct mln_vulkan_borrowed_texture mln_vulkan_borrowed_texture

One caller-owned Vulkan image of a borrowed texture ring.

mln_vulkan_borrowed_texture_descriptor

typedef struct mln_vulkan_borrowed_texture_descriptor mln_vulkan_borrowed_texture_descriptor

Vulkan attachment options for a borrowed texture target.

mln_vulkan_owned_texture_descriptor

typedef struct mln_vulkan_owned_texture_descriptor mln_vulkan_owned_texture_descriptor

Vulkan attachment options for an owned texture target.

mln_vulkan_texture_frame

typedef struct mln_vulkan_texture_frame mln_vulkan_texture_frame

Vulkan frame acquired from a texture ring.

mln_webgpu_borrowed_texture

typedef struct mln_webgpu_borrowed_texture mln_webgpu_borrowed_texture

One caller-owned WebGPU texture of a borrowed texture ring.

mln_webgpu_borrowed_texture_descriptor

typedef struct mln_webgpu_borrowed_texture_descriptor mln_webgpu_borrowed_texture_descriptor

WebGPU attachment options for a borrowed texture target.

mln_webgpu_owned_texture_descriptor

typedef struct mln_webgpu_owned_texture_descriptor mln_webgpu_owned_texture_descriptor

WebGPU attachment options for an owned texture target.

mln_webgpu_texture_frame

typedef struct mln_webgpu_texture_frame mln_webgpu_texture_frame

WebGPU frame acquired from a texture ring.

Function Documentation

mln_acquired_frame_get_metal_texture()

mln_status mln_acquired_frame_get_metal_texture	(	mln_acquired_frame	frame,
		mln_metal_texture_frame *	out_frame,
		mln_diagnostic *	out_diagnostic )

Copies Metal-native metadata from an acquired frame.

The texture and device pointers are borrowed and remain valid only until mln_acquired_frame_release(). A host that may dispose the frame or its session from another thread uses them inside an mln_acquired_frame_view_begin() scope.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when frame is an invalid handle, or out_frame is null or undersized.
• MLN_STATUS_INVALID_STATE when frame has been released.
• MLN_STATUS_UNSUPPORTED when the frame was produced by a different render backend.
• MLN_STATUS_TARGET_LOST when the session lost or abandoned its target.
• MLN_STATUS_NATIVE_ERROR when native code fails.

mln_acquired_frame_get_opengl_texture()

mln_status mln_acquired_frame_get_opengl_texture	(	mln_acquired_frame	frame,
		mln_opengl_texture_frame *	out_frame,
		mln_diagnostic *	out_diagnostic )

Copies OpenGL-native metadata from an acquired frame.

The caller driver's context must be current on this thread. The texture name is borrowed and remains valid only until mln_acquired_frame_release(). A host that may dispose the frame or its session from another thread uses it inside an mln_acquired_frame_view_begin() scope.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when frame is an invalid handle, or out_frame is null or undersized.
• MLN_STATUS_INVALID_STATE when frame has been released.
• MLN_STATUS_UNSUPPORTED when the frame was produced by a different render backend.
• MLN_STATUS_TARGET_LOST when the session lost or abandoned its target.
• MLN_STATUS_NATIVE_ERROR when native code fails.

mln_acquired_frame_get_vulkan_texture()

mln_status mln_acquired_frame_get_vulkan_texture	(	mln_acquired_frame	frame,
		mln_vulkan_texture_frame *	out_frame,
		mln_diagnostic *	out_diagnostic )

Copies Vulkan-native metadata from an acquired frame.

The image and image view handles and the device pointer are borrowed and remain valid only until mln_acquired_frame_release(). A host that may dispose the frame or its session from another thread uses them inside an mln_acquired_frame_view_begin() scope.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when frame is an invalid handle, or out_frame is null or undersized.
• MLN_STATUS_INVALID_STATE when frame has been released.
• MLN_STATUS_UNSUPPORTED when the frame was produced by a different render backend.
• MLN_STATUS_TARGET_LOST when the session lost or abandoned its target.
• MLN_STATUS_NATIVE_ERROR when native code fails.

mln_acquired_frame_get_webgpu_texture()

mln_status mln_acquired_frame_get_webgpu_texture	(	mln_acquired_frame	frame,
		mln_webgpu_texture_frame *	out_frame,
		mln_diagnostic *	out_diagnostic )

Copies WebGPU-native metadata from an acquired frame.

The texture, view, and device pointers are borrowed and remain valid only until mln_acquired_frame_release(). A host that may dispose the frame or its session from another thread uses them inside an mln_acquired_frame_view_begin() scope.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when frame is an invalid handle, or out_frame is null or undersized.
• MLN_STATUS_INVALID_STATE when frame has been released.
• MLN_STATUS_UNSUPPORTED when the frame was produced by a different render backend.
• MLN_STATUS_TARGET_LOST when the session lost or abandoned its target.
• MLN_STATUS_NATIVE_ERROR when native code fails.

mln_map_attach_metal_borrowed_texture()

mln_status mln_map_attach_metal_borrowed_texture	(	mln_map	map,
		const mln_metal_borrowed_texture_descriptor *	descriptor,
		const mln_render_session_attach_options *	options,
		mln_render_session *	out_session,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts attachment of a ring of caller-owned Metal textures.

The session renders into the descriptor's textures as a ring whose depth is their count, and grants frame acquisition and consumer synchronization, but not readback. It never renders into a texture whose frame is acquired. Without acquisition, the session may render into any slot that no acquired frame holds whenever it runs a demand. A host that samples a texture across demands on a core worker acquires its frame first. The common options select driver placement; their requested ring depth is ignored. The descriptor, its textures array, and the options are copied before return.

Returns:

• MLN_STATUS_OK when the attachment is accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle; descriptor, options, or completion is null or undersized; a required backend handle is null; textures is null, texture_count is zero or above MLN_TEXTURE_RING_MAX_DEPTH, or two entries name the same texture; the textures differ in device or pixel format, or one does not match the physical size, render-target usage, or sample count; descriptor->extent has a zero width or height, or a scale_factor that is not finite and positive; the stated physical size is zero; out_session is null or does not point to the null handle; or the requested driver kind is unknown, or options carry a malformed wake or queue lock.
• MLN_STATUS_INVALID_STATE when map has been released.
• MLN_STATUS_UNSUPPORTED when this build carries no Metal backend, or options enable a queue lock.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver owns the target.
• MLN_STATUS_NATIVE_ERROR when target initialization fails.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_map_attach_metal_owned_texture()

mln_status mln_map_attach_metal_owned_texture	(	mln_map	map,
		const mln_metal_owned_texture_descriptor *	descriptor,
		const mln_render_session_attach_options *	options,
		mln_render_session *	out_session,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts attachment of a session-owned Metal texture ring.

The common options select driver placement and requested ring depth. The descriptor and options are copied before return.

Returns:

• MLN_STATUS_OK when the attachment is accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle; descriptor, options, or completion is null or undersized; a required backend handle is null; descriptor->extent has a zero width or height, a scale_factor that is not finite and positive, or a scaled dimension past UINT32_MAX; descriptor->pixel_format is neither format it accepts; out_session is null or does not point to the null handle; or the requested driver kind is unknown, or options carry a malformed wake or queue lock.
• MLN_STATUS_INVALID_STATE when map has been released.
• MLN_STATUS_UNSUPPORTED when this build carries no Metal backend, or options enable a queue lock.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver owns the target.
• MLN_STATUS_NATIVE_ERROR when target initialization fails.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_map_attach_opengl_borrowed_texture()

mln_status mln_map_attach_opengl_borrowed_texture	(	mln_map	map,
		const mln_opengl_borrowed_texture_descriptor *	descriptor,
		const mln_render_session_attach_options *	options,
		mln_render_session *	out_session,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts attachment of a ring of caller-owned OpenGL textures.

The textures are GL_TEXTURE_2D, and the ring behaves as mln_map_attach_metal_borrowed_texture() describes.

Returns:

• MLN_STATUS_OK when the attachment is accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle; descriptor, options, or completion is null or undersized; a required backend handle is null; textures is null, texture_count is zero or above MLN_TEXTURE_RING_MAX_DEPTH, or two entries name the same texture; target is not GL_TEXTURE_2D; descriptor->extent has a zero width or height, or a scale_factor that is not finite and positive; the stated physical size is zero; out_session is null or does not point to the null handle; or the requested driver kind is unknown, or options carry a malformed wake or queue lock.
• MLN_STATUS_INVALID_STATE when map has been released.
• MLN_STATUS_UNSUPPORTED when this build carries no OpenGL backend, its context provider is unavailable; the requested driver is not MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD; or options enable a queue lock.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver owns the target.
• MLN_STATUS_NATIVE_ERROR when target initialization fails.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_map_attach_opengl_owned_texture()

mln_status mln_map_attach_opengl_owned_texture	(	mln_map	map,
		const mln_opengl_owned_texture_descriptor *	descriptor,
		const mln_render_session_attach_options *	options,
		mln_render_session *	out_session,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts attachment of a session-owned OpenGL texture ring.

Shared WGL, EGL, and existing WebGL contexts require the caller driver and grant frame acquisition, readback, and consumer synchronization. Dedicated EGL, dedicated WGL, and transferred WebGL contexts require the core-worker driver and grant readback only with a ring depth of one.

The host keeps every descriptor-named backend handle valid through completed detach. In particular, it keeps an EGLDisplay initialized while its session is live.

Returns:

• MLN_STATUS_OK when the attachment is accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle; descriptor, options, or completion is null or undersized; a required backend handle is null; descriptor->extent has a zero width or height, a scale_factor that is not finite and positive, or a scaled dimension past UINT32_MAX; out_session is null or does not point to the null handle; or the requested driver kind is unknown, or options carry a malformed wake or queue lock.
• MLN_STATUS_INVALID_STATE when map has been released.
• MLN_STATUS_UNSUPPORTED when this build carries no OpenGL backend, its context provider is unavailable; the requested driver does not match the context placement; or options enable a queue lock.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver owns the target.
• MLN_STATUS_NATIVE_ERROR when target initialization fails.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_map_attach_vulkan_borrowed_texture()

mln_status mln_map_attach_vulkan_borrowed_texture	(	mln_map	map,
		const mln_vulkan_borrowed_texture_descriptor *	descriptor,
		const mln_render_session_attach_options *	options,
		mln_render_session *	out_session,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts attachment of a ring of caller-owned Vulkan images.

The ring behaves as mln_map_attach_metal_borrowed_texture() describes.

Returns:

• MLN_STATUS_OK when the attachment is accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle; descriptor, options, or completion is null or undersized; a required backend handle is null; textures is null, texture_count is zero or above MLN_TEXTURE_RING_MAX_DEPTH, or two entries name the same texture; descriptor->extent has a zero width or height, or a scale_factor that is not finite and positive; the stated physical size is zero; out_session is null or does not point to the null handle; or the requested driver kind is unknown, or options carry a malformed wake or queue lock.
• MLN_STATUS_INVALID_STATE when map has been released.
• MLN_STATUS_UNSUPPORTED when this build carries no Vulkan backend.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver owns the target.
• MLN_STATUS_NATIVE_ERROR when target initialization fails.
• MLN_STATUS_INVALID_ARGUMENT when the driver finds the context inconsistent, such as a physical device of another instance or a graphics_queue_family_index that names no graphics queue family.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_map_attach_vulkan_owned_texture()

mln_status mln_map_attach_vulkan_owned_texture	(	mln_map	map,
		const mln_vulkan_owned_texture_descriptor *	descriptor,
		const mln_render_session_attach_options *	options,
		mln_render_session *	out_session,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts attachment of a session-owned Vulkan texture ring.

The common options select driver placement and requested ring depth. The descriptor and options are copied before return.

Returns:

• MLN_STATUS_OK when the attachment is accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle; descriptor, options, or completion is null or undersized; a required backend handle is null; descriptor->extent has a zero width or height, a scale_factor that is not finite and positive, or a scaled dimension past UINT32_MAX; out_session is null or does not point to the null handle; or the requested driver kind is unknown, or options carry a malformed wake or queue lock.
• MLN_STATUS_INVALID_STATE when map has been released.
• MLN_STATUS_UNSUPPORTED when this build carries no Vulkan backend.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver owns the target.
• MLN_STATUS_NATIVE_ERROR when target initialization fails.
• MLN_STATUS_INVALID_ARGUMENT when the driver finds the context inconsistent, such as a physical device of another instance or a graphics_queue_family_index that names no graphics queue family.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_map_attach_webgpu_borrowed_texture()

mln_status mln_map_attach_webgpu_borrowed_texture	(	mln_map	map,
		const mln_webgpu_borrowed_texture_descriptor *	descriptor,
		const mln_render_session_attach_options *	options,
		mln_render_session *	out_session,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts attachment of a ring of caller-owned WebGPU textures.

Browser targets require MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD. The ring otherwise behaves as mln_map_attach_metal_borrowed_texture() describes.

Returns:

• MLN_STATUS_OK when the attachment is accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle; descriptor, options, or completion is null or undersized; a required backend handle is null; textures is null, texture_count is zero or above MLN_TEXTURE_RING_MAX_DEPTH, or two entries name the same texture; descriptor->extent has a zero width or height, or a scale_factor that is not finite and positive; the stated physical size is zero; out_session is null or does not point to the null handle; or the requested driver kind is unknown, or options carry a malformed wake or queue lock.
• MLN_STATUS_INVALID_STATE when map has been released.
• MLN_STATUS_UNSUPPORTED when this build carries no WebGPU backend, or the requested driver is not MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD, or options enable a queue lock.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver owns the target.
• MLN_STATUS_NATIVE_ERROR when target initialization fails.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_map_attach_webgpu_owned_texture()

mln_status mln_map_attach_webgpu_owned_texture	(	mln_map	map,
		const mln_webgpu_owned_texture_descriptor *	descriptor,
		const mln_render_session_attach_options *	options,
		mln_render_session *	out_session,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts attachment of a session-owned WebGPU texture ring.

Browser targets require MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD.

Returns:

• MLN_STATUS_OK when the attachment is accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is an invalid handle; descriptor, options, or completion is null or undersized; a required backend handle is null; descriptor->extent has a zero width or height, a scale_factor that is not finite and positive, or a scaled dimension past UINT32_MAX; out_session is null or does not point to the null handle; or the requested driver kind is unknown, or options carry a malformed wake or queue lock.
• MLN_STATUS_INVALID_STATE when map has been released.
• MLN_STATUS_UNSUPPORTED when this build carries no WebGPU backend, or the requested driver is not MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD, or options enable a queue lock.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver owns the target.
• MLN_STATUS_NATIVE_ERROR when target initialization fails.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_metal_borrowed_texture_descriptor_default()

mln_metal_borrowed_texture_descriptor mln_metal_borrowed_texture_descriptor_default

(

void

)

Returns Metal borrowed-texture descriptor defaults for this C API version.

mln_metal_owned_texture_descriptor_default()

mln_metal_owned_texture_descriptor mln_metal_owned_texture_descriptor_default

(

void

)

Returns Metal owned-texture descriptor defaults for this C API version.

mln_opengl_borrowed_texture_descriptor_default()

mln_opengl_borrowed_texture_descriptor mln_opengl_borrowed_texture_descriptor_default

(

void

)

Returns OpenGL borrowed-texture descriptor defaults for this C API version.

mln_opengl_owned_texture_descriptor_default()

mln_opengl_owned_texture_descriptor mln_opengl_owned_texture_descriptor_default

(

void

)

Returns OpenGL owned-texture descriptor defaults for this C API version.

mln_render_session_read_texture()

mln_status mln_render_session_read_texture	(	mln_render_session	session,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Reads back the latest frame of the session's owned texture as premultiplied RGBA8.

The completion delivers one mln_texture_readback_result as its value, with a value_count of one. Its pixel bytes are borrowed for the duration of the callback; copy anything the host keeps.

On browser WebGPU the readback finishes on a later driver service, after the graphics thread's event loop delivers the mapped copy; see mln_render_session_service_driver_work(). The session's later driver work runs after it. A lost device fails the readback.

Returns:

• MLN_STATUS_OK when the readback is accepted.
• MLN_STATUS_INVALID_ARGUMENT when session is an invalid handle, or completion is null or undersized.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK and one mln_texture_readback_result.
• MLN_STATUS_UNSUPPORTED when the target is not a session-owned texture ring or its backend cannot read back.
• MLN_STATUS_INVALID_STATE when no frame has been rendered at the session's current generation.
• MLN_STATUS_NATIVE_ERROR when the read fails.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_render_session_set_metal_borrowed_texture_target()

mln_status mln_render_session_set_metal_borrowed_texture_target	(	mln_render_session	session,
		const mln_metal_borrowed_texture_descriptor *	descriptor,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts an ordered replacement of every texture of a caller-owned Metal ring.

The descriptor and its textures array are copied before return. The replacement names as many textures as the session attached with, each belonging to the device this session attached with.

The replacement runs in order with the session's other driver work. Frames published before the replacement can no longer be acquired: acquisition reports MLN_STATUS_NOT_READY from this call's return until the replacement has run. The replacement also returns to service every slot whose frame was disposed. The completion means that the session no longer renders into or reads the replaced textures.

Returns:

• MLN_STATUS_OK when the replacement is accepted.
• MLN_STATUS_INVALID_ARGUMENT when session is an invalid handle; descriptor or completion is null or undersized; a required backend handle is null; textures is null, texture_count is zero, above MLN_TEXTURE_RING_MAX_DEPTH, or different from the session's ring depth, or two entries name the same texture; descriptor->extent has a zero width or height, or a scale_factor that is not finite and positive; or the stated physical size is zero.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached, or while a frame of the ring is acquired.
• MLN_STATUS_UNSUPPORTED when this build carries no Metal backend, or the session does not render into a caller-owned texture.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver renders into the new textures.
• MLN_STATUS_INVALID_ARGUMENT when the replacement belongs to another device.
• MLN_STATUS_UNSUPPORTED when the replacement's pixel format differs from the one the session attached with.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_render_session_set_opengl_borrowed_texture_target()

mln_status mln_render_session_set_opengl_borrowed_texture_target	(	mln_render_session	session,
		const mln_opengl_borrowed_texture_descriptor *	descriptor,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts an ordered replacement of every texture of a caller-owned OpenGL ring.

The descriptor and its textures array are copied before return. The replacement names as many GL_TEXTURE_2D textures as the session attached with, in the context this session attached with.

The replacement otherwise behaves as mln_render_session_set_metal_borrowed_texture_target() describes.

Returns:

• MLN_STATUS_OK when the replacement is accepted.
• MLN_STATUS_INVALID_ARGUMENT when session is an invalid handle; descriptor or completion is null or undersized; a required backend handle is null; textures is null, texture_count is zero, above MLN_TEXTURE_RING_MAX_DEPTH, or different from the session's ring depth, or two entries name the same texture; descriptor->extent has a zero width or height, or a scale_factor that is not finite and positive; or the stated physical size is zero.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached, or while a frame of the ring is acquired.
• MLN_STATUS_UNSUPPORTED when this build carries no OpenGL backend, or the session does not render into a caller-owned texture.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver renders into the new textures.
• MLN_STATUS_INVALID_ARGUMENT when the replacement names another context.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_render_session_set_vulkan_borrowed_texture_target()

mln_status mln_render_session_set_vulkan_borrowed_texture_target	(	mln_render_session	session,
		const mln_vulkan_borrowed_texture_descriptor *	descriptor,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts an ordered replacement of every image of a caller-owned Vulkan ring.

The descriptor and its textures array are copied before return. The replacement names as many images as the session attached with, and the context this session attached with.

The replacement otherwise behaves as mln_render_session_set_metal_borrowed_texture_target() describes.

Returns:

• MLN_STATUS_OK when the replacement is accepted.
• MLN_STATUS_INVALID_ARGUMENT when session is an invalid handle; descriptor or completion is null or undersized; a required backend handle is null; textures is null, texture_count is zero, above MLN_TEXTURE_RING_MAX_DEPTH, or different from the session's ring depth, or two entries name the same texture; descriptor->extent has a zero width or height, or a scale_factor that is not finite and positive; or the stated physical size is zero.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached, or while a frame of the ring is acquired.
• MLN_STATUS_UNSUPPORTED when this build carries no Vulkan backend, or the session does not render into a caller-owned texture.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver renders into the new textures.
• MLN_STATUS_INVALID_ARGUMENT when the replacement names another context.
• MLN_STATUS_UNSUPPORTED when the replacement's format or layouts differ from those the session attached with.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_render_session_set_webgpu_borrowed_texture_target()

mln_status mln_render_session_set_webgpu_borrowed_texture_target	(	mln_render_session	session,
		const mln_webgpu_borrowed_texture_descriptor *	descriptor,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts an ordered replacement of every texture of a caller-owned WebGPU ring.

The descriptor and its textures array are copied before return. The replacement names as many textures as the session attached with, and the device and queue this session attached with.

The replacement otherwise behaves as mln_render_session_set_metal_borrowed_texture_target() describes.

Returns:

• MLN_STATUS_OK when the replacement is accepted.
• MLN_STATUS_INVALID_ARGUMENT when session is an invalid handle; descriptor or completion is null or undersized; a required backend handle is null; textures is null, texture_count is zero, above MLN_TEXTURE_RING_MAX_DEPTH, or different from the session's ring depth, or two entries name the same texture; descriptor->extent has a zero width or height, or a scale_factor that is not finite and positive; or the stated physical size is zero.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached, or while a frame of the ring is acquired.
• MLN_STATUS_UNSUPPORTED when this build carries no WebGPU backend, or the session does not render into a caller-owned texture.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver renders into the new textures.
• MLN_STATUS_INVALID_ARGUMENT when the replacement names another device or queue.
• MLN_STATUS_UNSUPPORTED when the replacement's format differs from the one the session attached with.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_vulkan_borrowed_texture_descriptor_default()

mln_vulkan_borrowed_texture_descriptor mln_vulkan_borrowed_texture_descriptor_default

(

void

)

Returns Vulkan borrowed-texture descriptor defaults for this C API version.

mln_vulkan_owned_texture_descriptor_default()

mln_vulkan_owned_texture_descriptor mln_vulkan_owned_texture_descriptor_default

(

void

)

Returns Vulkan owned-texture descriptor defaults for this C API version.

mln_webgpu_borrowed_texture_descriptor_default()

mln_webgpu_borrowed_texture_descriptor mln_webgpu_borrowed_texture_descriptor_default

(

void

)

Returns WebGPU borrowed-texture descriptor defaults for this C API version.

mln_webgpu_owned_texture_descriptor_default()

mln_webgpu_owned_texture_descriptor mln_webgpu_owned_texture_descriptor_default

(

void

)

Returns WebGPU owned-texture descriptor defaults for this C API version.