Additional Math Functions

Additional functions for common mathematical operations. More...

Functions

template<typename T , typename U >
PLAYRHO_CONSTEXPRplayrho::Secant (T target, U a1, T s1, U a2, T s2) noexcept
 Secant method. More...
 
template<typename T >
PLAYRHO_CONSTEXPRplayrho::Bisect (T a1, T a2) noexcept
 Bisection method. More...
 
template<typename T >
PLAYRHO_CONSTEXPR bool playrho::IsOdd (T val) noexcept
 Is-odd. More...
 
template<class TYPE >
PLAYRHO_CONSTEXPR auto playrho::Square (TYPE t) noexcept
 Squares the given value. More...
 
template<typename T >
auto playrho::Atan2 (T y, T x)
 Computes the arc-tangent of the given y and x values. More...
 
template<typename T , typename = std::enable_if_t< IsIterable<T>::value && IsAddable<decltype(*begin(std::declval<T>()))>::value>
auto playrho::Average (const T &span)
 Computes the average of the given values. More...
 
template<typename T >
std::enable_if_t< IsArithmetic< T >::value, T > playrho::RoundOff (T value, unsigned precision=100000)
 Computes the rounded value of the given value. More...
 
Vec2 playrho::RoundOff (Vec2 value, std::uint32_t precision=100000)
 Computes the rounded value of the given value. More...
 
template<typename T , std::size_t N>
PLAYRHO_CONSTEXPR Vector< T, N > playrho::abs (const Vector< T, N > &v) noexcept
 Absolute value function for vectors. More...
 
d2::UnitVec playrho::abs (const d2::UnitVec &v) noexcept
 Gets the absolute value of the given value. More...
 
template<typename T >
PLAYRHO_CONSTEXPR std::enable_if_t< std::is_arithmetic< T >::value, bool > playrho::AlmostZero (T value)
 Gets whether a given value is almost zero. More...
 
template<typename T >
PLAYRHO_CONSTEXPR std::enable_if_t< std::is_floating_point< T >::value, bool > playrho::AlmostEqual (T x, T y, int ulp=2)
 Determines whether the given two values are "almost equal". More...
 
template<typename T >
auto playrho::ModuloViaFmod (T dividend, T divisor) noexcept
 Modulo operation using std::fmod. More...
 
template<typename T >
auto playrho::ModuloViaTrunc (T dividend, T divisor) noexcept
 Modulo operation using std::trunc. More...
 
Angle playrho::GetNormalized (Angle value) noexcept
 Gets the "normalized" value of the given angle. More...
 
template<class T >
Angle playrho::GetAngle (const Vector2< T > value)
 Gets the angle. More...
 
template<typename T >
PLAYRHO_CONSTEXPR auto playrho::GetMagnitudeSquared (T value) noexcept
 Gets the square of the magnitude of the given iterable value. More...
 
template<typename T >
auto playrho::GetMagnitude (T value)
 Gets the magnitude of the given value. More...
 
template<typename T1 , typename T2 >
PLAYRHO_CONSTEXPR auto playrho::Dot (const T1 a, const T2 b) noexcept
 Performs the dot product on two vectors (A and B). More...
 
template<class T1 , class T2 , std::enable_if_t< std::tuple_size< T1 >::value==2 &&std::tuple_size< T2 >::value==2, int > = 0>
PLAYRHO_CONSTEXPR auto playrho::Cross (T1 a, T2 b) noexcept
 Performs the 2-element analog of the cross product of two vectors. More...
 
template<typename T , typename U >
PLAYRHO_CONSTEXPR auto playrho::Solve (const Matrix22< U > mat, const Vector2< T > b) noexcept
 Solves A * x = b, where b is a column vector. More...
 
template<class IN_TYPE >
PLAYRHO_CONSTEXPR auto playrho::Invert (const Matrix22< IN_TYPE > value) noexcept
 Inverts the given value. More...
 
PLAYRHO_CONSTEXPR Vec3 playrho::Solve33 (const Mat33 &mat, const Vec3 b) noexcept
 Solves A * x = b, where b is a column vector. More...
 
