Vulkan Foundation API¶

Vulkan instances, devices, queues, allocation, GPU contexts, and memory interop.

Status: advanced/unstable

This generated page lists exported C functions and their canonical public types classified by the v0.4 C API reference policy. Raw Python ctypes call forms are documented separately.

Use this advanced API for direct Vulkan ownership and interop below vklite.

Common workflows:

Functions: 96 Types: 26

Symbol Groups¶

Group	Functions	Types	Headers
Devices And Queues	28	8	4 headers
GPU Context	19	3	`include/datoviz/vk/gpu.h`, `include/datoviz/vk/gpu_ctx.h`
Instances	17	3	3 headers
Memory And Interop	32	4	`include/datoviz/vk/memory.h`, `include/datoviz/vk/memory_interop.h`
Shared Render Types	0	8	`include/datoviz/vk/enums.h`

Grouped function index

Devices And Queues

Function	Header
`dvz_device_allocator()`	`include/datoviz/vk/memory.h`
`dvz_device_command_pool()`	`include/datoviz/vk/device.h`
`dvz_device_config()`	`include/datoviz/vk/device.h`
`dvz_device_config_enable_canvas_extensions()`	`include/datoviz/vk/device.h`
`dvz_device_config_request_extension()`	`include/datoviz/vk/device.h`
`dvz_device_config_request_queue()`	`include/datoviz/vk/device.h`
`dvz_device_config_set_features10()`	`include/datoviz/vk/device.h`
`dvz_device_config_set_features11()`	`include/datoviz/vk/device.h`
`dvz_device_config_set_features12()`	`include/datoviz/vk/device.h`
`dvz_device_config_set_features13()`	`include/datoviz/vk/device.h`
`dvz_device_config_set_gpu_index()`	`include/datoviz/vk/device.h`
`dvz_device_create()`	`include/datoviz/vk/device.h`
`dvz_device_descriptor_pool()`	`include/datoviz/vk/device.h`
`dvz_device_destroy()`	`include/datoviz/vk/device.h`
`dvz_device_features10()`	`include/datoviz/vk/device.h`
`dvz_device_handle()`	`include/datoviz/vk/device.h`
`dvz_device_has_extension()`	`include/datoviz/vk/device.h`
`dvz_device_physical_device()`	`include/datoviz/vk/device.h`
`dvz_device_queue()`	`include/datoviz/vk/device.h`
`dvz_device_wait()`	`include/datoviz/vk/device.h`
`dvz_queue_family()`	`include/datoviz/vk/queues.h`
`dvz_queue_from_role()`	`include/datoviz/vk/queues.h`
`dvz_queue_handle()`	`include/datoviz/vk/queues.h`
`dvz_queue_index()`	`include/datoviz/vk/queues.h`
`dvz_queue_supports()`	`include/datoviz/vk/queues.h`
`dvz_queue_wait()`	`include/datoviz/vk/queues.h`
`dvz_queues()`	`include/datoviz/vk/queues.h`
`dvz_queues_show()`	`include/datoviz/vk/queues.h`

GPU Context

Function	Header
`dvz_compile_glsl()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_alloc()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_config()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_config_add_instance_extension()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_config_alloc()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_config_enable_canvas_extensions()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_config_features10()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_config_features12()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_config_features13()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_config_gpu()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_config_validation()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_destroy()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_device()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_error_count()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_gpu_index()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_gpu_info()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_instance()`	`include/datoviz/vk/gpu_ctx.h`
`dvz_gpu_ctx_queue()`	`include/datoviz/vk/gpu_ctx.h`

Instances

Function	Header
`dvz_instance_config()`	`include/datoviz/vk/instance.h`
`dvz_instance_config_request_extension()`	`include/datoviz/vk/instance.h`
`dvz_instance_config_request_layer()`	`include/datoviz/vk/instance.h`
`dvz_instance_create()`	`include/datoviz/vk/instance.h`
`dvz_instance_destroy()`	`include/datoviz/vk/instance.h`
`dvz_instance_error_count()`	`include/datoviz/vk/instance.h`
`dvz_instance_gpu_count()`	`include/datoviz/vk/gpu.h`
`dvz_instance_gpu_handle()`	`include/datoviz/vk/gpu.h`
`dvz_instance_gpu_info()`	`include/datoviz/vk/gpu.h`
`dvz_instance_gpu_queue_caps()`	`include/datoviz/vk/queues.h`
`dvz_instance_handle()`	`include/datoviz/vk/instance.h`
`dvz_instance_has_extension()`	`include/datoviz/vk/instance.h`
`dvz_instance_has_layer()`	`include/datoviz/vk/instance.h`
`dvz_instance_probe_extensions()`	`include/datoviz/vk/instance.h`
`dvz_instance_probe_layers()`	`include/datoviz/vk/instance.h`
`dvz_instance_supported_extensions()`	`include/datoviz/vk/instance.h`
`dvz_instance_supported_layers()`	`include/datoviz/vk/instance.h`

Memory And Interop

Function	Header
`dvz_allocation_create()`	`include/datoviz/vk/memory.h`
`dvz_allocation_flags()`	`include/datoviz/vk/memory.h`
`dvz_allocation_flags_contains()`	`include/datoviz/vk/memory.h`
`dvz_allocation_free()`	`include/datoviz/vk/memory.h`
`dvz_allocation_mapped()`	`include/datoviz/vk/memory.h`
`dvz_allocation_memory()`	`include/datoviz/vk/memory_interop.h`
`dvz_allocation_set_flags()`	`include/datoviz/vk/memory.h`
`dvz_allocation_size()`	`include/datoviz/vk/memory.h`
`dvz_allocator_buffer()`	`include/datoviz/vk/memory.h`
`dvz_allocator_copy_from()`	`include/datoviz/vk/memory.h`
`dvz_allocator_copy_to()`	`include/datoviz/vk/memory.h`
`dvz_allocator_create()`	`include/datoviz/vk/memory.h`
`dvz_allocator_destroy()`	`include/datoviz/vk/memory.h`
`dvz_allocator_destroy_buffer()`	`include/datoviz/vk/memory.h`
`dvz_allocator_destroy_image()`	`include/datoviz/vk/memory.h`
`dvz_allocator_device()`	`include/datoviz/vk/memory.h`
`dvz_allocator_export()`	`include/datoviz/vk/memory_interop.h`
`dvz_allocator_external()`	`include/datoviz/vk/memory_interop.h`
`dvz_allocator_flush()`	`include/datoviz/vk/memory.h`
`dvz_allocator_free()`	`include/datoviz/vk/memory.h`
`dvz_allocator_image()`	`include/datoviz/vk/memory.h`
`dvz_allocator_import_buffer()`	`include/datoviz/vk/memory_interop.h`
`dvz_allocator_import_image()`	`include/datoviz/vk/memory_interop.h`
`dvz_allocator_invalidate()`	`include/datoviz/vk/memory.h`
`dvz_allocator_map()`	`include/datoviz/vk/memory.h`
`dvz_allocator_unmap()`	`include/datoviz/vk/memory.h`
`dvz_interop_buffer_export()`	`include/datoviz/vk/memory_interop.h`
`dvz_interop_buffer_export_config()`	`include/datoviz/vk/memory_interop.h`
`dvz_interop_buffer_export_from_buffer()`	`include/datoviz/vk/memory_interop.h`
`dvz_interop_buffer_wait_timeline()`	`include/datoviz/vk/memory_interop.h`
`dvz_interop_gpu_ctx()`	`include/datoviz/vk/memory_interop.h`
`dvz_interop_gpu_ctx_ex()`	`include/datoviz/vk/memory_interop.h`

Devices And Queues¶

Functions

`dvz_device_allocator()`¶

Create an allocator for the stable low-level Datoviz allocation path.

This is the main allocator entry point for regular buffer/image allocation workflows. External-memory interop remains a narrower advanced path documented in datoviz/vk/memory_interop.h. Reinitializing a live allocator requires dvz_allocator_destroy() first.

int dvz_device_allocator(
    DvzDevice * device,
    VkExternalMemoryHandleTypeFlagsKHR export_handle_type,
    DvzVma * allocator
);

Field	Type	Description
return	`int`	0 on success, non-zero on Vulkan or allocator failure
`device`	`DvzDevice` *	the device
`export_handle_type`	`VkExternalMemoryHandleTypeFlagsKHR`	if exporting created allocations, the external memory handle type
`allocator`	`DvzVma` *

Declared in include/datoviz/vk/memory.h:184.

`dvz_device_command_pool()`¶

Return the command pool associated to a queue family index.

VkCommandPool dvz_device_command_pool(
    DvzDevice * device,
    uint32_t queue_family
);

Field	Type	Description
return	`VkCommandPool`	borrowed command-pool handle for `queue_family`, or `VK_NULL_HANDLE` if unavailable
`device`	`DvzDevice` *	the device
`queue_family`	`uint32_t`	the queue family index

Declared in include/datoviz/vk/device.h:236.

