Common And Utility API¶

Common runtime, file I/O, font, render-type, and miscellaneous utility functions.

Status: mixed tiers; see spec/api/status.yml

This generated page lists exported C functions and their canonical public types classified by the v0.4 C API reference policy. Raw Python ctypes call forms are documented separately.

Use these functions for allocation, diagnostics, resources, file access, and shared runtime support.

Functions: 23 Types: 8

Symbol Groups¶

Group	Functions	Types	Headers
Common Types	0	4	`include/datoviz/common/types.h`
Error	1	1	`include/datoviz/common/functions.h`
File	1	0	`include/datoviz/fileio/fileio.h`
Font	2	2	`include/datoviz/font.h`
Load	2	0	`include/datoviz/fileio/fileio.h`
Log	0	1	`include/datoviz/common/functions.h`
Make	1	0	`include/datoviz/fileio/fileio.h`
Memory	1	0	`include/datoviz/common/functions.h`
Parse	1	0	`include/datoviz/fileio/fileio.h`
Read	5	0	`include/datoviz/fileio/fileio.h`
Resource	4	0	`include/datoviz/fileio/fileio.h`
Time	1	0	`include/datoviz/common/functions.h`
Version	1	0	`include/datoviz/common/version.h`
Write	3	0	`include/datoviz/fileio/fileio.h`

Grouped function index

Error

Function	Header
`dvz_error_set_callback()`	`include/datoviz/common/functions.h`

File

Function	Header
`dvz_file_size()`	`include/datoviz/fileio/fileio.h`

Font

Function	Header
`dvz_font_defaults()`	`include/datoviz/font.h`
`dvz_font_desc()`	`include/datoviz/font.h`

Load

Function	Header
`dvz_load_jpeg()`	`include/datoviz/fileio/fileio.h`
`dvz_load_png()`	`include/datoviz/fileio/fileio.h`

Make

Function	Header
`dvz_make_png()`	`include/datoviz/fileio/fileio.h`

Memory

Function	Header
`dvz_memory_free()`	`include/datoviz/common/functions.h`

Parse

Function	Header
`dvz_parse_npy()`	`include/datoviz/fileio/fileio.h`

Read

Function	Header
`dvz_read_file()`	`include/datoviz/fileio/fileio.h`
`dvz_read_gz()`	`include/datoviz/fileio/fileio.h`
`dvz_read_jpeg()`	`include/datoviz/fileio/fileio.h`
`dvz_read_npy()`	`include/datoviz/fileio/fileio.h`
`dvz_read_ppm()`	`include/datoviz/fileio/fileio.h`

Resource

Function	Header
`dvz_resource_font()`	`include/datoviz/fileio/fileio.h`
`dvz_resource_glsl()`	`include/datoviz/fileio/fileio.h`
`dvz_resource_shader()`	`include/datoviz/fileio/fileio.h`
`dvz_resource_wgsl()`	`include/datoviz/fileio/fileio.h`

Time

Function	Header
`dvz_time_monotonic_ns()`	`include/datoviz/common/functions.h`

Version

Function	Header
`dvz_version()`	`include/datoviz/common/version.h`

Write

Function	Header
`dvz_write_bytes()`	`include/datoviz/fileio/fileio.h`
`dvz_write_png()`	`include/datoviz/fileio/fileio.h`
`dvz_write_ppm()`	`include/datoviz/fileio/fileio.h`

Common Types¶

Types

DvzColor · record

struct DvzColor {
    uint8_t r;
    uint8_t g;
    uint8_t b;
    uint8_t a;
};

Declared in include/datoviz/common/types.h:51.

DvzColorf · record

struct DvzColorf {
    float r;
    float g;
    float b;
    float a;
};

Declared in include/datoviz/common/types.h:61.

DvzResult · typedef

typedef int32_t DvzResult;

Declared in include/datoviz/common/types.h:34.

DvzTime · record

struct DvzTime {
    uint64_t seconds;
    uint64_t nanoseconds;
};

Declared in include/datoviz/common/types.h:71.

Error¶

Functions

`dvz_error_set_callback()`¶

Register or clear the process-wide error callback.

The callback and borrowed user data must remain valid until replaced or cleared. Passing NULL for @p cb clears the callback.

DvzResult dvz_error_set_callback(
    DvzErrorCallback cb,
    void * user_data
);

Field	Type	Description
return	`DvzResult`	DVZ_OK on success
`cb`	`DvzErrorCallback`	callback invoked for Datoviz errors, or NULL to clear the current callback
`user_data`	`void` *	borrowed opaque pointer passed unchanged to @p cb; may be NULL

Declared in include/datoviz/common/functions.h:60.

Types

DvzErrorCallback · typedef

typedef void (*)(DvzLogLevel, const char *, void *) DvzErrorCallback;

Declared in include/datoviz/common/functions.h:39.

