Math

Vector math types and functions. More...

Data Structures
struct	b3Vec2
	A 2D vector. More...
struct	b3Vec3
	A 3D vector. More...
struct	b3CosSin
	Cosine and sine pair. More...
struct	b3Quat
	A quaternion. More...
struct	b3Transform
	A rigid transform. More...
struct	b3Matrix3
	A 3x3 matrix. More...
struct	b3AABB
	Axis aligned bounding box. More...
struct	b3Plane
	A plane. More...
struct	b3SegmentDistanceResult
	The closest points between to segments or infinite lines. More...

Macros
#define	B3_PI   3.14159265359f
	https://en.wikipedia.org/wiki/Pi
#define	B3_DEG_TO_RAD   0.01745329251f
	Convenience macro to convert from degrees to radians.
#define	B3_RAD_TO_DEG   57.2957795131f
	Convenience macro to convert from radians to degrees.
#define	B3_MIN_SCALE   0.01f
	Minimum scale used for scaling collision meshes, etc.

Typedefs
typedef b3Vec3	b3Pos
	In single precision mode these types are the same.
typedef b3Transform	b3WorldTransform
	In single precision mode these types are the same.

Functions
int	b3MinInt (int a, int b)
int	b3MaxInt (int a, int b)
int	b3ClampInt (int a, int lower, int upper)
bool	b3IsValidFloat (float a)
	Is this a valid number? Not NaN or infinity.
float	b3AbsFloat (float a)
float	b3MinFloat (float a, float b)
float	b3MaxFloat (float a, float b)
float	b3ClampFloat (float a, float lower, float upper)
float	b3LerpFloat (float a, float b, float alpha)
	Interpolate a scalar.
float	b3Atan2 (float y, float x)
	Compute an approximate arctangent in the range [-pi, pi] This is hand coded for cross-platform determinism.
b3CosSin	b3ComputeCosSin (float radians)
	Compute the cosine and sine of an angle in radians.
float	b3Sin (float radians)
float	b3Cos (float radians)
float	b3UnwindAngle (float radians)
	Convert any angle into the range [-pi, pi].
b3Vec3	b3Add (b3Vec3 a, b3Vec3 b)
	Vector addition.
b3Vec3	b3Sub (b3Vec3 a, b3Vec3 b)
	Vector subtraction.
b3Vec3	b3Mul (b3Vec3 a, b3Vec3 b)
	Vector component-wise multiplication.
b3Vec3	b3Neg (b3Vec3 a)
	Vector negation.
float	b3Dot (b3Vec3 a, b3Vec3 b)
	Vector dot product.
float	b3Length (b3Vec3 v)
	Vector length.
float	b3LengthSquared (b3Vec3 a)
	Vector length squared.
float	b3Distance (b3Vec3 a, b3Vec3 b)
	Distance between two points.
float	b3DistanceSquared (b3Vec3 a, b3Vec3 b)
	Squared distance between two points.
b3Vec3	b3Normalize (b3Vec3 a)
	Normalize a vector. Returns a zero vector if the input vector is very small.
b3Vec3	b3GetLengthAndNormalize (float *length, b3Vec3 a)
	Normalize a vector and return the length.
b3Vec3	b3Perp (b3Vec3 a)
	Get a unit vector that is perpendicular to the supplied vector.
bool	b3IsNormalized (b3Vec3 a)
	Is a vector normalized? In other words, does it have unit length?
b3Vec3	b3MulAdd (b3Vec3 a, float s, b3Vec3 b)
	a + s * b
b3Vec3	b3MulSub (b3Vec3 a, float s, b3Vec3 b)
	a - s * b
b3Vec3	b3MulSV (float s, b3Vec3 a)
	s * a
b3Vec3	b3Cross (b3Vec3 a, b3Vec3 b)
	https://en.wikipedia.org/wiki/Cross_product
b3Vec3	b3Lerp (b3Vec3 a, b3Vec3 b, float alpha)
	Linearly interpolate between two vectors.
b3Vec3	b3Blend2 (float s, b3Vec3 a, float t, b3Vec3 b)
	Blend two vectors: s * a + t * b.
