Mathematical Functions

About

The MAXON API contains mathematical constants and functions that can be used with the basic data types. These constants and functions are defined in the general_math.h and lib_math.h header files. See also Basic Data Types.

Constants

Generic constants are:

Note
If an error occurs in a function, this function should return a proper error object. See Error Handling.

Mathematical floating point constants are:

For values and limits of data types see Basic Data Types.

// This example calculates the area of a circle of the given radius.
const maxon::Float radius = 123.0;
const maxon::Float area = maxon::PI * maxon::Sqr(radius);
Float64 Float
Definition: apibase.h:222
MAXON_ATTRIBUTE_FORCE_INLINE X Sqr(X a, X b)
Calculates square difference of two values.
Definition: apibasemath.h:373
static constexpr Float64 PI
floating point constant: PI
Definition: apibasemath.h:139

Template Functions

These template functions can be used with any data type that supports the required operations:

// This example template function clamps the given values and returned a mixed result.
// It uses template sub-functions.
template <typename T> static T ClampAndBlend(T a, T b, T min, T max, T blend)
{
return maxon::Blend(a, b, blend);
}
MAXON_ATTRIBUTE_FORCE_INLINE X ClampValue(X value, X lowerLimit, X upperLimit)
Clips a value against a lower and upper limit. The new value is returned.
Definition: apibasemath.h:358
MAXON_ATTRIBUTE_FORCE_INLINE X Blend(const X &value1, const X &value2, Y blendValue)
Blends two values. If blendValue is 0.0 value1 is returned, if blendValue is 1.0 value2 is returned....
Definition: apibasemath.h:366
const char Py_ssize_t const char Py_ssize_t Py_ssize_t max
Definition: modsupport.h:59
const char Py_ssize_t const char Py_ssize_t min
Definition: modsupport.h:58

Exponent

These exponential functions are available for maxon::Float32 and maxon::Float64 values:

Trigonometry

These trigonometric functions are available for maxon::Float32 and maxon::Float64 values:

// This example calculates coordinates along a circle.
const maxon::Int count = 100;
const maxon::Float countF = maxon::Float(count);
const maxon::Float step = maxon::PI2 / countF;
maxon::Float angle = 0.0;
for (maxon::Int i = 0; i < count; ++i)
{
maxon::SinCos(angle, sin, cos);
const maxon::Float degree = maxon::RadToDeg(angle);
// output
const maxon::String result = FormatString("Pos X: @, Y: @, at @ degree.", sin, cos, degree);
// next angle
angle += step;
}
Py_ssize_t i
Definition: abstract.h:645
Py_ssize_t count
Definition: abstract.h:640
Definition: string.h:1235
PyObject PyObject * result
Definition: abstract.h:43
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:213
MAXON_ATTRIBUTE_FORCE_INLINE void SinCos(Float32 val, Float32 &sn, Float32 &cs)
Calculates both sine and cosine of a value.
Definition: apibasemath.h:486
static constexpr Float64 PI2
floating point constant: 2.0 * PI
Definition: apibasemath.h:145
constexpr MAXON_ATTRIBUTE_FORCE_INLINE Float32 RadToDeg(Float32 r)
Converts float value from radians to degrees.
Definition: apibasemath.h:480
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:176
#define FormatString(...)
Definition: string.h:2112
PyObject PyObject * step
Definition: sliceobject.h:34

Advanced functions are:

Limit

These functions are available for maxon::Float32 and maxon::Float64 values:

  • maxon::Clamp01(): Clips a the given value against the lower limit 0 and the upper limit 1.
  • maxon::Floor(): Calculates the largest previous integer number.
  • maxon::Ceil(): Calculates the smallest following integer number.
  • maxon::SmoothStep(): Returns 0.0 if the given value is less than a and 1.0 if the value is greater than b, else returns the value mapped by a smooth curve on the range [a,b].
  • maxon::BoxStep(): Returns 0.0 if the given value is less than a and 1.0 if the value is greater than b, else returns the value mapped on the range [a,b].
// This example calculates the previous and following integer numbers for the given float value.
const maxon::Float value = 1.23;
const maxon::Float previousInt = maxon::Floor(value);
const maxon::Float nextInt = maxon::Ceil(value);
PyObject * value
Definition: abstract.h:715
MAXON_ATTRIBUTE_FORCE_INLINE Float32 Ceil(Float32 val)
Rounds to the smallest following integer number.
Definition: apibasemath.h:278
MAXON_ATTRIBUTE_FORCE_INLINE Float32 Floor(Float32 val)
Rounds to the largest previous integer number.
Definition: apibasemath.h:272

Iterables

These template functions work with all values stored in the given iterable e.g. a maxon::BaseArray:

See BaseArray Manual and Arrays Manual.

// This example gets the sum and average value of all elements stored in the BaseArray.
baseArray.Append(1.0) iferr_return;
baseArray.Append(2.0) iferr_return;
baseArray.Append(3.0) iferr_return;
const maxon::Float sum = maxon::GetSum(baseArray);
const maxon::Float average = maxon::GetAverage(baseArray);
Definition: basearray.h:415
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Append(ARG &&x)
Appends a new element at the end of the array and constructs it using the forwarded value.
Definition: basearray.h:619
MAXON_ATTRIBUTE_FORCE_INLINE std::remove_reference< ITERABLETYPE >::type::ValueType GetAverage(ITERABLETYPE &&array)
Returns the average of all elements.
Definition: lib_math.h:300
MAXON_ATTRIBUTE_FORCE_INLINE std::remove_reference< ITERABLETYPE >::type::ValueType GetSum(ITERABLETYPE &&array)
Returns the sum of all elements.
Definition: lib_math.h:287
#define iferr_return
Definition: resultbase.h:1521

Miscellaneous

These mathematical utility functions are available for maxon::Float32 and maxon::Float64 values:

  • maxon::Abs(): Calculates the absolute value of a floating point number.
  • maxon::Inverse(): Calculates the reciprocal value (multiplicative inverse).
  • maxon::Bias(): Returns the bias as the defined in the book "Texturing and Modeling" by Ebert.
  • maxon::Truncate(): Returns the next integer value towards zero.

Special maxon::UInt functions are:

  • maxon::LessThan(): Returns true if the product of the first two arguments is less than the product of the second two arguments.
  • maxon::IsPowerOfTwo(): Returns true if the given value is a power of 2.

This modulo operation is defined for maxon::Int32, maxon::Int64, maxon::Float32 and maxon::Float64.

Further Reading