Using Datoviz in C¶
Datoviz is written in portable C and can be used directly in C applications for high-performance GPU visualization. The C API gives you full access to the library's core functionality, including visuals, scenes, interactivity, and rendering.
This guide shows how to build and run a simple C program with Datoviz, and how the Python API relates to it.
C API Overview¶
The C API is defined in a single public header (which includes a few other files in include/
):
#include <datoviz.h>
You create and manage:
DvzApp
andDvzBatch
: top-level context and command submissionDvzScene
,DvzFigure
,DvzPanel
: layout and interactionDvzVisual
: one of the GPU-accelerated visual types
See the C API reference for the full list of functions and types.
Python ↔ C Correspondence¶
The Datoviz Python bindings consist of:
- Low-level
ctypes
bindings that directly wrap the C library, - A high-level Python wrapper built on top, with objects like
App
,Visual
,Panel
, etc.
The mapping for the raw ctypes
bindings is:
C API | Python API |
---|---|
dvz_point_alloc(...) |
dvz.point_alloc(...) |
dvz_mock_color(...) |
dvz.mock_color(...) |
DVZ_MARKER_SHAPE_DISC |
dvz.MARKER_SHAPE_DISC |
Python functions are named the same (minus the dvz_
prefix) and constants use dvz.CONSTANT_NAME
.
Building a C Program¶
To build a C application based on Datoviz:
- Ensure Datoviz is compiled from source or use a prebuilt version (not yet available).
- Include the
datoviz/
header directory. - Specify the link directories containing
libdatoviz.so
(or the equivalent for your OS). - Link against
libdatoviz
and the standard math library.
Example (GCC):¶
gcc -std=c11 -O2 -I/path/to/datoviz/include \
my_program.c -L/path/to/datoviz/build -ldatoviz -lm -o my_program
Note
We plan to provide downloadable builds for major platforms in the future.
Full Example¶
/*************************************************************************************************/
/* Scatter plot example */
/*************************************************************************************************/
/// We import the library public header.
#include <datoviz.h>
// Entry point.
int main(int argc, char** argv)
{
// Create app object.
DvzApp* app = dvz_app(0);
DvzBatch* batch = dvz_app_batch(app);
// Create a scene.
DvzScene* scene = dvz_scene(batch);
// Create a figure.
DvzFigure* figure = dvz_figure(scene, 800, 600, 0);
// Create a panel.
DvzPanel* panel = dvz_panel_default(figure);
// Panzoom.
DvzPanzoom* pz = dvz_panel_panzoom(panel, 0);
// Create a visual.
DvzVisual* visual = dvz_point(batch, 0);
// Allocate a number of points.
const uint32_t n = 10000;
dvz_point_alloc(visual, n);
// Set the point positions.
vec3* pos = dvz_mock_pos_2D(n, 0.25);
dvz_point_position(visual, 0, n, pos, 0);
FREE(pos);
// Set the point RGBA colors.
DvzColor* color = dvz_mock_color(n, 128);
dvz_point_color(visual, 0, n, color, 0);
FREE(color);
// Set the point sizes.
float* size = dvz_mock_uniform(n, 25, 50);
dvz_point_size(visual, 0, n, size, 0);
FREE(size);
// Add the visual to the panel AFTER setting the visual's data.
dvz_panel_visual(panel, visual, 0);
// Run the app.
dvz_scene_run(scene, app, 0);
// Cleanup.
dvz_scene_destroy(scene);
dvz_app_destroy(app);
return 0;
}
This program creates a scatter plot with 10,000 points using the point visual. It uses mock data helpers for positions, colors, and sizes.
Notes¶
- C usage provides the lowest-level, most performant access to Datoviz.
- The API is designed to be clear and safe to use in systems programming.
- The auto-generated Python
ctypes
bindings is identical to this C API to ensure consistent behavior across both languages. - Most examples and documentation use the higher-level Python wrapper built on top of the
ctypes
bindings, for user convenience and to better decouple user code from the C API, which may still change with each release.