b3Vec3	b3Abs (b3Vec3 a)
	Component-wise absolute value.
b3Vec3	b3Sign (b3Vec3 a)
	Component-wise -1 or 1 (1 if zero).
b3Vec3	b3Min (b3Vec3 a, b3Vec3 b)
	Component-wise minimum value.
b3Vec3	b3Max (b3Vec3 a, b3Vec3 b)
	Component-wise maximum value.
b3Vec3	b3Clamp (b3Vec3 a, b3Vec3 lower, b3Vec3 upper)
	Component-wise clamped value.
b3Vec3	b3SafeScale (b3Vec3 a)
	Create a safe scaling value for scaling collision.
bool	b3IsNormalizedQuat (b3Quat q)
	Does the supplied quaternion have unit length?
b3Vec3	b3RotateVector (b3Quat q, b3Vec3 v)
	Rotate a vector.
b3Vec3	b3InvRotateVector (b3Quat q, b3Vec3 v)
	Inverse rotate a vector.
float	b3DotQuat (b3Quat a, b3Quat b)
	Compute dot product of two quaternions. Useful for polarity tests.
b3Quat	b3MulQuat (b3Quat q1, b3Quat q2)
	Multiply two quaternions.
b3Quat	b3InvMulQuat (b3Quat q1, b3Quat q2)
	Compute a relative quaternion.
b3Quat	b3Conjugate (b3Quat q)
	Quaternion conjugate (cheap inverse).
b3Quat	b3NegateQuat (b3Quat q)
	Component-wise quaternion negation.
b3Quat	b3NormalizeQuat (b3Quat q)
	Normalize a quaternion.
b3Quat	b3MakeQuatFromAxisAngle (b3Vec3 axis, float radians)
	Make a quaternion that is equivalent to rotating around an axis by a specified angle.
b3Vec3	b3GetAxisAngle (float *radians, b3Quat q)
	Get the axis and angle from a quaternion. Assumes the quaternion is normalized.
float	b3GetQuatAngle (b3Quat q)
	Get the angle for a quaternion in radians.
b3Quat	b3MakeQuatFromMatrix (const b3Matrix3 *m)
	Extract a quaternion from a rotation matrix.
b3Quat	b3ComputeQuatBetweenUnitVectors (b3Vec3 v1, b3Vec3 v2)
	Find a quaternion that rotates one vector to another.
float	b3GetTwistAngle (b3Quat q)
	Twist angle around the z-axis, used for twist limit and revolute angle limit.
float	b3GetSwingAngle (b3Quat q)
	Swing angle used for cone limit.
b3Quat	b3NLerp (b3Quat q1, b3Quat q2, float alpha)
	Linearly interpolate and normalize between two quaternions.
b3Transform	b3MulTransforms (b3Transform a, b3Transform b)
	Multiply two transforms.
B3_FORCE_INLINE b3Transform	b3InvMulTransforms (b3Transform a, b3Transform b)
	Creates a transform that converts a local point in frame B to a local point in frame A.
b3Transform	b3InvertTransform (b3Transform t)
	Get the inverse of a transform.
b3Vec3	b3TransformPoint (b3Transform t, b3Vec3 v)
	Transform a point.
b3Vec3	b3InvTransformPoint (b3Transform t, b3Vec3 v)
	Inverse transform a point.
b3Pos	b3ToPos (b3Vec3 v)
	Convert a vector to a world position.
b3Vec3	b3ToVec3 (b3Pos p)
	Lossy conversion of a world position to a float vector.
float	b3RoundDownFloat (double x)
	Narrow a world coordinate to float, rounding toward negative infinity.
float	b3RoundUpFloat (double x)
	Narrow a world coordinate to float, rounding toward positive infinity.
b3Vec3	b3SubPos (b3Pos a, b3Pos b)
	a - b, demoted to float. The primary precision boundary operation.
b3Pos	b3OffsetPos (b3Pos p, b3Vec3 d)
	p + d
b3Pos	b3LerpPosition (b3Pos a, b3Pos b, float t)
	World position interpolation for sweeps and sampling.
