Skip to content

Math API

Boxes, vectors, animation curves, pseudo-random generation, and statistical helpers.

Status: stable

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 helpers for numeric work shared by scene, controller, and runtime integrations.

Functions: 33 Types: 46

Symbol Groups

Group Functions Types Headers
Box 10 3 include/datoviz/math/box.h
Dim 0 1 include/datoviz/math/dim.h
Dmat4 8 0 include/datoviz/math/vec.h
Dvec3 2 0 include/datoviz/math/vec.h
Dvec4 2 0 include/datoviz/math/vec.h
Easing 1 1 include/datoviz/math/anim.h
Mean 1 0 include/datoviz/math/stats.h
Min 1 0 include/datoviz/math/stats.h
Normalize 1 0 include/datoviz/math/stats.h
Prng 3 1 include/datoviz/math/prng.h
Range 1 0 include/datoviz/math/stats.h
Scalar And Vector Types 0 40 include/datoviz/math/types.h
Vec2 1 0 include/datoviz/math/vec.h
Vec3 2 0 include/datoviz/math/vec.h
Grouped function index

Box

Function Header
dvz_box() include/datoviz/math/box.h
dvz_box_aspect() include/datoviz/math/box.h
dvz_box_center() include/datoviz/math/box.h
dvz_box_extent() include/datoviz/math/box.h
dvz_box_inverse() include/datoviz/math/box.h
dvz_box_merge() include/datoviz/math/box.h
dvz_box_normalize_1D() include/datoviz/math/box.h
dvz_box_normalize_2D() include/datoviz/math/box.h
dvz_box_normalize_3D() include/datoviz/math/box.h
dvz_box_normalize_polygon() include/datoviz/math/box.h

Dmat4

Function Header
dvz_dmat4_copy() include/datoviz/math/vec.h
dvz_dmat4_identity() include/datoviz/math/vec.h
dvz_dmat4_inv() include/datoviz/math/vec.h
dvz_dmat4_mat4() include/datoviz/math/vec.h
dvz_dmat4_mul() include/datoviz/math/vec.h
dvz_dmat4_mulv() include/datoviz/math/vec.h
dvz_dmat4_mulv3() include/datoviz/math/vec.h
dvz_dmat4_scale_p() include/datoviz/math/vec.h

Dvec3

Function Header
dvz_dvec3() include/datoviz/math/vec.h
dvz_dvec3_copy() include/datoviz/math/vec.h

Dvec4

Function Header
dvz_dvec4() include/datoviz/math/vec.h
dvz_dvec4_copy() include/datoviz/math/vec.h

Easing

Function Header
dvz_easing() include/datoviz/math/anim.h

Mean

Function Header
dvz_mean() include/datoviz/math/stats.h

Min

Function Header
dvz_min_max() include/datoviz/math/stats.h

Normalize

Function Header
dvz_normalize_bytes() include/datoviz/math/stats.h

Prng

Function Header
dvz_prng() include/datoviz/math/prng.h
dvz_prng_destroy() include/datoviz/math/prng.h
dvz_prng_uuid() include/datoviz/math/prng.h

Range

Function Header
dvz_range() include/datoviz/math/stats.h

Vec2

Function Header
dvz_vec2_copy() include/datoviz/math/vec.h

Vec3

Function Header
dvz_vec3_cast() include/datoviz/math/vec.h
dvz_vec3_copy() include/datoviz/math/vec.h

Box

Functions

dvz_box()

Create a box.

DvzBox dvz_box(
    double xmin,
    double xmax,
    double ymin,
    double ymax,
    double zmin,
    double zmax
);
Field Type Description
return DvzBox box with the supplied axis bounds
xmin double minimum x value
xmax double maximum x value
ymin double minimum y value
ymax double maximum y value
zmin double minimum z value
zmax double maximum z value

Declared in include/datoviz/math/box.h:88.

dvz_box_aspect()

Return the aspect ratio of a box.

double dvz_box_aspect(
    DvzBox box
);
Field Type Description
return double (xmax - xmin) / (ymax - ymin)
box DvzBox the box

