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.