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

Go to the source code of this file.

Data Structures

struct  mln_queue_lock
struct  mln_render_session_attach_options
struct  mln_render_session_capabilities
struct  mln_gpu_sync
struct  mln_metal_context_descriptor
struct  mln_vulkan_context_descriptor
struct  mln_web_gpu_context_descriptor
struct  mln_wgl_context_descriptor
struct  mln_egl_context_descriptor
struct  mln_web_gl_context_descriptor
union  mln_open_gl_context_descriptor_data
struct  mln_open_gl_context_descriptor

Macros

#define MLN_VULKAN_NON_DISPATCHABLE_HANDLE_NULL   UINT64_C(0)
#define MLN_TEXTURE_RING_MAX_DEPTH   8u

Typedefs

typedef uint64_t mln_vulkan_non_dispatchable_handle
typedef enum mln_render_driver_kind mln_render_driver_kind
typedef enum mln_render_session_capability_flag mln_render_session_capability_flag
typedef uint32_t mln_render_session_capability_flags
typedef void(*) mln_queue_lock_callback(void *user_data)
typedef struct mln_queue_lock mln_queue_lock
typedef enum mln_gpu_sync_kind mln_gpu_sync_kind
typedef enum mln_gpu_sync_kind_flag mln_gpu_sync_kind_flag
typedef uint32_t mln_gpu_sync_kind_flags
typedef struct mln_render_session_attach_options mln_render_session_attach_options
typedef struct mln_render_session_capabilities mln_render_session_capabilities
typedef struct mln_gpu_sync mln_gpu_sync
typedef struct mln_metal_context_descriptor mln_metal_context_descriptor
typedef struct mln_vulkan_context_descriptor mln_vulkan_context_descriptor
typedef struct mln_web_gpu_context_descriptor mln_web_gpu_context_descriptor
typedef enum mln_open_gl_context_provider_flag mln_open_gl_context_provider_flag
typedef uint32_t mln_open_gl_context_provider_flags
typedef enum mln_open_gl_context_platform mln_open_gl_context_platform
typedef enum mln_open_gl_context_ownership mln_open_gl_context_ownership
typedef enum mln_open_gl_client_api mln_open_gl_client_api
typedef struct mln_wgl_context_descriptor mln_wgl_context_descriptor
typedef struct mln_egl_context_descriptor mln_egl_context_descriptor
typedef enum mln_web_gl_context_kind mln_web_gl_context_kind
typedef struct mln_web_gl_context_descriptor mln_web_gl_context_descriptor
typedef union mln_open_gl_context_descriptor_data mln_open_gl_context_descriptor_data
typedef struct mln_open_gl_context_descriptor mln_open_gl_context_descriptor

Enumerations

