Math utility classes and functions.
Math Classes
The three array-like classes in fcppt.math are:
Vector and dim are one-dimensional statically sized arrays, while matrix is a two-dimensional statically sized array. Although vector and dim are very similar, they do not provide the same operations. Vectors should be used for points or arrows, while dims should be used for sizes. The three classes follow a common base design which will be explained using vectors.
There are two classes that build on top of vector and dim:
Declarations
Vector, dim and matrix are statically sized arrays. The declaration of vector uses the template parameters typename T
, fcppt::math::size_type N
and typename S
. Here, T
is the element type, N
the number of elements and S
the storage type. The latter requires further explanation: For a normal vector that owns its elements, S
can be std::array<T,N>
.
typedef
float,
2,
float,
2
>
>
vector2f;
This is exactly what fcppt::math::vector::static_ does.
typedef
float,
2
>
vector2f;
If we want a view vector, for example a vector that represents a row of a matrix, we could use S=T*
instead.
Initialization
Vector and dim are initialized in the same way: An fcppt::math::vector::object<T,N,S>
can be initialized by either:
vector2f v1(
);
v1.x() = 0.1f;
v1.y() = 0.2f;
vector2f const v2(
0.1f,
0.2f
);
Conversions
vector
, dim
and matrix
each have a structure_cast
function. Structure casts preserve dimensions but convert the underlying value type. How this is done is specified by a function object.
int,
1
> const i(
10
);
auto const f(
float,
1
>,
>(
i
)
);
vector
and dim
have functions push_back
, which increases the dimension by one, and narrow_cast
, which decreases the dimension.
int,
1
> const small(
10
);
int,
2
> const bigger(
small,
20
)
);
auto const small_again(
int,
1
>
>(
bigger
)
);
Comparison
All math classes can be compared using operator==
, for example:
vector2f const x(1.f,2.f);
vector2f const y(1.f,2.f);
std::cout << (x == y) <<
',' << (x - y == vector2f{0.f,0.f}) <<
'\n';
operator==
uses the underlying comparison operator of the value type, which is error-prone for floats. The componentwise_equal
compare using an epsilon:
vector2f const x(1.f,2.f);
vector2f const y(1.f,2.f);
float const epsilon(0.001f);
For vector
, dim
and matrix
, the following comparison operators are defined:
-
operator==
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
Arithmetic
vector
, dim
and matrix
define different arithmetic operators. See their individual documentations for more information.
It is important to note that all of the free operators support that the value types of their arguments differ. Suppose we can divide meters by seconds to get speed.
struct meter
{
};
struct second
{
};
struct speed
{
};
speed
meter,
second
)
{
return
speed{};
}
This can now be used to divide vectors of meters by vectors of seconds to obtain vectors of speeds.
typedef
meter,
2
>
meter2;
typedef
second,
2
>
second2;
typedef
speed,
2
>
speed2;
speed2
> const s{
meter2(
meter{},
meter{}
)
/
second2(
second{},
second{}
)
};
Null
vector
, dim
and box
provide null
functions that return an object consisting of zeroes.
auto const n(
vector2f
>()
);
Input and output
All classes provide an output operator operator<<
, some also provide an input operator operator>>
.
|
template<typename T > |
fcppt::optional::object< T > | fcppt::math::ceil_div (T const &_dividend, T const &_divisor) |
| Calculates dividend / divisor rounded towards infinity. More...
|
|
template<typename T > |
fcppt::optional::object< T > | fcppt::math::ceil_div_signed (T const &_dividend, T const &_divisor) |
| Calculates dividend / divisor rounded towards infinity. More...
|
|
template<typename T > |
T | fcppt::math::clamp (T const &_value, T const &_vmin, T const &_vmax) |
| Clamps a value into a range. More...
|
|
template<typename T > |
T | fcppt::math::deg_to_rad (T const deg) |
| Transforms degrees into radians. More...
|
|
template<typename T > |
T | fcppt::math::diff (T const &_a, T const &_b) |
| Calculates the absolute distance between a and b . More...
|
|
template<typename L , typename R > |
fcppt::optional::object<> | fcppt::math::div (L const &_dividend, R const &_divisor) |
| Calculates dividend / divisor. More...
|
|
template<typename Type > |
Type | fcppt::math::from_array (fcppt::math::to_array_type< Type > &&_value) |
| Constructs an object with static storage from an array rvalue. More...
|
|
template<typename Type > |
Type | fcppt::math::from_array (fcppt::math::to_array_type< Type > const &_value) |
| Constructs an object with static storage from an array lvalue. More...
|
|
template<typename Float , typename Value > |
Value | fcppt::math::interpolation::linear (Float const &_f, Value const &_v1, Value const &_v2) |
| Interpolates between two values linearly. More...
|
|
template<typename Float , typename Value > |
Value | fcppt::math::interpolation::perlin_fifth_degree (Float const &_f, Value const &_v1, Value const &_v2) |
| Interpolates between two values using perlin fifth degree. More...
|
|
template<typename Float , typename Value > |
Value | fcppt::math::interpolation::trigonometric (Float const &_f, Value const &_v1, Value const &_v2) |
| Interpolates between two values trigonometrically. More...
|
|
template<typename Type > |
Type | fcppt::math::interval_distance (fcppt::homogenous_pair< Type > _i1, fcppt::homogenous_pair< Type > _i2) |
| Calculates the distance of two intervals. More...
|
|
template<typename T > |
constexpr bool | fcppt::math::is_power_of_2 (T const x) noexcept |
| Checks if a number is a power of two. More...
|
|
template<typename T > |
bool | fcppt::math::is_zero (T const &_value) |
| Compares a value against zero. More...
|
|
template<typename T > |
T | fcppt::math::log2 (T const x) |
| Calculates for unsigned types (using a loop) More...
|
|
template<typename T > |
fcppt::optional::object< T > | fcppt::math::mod (T const &_dividend, T const &_divisor) |
| Wraps the integral modulo operator and the floating point modulo functions. More...
|
|
template<typename T > |
T | fcppt::math::next_power_of_2 (T const _value) |
| Calculates the next power of 2 for an unsigned value. More...
|
|
template<typename T > |
T | fcppt::math::pi () |
| Returns Pi for type T. More...
|
|
template<typename Result , typename Exponent > |
constexpr Result | fcppt::math::power_of_2 (Exponent const _exponent) |
| Calculates two to the power of n. More...
|
|
template<typename T > |
T | fcppt::math::rad_to_deg (T const rad) |
| Transforms radians into degrees. More...
|
|
template<typename Type > |
fcppt::math::to_array_type< Type > | fcppt::math::to_array (Type const &_value) |
| Returns the array of an object with static storage. More...
|
|
template<typename T > |
T | fcppt::math::twopi () |
| Returns two Pi for type T. More...
|
|
◆ difference_type
The difference type used for structure sizes.
◆ int_range
template<fcppt::math::size_type Start, fcppt::math::size_type End>
◆ int_range_count
template<fcppt::math::size_type Count>
A static int range starting at 0.
◆ size_type
The size type used for structure sizes.
◆ static_size
template<fcppt::math::size_type N>
◆ to_array_type
template<typename Type >
using fcppt::math::to_array_type = typedef std::array< typename Type::value_type, fcppt::math::detail::storage_size< typename Type::storage_type >::value > |
Returns the array type of an object with static storage.
◆ ceil_div()
Calculates dividend / divisor rounded towards infinity.
In case divisor is 0, nothing is returned. Otherwise, returns (dividend / divisor) if dividend can be divided by divisor, and (dividend / divisor) + 1 if dividend can not be divided by divisor.
- Template Parameters
-
◆ ceil_div_signed()
Calculates dividend / divisor rounded towards infinity.
The same as fcppt::math::ceil_div, except in case where dividend is negative, dividend / divisor is returned.
- Template Parameters
-
◆ clamp()
template<typename T >
T fcppt::math::clamp |
( |
T const & |
_value, |
|
|
T const & |
_vmin, |
|
|
T const & |
_vmax |
|
) |
| |
Clamps a value into a range.
- Precondition
_vmin
<= _vmax
◆ deg_to_rad()
template<typename T >
T fcppt::math::deg_to_rad |
( |
T const |
deg | ) |
|
|
inline |
Transforms degrees into radians.
- Template Parameters
-
◆ diff()
template<typename T >
T fcppt::math::diff |
( |
T const & |
_a, |
|
|
T const & |
_b |
|
) |
| |
|
inline |
Calculates the absolute distance between a
and b
.
- Template Parameters
-
For unsigned types, this returns:
For other types, abs(a-b)
is returned.
◆ div()
template<typename L , typename R >
Calculates dividend / divisor.
In case divisor is 0, nothing is returned.
- Template Parameters
-
◆ from_array() [1/2]
Constructs an object with static storage from an array rvalue.
◆ from_array() [2/2]
Constructs an object with static storage from an array lvalue.
◆ interval_distance()
Calculates the distance of two intervals.
Returns the distance (as defined below) of the intervals _i1 and _i2.
Distance can be zero if the intervals touch, or negative if they overlap. If they only partially overlap, the distance is negative the common length where they overlap. If one completely contains the other, the "outer" interval is split in two parts by the "inner" one. In this case, the (again negative) length of the shorter part is returned. Therefore the distance is zero if the inner interval touches the outer one.
- Template Parameters
-
◆ is_power_of_2()
template<typename T >
constexpr bool fcppt::math::is_power_of_2 |
( |
T const |
x | ) |
|
|
inlinenoexcept |
Checks if a number is a power of two.
- Template Parameters
-
T | Must be an unsigned integral type |
If you need to check whether a signed integral type is a power of two, convert it to its unsigned counterpart before checking.
◆ is_zero()
template<typename T >
bool fcppt::math::is_zero |
( |
T const & |
_value | ) |
|
|
inline |
Compares a value against zero.
Uses fcppt::literal to create a zero constant and uses operator==
for comparison.
This function is special because it also allows comparison of floating-point values against zero, which would otherwise trigger a warning.
◆ linear()
template<typename Float , typename Value >
Value fcppt::math::interpolation::linear |
( |
Float const & |
_f, |
|
|
Value const & |
_v1, |
|
|
Value const & |
_v2 |
|
) |
| |
Interpolates between two values linearly.
- Template Parameters
-
Float | Must be a floating point type |
Value | Must support scalar multiplication with Float and addition |
◆ log2()
template<typename T >
T fcppt::math::log2 |
( |
T const |
x | ) |
|
|
inline |
Calculates
for unsigned types (using a loop)
- Template Parameters
-
T | Must be an unsigned integral type |
- Warning
- Behaviour is undefined if
x
is 0.
◆ mod()
Wraps the integral modulo operator and the floating point modulo functions.
It uses std::fmod for floating point types. Otherwise % is used. Returns nothing if _divisor is zero.
- Template Parameters
-
T | A floating-point type or an unsigned type. |
◆ next_power_of_2()
template<typename T >
T fcppt::math::next_power_of_2 |
( |
T const |
_value | ) |
|
Calculates the next power of 2 for an unsigned value.
- Template Parameters
-
◆ perlin_fifth_degree()
template<typename Float , typename Value >
Value fcppt::math::interpolation::perlin_fifth_degree |
( |
Float const & |
_f, |
|
|
Value const & |
_v1, |
|
|
Value const & |
_v2 |
|
) |
| |
Interpolates between two values using perlin fifth degree.
- Template Parameters
-
Float | Must be a floating point type |
Value | Must support scalar multiplication with Float and addition |
◆ pi()
Returns Pi for type T.
- Template Parameters
-
T | Must be a floating point type |
◆ power_of_2()
template<typename Result , typename Exponent >
constexpr Result fcppt::math::power_of_2 |
( |
Exponent const |
_exponent | ) |
|
|
inline |
Calculates two to the power of n.
Returns 2 ^ _exponent
.
- Template Parameters
-
Exponent | Must be an unsigned type. |
Result | Must be a type constructible with fcppt::literal. |
◆ rad_to_deg()
template<typename T >
T fcppt::math::rad_to_deg |
( |
T const |
rad | ) |
|
|
inline |
Transforms radians into degrees.
- Template Parameters
-
◆ to_array()
Returns the array of an object with static storage.
◆ trigonometric()
template<typename Float , typename Value >
Value fcppt::math::interpolation::trigonometric |
( |
Float const & |
_f, |
|
|
Value const & |
_v1, |
|
|
Value const & |
_v2 |
|
) |
| |
Interpolates between two values trigonometrically.
- Template Parameters
-
Float | Must be a floating point type |
Value | Must support scalar multiplication with Float and addition |
◆ twopi()
Returns two Pi for type T.
- Template Parameters
-
T | Must be a floating point type |