surface.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_metal_surface_descriptor
struct	mln_vulkan_surface_descriptor
struct	mln_webgpu_surface_descriptor
struct	mln_opengl_surface_descriptor

Typedefs
typedef struct mln_metal_surface_descriptor	mln_metal_surface_descriptor
typedef struct mln_vulkan_surface_descriptor	mln_vulkan_surface_descriptor
typedef struct mln_webgpu_surface_descriptor	mln_webgpu_surface_descriptor
typedef struct mln_opengl_surface_descriptor	mln_opengl_surface_descriptor

Functions
mln_metal_surface_descriptor	mln_metal_surface_descriptor_default (void)
mln_vulkan_surface_descriptor	mln_vulkan_surface_descriptor_default (void)
mln_opengl_surface_descriptor	mln_opengl_surface_descriptor_default (void)
mln_webgpu_surface_descriptor	mln_webgpu_surface_descriptor_default (void)
mln_status	mln_map_attach_metal_surface (mln_map map, const mln_metal_surface_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_surface (mln_map map, const mln_vulkan_surface_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_surface (mln_map map, const mln_opengl_surface_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_surface (mln_map map, const mln_webgpu_surface_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_surface_target (mln_render_session session, const mln_metal_surface_descriptor *descriptor, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_render_session_set_vulkan_surface_target (mln_render_session session, const mln_vulkan_surface_descriptor *descriptor, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_render_session_set_opengl_surface_target (mln_render_session session, const mln_opengl_surface_descriptor *descriptor, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_render_session_set_webgpu_surface_target (mln_render_session session, const mln_webgpu_surface_descriptor *descriptor, const mln_completion *completion, mln_diagnostic *out_diagnostic)

Detailed Description

Public C API declarations for surface render targets.

Typedef Documentation

mln_metal_surface_descriptor

typedef struct mln_metal_surface_descriptor mln_metal_surface_descriptor

Metal attachment options for a native surface.

mln_opengl_surface_descriptor

typedef struct mln_opengl_surface_descriptor mln_opengl_surface_descriptor

OpenGL attachment options for a native surface.

mln_vulkan_surface_descriptor

typedef struct mln_vulkan_surface_descriptor mln_vulkan_surface_descriptor

Vulkan attachment options for a native surface.

mln_webgpu_surface_descriptor

typedef struct mln_webgpu_surface_descriptor mln_webgpu_surface_descriptor

WebGPU attachment options for a native surface.

Function Documentation

mln_map_attach_metal_surface()

mln_status mln_map_attach_metal_surface	(	mln_map	map,
		const mln_metal_surface_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 Metal surface target.

The descriptor and options are copied before return. An accepted attachment retains the Metal layer and device before return. The completion reports target initialization. A caller driver requires service on a thread where the Metal context is usable.

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 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_surface()

mln_status mln_map_attach_opengl_surface	(	mln_map	map,
		const mln_opengl_surface_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 an OpenGL surface target.

WGL, EGL, and existing WebGL contexts require MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD. A transferred WebGL canvas requires MLN_RENDER_DRIVER_CORE_WORKER. Context ownership remains independent.

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_surface()

mln_status mln_map_attach_vulkan_surface	(	mln_map	map,
		const mln_vulkan_surface_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 Vulkan surface target.

The descriptor and options are copied before return. The completion runs only after the selected driver creates the swapchain.

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_surface()

mln_status mln_map_attach_webgpu_surface	(	mln_map	map,
		const mln_webgpu_surface_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 WebGPU surface target.

Browser targets require MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD in the agent that created the WebGPU objects.

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_surface_descriptor_default()

mln_metal_surface_descriptor mln_metal_surface_descriptor_default

(

void

)

Returns Metal surface descriptor defaults for this C API version.

mln_opengl_surface_descriptor_default()

mln_opengl_surface_descriptor mln_opengl_surface_descriptor_default

(

void

)

Returns OpenGL surface descriptor defaults for this C API version.

mln_render_session_set_metal_surface_target()

mln_status mln_render_session_set_metal_surface_target	(	mln_render_session	session,
		const mln_metal_surface_descriptor *	descriptor,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts an ordered Metal surface replacement.

The descriptor is copied before return, and the session retains the replacement layer and device.

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; or descriptor->extent has a zero width or height, a scale_factor that is not finite and positive, or a scaled dimension past UINT32_MAX.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached, or a texture frame is still acquired.
• MLN_STATUS_UNSUPPORTED when this build carries no Metal backend, or the session does not render through a native surface.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver renders through the new target.
• MLN_STATUS_INVALID_ARGUMENT when the replacement names another device.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_render_session_set_opengl_surface_target()

mln_status mln_render_session_set_opengl_surface_target	(	mln_render_session	session,
		const mln_opengl_surface_descriptor *	descriptor,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts an ordered OpenGL surface replacement.

The descriptor is copied before return. The replacement must name the share group this session attached with.

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; or descriptor->extent has a zero width or height, a scale_factor that is not finite and positive, or a scaled dimension past UINT32_MAX.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached, or a texture frame is still acquired.
• MLN_STATUS_UNSUPPORTED when this build carries no OpenGL backend, or the session does not render through a native surface.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver renders through the new target.
• MLN_STATUS_INVALID_ARGUMENT when the replacement names another share group.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_render_session_set_vulkan_surface_target()

mln_status mln_render_session_set_vulkan_surface_target	(	mln_render_session	session,
		const mln_vulkan_surface_descriptor *	descriptor,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts an ordered Vulkan surface replacement.

The descriptor is copied before return. The replacement must name the context this session attached with.

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; or descriptor->extent has a zero width or height, a scale_factor that is not finite and positive, or a scaled dimension past UINT32_MAX.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached, or a texture frame is still acquired.
• MLN_STATUS_UNSUPPORTED when this build carries no Vulkan backend, or the session does not render through a native surface.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver renders through the new target.
• MLN_STATUS_INVALID_ARGUMENT when the replacement names another context, or its surface cannot present from the context's graphics queue.
• MLN_STATUS_UNSUPPORTED when the replacement surface's color format or transform differs from those the session attached with.
• MLN_STATUS_NATIVE_ERROR when querying the replacement surface fails.
• MLN_STATUS_TARGET_LOST when the session is abandoned first.

mln_render_session_set_webgpu_surface_target()

mln_status mln_render_session_set_webgpu_surface_target	(	mln_render_session	session,
		const mln_webgpu_surface_descriptor *	descriptor,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts an ordered WebGPU surface replacement.

The descriptor is copied before return. The replacement must name the device and queue this session attached with.

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; or descriptor->extent has a zero width or height, a scale_factor that is not finite and positive, or a scaled dimension past UINT32_MAX.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached, or a texture frame is still acquired.
• MLN_STATUS_UNSUPPORTED when this build carries no WebGPU backend, or the session does not render through a native surface.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_OK once the driver renders through the new target.
• 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_surface_descriptor_default()

mln_vulkan_surface_descriptor mln_vulkan_surface_descriptor_default

(

void

)

Returns Vulkan surface descriptor defaults for this C API version.

mln_webgpu_surface_descriptor_default()

mln_webgpu_surface_descriptor mln_webgpu_surface_descriptor_default

(

void

)

Returns WebGPU surface descriptor defaults for this C API version.