Skip to content

Scene API

App, canvas, main loop

dvz_app()

Create an application instance.

DvzApp* dvz_app(DvzBackend backend);
Parameter Type Description
backend DvzBackend the backend
returns DvzApp* pointer to the created app

There is typically only one App object in a given application. This object holds a pointer to the Vulkan instance and is responsible for discovering the available GPUs.

dvz_canvas()

Create a canvas.

DvzCanvas* dvz_canvas(DvzGpu* gpu, uint32_t width, uint32_t height, int flags);
Parameter Type Description
gpu DvzGpu* the GPU to use for swapchain presentation
width uint32_t the initial window width, in pixels
height uint32_t the initial window height, in pixels
flags int the creation flags for the canvas

dvz_canvas_dpi_scaling()

Set the DPI scaling factor of a canvas.

void dvz_canvas_dpi_scaling(DvzCanvas* canvas, float scaling);
Parameter Type Description
canvas DvzCanvas* the canvas
scaling float the scaling factor

dvz_scene()

Create a scene with a grid layout.

DvzScene* dvz_scene(DvzCanvas* canvas, uint32_t n_rows, uint32_t n_cols);
Parameter Type Description
canvas DvzCanvas* the canvas
n_rows uint32_t number of rows in the grid
n_cols uint32_t number of columns in the grid
returns DvzScene* pointer to the created scene

The scene defines a 2D grid where each cell contains a panel (subplot). Panels may support various kinds of interactivity.

dvz_app_run()

Start the main event loop.

int dvz_app_run(DvzApp* app, uint64_t frame_count);
Parameter Type Description
app DvzApp* the app
frame_count uint64_t number of frames to process (0 for infinite loop)
returns int number of active canvases at the time the function returns

Every loop iteration processes one frame of all open canvases.

dvz_scene_destroy()

Destroy a scene.

void dvz_scene_destroy(DvzScene* scene);
Parameter Type Description
scene DvzScene* the scene

Destroy all panels and visuals in the scene.

dvz_canvas_destroy()

Destroy a canvas.

void dvz_canvas_destroy(DvzCanvas* canvas);
Parameter Type Description
canvas DvzCanvas* the canvas

dvz_app_destroy()

Destroy the application.

int dvz_app_destroy(DvzApp* app);
Parameter Type Description
app DvzApp* the application to destroy

This function automatically destroys all objects created within the application.

Set panels, add visuals

dvz_scene_panel()

Add a panel to the scene grid.

DvzPanel* dvz_scene_panel(
    DvzScene* scene, uint32_t row, uint32_t col,
    DvzControllerType type, int flags);
Parameter Type Description
controller None the scene
row uint32_t the row index (0-based)
col uint32_t the column index (0-based)
type DvzControllerType the controller type
flags int flags for the builtin controller
returns DvzPanel* panel

dvz_scene_visual()

Create a builtin visual and add it to a panel.

DvzVisual* dvz_scene_visual(DvzPanel* panel, DvzVisualType type, int flags);
Parameter Type Description
panel DvzPanel* the panel
type DvzVisualType the type of visual
flags int flags for the builtin visual
returns DvzVisual* visual

Custom visuals and graphics

dvz_blank_graphics()

Create a blank graphics (used when creating custom graphics and visuals).

DvzGraphics* dvz_blank_graphics(DvzScene* scene, int flags);
Parameter Type Description
scene DvzScene* the scene
flags int graphics flags
returns DvzGraphics* blank graphics

dvz_custom_graphics()

Make a custom graphics and add it to a visual.

void dvz_custom_graphics(DvzVisual* visual, DvzGraphics* graphics);
Parameter Type Description
visual DvzVisual* a visual
graphics DvzGraphics* the custom graphics

dvz_blank_visual()

Create a blank visual (used when creating custom visuals).

DvzVisual* dvz_blank_visual(DvzScene* scene, int flags);
Parameter Type Description
scene DvzScene* the scene
flags int visual flags
returns DvzVisual* blank visual

