Skip to content

vklite API

GPU

dvz_gpu()

Initialize a GPU.

DvzGpu* dvz_gpu(DvzApp* app, uint32_t idx);
Parameter Type Description
app DvzApp* the app
idx uint32_t the GPU index among the system's GPUs
returns DvzGpu* pointer to the created GPU object

A GPU object is the interface to one of the GPUs on the current system.

dvz_gpu_best()

Find the "best" GPU on the system.

DvzGpu* dvz_gpu_best(DvzApp* app);
Parameter Type Description
app DvzApp* the app
returns DvzGpu* pointer to the best GPU object

For now, this is just the discrete GPU with the most VRAM, or the GPU with the most VRAM if there are no discrete GPUs.

dvz_gpu_request_features()

Request some features before creating the GPU instance.

void dvz_gpu_request_features(
    DvzGpu* gpu, VkPhysicalDeviceFeatures requested_features);
Parameter Type Description
gpu DvzGpu* the GPU
requested_features VkPhysicalDeviceFeatures the list of requested features

This function needs to be called before creating the GPU with dvz_gpu_create().

dvz_gpu_queue()

Request a new Vulkan queue before creating the GPU.

void dvz_gpu_queue(DvzGpu* gpu, uint32_t idx, DvzQueueType type);
Parameter Type Description
gpu DvzGpu* the GPU
idx uint32_t the queue index (should be regularly increasing: 0, 1, 2...)
type DvzQueueType the queue type

dvz_gpu_create()

Create a GPU once the features and queues have been set up.

void dvz_gpu_create(DvzGpu* gpu, VkSurfaceKHR surface);
Parameter Type Description
gpu DvzGpu* the GPU
surface VkSurfaceKHR the surface on which the GPU will need to render

dvz_gpu_destroy()

Destroy the resources associated to a GPU.

void dvz_gpu_destroy(DvzGpu* gpu);
Parameter Type Description
gpu DvzGpu* the GPU

Coarse synchronization

dvz_queue_wait()

Wait for a queue to be idle.

void dvz_queue_wait(DvzGpu* gpu, uint32_t queue_idx);
Parameter Type Description
gpu DvzGpu* the GPU
queue_idx uint32_t the queue index

This is one of the different GPU synchronization methods. It is not efficient as it waits until the queue is idle.

dvz_app_wait()

Full synchronization on all GPUs.

void dvz_app_wait(DvzApp* app);
Parameter Type Description
app DvzApp* the application instance

This function waits on all queues of all GPUs. The strongest, least efficient of the synchronization methods.

dvz_gpu_wait()

Full synchronization on a given GPU.

void dvz_gpu_wait(DvzGpu* gpu);
Parameter Type Description
gpu DvzGpu* the GPU

This function waits on all queues of a given GPU.

Window

dvz_window()

Create a blank window.

DvzWindow* dvz_window(DvzApp* app, uint32_t width, uint32_t height);
Parameter Type Description
app DvzApp* the application instance
width uint32_t the window width, in pixels
height uint32_t the window height, in pixels
returns DvzWindow* window

This function is rarely used on its own. A bare window offers no functionality that allows one to render to it with Vulkan. One needs a swapchain, an event loop, and so on, which are provided instead at the level of the Canvas.

dvz_window_get_size()

Get the window size, in pixels.

void dvz_window_get_size(
    DvzWindow* window, uint32_t* framebuffer_width, uint32_t* framebuffer_height);
Parameter Type Description
window DvzWindow* the window
framebuffer_width uint32_t* the width, in pixels
framebuffer_height uint32_t* the height, in pixels

dvz_window_set_size()

Set the window size, in pixels.

void dvz_window_set_size(DvzWindow* window, uint32_t width, uint32_t height);
Parameter Type Description
window DvzWindow* the window
width uint32_t the width, in pixels
height uint32_t the height, in pixels

dvz_window_poll_events()

Process the pending windowing events by the backend (glfw by default).

void dvz_window_poll_events(DvzWindow* window);
Parameter Type Description
window DvzWindow* the window

dvz_window_destroy()

Destroy a window.

void dvz_window_destroy(DvzWindow* window);
Parameter Type Description
window DvzWindow* the window

Warning

This function must be imperatively called after dvz_swapchain_destroy().

Swapchain

dvz_swapchain()

Initialize a swapchain.

DvzSwapchain dvz_swapchain(
    DvzGpu* gpu, DvzWindow* window, uint32_t min_img_count);
Parameter Type Description
gpu DvzGpu* the GPU
window DvzWindow* the window
min_img_count uint32_t the minimum acceptable number of images in the swapchain
returns DvzSwapchain swapchain

dvz_swapchain_format()

Set the swapchain image format.

void dvz_swapchain_format(DvzSwapchain* swapchain, VkFormat format);
Parameter Type Description
swapchain DvzSwapchain* the swapchain
format VkFormat the format

dvz_swapchain_present_mode()

Set the swapchain present mode.

void dvz_swapchain_present_mode(
    DvzSwapchain* swapchain, VkPresentModeKHR present_mode);
Parameter Type Description
swapchain DvzSwapchain* the swapchain
present_mode VkPresentModeKHR the present mode

dvz_swapchain_requested_size()

Set the swapchain requested image size.

void dvz_swapchain_requested_size(
    DvzSwapchain* swapchain, uint32_t width, uint32_t height);
Parameter Type Description
swapchain DvzSwapchain* the swapchain
width uint32_t the requested width
height uint32_t the requested height

dvz_swapchain_create()

Create the swapchain once it has been set up.

void dvz_swapchain_create(DvzSwapchain* swapchain);
Parameter Type Description
swapchain DvzSwapchain* the swapchain

dvz_swapchain_recreate()

Recreate a swapchain (for example after a window resize).

void dvz_swapchain_recreate(DvzSwapchain* swapchain);
Parameter Type Description
swapchain DvzSwapchain* the swapchain

dvz_swapchain_acquire()

