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_descriptor
struct	mln_metal_owned_texture_frame
struct	mln_vulkan_owned_texture_descriptor
struct	mln_vulkan_borrowed_texture_descriptor
struct	mln_vulkan_owned_texture_frame
struct	mln_opengl_owned_texture_descriptor
struct	mln_opengl_borrowed_texture_descriptor
struct	mln_opengl_owned_texture_frame
struct	mln_texture_image_info

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_texture_image_info	mln_texture_image_info_default (void)
mln_status	mln_metal_owned_texture_attach (mln_map *map, const mln_metal_owned_texture_descriptor *descriptor, mln_render_session **out_session)
mln_status	mln_metal_borrowed_texture_attach (mln_map *map, const mln_metal_borrowed_texture_descriptor *descriptor, mln_render_session **out_session)
mln_status	mln_vulkan_owned_texture_attach (mln_map *map, const mln_vulkan_owned_texture_descriptor *descriptor, mln_render_session **out_session)
mln_status	mln_vulkan_borrowed_texture_attach (mln_map *map, const mln_vulkan_borrowed_texture_descriptor *descriptor, mln_render_session **out_session)
mln_status	mln_opengl_owned_texture_attach (mln_map *map, const mln_opengl_owned_texture_descriptor *descriptor, mln_render_session **out_session)
mln_status	mln_opengl_borrowed_texture_attach (mln_map *map, const mln_opengl_borrowed_texture_descriptor *descriptor, mln_render_session **out_session)
mln_status	mln_texture_read_premultiplied_rgba8 (mln_render_session *session, uint8_t *out_data, size_t out_data_capacity, mln_texture_image_info *out_info)
mln_status	mln_metal_owned_texture_acquire_frame (mln_render_session *session, mln_metal_owned_texture_frame *out_frame)
mln_status	mln_metal_owned_texture_release_frame (mln_render_session *session, const mln_metal_owned_texture_frame *frame)
mln_status	mln_vulkan_owned_texture_acquire_frame (mln_render_session *session, mln_vulkan_owned_texture_frame *out_frame)
mln_status	mln_vulkan_owned_texture_release_frame (mln_render_session *session, const mln_vulkan_owned_texture_frame *frame)
mln_status	mln_opengl_owned_texture_acquire_frame (mln_render_session *session, mln_opengl_owned_texture_frame *out_frame)
mln_status	mln_opengl_owned_texture_release_frame (mln_render_session *session, const mln_opengl_owned_texture_frame *frame)

Detailed Description

Public C API declarations for texture render targets.

Function Documentation

mln_metal_borrowed_texture_attach()

mln_status mln_metal_borrowed_texture_attach	(	mln_map *	map,
		const mln_metal_borrowed_texture_descriptor *	descriptor,
		mln_render_session **	out_session )

Attaches a Metal caller-owned texture render target to a map.

The map may have at most one live render session. The session and every texture-session call are owner-thread affine to the map owner thread. The session renders into descriptor->texture. The caller owns the texture, keeps it valid until detach or destroy, and synchronizes any use outside this session. On success, *out_session receives a handle the caller destroys with mln_render_session_destroy().

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live, descriptor is null or invalid, out_session is null, or *out_session is not null.
• MLN_STATUS_INVALID_STATE when the map already has a render session.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_UNSUPPORTED when Metal borrowed texture sessions are not supported by this build.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

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

mln_status mln_metal_owned_texture_acquire_frame	(	mln_render_session *	session,
		mln_metal_owned_texture_frame *	out_frame )

Acquires the most recently rendered Metal texture frame.

Use this function with sessions created by mln_metal_owned_texture_attach().

The returned texture and device pointers are borrowed and remain valid only until mln_metal_owned_texture_release_frame() is called for the same frame. While acquired, resize, render update, detach, destroy, and a second acquire return MLN_STATUS_INVALID_STATE.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when session is null or not live, out_frame is null, or out_frame->size is too small.
• MLN_STATUS_INVALID_STATE when the session is detached, no rendered frame is available, or a texture frame is already acquired.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
• MLN_STATUS_UNSUPPORTED when session cannot expose a Metal texture frame.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_metal_owned_texture_attach()

