MapLibre Native C API
Public C ABI for the MapLibre Native wrapper.
Loading...
Searching...
No Matches
texture.h File Reference

Go to the source code of this file.

Data Structures

struct  mln_metal_borrowed_texture
struct  mln_metal_borrowed_texture_descriptor
struct  mln_metal_borrowed_texture_replacement
struct  mln_metal_texture_frame
struct  mln_vulkan_borrowed_texture
struct  mln_vulkan_borrowed_texture_descriptor
struct  mln_vulkan_borrowed_texture_replacement
struct  mln_vulkan_texture_frame
struct  mln_open_gl_borrowed_texture
struct  mln_open_gl_borrowed_texture_descriptor
struct  mln_open_gl_borrowed_texture_replacement
struct  mln_web_gpu_borrowed_texture
struct  mln_web_gpu_borrowed_texture_descriptor
struct  mln_web_gpu_borrowed_texture_replacement
struct  mln_web_gpu_texture_frame
struct  mln_open_gl_texture_frame
struct  mln_texture_image_info
struct  mln_texture_readback_result

Typedefs

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_borrowed_texture_replacement mln_metal_borrowed_texture_replacement
typedef struct mln_metal_texture_frame mln_metal_texture_frame
typedef struct mln_vulkan_borrowed_texture mln_vulkan_borrowed_texture
typedef enum mln_vulkan_image_owner mln_vulkan_image_owner
typedef struct mln_vulkan_borrowed_texture_descriptor mln_vulkan_borrowed_texture_descriptor
typedef struct mln_vulkan_borrowed_texture_replacement mln_vulkan_borrowed_texture_replacement
typedef struct mln_vulkan_texture_frame mln_vulkan_texture_frame
typedef struct mln_open_gl_borrowed_texture mln_open_gl_borrowed_texture
typedef struct mln_open_gl_borrowed_texture_descriptor mln_open_gl_borrowed_texture_descriptor
typedef struct mln_open_gl_borrowed_texture_replacement mln_open_gl_borrowed_texture_replacement
typedef struct mln_web_gpu_borrowed_texture mln_web_gpu_borrowed_texture
typedef struct mln_web_gpu_borrowed_texture_descriptor mln_web_gpu_borrowed_texture_descriptor
typedef struct mln_web_gpu_borrowed_texture_replacement mln_web_gpu_borrowed_texture_replacement
typedef struct mln_web_gpu_texture_frame mln_web_gpu_texture_frame
typedef struct mln_open_gl_texture_frame mln_open_gl_texture_frame
typedef struct mln_texture_image_info mln_texture_image_info
typedef struct mln_texture_readback_result mln_texture_readback_result

Enumerations

enum  mln_vulkan_image_owner : uint32_t { MLN_VULKAN_IMAGE_OWNER_GRAPHICS_QUEUE = 0U , MLN_VULKAN_IMAGE_OWNER_EXTERNAL = 1U , MLN_VULKAN_IMAGE_OWNER_FOREIGN = 2U }