template<typename T >
PLAYRHO_CONSTEXPRplayrho::Solve22 (const Mat33 &mat, const T b) noexcept
 Solves A * x = b, where b is a column vector. More...
 
PLAYRHO_CONSTEXPR Mat33 playrho::GetInverse22 (const Mat33 &value) noexcept
 Gets the inverse of the given matrix as a 2-by-2. More...
 
PLAYRHO_CONSTEXPR Mat33 playrho::GetSymInverse33 (const Mat33 &value) noexcept
 Gets the symmetric inverse of this matrix as a 3-by-3. More...
 
template<class T >
PLAYRHO_CONSTEXPR auto playrho::GetRevPerpendicular (const T vector) noexcept
 Gets a vector counter-clockwise (reverse-clockwise) perpendicular to the given vector. More...
 
template<class T >
PLAYRHO_CONSTEXPR auto playrho::GetFwdPerpendicular (const T vector) noexcept
 Gets a vector clockwise (forward-clockwise) perpendicular to the given vector. More...
 
template<std::size_t M, typename T1 , std::size_t N, typename T2 >
PLAYRHO_CONSTEXPR auto playrho::Transform (const Vector< T1, M > v, const Matrix< T2, M, N > &m) noexcept
 Multiplies an M-element vector by an M-by-N matrix. More...
 
PLAYRHO_CONSTEXPR Vec2 playrho::Transform (const Vec2 v, const Mat33 &A) noexcept
 Multiplies a vector by a matrix. More...
 
PLAYRHO_CONSTEXPR Vec2 playrho::InverseTransform (const Vec2 v, const Mat22 &A) noexcept
 
PLAYRHO_CONSTEXPR Mat22 playrho::MulT (const Mat22 &A, const Mat22 &B) noexcept
 Computes A^T * B. More...
 
Mat22 playrho::abs (const Mat22 &A)
 Gets the absolute value of the given value. More...
 
std::uint64_t playrho::NextPowerOfTwo (std::uint64_t x)
 Gets the next largest power of 2. More...
 
Real playrho::Normalize (Vec2 &vector)
 Converts the given vector into a unit vector and returns its original length. More...
 
Length2 playrho::ComputeCentroid (const Span< const Length2 > &vertices)
 Computes the centroid of a counter-clockwise array of 3 or more vertices. More...
 
template<typename T >
PLAYRHO_CONSTEXPRplayrho::GetModuloNext (T value, T count) noexcept
 Gets the modulo next value. More...
 
template<typename T >
PLAYRHO_CONSTEXPRplayrho::GetModuloPrev (T value, T count) noexcept
 Gets the modulo previous value. More...
 
Angle playrho::GetDelta (Angle a1, Angle a2) noexcept
 Gets the shortest angular distance to go from angle 1 to angle 2. More...
 
PLAYRHO_CONSTEXPR Angle playrho::GetRevRotationalAngle (Angle a1, Angle a2) noexcept
 
std::vector< Length2playrho::GetCircleVertices (Length radius, unsigned slices, Angle start=0_deg, Real turns=Real{1})
 Gets the vertices for a circle described by the given parameters. More...
 
NonNegative< Areaplayrho::GetAreaOfCircle (Length radius)
 Gets the area of a circle. More...
 
NonNegative< Areaplayrho::GetAreaOfPolygon (Span< const Length2 > vertices)
 Gets the area of a polygon. More...
 
SecondMomentOfArea playrho::GetPolarMoment (Span< const Length2 > vertices)
 Gets the polar moment of the area enclosed by the given vertices. More...
 
template<typename T , std::size_t N>
PLAYRHO_CONSTEXPR Vector< T, N > abs (const Vector< T, N > &v) noexcept
 Absolute value function for vectors. More...
 

Detailed Description

Additional functions for common mathematical operations.

These are non-member non-friend functions for mathematical operations especially those with mixed input and output types.

Function Documentation

◆ Secant()

template<typename T , typename U >
PLAYRHO_CONSTEXPR U playrho::Secant ( target,
a1,
s1,
a2,
s2 
)
inlinenoexcept

