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, const 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 betweenfirst_item
andfirst_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 ofdata
will be repeated until the last value.
Example:
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,
const 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(
const char* filename, uint32_t width, uint32_t height,
const 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(
const char* filename, uint32_t width, uint32_t height,
const 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(const 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(const 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(const 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(const 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, const vec3* positions,
const 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, const 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);