Functions

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_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_open_gl_borrowed_texture (mln_map map, const mln_open_gl_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_web_gpu_borrowed_texture (mln_map map, const mln_web_gpu_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_replacement *replacement, 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_replacement *replacement, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_set_open_gl_borrowed_texture_target (mln_render_session session, const mln_open_gl_borrowed_texture_replacement *replacement, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_set_web_gpu_borrowed_texture_target (mln_render_session session, const mln_web_gpu_borrowed_texture_replacement *replacement, 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_open_gl_texture (mln_acquired_frame frame, mln_open_gl_texture_frame *out_frame, mln_diagnostic *out_diagnostic)
mln_status mln_acquired_frame_get_web_gpu_texture (mln_acquired_frame frame, mln_web_gpu_texture_frame *out_frame, mln_diagnostic *out_diagnostic)

Detailed Description

Render a map into a ring of textures that your renderer draws.

Typedef Documentation

◆ mln_metal_borrowed_texture

typedef struct mln_metal_borrowed_texture mln_metal_borrowed_texture

A Metal texture of a borrowed ring.

◆ mln_metal_borrowed_texture_descriptor

typedef struct mln_metal_borrowed_texture_descriptor mln_metal_borrowed_texture_descriptor

A ring of your Metal textures, for mln_map_attach_metal_borrowed_texture().

logical_size sets the map's size. physical_width and physical_height give the textures' size in pixels, which is usually logical_size times the map's scale factor. The textures must all have that size, one device, one pixel format, one sample, and MTLTextureUsageRenderTarget. The ring holds up to MLN_TEXTURE_RING_MAX_DEPTH distinct textures.

The session uses the textures until a replacement or release of the target completes, a detach or release of the session completes, or an abandon of it returns.

◆ mln_metal_borrowed_texture_replacement

typedef struct mln_metal_borrowed_texture_replacement mln_metal_borrowed_texture_replacement

New Metal textures for a borrowed ring, for mln_render_session_set_metal_borrowed_texture_target().

The members and the textures follow the rules of mln_metal_borrowed_texture_descriptor. The ring keeps its depth, device, and command queue, so give it as many textures as it attached with, on the same device.

◆ mln_metal_texture_frame

typedef struct mln_metal_texture_frame mln_metal_texture_frame

The Metal texture of an acquired frame.

◆ mln_open_gl_borrowed_texture

typedef struct mln_open_gl_borrowed_texture mln_open_gl_borrowed_texture

An OpenGL texture of a borrowed ring.

◆ mln_open_gl_borrowed_texture_descriptor

typedef struct mln_open_gl_borrowed_texture_descriptor mln_open_gl_borrowed_texture_descriptor

A ring of your OpenGL textures, for mln_map_attach_open_gl_borrowed_texture().

logical_size sets the map's size. physical_width and physical_height give the textures' size in pixels, which is usually logical_size times the map's scale factor. The context must use MLN_OPEN_GL_CONTEXT_OWNERSHIP_SHARED. Each texture must be in your context's share group, with storage of that size. The ring holds up to MLN_TEXTURE_RING_MAX_DEPTH distinct textures.

The session uses the textures until a replacement or release of the target completes, a detach or release of the session completes, or an abandon of it returns.

◆ mln_open_gl_borrowed_texture_replacement

typedef struct mln_open_gl_borrowed_texture_replacement mln_open_gl_borrowed_texture_replacement

New OpenGL textures for a borrowed ring, for mln_render_session_set_open_gl_borrowed_texture_target().

The members and the textures follow the rules of mln_open_gl_borrowed_texture_descriptor. The ring keeps its depth, context, and texture target, so give it as many textures as it attached with, in the same share group.

◆ mln_open_gl_texture_frame

typedef struct mln_open_gl_texture_frame mln_open_gl_texture_frame

The OpenGL texture of an acquired frame.

◆ mln_texture_image_info

typedef struct mln_texture_image_info mln_texture_image_info

The layout of the pixels that mln_render_session_read_texture() reads.

◆ mln_texture_readback_result

typedef struct mln_texture_readback_result mln_texture_readback_result

The pixels that mln_render_session_read_texture() reads.

◆ mln_vulkan_borrowed_texture

typedef struct mln_vulkan_borrowed_texture mln_vulkan_borrowed_texture

A Vulkan image of a borrowed ring.

◆ mln_vulkan_borrowed_texture_descriptor

typedef struct mln_vulkan_borrowed_texture_descriptor mln_vulkan_borrowed_texture_descriptor

A ring of your Vulkan images, for mln_map_attach_vulkan_borrowed_texture().

logical_size sets the map's size. physical_width and physical_height give the images' size in pixels, which is usually logical_size times the map's scale factor. Each image must have that size, format, and VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, and belong to the context's device. The ring holds up to MLN_TEXTURE_RING_MAX_DEPTH distinct images.

The session uses the images until a replacement or release of the target completes, a detach or release of the session completes, or an abandon of it returns.

◆ mln_vulkan_borrowed_texture_replacement

typedef struct mln_vulkan_borrowed_texture_replacement mln_vulkan_borrowed_texture_replacement

New Vulkan images for a borrowed ring, for mln_render_session_set_vulkan_borrowed_texture_target().

The members and the images follow the rules of mln_vulkan_borrowed_texture_descriptor. The ring keeps its depth, context, format, final_layout, and owner, so give it as many images as it attached with, in that format, on the same device.

◆ mln_vulkan_image_owner

The queue family that a borrowed image goes to after each frame.

With MLN_VULKAN_IMAGE_OWNER_EXTERNAL or MLN_VULKAN_IMAGE_OWNER_FOREIGN, acquire the image on your side before you read it. You don't need to release it back.

◆ mln_vulkan_texture_frame

typedef struct mln_vulkan_texture_frame mln_vulkan_texture_frame

The Vulkan image of an acquired frame.

◆ mln_web_gpu_borrowed_texture

typedef struct mln_web_gpu_borrowed_texture mln_web_gpu_borrowed_texture

A WebGPU texture of a borrowed ring.

◆ mln_web_gpu_borrowed_texture_descriptor

typedef struct mln_web_gpu_borrowed_texture_descriptor mln_web_gpu_borrowed_texture_descriptor

A ring of your WebGPU textures, for mln_map_attach_web_gpu_borrowed_texture().

logical_size sets the map's size. physical_width and physical_height give the textures' size in pixels, which is usually logical_size times the map's scale factor. Each texture must be 2D with that size, format, one layer, one mip level, one sample, and WGPUTextureUsage_RenderAttachment. The ring holds up to MLN_TEXTURE_RING_MAX_DEPTH distinct textures.

The session uses the textures until a replacement or release of the target completes, a detach or release of the session completes, or an abandon of it returns.

◆ mln_web_gpu_borrowed_texture_replacement

typedef struct mln_web_gpu_borrowed_texture_replacement mln_web_gpu_borrowed_texture_replacement

New WebGPU textures for a borrowed ring, for mln_render_session_set_web_gpu_borrowed_texture_target().

The members and the textures follow the rules of mln_web_gpu_borrowed_texture_descriptor. The ring keeps its depth, context, and format, so give it as many textures as it attached with, in that format, on the same device.

◆ mln_web_gpu_texture_frame

typedef struct mln_web_gpu_texture_frame mln_web_gpu_texture_frame

The WebGPU texture of an acquired frame.

Enumeration Type Documentation

◆ mln_vulkan_image_owner

enum mln_vulkan_image_owner : uint32_t

The queue family that a borrowed image goes to after each frame.

With MLN_VULKAN_IMAGE_OWNER_EXTERNAL or MLN_VULKAN_IMAGE_OWNER_FOREIGN, acquire the image on your side before you read it. You don't need to release it back.

Enumerator
MLN_VULKAN_IMAGE_OWNER_GRAPHICS_QUEUE 

The image stays with the queue family of graphics_queue_family_index.

MLN_VULKAN_IMAGE_OWNER_EXTERNAL 

Each frame releases the image to VK_QUEUE_FAMILY_EXTERNAL.

MLN_VULKAN_IMAGE_OWNER_FOREIGN 

Each frame releases the image to VK_QUEUE_FAMILY_FOREIGN_EXT.

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 )

Gets the Metal texture of an acquired frame.

Returns:

  • MLN_STATUS_TARGET_LOST when the session failed, or you detached, abandoned, or disposed it.

Lifetimes: The texture and device in out_frame stay valid until you release or discard the frame, or the session is abandoned or disposed. A view from mln_acquired_frame_view_begin() keeps them valid until mln_acquired_frame_view_end().

◆ mln_acquired_frame_get_open_gl_texture()

mln_status mln_acquired_frame_get_open_gl_texture ( mln_acquired_frame frame,
mln_open_gl_texture_frame * out_frame,
mln_diagnostic * out_diagnostic )

Gets the OpenGL texture of an acquired frame.

Returns:

  • MLN_STATUS_TARGET_LOST when the session failed, or you detached, abandoned, or disposed it.

Lifetimes: The texture in out_frame stays valid until you release or discard the frame, or the session is abandoned or disposed. A view from mln_acquired_frame_view_begin() keeps it valid until mln_acquired_frame_view_end().

◆ 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 )

Gets the Vulkan image of an acquired frame.

Returns:

  • MLN_STATUS_TARGET_LOST when the session failed, or you detached, abandoned, or disposed it.

Lifetimes: The image, view, and device in out_frame stay valid until you release or discard the frame, or the session is abandoned or disposed. A view from mln_acquired_frame_view_begin() keeps them valid until mln_acquired_frame_view_end().

◆ mln_acquired_frame_get_web_gpu_texture()

mln_status mln_acquired_frame_get_web_gpu_texture ( mln_acquired_frame frame,
mln_web_gpu_texture_frame * out_frame,
mln_diagnostic * out_diagnostic )

Gets the WebGPU texture of an acquired frame.

Returns:

  • MLN_STATUS_TARGET_LOST when the session failed, or you detached, abandoned, or disposed it.

Lifetimes: The texture, view, and device in out_frame stay valid until you release or discard the frame, or the session is abandoned or disposed. A view from mln_acquired_frame_view_begin() keeps them valid until mln_acquired_frame_view_end().

◆ 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 )

Creates a session that renders the map into a ring of your Metal textures.

Returns:

◆ mln_map_attach_open_gl_borrowed_texture()

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

Creates a session that renders the map into a ring of your OpenGL textures.

Returns:

◆ 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 )

