Skip to content

Misc API

Array

dvz_array()

Create a new 1D array.

DvzArray dvz_array(uint32_t item_count, DvzDataType dtype);
Parameter Type Description
item_count uint32_t initial number of elements
dtype DvzDataType the data type of the array
returns DvzArray new array

dvz_array_point()

Create an array with a single dvec3 position.

DvzArray dvz_array_point(dvec3 pos);
Parameter Type Description
pos dvec3 initial number of elements
returns DvzArray new array

dvz_array_wrap()

Create a 1D array from an existing compatible memory buffer.

DvzArray dvz_array_wrap(uint32_t item_count, DvzDataType dtype, void* data);
Parameter Type Description
item_count uint32_t number of elements in the passed buffer
dtype DvzDataType the data type of the array
returns DvzArray array wrapping the buffer

The created array does not allocate memory, it uses the passed buffer instead.

Warning

Destroying the array will free the passed pointer!

dvz_array_struct()

Create a 1D record array with heterogeneous data type.

DvzArray dvz_array_struct(uint32_t item_count, VkDeviceSize item_size);
Parameter Type Description
item_count uint32_t number of elements
item_size VkDeviceSize size, in bytes, of each item
returns DvzArray array

dvz_array_3D()

Create a 3D array holding a texture.

DvzArray dvz_array_3D(
    uint32_t ndims, uint32_t width, uint32_t height,
    uint32_t depth, VkDeviceSize item_size);
Parameter Type Description
ndims uint32_t number of dimensions (1, 2, 3)
width uint32_t number of elements along the 1st dimension
height uint32_t number of elements along the 2nd dimension
depth uint32_t number of elements along the 3rd dimension
item_size VkDeviceSize size of each item in bytes
returns DvzArray array

dvz_array_resize()

Resize an existing array.

void dvz_array_resize(DvzArray* array, uint32_t item_count);
Parameter Type Description
array DvzArray* the array to resize
item_count uint32_t the new number of items
  • If the new size is equal to the old size, do nothing.
  • If the new size is smaller than the old size, change the size attribute but do not reallocate
  • If the new size is larger than the old size, reallocate memory and copy over the old values

dvz_array_clear()

Reset to 0 the contents of an existing array.

void dvz_array_clear(DvzArray* array);
Parameter Type Description
array DvzArray* the array to clear

dvz_array_reshape()

Reshape a 3D array and delete all the data in it.

void dvz_array_reshape(
    DvzArray* array, uint32_t width, uint32_t height, uint32_t depth);
Parameter Type Description
array DvzArray* the array to reshape and clear
width uint32_t number of elements along the 1st dimension
height uint32_t number of elements along the 2nd dimension
depth uint32_t number of elements along the 3rd dimension

Warning

The contents of the array will be cleared. Copying the existing data would require more work and is not necessary at the moment.

dvz_array_data()

Copy data into an array.

void dvz_array_data(
    DvzArray* array, uint32_t first_item, uint32_t item_count,
    uint32_t data_item_count, void* data);
Parameter Type Description
array DvzArray* the array
first_item uint32_t first element in the array to be overwritten
item_count uint32_t number of items to write
data_item_count uint32_t number of elements in data
data void* the buffer containing the data to copy
  • There will be item_count values copied between first_item and first_item + item_count in the array.
  • There are data_item_count values in the passed buffer.
  • If item_count > data_item_count, the last value of data will be repeated until the last value.

Example:

// Create an array of 10 double numbers, initialize all elements with 1.23.
DvzArray arr = dvz_array(10, DVZ_DTYPE_DOUBLE);
double item = 1.23;
dvz_array_data(&arr, 0, 10, 1, &item);

dvz_array_item()

Retrieve a single element from an array.

void* dvz_array_item(DvzArray* array, uint32_t idx);
Parameter Type Description
array DvzArray* the array
idx uint32_t the index of the element to retrieve
returns void* pointer to the requested element

dvz_array_column()

Copy data into the column of a record array.

void dvz_array_column(
    DvzArray* array, VkDeviceSize offset, VkDeviceSize col_size,
    uint32_t first_item, uint32_t item_count, uint32_t data_item_count,
    void* data, DvzDataType source_dtype, DvzDataType target_dtype,
    DvzArrayCopyType copy_type, uint32_t reps);