`dvz_device_config()`¶

Return default configuration values for creating a device.

DvzDeviceConfig dvz_device_config(
    DvzInstance * instance
);

Field	Type	Description
return	`DvzDeviceConfig`	the default device configuration
`instance`	`DvzInstance` *	the source instance

Related: dvz_device_create().

Declared in include/datoviz/vk/device.h:84.

`dvz_device_config_enable_canvas_extensions()`¶

Toggle canvas extension requests on a device configuration.

void dvz_device_config_enable_canvas_extensions(
    DvzDeviceConfig * cfg,
    _Bool enabled
);

Field	Type	Description
`cfg`	`DvzDeviceConfig` *	the device configuration
`enabled`	`_Bool`	whether canvas extensions should be requested

Declared in include/datoviz/vk/device.h:130.

`dvz_device_config_request_extension()`¶

Add an extension request to a device configuration.

_Bool dvz_device_config_request_extension(
    DvzDeviceConfig * cfg,
    const char * extension
);

Field	Type	Description
return	`_Bool`	whether the extension was added
`cfg`	`DvzDeviceConfig` *	the device configuration
`extension`	`const` `char` *	the extension name

Declared in include/datoviz/vk/device.h:120.

`dvz_device_config_request_queue()`¶

Add a queue request to a device configuration.

_Bool dvz_device_config_request_queue(
    DvzDeviceConfig * cfg,
    uint32_t family,
    uint32_t count
);

Field	Type	Description
return	`_Bool`	whether the request was added
`cfg`	`DvzDeviceConfig` *	the device configuration
`family`	`uint32_t`	the queue family index
`count`	`uint32_t`	the number of queues requested

Declared in include/datoviz/vk/device.h:108.

`dvz_device_config_set_features10()`¶

Copy Vulkan 1.0 features into a device configuration.

void dvz_device_config_set_features10(
    DvzDeviceConfig * cfg,
    const VkPhysicalDeviceFeatures * features
);

Field	Type	Description
`cfg`	`DvzDeviceConfig` *	the device configuration
`features`	`const` `VkPhysicalDeviceFeatures` *	the Vulkan 1.0 feature struct

Declared in include/datoviz/vk/device.h:141.

`dvz_device_config_set_features11()`¶

Copy Vulkan 1.1 features into a device configuration.

void dvz_device_config_set_features11(
    DvzDeviceConfig * cfg,
    const VkPhysicalDeviceVulkan11Features * features
);

Field	Type	Description
`cfg`	`DvzDeviceConfig` *	the device configuration
`features`	`const` `VkPhysicalDeviceVulkan11Features` *	the Vulkan 1.1 feature struct

Declared in include/datoviz/vk/device.h:151.

`dvz_device_config_set_features12()`¶

Copy Vulkan 1.2 features into a device configuration.

void dvz_device_config_set_features12(
    DvzDeviceConfig * cfg,
    const VkPhysicalDeviceVulkan12Features * features
);

Field	Type	Description
`cfg`	`DvzDeviceConfig` *	the device configuration
`features`	`const` `VkPhysicalDeviceVulkan12Features` *	the Vulkan 1.2 feature struct

Declared in include/datoviz/vk/device.h:162.

`dvz_device_config_set_features13()`¶

Copy Vulkan 1.3 features into a device configuration.

void dvz_device_config_set_features13(
    DvzDeviceConfig * cfg,
    const VkPhysicalDeviceVulkan13Features * features
);

Field	Type	Description
`cfg`	`DvzDeviceConfig` *	the device configuration
`features`	`const` `VkPhysicalDeviceVulkan13Features` *	the Vulkan 1.3 feature struct

Declared in include/datoviz/vk/device.h:173.

`dvz_device_config_set_gpu_index()`¶

Select the GPU index used for device creation.

_Bool dvz_device_config_set_gpu_index(
    DvzDeviceConfig * cfg,
    uint32_t gpu_index
);

Field	Type	Description
return	`_Bool`	whether the index was stored successfully
`cfg`	`DvzDeviceConfig` *	the device configuration
`gpu_index`	`uint32_t`	the selected GPU index in the instance

Declared in include/datoviz/vk/device.h:95.

`dvz_device_create()`¶

Create and initialize a heap-allocated device from a configuration.

DvzDevice * dvz_device_create(
    const DvzDeviceConfig * cfg
);

Field	Type	Description
return	`DvzDevice` *	a created device on success, `NULL` on failure
`cfg`	`const` `DvzDeviceConfig` *	the device configuration

Related: dvz_device_destroy().

Declared in include/datoviz/vk/device.h:184.

`dvz_device_descriptor_pool()`¶

Return the descriptor pool associated to a device.

VkDescriptorPool dvz_device_descriptor_pool(
    DvzDevice * device
);

Field	Type	Description
return	`VkDescriptorPool`	borrowed descriptor-pool handle, or `VK_NULL_HANDLE` if unavailable
`device`	`DvzDevice` *	the device

Declared in include/datoviz/vk/device.h:246.

`dvz_device_destroy()`¶

Destroy a device.

void dvz_device_destroy(
    DvzDevice * device
);

Field	Type	Description
`device`	`DvzDevice` *	live logical device to destroy; NULL is ignored

Related: dvz_device_create().

Declared in include/datoviz/vk/device.h:264.

`dvz_device_features10()`¶

Return the Vulkan 1.0 feature set enabled on this device.

const VkPhysicalDeviceFeatures * dvz_device_features10(
    DvzDevice * device
);

Field	Type	Description
return	`const` `VkPhysicalDeviceFeatures` *	borrowed immutable enabled-feature storage, valid until device destruction
`device`	`DvzDevice` *	the device

Declared in include/datoviz/vk/device.h:214.

`dvz_device_handle()`¶

Get the Vulkan VkDevice handle of a device.

VkDevice dvz_device_handle(
    DvzDevice * device
);

Field	Type	Description
return	`VkDevice`	borrowed Vulkan logical-device handle, or `VK_NULL_HANDLE` when unavailable
`device`	`DvzDevice` *	the device

Declared in include/datoviz/vk/device.h:194.

`dvz_device_has_extension()`¶

Return whether a device was created with support for a given extension or not.

_Bool dvz_device_has_extension(
    DvzDevice * device,
    const char * extension
);

Field	Type	Description
return	`_Bool`	whether the device has support for the extension
`device`	`DvzDevice` *	the device
`extension`	`const` `char` *	the extension name

Declared in include/datoviz/vk/device.h:275.

`dvz_device_physical_device()`¶

Return the Vulkan physical device used by this logical device.

VkPhysicalDevice dvz_device_physical_device(
    DvzDevice * device
);

Field	Type	Description
return	`VkPhysicalDevice`	borrowed Vulkan physical-device handle, or `VK_NULL_HANDLE` when unavailable
`device`	`DvzDevice` *	the device

Declared in include/datoviz/vk/device.h:204.

`dvz_device_queue()`¶

Retrieve a queue from a role.

DvzQueue * dvz_device_queue(
    DvzDevice * device,
    DvzQueueRole role
);

Field	Type	Description
return	`DvzQueue` *	borrowed queue wrapper owned by the device, or NULL when the role is unavailable
`device`	`DvzDevice` *	the device
`role`	`DvzQueueRole`	the role

Declared in include/datoviz/vk/device.h:225.

`dvz_device_wait()`¶

Wait until the device is ready. Inefficient.

void dvz_device_wait(
    DvzDevice * device
);

Field	Type	Description
`device`	`DvzDevice` *	the device

Declared in include/datoviz/vk/device.h:255.

`dvz_queue_family()`¶

Return the queue family of a queue.

uint32_t dvz_queue_family(
    DvzQueue * queue
);

Field	Type	Description
return	`uint32_t`	the queue family index
`queue`	`DvzQueue` *	the queue

Declared in include/datoviz/vk/queues.h:191.

`dvz_queue_from_role()`¶

Get a queue for a role from a queue-selection plan or device-owned queue table.

The returned queue may be a dedicated queue for the role, or the main queue when that queue intentionally satisfies the requested role.

DvzQueue * dvz_queue_from_role(
    DvzQueues * queues,
    DvzQueueRole role
);

Field	Type	Description
return	`DvzQueue` *	the queue
`queues`	`DvzQueues` *	the queues
`role`	`DvzQueueRole`	the role

Declared in include/datoviz/vk/queues.h:171.

`dvz_queue_handle()`¶

Return the Vulkan handle of a queue.

VkQueue dvz_queue_handle(
    DvzQueue * queue
);

Field	Type	Description
return	`VkQueue`	borrowed Vulkan queue handle, or `VK_NULL_HANDLE` when unavailable
`queue`	`DvzQueue` *	the queue

Declared in include/datoviz/vk/queues.h:201.

`dvz_queue_index()`¶

Return the queue index of a queue.

uint32_t dvz_queue_index(
    DvzQueue * queue
);

Field	Type	Description
return	`uint32_t`	the queue index
`queue`	`DvzQueue` *	the queue