Declared in include/datoviz/math/box.h:98.

dvz_box_center()

Return the box center.

void dvz_box_center(
    DvzBox box,
    dvec3 center
);
Field Type Description
box DvzBox the box
center dvec3

Declared in include/datoviz/math/box.h:108.

dvz_box_extent()

Return the extent of a box, in the same coordinate system, depending on the target viewport aspect ratio. DVZ_BOX_EXTENT_DEFAULT returns the input box unchanged. EXPAND preserves the center and grows the smaller axis so the returned box contains the input. CONTRACT preserves the center and shrinks the larger axis so the returned box is contained by the input.

DvzBox dvz_box_extent(
    DvzBox box,
    float width,
    float height,
    DvzBoxExtentStrategy strategy
);
Field Type Description
return DvzBox adjusted extent box
box DvzBox the original box
width float target viewport width in arbitrary units; nonpositive values leave the box unchanged
height float target viewport height in the same units as @p width; nonpositive values leave the box unchanged
strategy DvzBoxExtentStrategy indicates how the extent box should be computed

Declared in include/datoviz/math/box.h:126.

dvz_box_inverse()

Perform an inverse transformation of a position from a target box to a source box.

be NULL

void dvz_box_inverse(
    DvzBox source,
    DvzBox target,
    const vec3 pos,
    dvec3 * out
);
Field Type Description
source DvzBox the source box, in data coordinates
target DvzBox the target box, typically in normalized coordinates
pos const vec3 single-precision position in the target box
out dvec3 *

Declared in include/datoviz/math/box.h:215.

dvz_box_merge()

Merge a number of boxes into a single box.

DvzBox dvz_box_merge(
    uint32_t box_count,
    const DvzBox * boxes,
    DvzBoxMergeStrategy strategy
);
Field Type Description
return DvzBox merged box, or DVZ_BOX_NDC when @p box_count is zero
box_count uint32_t number of boxes to merge; may be zero
boxes const DvzBox * input array containing @p box_count boxes; must not be NULL when @p box_count is positive
strategy DvzBoxMergeStrategy the merge strategy

Declared in include/datoviz/math/box.h:140.

dvz_box_normalize_1D()

Normalize 1D input positions into a target box.

NULL

void dvz_box_normalize_1D(
    DvzBox source,
    DvzBox target,
    DvzDim dim,
    uint32_t count,
    const double * pos,
    vec3 * out
);
Field Type Description
source DvzBox the source box, in data coordinates
target DvzBox the target box, typically in normalized coordinates
dim DvzDim which dimension
count uint32_t number of positions
pos const double * input array containing @p count double-precision scalar positions; must not be NULL
out vec3 *

Declared in include/datoviz/math/box.h:156.

dvz_box_normalize_2D()

Normalize 2D input positions into a target box.

NULL

void dvz_box_normalize_2D(
    DvzBox source,
    DvzBox target,
    uint32_t count,
    dvec2 * pos,
    vec3 * out
);
Field Type Description
source DvzBox the source box, in data coordinates
target DvzBox the target box, typically in normalized coordinates
count uint32_t number of positions
pos dvec2 * input array containing @p count double-precision 2D positions; must not be NULL
out vec3 *

Declared in include/datoviz/math/box.h:172.

dvz_box_normalize_3D()

Normalize 3D input positions into a target box.

NULL

void dvz_box_normalize_3D(
    DvzBox source,
    DvzBox target,
    uint32_t count,
    dvec3 * pos,
    vec3 * out
);
Field Type Description
source DvzBox the source box, in data coordinates
target DvzBox the target box, typically in normalized coordinates
count uint32_t number of positions
pos dvec3 * input array containing @p count double-precision 3D positions; must not be NULL
out vec3 *

Declared in include/datoviz/math/box.h:202.

dvz_box_normalize_polygon()

Normalize 2D input positions into a target box, using dvec2* as output format.

NULL