mln_status mln_metal_owned_texture_attach	(	mln_map *	map,
		const mln_metal_owned_texture_descriptor *	descriptor,
		mln_render_session **	out_session )

Attaches a Metal texture render target owned by the session to a map.

The map may have at most one live render session. The session and every texture-session call are owner-thread affine to the map owner thread. The session renders into a session-owned texture created on descriptor->context.device. On success, *out_session receives a handle the caller destroys with mln_render_session_destroy().

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live, descriptor is null or invalid, out_session is null, or *out_session is not null.
• MLN_STATUS_INVALID_STATE when the map already has a render session.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_UNSUPPORTED when Metal texture sessions are not supported by this build.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

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

mln_status mln_metal_owned_texture_release_frame	(	mln_render_session *	session,
		const mln_metal_owned_texture_frame *	frame )

Releases a Metal texture frame acquired from a session-owned texture target.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when session is null or not live, frame is null, frame->size is too small, or frame identity does not match the acquired frame.
• MLN_STATUS_INVALID_STATE when no texture frame is currently acquired.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
• MLN_STATUS_UNSUPPORTED when session cannot release a Metal texture frame.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_opengl_borrowed_texture_attach()

mln_status mln_opengl_borrowed_texture_attach	(	mln_map *	map,
		const mln_opengl_borrowed_texture_descriptor *	descriptor,
		mln_render_session **	out_session )

Attaches an OpenGL caller-owned texture render target to a map.

The map may have at most one live render session. The session and every texture-session call are owner-thread affine to the map owner thread. The session renders into descriptor->texture. The caller owns the texture, keeps it valid until detach or destroy, and synchronizes any use outside this session. On success, *out_session receives a handle the caller destroys with mln_render_session_destroy().

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live, descriptor is null or invalid, out_session is null, or *out_session is not null.
• MLN_STATUS_INVALID_STATE when the map already has a render session.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_UNSUPPORTED when OpenGL borrowed texture sessions are not supported by this build.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

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

mln_status mln_opengl_owned_texture_acquire_frame	(	mln_render_session *	session,
		mln_opengl_owned_texture_frame *	out_frame )

Acquires the most recently rendered OpenGL texture frame.

Use this function with sessions created by mln_opengl_owned_texture_attach().

The returned texture object is borrowed and remains valid only until mln_opengl_owned_texture_release_frame() is called for the same frame. While acquired, resize, render update, detach, destroy, and a second acquire return MLN_STATUS_INVALID_STATE.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when session is null or not live, out_frame is null, or out_frame->size is too small.
• MLN_STATUS_INVALID_STATE when the session is detached, no rendered frame is available, or a texture frame is already acquired.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
• MLN_STATUS_UNSUPPORTED when session cannot expose an OpenGL texture frame.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_opengl_owned_texture_attach()

mln_status mln_opengl_owned_texture_attach	(	mln_map *	map,
		const mln_opengl_owned_texture_descriptor *	descriptor,
		mln_render_session **	out_session )

Attaches an OpenGL texture render target owned by the session to a map.

The map may have at most one live render session. The session and every texture-session call are owner-thread affine to the map owner thread. The session creates an OpenGL texture in a context that shares objects with descriptor->context. Host sampling may use the acquired texture from a context in the same share group after acquire succeeds and before release. On success, *out_session receives a handle the caller destroys with mln_render_session_destroy().

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live, descriptor is null or invalid, out_session is null, or *out_session is not null.
• MLN_STATUS_INVALID_STATE when the map already has a render session.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_UNSUPPORTED when OpenGL texture sessions are not supported by this build.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

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

mln_status mln_opengl_owned_texture_release_frame	(	mln_render_session *	session,
		const mln_opengl_owned_texture_frame *	frame )

Releases an OpenGL texture frame acquired from a session-owned texture target.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when session is null or not live, frame is null, frame->size is too small, or frame identity does not match the acquired frame.
• MLN_STATUS_INVALID_STATE when no texture frame is currently acquired.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
• MLN_STATUS_UNSUPPORTED when session cannot release an OpenGL texture frame.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_texture_image_info_default()

mln_texture_image_info mln_texture_image_info_default

(

void

)

Returns texture image info defaults for this C API version.

