Math

Vector math types and functions. More...

Data Structures
struct	b2Vec2
	2D vector This can be used to represent a point or free vector More...
struct	b2CosSin
	Cosine and sine pair This uses a custom implementation designed for cross-platform determinism. More...
struct	b2Rot
	2D rotation This is similar to using a complex number for rotation More...
struct	b2Transform
	A 2D rigid transform. More...
struct	b2Mat22
	A 2-by-2 Matrix. More...
struct	b2AABB
	Axis-aligned bounding box. More...
struct	b2Plane
	separation = dot(normal, point) - offset More...

Macros
#define	B2_PI   3.14159265359f
	https://en.wikipedia.org/wiki/Pi

Functions
int	b2MinInt (int a, int b)
int	b2MaxInt (int a, int b)
int	b2AbsInt (int a)
int	b2ClampInt (int a, int lower, int upper)
float	b2MinFloat (float a, float b)
float	b2MaxFloat (float a, float b)
float	b2AbsFloat (float a)
float	b2ClampFloat (float a, float lower, float upper)
float	b2Atan2 (float y, float x)
	Compute an approximate arctangent in the range [-pi, pi] This is hand coded for cross-platform determinism.
b2CosSin	b2ComputeCosSin (float radians)
	Compute the cosine and sine of an angle in radians.
float	b2Dot (b2Vec2 a, b2Vec2 b)
	Vector dot product.
float	b2Cross (b2Vec2 a, b2Vec2 b)
	Vector cross product. In 2D this yields a scalar.
b2Vec2	b2CrossVS (b2Vec2 v, float s)
	Perform the cross product on a vector and a scalar. In 2D this produces a vector.
b2Vec2	b2CrossSV (float s, b2Vec2 v)
	Perform the cross product on a scalar and a vector. In 2D this produces a vector.
b2Vec2	b2LeftPerp (b2Vec2 v)
	Get a left pointing perpendicular vector. Equivalent to b2CrossSV(1.0f, v)
b2Vec2	b2RightPerp (b2Vec2 v)
	Get a right pointing perpendicular vector. Equivalent to b2CrossVS(v, 1.0f)
b2Vec2	b2Add (b2Vec2 a, b2Vec2 b)
	Vector addition.
b2Vec2	b2Sub (b2Vec2 a, b2Vec2 b)
	Vector subtraction.
b2Vec2	b2Neg (b2Vec2 a)
	Vector negation.
b2Vec2	b2Lerp (b2Vec2 a, b2Vec2 b, float t)
	Vector linear interpolation https://fgiesen.wordpress.com/2012/08/15/linear-interpolation-past-present-and-future/.
b2Vec2	b2Mul (b2Vec2 a, b2Vec2 b)
	Component-wise multiplication.
b2Vec2	b2MulSV (float s, b2Vec2 v)
	Multiply a scalar and vector.
b2Vec2	b2MulAdd (b2Vec2 a, float s, b2Vec2 b)
	a + s * b
b2Vec2	b2MulSub (b2Vec2 a, float s, b2Vec2 b)
	a - s * b
b2Vec2	b2Abs (b2Vec2 a)
	Component-wise absolute vector.
b2Vec2	b2Min (b2Vec2 a, b2Vec2 b)
	Component-wise minimum vector.
b2Vec2	b2Max (b2Vec2 a, b2Vec2 b)
	Component-wise maximum vector.
b2Vec2	b2Clamp (b2Vec2 v, b2Vec2 a, b2Vec2 b)
	Component-wise clamp vector v into the range [a, b].
float	b2Length (b2Vec2 v)
	Get the length of this vector (the norm)
float	b2Distance (b2Vec2 a, b2Vec2 b)
	Get the distance between two points.
b2Vec2	b2Normalize (b2Vec2 v)
	Convert a vector into a unit vector if possible, otherwise returns the zero vector.
bool	b2IsNormalized (b2Vec2 a)
	Determines if the provided vector is normalized (norm(a) == 1).
b2Vec2	b2GetLengthAndNormalize (float *length, b2Vec2 v)
	Convert a vector into a unit vector if possible, otherwise returns the zero vector.
b2Rot	b2NormalizeRot (b2Rot q)
	Normalize rotation.
b2Rot	b2IntegrateRotation (b2Rot q1, float deltaAngle)
	Integrate rotation from angular velocity.
float	b2LengthSquared (b2Vec2 v)
	Get the length squared of this vector.
float	b2DistanceSquared (b2Vec2 a, b2Vec2 b)
	Get the distance squared between points.
b2Rot	b2MakeRot (float radians)
	Make a rotation using an angle in radians.