Creates a session that renders the map into a ring of your Vulkan images.

Returns:

  • MLN_STATUS_UNSUPPORTED when mln_supported_render_backend_mask() lacks MLN_RENDER_BACKEND_FLAG_VULKAN, or when the target supports none of the producer_sync_kinds in options.

◆ mln_map_attach_web_gpu_borrowed_texture()

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

Creates a session that renders the map into a ring of your WebGPU textures.

Returns:

  • MLN_STATUS_UNSUPPORTED when mln_supported_render_backend_mask() lacks MLN_RENDER_BACKEND_FLAG_WEB_GPU, or when the target supports none of the producer_sync_kinds in options.

◆ 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 the pixels of the last frame that the session rendered.

Completes with:

  • MLN_STATUS_UNSUPPORTED when the session's capabilities lack MLN_RENDER_SESSION_CAPABILITY_READBACK.
  • MLN_STATUS_INVALID_STATE when the session hasn't rendered a frame since it attached, resized, or changed its target.

◆ 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_replacement * replacement,
const mln_completion * completion,
mln_diagnostic * out_diagnostic )

Replaces the Metal textures that a borrowed ring renders into.

Use it to resize the ring, or to give the session textures again after mln_render_session_release_target(). Release every acquired frame first. Once the replacement completes, the session no longer uses the old textures.

