Skip to content

GPU context and objects

Context

dvz_context()

Create a context associated to a GPU.

DvzContext* dvz_context(DvzGpu* gpu, DvzWindow* window);
Parameter Type Description
gpu DvzGpu* the GPU
window DvzWindow* the window with the surface attached to the GPU

dvz_context_reset()

Destroy all GPU resources in a GPU context.

void dvz_context_reset(DvzContext* context);
Parameter Type Description
context DvzContext* the context

dvz_context_destroy()

Destroy a context.

void dvz_context_destroy(DvzContext* context);
Parameter Type Description
context DvzContext* the context

Buffers

dvz_ctx_buffers()

Allocate one of several buffer regions on the GPU.

DvzBufferRegions dvz_ctx_buffers(
    DvzContext* context, DvzBufferType buffer_type, uint32_t buffer_count,
    VkDeviceSize size);
Parameter Type Description
context DvzContext* the context
buffer_type DvzBufferType the type of buffer to allocate the regions on
buffer_count uint32_t the number of buffer regions to allocate
size VkDeviceSize the size of each region to allocate, in bytes

dvz_ctx_buffers_resize()

Resize a set of buffer regions.

void dvz_ctx_buffers_resize(
    DvzContext* context, DvzBufferRegions* br, VkDeviceSize new_size);
Parameter Type Description
context DvzContext* the context
br DvzBufferRegions* the buffer regions to resize
new_size VkDeviceSize the new size of each buffer region, in bytes

Textures

dvz_ctx_texture()

Create a new GPU texture.

DvzTexture* dvz_ctx_texture(
    DvzContext* context, uint32_t dims, uvec3 size, VkFormat format);
Parameter Type Description
context DvzContext* the context
dims uint32_t the number of dimensions of the texture (1, 2, or 3)
size uvec3 the width, height, and depth
format VkFormat the format of each pixel

dvz_texture_resize()

Resize a texture.

void dvz_texture_resize(DvzTexture* texture, uvec3 size);
Parameter Type Description
texture DvzTexture* the texture
size uvec3 the new size (width, height, depth)

Warning

This function will delete the texture data.

dvz_texture_filter()

Set the texture filter.

void dvz_texture_filter(
    DvzTexture* texture, DvzFilterType type, VkFilter filter);
Parameter Type Description
texture DvzTexture* the texture
type DvzFilterType the filter type
filter VkFilter the filter

dvz_texture_address_mode()

Set the texture address mode.

void dvz_texture_address_mode(
    DvzTexture* texture, DvzTextureAxis axis, VkSamplerAddressMode address_mode);
Parameter Type Description
texture DvzTexture* the texture
axis DvzTextureAxis the axis
address_mode VkSamplerAddressMode the address mode

dvz_texture_upload()

Upload data to a GPU texture.

void dvz_texture_upload(
    DvzTexture* texture, uvec3 offset, uvec3 shape,
    VkDeviceSize size, void* data);
Parameter Type Description
texture DvzTexture* the texture
offset uvec3 offset within the texture
shape uvec3 shape of the part of the texture to update
size VkDeviceSize size of the data to upload, in bytes
data void* pointer to the data to upload

Note

This function should not be used to update a texture that is being used for rendering in the main event loop, otherwise full GPU synchronization needs to be done. Look at the Transfers API instead.

dvz_texture_download()

Download a texture from the GPU to the CPU.

void dvz_texture_download(
    DvzTexture* texture, uvec3 offset, uvec3 shape,
    VkDeviceSize size, void* data);
Parameter Type Description
texture DvzTexture* the texture
offset uvec3 offset within the texture
shape uvec3 shape of the part of the texture to download
size VkDeviceSize size of the data to download, in bytes
data void* pointer to the buffer to download to (should be already allocated)

Note

This function should not be used to download from a texture that is being used for rendering in the main event loop, otherwise full GPU synchronization needs to be done. Look at the Transfers API instead.

dvz_texture_copy()

Copy part of a texture to another texture.

void dvz_texture_copy(
    DvzTexture* src, uvec3 src_offset, DvzTexture* dst,
    uvec3 dst_offset, uvec3 shape);
Parameter Type Description
src DvzTexture* the source texture
src_offset uvec3 offset within the source texture
dst DvzTexture* the target texture
dst_offset uvec3 offset within the target texture
shape uvec3 shape of the part of the texture to copy

This function does not involve CPU-GPU data transfers.