Parameter Type Description
array DvzArray* the array
offset VkDeviceSize the offset within the array, in bytes
col_size VkDeviceSize stride in the source array, in bytes
first_item uint32_t first element in the array to be overwritten
item_count uint32_t number of elements to write
data_item_count uint32_t number of elements in data
data void* the buffer containing the data to copy
source_dtype DvzDataType the source dtype (only used when casting)
target_dtype DvzDataType the target dtype (only used when casting)
copy_type DvzArrayCopyType the type of copy
reps uint32_t the number of repeats for each copied element

This function is used by the default visual baking function, which copies to the vertex buffer (corresponding to a record array with as many fields as GLSL attributes in the vertex shader) the user-specified visual props (data for the individual elements).

dvz_array_insert()

Insert data in an array.

void dvz_array_insert(
    DvzArray* array, uint32_t offset, uint32_t size, void* insert);
Parameter Type Description
array DvzArray* the array
offset uint32_t the index of the first element of the inserted data in the new array
size uint32_t the number of elements to insert
insert void* the data to insert

dvz_array_copy_region()

Copy a region of an array into another.

void dvz_array_copy_region(
    DvzArray* src_arr, DvzArray* dst_arr, uint32_t src_offset,
    uint32_t dst_offset, uint32_t item_count);
Parameter Type Description
src_arr DvzArray* the source array
dst_arr DvzArray* the destination array
src_offset uint32_t the index, in the source array, of the first item to copy
dst_offset uint32_t the destination index
item_count uint32_t the number of items to copy

dvz_array_destroy()

Destroy an array.

void dvz_array_destroy(DvzArray* array);
Parameter Type Description
array DvzArray* the array to destroy

This function frees the allocated underlying data buffer.

Object

dvz_obj_init()

Initialize an object.

void dvz_obj_init(DvzObject* obj);
Parameter Type Description
obj DvzObject* the object

Memory for the object has been allocated and its fields properly initialized.

dvz_obj_created()

Mark an object as successfully created on the GPU.

void dvz_obj_created(DvzObject* obj);
Parameter Type Description
obj DvzObject* the object

dvz_obj_destroyed()

Mark an object as destroyed.

void dvz_obj_destroyed(DvzObject* obj);
Parameter Type Description
obj DvzObject* the object

dvz_obj_is_created()

Whether an object has been successfully created.

bool dvz_obj_is_created(DvzObject* obj);
Parameter Type Description
obj DvzObject* the object
returns bool boolean indicated whether the object has been successfully created

Container

dvz_container()

Create a container that will contain an arbitrary number of objects of the same type.

DvzContainer dvz_container(
    uint32_t count, size_t item_size, DvzObjectType type);
Parameter Type Description
count uint32_t initial number of objects in the container
item_size size_t size of each object, in bytes
type DvzObjectType object type

dvz_container_delete_if_destroyed()

Free a given object in the constainer if it was previously destroyed.

void dvz_container_delete_if_destroyed(DvzContainer* container, uint32_t idx);
Parameter Type Description
container DvzContainer* the container
idx uint32_t the index of the object within the container

dvz_container_alloc()

Get a pointer to a new object in the container.

void* dvz_container_alloc(DvzContainer* container);
Parameter Type Description
container DvzContainer* the container
returns void* pointer to an allocated object

If the container is full, it will be automatically resized.

dvz_container_get()

Return the object at a given index.

void* dvz_container_get(DvzContainer* container, uint32_t idx);
Parameter Type Description
container DvzContainer* the container
idx uint32_t the index of the object within the container
returns None a pointer to the object at the specified index

dvz_container_iterator()

Start a loop iteration over all valid objects within the container.

DvzContainerIterator dvz_container_iterator(DvzContainer* container);
Parameter Type Description
container DvzContainer* the container
returns DvzContainerIterator pointer to the first object

dvz_container_iter()

Continue an already-started loop iteration on a container.

void dvz_container_iter(DvzContainerIterator* iterator);
Parameter Type Description
container None the container
returns void pointer to the next object in the container, or NULL at the end

dvz_container_destroy()

Destroy a container.

void dvz_container_destroy(DvzContainer* container);
Parameter Type Description
container DvzContainer* the container
idx None the index of the object within the container

Free all remaining objects, as well as the container itself.

Warning

All objects in the container must have been destroyed beforehand, since the generic container does not know how to properly destroy objects that were created with Vulkan.

I/O

dvz_write_png()

Save an image to a PNG file

int dvz_write_png(
    char* filename, uint32_t width, uint32_t height, uint8_t* image);
