Vectors

About

The vector classes of the MAXON API are based on these generic vector templates:

For basic data types see Basic Data Types.

Classes

Two Component Vectors

Two-component vectors contain these members:

maxon::Float based vector classes are:

maxon::Int based vector classes are:

Three Component Vectors

Three-component vectors contain these members:

maxon::Float based vector classes are:

maxon::Int based vector classes are:

Four Component Vectors

Four-component vectors contain these members:

maxon::Float based vector classes are:

maxon::Int based vector classes are:

Data

A member of a vector can be simply accessed directly or by using the "[]" operator:

// This example creates and fills multiple maxon::Vector objects.
vecA[0] = 1.0;
vecA[1] = 2.0;
vecA[2] = 3.0;
// is the same as
vecB.x = 1.0;
vecB.y = 2.0;
vecB.z = 3.0;
T y
Definition: vec.h:40
T x
Definition: vec.h:39
T z
Definition: vec.h:41

The length or a vector can be calculated with:

// This example compares the distance of two positions
// to a reference position using GetSquaredLength().
const maxon::Vector objectA(100, 200, 300);
const maxon::Vector objectB(200, 300, 400);
const maxon::Vector reference(300, 400, 500);
const maxon::Vector distanceA = objectA - reference;
const maxon::Vector distanceB = objectB - reference;
if (distanceA.GetSquaredLength() < distanceB.GetSquaredLength())
DiagnosticOutput("Object A is closer.");
else
DiagnosticOutput("Object B is closer.");
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170
constexpr T GetSquaredLength() const
Returns the squared length of the vector.
Definition: vec.h:466

If all components of a given vector are zero, it can be checked with:

// This example checks if the given vector is zero. If not, it is set to zero.
maxon::IntVector2d vec(1, 2);
if (!vec.IsZero())
vec.SetZero();
DiagnosticOutput("Vector: @", vec);

The sum of all vector components is calculated with:

// This example gets the sum and average value of all vector components.
const maxon::Vector4d vec(1, 2, 3, 4);
const maxon::Float sum = vec.GetSum();
const maxon::Float avg = vec.GetAverage();
DiagnosticOutput("Sum: @, Average: @", sum, avg);
Float64 Float
Definition: apibase.h:211
A vector consisting of four components X, Y, Z and W.
Definition: vec4.h:21

The vector values can further be edited with:

Further values are accessed with:

// This example gets the minimum and maximum value stored in the given vector.
const maxon::Float min = vec.GetMin();
const maxon::Float max = vec.GetMax();
DiagnosticOutput("Min: @, Max: @", min, max);
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

A subset of the vector can be obtained with:

// This example defines a vector and converts it to a maxon::Color.
const maxon::Vector vector(0, 1, 0);
const maxon::Color color = vector.GetColor();
DiagnosticOutput("Color: @", color);

Assignment

A vector can be constructed and changed with the following operators:

// This example creates and constructs a new vector using the given vectors.
// copy
// add
pos += offset;
// scale
pos *= 3.0;
void Py_ssize_t * pos
Definition: dictobject.h:50

Comparison

Two vectors can be compared with:

// This example checks if the given vectors are equal
// within the range of the defined epsilon.
const maxon::Float epsilon = 0.0001;
if (vecA.IsEqual(vecB, epsilon))
{
const maxon::UInt hash = vecA.GetHashCode();
DiagnosticOutput("Hash: @", hash);
}
PyObject Py_hash_t hash
Definition: dictobject.h:35
UInt64 UInt
unsigned 32/64 bit int, size depends on the platform
Definition: apibase.h:203
BoolType IsEqual(const Vec3 &other, ValueTypeParam epsilon) const
Tests component-wise if the difference is no bigger than 'epsilon'.
Definition: vec.h:352
constexpr HashInt GetHashCode() const
Definition: vec.h:336

Mathematical Functions

Vector related mathematical functions are:

  • GetAngle(): Calculates the angle between the given vectors.
  • Cross(): Calculates the cross product.
  • Dot(): Calculates the dot product.
Note
For more complex vector operations like intersections see Geometry Utility Manual.
// This example performs various mathematical operations on the given vectors.
const maxon::Vector vecA(0, 1, 0);
const maxon::Vector vecB(1, 0, 0);
const maxon::Float angle = GetAngle(vecA, vecB);
const maxon::Float dot = Dot(vecA, vecB);
const maxon::Vector cross = Cross(vecA, vecB);

Colors

For vectors defining a color value the explicit class maxon::Color exists:

// This example defines a vector and converts it to a maxon::Color.
const maxon::Vector vector(0, 1, 0);
const maxon::Color color = vector.GetColor();
DiagnosticOutput("Color: @", color);

Utility

Further utility functions are:

  • maxon::ReflectRay(): Calculates the reflection vector for the given vector to the given normal.

Color specific utility functions are:

// This example blends the given two colors and calculates the result color brightness.
const maxon::ColorA colorA { 1.0, 0.0, 1.0, 1.0 };
const maxon::ColorA colorB { 0.0, 1.0, 0.0, 1.0 };
// blend colors
const maxon::ColorA colorBlend = maxon::BlendColor(colorA, colorB, 0.5);
// get brightness
const maxon::Float brightness = maxon::GetPerceivedBrightness(colorBlend);
const maxon::Bool dark = maxon::IsColorPerceivedAsDark(colorBlend);
DiagnosticOutput("Color @, Brightness @, Dark @", colorBlend, brightness, dark);
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:195
MAXON_ATTRIBUTE_FORCE_INLINE Bool IsColorPerceivedAsDark(const ColorA &color)
Definition: vector4d.h:241
MAXON_ATTRIBUTE_FORCE_INLINE Float GetPerceivedBrightness(const ColorA &color)
Definition: vector4d.h:229
constexpr MAXON_ATTRIBUTE_FORCE_INLINE COLORTYPE BlendColor(const COLORTYPE &col1, const COLORTYPE &col2, const typename COLORTYPE::ValueType blendValue)
Definition: vector4d.h:212
A color consisting of three components R, G, B and an alpha.
Definition: col4.h:16

Further Reading