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;

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.");

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);

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);

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
maxon::Vector pos = vec;
// add
pos += offset;
// scale
pos *= 3.0;

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);
}

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);

Further Reading

maxon::Vec3::GetMax
T GetMax() const
Returns the maximum of 'x', 'y' and 'z'.
Definition: vec.h:488
maxon::BlendColor
MAXON_ATTRIBUTE_FORCE_INLINE ColorA BlendColor(const ColorA &col1, const ColorA &col2, const Float blendValue)
Definition: vector4d.h:73
maxon::Vec3::SetZero
void SetZero()
Sets all components to zero.
Definition: vec.h:341
maxon::Bool
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:172
maxon::Vec4
A vector consisting of four components X, Y, Z and W.
Definition: vec4.h:14
maxon::Vec3::IsZero
BoolType IsZero() const
Checks if each component is zero.
Definition: vec.h:325
maxon::Float
Float64 Float
Definition: apibase.h:188
maxon::Vec3::GetSquaredLength
T GetSquaredLength() const
Returns the squared length of the vector.
Definition: vec.h:411
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:168
maxon::Vec3::z
T z
Definition: vec.h:34
maxon::Col4
A color consisting of three components R, G, B and an alpha.
Definition: col4.h:14
maxon::Vec3< Float, 1 >
maxon::Vec3::x
T x
Definition: vec.h:32
maxon::IsColorPerceivedAsDark
MAXON_ATTRIBUTE_FORCE_INLINE Bool IsColorPerceivedAsDark(const ColorA &color)
Definition: vector4d.h:102
maxon::Vec3::GetAverage
T GetAverage() const
Calculates the average value of 'x', 'y' and 'z'.
Definition: vec.h:347
maxon::Vec2< Int, 1 >
maxon::Vec3::y
T y
Definition: vec.h:33
maxon::GetPerceivedBrightness
MAXON_ATTRIBUTE_FORCE_INLINE Float GetPerceivedBrightness(const ColorA &color)
Definition: vector4d.h:90
maxon::Vec3::GetColor
const Col3< T, STRIDE > & GetColor() const
Reinterprets the vector as color.
Definition: vec.h:459
maxon::Col3< Float, 1 >
maxon::Vec3::GetHashCode
UInt GetHashCode() const
Definition: vec.h:291
maxon::Vec3::IsEqual
BoolType IsEqual(const Vec3 &other, ValueTypeParam epsilon) const
Tests component-wise if the difference is no bigger than 'epsilon'.
Definition: vec.h:297
maxon::UInt
UInt64 UInt
unsigned 32/64 bit int, size depends on the platform
Definition: apibase.h:180
maxon::Vec3::GetMin
T GetMin() const
Returns the minimum of 'x', 'y' and 'z'.
Definition: vec.h:475
maxon::Vec3::GetSum
T GetSum() const
Calculates the sum of 'x', 'y' and 'z'.
Definition: vec.h:353