Declared in include/datoviz/vk/queues.h:181.

`dvz_queue_supports()`¶

Returns whether a queue supports a given role.

_Bool dvz_queue_supports(
    DvzQueue * queue,
    DvzQueueRole role
);

Field	Type	Description
return	`_Bool`	true if the queue advertises the requested role
`queue`	`DvzQueue` *	a queue
`role`	`DvzQueueRole`	a queue role

Declared in include/datoviz/vk/queues.h:221.

`dvz_queue_wait()`¶

Wait for a queue to be idle. Inefficient.

void dvz_queue_wait(
    DvzQueue * queue
);

Field	Type	Description
`queue`	`DvzQueue` *	the queue

Declared in include/datoviz/vk/queues.h:210.

`dvz_queues()`¶

Choose a logical-device queue plan from a capability snapshot.

This function is part of the intentional public low-level queue-planning API. It does not create Vulkan queues by itself; it selects family/role assignments that higher-level device setup then requests explicitly.

void dvz_queues(
    DvzQueueCaps * qc,
    DvzQueues * queues
);

Field	Type	Description
`qc`	`DvzQueueCaps` *	the queue caps
`queues`	`DvzQueues` *

Declared in include/datoviz/vk/queues.h:148.

`dvz_queues_show()`¶

Show the queues.

void dvz_queues_show(
    DvzQueues * queues
);

Field	Type	Description
`queues`	`DvzQueues` *	the queues

Declared in include/datoviz/vk/queues.h:157.

Types

DvzDefaultQueue · enum

enum DvzDefaultQueue {
    DVZ_DEFAULT_QUEUE_TRANSFER = 0,
    DVZ_DEFAULT_QUEUE_COMPUTE = 1,
    DVZ_DEFAULT_QUEUE_RENDER = 2,
    DVZ_DEFAULT_QUEUE_PRESENT = 3,
    DVZ_DEFAULT_QUEUE_COUNT = 4,
};

Declared in include/datoviz/vk/enums.h:48.

DvzDevice · typedef

typedef struct DvzDevice DvzDevice;

Declared in include/datoviz/vk/device.h.

DvzDeviceConfig · record

struct DvzDeviceConfig {
    uint32_t struct_size;
    uint32_t flags;
    DvzInstance * instance;
    uint32_t gpu_index;
    _Bool enable_canvas_extensions;
    uint32_t queue_request_count;
    DvzDeviceQueueRequest[8] queue_requests;
    uint32_t extension_count;
    const char *[256] extensions;
    _Bool has_features10;
    _Bool has_features11;
    _Bool has_features12;
    _Bool has_features13;
    VkPhysicalDeviceFeatures features10;
    VkPhysicalDeviceVulkan11Features features11;
    VkPhysicalDeviceVulkan12Features features12;
    VkPhysicalDeviceVulkan13Features features13;
};

Declared in include/datoviz/vk/device.h:51.

DvzDeviceQueueRequest · record

struct DvzDeviceQueueRequest {
    uint32_t family;
    uint32_t count;
};

Declared in include/datoviz/vk/device.h:43.

DvzQueue · record

struct DvzQueue {
    uint32_t family_idx;
    uint32_t queue_idx;
    VkQueue vk_queue;
    VkQueueFlags flags;
    _Bool is_main;
    _Bool is_set;
};

Declared in include/datoviz/vk/queues.h:89.

DvzQueueCaps · record

struct DvzQueueCaps {
    uint32_t family_count;
    VkQueueFlags[8] flags;
    uint32_t[8] queue_count;
};

Declared in include/datoviz/vk/queues.h:74.

DvzQueueRole · enum

enum DvzQueueRole {
    DVZ_QUEUE_MAIN = 0,
    DVZ_QUEUE_COMPUTE = 1,
    DVZ_QUEUE_TRANSFER = 2,
    DVZ_QUEUE_VIDEO_ENCODE = 3,
    DVZ_QUEUE_VIDEO_DECODE = 4,
    DVZ_QUEUE_COUNT = 5,
};

Declared in include/datoviz/vk/queues.h:40.

DvzQueues · record

struct DvzQueues {
    uint32_t queue_count;
    DvzQueue[5] queues;
};

Declared in include/datoviz/vk/queues.h:107.

GPU Context¶

Functions

`dvz_compile_glsl()`¶

Compile a GLSL source string to SPIR-V using shaderc (lazy-loaded).

The returned buffer is heap-allocated and must be freed with dvz_memory_free(). Returns NULL if shaderc is unavailable or compilation fails.

uint32_t * dvz_compile_glsl(
    const char * stage,
    const char * glsl,
    uint64_t * out_size
);

Field	Type	Description
return	`uint32_t` *	heap-allocated SPIR-V words, or NULL on failure
`stage`	`const` `char` *	shader stage: "vertex", "fragment", or "compute"
`glsl`	`const` `char` *	null-terminated GLSL source string
`out_size`	`uint64_t` *	receives the byte size of the returned SPIR-V buffer

Declared in include/datoviz/vk/gpu_ctx.h:273.

`dvz_gpu_ctx()`¶

Create an owned GPU context from a configuration.

DvzGpuCtx * dvz_gpu_ctx(
    const DvzGpuCtxConfig * cfg
);

Field	Type	Description
return	`DvzGpuCtx` *	allocated GPU context, or NULL on failure
`cfg`	`const` `DvzGpuCtxConfig` *	the GPU-context configuration

Declared in include/datoviz/vk/gpu_ctx.h:173.

`dvz_gpu_ctx_alloc()`¶

Return the allocator owned by a GPU context.

DvzVma * dvz_gpu_ctx_alloc(
    DvzGpuCtx * ctx
);

Field	Type	Description
return	`DvzVma` *	borrowed allocator
`ctx`	`DvzGpuCtx` *	the GPU context

Declared in include/datoviz/vk/gpu_ctx.h:224.

`dvz_gpu_ctx_config()`¶

Return the default GPU-context configuration.

DvzGpuCtxConfig dvz_gpu_ctx_config(void);

Field	Type	Description
return	`DvzGpuCtxConfig`	the default configuration

Declared in include/datoviz/vk/gpu_ctx.h:76.

`dvz_gpu_ctx_config_add_instance_extension()`¶

Request an additional Vulkan instance extension for a GPU-context configuration.

void dvz_gpu_ctx_config_add_instance_extension(
    DvzGpuCtxConfig * cfg,
    const char * extension
);

Field	Type	Description
`cfg`	`DvzGpuCtxConfig` *	the GPU-context configuration
`extension`	`const` `char` *	null-terminated extension name (must outlive the config)

Declared in include/datoviz/vk/gpu_ctx.h:151.

`dvz_gpu_ctx_config_alloc()`¶

Select the allocator external-memory export policy for a GPU-context configuration.

void dvz_gpu_ctx_config_alloc(
    DvzGpuCtxConfig * cfg,
    VkExternalMemoryHandleTypeFlagsKHR export_handle_type
);

Field	Type	Description
`cfg`	`DvzGpuCtxConfig` *	the GPU-context configuration
`export_handle_type`	`VkExternalMemoryHandleTypeFlagsKHR`	external memory export flags

Declared in include/datoviz/vk/gpu_ctx.h:108.

`dvz_gpu_ctx_config_enable_canvas_extensions()`¶

Enable or disable canvas (swapchain/surface) device extensions for a GPU-context configuration.

Must be set before dvz_gpu_ctx() is called. Required when creating present canvases.

void dvz_gpu_ctx_config_enable_canvas_extensions(
    DvzGpuCtxConfig * cfg,
    _Bool enable
);

Field	Type	Description
`cfg`	`DvzGpuCtxConfig` *	the GPU-context configuration
`enable`	`_Bool`	whether canvas extensions should be enabled on the device

Declared in include/datoviz/vk/gpu_ctx.h:163.

`dvz_gpu_ctx_config_features10()`¶

Copy Vulkan 1.0 features into a GPU-context configuration.

void dvz_gpu_ctx_config_features10(
    DvzGpuCtxConfig * cfg,
    const VkPhysicalDeviceFeatures * features
);

Field	Type	Description
`cfg`	`DvzGpuCtxConfig` *	the GPU-context configuration
`features`	`const` `VkPhysicalDeviceFeatures` *	the Vulkan 1.0 feature struct

Declared in include/datoviz/vk/gpu_ctx.h:119.

`dvz_gpu_ctx_config_features12()`¶

Copy Vulkan 1.2 features into a GPU-context configuration.

void dvz_gpu_ctx_config_features12(
    DvzGpuCtxConfig * cfg,
    const VkPhysicalDeviceVulkan12Features * features
);

Field	Type	Description
`cfg`	`DvzGpuCtxConfig` *	the GPU-context configuration
`features`	`const` `VkPhysicalDeviceVulkan12Features` *	the Vulkan 1.2 feature struct

Declared in include/datoviz/vk/gpu_ctx.h:128.

`dvz_gpu_ctx_config_features13()`¶

