GPU context and objects¶
Context¶
dvz_context()
¶
Create a context associated to a GPU.
DvzContext* dvz_context(DvzGpu* gpu);
Parameter | Type | Description |
---|---|---|
gpu |
DvzGpu* |
the GPU |
Note
The GPU must have been created beforehand.
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_app_reset()
¶
Reset all GPUs.
void dvz_app_reset(DvzApp* app);
Parameter | Type | Description |
---|---|---|
app |
DvzApp* |
the application instance |
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, const 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_transition()
¶
Transition a texture to its layout.
void dvz_texture_transition(DvzTexture* tex);
Parameter | Type | Description |
---|---|---|
texture |
None |
the texture to transition |
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, const 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_buffer()
¶
Upload data to 1 or N buffer regions on the GPU while the app event loop is running.
void dvz_upload_buffer(
DvzContext* context, DvzBufferRegions br, VkDeviceSize offset,
VkDeviceSize size, void* data);
Parameter | Type | Description |
---|---|---|
canvas |
None |
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_buffer()
¶
Download data from a buffer region to the CPU while the app event loop is running.
void dvz_download_buffer(
DvzContext* context, DvzBufferRegions br, VkDeviceSize offset,
VkDeviceSize size, void* data);
Parameter | Type | Description |
---|---|---|
canvas |
None |
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_buffer()
¶
Copy data between two GPU buffer regions.
void dvz_copy_buffer(
DvzContext* context, DvzBufferRegions src, VkDeviceSize src_offset,
DvzBufferRegions dst, VkDeviceSize dst_offset, VkDeviceSize size);
Parameter | Type | Description |
---|---|---|
canvas |
None |
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(
DvzContext* context, DvzTexture* texture, uvec3 offset,
uvec3 shape, VkDeviceSize size, void* data);
Parameter | Type | Description |
---|---|---|
canvas |
None |
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(
DvzContext* context, DvzTexture* texture, uvec3 offset,
uvec3 shape, VkDeviceSize size, void* data);
Parameter | Type | Description |
---|---|---|
canvas |
None |
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(
DvzContext* context, DvzTexture* src, uvec3 src_offset,
DvzTexture* dst, uvec3 dst_offset, uvec3 shape,
VkDeviceSize size);
Parameter | Type | Description |
---|---|---|
canvas |
None |
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(DvzContext* context);
Parameter | Type | Description |
---|---|---|
canvas |
None |
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.