Parameter Type Description
filename char* path to the PNG file to create
width uint32_t width of the image
height uint32_t height of the image
image uint8_t* pointer to an array of 32-bit RGBA values

dvz_write_ppm()

Save an image to a PPM file (short ASCII header and flat binary RGBA values).

int dvz_write_ppm(
    char* filename, uint32_t width, uint32_t height, uint8_t* image);
Parameter Type Description
filename char* path to the PPM file to create
width uint32_t width of the image
height uint32_t height of the image
image uint8_t* pointer to an array of 32-bit RGBA values

dvz_read_file()

Read a binary file.

uint32_t* dvz_read_file(char* filename, size_t* size);
Parameter Type Description
filename char* path of the file to open
size size_t* of the file
returns uint32_t* to a byte buffer with the file contents

dvz_read_npy()

Read a NumPy NPY file.

char* dvz_read_npy(char* filename, size_t* size);
Parameter Type Description
filename char* path of the file to open
size size_t* of the file
returns char* to a buffer containing the array elements

dvz_read_ppm()

Read a PPM image file.

uint8_t* dvz_read_ppm(char* filename, int* width, int* height);
Parameter Type Description
filename char* path of the file to open
width int* width of the image
height int* of the image
returns uint8_t* to a buffer with the loaded RGBA pixel colors

Thread

dvz_thread()

Create a thread.

DvzThread dvz_thread(DvzThreadCallback callback, void* user_data);
Parameter Type Description
callback DvzThreadCallback the function that will run in a background thread
user_data void* a pointer to arbitrary user data
returns DvzThread object

Callback function signature: void*(void*)

dvz_thread_lock()

Acquire a mutex lock associated to the thread.

void dvz_thread_lock(DvzThread* thread);
Parameter Type Description
thread DvzThread* the thread

dvz_thread_unlock()

Release a mutex lock associated to the thread.

void dvz_thread_unlock(DvzThread* thread);
Parameter Type Description
thread DvzThread* the thread

dvz_thread_join()

Destroy a thread after the thread function has finished running.

void dvz_thread_join(DvzThread* thread);
Parameter Type Description
thread DvzThread* the thread

FIFO queue

dvz_fifo()

Create a FIFO queue.

DvzFifo dvz_fifo(int32_t capacity);
Parameter Type Description
capacity int32_t the maximum size
returns DvzFifo FIFO queue

dvz_fifo_enqueue()

Enqueue an object in a queue.

void dvz_fifo_enqueue(DvzFifo* fifo, void* item);
Parameter Type Description
fifo DvzFifo* the FIFO queue
item void* the pointer to the object to enqueue

dvz_fifo_dequeue()

Dequeue an object from a queue.

void* dvz_fifo_dequeue(DvzFifo* fifo, bool wait);
Parameter Type Description
fifo DvzFifo* the FIFO queue
wait bool whether to return immediately, or wait until the queue is non-empty
returns void* pointer to the dequeued object, or NULL if the queue is empty

dvz_fifo_size()

Get the number of items in a queue.

int dvz_fifo_size(DvzFifo* fifo);
Parameter Type Description
fifo DvzFifo* the FIFO queue
returns int number of elements in the queue

dvz_fifo_discard()

Discard old items in a queue.

void dvz_fifo_discard(DvzFifo* fifo, int max_size);
Parameter Type Description
fifo DvzFifo* the FIFO queue
max_size int the number of items to keep in the queue.

This function will suppress all items in the queue except the max_size most recent ones.

dvz_fifo_reset()

Delete all items in a queue.

void dvz_fifo_reset(DvzFifo* fifo);
Parameter Type Description
fifo DvzFifo* the FIFO queue

dvz_fifo_destroy()

Destroy a queue.

void dvz_fifo_destroy(DvzFifo* fifo);
Parameter Type Description
fifo DvzFifo* the FIFO queue

Mesh

dvz_mesh()

Create a new mesh.

DvzMesh dvz_mesh(void );

| returns | DvzMesh | mesh object |

A mesh is represented by an array of vertices of type DvzGraphicsMeshVertex and indices, where every triplet of vertex indices represents a triangular face of the mesh.

dvz_mesh_obj()

Load an OBJ mesh.

DvzMesh dvz_mesh_obj(char* file_path);
Parameter Type Description
file_path char* the path to the .obj file
returns DvzMesh mesh

dvz_mesh_grid()

Create a grid mesh.