dvz_custom_visual()

Make a custom visual and add it to a panel.

void dvz_custom_visual(DvzPanel* panel, DvzVisual* visual);
Parameter Type Description
panel DvzPanel* the panel
visual DvzVisual* the custom visual

Grid and panels

dvz_grid()

Create a grid of panels.

DvzGrid dvz_grid(DvzCanvas* canvas, uint32_t row_count, uint32_t col_count);
Parameter Type Description
canvas DvzCanvas* the canvas
row_count uint32_t the number of rows
col_count uint32_t the number of columns
returns DvzGrid grid object

dvz_grid_destroy()

Destroy a grid.

void dvz_grid_destroy(DvzGrid* grid);
Parameter Type Description
grid DvzGrid* the grid

dvz_panel()

Create a panel at a given location in a grid.

DvzPanel* dvz_panel(DvzGrid* grid, uint32_t row, uint32_t col);
Parameter Type Description
grid DvzGrid* the grid
row uint32_t the row index in the grid
col uint32_t the column index in the grid
returns DvzPanel* panel

dvz_panel_update()

Update a panel viewport.

void dvz_panel_update(DvzPanel* panel);
Parameter Type Description
panel DvzPanel* the panel

dvz_panel_margins()

Set panel margins.

void dvz_panel_margins(DvzPanel* panel, vec4 margins);
Parameter Type Description
panel DvzPanel* the panel
margins vec4 the margins, in pixels

Margins are represented as a vec4 vector: top, right, bottom, left.

dvz_panel_unit()

Set the unit in which the panel size is specified.

void dvz_panel_unit(DvzPanel* panel, DvzPanelSizeUnit unit);
Parameter Type Description
panel DvzPanel* the panel
unit DvzPanelSizeUnit the unit

dvz_panel_mode()

Set the panel mode (grid or detached).

void dvz_panel_mode(DvzPanel* panel, DvzPanelMode mode);
Parameter Type Description
panel DvzPanel* the panel
mode DvzPanelMode the mode

dvz_panel_visual()

Add a visual to a panel.

void dvz_panel_visual(DvzPanel* panel, DvzVisual* visual);
Parameter Type Description
panel DvzPanel* the panel
visual DvzVisual* the visual

dvz_panel_pos()

Set a panel position (in detached mode).

void dvz_panel_pos(DvzPanel* panel, float x, float y);
Parameter Type Description
panel DvzPanel* the panel
x float the position
y float the position

The unit in which the coordinates are specified is controller by dvz_panel_unit().

dvz_panel_size()

Set a panel size (in detached mode).

void dvz_panel_size(DvzPanel* panel, DvzGridAxis axis, float size);
Parameter Type Description
panel DvzPanel* the panel
axis DvzGridAxis the axis on which to specify the size
size float the size

The unit in which the size is specified is controller by dvz_panel_unit().

dvz_panel_span()

Set the number of cells a panel is spanning.

void dvz_panel_span(DvzPanel* panel, DvzGridAxis axis, uint32_t span);
Parameter Type Description
panel DvzPanel* the panel
axis DvzGridAxis the direction to set the span
span uint32_t the number of cells the panel spans

dvz_panel_cell()

Set the position of a panel within a grid.

void dvz_panel_cell(DvzPanel* panel, uint32_t row, uint32_t col);
Parameter Type Description
panel DvzPanel* the panel
row uint32_t the row index
col uint32_t the column index

dvz_panel_transpose()

Set the coordinate system transposition (order and direction of the 3 xyz axes).

void dvz_panel_transpose(DvzPanel* panel, DvzCDSTranspose transpose);
Parameter Type Description
panel DvzPanel* the panel
transpose DvzCDSTranspose the transposition mode

dvz_panel_contains()

Returns whether a point is contained in a panel.

bool dvz_panel_contains(DvzPanel* panel, vec2 screen_pos);
Parameter Type Description
panel DvzPanel* the panel
screen_pos vec2 the position in screen pixel coordinates
returns bool boolean