Secant method.

See also
https://en.wikipedia.org/wiki/Secant_method

Definition at line 132 of file Math.hpp.

◆ Bisect()

template<typename T >
PLAYRHO_CONSTEXPR T playrho::Bisect ( a1,
a2 
)
inlinenoexcept

Bisection method.

See also
https://en.wikipedia.org/wiki/Bisection_method

Definition at line 141 of file Math.hpp.

◆ IsOdd()

template<typename T >
PLAYRHO_CONSTEXPR bool playrho::IsOdd ( val)
inlinenoexcept

Is-odd.

Determines whether the given integral value is odd (as opposed to being even).

Definition at line 149 of file Math.hpp.

◆ Square()

template<class TYPE >
PLAYRHO_CONSTEXPR auto playrho::Square ( TYPE  t)
inlinenoexcept

Squares the given value.

Examples
World.cpp.

Definition at line 157 of file Math.hpp.

◆ Atan2()

template<typename T >
auto playrho::Atan2 ( y,
x 
)
inline

Computes the arc-tangent of the given y and x values.

Returns
Normalized angle - an angle between -Pi and Pi inclusively.
See also
http://en.cppreference.com/w/cpp/numeric/math/atan2

Definition at line 163 of file Math.hpp.

◆ Average()

template<typename T , typename = std::enable_if_t< IsIterable<T>::value && IsAddable<decltype(*begin(std::declval<T>()))>::value>
auto playrho::Average ( const T &  span)
inline

Computes the average of the given values.

Definition at line 172 of file Math.hpp.

◆ RoundOff() [1/2]

template<typename T >
std::enable_if_t<IsArithmetic<T>::value, T> playrho::RoundOff ( value,
unsigned  precision = 100000 
)
inline

Computes the rounded value of the given value.

Definition at line 189 of file Math.hpp.

◆ RoundOff() [2/2]

Vec2 playrho::RoundOff ( Vec2  value,
std::uint32_t  precision = 100000 
)
inline

Computes the rounded value of the given value.

Definition at line 196 of file Math.hpp.

◆ abs() [1/4]

template<typename T , std::size_t N>
PLAYRHO_CONSTEXPR Vector< T, N > abs ( const Vector< T, N > &  v)
inlinenoexcept

Absolute value function for vectors.

Definition at line 204 of file Math.hpp.

◆ abs() [2/4]

d2::UnitVec playrho::abs ( const d2::UnitVec v)
inlinenoexcept

Gets the absolute value of the given value.

Definition at line 215 of file Math.hpp.

◆ AlmostZero()

template<typename T >
PLAYRHO_CONSTEXPR std::enable_if_t<std::is_arithmetic<T>::value, bool> playrho::AlmostZero ( value)
inline

Gets whether a given value is almost zero.

An almost zero value is "subnormal". Dividing by these values can lead to odd results like a divide by zero trap occurring.

Returns
true if the given value is almost zero, false otherwise.

Definition at line 226 of file Math.hpp.

◆ AlmostEqual()

template<typename T >
PLAYRHO_CONSTEXPR std::enable_if_t<std::is_floating_point<T>::value, bool> playrho::AlmostEqual ( x,
y,
int  ulp = 2 
)
inline

Determines whether the given two values are "almost equal".

Definition at line 234 of file Math.hpp.

◆ ModuloViaFmod()

template<typename T >
auto playrho::ModuloViaFmod ( dividend,
divisor 
)
inlinenoexcept

Modulo operation using std::fmod.

Note
Modulo via std::fmod appears slower than via std::trunc.
See also
ModuloViaTrunc

Definition at line 249 of file Math.hpp.

◆ ModuloViaTrunc()

template<typename T >
auto playrho::ModuloViaTrunc ( dividend,
divisor 
)
inlinenoexcept

Modulo operation using std::trunc.

Note
Modulo via std::fmod appears slower than via std::trunc.
See also
ModuloViaFmod

Definition at line 259 of file Math.hpp.

◆ GetNormalized()

Angle playrho::GetNormalized ( Angle  value)
inlinenoexcept