Acquire a swapchain image.

void dvz_swapchain_acquire(
    DvzSwapchain* swapchain, DvzSemaphores* semaphores, uint32_t semaphore_idx,
    DvzFences* fences, uint32_t fence_idx);
Parameter Type Description
swapchain DvzSwapchain* the swapchain
semaphores DvzSemaphores* the set of signal semaphores
semaphore_idx uint32_t the index of the semaphore to signal after image acquisition
fences DvzFences* the set of signal fences
fence_idx uint32_t the index of the fence to signal after image acquisition

dvz_swapchain_present()

Present a swapchain image to the screen after it has been rendered.

void dvz_swapchain_present(
    DvzSwapchain* swapchain, uint32_t queue_idx, DvzSemaphores* semaphores,
    uint32_t semaphore_idx);
Parameter Type Description
swapchain DvzSwapchain* the swapchain
queue_idx uint32_t the index of the present queue
semaphores DvzSemaphores* the set of waiting semaphores
semaphore_idx uint32_t the index of the semaphore to wait on before presentation

dvz_swapchain_destroy()

Destroy a swapchain

void dvz_swapchain_destroy(DvzSwapchain* swapchain);
Parameter Type Description
swapchain DvzSwapchain* the swapchain

Warning

This function must imperatively be called before dvz_window_destroy().

Command buffers

dvz_commands()

Create a set of command buffers.

DvzCommands dvz_commands(DvzGpu* gpu, uint32_t queue, uint32_t count);
Parameter Type Description
gpu DvzGpu* the GPU
queue uint32_t the queue index within the GPU
count uint32_t the number of command buffers to create
returns DvzCommands set of command buffers

Note

We use the following convention in vklite and elsewhere in datoviz: the queue #0 must support transfer tasks. This convention makes the implementation a bit simpler. This convention is respected by the context module, where the first default queue is the transfer queue, dedicated to transfer tasks.

dvz_cmd_begin()

Start recording a command buffer.

void dvz_cmd_begin(DvzCommands* cmds, uint32_t idx);
Parameter Type Description
cmds DvzCommands* the set of command buffers
idx uint32_t the index of the command buffer to begin recording on

dvz_cmd_end()

Stop recording a command buffer.

void dvz_cmd_end(DvzCommands* cmds, uint32_t idx);
Parameter Type Description
cmds DvzCommands* the set of command buffers
idx uint32_t the index of the command buffer to stop the recording on

dvz_cmd_reset()

Reset a command buffer.

void dvz_cmd_reset(DvzCommands* cmds, uint32_t idx);
Parameter Type Description
cmds DvzCommands* the set of command buffers
idx uint32_t the index of the command buffer to reset

dvz_cmd_free()

Free a set of command buffers.

void dvz_cmd_free(DvzCommands* cmds);
Parameter Type Description
cmds DvzCommands* the set of command buffers

dvz_cmd_submit_sync()

Submit a command buffer on its queue with inefficient full synchronization.

void dvz_cmd_submit_sync(DvzCommands* cmds, uint32_t idx);
Parameter Type Description
cmds DvzCommands* the set of command buffers
idx uint32_t the index of the command buffer to submit

This function is relatively inefficient because it calls dvz_queue_wait().

dvz_commands_destroy()

Destroy a set of command buffers.

void dvz_commands_destroy(DvzCommands* cmds);
Parameter Type Description
cmds DvzCommands* the set of command buffers

GPU buffer

dvz_buffer()

Initialize a GPU buffer.

DvzBuffer dvz_buffer(DvzGpu* gpu);
Parameter Type Description
gpu DvzGpu* the GPU
returns DvzBuffer buffer

dvz_buffer_size()

Set the buffer size.

void dvz_buffer_size(DvzBuffer* buffer, VkDeviceSize size);
Parameter Type Description
buffer DvzBuffer* the buffer
size VkDeviceSize the buffer size, in bytes

dvz_buffer_type()

Set the buffer type.

void dvz_buffer_type(DvzBuffer* buffer, DvzBufferType type);
Parameter Type Description
buffer DvzBuffer* the buffer
type DvzBufferType the buffer type

dvz_buffer_usage()

Set the buffer usage.

void dvz_buffer_usage(DvzBuffer* buffer, VkBufferUsageFlags usage);
Parameter Type Description
buffer DvzBuffer* the buffer
usage VkBufferUsageFlags the buffer usage

dvz_buffer_memory()

Set the buffer memory properties.

void dvz_buffer_memory(DvzBuffer* buffer, VkMemoryPropertyFlags memory);
Parameter Type Description
buffer DvzBuffer* the buffer
memory VkMemoryPropertyFlags the memory properties

dvz_buffer_queue_access()

Set the buffer queue access.

void dvz_buffer_queue_access(DvzBuffer* buffer, uint32_t queue_idx);
Parameter Type Description
buffer DvzBuffer* the buffer
queue_idx uint32_t the queue index

dvz_buffer_create()

Create the buffer after it has been set.

void dvz_buffer_create(DvzBuffer* buffer);
Parameter Type Description
buffer DvzBuffer* the buffer

dvz_buffer_resize()

Resize a buffer.

void dvz_buffer_resize(DvzBuffer* buffer, VkDeviceSize size);
Parameter Type Description
buffer DvzBuffer* the buffer
size VkDeviceSize the new buffer size, in bytes

dvz_buffer_map()

Memory-map a buffer.

void* dvz_buffer_map(
    DvzBuffer* buffer, VkDeviceSize offset, VkDeviceSize size);
Parameter Type Description
buffer DvzBuffer* the buffer
offset VkDeviceSize the offset within the buffer, in bytes
size VkDeviceSize the size to map, in bytes

dvz_buffer_unmap()

Unmap a buffer.

void dvz_buffer_unmap(DvzBuffer* buffer);
Parameter Type Description
buffer DvzBuffer* the buffer

dvz_buffer_download()

Download a buffer data to the CPU.

