Vectors

Table of Contents

• About
• Classes
  • Two Component Vectors
  • Three Component Vectors
  • Four Component Vectors
• Data
• Assignment
• Comparison
• Mathematical Functions
• Colors
• Utility
• Further Reading

About

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

• maxon::Vec2: Template for a two-component vector.
• maxon::Vec3: Template for a three-component vector.
• maxon::Vec4: Template for a four-component vector.

For basic data types see Basic Data Types.

Classes

Two Component Vectors

Two-component vectors contain these members:

• maxon::Vec2::x: X component.
• maxon::Vec2::y: Y component.

maxon::Float based vector classes are:

• maxon::Vector2d32: Two-component maxon::Float32 vector.
• maxon::Vector2d64: Two-component maxon::Float64 vector.
• maxon::Vector2d: Two-component maxon::Float vector.

maxon::Int based vector classes are:

• maxon::IntVector2d32: Two-component maxon::Int32 vector.
• maxon::UIntVector2d32: Two-component maxon::UInt32 vector.
• maxon::IntVector2d64: Two-component maxon::Int64 vector.
• maxon::UIntVector2d64: Two-component maxon::UInt64 vector.
• maxon::IntVector2d: Two-component maxon::Int vector.

Three Component Vectors

Three-component vectors contain these members:

• maxon::Vec3::x: X component.
• maxon::Vec3::y: Y component.
• maxon::Vec3::z: Z component.

maxon::Float based vector classes are:

• maxon::Vector32: Three-component maxon::Float32 vector.
• maxon::Vector64: Three-component maxon::Float64 vector.
• maxon::Vector: Three-component maxon::Float vector.
• maxon::Color32: Three-component maxon::Float32 vector.
• maxon::Color64: Three-component maxon::Float64 vector.
• maxon::Color: Three-component maxon::Float vector.

maxon::Int based vector classes are:

• maxon::IntVector32: Three-component maxon::Int32 vector.
• maxon::IntVector64: Three-component maxon::Int64 vector.
• maxon::IntVector: Three-component maxon::Int vector.

Four Component Vectors

Four-component vectors contain these members:

• maxon::Vec4::x: X component.
• maxon::Vec4::y: Y component.
• maxon::Vec4::z: Z component.
• maxon::Vec4::w: W component.

maxon::Float based vector classes are:

• maxon::Vector4d32: Four-component maxon::Float32 vector.
• maxon::Vector4d64: Four-component maxon::Float64 vector.
• maxon::Vector4d: Four-component maxon::Float vector.
• maxon::ColorA32: Four-component maxon::Float32 vector.
• maxon::ColorA64: Four-component maxon::Float64 vector.
• maxon::ColorA: Four-component maxon::Float vector.

maxon::Int based vector classes are:

• maxon::IntVector4d32: Four-component maxon::Int32 vector.
• maxon::IntVector4d64: Four-component maxon::Int64 vector.
• maxon::IntVector4d: Four-component maxon::Int vector.

Data

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

• maxon::Vec2::operator[](): Returns the vector member of the given index.

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

The length or a vector can be calculated with:

• maxon::Vec2::GetLength(): Returns the length of the vector.
• maxon::Vec2::GetSquaredLength(): Returns the squared length of the vector.

    // 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:

• maxon::Vec2::IsZero(): Returns true if all components are zero.
• maxon::Vec2::SetZero(): Sets all components to zero.

    // 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:

• maxon::Vec2::GetSum(): Returns the sum of all vector components.
• maxon::Vec2::GetAverage(): Returns the average value of all vector components.

    // 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:

• maxon::Vec2::Clamp01(): Returns a copy of the vector with values clamped from 0.0 to 1.0.
• maxon::Vec2::GetNormalized(): Returns a copy of the vector that has been normalized.
• maxon::Vec2::operator!(): Returns a copy of the vector that has been normalized.
• maxon::Vec2::Normalize(): Normalizes the vector.
• maxon::Vec2::Abs(): Returns a copy of the vector with the absolute value of each component.
• maxon::Vec2::GetRightRotated(): Returns a copy of the vector where the components have been rotated to the right.

Further values are accessed with:

• maxon::Vec2::GetMin(): Returns the value of smallest component.
• maxon::Vec2::GetMax(): Returns the value of the biggest component.

    // 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:

• maxon::Vec3::GetColor(): Returns the x/y/z components as a maxon::Color.
• maxon::Vec4::GetColor(): Returns the x/y/z components as a maxon::Color.
• maxon::Vec4::GetVector3(): Returns the x/y/z components as a maxon::Vector.

    // 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:

• maxon::Vec2::operator=(): Assigns the values of the given vector to the vector.
• maxon::Vec2::operator+=(): Adds the values of the given vector to the vector.
• maxon::Vec2::operator*=(): Multiplies each vector components respectively by the given vector components.
• maxon::Vec2::operator/=(): Divides each vector component by the given scalar.
• maxon::Vec2::operator*(): Multiplies each vector component by the given scalar.
• maxon::Vec2::operator/(): Divides each vector component by the given scalar.
• maxon::Vec2::operator-(): Negates the vector.

    // 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:

• maxon::Vec2::GetHashCode(): Returns a hash value for the vector.
• maxon::Vec2::IsEqual(): Returns true if the difference per component is not bigger than the given epsilon.

    // 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:

• maxon::Color32: RGB maxon::Float32 color value.
• maxon::Color64: RGB maxon::Float64 color value.
• maxon::Color: RGB maxon::Float color value.
• maxon::ColorA32: RGBA maxon::Float32 color value.
• maxon::ColorA64: RGBA maxon::Float64 color value.
• maxon::ColorA: RGBA maxon::Float color value.

    // 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:

• maxon::RGBToHSV(): Converts an RGB value into HSV color space.
• maxon::HSVToRGB(): Converts an HSV value into RGB color space.
• maxon::BlendColor(): Blend linearly between two colors.
• maxon::GetPerceivedBrightness(): Gets the perceived brightness from the color.
• maxon::IsColorPerceivedAsDark(): Checks if a color is perceived as dark by the human eye.

  // 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

• Geometry Utility Manual
• Data & Algorithms
• Matrices
• Basic Data Types