b3Pos	b3TransformWorldPoint (b3WorldTransform t, b3Vec3 p)
	Transform a local point to a world position. Rotation in float, translation in double.
b3Vec3	b3InvTransformWorldPoint (b3WorldTransform t, b3Pos p)
	Transform a world position to a local point. One double subtraction, then float.
b3Transform	b3InvMulWorldTransforms (b3WorldTransform A, b3WorldTransform B)
	Relative transform of frame B in frame A. The narrow phase boundary.
b3WorldTransform	b3MulWorldTransforms (b3WorldTransform A, b3Transform B)
	Compose a world transform with a local transform.
b3Transform	b3ToRelativeTransform (b3WorldTransform t, b3Pos base)
	Shift a world transform into the frame of a base position.
b3WorldTransform	b3MakeWorldTransform (b3Transform t)
	Promote a float transform to a world transform. Lossless.
b3AABB	b3OffsetAABB (b3AABB localBox, b3Pos origin)
	Translate a local AABB by a world origin, rounding outward so the float box always contains the double box.
float	b3Det (b3Matrix3 m)
	Compute the determinant of a 3-by-3 matrix.
b3Vec3	b3MulMV (b3Matrix3 m, b3Vec3 a)
	Multiply a matrix times a column vector.
b3Matrix3	b3NegateMat3 (b3Matrix3 a)
	Negate a matrix.
b3Matrix3	b3AddMM (b3Matrix3 a, b3Matrix3 b)
	Matrix addition.
b3Matrix3	b3SubMM (b3Matrix3 a, b3Matrix3 b)
	Matrix subtraction.
b3Matrix3	b3MulSM (float s, b3Matrix3 a)
	Multiply a matrix by a scalar, component-wise.
b3Matrix3	b3MulMM (b3Matrix3 a, b3Matrix3 b)
	Matrix multiplication.
b3Matrix3	b3Transpose (b3Matrix3 m)
	Matrix transpose.
b3Matrix3	b3InvertMatrix (b3Matrix3 m)
	General matrix inverse.
b3Vec3	b3Solve3 (b3Matrix3 m, b3Vec3 a)
	Solve a matrix equation.
b3Matrix3	b3InvertT (b3Matrix3 m)
	Invert a matrix.
b3Matrix3	b3AbsMatrix3 (b3Matrix3 m)
	Get the component-wise absolute value of a matrix.
B3_FORCE_INLINE b3Matrix3	b3MakeMatrixFromQuat (b3Quat q)
	Make a matrix from a quaternion.
b3Matrix3	b3Steiner (float mass, b3Vec3 origin)
	Get the inertia tensor of an offset point.
b3AABB	b3MakeAABB (const b3Vec3 *points, int count, float radius)
	Get the AABB of a point cloud.
bool	b3AABB_Contains (b3AABB a, b3AABB b)
	Does a fully contain b?
float	b3AABB_Area (b3AABB a)
	Get the surface area of an axis-aligned bounding box.
b3Vec3	b3AABB_Center (b3AABB a)
	Get the center of an axis-aligned bounding box.
b3Vec3	b3AABB_Extents (b3AABB a)
	Get the extents (half-widths) of an axis-aligned bounding box.
b3AABB	b3AABB_Union (b3AABB a, b3AABB b)
	Get the union of two axis-aligned bounding boxes.
b3AABB	b3AABB_Inflate (b3AABB a, float extension)
	Add uniform padding to an axis-aligned bounding box.
bool	b3AABB_Overlaps (b3AABB a, b3AABB b)
	Do two axis-aligned boxes overlap?
b3AABB	b3AABB_Transform (b3Transform transform, b3AABB a)
	Transform an axis-aligned bounding box.
b3Vec3	b3ClosestPointToAABB (b3Vec3 point, b3AABB a)
	Get the closest point on an axis-aligned bounding box.
b3Vec3	b3PointToSegmentDistance (b3Vec3 a, b3Vec3 b, b3Vec3 q)
	Compute the closest point on the segment a-b to the target q.