void dvz_buffer_download(
    DvzBuffer* buffer, VkDeviceSize offset, VkDeviceSize size, void* data);
Parameter Type Description
buffer DvzBuffer* the buffer
offset VkDeviceSize the offset within the buffer, in bytes
size VkDeviceSize the size of the region to download, in bytes
data void* the buffer to download on (must be allocated with the appropriate size)

Important

This function does not use any GPU synchronization primitive: this is the responsibility of the caller. A simple (but not optimal) method is just to call the following function after every call to this function: dvz_queue_wait(gpu, DVZ_DEFAULT_QUEUE_TRANSFER);

dvz_buffer_upload()

Upload data to a GPU buffer.

void dvz_buffer_upload(
    DvzBuffer* buffer, VkDeviceSize offset, VkDeviceSize size, void* data);
Parameter Type Description
buffer DvzBuffer* the buffer
offset VkDeviceSize the offset within the buffer, in bytes
size VkDeviceSize the buffer size, in bytes
data void* the data to upload

Important

This function does not use any GPU synchronization primitive: this is the responsibility of the caller. A simple (but not optimal) method is just to call the following function after every call to this function: dvz_queue_wait(gpu, DVZ_DEFAULT_QUEUE_TRANSFER);

dvz_buffer_destroy()

Destroy a buffer

void dvz_buffer_destroy(DvzBuffer* buffer);
Parameter Type Description
buffer DvzBuffer* the buffer

dvz_buffer_regions()

Create buffer regions on an existing GPU buffer.

DvzBufferRegions dvz_buffer_regions(
    DvzBuffer* buffer, uint32_t count, VkDeviceSize offset,
    VkDeviceSize size, VkDeviceSize alignment);
Parameter Type Description
buffer DvzBuffer* the buffer
count uint32_t the number of successive regions
offset VkDeviceSize the offset within the buffer
size VkDeviceSize the size of each region, in bytes
alignment VkDeviceSize the alignment requirement for the region offsets

dvz_buffer_regions_map()

Map a buffer region.

void* dvz_buffer_regions_map(DvzBufferRegions* br, uint32_t idx);
Parameter Type Description
br DvzBufferRegions* the buffer regions
idx uint32_t the index of the buffer region to map

dvz_buffer_regions_unmap()

Unmap a set of buffer regions.

void dvz_buffer_regions_unmap(DvzBufferRegions* br);
Parameter Type Description
br DvzBufferRegions* the buffer regions

dvz_buffer_regions_upload()

Upload data to a buffer region.

void dvz_buffer_regions_upload(DvzBufferRegions* br, uint32_t idx, void* data);
Parameter Type Description
br DvzBufferRegions* the set of buffer regions
idx uint32_t the index of the buffer region to upload data to
data void* the data to upload

Important

This function does not use any GPU synchronization primitive: this is the responsibility of the caller. A simple (but not optimal) method is just to call the following function after every call to this function: dvz_queue_wait(gpu, DVZ_DEFAULT_QUEUE_TRANSFER);

GPU images

dvz_images()

Initialize a set of GPU images.

DvzImages dvz_images(DvzGpu* gpu, VkImageType type, uint32_t count);
Parameter Type Description
gpu DvzGpu* the GPU
type VkImageType the image type
count uint32_t the number of images
returns DvzImages images

dvz_images_format()

Set the images format.

void dvz_images_format(DvzImages* images, VkFormat format);
Parameter Type Description
images DvzImages* the images
format VkFormat the image format

dvz_images_layout()

Set the images layout.

void dvz_images_layout(DvzImages* images, VkImageLayout layout);
Parameter Type Description
images DvzImages* the images
layout VkImageLayout the image layout

dvz_images_size()

Set the images size.

void dvz_images_size(
    DvzImages* images, uint32_t width, uint32_t height, uint32_t depth);
Parameter Type Description
images DvzImages* the images
width uint32_t the image width
height uint32_t the image height
depth uint32_t the image depth

dvz_images_tiling()

Set the images tiling.

void dvz_images_tiling(DvzImages* images, VkImageTiling tiling);
Parameter Type Description
images DvzImages* the images
tiling VkImageTiling the image tiling

dvz_images_usage()

Set the images usage.

void dvz_images_usage(DvzImages* images, VkImageUsageFlags usage);
Parameter Type Description
images DvzImages* the images
usage VkImageUsageFlags the image usage

dvz_images_memory()

Set the images memory properties.

void dvz_images_memory(DvzImages* images, VkMemoryPropertyFlags memory);
Parameter Type Description
images DvzImages* the images
memory VkMemoryPropertyFlags the memory properties

dvz_images_aspect()

Set the images aspect.

void dvz_images_aspect(DvzImages* images, VkImageAspectFlags aspect);
Parameter Type Description
images DvzImages* the images
aspect VkImageAspectFlags the image aspect

dvz_images_queue_access()

Set the images queue access.

void dvz_images_queue_access(DvzImages* images, uint32_t queue_idx);
Parameter Type Description
images DvzImages* the images
queue_idx uint32_t the queue index

This parameter specifies which queues may access the image from command buffers submitted to them.

dvz_images_create()

Create the images after they have been set up.

void dvz_images_create(DvzImages* images);
Parameter Type Description
images DvzImages* the images

dvz_images_resize()

Resize images.

void dvz_images_resize(
    DvzImages* images, uint32_t width, uint32_t height, uint32_t depth);
Parameter Type Description
images DvzImages* the images
width uint32_t the new width
height uint32_t the new height
depth uint32_t the new depth

Warning

This function deletes the images contents when resizing.

dvz_images_transition()

Transition the images to their layout after creation.

void dvz_images_transition(DvzImages* images);
Parameter Type Description
images DvzImages* the images

This function performs a hard synchronization on the queue and submits a command buffer with the image transition.

dvz_images_download()

Download the data from a staging GPU image.

void dvz_images_download(
    DvzImages* staging, uint32_t idx, VkDeviceSize bytes_per_component,
    bool swizzle, bool has_alpha, void* out);