Copy Vulkan 1.3 features into a GPU-context configuration.

void dvz_gpu_ctx_config_features13(
    DvzGpuCtxConfig * cfg,
    const VkPhysicalDeviceVulkan13Features * features
);

Field	Type	Description
`cfg`	`DvzGpuCtxConfig` *	the GPU-context configuration
`features`	`const` `VkPhysicalDeviceVulkan13Features` *	the Vulkan 1.3 feature struct

Declared in include/datoviz/vk/gpu_ctx.h:139.

`dvz_gpu_ctx_config_gpu()`¶

Select the GPU index to use for a GPU-context configuration.

void dvz_gpu_ctx_config_gpu(
    DvzGpuCtxConfig * cfg,
    uint32_t gpu_index
);

Field	Type	Description
`cfg`	`DvzGpuCtxConfig` *	the GPU-context configuration
`gpu_index`	`uint32_t`	the selected GPU index

Declared in include/datoviz/vk/gpu_ctx.h:97.

`dvz_gpu_ctx_config_validation()`¶

Toggle instance validation for a GPU-context configuration.

void dvz_gpu_ctx_config_validation(
    DvzGpuCtxConfig * cfg,
    _Bool enable_validation
);

Field	Type	Description
`cfg`	`DvzGpuCtxConfig` *	the GPU-context configuration
`enable_validation`	`_Bool`	whether validation should be enabled

Declared in include/datoviz/vk/gpu_ctx.h:87.

`dvz_gpu_ctx_destroy()`¶

Destroy a GPU context and all owned runtime objects.

void dvz_gpu_ctx_destroy(
    DvzGpuCtx * ctx
);

Field	Type	Description
`ctx`	`DvzGpuCtx` *	the GPU context

Declared in include/datoviz/vk/gpu_ctx.h:254.

`dvz_gpu_ctx_device()`¶

Return the device owned by a GPU context.

DvzDevice * dvz_gpu_ctx_device(
    DvzGpuCtx * ctx
);

Field	Type	Description
return	`DvzDevice` *	borrowed device
`ctx`	`DvzGpuCtx` *	the GPU context

Declared in include/datoviz/vk/gpu_ctx.h:214.

`dvz_gpu_ctx_error_count()`¶

Return the validation error count associated with a GPU context.

uint32_t dvz_gpu_ctx_error_count(
    DvzGpuCtx * ctx
);

Field	Type	Description
return	`uint32_t`	the validation error count
`ctx`	`DvzGpuCtx` *	the GPU context

Declared in include/datoviz/vk/gpu_ctx.h:245.

`dvz_gpu_ctx_gpu_index()`¶

Return the selected GPU index of a GPU context.

uint32_t dvz_gpu_ctx_gpu_index(
    DvzGpuCtx * ctx
);

Field	Type	Description
return	`uint32_t`	the selected GPU index, or UINT32_MAX when unavailable
`ctx`	`DvzGpuCtx` *	the GPU context

Declared in include/datoviz/vk/gpu_ctx.h:193.

`dvz_gpu_ctx_gpu_info()`¶

Return the selected GPU descriptor of a GPU context.

_Bool dvz_gpu_ctx_gpu_info(
    DvzGpuCtx * ctx,
    DvzGpuInfo * out_info
);

Field	Type	Description
return	`_Bool`	whether the descriptor could be retrieved
`ctx`	`DvzGpuCtx` *	the GPU context
`out_info`	`DvzGpuInfo` *

Declared in include/datoviz/vk/gpu_ctx.h:204.

`dvz_gpu_ctx_instance()`¶

Return the instance owned by a GPU context.

DvzInstance * dvz_gpu_ctx_instance(
    DvzGpuCtx * ctx
);

Field	Type	Description
return	`DvzInstance` *	borrowed instance
`ctx`	`DvzGpuCtx` *	the GPU context

Declared in include/datoviz/vk/gpu_ctx.h:183.

`dvz_gpu_ctx_queue()`¶

Return a queue owned by the GPU-context device.

DvzQueue * dvz_gpu_ctx_queue(
    DvzGpuCtx * ctx,
    DvzQueueRole role
);

Field	Type	Description
return	`DvzQueue` *	borrowed queue, or NULL when unavailable
`ctx`	`DvzGpuCtx` *	the GPU context
`role`	`DvzQueueRole`	the requested queue role

Declared in include/datoviz/vk/gpu_ctx.h:235.

Types

DvzGpuCtx · typedef

typedef struct DvzGpuCtx DvzGpuCtx;

Declared in include/datoviz/vk/gpu_ctx.h.

DvzGpuCtxConfig · record

struct DvzGpuCtxConfig {
    uint32_t struct_size;
    uint32_t flags;
    _Bool enable_validation;
    uint32_t gpu_index;
    VkExternalMemoryHandleTypeFlagsKHR export_handle_type;
    _Bool has_features10;
    _Bool has_features12;
    _Bool has_features13;
    VkPhysicalDeviceFeatures features10;
    VkPhysicalDeviceVulkan12Features features12;
    VkPhysicalDeviceVulkan13Features features13;
    uint32_t instance_extension_count;
    const char *[16] instance_extensions;
    _Bool enable_canvas_extensions;
};

Declared in include/datoviz/vk/gpu_ctx.h:45.

DvzGpuInfo · record

struct DvzGpuInfo {
    uint32_t index;
    char[256] name;
    VkPhysicalDeviceType device_type;
    uint32_t api_version;
    uint32_t driver_version;
    uint32_t vendor_id;
    uint32_t device_id;
    DvzQueueCaps queue_caps;
};

Declared in include/datoviz/vk/gpu.h:42.

Instances¶

Functions

`dvz_instance_config()`¶

Return default configuration values for creating an instance.

DvzInstanceConfig dvz_instance_config(void);

Field	Type	Description
return	`DvzInstanceConfig`	the default instance configuration

Related: dvz_instance_create().

Declared in include/datoviz/vk/instance.h:87.

`dvz_instance_config_request_extension()`¶

Add an instance extension request to a configuration.

_Bool dvz_instance_config_request_extension(
    DvzInstanceConfig * cfg,
    const char * extension
);

Field	Type	Description
return	`_Bool`	whether the extension was added to the request list
`cfg`	`DvzInstanceConfig` *	the instance configuration
`extension`	`const` `char` *	the extension name

Declared in include/datoviz/vk/instance.h:110.

`dvz_instance_config_request_layer()`¶

Add an instance layer request to a configuration.

_Bool dvz_instance_config_request_layer(
    DvzInstanceConfig * cfg,
    const char * layer
);

Field	Type	Description
return	`_Bool`	whether the layer was added to the request list
`cfg`	`DvzInstanceConfig` *	the instance configuration
`layer`	`const` `char` *	the layer name

Declared in include/datoviz/vk/instance.h:98.

`dvz_instance_create()`¶

Create and initialize a heap-allocated instance from a configuration.

DvzInstance * dvz_instance_create(
    const DvzInstanceConfig * cfg
);

Field	Type	Description
return	`DvzInstance` *	a created instance on success, `NULL` on failure
`cfg`	`const` `DvzInstanceConfig` *	the instance configuration

Related: dvz_instance_destroy().

Declared in include/datoviz/vk/instance.h:120.

`dvz_instance_destroy()`¶

Destroy the instance.

void dvz_instance_destroy(
    DvzInstance * instance
);

Field	Type	Description
`instance`	`DvzInstance` *	the instance

Related: dvz_instance_create().

Declared in include/datoviz/vk/instance.h:139.

`dvz_instance_error_count()`¶

Return the validation error counter accumulated by an instance.

uint32_t dvz_instance_error_count(
    DvzInstance * instance
);

Field	Type	Description
return	`uint32_t`	the number of validation errors reported through the debug callback
`instance`	`DvzInstance` *	the instance

Declared in include/datoviz/vk/instance.h:149.

`dvz_instance_gpu_count()`¶

Return the number of detected physical GPUs.

uint32_t dvz_instance_gpu_count(
    DvzInstance * instance
);

Field	Type	Description
return	`uint32_t`	the number of detected GPUs
`instance`	`DvzInstance` *	the instance

Declared in include/datoviz/vk/gpu.h:66.

`dvz_instance_gpu_handle()`¶

Resolve the Vulkan physical device handle for a selected GPU index.

_Bool dvz_instance_gpu_handle(
    DvzInstance * instance,
    uint32_t gpu_index,
    VkPhysicalDevice * out_pdevice
);

Field	Type	Description
return	`_Bool`	true when the physical device handle was resolved
`instance`	`DvzInstance` *	the instance
`gpu_index`	`uint32_t`	selected GPU index
`out_pdevice`	`VkPhysicalDevice` *

Declared in include/datoviz/vk/gpu.h:91.

`dvz_instance_gpu_info()`¶

Return a GPU descriptor snapshot for a given GPU index.

_Bool dvz_instance_gpu_info(
    DvzInstance * instance,
    uint32_t gpu_index,
    DvzGpuInfo * out_info
);