DvzMesh dvz_mesh_grid(
    uint32_t row_count, uint32_t col_count, vec3* positions,
    vec2* texcoords);
Parameter Type Description
row_count uint32_t number of rows
col_count uint32_t number of columns
positions vec3* the 3D position of each vertex in the grid
texcoords vec2* the texture coordinates of each vertex
returns DvzMesh mesh object

The positions buffer should contain row_count * col_count vec3 positions (C order).

dvz_mesh_surface()

Create a surface mesh.

DvzMesh dvz_mesh_surface(
    uint32_t row_count, uint32_t col_count, float* heights);
Parameter Type Description
row_count uint32_t number of rows
col_count uint32_t number of columns
heights float* the height of each vertex in the grid
returns DvzMesh mesh object

The heights buffer should contain row_count * col_count float positions (C order).

dvz_mesh_cube()

Create a unit cube mesh (ranging [-0.5, +0.5]).

DvzMesh dvz_mesh_cube(void );

| returns | DvzMesh | mesh object |

dvz_mesh_sphere()

Create a sphere mesh.

DvzMesh dvz_mesh_sphere(uint32_t row_count, uint32_t col_count);
Parameter Type Description
row_count uint32_t number of rows
col_count uint32_t number of columns
returns DvzMesh mesh object

dvz_mesh_cylinder()

Create a cylinder mesh.

DvzMesh dvz_mesh_cylinder(uint32_t count);
Parameter Type Description
count uint32_t number of sides
returns DvzMesh mesh object

dvz_mesh_cone()

Create a cone mesh.

DvzMesh dvz_mesh_cone(uint32_t count);
Parameter Type Description
count uint32_t number of sides
returns DvzMesh mesh object

dvz_mesh_square()

Create a square mesh.

DvzMesh dvz_mesh_square(void );

| returns | DvzMesh | mesh object |

dvz_mesh_disc()

Create a disc mesh.

DvzMesh dvz_mesh_disc(uint32_t count);
Parameter Type Description
count uint32_t number of sides
returns DvzMesh mesh object

dvz_mesh_normalize()

Normalize a mesh.

void dvz_mesh_normalize(DvzMesh* mesh);
Parameter Type Description
mesh DvzMesh* the mesh

dvz_mesh_destroy()

Destroy a mesh.

void dvz_mesh_destroy(DvzMesh* mesh);
Parameter Type Description
mesh DvzMesh* the mesh

Mesh transform

dvz_mesh_transform_reset()

Reset the mesh transformation.

void dvz_mesh_transform_reset(DvzMesh* mesh);
Parameter Type Description
mesh DvzMesh* the mesh

dvz_mesh_transform_add()

Append a mesh transformation.

void dvz_mesh_transform_add(DvzMesh* mesh, mat4 transform);
Parameter Type Description
mesh DvzMesh* the mesh
transform mat4 the transform matrix

dvz_mesh_translate()

Append a translation transformation.

void dvz_mesh_translate(DvzMesh* mesh, vec3 translate);
Parameter Type Description
mesh DvzMesh* the mesh
translate vec3 the translation vector

dvz_mesh_scale()

Append a scaling transformation.

void dvz_mesh_scale(DvzMesh* mesh, vec3 scale);
Parameter Type Description
mesh DvzMesh* the mesh
scale vec3 the scaling coefficients

dvz_mesh_rotate()

Append a rotation transformation.

void dvz_mesh_rotate(DvzMesh* mesh, float angle, vec3 axis);
Parameter Type Description
mesh DvzMesh* the mesh
angle float the rotation angle
axis vec3 the rotation axis

dvz_mesh_transform()

Apply the transformation matrix to a mesh.

void dvz_mesh_transform(DvzMesh* mesh);
Parameter Type Description
mesh DvzMesh* the mesh

Random

dvz_rand_byte()

Return a random integer number between 0 and 255.

uint8_t dvz_rand_byte(void );

| returns | uint8_t | number |

dvz_rand_float()

Return a random floating-point number between 0 and 1.

float dvz_rand_float(void );

| returns | float | number |

dvz_rand_normal()

Return a random normal floating-point number.

float dvz_rand_normal(void );

| returns | float | number |

Misc

dvz_sleep()

Wait a given number of milliseconds.

void dvz_sleep(int milliseconds);
Parameter Type Description
milliseconds int sleep duration

dvz_next_pow2()

uint64_t dvz_next_pow2(uint64_t x);