void dvz_box_normalize_polygon(
    DvzBox source,
    DvzBox target,
    uint32_t count,
    dvec2 * pos,
    dvec2 * out
);
Field Type Description
source DvzBox the source box, in data coordinates
target DvzBox the target box, typically in normalized coordinates
count uint32_t number of positions
pos dvec2 * input array containing @p count double-precision 2D positions; must not be NULL
out dvec2 *

Declared in include/datoviz/math/box.h:186.

Types

DvzBox · record
struct DvzBox {
    double xmin;
    double xmax;
    double ymin;
    double ymax;
    double zmin;
    double zmax;
};

Declared in include/datoviz/math/box.h:39.

DvzBoxExtentStrategy · enum
enum DvzBoxExtentStrategy {
    DVZ_BOX_EXTENT_DEFAULT = 0,
    DVZ_BOX_EXTENT_FIXED_ASPECT_EXPAND = 1,
    DVZ_BOX_EXTENT_FIXED_ASPECT_CONTRACT = 2,
};

Declared in include/datoviz/math/box.h:61.

DvzBoxMergeStrategy · enum
enum DvzBoxMergeStrategy {
    DVZ_BOX_MERGE_DEFAULT = 0,
    DVZ_BOX_MERGE_CENTER = 1,
    DVZ_BOX_MERGE_CORNER = 2,
};

Declared in include/datoviz/math/box.h:51.

Dim

Types

DvzDim · enum
enum DvzDim {
    DVZ_DIM_X = 0,
    DVZ_DIM_Y = 1,
    DVZ_DIM_Z = 2,
    DVZ_DIM_COUNT = 3,
};

Declared in include/datoviz/math/dim.h:20.

Dmat4

Functions

dvz_dmat4_copy()

Copy a double-precision 4x4 matrix.

void dvz_dmat4_copy(
    dmat4 mat,
    dmat4 dest
);
Field Type Description
mat dmat4 source matrix
dest dmat4

Declared in include/datoviz/math/vec.h:90.

dvz_dmat4_identity()

Set a double-precision 4x4 matrix to the identity matrix.

void dvz_dmat4_identity(
    dmat4 mat
);
Field Type Description
mat dmat4

Declared in include/datoviz/math/vec.h:109.

dvz_dmat4_inv()

Invert a double-precision 4x4 matrix.

void dvz_dmat4_inv(
    dmat4 mat,
    dmat4 dest
);
Field Type Description
mat dmat4 source matrix; must be invertible
dest dmat4

Declared in include/datoviz/math/vec.h:184.

dvz_dmat4_mat4()

Cast a single-precision 4x4 matrix to double precision.

void dvz_dmat4_mat4(
    mat4 mat,
    dmat4 dest
);
Field Type Description
mat mat4 source matrix
dest dmat4

Declared in include/datoviz/math/vec.h:100.

dvz_dmat4_mul()

Multiply two double-precision 4x4 matrices.

void dvz_dmat4_mul(
    dmat4 m1,
    dmat4 m2,
    dmat4 dest
);
Field Type Description
m1 dmat4 left operand
m2 dmat4 right operand
dest dmat4

Declared in include/datoviz/math/vec.h:120.

dvz_dmat4_mulv()

Multiply a double-precision 4x4 matrix by a four-component vector.

void dvz_dmat4_mulv(
    dmat4 m,
    dvec4 v,
    dvec4 dest
);
Field Type Description
m dmat4 matrix operand
v dvec4 vector operand
dest dvec4

Declared in include/datoviz/math/vec.h:131.

dvz_dmat4_mulv3()

Transform a three-component vector by a double-precision 4x4 matrix.

void dvz_dmat4_mulv3(
    dmat4 m,
    dvec3 v,
    double last,
    dvec3 dest
);
Field Type Description
m dmat4 transformation matrix
v dvec3 source vector
last double homogeneous fourth component, commonly 1 for a position or 0 for a direction
dest dvec3

Declared in include/datoviz/math/vec.h:164.

dvz_dmat4_scale_p()