Field	Type	Description
return	`_Bool`	true when the descriptor was populated
`instance`	`DvzInstance` *	the instance
`gpu_index`	`uint32_t`	selected GPU index in the instance
`out_info`	`DvzGpuInfo` *

Declared in include/datoviz/vk/gpu.h:79.

`dvz_instance_gpu_queue_caps()`¶

Query a GPU queue-family capability snapshot from an instance.

Together with DvzQueues, this forms the public low-level queue-planning surface used before device creation. Callers should treat the result as a capability snapshot, not as owned runtime state.

_Bool dvz_instance_gpu_queue_caps(
    DvzInstance * instance,
    uint32_t gpu_index,
    DvzQueueCaps * out_caps
);

Field	Type	Description
return	`_Bool`	whether queue capabilities were retrieved
`instance`	`DvzInstance` *	source instance
`gpu_index`	`uint32_t`	selected GPU index in the instance
`out_caps`	`DvzQueueCaps` *

Declared in include/datoviz/vk/queues.h:134.

`dvz_instance_handle()`¶

Return the native VkInstance for a DvzInstance.

VkInstance dvz_instance_handle(
    DvzInstance * instance
);

Field	Type	Description
return	`VkInstance`	the Vulkan instance
`instance`	`DvzInstance` *	the Datoviz instance

Declared in include/datoviz/vk/instance.h:130.

`dvz_instance_has_extension()`¶

Returns whether an instance extension is supported on the system?

_Bool dvz_instance_has_extension(
    DvzInstance * instance,
    const char * extension
);

Field	Type	Description
return	`_Bool`	a boolean indicating whether this extension is supported
`instance`	`DvzInstance` *	the instance
`extension`	`const` `char` *	the extension name

Declared in include/datoviz/vk/instance.h:229.

`dvz_instance_has_layer()`¶

Returns whether an instance layer is supported on the system?

_Bool dvz_instance_has_layer(
    DvzInstance * instance,
    const char * layer
);

Field	Type	Description
return	`_Bool`	a boolean indicating whether this layer is supported
`instance`	`DvzInstance` *	the instance
`layer`	`const` `char` *	the layer name

Declared in include/datoviz/vk/instance.h:189.

`dvz_instance_probe_extensions()`¶

Probe instance extensions.

void dvz_instance_probe_extensions(
    DvzInstance * instance
);

Field	Type	Description
`instance`	`DvzInstance` *	the instance

Declared in include/datoviz/vk/instance.h:202.

`dvz_instance_probe_layers()`¶

Probe instance layers.

void dvz_instance_probe_layers(
    DvzInstance * instance
);

Field	Type	Description
`instance`	`DvzInstance` *	the instance

Declared in include/datoviz/vk/instance.h:162.

`dvz_instance_supported_extensions()`¶

Get the supported extensions before creating an instance.

The returned string array is borrowed instance-owned storage. It remains valid until the next extension probe on the same instance or instance destruction. Callers must not mutate or free the array or strings.

char ** dvz_instance_supported_extensions(
    DvzInstance * instance,
    uint32_t * count
);

Field	Type	Description
return	`char` **	borrowed string array owned by `instance`, valid until extensions are reprobed or the instance is destroyed
`instance`	`DvzInstance` *	the instance
`count`	`uint32_t` *

Declared in include/datoviz/vk/instance.h:218.

`dvz_instance_supported_layers()`¶

Get the supported layers before creating an instance.

The returned string array is borrowed instance-owned storage. It remains valid until the next layer probe on the same instance or instance destruction. Callers must not mutate or free the array or strings.

char ** dvz_instance_supported_layers(
    DvzInstance * instance,
    uint32_t * count
);

Field	Type	Description
return	`char` **	borrowed string array owned by `instance`, valid until layers are reprobed or the instance is destroyed
`instance`	`DvzInstance` *	the instance
`count`	`uint32_t` *

Declared in include/datoviz/vk/instance.h:178.

Types

DvzInstance · typedef

typedef struct DvzInstance DvzInstance;

Declared in include/datoviz/vk/instance.h:41.

DvzInstanceConfig · record

struct DvzInstanceConfig {
    uint32_t struct_size;
    uint32_t flags;
    uint32_t vk_version;
    const char * app_name;
    uint32_t app_version;
    _Bool portability;
    uint32_t layer_count;
    const char *[32] layers;
    uint32_t extension_count;
    const char *[256] extensions;
};

Declared in include/datoviz/vk/instance.h:48.

DvzInstanceFlags · enum

enum DvzInstanceFlags {
    DVZ_INSTANCE_VALIDATION_FLAGS = 1,
};

Declared in include/datoviz/vk/instance.h:69.

Memory And Interop¶

Functions

`dvz_allocation_create()`¶

Allocate an empty allocation wrapper.

Heap-allocated wrappers follow the same lifecycle as stack-owned wrappers: fill them through allocator create/import helpers, destroy the owning Vulkan resource before discarding them, and free only if this wrapper came from dvz_allocation_create().

DvzAllocation * dvz_allocation_create(void);

Field	Type	Description
return	`DvzAllocation` *	allocated allocation wrapper, or NULL on allocation failure

Declared in include/datoviz/vk/memory.h:97.

`dvz_allocation_flags()`¶

Return the allocation policy flags currently associated with an allocation.

DvzAllocationFlags dvz_allocation_flags(
    DvzAllocation * alloc
);

Field	Type	Description
return	`DvzAllocationFlags`	allocation policy flags
`alloc`	`DvzAllocation` *	the allocation

Declared in include/datoviz/vk/memory.h:136.

`dvz_allocation_flags_contains()`¶

Test whether a flag set contains all requested allocation policy flags.

_Bool dvz_allocation_flags_contains(
    DvzAllocationFlags flags,
    DvzAllocationFlags test
);

Field	Type	Description
return	`_Bool`	true when every flag in test is set in flags
`flags`	`DvzAllocationFlags`	flag set to test
`test`	`DvzAllocationFlags`	flags that must all be present

Declared in include/datoviz/vk/memory.h:147.

`dvz_allocation_free()`¶

Free an allocation wrapper allocated by dvz_allocation_create().

void dvz_allocation_free(
    DvzAllocation * alloc
);

Field	Type	Description
`alloc`	`DvzAllocation` *	allocation wrapper to free

Declared in include/datoviz/vk/memory.h:106.

`dvz_allocation_mapped()`¶

Return the mapped pointer currently associated with an allocation.

void * dvz_allocation_mapped(
    DvzAllocation * alloc
);

Field	Type	Description
return	`void` *	mapped pointer or NULL
`alloc`	`DvzAllocation` *	the allocation

Declared in include/datoviz/vk/memory.h:126.

`dvz_allocation_memory()`¶

Return the Vulkan device-memory handle backing an allocation.

This is an advanced interop helper for external-memory workflows. Regular Datoviz callers should prefer the allocator/map/copy helpers in memory.h instead of depending on raw memory handles.

VkDeviceMemory dvz_allocation_memory(
    DvzAllocation * alloc
);

Field	Type	Description
return	`VkDeviceMemory`	borrowed Vulkan device-memory handle, or `VK_NULL_HANDLE` when unavailable
`alloc`	`DvzAllocation` *	the allocation

Declared in include/datoviz/vk/memory_interop.h:268.

`dvz_allocation_set_flags()`¶

Update the allocation policy flags used by higher-level wrappers.

void dvz_allocation_set_flags(
    DvzAllocation * alloc,
    DvzAllocationFlags flags
);

Field	Type	Description
`alloc`	`DvzAllocation` *	the allocation
`flags`	`DvzAllocationFlags`	allocation policy flags

Declared in include/datoviz/vk/memory.h:157.

`dvz_allocation_size()`¶

Return the allocation size, in bytes.

VkDeviceSize dvz_allocation_size(
    DvzAllocation * alloc
);

Field	Type	Description
return	`VkDeviceSize`	allocation size in bytes
`alloc`	`DvzAllocation` *	the allocation

Declared in include/datoviz/vk/memory.h:167.

`dvz_allocator_buffer()`¶

Allocate and create a Vulkan buffer.

The input create-info struct is treated as caller-owned configuration and is not retained or mutated after this call returns.

int dvz_allocator_buffer(
    DvzVma * allocator,
    VkBufferCreateInfo * info,
    DvzAllocationFlags flags,
    DvzAllocation * alloc,
    VkBuffer * vk_buffer
);

Field	Type	Description
return	`int`	0 on success, non-zero on Vulkan or allocator failure
`allocator`	`DvzVma` *	the allocator
`info`	`VkBufferCreateInfo` *	the buffer creation info Vulkan struct
`flags`	`DvzAllocationFlags`	Datoviz allocation policy flags
`alloc`	`DvzAllocation` *
`vk_buffer`	`VkBuffer` *

Declared in include/datoviz/vk/memory.h:202.

`dvz_allocator_copy_from()`¶

