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 |