File¶

Functions

`dvz_file_size()`¶

Return the size of a file.

DvzSize dvz_file_size(
    const char * filename
);

Field	Type	Description
return	`DvzSize`	file size in bytes, or zero if the file cannot be opened (also valid for an empty file)
`filename`	`const` `char` *	path of the file; must not be NULL

Declared in include/datoviz/fileio/fileio.h:42.

Font¶

Functions

`dvz_font_defaults()`¶

Return Datoviz's shared default font policy.

The returned descriptors use borrowed static strings. Runtime consumers build their own backend font objects from this policy; ImGui fonts and scene text atlas fonts are not shared.

DvzFontDefaults dvz_font_defaults(void);

Field	Type	Description
return	`DvzFontDefaults`	default font policy

Declared in include/datoviz/font.h:86.

`dvz_font_desc()`¶

Return an empty font descriptor.

DvzFontDesc dvz_font_desc(void);

Field	Type	Description
return	`DvzFontDesc`	default font descriptor

Declared in include/datoviz/font.h:75.

Types

DvzFontDefaults · record

struct DvzFontDefaults {
    uint32_t struct_size;
    uint32_t flags;
    const char * sans_path;
    const char * sans_family;
    const char * sans_style;
    uint32_t sans_face_index;
    uint32_t sans_font_flags;
    const char * mono_path;
    const char * mono_family;
    const char * mono_style;
    uint32_t mono_face_index;
    uint32_t mono_font_flags;
    float ui_size_px;
    float mono_size_px;
    float text_size_px;
};

Declared in include/datoviz/font.h:42.

DvzFontDesc · record

struct DvzFontDesc {
    uint32_t struct_size;
    uint32_t flags;
    const char * path;
    const char * family;
    const char * style;
    uint32_t face_index;
    uint32_t font_flags;
};

Declared in include/datoviz/font.h:29.

Load¶

Functions

`dvz_load_jpeg()`¶

Decode a JPEG image from memory into tightly packed RGBA8 pixels.

uint8_t * dvz_load_jpeg(
    const void * bytes,
    DvzSize size_bytes,
    uint32_t * width,
    uint32_t * height
);

Field	Type	Description
return	`uint8_t` *	owned RGBA8 pixel buffer, or NULL on failure; free with `dvz_memory_free()`
`bytes`	`const` `void` *	complete JPEG byte buffer; must not be NULL
`size_bytes`	`DvzSize`	size of the JPEG byte buffer in bytes
`width`	`uint32_t` *
`height`	`uint32_t` *

Declared in include/datoviz/fileio/fileio.h:204.

`dvz_load_png()`¶

Decode a PNG image from memory into tightly packed RGB8 pixels.

uint8_t * dvz_load_png(
    const void * bytes,
    DvzSize size_bytes,
    uint32_t * width,
    uint32_t * height
);

Field	Type	Description
return	`uint8_t` *	owned RGB8 pixel buffer, or NULL on decode failure; free with `dvz_memory_free()`
`bytes`	`const` `void` *	complete PNG byte buffer; must not be NULL
`size_bytes`	`DvzSize`	size of the PNG byte buffer in bytes
`width`	`uint32_t` *
`height`	`uint32_t` *

Declared in include/datoviz/fileio/fileio.h:186.

Log¶

Types

DvzLogLevel · enum

enum DvzLogLevel {
    DVZ_LOG_LEVEL_ERROR = 0,
    DVZ_LOG_LEVEL_WARNING = 1,
    DVZ_LOG_LEVEL_INFO = 2,
};

Declared in include/datoviz/common/functions.h:30.

Make¶

Functions

`dvz_make_png()`¶

Compress an sRGB RGB8 image to PNG and write it to a memory buffer.

buffer must be freed with dvz_memory_free()

int dvz_make_png(
    uint32_t width,
    uint32_t height,
    const uint8_t * rgb,
    DvzSize * size,
    void ** out
);

Field	Type	Description
return	`int`	zero after the encode attempt
`width`	`uint32_t`	image width in pixels; must be positive
`height`	`uint32_t`	image height in pixels; must be positive
`rgb`	`const` `uint8_t` *	tightly packed sRGB RGB8 pixels containing `width * height * 3` bytes; must not be NULL
`size`	`DvzSize` *
`out`	`void` **

Declared in include/datoviz/fileio/fileio.h:172.

Memory¶

Functions

`dvz_memory_free()`¶

Release memory returned by Datoviz public APIs.

Use this function for owned buffers returned through public API calls such as file loading, shader compilation, screenshots, and readbacks. Passing NULL is allowed.

void dvz_memory_free(
    void * pointer
);

Field	Type	Description
`pointer`	`void` *	pointer returned by a Datoviz public API, or NULL

Declared in include/datoviz/common/functions.h:71.