mln_texture_read_premultiplied_rgba8()

mln_status mln_texture_read_premultiplied_rgba8	(	mln_render_session *	session,
		uint8_t *	out_data,
		size_t	out_data_capacity,
		mln_texture_image_info *	out_info )

Reads the most recently rendered session-owned texture frame into caller-owned storage.

The copied image is premultiplied RGBA8 in physical pixels. The function fills out_info with the required byte length and image layout metadata. When out_data is null or out_data_capacity is too small, out_info is still filled and the function returns MLN_STATUS_INVALID_ARGUMENT.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when session is null or not live, out_info is null, out_info->size is too small, out_data is null, or out_data_capacity is too small.
• MLN_STATUS_INVALID_STATE when no rendered frame is available, the session is detached, a frame is currently acquired, or readback produces no image.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
• MLN_STATUS_UNSUPPORTED when session is not a texture session or when the texture session uses a caller-owned target.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_vulkan_borrowed_texture_attach()

mln_status mln_vulkan_borrowed_texture_attach	(	mln_map *	map,
		const mln_vulkan_borrowed_texture_descriptor *	descriptor,
		mln_render_session **	out_session )

Attaches a Vulkan caller-owned texture render target to a map.

The map may have at most one live render session. The session and every texture-session call are owner-thread affine to the map owner thread. The session renders into descriptor->image through descriptor->image_view. The caller owns the image and view, keeps them valid until detach or destroy, and handles queue-family ownership and synchronization outside this session. On success, *out_session receives a handle the caller destroys with mln_render_session_destroy().

Before each mln_render_session_render_update(), make the image available on descriptor->context.graphics_queue in descriptor->initial_layout and keep it out of concurrent use. The session submits rendering on that queue, waits for the submitted work to finish, and leaves the image in descriptor->final_layout before mln_render_session_render_update() returns.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live, descriptor is null or invalid, out_session is null, or *out_session is not null.
• MLN_STATUS_INVALID_STATE when the map already has a render session.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_UNSUPPORTED when Vulkan borrowed texture sessions are not supported by this build.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

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

mln_status mln_vulkan_owned_texture_acquire_frame	(	mln_render_session *	session,
		mln_vulkan_owned_texture_frame *	out_frame )

Acquires the most recently rendered Vulkan texture frame.

Use this function with sessions created by mln_vulkan_owned_texture_attach().

The returned image, image view, and device pointers are borrowed and remain valid only until mln_vulkan_owned_texture_release_frame() is called for the same frame. While acquired, resize, render update, detach, destroy, and a second acquire return MLN_STATUS_INVALID_STATE.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when session is null or not live, out_frame is null, or out_frame->size is too small.
• MLN_STATUS_INVALID_STATE when the session is detached, no rendered frame is available, or a texture frame is already acquired.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
• MLN_STATUS_UNSUPPORTED when session cannot expose a Vulkan texture frame.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_vulkan_owned_texture_attach()

mln_status mln_vulkan_owned_texture_attach	(	mln_map *	map,
		const mln_vulkan_owned_texture_descriptor *	descriptor,
		mln_render_session **	out_session )

Attaches a Vulkan texture render target owned by the session to a map.

The map may have at most one live render session. The session and every texture-session call are owner-thread affine to the map owner thread. The session renders into a session-owned image created on descriptor->context.device. Vulkan handles are borrowed and must remain valid until detach or destroy. On success, *out_session receives a handle the caller destroys with mln_render_session_destroy().

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live, descriptor is null or invalid, out_session is null, or *out_session is not null.
• MLN_STATUS_INVALID_STATE when the map already has a render session.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_UNSUPPORTED when Vulkan texture sessions are not supported by this build.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

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

mln_status mln_vulkan_owned_texture_release_frame	(	mln_render_session *	session,
		const mln_vulkan_owned_texture_frame *	frame )

Releases a Vulkan texture frame acquired from a session-owned texture target.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when session is null or not live, frame is null, frame->size is too small, or frame identity does not match the acquired frame.
• MLN_STATUS_INVALID_STATE when no texture frame is currently acquired.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
• MLN_STATUS_UNSUPPORTED when session cannot release a Vulkan texture frame.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.