enum  mln_render_driver_kind : uint32_t { MLN_RENDER_DRIVER_CORE_WORKER = 1U , MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD = 2U }
enum  mln_render_session_capability_flag : uint32_t { MLN_RENDER_SESSION_CAPABILITY_FRAME_ACQUISITION = 1U << 0U , MLN_RENDER_SESSION_CAPABILITY_READBACK = 1U << 1U , MLN_RENDER_SESSION_CAPABILITY_PRESENTATION = 1U << 2U }
enum  mln_gpu_sync_kind : uint32_t {
  MLN_GPU_SYNC_CPU_COMPLETE = 0U , MLN_GPU_SYNC_OPEN_GL_FENCE = 1U , MLN_GPU_SYNC_QUEUE_ORDER = 2U , MLN_GPU_SYNC_VULKAN_TIMELINE_SEMAPHORE = 3U ,
  MLN_GPU_SYNC_SYNC_FD = 4U , MLN_GPU_SYNC_METAL_SHARED_EVENT = 5U , MLN_GPU_SYNC_D3D12_FENCE = 6U
}
enum  mln_gpu_sync_kind_flag : uint32_t {
  MLN_GPU_SYNC_KIND_FLAG_CPU_COMPLETE = 1U << 0U , MLN_GPU_SYNC_KIND_FLAG_OPEN_GL_FENCE = 1U << 1U , MLN_GPU_SYNC_KIND_FLAG_QUEUE_ORDER = 1U << 2U , MLN_GPU_SYNC_KIND_FLAG_VULKAN_TIMELINE_SEMAPHORE = 1U << 3U ,
  MLN_GPU_SYNC_KIND_FLAG_SYNC_FD = 1U << 4U , MLN_GPU_SYNC_KIND_FLAG_METAL_SHARED_EVENT = 1U << 5U , MLN_GPU_SYNC_KIND_FLAG_D3D12_FENCE = 1U << 6U
}
enum  mln_open_gl_context_provider_flag : uint32_t { MLN_OPEN_GL_CONTEXT_PROVIDER_FLAG_WGL = 1u << 0u , MLN_OPEN_GL_CONTEXT_PROVIDER_FLAG_EGL = 1u << 1u , MLN_OPEN_GL_CONTEXT_PROVIDER_FLAG_WEB_GL = 1u << 2u }
enum  mln_open_gl_context_platform : uint32_t { MLN_OPEN_GL_CONTEXT_PLATFORM_UNSPECIFIED = 0u , MLN_OPEN_GL_CONTEXT_PLATFORM_WGL = 1u , MLN_OPEN_GL_CONTEXT_PLATFORM_EGL = 2u , MLN_OPEN_GL_CONTEXT_PLATFORM_WEB_GL = 3u }
enum  mln_open_gl_context_ownership : uint32_t { MLN_OPEN_GL_CONTEXT_OWNERSHIP_SHARED = 0u , MLN_OPEN_GL_CONTEXT_OWNERSHIP_DEDICATED = 1u }
enum  mln_open_gl_client_api : uint32_t { MLN_OPEN_GL_CLIENT_API_UNSPECIFIED = 0u , MLN_OPEN_GL_CLIENT_API_GL = 1u , MLN_OPEN_GL_CLIENT_API_GLES = 2u }
enum  mln_web_gl_context_kind : uint32_t { MLN_WEB_GL_CONTEXT_EXISTING = 0U , MLN_WEB_GL_CONTEXT_TRANSFERRED_CANVAS = 1U }

Functions

mln_status mln_logical_extent_physical_size (mln_logical_extent extent, uint32_t *out_width, uint32_t *out_height, mln_diagnostic *out_diagnostic)
mln_open_gl_context_provider_flags mln_open_gl_supported_context_provider_mask (void)

Detailed Description

Options, capabilities, graphics contexts, and GPU synchronization that every render target shares.

Macro Definition Documentation

◆ MLN_TEXTURE_RING_MAX_DEPTH

#define MLN_TEXTURE_RING_MAX_DEPTH   8u

The most textures that a render session's texture ring can have.

◆ MLN_VULKAN_NON_DISPATCHABLE_HANDLE_NULL

#define MLN_VULKAN_NON_DISPATCHABLE_HANDLE_NULL   UINT64_C(0)

The null Vulkan non-dispatchable handle.

Typedef Documentation

◆ mln_egl_context_descriptor

typedef struct mln_egl_context_descriptor mln_egl_context_descriptor

The EGL objects that a render session makes its OpenGL context from.

◆ mln_gpu_sync

typedef struct mln_gpu_sync mln_gpu_sync

A point in GPU work that the other side waits for before using a texture.

◆ mln_gpu_sync_kind

How one side waits for the other's GPU work on a shared texture.

A sync file descriptor or an OpenGL fence signals once, so when mln_acquired_frame_release() succeeds, the session takes the one you pass. A Vulkan timeline semaphore, Metal shared event, or D3D12 fence counts up with each frame, so the one you pass stays yours. Keep it valid until a detach or release of the session completes.

◆ mln_gpu_sync_kind_flag

A GPU sync kind, as a bit in a set.

◆ mln_gpu_sync_kind_flags

typedef uint32_t mln_gpu_sync_kind_flags

A set of mln_gpu_sync_kind_flag bits.

◆ mln_metal_context_descriptor

typedef struct mln_metal_context_descriptor mln_metal_context_descriptor

The Metal device that a render session uses.

◆ mln_open_gl_client_api