Parameter Type Description
staging DvzImages* the images to download the data from
idx uint32_t the index of the image
bytes_per_component VkDeviceSize number of bytes per component
swizzle bool whether the RGB(A) values need to be transposed
has_alpha bool whether there is an Alpha component in the output buffer
out void* the buffer that will be filled with the image data (must be already allocated)

dvz_images_destroy()

Destroy images.

void dvz_images_destroy(DvzImages* images);
Parameter Type Description
images DvzImages* the images

Sampler

dvz_sampler()

Initialize a texture sampler.

DvzSampler dvz_sampler(DvzGpu* gpu);
Parameter Type Description
gpu DvzGpu* the GPU
returns DvzSampler sampler object

dvz_sampler_min_filter()

Set the sampler min filter.

void dvz_sampler_min_filter(DvzSampler* sampler, VkFilter filter);
Parameter Type Description
sampler DvzSampler* the sampler
filter VkFilter the filter

dvz_sampler_mag_filter()

Set the sampler mag filter.

void dvz_sampler_mag_filter(DvzSampler* sampler, VkFilter filter);
Parameter Type Description
sampler DvzSampler* the sampler
filter VkFilter the filter

dvz_sampler_address_mode()

Set the sampler address mode

void dvz_sampler_address_mode(
    DvzSampler* sampler, DvzTextureAxis axis, VkSamplerAddressMode address_mode);
Parameter Type Description
sampler DvzSampler* the sampler
axis DvzTextureAxis the sampler axis
address_mode VkSamplerAddressMode the address mode

dvz_sampler_create()

Create the sampler after it has been set up.

void dvz_sampler_create(DvzSampler* sampler);
Parameter Type Description
sampler DvzSampler* the sampler

dvz_sampler_destroy()

Destroy a sampler

void dvz_sampler_destroy(DvzSampler* sampler);
Parameter Type Description
sampler DvzSampler* the sampler

Pipeline slots

Vulkan terminology: descriptor set layout.

dvz_slots()

Initialize pipeline slots (aka Vulkan descriptor set layout).

DvzSlots dvz_slots(DvzGpu* gpu);
Parameter Type Description
gpu DvzGpu* the GPU
returns DvzSlots slots

dvz_slots_binding()

Set the slots binding.

void dvz_slots_binding(DvzSlots* slots, uint32_t idx, VkDescriptorType type);
Parameter Type Description
slots DvzSlots* the slots
idx uint32_t the slot index to set up
type VkDescriptorType the descriptor type for that slot

dvz_slots_push()

Set up push constants.

void dvz_slots_push(
    DvzSlots* slots, VkDeviceSize offset, VkDeviceSize size,
    VkShaderStageFlags shaders);
Parameter Type Description
slots DvzSlots* the slots
offset VkDeviceSize the push constant offset, in bytes
size VkDeviceSize the push constant size, in bytes
shaders VkShaderStageFlags the shader stages that will access the push constant

dvz_slots_create()

Create the slots after they have been set up.

void dvz_slots_create(DvzSlots* slots);
Parameter Type Description
slots DvzSlots* the slots

dvz_slots_destroy()

Destroy the slots

void dvz_slots_destroy(DvzSlots* slots);
Parameter Type Description
slots DvzSlots* the slots

Pipeline bindings

Vulkan terminology: descriptor sets

dvz_bindings()

Initialize bindings corresponding to slots.

DvzBindings dvz_bindings(DvzSlots* slots, uint32_t dset_count);
Parameter Type Description
slots DvzSlots* the slots
dset_count uint32_t the number of descriptor sets (number of swapchain images)

dvz_bindings_buffer()

Bind a buffer to a slot.

void dvz_bindings_buffer(
    DvzBindings* bindings, uint32_t idx, DvzBufferRegions br);
Parameter Type Description
bindings DvzBindings* the bindings
idx uint32_t the slot index
br DvzBufferRegions the buffer regions to bind to that slot

dvz_bindings_texture()

Bind a texture to a slot.

void dvz_bindings_texture(
    DvzBindings* bindings, uint32_t idx, DvzTexture* texture);
Parameter Type Description
bindings DvzBindings* the bindings
idx uint32_t the slot index
br None the texture to bind to that slot

dvz_bindings_update()

Update the bindings after the buffers/textures have been set up.

void dvz_bindings_update(DvzBindings* bindings);
Parameter Type Description
bindings DvzBindings* the bindings

dvz_bindings_destroy()

Destroy bindings.

void dvz_bindings_destroy(DvzBindings* bindings);
Parameter Type Description
bindings DvzBindings* the bindings

Graphics pipeline

dvz_graphics()

Initialize a graphics pipeline.

DvzGraphics dvz_graphics(DvzGpu* gpu);
Parameter Type Description
gpu DvzGpu* the GPU
returns DvzGraphics graphics pipeline

dvz_graphics_renderpass()

Set the renderpass of a graphics pipeline.

void dvz_graphics_renderpass(
    DvzGraphics* graphics, DvzRenderpass* renderpass, uint32_t subpass);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
renderpass DvzRenderpass* the render pass
subpass uint32_t the subpass index

dvz_graphics_topology()

Set the graphics pipeline primitive topology

void dvz_graphics_topology(
    DvzGraphics* graphics, VkPrimitiveTopology topology);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
topology VkPrimitiveTopology the primitive topology

dvz_graphics_shader_glsl()

Set the GLSL code of a graphics pipeline.

void dvz_graphics_shader_glsl(
    DvzGraphics* graphics, VkShaderStageFlagBits stage, char* code);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
stage VkShaderStageFlagBits the shader stage
code char* the GLSL code of the shader

dvz_graphics_shader_spirv()

Set the SPIRV code of a graphics pipeline.

void dvz_graphics_shader_spirv(
    DvzGraphics* graphics, VkShaderStageFlagBits stage, VkDeviceSize size,
    uint32_t* buffer);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