b2Rot	b2ComputeRotationBetweenUnitVectors (b2Vec2 v1, b2Vec2 v2)
	Compute the rotation between two unit vectors.
bool	b2IsNormalizedRot (b2Rot q)
	Is this rotation normalized?
b2Rot	b2NLerp (b2Rot q1, b2Rot q2, float t)
	Normalized linear interpolation https://fgiesen.wordpress.com/2012/08/15/linear-interpolation-past-present-and-future/ https://web.archive.org/web/20170825184056/http://number-none.com/product/Understanding%20Slerp,%20Then%20Not%20Using%20It/.
float	b2ComputeAngularVelocity (b2Rot q1, b2Rot q2, float inv_h)
	Compute the angular velocity necessary to rotate between two rotations over a give time.
float	b2Rot_GetAngle (b2Rot q)
	Get the angle in radians in the range [-pi, pi].
b2Vec2	b2Rot_GetXAxis (b2Rot q)
	Get the x-axis.
b2Vec2	b2Rot_GetYAxis (b2Rot q)
	Get the y-axis.
b2Rot	b2MulRot (b2Rot q, b2Rot r)
	Multiply two rotations: q * r.
b2Rot	b2InvMulRot (b2Rot q, b2Rot r)
	Transpose multiply two rotations: qT * r.
float	b2RelativeAngle (b2Rot b, b2Rot a)
	relative angle between b and a (rot_b * inv(rot_a))
float	b2UnwindAngle (float radians)
	Convert an angle in the range [-2*pi, 2*pi] into the range [-pi, pi].
float	b2UnwindLargeAngle (float radians)
	Convert any into the range [-pi, pi] (slow)
b2Vec2	b2RotateVector (b2Rot q, b2Vec2 v)
	Rotate a vector.
b2Vec2	b2InvRotateVector (b2Rot q, b2Vec2 v)
	Inverse rotate a vector.
b2Vec2	b2TransformPoint (b2Transform t, const b2Vec2 p)
	Transform a point (e.g. local space to world space)
b2Vec2	b2InvTransformPoint (b2Transform t, const b2Vec2 p)
	Inverse transform a point (e.g. world space to local space)
b2Transform	b2MulTransforms (b2Transform A, b2Transform B)
	Multiply two transforms.
b2Transform	b2InvMulTransforms (b2Transform A, b2Transform B)
	Creates a transform that converts a local point in frame B to a local point in frame A.
b2Vec2	b2MulMV (b2Mat22 A, b2Vec2 v)
	Multiply a 2-by-2 matrix times a 2D vector.
b2Mat22	b2GetInverse22 (b2Mat22 A)
	Get the inverse of a 2-by-2 matrix.
b2Vec2	b2Solve22 (b2Mat22 A, b2Vec2 b)
	Solve A * x = b, where b is a column vector.
bool	b2AABB_Contains (b2AABB a, b2AABB b)
	Does a fully contain b.
b2Vec2	b2AABB_Center (b2AABB a)
	Get the center of the AABB.
b2Vec2	b2AABB_Extents (b2AABB a)
	Get the extents of the AABB (half-widths).
b2AABB	b2AABB_Union (b2AABB a, b2AABB b)
	Union of two AABBs.
b2AABB	b2MakeAABB (const b2Vec2 *points, int count, float radius)
	Compute the bounding box of an array of circles.
float	b2PlaneSeparation (b2Plane plane, b2Vec2 point)
	Signed separation of a point from a plane.
bool	b2IsValidFloat (float a)
	Is this a valid number? Not NaN or infinity.
bool	b2IsValidVec2 (b2Vec2 v)
	Is this a valid vector? Not NaN or infinity.
bool	b2IsValidRotation (b2Rot q)
	Is this a valid rotation? Not NaN or infinity. Is normalized.
bool	b2IsValidAABB (b2AABB aabb)
	Is this a valid bounding box? Not Nan or infinity. Upper bound greater than or equal to lower bound.
bool	b2IsValidPlane (b2Plane a)
	Is this a valid plane? Normal is a unit vector. Not Nan or infinity.
void	b2SetLengthUnitsPerMeter (float lengthUnits)
	Box2D bases all length units on meters, but you may need different units for your game.
float	b2GetLengthUnitsPerMeter (void)
	Get the current length units per meter.

Detailed Description

Vector math types and functions.

---

Data Structure Documentation

b2Vec2

struct b2Vec2

2D vector This can be used to represent a point or free vector

Data Fields
float	x	coordinates
float	y

b2CosSin

struct b2CosSin

Cosine and sine pair This uses a custom implementation designed for cross-platform determinism.

Data Fields
float	cosine	cosine and sine
float	sine

b2Rot

struct b2Rot

