Vectors come in 2, 3, and 4 dimensional variants, with float, double, int, and long internal types. They are systematically named, with both a "long" name chosen to avoid conflicts with other libraries and a "short" name that is more convenient if you have no conflicts. Typedefs for the short names as well as short initialization macros are found in short_macros.h.

Type Width FS

2 3 4 (see below)

float Vector2
vec2 Vector3
vec3 Vector4
vec4
Quaternion
quat float

double Vector2d
vec2d Vector3d
vec3d Vector4d
vec4d double

int Vector2i
vec2i Vector3i
vec3i Vector4i
vec4i float

long Vector2l
vec2l Vector3l
vec3l Vector4l
vec4l double

There are no unsigned versions, nor sizes smaller than 32-bits.

In this documentation, the "X" suffix will be used to refer to any suffix combination. When "X" is used alone, it refers to a scalar variable of the respective internal type. "FS" is used to refer to the corresponding floating point scalar type associated with the internal element type. Some functions return floats despite operating on integers because an integer return typme makes little sense. Most functions have two versions: one that passes arguments by value and returns the result, and a void function that accepts pointers as arguments and has a final pointer out-arg. For the sake of clarity, const qualifiers are generally omitted in this documentation but do exist in the source where it makes sense.

Most vector functions also have a generic version that omits the suffix entirely and chooses the correct function based on the type of the first argument alone using _Generic().

Function Reference

vecX vAddX(vecX a, vecX b) void vAddXp(vecX* a, vecX* b, vecX* out)

Adds each element of a to the respective element of b and returns the result.

vecX vSubX(vecX a, vecX b) void vSubXp(vecX* a, vecX* b, vecX* out)

Subtracts each element of b from the respective element of a and returns the result: out = a - b. From a geometric perspective, it calculates the vector that points from b to a: b <--out-- a.

vecX vDivX(vecX top, vecX bottom) void vDivXp(vecX* top, vecX* bottom, vecX* out)

Divides each element of top by the respective element of b and returns the result.

vecX vMulX(vecX a, vecX b) void vMulXp(vecX* a, vecX* b, vecX* out)

Multiplies each element of a with the respective element of b and returns the result.

vecX vMulX(vecX a, X s) void vMulXp(vecX* a, X s, vecX* out)

Multiplies each element of a with s and returns the result. There is no "division" version of this function; invert s if you want to divide.

vecX vFMAX(vecX add, vecX mul, X s) void vFMAXp(vecX* add, vecX* mul, X s, vecX* out)

Multiplies each element of mul with s then adds the result to add. Equivalent to vAdd(add, vScale(mul, s)), hence the argument order. This function does not necessarily use true fused-multiply-add instructions internally and has no guaranteed precision or rounding properties other than given by C to the normal scalar expression out = a + b * c.

FV vDotX(vecX a, vecX b) FV vDotXp(vecX* a, vecX* b)

Computes the dot product of a and b.

vec3 vCross3(vec3 a, vec3 b) vec3d vCross3d(vec3d a, vec3d b) void vCross3p(vec3* a, vec3* b, vec3* out) void vCross3dp(vec3d* a, vec3d* b, vec3d* out)

Computes the cross product of a and b.

float vCross2(vec2 a, vec2 b) double vCross2d(vec2d a, vec2d b) float vCross2p(vec2* a, vec2* b) double vCross2dp(vec2d* a, vec2d* b)

Computes the outer product of the two vectors, which is equivalent to the 3D version with zeros for z. Useful for determining polygon winding in much the same way that the 3D cross product is used to determine triangle winding in 3D.

vecX vNegX(vecX v) void vNegXp(vecX* v, vecX* out)

Negates each element of the input.

vecX vInvX(vecX v) void vInvXp(vecX* v, vecX* out) vecX vRecipX(vecX v) void vRecipXp(vecX* v, vecX* out)

Inverts (takes the reciprocal) of each element of the input.

vecX vDotX(vecX a, vecX b) void vAvgXp(vecX* a, vecX* b, vecX* out)

Equivalent to vScale(vAdd(a, b), .5). Geometrically, is the point directly in between the points.

FS vLenX(vecX v) FS vLenXp(vecX* v) FS vMagX(vecX v) FS vMagXp(vecX* v)

Returns the length (magnitude) of the vector.

FS vLenSqX(vecX v) FS vLenSqXp(vecX* v)

Returns the squared length (magnitude) of the vector.

FS vInvLenX(vecX v) FS vInvLenXp(vecX* v)