Completes with:

  • MLN_STATUS_UNSUPPORTED when the new textures have a different pixel format than the old ones. Attach a new session to change it.

◆ mln_render_session_set_open_gl_borrowed_texture_target()

mln_status mln_render_session_set_open_gl_borrowed_texture_target ( mln_render_session session,
const mln_open_gl_borrowed_texture_replacement * replacement,
const mln_completion * completion,
mln_diagnostic * out_diagnostic )

Replaces the OpenGL textures that a borrowed ring renders into.

Use it to resize the ring, or to give the session textures again after mln_render_session_release_target(). Release every acquired frame first. Once the replacement completes, the session no longer uses the old textures.

◆ 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_replacement * replacement,
const mln_completion * completion,
mln_diagnostic * out_diagnostic )

Replaces the Vulkan images that a borrowed ring renders into.

Use it to resize the ring, or to give the session images again after mln_render_session_release_target(). Release every acquired frame first. Once the replacement completes, the session no longer uses the old images.

◆ mln_render_session_set_web_gpu_borrowed_texture_target()

mln_status mln_render_session_set_web_gpu_borrowed_texture_target ( mln_render_session session,
const mln_web_gpu_borrowed_texture_replacement * replacement,
const mln_completion * completion,
mln_diagnostic * out_diagnostic )

Replaces the WebGPU textures that a borrowed ring renders into.

Use it to resize the ring, or to give the session textures again after mln_render_session_release_target(). Release every acquired frame first. Once the replacement completes, the session no longer uses the old textures.