Copy memory from an allocation into host memory.

int dvz_allocator_copy_from(
    DvzVma * allocator,
    DvzAllocation * alloc,
    VkDeviceSize offset,
    void * data,
    VkDeviceSize size
);

Field	Type	Description
return	`int`	0 on success, -1 on failure
`allocator`	`DvzVma` *	the allocator
`alloc`	`DvzAllocation` *	the source allocation
`offset`	`VkDeviceSize`	source byte offset within the allocation
`data`	`void` *	destination host pointer
`size`	`VkDeviceSize`	number of bytes to copy

Declared in include/datoviz/vk/memory.h:299.

`dvz_allocator_copy_to()`¶

Copy host memory into an allocation.

int dvz_allocator_copy_to(
    DvzVma * allocator,
    DvzAllocation * alloc,
    VkDeviceSize offset,
    const void * data,
    VkDeviceSize size
);

Field	Type	Description
return	`int`	0 on success, -1 on failure
`allocator`	`DvzVma` *	the allocator
`alloc`	`DvzAllocation` *	the destination allocation
`offset`	`VkDeviceSize`	destination byte offset within the allocation
`data`	`const` `void` *	source host pointer
`size`	`VkDeviceSize`	number of bytes to copy

Declared in include/datoviz/vk/memory.h:283.

`dvz_allocator_create()`¶

Allocate an empty allocator wrapper.

Heap-allocated wrappers follow the same lifecycle as stack-owned wrappers: initialize with dvz_device_allocator(), destroy with dvz_allocator_destroy(), and free only if this wrapper came from dvz_allocator_create().

DvzVma * dvz_allocator_create(void);

Field	Type	Description
return	`DvzVma` *	allocated allocator wrapper, or NULL on allocation failure

Related: dvz_allocator_destroy().

Declared in include/datoviz/vk/memory.h:74.

`dvz_allocator_destroy()`¶

Destroy an allocator.

void dvz_allocator_destroy(
    DvzVma * allocator
);

Field	Type	Description
`allocator`	`DvzVma` *	the allocator.

Related: dvz_allocator_create().

Declared in include/datoviz/vk/memory.h:333.

`dvz_allocator_destroy_buffer()`¶

Destroy a buffer allocation.

void dvz_allocator_destroy_buffer(
    DvzVma * allocator,
    DvzAllocation * alloc,
    VkBuffer vk_buffer
);

Field	Type	Description
`allocator`	`DvzVma` *	the allocator
`alloc`	`DvzAllocation` *	the allocation
`vk_buffer`	`VkBuffer`	the buffer

Declared in include/datoviz/vk/memory.h:312.

`dvz_allocator_destroy_image()`¶

Destroy a image allocation.

void dvz_allocator_destroy_image(
    DvzVma * allocator,
    DvzAllocation * alloc,
    VkImage vk_image
);

Field	Type	Description
`allocator`	`DvzVma` *	the allocator
`alloc`	`DvzAllocation` *	the allocation
`vk_image`	`VkImage`	the image

Declared in include/datoviz/vk/memory.h:324.

`dvz_allocator_device()`¶

Return the device associated with an allocator.

DvzDevice * dvz_allocator_device(
    DvzVma * allocator
);

Field	Type	Description
return	`DvzDevice` *	associated device, or NULL if unset
`allocator`	`DvzVma` *	the allocator

Declared in include/datoviz/vk/memory.h:116.

`dvz_allocator_export()`¶

Export an allocation for another GPU API.

This function is part of the advanced external-memory interop surface. It is intended for specialized paths such as video/interop plumbing rather than ordinary Datoviz allocation use.

int dvz_allocator_export(
    DvzVma * allocator,
    DvzAllocation * alloc,
    int * handle
);

Field	Type	Description
return	`int`	0 on success, non-zero on unsupported interop or Vulkan failure
`allocator`	`DvzVma` *	the allocator
`alloc`	`DvzAllocation` *	the allocation
`handle`	`int` *

Declared in include/datoviz/vk/memory_interop.h:191.

`dvz_allocator_external()`¶

Return the external-handle type configured on an allocator.

This helper belongs to the narrower external-memory interop surface rather than the stable allocation path.

VkExternalMemoryHandleTypeFlagsKHR dvz_allocator_external(
    DvzVma * allocator
);

Field	Type	Description
return	`VkExternalMemoryHandleTypeFlagsKHR`	external memory handle type flags (0 when disabled)
`allocator`	`DvzVma` *	the allocator

Declared in include/datoviz/vk/memory_interop.h:176.

`dvz_allocator_flush()`¶

Flush mapped memory ranges so GPU sees the latest CPU writes.

int dvz_allocator_flush(
    DvzVma * allocator,
    DvzAllocation * alloc,
    VkDeviceSize offset,
    VkDeviceSize size
);

Field	Type	Description
return	`int`	0 on success, -1 on failure
`allocator`	`DvzVma` *	the allocator
`alloc`	`DvzAllocation` *	the allocation
`offset`	`VkDeviceSize`	the byte offset within the allocation
`size`	`VkDeviceSize`	the number of bytes to flush

Declared in include/datoviz/vk/memory.h:256.

`dvz_allocator_free()`¶

Free an allocator wrapper allocated by dvz_allocator_create().

void dvz_allocator_free(
    DvzVma * allocator
);

Field	Type	Description
`allocator`	`DvzVma` *	allocator wrapper to free

Declared in include/datoviz/vk/memory.h:83.

`dvz_allocator_image()`¶

Allocate and create a Vulkan image.

The input create-info struct is treated as caller-owned configuration and is not retained or mutated after this call returns.

int dvz_allocator_image(
    DvzVma * allocator,
    VkImageCreateInfo * info,
    DvzAllocationFlags flags,
    DvzAllocation * alloc,
    VkImage * vk_image
);

Field	Type	Description
return	`int`	0 on success, non-zero on Vulkan or allocator failure
`allocator`	`DvzVma` *	the allocator
`info`	`VkImageCreateInfo` *	the image creation info Vulkan struct
`flags`	`DvzAllocationFlags`	Datoviz allocation policy flags
`alloc`	`DvzAllocation` *
`vk_image`	`VkImage` *

Declared in include/datoviz/vk/memory.h:221.

`dvz_allocator_import_buffer()`¶

Import an external GPU data pointer to a Vulkan buffer.

This function belongs to the advanced external-memory interop surface, not the stable low-level allocation path.

This declaration remains intentionally public even though the active branch currently exercises import paths only narrowly; future allocator-interop hardening is expected to build on this surface rather than reintroducing private entry points.

Warning

This CUDA/CuPy-owned pointer -> Vulkan import direction remains experimental on the current branch. It is unreliable in practice and should not be treated as a stable v0.4 contract. Prefer the opposite direction: create/export Vulkan memory first, then import the external memory handle into CUDA/CuPy.

int dvz_allocator_import_buffer(
    DvzVma * allocator,
    VkBufferCreateInfo * info,
    DvzAllocationFlags flags,
    int handle,
    DvzAllocation * alloc,
    VkBuffer * vk_buffer
);

Field	Type	Description
return	`int`	0 on success, -1 on failure
`allocator`	`DvzVma` *	the allocator
`info`	`VkBufferCreateInfo` *	the buffer creation info Vulkan struct
`flags`	`DvzAllocationFlags`	Datoviz allocation policy flags
`handle`	`int`	the handle to import
`alloc`	`DvzAllocation` *
`vk_buffer`	`VkBuffer` *

Declared in include/datoviz/vk/memory_interop.h:296.

`dvz_allocator_import_image()`¶

Import an external GPU data pointer to a Vulkan image.

This function belongs to the advanced external-memory interop surface, not the stable low-level allocation path.

This declaration remains intentionally public even though the active branch does not yet rely on image import broadly; future allocator-interop hardening is expected to build on this surface rather than reintroducing private entry points.

int dvz_allocator_import_image(
    DvzVma * allocator,
    VkImageCreateInfo * info,
    DvzAllocationFlags flags,
    int handle,
    DvzAllocation * alloc,
    VkImage * vk_image
);

Field	Type	Description
return	`int`	0 on success, -1 on failure
`allocator`	`DvzVma` *	the allocator
`info`	`VkImageCreateInfo` *	the image creation info Vulkan struct
`flags`	`DvzAllocationFlags`	Datoviz allocation policy flags
`handle`	`int`	the handle to import
`alloc`	`DvzAllocation` *
`vk_image`	`VkImage` *

Declared in include/datoviz/vk/memory_interop.h:320.

`dvz_allocator_invalidate()`¶

Invalidate mapped memory ranges so the CPU sees the latest GPU writes.

int dvz_allocator_invalidate(
    DvzVma * allocator,
    DvzAllocation * alloc,
    VkDeviceSize offset,
    VkDeviceSize size
);

Field	Type	Description
return	`int`	0 on success, -1 on failure
`allocator`	`DvzVma` *	the allocator
`alloc`	`DvzAllocation` *	the allocation
`offset`	`VkDeviceSize`	the byte offset within the allocation
`size`	`VkDeviceSize`	the number of bytes to invalidate