Returns the reciprocal (inverse) of the length of the vector. This function does not use the lower-precision "approximate inverse square root" functions available on some systems.

vecX vNormX(vecX v) void vNormXp(vecX* v, vecX* out) vecX vUnitX(vecX v) void vUnitXp(vecX* v, vecX* out)

Calculates the normalized vector (aka "unit vector") for v. Unit vectors have a length of 1. Zero-length vectors are returned unchanged.

FS vDistX(vecX a, vecX b) FS vDistXp(vecX* a, vecX* b)

Calculates the distance between the two points. Equivalent to vLen(vSub(b, a)).

FS vDistSqX(vecX a, vecX b) FS vDistSqXp(vecX* a, vecX* b)

Calculates the squared distance between the two points. Equivalent to vLenSq(vSub(b, a)).

vecX vLerpX(vecX low, vecX high, FS t) void vLerpXp(vecX* low, vecX* high, FS t, vecX* out)

Performs element-wise linear interpolation between low and high based on the normalized (0 to 1) value of t. No clamping is done on the value of t and as such the return value may be outside the limits of low and high if t is less than zero or greater than one.

vec3 vC2S3(vec3 cart)

Cartesian to Spherical coordinate conversion.

vec3 vS2C3(vec3 cart)

Spherical to Cartesian coordinate conversion.

float vAngleBetween2(vec2 a, vec2 b) float vAngleBetween3(vec3 a, vec3 b)

Returns the smallest angle between two vectors. Both arguments must be normalized.

bool vEqX(vecX a, vecX b) bool vEqXp(vecX* a, vecX* b)

Compares the geometric distance between a and b to the appropriate FLT_CMP_EPSILON/DBL_CMP_EPSILON.

bool vEqEpX(vecX a, vecX b, X epsilon) bool vEqEpXp(vecX* a, vecX* b, X epsilon)

Compares the geometric distance between a and b to a configurable epsilon.

bool vEqExactX(vecX a, vecX b, X epsilon) bool vEqExactXp(vecX* a, vecX* b, X epsilon)

Compares a and b for bit-exact equivalence.

vecX vMinX(vecX a, vecX b) vecX vMinXp(vecX* a, vecX* b)

Returns the minimum value of a and b on a per-element basis.

vecX vMaxX(vecX a, vecX b) vecX vMaxXp(vecX* a, vecX* b)

Returns the maximum value of a and b on a per-element basis.

vecX vClampX(vecX in, vecX min, vecX max) vecX vClampXp(vecX* in, vecX* min, vecX* max)

Clamps the value of each element of in between the respective values in min and max, inclusive.

int vMinCompX(vecX in, vecX min, vecX max) int vMinCompXp(vecX* in, vecX* min, vecX* max)

Returns the 0-based index of the element with the lowest value (closest to negative infinity). If multiple elements are equal, the lower index is returned.

int vMaxCompX(vecX in, vecX min, vecX max) int vMaxCompXp(vecX* in, vecX* min, vecX* max)

Returns the 0-based index of the element with the highest value (closest to positive infinity). If multiple elements are equal, the lower index is returned.

vecX vAbsX(vecX v) void vAbsXp(vecX* v vecX* out)

Takes the absolute value of each element of v.

vecX vSignX(vecX v) void vSignXp(vecX* v vecX* out)

Returns a vector with 1 for input elements that are positive or zero and -1 for elements that are negative (or negative zero, if supported by the platform). Uses copysign() internally.

vecX vStepX(vecX edge, vecX v) void vStepXp(vecX* edge, vecX* v vecX* out)

Returns a vector with 0 for elements of v that are less than the corresponding element in edge, and 1 if greater or equal.

vecNi vFloorN(const vecN v); vecNl vFloorNd(vecNd v)

Rounds a floating point vector down based on the floor() C function, then converts to integer elements.

vecNi vCeil4(vecN v) vecNl vCeilNd(const vecNd v)

Rounds a floating point vector up based on the ceil() C function, then converts to integer elements.

void vSwap2ip(vec2i* a, vec2i* b) void vSwap2p(vec2* a, vec2* b) void vSwap3p(vec3* a, vec3* b) void vSwap4p(vec4* a, vec4* b)

Swaps two vectors. Only exists in pointer version for obvious reasons.

Functions without documentation yet

vec2 vModPositive2(vec2 v, vec2 m); vec3 vModPositive3(vec3 v, vec3 m); vec4 vModPositive4(vec4 v, vec4 m);