mathLib

A SIMD-oriented linear algebra library for graphics-style code: vectors, matrices, quaternions, rigid transforms, and trig helpers. The public API lives in the mathLib namespace; include MathLib.h for the full surface (core math plus optional app helpers).

About

mathLib is a compact C++ library built around SSE intrinsics (__m128), with types such as Vec3, Vec4, Mat3, Mat4, and Quat, plus helpers for scale, translation, rotation, and common trig. It is intended for projects that need fast CPU-side math (transforms, animation, tooling) and a clear, documented convention for how vectors and matrices combine.

Features

• Vectors — Vec3, Vec4 with SIMD-backed storage where applicable
• Matrices — Mat3, Mat4 with row-major element layout (see below)
• Quaternions — Quat and related helpers
• Transforms — scale, translation, rotation utilities (Scale, Trans, Rot)
• Trig — Trig static methods (angles in radians)

Requirements

• Toolchain — Microsoft Visual C++ (MSVC) is the primary supported compiler; headers use SSE intrinsics (<xmmintrin.h>, <smmintrin.h>).
• Platform — x86 / x64 Windows targets match the current intrinsics and project layout.
• C++ — A recent C++ standard with support for move semantics and constexpr as used in the headers (typically C++11 or newer).
• Alignment — Several types inherit Align16 (16-byte alignment for SIMD). Your application must define this base (for example via a small Framework.h included before math headers), matching how the library expects aligned new / storage for Vec3, Vec4, Mat3, Mat4, and Quat.

Math conventions (read before integrating)

These rules are the “contract” between this library and your renderer or tools.

Vectors and matrix multiply

• Vec4 and Vec3 behave as row vectors on the left of a matrix.
• Use v * M (e.g. Vec4 * Mat4, Vec3 * Mat3), not M * v.
• For Vec4 × Mat4, each result component is the dot product of v with the corresponding column of M (equivalently: row-vector × matrix in the usual linear-algebra sense).

Matrix storage (Mat4 / Mat3)

• Mat4 is stored in row-major order: scalars m0–m3 are the first row, m4–m7 the second, m8–m11 the third, m12–m15 the fourth. The matrix is composed of four row vectors (Row4 accessors).
• Mat3 follows the same idea for its 3×3 layout (see accessors / element naming in Mat3.h).
• Matrix × matrix uses Mat4 * Mat4 / Mat3 * Mat3 as implemented; when chaining transforms with row vectors, composition order must match your engine’s expectations—verify against a known test (e.g. translate then rotate) when wiring to rendering.

Angles and coordinates

• Trig functions take angles in radians (see parameter names in Trig.h).
• The library does not fix a global clip space or NDC range; projection and handedness are your responsibility. Use the same row-vector and row-major rules when building view/projection matrices so they match v * M.
• Handedness (left- vs right-handed) is not enforced here; cross products and rotation helpers follow the implemented formulas—sanity-check against your asset pipeline if mixing with other libraries.

SIMD alignment

• Types derived from Align16 must be 16-byte aligned in memory. Avoid packing them in unaligned structs or treating them as arbitrary byte blobs without alignment guarantees.

How to use the library

1. Add the include/ directory to your project’s additional include paths.

2. Compile and link the src/ translation units (or your static library project that wraps them).

3. Ensure Align16 is defined and included before math headers, per your project’s framework.

4. In code, include the umbrella header and qualify types:

   #include "MathLib.h"
   
   void example()
   {
       using namespace mathLib;
       Vec4 v(1.0f, 0.0f, 0.0f, 1.0f);
       Mat4 M(Identity);
       Vec4 v2 = v * M;
   }

5. Prefer #include "MathLib.h" for applications. For tighter dependencies you can include specific headers (e.g. "Vec4.h", "Mat4.h") instead.

Optional but recommended for efficiency: MATH_USE_HINTS (see Mat4.h) enables hint machinery for matrix operations; leave it as in the headers unless you have a reason to change it.

Quick start (existing Visual Studio project)

mathLib ships as include/ and src/ only. You fold it into a project you already have (executable or static library).

1. Bring in the tree — Copy the include and src folders into your repo (for example third_party/mathLib/include and third_party/mathLib/src), or keep them elsewhere and use absolute/relative paths in the steps below.
2. Include path — Open your project’s Property Pages → C/C++ → General → Additional Include Directories and add the directory that contains MathLib.h (the include folder itself, not its parent).
3. Compile the sources — In Solution Explorer, right-click your project → Add → Existing Item… and add every .cpp under src/ (or add the whole src folder if your VS version supports it). Those files build as part of your target; there is no separate math .lib unless you split it into its own static library project later.
4. C++ and intrinsics — Use a C++ dialect that matches Requirements (e.g. C/C++ → Language → C++ Language Standard set to at least C++11). MSVC enables SSE/SSE2 for typical x64 and modern Win32 configs; if you hit missing intrinsic errors on an unusual target, check C/C++ → Code Generation (e.g. enable SSE2 for 32-bit builds).
5. Alignment base class — Ensure Align16 is visible to the translation units that include math headers (see Requirements).
6. Build — Compile your project; resolve any missing includes or linker issues the same way you would for any other added sources.

Other build systems (CMake, etc.) follow the same idea: add the include directory, compile all src/*.cpp, satisfy Align16, and use MSVC-friendly flags for SSE intrinsics.

License

This project is released under the MIT License. See the LICENSE file for the full text and copyright notice.