b3SegmentDistanceResult	b3LineDistance (b3Vec3 p1, b3Vec3 d1, b3Vec3 p2, b3Vec3 d2)
	Compute the closest points on two infinite lines.
b3SegmentDistanceResult	b3SegmentDistance (b3Vec3 p1, b3Vec3 q1, b3Vec3 p2, b3Vec3 q2)
	Compute the closest points on two line segments.
bool	b3IsValidVec3 (b3Vec3 a)
	Is this a valid vector? Not NaN or infinity.
bool	b3IsValidQuat (b3Quat q)
	Is this a valid quaternion? Not NaN or infinity. Is normalized.
bool	b3IsValidTransform (b3Transform a)
	Is this a valid transform? Not NaN or infinity. Is normalized.
bool	b3IsValidMatrix3 (b3Matrix3 a)
	Is this a valid matrix? Not NaN or infinity.
bool	b3IsValidAABB (b3AABB a)
	Is this a valid bounding box? Not Nan or infinity. Upper bound greater than or equal to lower bound.
bool	b3IsBoundedAABB (b3AABB a)
	Is this AABB reasonably close to the origin? See B3_HUGE.
bool	b3IsSaneAABB (b3AABB a)
	Is this AABB valid and reasonable?
bool	b3IsValidPlane (b3Plane a)
	Is this a valid plane? Normal is a unit vector. Not Nan or infinity.
bool	b3IsValidPosition (b3Pos p)
	Is this a valid world position? Not NaN or infinity.
bool	b3IsValidWorldTransform (b3WorldTransform t)
	Is this a valid world transform? Not NaN or infinity. Rotation is normalized.

Detailed Description

Vector math types and functions.

---

Data Structure Documentation

b3Vec2

struct b3Vec2

A 2D vector.

Data Fields
float	x
float	y

b3Vec3

struct b3Vec3

A 3D vector.

Data Fields
float	x
float	y
float	z

b3CosSin

struct b3CosSin

Cosine and sine pair.

This uses a custom implementation designed for cross-platform determinism.

Data Fields
float	cosine	cosine and sine
float	sine

b3Quat

struct b3Quat

A quaternion.

Collaboration diagram for b3Quat:

Data Fields
float	s
b3Vec3	v

b3Transform

struct b3Transform

A rigid transform.

Collaboration diagram for b3Transform:

Data Fields
b3Vec3	p
b3Quat	q

b3Matrix3

struct b3Matrix3

A 3x3 matrix.

Collaboration diagram for b3Matrix3:

Data Fields
b3Vec3	cx
b3Vec3	cy
b3Vec3	cz

b3AABB

struct b3AABB

Axis aligned bounding box.

Collaboration diagram for b3AABB:

Data Fields
b3Vec3	lowerBound
b3Vec3	upperBound

b3Plane

struct b3Plane

A plane.

separation = dot(normal, point) - offset

Collaboration diagram for b3Plane:

Data Fields
b3Vec3	normal
float	offset

b3SegmentDistanceResult

struct b3SegmentDistanceResult

The closest points between to segments or infinite lines.

Collaboration diagram for b3SegmentDistanceResult:

Data Fields
float	fraction1
float	fraction2
b3Vec3	point1
b3Vec3	point2

Function Documentation

b3AABB_Transform()

b3AABB b3AABB_Transform	(	b3Transform	transform,
		b3AABB	a )

Transform an axis-aligned bounding box.

This can create a larger box than if you recomputed the AABB of the original shape with the transform applied.

b3AbsFloat()

float b3AbsFloat

(

float

a

)

Returns

the absolute value of a float.

b3AddMM()

b3Matrix3 b3AddMM	(	b3Matrix3	a,
		b3Matrix3	b )

Matrix addition.

Returns

a + b

b3Atan2()

float b3Atan2	(	float	y,
		float	x )

Compute an approximate arctangent in the range [-pi, pi] This is hand coded for cross-platform determinism.

The atan2f function in the standard library is not cross-platform deterministic. Accurate to around 0.0023 degrees.

b3ClampFloat()