Declared in include/datoviz/vk/memory.h:269.

`dvz_allocator_map()`¶

Map an allocation.

void * dvz_allocator_map(
    DvzVma * allocator,
    DvzAllocation * alloc
);

Field	Type	Description
return	`void` *	the mapped pointer
`allocator`	`DvzVma` *	the allocator
`alloc`	`DvzAllocation` *	the allocation

Declared in include/datoviz/vk/memory.h:233.

`dvz_allocator_unmap()`¶

Unmap the allocation.

void dvz_allocator_unmap(
    DvzVma * allocator,
    DvzAllocation * alloc
);

Field	Type	Description
`allocator`	`DvzVma` *	the allocator
`alloc`	`DvzAllocation` *	the allocation

Declared in include/datoviz/vk/memory.h:243.

`dvz_interop_buffer_export()`¶

Export a Vulkan-owned buffer allocation and package external interop metadata.

This helper transfers ownership of out->memory_handle to the caller on success. The optional semaphore_handle is copied into the descriptor as metadata; ownership of that handle remains defined by the call site that exported it.

int dvz_interop_buffer_export(
    DvzVma * allocator,
    DvzAllocation * alloc,
    uint64_t offset,
    uint64_t size,
    uint32_t usage,
    int semaphore_handle,
    uint32_t semaphore_handle_type,
    uint64_t semaphore_value,
    DvzInteropBufferExport * out
);

Field	Type	Description
return	`int`	0 on success, non-zero on invalid input, unsupported interop, or Vulkan failure
`allocator`	`DvzVma` *	the allocator configured for external-memory export
`alloc`	`DvzAllocation` *	the Vulkan-owned allocation backing the buffer
`offset`	`uint64_t`	byte offset of the logical buffer view within the allocation
`size`	`uint64_t`	logical buffer-view size in bytes
`usage`	`uint32_t`	DRP2/Vulkan buffer usage flags expected by the consumer
`semaphore_handle`	`int`	optional exported external semaphore handle, or -1 when absent
`semaphore_handle_type`	`uint32_t`	external semaphore handle type, or 0 when absent
`semaphore_value`	`uint64_t`	timeline semaphore value associated with the export
`out`	`DvzInteropBufferExport` *

Declared in include/datoviz/vk/memory_interop.h:212.

`dvz_interop_buffer_export_config()`¶

Return a default interop buffer export configuration.

DvzInteropBufferExportConfig dvz_interop_buffer_export_config(void);

Field	Type	Description
return	`DvzInteropBufferExportConfig`	default export configuration

Declared in include/datoviz/vk/memory_interop.h:104.

`dvz_interop_buffer_export_from_buffer()`¶

Export a vklite buffer and package external interop metadata.

This is the preferred public helper for CUDA/CuPy import of Datoviz/Vulkan-owned buffers. It avoids exposing private DvzBuffer allocation internals to examples and bindings. On success, ownership of out->memory_handle transfers to the caller. If config->semaphore is non-NULL, this function also exports a semaphore handle and transfers out->semaphore_handle ownership to the caller.

int dvz_interop_buffer_export_from_buffer(
    DvzBuffer * buffer,
    const DvzInteropBufferExportConfig * config,
    DvzInteropBufferExport * out
);

Field	Type	Description
return	`int`	0 on success, non-zero on invalid input, unsupported interop, or Vulkan failure
`buffer`	`DvzBuffer` *	the live Vulkan-owned buffer
`config`	`const` `DvzInteropBufferExportConfig` *	logical export range and optional timeline semaphore metadata
`out`	`DvzInteropBufferExport` *

Declared in include/datoviz/vk/memory_interop.h:233.

`dvz_interop_buffer_wait_timeline()`¶

Wait on a timeline semaphore before Vulkan reads an interop buffer as vertex input.

This helper is the explicit Vulkan-side synchronization point for CUDA/CuPy writes into a Vulkan-owned exported buffer. It submits a short barrier command on the main queue that waits for semaphore to reach value, then makes external writes visible to vertex-attribute reads.

_Bool dvz_interop_buffer_wait_timeline(
    DvzDevice * device,
    DvzBuffer * buffer,
    uint64_t size,
    DvzSemaphore * semaphore,
    uint64_t value
);

Field	Type	Description
return	`_Bool`	true on success
`device`	`DvzDevice` *	logical device owning the main Vulkan queue
`buffer`	`DvzBuffer` *	buffer whose contents were written externally
`size`	`uint64_t`	byte size of the synchronized buffer range
`semaphore`	`DvzSemaphore` *	timeline semaphore signaled by the external API
`value`	`uint64_t`	timeline value to wait on

Declared in include/datoviz/vk/memory_interop.h:253.

`dvz_interop_gpu_ctx()`¶

Create an advanced GPU context for Vulkan-owned CUDA/CuPy interop buffers.

This helper is binding substrate, not the final high-level Python API. It creates a Datoviz GPU context whose allocator exports Vulkan memory with memory_handle_type, and whose device has the external-memory, external-semaphore, and timeline-semaphore support needed by the Linux/NVIDIA CuPy smoke. Destroy the returned context with dvz_gpu_ctx_destroy().

DvzGpuCtx * dvz_interop_gpu_ctx(
    uint32_t gpu_index,
    VkExternalMemoryHandleTypeFlagsKHR memory_handle_type
);

Field	Type	Description
return	`DvzGpuCtx` *	owned GPU context, or NULL on failure
`gpu_index`	`uint32_t`	Vulkan physical-device index to use
`memory_handle_type`	`VkExternalMemoryHandleTypeFlagsKHR`	external memory handle type for exported allocations

Declared in include/datoviz/vk/memory_interop.h:141.

`dvz_interop_gpu_ctx_ex()`¶

Create an advanced GPU context for CUDA/CuPy interop that also supports presentation.

This is the configurable variant of dvz_interop_gpu_ctx(). It keeps the same external-memory allocator policy and timeline-semaphore setup, then optionally adds caller-provided Vulkan instance extensions and canvas/swapchain device extensions. Use it when a borrowed interop GPU context must also back a visible GLFW or hosted-surface canvas.

DvzGpuCtx * dvz_interop_gpu_ctx_ex(
    uint32_t gpu_index,
    VkExternalMemoryHandleTypeFlagsKHR memory_handle_type,
    uint32_t instance_extension_count,
    const char *const * instance_extensions,
    _Bool enable_canvas_extensions
);

Field	Type	Description
return	`DvzGpuCtx` *	owned GPU context, or NULL on failure
`gpu_index`	`uint32_t`	Vulkan physical-device index to use
`memory_handle_type`	`VkExternalMemoryHandleTypeFlagsKHR`	external memory handle type for exported allocations
`instance_extension_count`	`uint32_t`	number of Vulkan instance extension names
`instance_extensions`	`const` `char` `const`	extension-name array, or NULL when count is zero
`enable_canvas_extensions`	`_Bool`	whether swapchain/surface device extensions should be requested

Declared in include/datoviz/vk/memory_interop.h:160.

Types

DvzAllocation · typedef

typedef struct DvzAllocation DvzAllocation;

Declared in include/datoviz/vk/memory.h:33.

DvzAllocationFlags · typedef

typedef uint32_t DvzAllocationFlags;

Declared in include/datoviz/vk/memory.h:34.

DvzInteropBufferExport · record

struct DvzInteropBufferExport {
    uint32_t version;
    int memory_handle;
    uint32_t memory_handle_type;
    uint64_t allocation_size;
    uint64_t offset;
    uint64_t size;
    uint32_t usage;
    uint32_t vk_usage;
    uint32_t drp2_usage;
    uint32_t flags;
    uint32_t device_uuid_valid;
    uint8_t[16] device_uuid;
    int semaphore_handle;
    uint32_t semaphore_handle_type;
    uint64_t semaphore_value;
};

Declared in include/datoviz/vk/memory_interop.h:51.

DvzInteropBufferExportConfig · record

struct DvzInteropBufferExportConfig {
    uint32_t struct_size;
    uint32_t flags;
    uint64_t offset;
    uint64_t size;
    uint32_t drp2_usage;
    uint32_t export_flags;
    DvzSemaphore * semaphore;
    uint32_t semaphore_handle_type;
    uint64_t semaphore_value;
};

Declared in include/datoviz/vk/memory_interop.h:72.

Shared Render Types¶

Types

DvzDescriptorType · enum

enum DvzDescriptorType {
    DVZ_DESCRIPTOR_TYPE_SAMPLER = 0,
    DVZ_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER = 1,
    DVZ_DESCRIPTOR_TYPE_SAMPLED_IMAGE = 2,
    DVZ_DESCRIPTOR_TYPE_STORAGE_IMAGE = 3,
    DVZ_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER = 4,
    DVZ_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER = 5,
    DVZ_DESCRIPTOR_TYPE_UNIFORM_BUFFER = 6,
    DVZ_DESCRIPTOR_TYPE_STORAGE_BUFFER = 7,
    DVZ_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC = 8,
    DVZ_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC = 9,
};

