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

mln_render_session_resize() returns MLN_STATUS_UNSUPPORTED for this target. Follow a resized host by destroying the session, recreating the texture at the new extent, and attaching again; see mln_render_session_resize().

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 the render backend reports no rendered Metal texture, or 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. Each render completes before mln_render_session_render_update() returns, so the caller reads or samples the texture from any context in the share group of descriptor->context without adding synchronization of its own. On success, *out_session receives a handle the caller destroys with mln_render_session_destroy().

mln_render_session_resize() returns MLN_STATUS_UNSUPPORTED for this target. Follow a resized host by destroying the session, recreating the texture at the new extent, and attaching again; see mln_render_session_resize().

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.

Acquiring completes the session rendering for the frame, so the caller reads or samples the texture from any context in the share group of the context passed to mln_opengl_owned_texture_attach() without adding synchronization of its own.

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, or a frame is currently acquired.
• 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 readback produces no image or an image whose layout does not match the session, when the render backend reports no renderer backend, or 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.

mln_render_session_resize() returns MLN_STATUS_UNSUPPORTED for this target. Follow a resized host by destroying the session, recreating the image and view at the new extent, and attaching again; see mln_render_session_resize().

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.