float b3ClampFloat	(	float	a,
		float	lower,
		float	upper )

Returns

a float clamped between a lower and upper bound.

b3ClampInt()

int b3ClampInt	(	int	a,
		int	lower,
		int	upper )

Returns

an integer clamped between a lower and upper bound.

b3ComputeCosSin()

b3CosSin b3ComputeCosSin

(

float

radians

)

Compute the cosine and sine of an angle in radians.

Implemented for cross-platform determinism.

b3Cos()

float b3Cos

(

float

radians

)

Deprecated

b3GetLengthAndNormalize()

b3Vec3 b3GetLengthAndNormalize	(	float *	length,
		b3Vec3	a )

Normalize a vector and return the length.

Returns a zero vector if the input is very small.

b3InvMulQuat()

b3Quat b3InvMulQuat	(	b3Quat	q1,
		b3Quat	q2 )

Compute a relative quaternion.

inv(q1) * q2

b3InvMulTransforms()

B3_FORCE_INLINE b3Transform b3InvMulTransforms	(	b3Transform	a,
		b3Transform	b )

Creates a transform that converts a local point in frame B to a local point in frame A.

This is useful for transforming points between the local spaces of two frames that are in world space.

b3IsValidFloat()

bool b3IsValidFloat

(

float

a

)

Is this a valid number? Not NaN or infinity.

Returns

is this float valid (finite and not NaN).

b3MakeMatrixFromQuat()

B3_FORCE_INLINE b3Matrix3 b3MakeMatrixFromQuat

(

b3Quat

q

)

Make a matrix from a quaternion.

This is useful if you need to rotate many vectors. The force inline improves the performance of b3ShapeDistance.

b3MaxFloat()

float b3MaxFloat	(	float	a,
		float	b )

Returns

the maximum of two floats.

b3MaxInt()

int b3MaxInt	(	int	a,
		int	b )

Returns

the maximum of two integers.

b3MinFloat()

float b3MinFloat	(	float	a,
		float	b )

Returns

the minimum of two floats.

b3MinInt()

int b3MinInt	(	int	a,
		int	b )

Returns

the minimum of two integers.

b3MulMM()

b3Matrix3 b3MulMM	(	b3Matrix3	a,
		b3Matrix3	b )

Matrix multiplication.

Returns

a * b

b3MulTransforms()

b3Transform b3MulTransforms	(	b3Transform	a,
		b3Transform	b )

Multiply two transforms.

If the result is applied to a point p local to frame B, the transform would first convert p to a point local to frame A, then into a point in the world frame. This is useful if frame B is a child of frame A.

b3OffsetAABB()

b3AABB b3OffsetAABB	(	b3AABB	localBox,
		b3Pos	origin )

Translate a local AABB by a world origin, rounding outward so the float box always contains the double box.

Far from the origin a plain conversion could clip a shape out of its own box. In float mode the origin is float and the rounding is a no-op.

b3RoundDownFloat()

float b3RoundDownFloat

(

double

x

)

Narrow a world coordinate to float, rounding toward negative infinity.

Use with b3RoundUpFloat to build a conservative float box that always contains the double bounds, where plain rounding far from the origin could clip. nextafterf is an exact IEEE operation, so this is cross-platform deterministic. With large world mode off this is a plain conversion.

b3SafeScale()

b3Vec3 b3SafeScale

(

b3Vec3

a

)

Create a safe scaling value for scaling collision.

This allows negative scale, but keeps scale sufficiently far from zero.

b3Sin()

float b3Sin

(

float

radians

)

Deprecated

b3Solve3()

b3Vec3 b3Solve3	(	b3Matrix3	m,
		b3Vec3	a )

Solve a matrix equation.

Returns

inv(m) * a

b3Steiner()

b3Matrix3 b3Steiner	(	float	mass,
		b3Vec3	origin )

Get the inertia tensor of an offset point.

https://en.wikipedia.org/wiki/Parallel_axis_theorem

b3SubMM()

b3Matrix3 b3SubMM	(	b3Matrix3	a,
		b3Matrix3	b )

Matrix subtraction.

Returns

a - b