stage VkShaderStageFlagBits the shader stage
size VkDeviceSize the size of the SPIRV buffer, in bytes
buffer uint32_t* the binary buffer with the SPIRV code

dvz_graphics_shader()

Set the path to a shader for a graphics pipeline.

void dvz_graphics_shader(
    DvzGraphics* graphics, VkShaderStageFlagBits stage, char* shader_path);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
stage VkShaderStageFlagBits the shader stage
shader_path char* the path to the .spirv shader file

dvz_graphics_vertex_binding()

Set the vertex binding.

void dvz_graphics_vertex_binding(
    DvzGraphics* graphics, uint32_t binding, VkDeviceSize stride);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
binding uint32_t the binding index
stride VkDeviceSize the stride in the vertex buffer, in bytes

dvz_graphics_vertex_attr()

Add a vertex attribute.

void dvz_graphics_vertex_attr(
    DvzGraphics* graphics, uint32_t binding, uint32_t location,
    VkFormat format, VkDeviceSize offset);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
binding uint32_t the binding index (as specified in the vertex shader)
location uint32_t the location index (as specified in the vertex shader)
format VkFormat the format
offset VkDeviceSize the offset, in bytes

dvz_graphics_blend()

Set the graphics blend type.

void dvz_graphics_blend(DvzGraphics* graphics, DvzBlendType blend_type);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
blend_type DvzBlendType the blend type

dvz_graphics_depth_test()

Set the graphics depth test.

void dvz_graphics_depth_test(DvzGraphics* graphics, DvzDepthTest depth_test);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
depth_test DvzDepthTest the depth test

dvz_graphics_pick()

Set whether the graphics pipeline supports picking.

void dvz_graphics_pick(DvzGraphics* graphics, bool support_pick);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
support_pick bool whether the graphics pipeline supports picking

Note

Picking support is currently all or nothing: all graphics of a canvas must either support picking or not. In addition, the canvas must have been created with the DVZ_CANVAS_FLAGS_PICK flag.

dvz_graphics_polygon_mode()

Set the graphics polygon mode.

void dvz_graphics_polygon_mode(
    DvzGraphics* graphics, VkPolygonMode polygon_mode);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
polygon_mode VkPolygonMode the polygon mode

dvz_graphics_cull_mode()

Set the graphics cull mode.

void dvz_graphics_cull_mode(DvzGraphics* graphics, VkCullModeFlags cull_mode);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
cull_mode VkCullModeFlags the cull mode

dvz_graphics_front_face()

Set the graphics front face.

void dvz_graphics_front_face(DvzGraphics* graphics, VkFrontFace front_face);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
front_face VkFrontFace the front face

dvz_graphics_create()

Create a graphics pipeline after it has been set up.

void dvz_graphics_create(DvzGraphics* graphics);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline

dvz_graphics_slot()

Set a binding slot for a graphics pipeline.

void dvz_graphics_slot(
    DvzGraphics* graphics, uint32_t idx, VkDescriptorType type);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
idx uint32_t the slot index
type VkDescriptorType the descriptor type

dvz_graphics_push()

Set a graphics pipeline push constant.

void dvz_graphics_push(
    DvzGraphics* graphics, VkDeviceSize offset, VkDeviceSize size,
    VkShaderStageFlags shaders);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
offset VkDeviceSize the push constant offset, in bytes
offset VkDeviceSize the push size, in bytes
shaders VkShaderStageFlags the shader stages that will access the push constant

dvz_graphics_destroy()

Destroy a graphics pipeline.

void dvz_graphics_destroy(DvzGraphics* graphics);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline

Compute pipeline

dvz_compute()

Initialize a compute pipeline.

DvzCompute dvz_compute(DvzGpu* gpu, char* shader_path);
Parameter Type Description
gpu DvzGpu* the GPU
shader_path char* (optional) the path to the .spirv file with the compute shader
returns DvzCompute compute pipeline

dvz_compute_create()

Create a compute pipeline after it has been set up.

void dvz_compute_create(DvzCompute* compute);
Parameter Type Description
compute DvzCompute* the compute pipeline

dvz_compute_code()

Set the GLSL code directly (the library will compile it automatically to SPIRV).

void dvz_compute_code(DvzCompute* compute, char* code);
Parameter Type Description
compute DvzCompute* the compute pipeline
code char* the GLSL code defining the compute shader

dvz_compute_slot()

Declare a slot for the compute pipeline.

void dvz_compute_slot(
    DvzCompute* compute, uint32_t idx, VkDescriptorType type);
Parameter Type Description
compute DvzCompute* the compute pipeline
idx uint32_t the slot index
type VkDescriptorType the descriptor type

dvz_compute_push()

Set up push constant.

void dvz_compute_push(
    DvzCompute* compute, VkDeviceSize offset, VkDeviceSize size,
    VkShaderStageFlags shaders);
Parameter Type Description
compute DvzCompute* the compute pipeline
offset VkDeviceSize the push constant offset, in bytes
size VkDeviceSize the push constant size, in bytes
shaders VkShaderStageFlags the shaders that will need to access the push constant

dvz_compute_bindings()

Associate a bindings object to a compute pipeline.

void dvz_compute_bindings(DvzCompute* compute, DvzBindings* bindings);
Parameter Type Description
compute DvzCompute* the compute pipeline
bindings DvzBindings* the bindings

dvz_compute_destroy()

Destroy a compute pipeline.

void dvz_compute_destroy(DvzCompute* compute);
Parameter Type Description
compute DvzCompute* the compute pipeline

Barrier

dvz_barrier()

Initialize a synchronization barrier (usedwithin a command buffer).

DvzBarrier dvz_barrier(DvzGpu* gpu);
Parameter Type Description
gpu DvzGpu* the GPU
returns DvzBarrier barrier

dvz_barrier_stages()

Set the barrier stages.

void dvz_barrier_stages(
    DvzBarrier* barrier, VkPipelineStageFlags src_stage, VkPipelineStageFlags dst_stage);