The OpenGL API that a context renders with.

◆ mln_open_gl_context_descriptor

typedef struct mln_open_gl_context_descriptor mln_open_gl_context_descriptor

How a render session gets the OpenGL context that it renders with.

Keep the objects that it names alive until a detach or release of the session completes, or an abandon of it returns.

◆ mln_open_gl_context_descriptor_data

typedef union mln_open_gl_context_descriptor_data mln_open_gl_context_descriptor_data

The WGL, EGL, or WebGL part of an OpenGL context descriptor.

◆ mln_open_gl_context_ownership

Whether a render session's OpenGL context shares objects with yours.

◆ mln_open_gl_context_platform

The platform API that provides an OpenGL context.

◆ mln_open_gl_context_provider_flag

An OpenGL context platform, as a bit in a set.

◆ mln_open_gl_context_provider_flags

◆ mln_queue_lock

typedef struct mln_queue_lock mln_queue_lock

Your lock on a Vulkan queue that you and a render session both submit to.

The session holds the lock only while it submits or presents to the queue. Set both lock and unlock, or neither when you don't submit to the queue yourself.

◆ mln_queue_lock_callback

typedef void(*) mln_queue_lock_callback(void *user_data)

Locks or unlocks the Vulkan queue that you share with a render session.

Threads: It can run on a library thread, and it can't call the library.

◆ mln_render_driver_kind

The thread that runs a render session's graphics work.

◆ mln_render_session_attach_options

typedef struct mln_render_session_attach_options mln_render_session_attach_options

Options for attaching a render session to a map.

◆ mln_render_session_capabilities

typedef struct mln_render_session_capabilities mln_render_session_capabilities

What an attached render session supports.

◆ mln_render_session_capability_flag

Something that a render session can do.

◆ mln_render_session_capability_flags

◆ mln_vulkan_context_descriptor

typedef struct mln_vulkan_context_descriptor mln_vulkan_context_descriptor

The Vulkan device and queue that a render session uses.

Keep these objects alive until a detach or release of the session completes, or an abandon of it returns.

◆ mln_vulkan_non_dispatchable_handle

A Vulkan non-dispatchable handle, such as a VkImage, as an integer.

◆ mln_web_gl_context_descriptor

typedef struct mln_web_gl_context_descriptor mln_web_gl_context_descriptor

The WebGL context or canvas that a render session uses.

◆ mln_web_gl_context_kind

How a render session gets its WebGL context.

◆ mln_web_gpu_context_descriptor

typedef struct mln_web_gpu_context_descriptor mln_web_gpu_context_descriptor

The WebGPU device that a render session uses.

◆ mln_wgl_context_descriptor

typedef struct mln_wgl_context_descriptor mln_wgl_context_descriptor

The WGL objects that a render session makes its OpenGL context from.

Enumeration Type Documentation

◆ mln_gpu_sync_kind

enum mln_gpu_sync_kind : uint32_t

How one side waits for the other's GPU work on a shared texture.

A sync file descriptor or an OpenGL fence signals once, so when mln_acquired_frame_release() succeeds, the session takes the one you pass. A Vulkan timeline semaphore, Metal shared event, or D3D12 fence counts up with each frame, so the one you pass stays yours. Keep it valid until a detach or release of the session completes.

Enumerator
MLN_GPU_SYNC_CPU_COMPLETE 

The work has already finished, so there is nothing to wait for.

MLN_GPU_SYNC_OPEN_GL_FENCE 

handle is a GLsync in the session's share group.

MLN_GPU_SYNC_QUEUE_ORDER 

The work was submitted to the queue that both sides share, so work submitted to that queue later runs after it.

MLN_GPU_SYNC_VULKAN_TIMELINE_SEMAPHORE 

handle is a VkSemaphore. Wait until it reaches value.

MLN_GPU_SYNC_SYNC_FD 

handle is a sync file descriptor.

MLN_GPU_SYNC_METAL_SHARED_EVENT 

handle is an MTLSharedEvent. Wait until it reaches value.

MLN_GPU_SYNC_D3D12_FENCE 

handle is a shared Windows handle to an ID3D12Fence. Wait until it reaches value.

