Skip to content

Visual API

Visual creation and destruction

dvz_visual()

Create a blank visual.

DvzVisual dvz_visual(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas
returns DvzVisual visual object

dvz_visual_graphics()

Add a graphics pipeline to a visual.

void dvz_visual_graphics(DvzVisual* visual, DvzGraphics* graphics);
Parameter Type Description
visual DvzVisual* the visual
graphics DvzGraphics* the graphics

dvz_visual_compute()

Add a compute pipeline to a visual.

void dvz_visual_compute(DvzVisual* visual, DvzCompute* compute);
Parameter Type Description
visual DvzVisual* the visual
compute DvzCompute* the compute pipeline

dvz_visual_destroy()

Destroy a visual.

void dvz_visual_destroy(DvzVisual* visual);
Parameter Type Description
visual DvzVisual* the visual

This function destroys all GPU objects associated to the visual.

Visual data

dvz_visual_group()

Define a new data group within a visual.

void dvz_visual_group(DvzVisual* visual, uint32_t group_idx, uint32_t size);
Parameter Type Description
visual DvzVisual* the visual
group_idx uint32_t the group index
size uint32_t the number of elements in the group

dvz_visual_data()

Set the data for a given visual prop.

void dvz_visual_data(
    DvzVisual* visual, DvzPropType prop_type, uint32_t prop_idx,
    uint32_t count, const void* data);
Parameter Type Description
visual DvzVisual* the visual
prop_type DvzPropType the prop type
prop_idx uint32_t the prop index
count uint32_t the number of elements to upload
data void* the data, that should be in the dtype of the prop

dvz_visual_data_partial()

Set partial data for a given visual prop.

void dvz_visual_data_partial(
    DvzVisual* visual, DvzPropType prop_type, uint32_t prop_idx,
    uint32_t first_item, uint32_t item_count, uint32_t data_item_count,
    const void* data);
Parameter Type Description
visual DvzVisual* the visual
prop_type DvzPropType the prop type
prop_idx uint32_t the prop index
first_item uint32_t the first item to write to
item_count uint32_t the number of elements to update in the source array
data_item_count uint32_t the number of elements to copy from data
data void* the data, that should be in the dtype of the prop

If the specified data has less elements than the number of elements to update, the last element will be repeated as many times as necessary.

dvz_visual_data_append()

Append elements to the prop.

void dvz_visual_data_append(
    DvzVisual* visual, DvzPropType prop_type, uint32_t prop_idx,
    uint32_t count, const void* data);
Parameter Type Description
visual DvzVisual* the visual
prop_type DvzPropType the prop type
prop_idx uint32_t the prop index
count uint32_t the number of elements to append to the prop
data void* the data, that should be in the dtype of the prop

dvz_visual_data_source()

Set partial data for a given source.

void dvz_visual_data_source(
    DvzVisual* visual, DvzSourceType source_type, uint32_t source_idx,
    uint32_t first_item, uint32_t item_count, uint32_t data_item_count,
    const void* data);
Parameter Type Description
visual DvzVisual* the visual
source_type DvzSourceType the source type
source_idx uint32_t the source index
first_item uint32_t the first item to write to
item_count uint32_t the number of elements to update in the source array
data_item_count uint32_t the number of elements to copy from data
data void* the data, that should be in the dtype of the source

dvz_visual_buffer()

Set an existing GPU buffer for a visual source.

void dvz_visual_buffer(
    DvzVisual* visual, DvzSourceType source_type, uint32_t source_idx,
    DvzBufferRegions br);
Parameter Type Description
visual DvzVisual* the visual
source_type DvzSourceType the source type
source_idx uint32_t the source index
br DvzBufferRegions the buffer regions

dvz_visual_texture()

Set an existing GPU texture for a visual source.

void dvz_visual_texture(
    DvzVisual* visual, DvzSourceType source_type, uint32_t source_idx,
    DvzTexture* texture);
Parameter Type Description
visual DvzVisual* the visual
source_type DvzSourceType the source type
source_idx uint32_t the source index
texture DvzTexture* the texture

Visual sources and props

dvz_visual_source()

Define a new source for a visual.

void dvz_visual_source(
    DvzVisual* visual, DvzSourceType source_type, uint32_t source_idx,
    DvzPipelineType pipeline, uint32_t pipeline_idx, uint32_t slot_idx,
    VkDeviceSize item_size, int flags);
Parameter Type Description
visual DvzVisual* the visual
source_type DvzSourceType the source type
source_idx uint32_t the index of the source
pipeline DvzPipelineType the pipeline type
pipeline_idx uint32_t the index of the pipeline
slot_idx uint32_t the binding slot of the GPU object associated to the source
item_size VkDeviceSize the size of every element in the source data, in bytes
flags int the source creation flags

Within a given visual, a source is uniquely determined by its type and index. The index is the index of the source among all sources of the same type within the visual.

Within a given visual, a pipeline is uniquely determined by its type and index. The index is the index of the pipeline among all pipelines of the same type within the visual.

dvz_visual_source_share()

Set up a source share between two sources of the same type, in a given visual.

void dvz_visual_source_share(
    DvzVisual* visual, DvzSourceType source_type, uint32_t source_idx,
    uint32_t other_idx);
Parameter Type Description
visual DvzVisual* the visual
source_type DvzSourceType the source type
source_idx uint32_t the source index
other_idx uint32_t the index of the other source

When two sources are shared, they use the same underlying data buffer.

dvz_visual_prop()

Define a new prop for a visual.

DvzProp* dvz_visual_prop(
    DvzVisual* visual, DvzPropType prop_type, uint32_t prop_idx,
    DvzDataType dtype, DvzSourceType source_type, uint32_t source_idx);
Parameter Type Description
visual DvzVisual* the visual
prop_type DvzPropType the prop type
prop_idx uint32_t the prop index
dtype DvzDataType the data type of the prop
source_type DvzSourceType the type of the source associated to the prop
source_idx uint32_t the index of the source associated to the prop
returns DvzProp* prop object

Within a given visual, a prop is uniquely determined by its type and index. The index is the index of the prop among all props of the same type within the visual.

dvz_visual_prop_default()

Set up a default value for a prop.

void dvz_visual_prop_default(DvzProp* prop, void* default_value);
Parameter Type Description
prop DvzProp* the prop
default_value void* a pointer to the default value

dvz_visual_prop_copy()

Set up how a prop is copied to its associated source.

void dvz_visual_prop_copy(
    DvzProp* prop, uint32_t field_idx, VkDeviceSize offset,
    DvzArrayCopyType copy_type, uint32_t reps);
Parameter Type Description
prop DvzProp* the prop
field_idx uint32_t the index of the corresponding struct field in the source
offset VkDeviceSize the offset within each source item
copy_type DvzArrayCopyType the type of copy
reps uint32_t the number of repeats for each copied item

dvz_visual_prop_cast()

Set up how a prop should be cast when it is copied to its source.

void dvz_visual_prop_cast(
    DvzProp* prop, uint32_t field_idx, VkDeviceSize offset,
    DvzDataType target_dtype, DvzArrayCopyType copy_type, uint32_t reps);
Parameter Type Description
prop DvzProp* the prop
field_idx uint32_t the index of the corresponding struct field in the source
offset VkDeviceSize the offset within each source item
target_dtype DvzDataType the data type to cast to
copy_type DvzArrayCopyType the type of copy
reps uint32_t the number of repeats for each copied item

Visual fill utils and callback

dvz_visual_fill_callback()

Set a fill callback for a visual

void dvz_visual_fill_callback(
    DvzVisual* visual, DvzVisualFillCallback callback);
Parameter Type Description
visual DvzVisual* the visual
callback DvzVisualFillCallback the fill callback

Callback function signature: void(DvzVisual*, DvzVisualFillEvent)

dvz_visual_fill_event()

Call the visual fill callback.

void dvz_visual_fill_event(
    DvzVisual* visual, VkClearColorValue clear_color, DvzCommands* cmds,
    uint32_t cmd_idx, DvzViewport viewport, void* user_data);
Parameter Type Description
visual DvzVisual* the visual
clear_color VkClearColorValue the clear color
cmds DvzCommands* the command buffers to update
cmd_idx uint32_t the index of the command buffer to update
viewport DvzViewport the viewport
user_data void* arbitrary user data pointer

dvz_visual_fill_begin()

Begin recording a command buffer and begin the render pass.

void dvz_visual_fill_begin(DvzCanvas* canvas, DvzCommands* cmds, uint32_t idx);
Parameter Type Description
canvas DvzCanvas* the canvas
cmds DvzCommands* the command buffers
idx uint32_t the command buffer index

dvz_visual_fill_end()

Stop recording a command buffer and stop the render pass.

void dvz_visual_fill_end(DvzCanvas* canvas, DvzCommands* cmds, uint32_t idx);
Parameter Type Description
canvas DvzCanvas* the canvas
cmds DvzCommands* the command buffers
idx uint32_t the command buffer index

dvz_visual_callback_bake()

Set the visual bake callback function.

void dvz_visual_callback_bake(
    DvzVisual* visual, DvzVisualDataCallback callback);
Parameter Type Description
visual DvzVisual* the visual
callback DvzVisualDataCallback the bake callback function

Callback function signature: void(DvzVisual*, DvzVisualDataEvent)

Visual baking helpers

dvz_source_get()

Return a source object.

DvzSource* dvz_source_get(
    DvzVisual* visual, DvzSourceType source_type, uint32_t source_idx);
Parameter Type Description
visual DvzVisual* the visual
source_type DvzSourceType the source type
source_idx uint32_t the source index
returns DvzSource* source

dvz_prop_get()

Return a prop object.

DvzProp* dvz_prop_get(
    DvzVisual* visual, DvzPropType prop_type, uint32_t prop_idx);
Parameter Type Description
visual DvzVisual* the visual
prop_type DvzPropType the prop type
prop_idx uint32_t the prop index
returns DvzProp* array

dvz_prop_array()

Return the array of a prop.

DvzArray* dvz_prop_array(
    DvzVisual* visual, DvzPropType prop_type, uint32_t prop_idx);
Parameter Type Description
visual DvzVisual* the visual
prop_type DvzPropType the prop type
prop_idx uint32_t the prop index
returns DvzArray* array

dvz_prop_size()

Return the size of a prop array.

uint32_t dvz_prop_size(DvzProp* prop);
Parameter Type Description
prop DvzProp* the prop
returns uint32_t prop size

dvz_prop_item()

Return an item in a prop array.

void* dvz_prop_item(DvzProp* prop, uint32_t prop_idx);
Parameter Type Description
prop DvzProp* the prop
prop_idx uint32_t the prop idx
returns void* pointer to the item

Graphics pipeline

dvz_graphics_callback()

Set a graphics data callback.

void dvz_graphics_callback(
    DvzGraphics* graphics, DvzGraphicsCallback callback);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
callback DvzGraphicsCallback the callback function

The callback function is called when one calls dvz_graphics_append() on that visual. It allows one to easily add graphical elements, letting the graphics handle low-level GPU implementation details (tesselation with vertices).

Callback function signature: void(DvzGraphicsData*, uint32_t, const void*)

dvz_graphics_data()

Start a data collection for a graphics pipeline.

DvzGraphicsData dvz_graphics_data(
    DvzGraphics* graphics, DvzArray* vertices, DvzArray* indices,
    void* user_data);
Parameter Type Description
graphics DvzGraphics* the graphics pipeline
vertices DvzArray* pointer to an existing array containing vertices of the right type
indices DvzArray* pointer to an existing array containing the indices
user_data void* arbitrary user-provided pointer
returns DvzGraphicsData graphics data object

dvz_graphics_alloc()

Allocate the graphics data object with the appropriate number of elements.

void dvz_graphics_alloc(DvzGraphicsData* data, uint32_t item_count);
Parameter Type Description
data DvzGraphicsData* the graphics data object
item_count uint32_t the number of graphical items

dvz_graphics_append()

Add one graphical element after the graphics data object has been properly allocated.

void dvz_graphics_append(DvzGraphicsData* data, const void* item);
Parameter Type Description
data DvzGraphicsData* the graphics data object
item void* a pointer to an object of the appropriate graphics item type

dvz_graphics_builtin()

Create a new graphics pipeline of a given builtin type.

DvzGraphics* dvz_graphics_builtin(
    DvzCanvas* canvas, DvzGraphicsType type, int flags);
Parameter Type Description
canvas DvzCanvas* the canvas holding the grahpics pipeline
type DvzGraphicsType the graphics type
flags int the creation flags for the graphics

Visual internal system

dvz_visual_update()

Update all GPU buffers and textures from the visual props and sources.

void dvz_visual_update(
    DvzVisual* visual, DvzViewport viewport, DvzDataCoords coords,
    const void* user_data);
Parameter Type Description
visual DvzVisual* the visual
viewport DvzViewport the viewport
coords DvzDataCoords the data coordinates and transformation
user_data void* arbitrary user data pointer