Gets the "normalized" value of the given angle.

Returns
Angle between -Pi and Pi radians inclusively where 0 represents the positive X-axis.
See also
Atan2

Definition at line 270 of file Math.hpp.

◆ GetAngle()

template<class T >
Angle playrho::GetAngle ( const Vector2< T >  value)
inline

Gets the angle.

Returns
Angular value in the range of -Pi to +Pi radians.

Definition at line 299 of file Math.hpp.

◆ GetMagnitudeSquared()

template<typename T >
PLAYRHO_CONSTEXPR auto playrho::GetMagnitudeSquared ( value)
inlinenoexcept

Gets the square of the magnitude of the given iterable value.

Note
For performance, use this instead of GetMagnitude(T value) (if possible).
Returns
Non-negative value from 0 to infinity, or NaN.

Definition at line 309 of file Math.hpp.

◆ GetMagnitude()

template<typename T >
auto playrho::GetMagnitude ( value)
inline

Gets the magnitude of the given value.

Note
Works for any type for which GetMagnitudeSquared also works.
Examples
World.cpp.

Definition at line 324 of file Math.hpp.

◆ Dot()

template<typename T1 , typename T2 >
PLAYRHO_CONSTEXPR auto playrho::Dot ( const T1  a,
const T2  b 
)
inlinenoexcept

Performs the dot product on two vectors (A and B).

The dot product of two vectors is defined as: the magnitude of vector A, multiplied by, the magnitude of vector B, multiplied by, the cosine of the angle between the two vectors (A and B). Thus the dot product of two vectors is a value ranging between plus and minus the magnitudes of each vector times each other. The middle value of 0 indicates that two vectors are perpendicular to each other (at an angle of +/- 90 degrees from each other).

Note
This operation is commutative. I.e. Dot(a, b) == Dot(b, a).
If A and B are the same vectors, GetMagnitudeSquared(Vec2) returns the same value using effectively one less input parameter.
This is similar to the std::inner_product standard library algorithm except benchmark tests suggest this implementation is faster at least for Vec2 like instances.
See also
https://en.wikipedia.org/wiki/Dot_product
Parameters
aVector A.
bVector B.
Returns
Dot product of the vectors (0 means the two vectors are perpendicular).

Definition at line 354 of file Math.hpp.

◆ Cross()

template<class T1 , class T2 , std::enable_if_t< std::tuple_size< T1 >::value==2 &&std::tuple_size< T2 >::value==2, int > = 0>
PLAYRHO_CONSTEXPR auto playrho::Cross ( T1  a,
T2  b 
)
inlinenoexcept

Performs the 2-element analog of the cross product of two vectors.

Cross-products the given two values.

Defined as the result of: (a.x * b.y) - (a.y * b.x).

Note
This operation is dimension squashing. I.e. A cross of a 2-D length by a 2-D unit vector results in a 1-D length value.
The unit of the result is the 1-D product of the inputs.
This operation is anti-commutative. I.e. Cross(a, b) == -Cross(b, a).
The result will be 0 if any of the following are true: vector A or vector B has a length of zero; vectors A and B point in the same direction; or vectors A and B point in exactly opposite direction of each other.
The result will be positive if: neither vector A nor B has a length of zero; and vector B is at an angle from vector A of greater than 0 and less than 180 degrees (counter-clockwise from A being a positive angle).
Result will be negative if: neither vector A nor B has a length of zero; and vector B is at an angle from vector A of less than 0 and greater than -180 degrees (clockwise from A being a negative angle).
The absolute value of the result is the area of the parallelogram formed by the vectors A and B.
See also
https://en.wikipedia.org/wiki/Cross_product
Returns
Cross product of the two values.
Note
This operation is anti-commutative. I.e. Cross(a, b) == -Cross(b, a).
See also
https://en.wikipedia.org/wiki/Cross_product
Parameters
aValue A of a 3-element type.
bValue B of a 3-element type.
Returns
Cross product of the two values.

Definition at line 399 of file Math.hpp.

◆ Solve()