Parameter Type Description
barrier DvzBarrier* the barrier
src_stage VkPipelineStageFlags the source stage
dst_stage VkPipelineStageFlags the destination stage

dvz_barrier_buffer()

Set the barrier buffer.

void dvz_barrier_buffer(DvzBarrier* barrier, DvzBufferRegions br);
Parameter Type Description
barrier DvzBarrier* the barrier
br DvzBufferRegions the buffer regions

dvz_barrier_buffer_queue()

Set the barrier buffer queue.

void dvz_barrier_buffer_queue(
    DvzBarrier* barrier, uint32_t src_queue, uint32_t dst_queue);
Parameter Type Description
barrier DvzBarrier* the barrier
src_queue uint32_t the source queue index
dst_queue uint32_t the destination queue index

dvz_barrier_buffer_access()

Set the barrier buffer access.

void dvz_barrier_buffer_access(
    DvzBarrier* barrier, VkAccessFlags src_access, VkAccessFlags dst_access);
Parameter Type Description
barrier DvzBarrier* the barrier
src_access VkAccessFlags the source access flags
dst_access VkAccessFlags the destination access flags

dvz_barrier_images()

Set the barrier images.

void dvz_barrier_images(DvzBarrier* barrier, DvzImages* images);
Parameter Type Description
barrier DvzBarrier* the barrier
images DvzImages* the images

dvz_barrier_images_layout()

Set the barrier images layout.

void dvz_barrier_images_layout(
    DvzBarrier* barrier, VkImageLayout src_layout, VkImageLayout dst_layout);
Parameter Type Description
barrier DvzBarrier* the barrier
src_layout VkImageLayout the source layout
dst_layout VkImageLayout the destination layout

dvz_barrier_images_queue()

Set the barrier images queue.

void dvz_barrier_images_queue(
    DvzBarrier* barrier, uint32_t src_queue, uint32_t dst_queue);
Parameter Type Description
barrier DvzBarrier* the barrier
src_queue uint32_t the source queue index
dst_queue uint32_t the destination queue index

dvz_barrier_images_access()

Set the barrier images access.

void dvz_barrier_images_access(
    DvzBarrier* barrier, VkAccessFlags src_access, VkAccessFlags dst_access);
Parameter Type Description
barrier DvzBarrier* the barrier
src_access VkAccessFlags the source access flags
dst_access VkAccessFlags the destination access flags

Semaphores

dvz_semaphores()

Initialize a set of semaphores (GPU-GPU synchronization).

DvzSemaphores dvz_semaphores(DvzGpu* gpu, uint32_t count);
Parameter Type Description
gpu DvzGpu* the GPU
count uint32_t the number of semaphores
returns DvzSemaphores semaphores

dvz_semaphores_destroy()

Destroy semaphores.

void dvz_semaphores_destroy(DvzSemaphores* semaphores);
Parameter Type Description
semaphores DvzSemaphores* the semaphores

Fences

dvz_fences()

Initialize a set of fences (CPU-GPU synchronization).

DvzFences dvz_fences(DvzGpu* gpu, uint32_t count, bool signaled);
Parameter Type Description
gpu DvzGpu* the GPU
count uint32_t the number of fences
signaled bool whether the fences are created in the signaled state or not
returns DvzFences fences

dvz_fences_copy()

Copy a fence from a set of fences to another.

void dvz_fences_copy(
    DvzFences* src_fences, uint32_t src_idx, DvzFences* dst_fences,
    uint32_t dst_idx);
Parameter Type Description
src_fences DvzFences* the source fences
src_idx uint32_t the fence index within the source fences
dst_fences DvzFences* the destination fences
dst_idx uint32_t the fence index within the destination fences

dvz_fences_wait()

Wait on the GPU until a fence is signaled.

void dvz_fences_wait(DvzFences* fences, uint32_t idx);
Parameter Type Description
fences DvzFences* the fences
idx uint32_t the fence index

dvz_fences_ready()

Return whether a fence is ready.

bool dvz_fences_ready(DvzFences* fences, uint32_t idx);
Parameter Type Description
fences DvzFences* the fences
idx uint32_t the fence index

dvz_fences_reset()

Rset the state of a fence.

void dvz_fences_reset(DvzFences* fences, uint32_t idx);
Parameter Type Description
fences DvzFences* the fences
idx uint32_t the fence index

dvz_fences_destroy()

Destroy fences.

void dvz_fences_destroy(DvzFences* fences);
Parameter Type Description
fences DvzFences* the fences

Renderpass

dvz_renderpass()

Initialize a render pass.

DvzRenderpass dvz_renderpass(DvzGpu* gpu);
Parameter Type Description
gpu DvzGpu* the GPU
returns DvzRenderpass render pass

dvz_renderpass_clear()

Set the clear value of a render pass.

void dvz_renderpass_clear(DvzRenderpass* renderpass, VkClearValue value);
Parameter Type Description
renderpass DvzRenderpass* the render pass
value VkClearValue the clear value

dvz_renderpass_attachment()

Specify a render pass attachment.

void dvz_renderpass_attachment(
    DvzRenderpass* renderpass, uint32_t idx, DvzRenderpassAttachmentType type,
    VkFormat format, VkImageLayout ref_layout);
Parameter Type Description
renderpass DvzRenderpass* the render pass
idx uint32_t the attachment index
type DvzRenderpassAttachmentType the attachment type
format VkFormat the attachment image format
ref_layout VkImageLayout the image layout

dvz_renderpass_attachment_layout()

Set the attachment layout.

void dvz_renderpass_attachment_layout(
    DvzRenderpass* renderpass, uint32_t idx, VkImageLayout src_layout,
    VkImageLayout dst_layout);
Parameter Type Description
renderpass DvzRenderpass* the render pass
idx uint32_t the attachment index
src_layout VkImageLayout the source layout
dst_layout VkImageLayout the destination layout

dvz_renderpass_attachment_ops()

