Mathematical Functions Manual (Cinema API)

Table of Contents

• About
• Constants
• Generic Datatypes
• Exponent
• Trigonometry
• Limit
• Miscellaneous
• Further Reading

About

The Cinema API provides basic mathematical constants and functions to perform mathematical operations using its data types.

See also Primitive Data Types Manual (Cinema API).

Warning

For Maxon API maths functions see Mathematical Functions.

Constants

These mathematical constants are defined as a ::Float64 values:

• maxon::PI: The value of pi.
• maxon::PI_INV: The value of 1.0 / pi.
• maxon::PI2: The value of 2.0 * pi.
• maxon::PI2_INV: The value of 1.0 / (2.0 * pi).
• maxon::PI05: The value of 0.5 * pi.

  // This example calculates the area of the given "Disc" object.
 
  GeData data;
  disc->GetParameter(ConstDescID(DescLevel(PRIM_DISC_ORAD)), data, DESCFLAGS_GET::NONE);
 
  const Float64 radius = data.GetFloat();
  const Float64 area = maxon::PI * maxon::Pow(radius, 2.0);

Further constants are:

• ::COLORTOINT_MULTIPLIER: Constant to convert from vectors color components to integers. See also Color Functions Manual.
• PERCENT: Constant to convert from 0.0-1.0 range to percentage.
• THIRD: Constant to calculate the third of a value.
• ::SIXTH: Constant to calculate the sixth of a value.
• MAXRANGE: Maximum value for metric data.
• MAXELEMENTS: Maximum number of points of a polygon or spline object.
• MIN_EPSILON: Minimum epsilon value.

Generic Datatypes

These template functions can be applied to all data types that support the required operations. The list, not limited to, includes:

• Abs(X f): Calculates the absolute value of any data type.
• Min(X a, X b): Calculates the minimum of two values and returns it.
• Max(X a, X b): Calculates the maximum of two values and returns it.
• Swap(X &a, X &b): Swaps two values. If available, move semantics will be used.
• ClampValue(X a, X b, X c): Clips a value against a lower and an upper limit. The new value is returned.
• Sqr(X a, X b): Calculates square of a value.
• SetMax(T & a,const T & b): Assigns the maximum of two values to the first value.
• SetMin(T & a,const T & b): Assigns the minimum of two values to the first value.
• Sign(X f): Calculates the sign of a value.
• Mod(T a, U b): Calculates a modulo b.

Exponent

These exponential functions are available for ::Float32 and ::Float64 values. The list, not limited to, includes:

• Exp(): Calculates e raised to the power of the given value.
• Pow(): Calculates v1 raised to the power of v2.
• Ln(): Calculates the natural logarithm of the given value.
• Log10(): Calculates the logarithm in base 10 of the given value.
• Log2(): Calculates the logarithm in base 2 of the given value.
• Sqrt(): Calculates the square root of the given value.
• Sqr(): Calculates the square of the given value.

Note

If faulty input values are given to these functions, no exceptions will be generated.

    // This example calculates the 2D distance between the given points in space.
 
    const Vector posA { 1, 1, 0 };
    const Vector posB { 9, 16, 0 };
 
    const Vector vec = posB - posA;
    const Float  distance = maxon::Sqrt(maxon::Sqr(vec.x) + maxon::Sqr(vec.y));

Trigonometry

These trigonometric functions are available for ::Float32 and ::Float64 values. The list, not limited to, includes:

• Sin(): Calculates the sine of the given value.
• Cos(): Calculates the cosine of the given value.
• SinCos(): Calculates the sine and cosine of the given value in one operation.
• Tan(): Calculates the tangent of the given value.
• ATan(): Calculates the arctangent of the given value (for first and forth quadrants).
• ATan2(): Calculates the arctangent of the given value (for all four quadrants).
• Sinh(): Calculates the hyperbolic sine of the given value.
• Cosh(): Calculates the hyperbolic cosine of the given value.
• Tanh(): Calculates the hyperbolic tangent of the given value.
• ASin(): Calculates the arcsine of the given value.
• ACos(): Calculates the arccosine of the given value.
• DegToRad(): Converts float value from degrees to radians.
• RadToDeg(): Converts float value from radians to degrees.

Note

If faulty input values are given to these functions, no exceptions will be generated.

  // This example creates null objects along a circle.
 
  for (Int i = 0; i < count; ++i)
  {
    // calculate position on circle
    maxon::SinCos(angle, sin, cos);
 
    // create null
    BaseObject* const nullObject = BaseObject::Alloc(Onull);
    if (nullObject == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    // place null
    const Vector pos { sin* 100.0, cos* 100.0, 0 };
    nullObject->SetAbsPos(pos);
 
    nullObject->SetName(FormatNumber(angle, FORMAT_DEGREE, 0));
    doc->InsertObject(nullObject, nullptr, nullptr);
 
    // next step
    angle = angle + step;
  }

Limit

These functions are available for ::Float32 and ::Float64 values. The list, not limited to, includes:

• Floor(): Calculates the greatest integer less than or equal to the given value.
• Ceil(): Calculates the least integer greater than or equal to the given value.
• Clamp01(): Clips the given float value against the lower limit 0.0 and the upper limit 1.0. The result will be returned.
• StepEx(): Returns 1.0 if x is greater than or equal to a, else 0.0. Only for ::Float64.
• Boxstep(): Returns 0.0 if x is less than a and 1.0 if x is greater than b, else returns x mapped on the range [a,b].
• Smoothstep(): Returns 0.0 if x is less than a and 1.0 if x is greater than b, else returns x mapped on the range [a,b].

    // This example calculates the integer values next to the given float value.
    const Float value = 9.123;
 
    const Float previousInteger = Floor(value);
    const Float nextInteger = Ceil(value);

And for ::Int32 and ::Int64 values:

• LCut(): Limits the given value to the given borders.
• VCut(): Limits the given value to the given borders.

Miscellaneous

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

• Bias(): Returns the bias as the defined in the book "Texturing and Modeling" by Ebert.
• Truncate(): Returns the next integer value towards zero.
• Abs(): Calculates the absolute value of a floating point number.
• Inverse(): Calculates the reciprocal value (multiplicative inverse).
• Round(): Rounds a floating point value.
• Blend(): Blend between two float values by a certain amount. The new value is returned.

Minimum and maximum checks for ::Float32, ::Float64, ::Int32 and ::Int64:

• FMin(): Gets the minimum of two float values.
• FMax(): Gets the maximum of two float values.
• LMin(): Gets the minimum of two integer values (single precision version).
• VMin(): Gets the minimum of two integer values (double precision version).
• LMax(): Gets the maximum of two integer values (single precision version).
• VMax(): Gets the maximum of two integer values (double precision version).

Modulo operations for ::Float32, ::Float64, ::Int32 and ::Int64:

• Modulo(): Returns a modulo b.
• FMod(): Calculates floating point modulo.
• Modf(): Breaks a value into an integral and a fractional part.
• LModulo(): Returns a modulo b (integer modulo).

Further Reading

• Primitive Data Types Manual (Cinema API)
• Vector Manual (Cinema API)
• Matrix Manual (Cinema API)