Vecmat

Precision chosen at build time

• Default: float and int32_t.
• Optional: double (VECMAT_USE_F64), and int width 8 / 16 / 32.

Math types

• Float vectors: 2D, 3D, 4D (vector2 / vector3 / vector4).
• Integer vectors: same sizes (vector2i / vector3i / vector4i).
• Float and integer matrices: 2x2, 3x3, 4x4.
• Quaternions for rotation.
• Easing functions for animation-style interpolation.
• Clip-space presets for OpenGL (RH_NO), Vulkan (RH_ZO) and Direct3D (LH_ZO).
• Dense packed vm_gemm (C = α op(A) op(B) + β C), batched GEMM, and heap vm_mat with LU / QR / SVD / Cholesky (solve, det, inverse, least squares).
• Sparse CSR (vm_spmat) with CG / BiCGSTAB and Jacobi / SSOR / IC(0) preconditioners.
• Time integrators (semi-implicit Euler, velocity Verlet, RK2 / RK4), CFL helper, and vm_rigid_step.
• Regular-grid / MAC operators and an assembled 5-/7-point Laplacian for Poisson projection.

Features to Avoid

• No SSE and no NEON on purpose. The library jumps to AVX / AVX2 / AVX-512 and ARM SVE / SVE2.

Two ways to call everything

• By-value helpers for everyday code.
• _ptr kernels for hot paths and SIMD.

Computer Graphics

Point Clouds, 3D Reconstruction, DNNs, LLMs

Physics and Simulations

Vecmat is still a math library: it does not ship a fluid solver, an SPH engine, or a constraint island. It supplies the primitives those codes call every substep.

Precision. Graphics can stay float. Scientific time integration and Poisson solves should configure -DVECMAT_USE_F64=ON so vm_float_t is double. The same relative-tolerance style used by LU / QR (tol ~ n ε max|A|) is reused by CG / BiCGSTAB as ||r|| / max(||b||, ε).

Generate local docs with m.css

python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install jinja2 Pygments
git clone --depth 1 https://github.com/mosra/m.css /tmp/m.css
python3 /tmp/m.css/documentation/doxygen.py doc/conf.py

HTML lands in doc/html/. Doxygen writes XML to doc/xml/ first; both directories are git-ignored.

Stock Doxygen HTML

cd doc && doxygen Doxyfile

CPU Feature Support

• AVX supported
• AVX2 (FMA3) supported
• AVX-512F (AVX-512 FMA) supported
• AVX10 (FMA3) work in progress
• AVX10.1 (Xeon 6) coming in 2027
• AVX10.2 (Xeon 7) tbd
• SVE (ARMv8.2-A+) supported
• SVE2 (ARMv9) supported

MMA Support

• WMMA / MMA (NVIDIA/CUDA) work in progress
• MFMA / WMMA (AMD/ROCm) work in progress
• AMX (4th-7th generation Intel Xeon) coming in 2027
• SME / SME2 (ARMv9.2-A+) tbd

At this moment we have no plans to support NEON.

Relevant Resources

• Convenient CPU feature detection and dispatch by Vladimír Vondruš
• LAPACK: Linear Algebra PACKage
• BiCGSTAB

Source using

if(NOT TARGET vecmat::vecmat)
    include(FetchContent)
    FetchContent_Declare(vecmat
        GIT_REPOSITORY https://github.com/alkavan/vecmat.git
        GIT_TAG v0.2.6
    )
    FetchContent_MakeAvailable(vecmat)
endif()

target_link_libraries(my_app PRIVATE vecmat::vecmat)

Installed Package

find_package(vecmat 0.2 CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE vecmat::vecmat)

Scalar precision flags

vm_float_t and vm_int_t are selected at compile time. Pass the matching CMake options when configuring Vecmat. The options become public compile definitions on vecmat::vecmat and vecmat::vecmat_static, so anything that links the library sees the same typedefs.

Defaults (no flags): vm_float_t is float, vm_int_t is int32_t.

The integer flags are mutually exclusive. CMake will error if more than one is ON. VECMAT_USE_F64 can be combined with any one integer flag.

Configure from the command line:

cmake -S . -B build \
  -DVECMAT_USE_F64=ON \
  -DVECMAT_USE_INT16=ON \
  -DVECMAT_BUILD_TESTS=ON

With FetchContent, set the cache variables before FetchContent_MakeAvailable:

set(VECMAT_USE_F64 ON CACHE BOOL "" FORCE)
set(VECMAT_USE_INT16 ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(vecmat)

Without CMake, define the same macros yourself (compiler flag or before the library include):

cc -DVECMAT_USE_F64 -DVECMAT_USE_INT16 ...

#define VECMAT_USE_F64
#define VECMAT_USE_INT16
#include <vecmat.h>

The library and every translation unit that includes vecmat.h must use the same set of macros, or the types will not match at link time.

Artificial Intelligence Guidelines and Transparency

1. AI use: Use of AI is neither prohibited nor encouraged. You may use AI only if you follow all the guidelines in this section.
2. Disclosure: If you add AI-generated material to a contribution or derivative work, say so clearly — for example in the pull request, commit message, or nearby comments. Note which parts were AI-generated or heavily AI-assisted. Everyday autocomplete or small wording help does not need a notice.
   
3. Responsibility: When you contribute or share a derivative, you take responsibility that the work has enough original human authorship, and that any AI-generated parts don't violate someone else's terms or the project [LICENSE](LICENSE).
4. AI training: If you train an AI system on this code, it is recommended to give it the whole project, including in-code comments and any generated documentation that exists.

Individual element access

vector3 p;
p.x = 1.0f;               // same as p.v[0]
p.v[1] = 2.0f;            // same as p.y
printf("%f\n", p.z);

matrix3 mat;
mat.v[0] = 1.0f;          // same as mat.m11 (column-major)
printf("%f\n", mat.m21);  // same as mat.v[1]

Initializing a vector

vector3 p = vec3(1.0f, 2.0f, 3.0f);
vector2 q = vec2(4.0f, 5.0f);
vector3i grid = vec3i(8, 16, 24);

vector3 origin = vec3_zero();
vector3 ones   = vec3_one();
vector3 fill   = vec3_splat(0.5f);

vector3 named = { .x = 1.0f, .y = 0.0f, .z = 0.0f };
vector4 homog = { .v = {1.0f, 2.0f, 3.0f, 1.0f} };

vec3_assign_xyz(&p, 0.0f, 1.0f, 0.0f);
vector3 lifted = vec3_from_vec2(q, 0.0f);

The same pattern exists for vector2 / vector4 and the integer types (vecN_zero, vecN_one, vecN_splat, plus vec2i / vec3i).

Initializing a matrix

matrix3 ident = {
    .m11 = 1.0f, .m21 = 0.0f, .m31 = 0.0f,
    .m12 = 0.0f, .m22 = 1.0f, .m32 = 0.0f,
    .m13 = 0.0f, .m23 = 0.0f, .m33 = 1.0f
};

matrix3 also = { .v = {1,0,0,  0,1,0,  0,0,1} };

Accessing matrix elements

float determinant(const matrix3 *mat) {
    float det =
        mat->m11 * (mat->m22 * mat->m33 - mat->m23 * mat->m32)   // First term
      - mat->m12 * (mat->m21 * mat->m33 - mat->m23 * mat->m31)   // Second term (negative)
      + mat->m13 * (mat->m21 * mat->m32 - mat->m22 * mat->m31);  // Third term
    return det;
}

matrix3 mat;
for (int i = 0; i < 9; i++) {
    mat.v[i] *= 2.0f;  // Scale all elements by 2
}

Vector Operations Examples

A function for general linear transformation to the vector:

void transform(vector3 *out, const matrix3 *mat, const vector3 *vec) {
    out->x = mat->m11 * vec->x + mat->m12 * vec->y + mat->m13 * vec->z;
    out->y = mat->m21 * vec->x + mat->m22 * vec->y + mat->m23 * vec->z;
    out->z = mat->m31 * vec->x + mat->m32 * vec->y + mat->m33 * vec->z;
}

A function to translate a vector by adding a translation offset:

void translate(vector3 *out, const vector3 *vec, const vector3 *translation) {
    out->x = vec->x + translation->x;
    out->y = vec->y + translation->y;
    out->z = vec->z + translation->z;
}

Matrix Operations Examples

You can write a function to multiply two matrix3 instances.
Using the array access makes it easier to implement with nested loops:

void multiply(matrix3 *result, const matrix3 *a, const matrix3 *b) {
    for (int c = 0; c < 3; c++) {      /* columns of result / of B */
        for (int r = 0; r < 3; r++) {  /* rows of result / of A */
            float sum = 0.0f;
            for (int k = 0; k < 3; k++) {
                sum += a->v[k * 3 + r] * b->v[c * 3 + k];  /* column-major */
            }
            result->v[c * 3 + r] = sum;
        }
    }
}

This creates a matrix4 that can apply rotation/scaling (from matrix3) followed by translation:

void affine_matrix(matrix4 *out, const matrix3 *linear, const vector3 *translation) {
    // Copy the 3x3 linear part (columns 1-3)
    out->m11 = linear->m11; out->m21 = linear->m21; out->m31 = linear->m31; out->m41 = 0.0f;
    out->m12 = linear->m12; out->m22 = linear->m22; out->m32 = linear->m32; out->m42 = 0.0f;
    out->m13 = linear->m13; out->m23 = linear->m23; out->m33 = linear->m33; out->m43 = 0.0f;
    
    // Set translation in the fourth column
    out->m14 = translation->x;
    out->m24 = translation->y;
    out->m34 = translation->z;
    out->m44 = 1.0f;
}