Set the attachment load and store operations.

void dvz_renderpass_attachment_ops(
    DvzRenderpass* renderpass, uint32_t idx, VkAttachmentLoadOp load_op,
    VkAttachmentStoreOp store_op);
Parameter Type Description
renderpass DvzRenderpass* the render pass
idx uint32_t the attachment index
load_op VkAttachmentLoadOp the load operation
store_op VkAttachmentStoreOp the store operation

dvz_renderpass_subpass_attachment()

Set a subpass attachment.

void dvz_renderpass_subpass_attachment(
    DvzRenderpass* renderpass, uint32_t subpass_idx, uint32_t attachment_idx);
Parameter Type Description
renderpass DvzRenderpass* the render pass
subpass_idx uint32_t the subpass index
attachment_idx uint32_t the attachment index

dvz_renderpass_subpass_dependency()

Set a subpass dependency.

void dvz_renderpass_subpass_dependency(
    DvzRenderpass* renderpass, uint32_t dependency_idx, uint32_t src_subpass,
    uint32_t dst_subpass);
Parameter Type Description
renderpass DvzRenderpass* the render pass
dependency_idx uint32_t the dependency index
src_subpass uint32_t the source subpass index
dst_subpass uint32_t the destination subpass index

dvz_renderpass_subpass_dependency_access()

Set a subpass dependency access.

void dvz_renderpass_subpass_dependency_access(
    DvzRenderpass* renderpass, uint32_t dependency_idx, VkAccessFlags src_access,
    VkAccessFlags dst_access);
Parameter Type Description
renderpass DvzRenderpass* the render pass
dependency_idx uint32_t the dependency index
src_access VkAccessFlags the source access flags
dst_access VkAccessFlags the destinationaccess flags

dvz_renderpass_subpass_dependency_stage()

Set a subpass dependency stage.

void dvz_renderpass_subpass_dependency_stage(
    DvzRenderpass* renderpass, uint32_t dependency_idx, VkPipelineStageFlags src_stage,
    VkPipelineStageFlags dst_stage);
Parameter Type Description
renderpass DvzRenderpass* the render pass
dependency_idx uint32_t the dependency index
src_stage VkPipelineStageFlags the source pipeline stages
dst_stage VkPipelineStageFlags the destination pipeline stages

dvz_renderpass_create()

Create a render pass after it has been set up.

void dvz_renderpass_create(DvzRenderpass* renderpass);
Parameter Type Description
renderpass DvzRenderpass* the render pass

dvz_renderpass_destroy()

Destroy a render pass.

void dvz_renderpass_destroy(DvzRenderpass* renderpass);
Parameter Type Description
renderpass DvzRenderpass* the render pass

Framebuffers

dvz_framebuffers()

Initialize a set of framebuffers.

DvzFramebuffers dvz_framebuffers(DvzGpu* gpu);
Parameter Type Description
gpu DvzGpu* the GPU
returns DvzFramebuffers framebuffers

dvz_framebuffers_attachment()

Set framebuffers attachment.

void dvz_framebuffers_attachment(
    DvzFramebuffers* framebuffers, uint32_t attachment_idx, DvzImages* images);
Parameter Type Description
framebuffers DvzFramebuffers* the framebuffers
attachment_idx uint32_t the attachment index
images DvzImages* the images

dvz_framebuffers_create()

Create a set of framebuffers after it has been set up.

void dvz_framebuffers_create(
    DvzFramebuffers* framebuffers, DvzRenderpass* renderpass);
Parameter Type Description
framebuffers DvzFramebuffers* the framebuffers
renderpass DvzRenderpass* the render pass

dvz_framebuffers_destroy()

Destroy a set of framebuffers.

void dvz_framebuffers_destroy(DvzFramebuffers* framebuffers);
Parameter Type Description
framebuffers DvzFramebuffers* the framebuffers

Submit

dvz_submit()

Create a submit object, used to submit command buffers to a GPU queue.

DvzSubmit dvz_submit(DvzGpu* gpu);
Parameter Type Description
gpu DvzGpu* the GPU
returns DvzSubmit submit

dvz_submit_commands()

Set the command buffers to submit.

void dvz_submit_commands(DvzSubmit* submit, DvzCommands* commands);
Parameter Type Description
submit DvzSubmit* the submit object
cmds None the set of command buffers

dvz_submit_wait_semaphores()

Set the wait semaphores

void dvz_submit_wait_semaphores(
    DvzSubmit* submit, VkPipelineStageFlags stage, DvzSemaphores* semaphores,
    uint32_t idx);
Parameter Type Description
submit DvzSubmit* the submit object
stage VkPipelineStageFlags the pipeline stage
semaphores DvzSemaphores* the set of semaphores to wait on
idx uint32_t the semaphore index to wait on

dvz_submit_signal_semaphores()

Set the signal semaphores

void dvz_submit_signal_semaphores(
    DvzSubmit* submit, DvzSemaphores* semaphores, uint32_t idx);
Parameter Type Description
submit DvzSubmit* the submit object
semaphores DvzSemaphores* the set of semaphores to signal after the commands have completed
idx uint32_t the semaphore index to signal

dvz_submit_send()

Submit the command buffers to their queue.

void dvz_submit_send(
    DvzSubmit* submit, uint32_t cmd_idx, DvzFences* fences,
    uint32_t fence_idx);
Parameter Type Description
submit DvzSubmit* the submit object
cmd_idx uint32_t the command buffer index to submit
fences DvzFences* the fences to signal after completion
fence_idx uint32_t the fence index to signal

dvz_submit_reset()

Reset a submit object.

void dvz_submit_reset(DvzSubmit* submit);
Parameter Type Description
submit DvzSubmit* the submit object

Command buffer recording

dvz_cmd_begin_renderpass()

Begin a render pass.

void dvz_cmd_begin_renderpass(
    DvzCommands* cmds, uint32_t idx, DvzRenderpass* renderpass,
    DvzFramebuffers* framebuffers);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