Multiply every component of a double-precision 4x4 matrix in place.

void dvz_dmat4_scale_p(
    dmat4 m,
    double s
);
Field Type Description
m dmat4
s double scalar multiplier

Declared in include/datoviz/math/vec.h:174.

Dvec3

Functions

dvz_dvec3()

Copy the first three components of a four-component vector.

void dvz_dvec3(
    dvec4 v4,
    dvec3 dest
);
Field Type Description
v4 dvec4 source vector
dest dvec3

Declared in include/datoviz/math/vec.h:152.

dvz_dvec3_copy()

Copy a three-component double-precision vector.

void dvz_dvec3_copy(
    const dvec3 a,
    dvec3 b
);
Field Type Description
a const dvec3 source vector
b dvec3

Declared in include/datoviz/math/vec.h:70.

Dvec4

Functions

dvz_dvec4()

Extend a three-component vector with a fourth component.

void dvz_dvec4(
    dvec3 v3,
    double last,
    dvec4 dest
);
Field Type Description
v3 dvec3 first three components
last double fourth component, commonly 1 for a position or 0 for a direction
dest dvec4

Declared in include/datoviz/math/vec.h:142.

dvz_dvec4_copy()

Copy a four-component double-precision vector.

void dvz_dvec4_copy(
    const dvec4 a,
    dvec4 b
);
Field Type Description
a const dvec4 source vector
b dvec4

Declared in include/datoviz/math/vec.h:80.

Easing

Functions

dvz_easing()

Apply an easing function to a normalized value.

double dvz_easing(
    DvzEasing easing,
    double t
);
Field Type Description
return double eased value; some curves intentionally overshoot [0, 1]
easing DvzEasing easing curve to apply
t double normalized input, normally in the interval [0, 1]

Declared in include/datoviz/math/anim.h:85.

Types

DvzEasing · enum
enum DvzEasing {
    DVZ_EASING_NONE = 0,
    DVZ_EASING_IN_SINE = 1,
    DVZ_EASING_OUT_SINE = 2,
    DVZ_EASING_IN_OUT_SINE = 3,
    DVZ_EASING_IN_QUAD = 4,
    DVZ_EASING_OUT_QUAD = 5,
    DVZ_EASING_IN_OUT_QUAD = 6,
    DVZ_EASING_IN_CUBIC = 7,
    DVZ_EASING_OUT_CUBIC = 8,
    DVZ_EASING_IN_OUT_CUBIC = 9,
    DVZ_EASING_IN_QUART = 10,
    DVZ_EASING_OUT_QUART = 11,
    DVZ_EASING_IN_OUT_QUART = 12,
    DVZ_EASING_IN_QUINT = 13,
    DVZ_EASING_OUT_QUINT = 14,
    DVZ_EASING_IN_OUT_QUINT = 15,
    DVZ_EASING_IN_EXPO = 16,
    DVZ_EASING_OUT_EXPO = 17,
    DVZ_EASING_IN_OUT_EXPO = 18,
    DVZ_EASING_IN_CIRC = 19,
    DVZ_EASING_OUT_CIRC = 20,
    DVZ_EASING_IN_OUT_CIRC = 21,
    DVZ_EASING_IN_BACK = 22,
    DVZ_EASING_OUT_BACK = 23,
    DVZ_EASING_IN_OUT_BACK = 24,
    DVZ_EASING_IN_ELASTIC = 25,
    DVZ_EASING_OUT_ELASTIC = 26,
    DVZ_EASING_IN_OUT_ELASTIC = 27,
    DVZ_EASING_IN_BOUNCE = 28,
    DVZ_EASING_OUT_BOUNCE = 29,
    DVZ_EASING_IN_OUT_BOUNCE = 30,
    DVZ_EASING_COUNT = 31,
};

Declared in include/datoviz/math/anim.h:34.

Mean

Functions

dvz_mean()

Compute the mean of an array of double values.

double dvz_mean(
    uint32_t n,
    const double * values
);
Field Type Description
return double arithmetic mean
n uint32_t number of values; must be positive
values const double * input array containing @p n values; must not be NULL