Declared in include/datoviz/vk/enums.h:119.

DvzFilter · enum

enum DvzFilter {
    DVZ_FILTER_NEAREST = 0,
    DVZ_FILTER_LINEAR = 1,
    DVZ_FILTER_CUBIC_IMG = 1000015000,
};

Declared in include/datoviz/vk/enums.h:61.

DvzPolygonMode · enum

enum DvzPolygonMode {
    DVZ_POLYGON_MODE_FILL = 0,
    DVZ_POLYGON_MODE_LINE = 1,
    DVZ_POLYGON_MODE_POINT = 2,
};

Declared in include/datoviz/vk/enums.h:92.

DvzSamplerAddressMode · enum

enum DvzSamplerAddressMode {
    DVZ_SAMPLER_ADDRESS_MODE_REPEAT = 0,
    DVZ_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT = 1,
    DVZ_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE = 2,
    DVZ_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER = 3,
    DVZ_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE = 4,
};

Declared in include/datoviz/vk/enums.h:71.

DvzShaderFormat · enum

enum DvzShaderFormat {
    DVZ_SHADER_NONE = 0,
    DVZ_SHADER_SPIRV = 1,
    DVZ_SHADER_GLSL = 2,
};

Declared in include/datoviz/vk/enums.h:38.

DvzShaderStageFlags · typedef

typedef int32_t DvzShaderStageFlags;

Declared in include/datoviz/vk/enums.h:114.

DvzShaderType · enum

enum DvzShaderType {
    DVZ_SHADER_VERTEX = 1,
    DVZ_SHADER_TESSELLATION_CONTROL = 2,
    DVZ_SHADER_TESSELLATION_EVALUATION = 4,
    DVZ_SHADER_GEOMETRY = 8,
    DVZ_SHADER_FRAGMENT = 16,
    DVZ_SHADER_COMPUTE = 32,
};

Declared in include/datoviz/vk/enums.h:102.

DvzVertexInputRate · enum

enum DvzVertexInputRate {
    DVZ_VERTEX_INPUT_RATE_VERTEX = 0,
    DVZ_VERTEX_INPUT_RATE_INSTANCE = 1,
};

Declared in include/datoviz/vk/enums.h:83.

Vulkan Foundation API¶

Symbol Groups¶

Devices And Queues¶

dvz_device_allocator()¶

dvz_device_command_pool()¶

dvz_device_config()¶

dvz_device_config_enable_canvas_extensions()¶

dvz_device_config_request_extension()¶

dvz_device_config_request_queue()¶

dvz_device_config_set_features10()¶

dvz_device_config_set_features11()¶

dvz_device_config_set_features12()¶

dvz_device_config_set_features13()¶

dvz_device_config_set_gpu_index()¶

dvz_device_create()¶

dvz_device_descriptor_pool()¶

dvz_device_destroy()¶

dvz_device_features10()¶

dvz_device_handle()¶

dvz_device_has_extension()¶

dvz_device_physical_device()¶

dvz_device_queue()¶

dvz_device_wait()¶

dvz_queue_family()¶

dvz_queue_from_role()¶

dvz_queue_handle()¶

dvz_queue_index()¶

dvz_queue_supports()¶

dvz_queue_wait()¶

dvz_queues()¶

dvz_queues_show()¶

GPU Context¶

dvz_compile_glsl()¶

dvz_gpu_ctx()¶

dvz_gpu_ctx_alloc()¶

dvz_gpu_ctx_config()¶

dvz_gpu_ctx_config_add_instance_extension()¶

dvz_gpu_ctx_config_alloc()¶

dvz_gpu_ctx_config_enable_canvas_extensions()¶

dvz_gpu_ctx_config_features10()¶

dvz_gpu_ctx_config_features12()¶

dvz_gpu_ctx_config_features13()¶

dvz_gpu_ctx_config_gpu()¶

dvz_gpu_ctx_config_validation()¶

dvz_gpu_ctx_destroy()¶

dvz_gpu_ctx_device()¶

dvz_gpu_ctx_error_count()¶

dvz_gpu_ctx_gpu_index()¶

dvz_gpu_ctx_gpu_info()¶

dvz_gpu_ctx_instance()¶

dvz_gpu_ctx_queue()¶

Instances¶

dvz_instance_config()¶

dvz_instance_config_request_extension()¶

dvz_instance_config_request_layer()¶

dvz_instance_create()¶

dvz_instance_destroy()¶

dvz_instance_error_count()¶

dvz_instance_gpu_count()¶

dvz_instance_gpu_handle()¶

dvz_instance_gpu_info()¶

dvz_instance_gpu_queue_caps()¶

dvz_instance_handle()¶

dvz_instance_has_extension()¶

dvz_instance_has_layer()¶

dvz_instance_probe_extensions()¶

dvz_instance_probe_layers()¶

dvz_instance_supported_extensions()¶

dvz_instance_supported_layers()¶

Memory And Interop¶

dvz_allocation_create()¶

dvz_allocation_flags()¶

dvz_allocation_flags_contains()¶

dvz_allocation_free()¶

dvz_allocation_mapped()¶

dvz_allocation_memory()¶

dvz_allocation_set_flags()¶

dvz_allocation_size()¶

dvz_allocator_buffer()¶

dvz_allocator_copy_from()¶

`dvz_device_allocator()`¶

`dvz_device_command_pool()`¶

`dvz_device_config()`¶

`dvz_device_config_enable_canvas_extensions()`¶

`dvz_device_config_request_extension()`¶

`dvz_device_config_request_queue()`¶

`dvz_device_config_set_features10()`¶

`dvz_device_config_set_features11()`¶

`dvz_device_config_set_features12()`¶

`dvz_device_config_set_features13()`¶

`dvz_device_config_set_gpu_index()`¶

`dvz_device_create()`¶

`dvz_device_descriptor_pool()`¶

`dvz_device_destroy()`¶

`dvz_device_features10()`¶

`dvz_device_handle()`¶

`dvz_device_has_extension()`¶

`dvz_device_physical_device()`¶

`dvz_device_queue()`¶

`dvz_device_wait()`¶

`dvz_queue_family()`¶

`dvz_queue_from_role()`¶

`dvz_queue_handle()`¶

`dvz_queue_index()`¶

`dvz_queue_supports()`¶

`dvz_queue_wait()`¶

`dvz_queues()`¶

`dvz_queues_show()`¶

`dvz_compile_glsl()`¶

`dvz_gpu_ctx()`¶

`dvz_gpu_ctx_alloc()`¶

`dvz_gpu_ctx_config()`¶

`dvz_gpu_ctx_config_add_instance_extension()`¶

`dvz_gpu_ctx_config_alloc()`¶

`dvz_gpu_ctx_config_enable_canvas_extensions()`¶

`dvz_gpu_ctx_config_features10()`¶

`dvz_gpu_ctx_config_features12()`¶

`dvz_gpu_ctx_config_features13()`¶

`dvz_gpu_ctx_config_gpu()`¶

`dvz_gpu_ctx_config_validation()`¶

`dvz_gpu_ctx_destroy()`¶

`dvz_gpu_ctx_device()`¶

`dvz_gpu_ctx_error_count()`¶

`dvz_gpu_ctx_gpu_index()`¶

`dvz_gpu_ctx_gpu_info()`¶

`dvz_gpu_ctx_instance()`¶

`dvz_gpu_ctx_queue()`¶

`dvz_instance_config()`¶

`dvz_instance_config_request_extension()`¶

`dvz_instance_config_request_layer()`¶

`dvz_instance_create()`¶

`dvz_instance_destroy()`¶

`dvz_instance_error_count()`¶

`dvz_instance_gpu_count()`¶

`dvz_instance_gpu_handle()`¶

`dvz_instance_gpu_info()`¶

`dvz_instance_gpu_queue_caps()`¶

`dvz_instance_handle()`¶

`dvz_instance_has_extension()`¶

`dvz_instance_has_layer()`¶

`dvz_instance_probe_extensions()`¶

`dvz_instance_probe_layers()`¶

`dvz_instance_supported_extensions()`¶

`dvz_instance_supported_layers()`¶

`dvz_allocation_create()`¶

`dvz_allocation_flags()`¶

`dvz_allocation_flags_contains()`¶

`dvz_allocation_free()`¶

`dvz_allocation_mapped()`¶

`dvz_allocation_memory()`¶

`dvz_allocation_set_flags()`¶

`dvz_allocation_size()`¶

`dvz_allocator_buffer()`¶

`dvz_allocator_copy_from()`¶

`dvz_allocator_copy_to()`¶

`dvz_allocator_create()`¶

`dvz_allocator_destroy()`¶

`dvz_allocator_destroy_buffer()`¶

`dvz_allocator_destroy_image()`¶

`dvz_allocator_device()`¶