template<typename T , typename U >
PLAYRHO_CONSTEXPR auto playrho::Solve ( const Matrix22< U >  mat,
const Vector2< T >  b 
)
inlinenoexcept

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

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

Definition at line 451 of file Math.hpp.

◆ Invert()

template<class IN_TYPE >
PLAYRHO_CONSTEXPR auto playrho::Invert ( const Matrix22< IN_TYPE >  value)
inlinenoexcept

Inverts the given value.

Definition at line 465 of file Math.hpp.

◆ Solve33()

PLAYRHO_CONSTEXPR Vec3 playrho::Solve33 ( const Mat33 mat,
const Vec3  b 
)
inlinenoexcept

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

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

Definition at line 480 of file Math.hpp.

◆ Solve22()

template<typename T >
PLAYRHO_CONSTEXPR T playrho::Solve22 ( const Mat33 mat,
const T  b 
)
inlinenoexcept

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

Note
This is more efficient than computing the inverse in one-shot cases.
Solves only the upper 2-by-2 matrix equation.

Definition at line 494 of file Math.hpp.

◆ GetInverse22()

PLAYRHO_CONSTEXPR Mat33 playrho::GetInverse22 ( const Mat33 value)
inlinenoexcept

Gets the inverse of the given matrix as a 2-by-2.

Returns
Zero matrix if singular.

Definition at line 505 of file Math.hpp.

◆ GetSymInverse33()

PLAYRHO_CONSTEXPR Mat33 playrho::GetSymInverse33 ( const Mat33 value)
inlinenoexcept

Gets the symmetric inverse of this matrix as a 3-by-3.

Returns
Zero matrix if singular.

Definition at line 518 of file Math.hpp.

◆ GetRevPerpendicular()

template<class T >
PLAYRHO_CONSTEXPR auto playrho::GetRevPerpendicular ( const T  vector)
inlinenoexcept

Gets a vector counter-clockwise (reverse-clockwise) perpendicular to the given vector.

This takes a vector of form (x, y) and returns the vector (-y, x).

Parameters
vectorVector to return a counter-clockwise perpendicular equivalent for.
Returns
A counter-clockwise 90-degree rotation of the given vector.
See also
GetFwdPerpendicular.

Definition at line 547 of file Math.hpp.

◆ GetFwdPerpendicular()

template<class T >
PLAYRHO_CONSTEXPR auto playrho::GetFwdPerpendicular ( const T  vector)
inlinenoexcept

Gets a vector clockwise (forward-clockwise) perpendicular to the given vector.

This takes a vector of form (x, y) and returns the vector (y, -x).

Parameters
vectorVector to return a clockwise perpendicular equivalent for.
Returns
A clockwise 90-degree rotation of the given vector.
See also
GetRevPerpendicular.

Definition at line 559 of file Math.hpp.

◆ Transform() [1/2]

template<std::size_t M, typename T1 , std::size_t N, typename T2 >
PLAYRHO_CONSTEXPR auto playrho::Transform ( const Vector< T1, M >  v,
const Matrix< T2, M, N > &  m 
)
inlinenoexcept

Multiplies an M-element vector by an M-by-N matrix.

Parameters
vVector that's interpreted as a matrix with 1 row and M-columns.
mAn M-row by N-column transformation matrix to multiply the vector by.
See also
https://en.wikipedia.org/wiki/Transformation_matrix

Definition at line 570 of file Math.hpp.

◆ Transform() [2/2]

PLAYRHO_CONSTEXPR Vec2 playrho::Transform ( const Vec2  v,
const Mat33 A 
)
inlinenoexcept

Multiplies a vector by a matrix.

Definition at line 576 of file Math.hpp.

◆ InverseTransform()

PLAYRHO_CONSTEXPR Vec2 playrho::InverseTransform ( const Vec2  v,
const Mat22 A 
)
inlinenoexcept

Multiply a matrix transpose times a vector. If a rotation matrix is provided, then this transforms the vector from one frame to another (inverse transform).

Definition at line 586 of file Math.hpp.

◆ MulT()