Declared in include/datoviz/math/stats.h:40.

Min

Functions

dvz_min_max()

Compute the min and max of an array of float values.

void dvz_min_max(
    uint32_t n,
    const float * values,
    vec2 out_min_max
);
Field Type Description
n uint32_t number of values; must be positive
values const float * input array containing @p n values; must not be NULL
out_min_max vec2

Declared in include/datoviz/math/stats.h:51.

Normalize

Functions

dvz_normalize_bytes()

Map floating-point values linearly to unsigned bytes.

Values at or below the selected minimum map to 0, and values at or above the maximum map to 255. When both bounds are equal, the effective maximum is minimum + 1.

void dvz_normalize_bytes(
    vec2 min_max,
    uint32_t count,
    float * values,
    uint8_t * out
);
Field Type Description
min_max vec2 input bounds {minimum, maximum}; minimum must not exceed maximum
count uint32_t number of values; must be positive
values float * input array containing @p count values; must not be NULL
out uint8_t *

Declared in include/datoviz/math/stats.h:66.

Prng

Functions

dvz_prng()

Create a pseudorandom number generator seeded from the platform random device.

DvzPrng * dvz_prng(void);
Field Type Description
return DvzPrng * a new owned generator; destroy it with dvz_prng_destroy()

Declared in include/datoviz/math/prng.h:43.

dvz_prng_destroy()

Destroy a pseudorandom number generator.

void dvz_prng_destroy(
    DvzPrng * prng
);
Field Type Description
prng DvzPrng * owned generator to destroy; must not be NULL

Declared in include/datoviz/math/prng.h:62.

dvz_prng_uuid()

Generate the next pseudorandom 64-bit value.

uint64_t dvz_prng_uuid(
    DvzPrng * prng
);
Field Type Description
return uint64_t pseudorandom value in the inclusive range [0, UINT64_MAX]
prng DvzPrng * generator state to advance; must not be NULL

Declared in include/datoviz/math/prng.h:53.

Types

DvzPrng · typedef
typedef struct DvzPrng DvzPrng;

Declared in include/datoviz/math/prng.h:28.

Range

Functions

dvz_range()

Compute the range of an array of double values.

If @p n is zero, this function returns without modifying @p min_max.

void dvz_range(
    uint32_t n,
    const double * values,
    dvec2 min_max
);
Field Type Description
n uint32_t number of input values
values const double * input array containing @p n values; must not be NULL when @p n is positive
min_max dvec2

Declared in include/datoviz/math/stats.h:79.

Scalar And Vector Types

Types

DvzAlpha · typedef
typedef uint8_t DvzAlpha;

Declared in include/datoviz/math/types.h:148.

DvzId · typedef
typedef uint64_t DvzId;

Declared in include/datoviz/math/types.h:72.

DvzIndex · typedef
typedef uint32_t DvzIndex;

Declared in include/datoviz/math/types.h:178.

DvzSize · typedef
typedef uint64_t DvzSize;

Declared in include/datoviz/math/types.h:86.

cvec2 · typedef
typedef uint8_t[2] cvec2;

Declared in include/datoviz/math/types.h:144.

cvec3 · typedef
typedef uint8_t[3] cvec3;

Declared in include/datoviz/math/types.h:145.

cvec4 · typedef
typedef uint8_t[4] cvec4;

Declared in include/datoviz/math/types.h:146.

dmat2 · typedef
typedef dvec2[2] dmat2;

Declared in include/datoviz/math/types.h:287.

dmat3 · typedef
typedef dvec3[3] dmat3;

Declared in include/datoviz/math/types.h:288.

dmat4 · typedef
typedef dvec4[4] dmat4;

Declared in include/datoviz/math/types.h:289.

dvec2 · typedef
typedef double[2] dvec2;

Declared in include/datoviz/math/types.h:282.

dvec3 · typedef
typedef double[3] dvec3;

Declared in include/datoviz/math/types.h:283.