Parse¶

Functions

`dvz_parse_npy()`¶

Extract the data payload from an in-memory NumPy NPY v1 buffer.

This minimal parser validates the magic and payload offset but does not expose or convert the array dtype, shape, byte order, or storage order.

void * dvz_parse_npy(
    const void * bytes,
    DvzSize size_bytes
);

Field	Type	Description
return	`void` *	owned copy of the array payload, or NULL for invalid input or allocation failure; free with `dvz_memory_free()`
`bytes`	`const` `void` *	complete NPY file bytes; must not be NULL
`size_bytes`	`DvzSize`	size of @p bytes in bytes

Declared in include/datoviz/fileio/fileio.h:83.

Read¶

Functions

`dvz_read_file()`¶

Read a binary file.

void * dvz_read_file(
    const char * filename,
    DvzSize * size
);

Field	Type	Description
return	`void` *	owned byte buffer, or NULL if the file cannot be opened; free with `dvz_memory_free()`
`filename`	`const` `char` *	path of the file to open; must not be NULL
`size`	`DvzSize` *

Declared in include/datoviz/fileio/fileio.h:53.

`dvz_read_gz()`¶

Read a compressed GZIP file.

zlib support is enabled

char * dvz_read_gz(
    const char * filename,
    DvzSize * size
);

Field	Type	Description
return	`char` *	owned decompressed byte buffer, or NULL on failure or when zlib support is unavailable; free with `dvz_memory_free()`
`filename`	`const` `char` *	path of the GZIP-compressed file; must not be NULL
`size`	`DvzSize` *

Declared in include/datoviz/fileio/fileio.h:96.

`dvz_read_jpeg()`¶

Read and decode a JPEG image file into tightly packed RGBA8 pixels.

uint8_t * dvz_read_jpeg(
    const char * filename,
    uint32_t * width,
    uint32_t * height
);

Field	Type	Description
return	`uint8_t` *	owned RGBA8 pixel buffer, or NULL on failure; free with `dvz_memory_free()`
`filename`	`const` `char` *	source JPEG file path; must not be NULL
`width`	`uint32_t` *
`height`	`uint32_t` *

Declared in include/datoviz/fileio/fileio.h:216.

`dvz_read_npy()`¶

Read the data payload of a NumPy NPY v1 file.

This minimal reader strips the NPY header but does not expose or convert the array dtype, shape, byte order, or storage order.

void * dvz_read_npy(
    const char * filename,
    DvzSize * size
);

Field	Type	Description
return	`void` *	owned buffer containing the array payload, or NULL on failure; free with `dvz_memory_free()`
`filename`	`const` `char` *	path of the file to open; must not be NULL
`size`	`DvzSize` *

Declared in include/datoviz/fileio/fileio.h:68.

`dvz_read_ppm()`¶

Read a PPM image file.

uint8_t * dvz_read_ppm(
    const char * filename,
    uint32_t * width,
    uint32_t * height
);

Field	Type	Description
return	`uint8_t` *	owned tightly packed RGB8 pixel buffer, or NULL on failure; free with `dvz_memory_free()`
`filename`	`const` `char` *	source P6 PPM file path; must not be NULL
`width`	`uint32_t` *
`height`	`uint32_t` *

Declared in include/datoviz/fileio/fileio.h:141.

Resource¶

Functions

`dvz_resource_font()`¶

Look up an embedded font resource by name.

const unsigned char * dvz_resource_font(
    const char * name,
    DvzSize * size
);

Field	Type	Description
return	`const` `unsigned` `char` *	borrowed immutable font bytes with static lifetime, or NULL if @p name is not found
`name`	`const` `char` *	resource name without a file extension; must not be NULL
`size`	`DvzSize` *

Declared in include/datoviz/fileio/fileio.h:262.

`dvz_resource_glsl()`¶

Look up an embedded GLSL shader source by name.

const char * dvz_resource_glsl(
    const char * name,
    DvzSize * size
);

Field	Type	Description
return	`const` `char` *	borrowed immutable source bytes with static lifetime, or NULL if @p name is not found
`name`	`const` `char` *	resource name without a file extension; must not be NULL
`size`	`DvzSize` *

Declared in include/datoviz/fileio/fileio.h:251.

`dvz_resource_shader()`¶

Look up an embedded SPIR-V shader resource by name.

const unsigned char * dvz_resource_shader(
    const char * name,
    DvzSize * size
);

Field	Type	Description
return	`const` `unsigned` `char` *	borrowed immutable bytes with static lifetime, or NULL if @p name is not found
`name`	`const` `char` *	resource name without a file extension; must not be NULL
`size`	`DvzSize` *

Declared in include/datoviz/fileio/fileio.h:231.

`dvz_resource_wgsl()`¶

Look up an embedded WGSL shader source by name.