2D rotation This is similar to using a complex number for rotation

Data Fields
float	c	cosine and sine
float	s

b2Transform

struct b2Transform

A 2D rigid transform.

Collaboration diagram for b2Transform:

Data Fields
b2Vec2	p
b2Rot	q

b2Mat22

struct b2Mat22

A 2-by-2 Matrix.

Collaboration diagram for b2Mat22:

Data Fields
b2Vec2	cx	columns
b2Vec2	cy

b2AABB

struct b2AABB

Axis-aligned bounding box.

Collaboration diagram for b2AABB:

Data Fields
b2Vec2	lowerBound
b2Vec2	upperBound

b2Plane

struct b2Plane

separation = dot(normal, point) - offset

Collaboration diagram for b2Plane:

Data Fields
b2Vec2	normal
float	offset

Function Documentation

b2AbsFloat()

float b2AbsFloat

(

float

a

)

Returns

the absolute value of a float

b2AbsInt()

int b2AbsInt

(

int

a

)

Returns

the absolute value of an integer

b2Atan2()

float b2Atan2	(	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

b2ClampFloat()

float b2ClampFloat	(	float	a,
		float	lower,
		float	upper )

Returns

a float clamped between a lower and upper bound

b2ClampInt()

int b2ClampInt	(	int	a,
		int	lower,
		int	upper )

Returns

an integer clamped between a lower and upper bound

b2ComputeAngularVelocity()

float b2ComputeAngularVelocity	(	b2Rot	q1,
		b2Rot	q2,
		float	inv_h )

Compute the angular velocity necessary to rotate between two rotations over a give time.

Parameters

q1	initial rotation
q2	final rotation
inv_h	inverse time step

b2ComputeCosSin()

b2CosSin b2ComputeCosSin

(

float

radians

)

Compute the cosine and sine of an angle in radians.

Implemented for cross-platform determinism.

b2GetLengthAndNormalize()

b2Vec2 b2GetLengthAndNormalize	(	float *	length,
		b2Vec2	v )

Convert a vector into a unit vector if possible, otherwise returns the zero vector.

Also outputs the length.

b2IntegrateRotation()

b2Rot b2IntegrateRotation	(	b2Rot	q1,
		float	deltaAngle )

Integrate rotation from angular velocity.

Parameters

q1	initial rotation
deltaAngle	the angular displacement in radians

b2InvMulTransforms()

b2Transform b2InvMulTransforms	(	b2Transform	A,
		b2Transform	B )

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

v2 = A.q' * (B.q * v1 + B.p - A.p) = A.q' * B.q * v1 + A.q' * (B.p - A.p)

b2MaxFloat()

float b2MaxFloat	(	float	a,
		float	b )

Returns

the maximum of two floats

b2MaxInt()

int b2MaxInt	(	int	a,
		int	b )

Returns

the maximum of two integers

b2MinFloat()

float b2MinFloat	(	float	a,
		float	b )

Returns

the minimum of two floats

b2MinInt()

int b2MinInt	(	int	a,
		int	b )

Returns

the minimum of two integers

b2MulTransforms()

b2Transform b2MulTransforms	(	b2Transform	A,
		b2Transform	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. v2 = A.q.Rot(B.q.Rot(v1) + B.p) + A.p = (A.q * B.q).Rot(v1) + A.q.Rot(B.p) + A.p

b2Normalize()

b2Vec2 b2Normalize

(

b2Vec2

v

)

Convert a vector into a unit vector if possible, otherwise returns the zero vector.

todo MSVC is not inlining this function in several places per warning 4710

b2SetLengthUnitsPerMeter()

void b2SetLengthUnitsPerMeter

(

float

lengthUnits

)

Box2D bases all length units on meters, but you may need different units for your game.

You can set this value to use different units. This should be done at application startup and only modified once. Default value is 1. For example, if your game uses pixels for units you can use pixels for all length values sent to Box2D. There should be no extra cost. However, Box2D has some internal tolerances and thresholds that have been tuned for meters. By calling this function, Box2D is able to adjust those tolerances and thresholds to improve accuracy. A good rule of thumb is to pass the height of your player character to this function. So if your player character is 32 pixels high, then pass 32 to this function. Then you may confidently use pixels for all the length values sent to Box2D. All length values returned from Box2D will also be pixels because Box2D does not do any scaling internally. However, you are now on the hook for coming up with good values for gravity, density, and forces.

Warning

This must be modified before any calls to Box2D

b2Solve22()

b2Vec2 b2Solve22	(	b2Mat22	A,
		b2Vec2	b )

Solve A * x = b, where b is a column vector.

This is more efficient than computing the inverse in one-shot cases.