dvz_texture_destroy()

Destroy a texture.

void dvz_texture_destroy(DvzTexture* texture);
Parameter Type Description
texture DvzTexture* the texture

Compute pipeline

dvz_ctx_compute()

Create a new compute pipeline.

DvzCompute* dvz_ctx_compute(DvzContext* context, char* shader_path);
Parameter Type Description
context DvzContext* the context
shader_path char* path to the .spirv file containing the compute shader

Data transfers

dvz_upload_buffers()

Upload data to 1 or N buffer regions on the GPU while the app event loop is running.

void dvz_upload_buffers(
    DvzCanvas* canvas, DvzBufferRegions br, VkDeviceSize offset,
    VkDeviceSize size, void* data);
Parameter Type Description
canvas DvzCanvas* the canvas
br DvzBufferRegions the buffer regions to update
offset VkDeviceSize the offset within the buffer regions, in bytes
size VkDeviceSize the size of the data to upload, in bytes
data void* pointer to the data to upload to the GPU

dvz_download_buffers()

Download data from a buffer region to the CPU while the app event loop is running.

void dvz_download_buffers(
    DvzCanvas* canvas, DvzBufferRegions br, VkDeviceSize offset,
    VkDeviceSize size, void* data);
Parameter Type Description
canvas DvzCanvas* the canvas
br DvzBufferRegions the buffer regions to update
offset VkDeviceSize the offset within the buffer regions, in bytes
size VkDeviceSize the size of the data to upload, in bytes
data void* pointer to a buffer already allocated to contain size bytes

dvz_copy_buffers()

Copy data between two GPU buffer regions.

void dvz_copy_buffers(
    DvzCanvas* canvas, DvzBufferRegions src, VkDeviceSize src_offset,
    DvzBufferRegions dst, VkDeviceSize dst_offset, VkDeviceSize size);
Parameter Type Description
canvas DvzCanvas* the canvas
src DvzBufferRegions the buffer region to copy from
src_offset VkDeviceSize the offset within the source buffer region
dst DvzBufferRegions the buffer region to copy to
dst_offset VkDeviceSize the offset within the target buffer region
size VkDeviceSize the size of the data to copy

This function does not involve GPU-CPU data transfers.

dvz_upload_texture()

Upload data to a texture.

void dvz_upload_texture(
    DvzCanvas* canvas, DvzTexture* texture, uvec3 offset,
    uvec3 shape, VkDeviceSize size, void* data);
Parameter Type Description
canvas DvzCanvas* the canvas
texture DvzTexture* the texture to update
offset uvec3 the offset within the texture
shape uvec3 the shape of the region to update within the texture
size VkDeviceSize the size of the uploaded data, in bytes
data void* pointer to the data to upload to the GPU

dvz_download_texture()

Download data from a texture.

void dvz_download_texture(
    DvzCanvas* canvas, DvzTexture* texture, uvec3 offset,
    uvec3 shape, VkDeviceSize size, void* data);
Parameter Type Description
canvas DvzCanvas* the canvas
texture DvzTexture* the texture to download from
offset uvec3 the offset within the texture
shape uvec3 the shape of the region to update within the texture
size VkDeviceSize the size of the downloaded data, in bytes
data void* pointer to the buffer that will hold the downloaded data

dvz_copy_texture()

Copy part of a texture to another.

void dvz_copy_texture(
    DvzCanvas* canvas, DvzTexture* src, uvec3 src_offset,
    DvzTexture* dst, uvec3 dst_offset, uvec3 shape,
    VkDeviceSize size);
Parameter Type Description
canvas DvzCanvas* the canvas
src DvzTexture* the source texture
src_offset uvec3 the offset within the source texture
dst DvzTexture* the target texture
dst_offset uvec3 the offset within the target texture
shape uvec3 the shape of the part of the texture to copy
size VkDeviceSize the corresponding size of that part, in bytes

This function does not involve GPU-CPU data transfers.

dvz_process_transfers()

Process the pending transfers.

void dvz_process_transfers(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas
br None the buffer regions to update
offset None the offset within the buffer regions, in bytes
size None the size of the data to upload, in bytes
data None pointer to the data to upload to the GPU

When the event loop is running, all transfers are enqueued in a queue rather than executed directly. The reason is that proper synchronization is required in order to avoid modifying GPU objects while they are being used for rendering. The transfer processing function is called at a deterministic time within the main event loop.