const char * dvz_resource_wgsl(
    const char * name,
    DvzSize * size
);

Field	Type	Description
return	`const` `char` *	borrowed immutable source bytes with static lifetime, or NULL if @p name is not found
`name`	`const` `char` *	resource name without a file extension; must not be NULL
`size`	`DvzSize` *

Declared in include/datoviz/fileio/fileio.h:241.

Time¶

Functions

`dvz_time_monotonic_ns()`¶

Return a monotonic timestamp in nanoseconds.

uint64_t dvz_time_monotonic_ns(void);

Field	Type	Description
return	`uint64_t`	monotonic timestamp in nanoseconds

Declared in include/datoviz/common/functions.h:79.

Version¶

Functions

`dvz_version()`¶

Return the current version string.

const char * dvz_version(void);

Field	Type	Description
return	`const` `char` *	borrowed, null-terminated version string with static lifetime

Declared in include/datoviz/common/version.h:69.

Write¶

Functions

`dvz_write_bytes()`¶

Write bytes to a file.

int dvz_write_bytes(
    const char * filename,
    const char * mode,
    DvzSize size,
    const uint8_t * bytes
);

Field	Type	Description
return	`int`	zero if the file was opened, nonzero otherwise; write errors are not reported
`filename`	`const` `char` *	destination file path; must not be NULL
`mode`	`const` `char` *	standard `fopen()` mode, typically `"wb"` or `"ab"`; must not be NULL
`size`	`DvzSize`	number of bytes to write
`bytes`	`const` `uint8_t` *	source buffer containing at least @p size bytes; must not be NULL when size is nonzero

Declared in include/datoviz/fileio/fileio.h:110.

`dvz_write_png()`¶

Save an sRGB RGBA8 image to a PNG file.

int dvz_write_png(
    const char * filename,
    uint32_t width,
    uint32_t height,
    const uint8_t * rgba
);

Field	Type	Description
return	`int`	zero after the encode attempt
`filename`	`const` `char` *	destination PNG file path; must not be NULL
`width`	`uint32_t`	image width in pixels; must be positive
`height`	`uint32_t`	image height in pixels; must be positive
`rgba`	`const` `uint8_t` *	tightly packed sRGB RGBA8 pixels with straight linear alpha; must contain `width * height * 4` bytes

Declared in include/datoviz/fileio/fileio.h:156.

`dvz_write_ppm()`¶

Save an image to a PPM file (short ASCII header and flat binary RGB values).

int dvz_write_ppm(
    const char * filename,
    uint32_t width,
    uint32_t height,
    const uint8_t * image
);

Field	Type	Description
return	`int`	zero if the file was opened, nonzero otherwise; write errors are not reported
`filename`	`const` `char` *	destination PPM file path; must not be NULL
`width`	`uint32_t`	image width in pixels
`height`	`uint32_t`	image height in pixels
`image`	`const` `uint8_t` *	tightly packed RGB8 pixels containing `width * height * 3` bytes; must not be NULL

Declared in include/datoviz/fileio/fileio.h:128.

Common And Utility API¶

Symbol Groups¶

Common Types¶

Error¶

dvz_error_set_callback()¶

File¶

dvz_file_size()¶

Font¶

dvz_font_defaults()¶

dvz_font_desc()¶

Load¶

dvz_load_jpeg()¶

dvz_load_png()¶

Log¶

Make¶

dvz_make_png()¶

Memory¶

dvz_memory_free()¶

Parse¶

dvz_parse_npy()¶

Read¶

dvz_read_file()¶

dvz_read_gz()¶

dvz_read_jpeg()¶

dvz_read_npy()¶

dvz_read_ppm()¶

Resource¶

dvz_resource_font()¶

dvz_resource_glsl()¶

dvz_resource_shader()¶

dvz_resource_wgsl()¶

Time¶

dvz_time_monotonic_ns()¶

Version¶

dvz_version()¶

Write¶

dvz_write_bytes()¶

dvz_write_png()¶

dvz_write_ppm()¶

`dvz_error_set_callback()`¶

`dvz_file_size()`¶

`dvz_font_defaults()`¶

`dvz_font_desc()`¶

`dvz_load_jpeg()`¶

`dvz_load_png()`¶

`dvz_make_png()`¶

`dvz_memory_free()`¶

`dvz_parse_npy()`¶

`dvz_read_file()`¶

`dvz_read_gz()`¶

`dvz_read_jpeg()`¶

`dvz_read_npy()`¶

`dvz_read_ppm()`¶

`dvz_resource_font()`¶

`dvz_resource_glsl()`¶

`dvz_resource_shader()`¶

`dvz_resource_wgsl()`¶

`dvz_time_monotonic_ns()`¶

`dvz_version()`¶

`dvz_write_bytes()`¶

`dvz_write_png()`¶

`dvz_write_ppm()`¶