Skip to content

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 and DvzBatch: top-level context and command submission
  • DvzScene, DvzFigure, DvzPanel: layout and interaction
  • DvzVisual: 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:

  1. Low-level ctypes bindings that directly wrap the C library,
  2. 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:

  1. Ensure Datoviz is compiled from source or use a prebuilt version (not yet available).
  2. Include the datoviz/ header directory.
  3. Specify the link directories containing libdatoviz.so (or the equivalent for your OS).
  4. 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.

See Also