renderpass DvzRenderpass* the render pass
framebuffers DvzFramebuffers* the framebuffers

dvz_cmd_end_renderpass()

End a render pass.

void dvz_cmd_end_renderpass(DvzCommands* cmds, uint32_t idx);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record

dvz_cmd_compute()

Launch a compute task.

void dvz_cmd_compute(
    DvzCommands* cmds, uint32_t idx, DvzCompute* compute, uvec3 size);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
compute DvzCompute* the computer pipeline
size uvec3 the task shape

dvz_cmd_barrier()

Register a barrier.

void dvz_cmd_barrier(DvzCommands* cmds, uint32_t idx, DvzBarrier* barrier);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
barrier DvzBarrier* the barrier

dvz_cmd_copy_buffer_to_image()

Copy a GPU buffer to a GPU image.

void dvz_cmd_copy_buffer_to_image(
    DvzCommands* cmds, uint32_t idx, DvzBuffer* buffer, DvzImages* images);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
buffer DvzBuffer* the buffer
images DvzImages* the image

dvz_cmd_copy_image_to_buffer()

Copy a GPU image to a GPU buffer.

void dvz_cmd_copy_image_to_buffer(
    DvzCommands* cmds, uint32_t idx, DvzImages* images, DvzBuffer* buffer);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
images DvzImages* the image
buffer DvzBuffer* the buffer

dvz_cmd_copy_image()

Copy a GPU image to another.

void dvz_cmd_copy_image(
    DvzCommands* cmds, uint32_t idx, DvzImages* src_img, DvzImages* dst_img);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
src_img DvzImages* the source image
dst_img DvzImages* the destination image

dvz_cmd_copy_image_region()

Copy a GPU image to another.

void dvz_cmd_copy_image_region(
    DvzCommands* cmds, uint32_t idx, DvzImages* src_img,
    ivec3 src_offset, DvzImages* dst_img, ivec3 dst_offset,
    uvec3 shape);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
src_img DvzImages* the source image
src_offset ivec3 the offset in the source image
dst_img DvzImages* the destination image
dst_offset ivec3 the offset in the target image
shape uvec3 the shape of the region to copy

dvz_cmd_viewport()

Set the viewport.

void dvz_cmd_viewport(DvzCommands* cmds, uint32_t idx, VkViewport viewport);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
viewport VkViewport the viewport

dvz_cmd_bind_graphics()

Bind a graphics pipeline.

void dvz_cmd_bind_graphics(
    DvzCommands* cmds, uint32_t idx, DvzGraphics* graphics,
    DvzBindings* bindings, uint32_t dynamic_idx);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
graphics DvzGraphics* the graphics pipeline
bindings DvzBindings* the bindings associated to the pipeline
dynamic_idx uint32_t the dynamic uniform buffer index

dvz_cmd_bind_vertex_buffer()

Bind a vertex buffer.

void dvz_cmd_bind_vertex_buffer(
    DvzCommands* cmds, uint32_t idx, DvzBufferRegions br,
    VkDeviceSize offset);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
br DvzBufferRegions the buffer regions
offset VkDeviceSize the offset within the buffer regions, in bytes

dvz_cmd_bind_index_buffer()

Bind an index buffer.

void dvz_cmd_bind_index_buffer(
    DvzCommands* cmds, uint32_t idx, DvzBufferRegions br,
    VkDeviceSize offset);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
br DvzBufferRegions the buffer regions
offset VkDeviceSize the offset within the buffer regions, in bytes

dvz_cmd_draw()

Direct draw.

void dvz_cmd_draw(
    DvzCommands* cmds, uint32_t idx, uint32_t first_vertex,
    uint32_t vertex_count);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
first_vertex uint32_t index of the first vertex
vertex_count uint32_t number of vertices to draw

dvz_cmd_draw_indexed()

Direct indexed draw.

void dvz_cmd_draw_indexed(
    DvzCommands* cmds, uint32_t idx, uint32_t first_index,
    uint32_t vertex_offset, uint32_t index_count);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
first_index uint32_t index of the first index
vertex_offset uint32_t offset of the vertex
index_count uint32_t number of indices to draw

dvz_cmd_draw_indirect()

Indirect draw.

void dvz_cmd_draw_indirect(
    DvzCommands* cmds, uint32_t idx, DvzBufferRegions indirect);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
indirect DvzBufferRegions buffer regions with the indirect draw info

dvz_cmd_draw_indexed_indirect()

Indirect indexed draw.

void dvz_cmd_draw_indexed_indirect(
    DvzCommands* cmds, uint32_t idx, DvzBufferRegions indirect);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
indirect DvzBufferRegions buffer regions with the indirect draw info

dvz_cmd_copy_buffer()

Copy a GPU buffer to another.

void dvz_cmd_copy_buffer(
    DvzCommands* cmds, uint32_t idx, DvzBuffer* src_buf,
    VkDeviceSize src_offset, DvzBuffer* dst_buf, VkDeviceSize dst_offset,
    VkDeviceSize size);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
src_buf DvzBuffer* the source buffer
src_offset VkDeviceSize the offset in the source buffer
dst_buf DvzBuffer* the destination buffer, in bytes
dst_offset VkDeviceSize the offset in the destination buffer, in bytes
size VkDeviceSize the size of the region to copy, in bytes

dvz_cmd_push()

Push constants.

void dvz_cmd_push(
    DvzCommands* cmds, uint32_t idx, DvzSlots* slots,
    VkShaderStageFlagBits shaders, VkDeviceSize offset, VkDeviceSize size,
    void* data);
Parameter Type Description
cmds DvzCommands* the set of command buffers to record
idx uint32_t the index of the command buffer to record
slots DvzSlots* the slots
shaders VkShaderStageFlagBits the shader stages that have access to the push constant
offset VkDeviceSize the offset in the push constant, in bytes
size VkDeviceSize the size in the push constant, in bytes
data void* the data to send via the push constant