PLAYRHO_CONSTEXPR Mat22 playrho::MulT ( const Mat22 A,
const Mat22 B 
)
inlinenoexcept

Computes A^T * B.

Definition at line 592 of file Math.hpp.

◆ abs() [3/4]

Mat22 playrho::abs ( const Mat22 A)
inline

Gets the absolute value of the given value.

Definition at line 600 of file Math.hpp.

◆ NextPowerOfTwo()

std::uint64_t playrho::NextPowerOfTwo ( std::uint64_t  x)
inline

Gets the next largest power of 2.

Given a binary integer value x, the next largest power of 2 can be computed by a S.W.A.R. algorithm that recursively "folds" the upper bits into the lower bits. This process yields a bit vector with the same most significant 1 as x, but all one's below it. Adding 1 to that value yields the next largest power of 2. For a 64-bit value:"

Definition at line 611 of file Math.hpp.

◆ Normalize()

Real playrho::Normalize ( Vec2 vector)
inline

Converts the given vector into a unit vector and returns its original length.

Definition at line 623 of file Math.hpp.

◆ ComputeCentroid()

Length2 playrho::ComputeCentroid ( const Span< const Length2 > &  vertices)

Computes the centroid of a counter-clockwise array of 3 or more vertices.

Note
Behavior is undefined if there are less than 3 vertices or the vertices don't go counter-clockwise.

Definition at line 44 of file Math.cpp.

◆ GetModuloNext()

template<typename T >
PLAYRHO_CONSTEXPR T playrho::GetModuloNext ( value,
count 
)
inlinenoexcept

Gets the modulo next value.

Definition at line 643 of file Math.hpp.

◆ GetModuloPrev()

template<typename T >
PLAYRHO_CONSTEXPR T playrho::GetModuloPrev ( value,
count 
)
inlinenoexcept

Gets the modulo previous value.

Definition at line 651 of file Math.hpp.

◆ GetDelta()

Angle playrho::GetDelta ( Angle  a1,
Angle  a2 
)
noexcept

Gets the shortest angular distance to go from angle 1 to angle 2.

This gets the angle to rotate angle 1 by in order to get to angle 2 with the least amount of rotation.

Returns
Angle between -Pi and Pi radians inclusively.
See also
GetNormalized

Definition at line 26 of file Math.cpp.

◆ GetRevRotationalAngle()

PLAYRHO_CONSTEXPR Angle playrho::GetRevRotationalAngle ( Angle  a1,
Angle  a2 
)
inlinenoexcept

Gets the reverse (counter) clockwise rotational angle to go from angle 1 to angle 2.

Returns
Angular rotation in the counter clockwise direction to go from angle 1 to angle 2.

Definition at line 666 of file Math.hpp.

◆ GetCircleVertices()

std::vector< Length2 > playrho::GetCircleVertices ( Length  radius,
unsigned  slices,
Angle  start,
Real  turns 
)

Gets the vertices for a circle described by the given parameters.

Definition at line 80 of file Math.cpp.

◆ GetAreaOfCircle()

NonNegative< Area > playrho::GetAreaOfCircle ( Length  radius)

Gets the area of a circle.

Definition at line 113 of file Math.cpp.

◆ GetAreaOfPolygon()

NonNegative< Area > playrho::GetAreaOfPolygon ( Span< const Length2 vertices)

Gets the area of a polygon.

Note
This function is valid for any non-self-intersecting (simple) polygon, which can be convex or concave.
Winding order doesn't matter.

Definition at line 118 of file Math.cpp.

◆ GetPolarMoment()

SecondMomentOfArea playrho::GetPolarMoment ( Span< const Length2 vertices)

Gets the polar moment of the area enclosed by the given vertices.

Warning
Behavior is undefined if given collection has less than 3 vertices.
Parameters
verticesCollection of three or more vertices.

Definition at line 138 of file Math.cpp.

◆ abs() [4/4]

template<typename T , std::size_t N>
PLAYRHO_CONSTEXPR Vector< T, N > abs ( const Vector< T, N > &  v)
related

Absolute value function for vectors.

Examples
World.cpp.

Definition at line 204 of file Math.hpp.