dvz_panel_at()

Return the panel at a given position within the canvas.

DvzPanel* dvz_panel_at(DvzGrid* grid, vec2 screen_pos);
Parameter Type Description
grid DvzGrid* the grid
screen_pos vec2 the position in screen pixel coordinates
returns DvzPanel* panel

dvz_panel_destroy()

Destroy a panel and all visuals inside it.

void dvz_panel_destroy(DvzPanel* panel);
Parameter Type Description
panel DvzPanel* the panel

dvz_panel_viewport()

Return the viewport of a panel.

DvzViewport dvz_panel_viewport(DvzPanel* panel);
Parameter Type Description
panel DvzPanel* the panel
returns DvzViewport viewport

Colormaps

dvz_colormap()

Fetch a color from a colormap and a value.

void dvz_colormap(DvzColormap cmap, uint8_t value, cvec4 color);
Parameter Type Description
cmap DvzColormap the colormap
value uint8_t the value
color cvec4 the fetched color

dvz_colormap_idx()

Get the texture integer coordinates corresponding to a colormap and value.

void dvz_colormap_idx(DvzColormap cmap, uint8_t value, cvec2 out);
Parameter Type Description
cmap DvzColormap the colormap
value uint8_t the value
out cvec2 the colormap coordinates within the texture

dvz_colormap_uv()

Get the texture normalized coordinates corresponding to a colormap and value.

void dvz_colormap_uv(DvzColormap cmap, uint8_t value, vec2 uv);
Parameter Type Description
cmap DvzColormap the colormap
value uint8_t the value
uv vec2 the colormap coordinates within the texture

dvz_colormap_scale()

Fetch a color from a colormap and an interpolated value.

void dvz_colormap_scale(
    DvzColormap cmap, double value, double vmin, double vmax, cvec4 color);
Parameter Type Description
cmap DvzColormap the colormap
value double the value
vmin double the minimum value
vmax double the maximum value
color cvec4 the fetched color

dvz_colormap_array()

Fetch colors from a colormap and an array of values.

void dvz_colormap_array(
    DvzColormap cmap, uint32_t count, double* values,
    double vmin, double vmax, cvec4* out);
Parameter Type Description
cmap DvzColormap the colormap
count uint32_t the number of values
values double* pointer to the array of double numbers
vmin double the minimum value
vmax double the maximum value
out cvec4* the fetched colors

dvz_colormap_packuv()

Pack an arbitrary RGB color into a special uv texture coordinates

void dvz_colormap_packuv(cvec3 color, vec2 uv);
Parameter Type Description
color cvec3 the RGB color
uv vec2 the texture coordinates

This is used by the mesh visual, that only accepts texture coordinates in its vertices. When setting the first texture coordinate to -1, the second coordinate, a float, is used to unpack 3 uint8_t RGB values. It only works because integers up to 2^24 can be represented exactly with float32.

dvz_colormap_extent()

Get the tex coords extent of a colormap.

void dvz_colormap_extent(DvzColormap cmap, vec4 uvuv);
Parameter Type Description
cmap DvzColormap the colormap
uvuv vec4 the texture coordinates of the upper-left and lower-right corners

dvz_colormap_set()

Modify a color in the colormap array (on the CPU only).

void dvz_colormap_set(uint8_t row, uint8_t col, cvec4 color);
Parameter Type Description
row uint8_t the row index in the colormap array
col uint8_t the column index in the colormap array
color cvec4 the color

dvz_colormap_custom()

Add a custom colormap.

void dvz_colormap_custom(uint8_t cmap, uint32_t color_count, cvec4* colors);
Parameter Type Description
cmap uint8_t the custom colormap index
color_count uint32_t the number of colors in the custom colormap
colors cvec4* the colors

The cmap index must be between 160 and 175 for continuous colormaps, or between 224 and 239 for categorical colormaps. The maximum number of colors in the colormap is 256.