◆ mln_gpu_sync_kind_flag

enum mln_gpu_sync_kind_flag : uint32_t

A GPU sync kind, as a bit in a set.

Enumerator
MLN_GPU_SYNC_KIND_FLAG_CPU_COMPLETE 
MLN_GPU_SYNC_KIND_FLAG_OPEN_GL_FENCE 
MLN_GPU_SYNC_KIND_FLAG_QUEUE_ORDER 
MLN_GPU_SYNC_KIND_FLAG_VULKAN_TIMELINE_SEMAPHORE 
MLN_GPU_SYNC_KIND_FLAG_SYNC_FD 
MLN_GPU_SYNC_KIND_FLAG_METAL_SHARED_EVENT 
MLN_GPU_SYNC_KIND_FLAG_D3D12_FENCE 

◆ mln_open_gl_client_api

enum mln_open_gl_client_api : uint32_t

The OpenGL API that a context renders with.

Enumerator
MLN_OPEN_GL_CLIENT_API_UNSPECIFIED 
MLN_OPEN_GL_CLIENT_API_GL 
MLN_OPEN_GL_CLIENT_API_GLES 

◆ mln_open_gl_context_ownership

Whether a render session's OpenGL context shares objects with yours.

Enumerator
MLN_OPEN_GL_CONTEXT_OWNERSHIP_SHARED 

The session's context shares objects with your share_context.

MLN_OPEN_GL_CONTEXT_OWNERSHIP_DEDICATED 

The session's context shares objects with no other context.

◆ mln_open_gl_context_platform

The platform API that provides an OpenGL context.

Enumerator
MLN_OPEN_GL_CONTEXT_PLATFORM_UNSPECIFIED 
MLN_OPEN_GL_CONTEXT_PLATFORM_WGL 
MLN_OPEN_GL_CONTEXT_PLATFORM_EGL 
MLN_OPEN_GL_CONTEXT_PLATFORM_WEB_GL 

◆ mln_open_gl_context_provider_flag

An OpenGL context platform, as a bit in a set.

Enumerator
MLN_OPEN_GL_CONTEXT_PROVIDER_FLAG_WGL 
MLN_OPEN_GL_CONTEXT_PROVIDER_FLAG_EGL 
MLN_OPEN_GL_CONTEXT_PROVIDER_FLAG_WEB_GL 

◆ mln_render_driver_kind

enum mln_render_driver_kind : uint32_t

The thread that runs a render session's graphics work.

Enumerator
MLN_RENDER_DRIVER_CORE_WORKER 

A library thread.

MLN_RENDER_DRIVER_CALLER_GRAPHICS_THREAD 

Your thread, when it calls mln_render_session_service_driver_work().

◆ mln_render_session_capability_flag

Something that a render session can do.

Enumerator
MLN_RENDER_SESSION_CAPABILITY_FRAME_ACQUISITION 

mln_render_session_acquire_frame() can take the frames it renders.

MLN_RENDER_SESSION_CAPABILITY_READBACK 

mln_render_session_read_texture() can copy its texture to memory.

MLN_RENDER_SESSION_CAPABILITY_PRESENTATION 

It shows frames on a surface.

◆ mln_web_gl_context_kind

enum mln_web_gl_context_kind : uint32_t

How a render session gets its WebGL context.

Enumerator
MLN_WEB_GL_CONTEXT_EXISTING 

The session uses a context that you created with emscripten_webgl_create_context().

MLN_WEB_GL_CONTEXT_TRANSFERRED_CANVAS 

The library transfers the canvas that canvas_selector names to a worker and creates the context there.

Function Documentation

◆ mln_logical_extent_physical_size()

mln_status mln_logical_extent_physical_size ( mln_logical_extent extent,
uint32_t * out_width,
uint32_t * out_height,
mln_diagnostic * out_diagnostic )

Computes the size in pixels of a target with a logical size and scale factor.

◆ mln_open_gl_supported_context_provider_mask()

mln_open_gl_context_provider_flags mln_open_gl_supported_context_provider_mask ( void )

Reports the OpenGL context platforms that this build of the library has.