dvec4 · typedef
typedef double[4] dvec4;

Declared in include/datoviz/math/types.h:284.

fvec2 · typedef
typedef vec2 fvec2;

Declared in include/datoviz/math/types.h:271.

fvec3 · typedef
typedef vec3 fvec3;

Declared in include/datoviz/math/types.h:272.

fvec4 · typedef
typedef vec4 fvec4;

Declared in include/datoviz/math/types.h:273.

ivec2 · typedef
typedef int32_t[2] ivec2;

Declared in include/datoviz/math/types.h:251.

ivec3 · typedef
typedef int32_t[3] ivec3;

Declared in include/datoviz/math/types.h:252.

ivec4 · typedef
typedef int32_t[4] ivec4;

Declared in include/datoviz/math/types.h:253.

mat2 · typedef
typedef vec2[2] mat2;

Declared in include/datoviz/math/types.h:263.

mat2x3 · typedef
typedef vec3[2] mat2x3;

Declared in include/datoviz/math/types.h:264.

mat2x4 · typedef
typedef vec4[2] mat2x4;

Declared in include/datoviz/math/types.h:265.

mat3 · typedef
typedef vec3[3] mat3;

Declared in include/datoviz/math/types.h:259.

mat3x2 · typedef
typedef vec2[3] mat3x2;

Declared in include/datoviz/math/types.h:260.

mat3x4 · typedef
typedef vec4[3] mat3x4;

Declared in include/datoviz/math/types.h:261.

mat4 · typedef
typedef vec4[4] mat4;

Declared in include/datoviz/math/types.h:267.

mat4x2 · typedef
typedef vec2[4] mat4x2;

Declared in include/datoviz/math/types.h:268.

mat4x3 · typedef
typedef vec3[4] mat4x3;

Declared in include/datoviz/math/types.h:269.

svec2 · typedef
typedef int16_t[2] svec2;

Declared in include/datoviz/math/types.h:157.

svec3 · typedef
typedef int16_t[3] svec3;

Declared in include/datoviz/math/types.h:158.

svec4 · typedef
typedef int16_t[4] svec4;

Declared in include/datoviz/math/types.h:159.

usvec2 · typedef
typedef uint16_t[2] usvec2;

Declared in include/datoviz/math/types.h:162.

usvec3 · typedef
typedef uint16_t[3] usvec3;

Declared in include/datoviz/math/types.h:163.

usvec4 · typedef
typedef uint16_t[4] usvec4;

Declared in include/datoviz/math/types.h:164.

uvec2 · typedef
typedef uint32_t[2] uvec2;

Declared in include/datoviz/math/types.h:173.

uvec3 · typedef
typedef uint32_t[3] uvec3;

Declared in include/datoviz/math/types.h:174.

uvec4 · typedef
typedef uint32_t[4] uvec4;

Declared in include/datoviz/math/types.h:175.

vec2 · typedef
typedef float[2] vec2;

Declared in include/datoviz/math/types.h:255.

vec3 · typedef
typedef float[3] vec3;

Declared in include/datoviz/math/types.h:256.

vec4 · typedef
typedef float[4] vec4;

Declared in include/datoviz/math/types.h:257.

Vec2

Functions

dvz_vec2_copy()

Copy a two-component single-precision vector.

void dvz_vec2_copy(
    const vec2 a,
    vec2 b
);
Field Type Description
a const vec2 source vector
b vec2

Declared in include/datoviz/math/vec.h:40.

Vec3

Functions

dvz_vec3_cast()

Cast a three-component double-precision vector to single precision.

void dvz_vec3_cast(
    const dvec3 * a,
    vec3 * b
);
Field Type Description
a const dvec3 * source vector; must not be NULL
b vec3 *

Declared in include/datoviz/math/vec.h:60.

dvz_vec3_copy()

Copy a three-component single-precision vector.

void dvz_vec3_copy(
    const vec3 a,
    vec3 b
);
Field Type Description
a const vec3 source vector
b vec3

Declared in include/datoviz/math/vec.h:50.