Vec3

The Vec3 class template represents a 3D vector, with predefined typedefs for vectors of type short, int, int64_t, float, and double.

Note that the integer specializations of Vec3 lack the length() and normalize() methods that are present in the float and double versions, because the results don’t fit into integer quantities.

There are also various utility functions that operate on vectors defined in ImathVecAlgo.h and described in Vector Functions.

Individual components of a vector V may be referenced as either V[i] or V.x, V.y, V.z. Obviously, the [] notation is more suited to looping over components, or in cases where a variable determines which coordinate is needed. However, when the coordinate is known, it can be more efficient to directly address the components, such as V.y rather than V[1]. While both appear to do the same thing (and indeed do generate the same machine operations for ordinary scalar code), when used inside loops that you hope to parallelize (either through compiler auto-vectorization or explicit hints such as #pragma omp simd), the function call and pointer casting of operator[] can confuse the compiler just enough to prevent vectorization of the loop.

Example:

#include <Imath/ImathVec.h>
#include <cassert>

void
vec3_example()
{
    Imath::V3f   a (1.0f, 2.0f, 3.0f);
    Imath::V3f   b; // b is uninitialized

    b.x = a[0];
    b.y = a[1];
    b.z = a[2];

    assert (a == b);

    assert (a.length() == sqrt (a ^ a));

    a.normalize();
    assert (Imath::equalWithAbsError (a.length(), 1.0f, 1e-6f));
}
typedef Vec3<short> Imath::V3s

Vec3 of short.

typedef Vec3<int> Imath::V3i

Vec3 of integer.

typedef Vec3<int64_t> Imath::V3i64

Vec3 of int64_t.

typedef Vec3<float> Imath::V3f

Vec3 of float.

typedef Vec3<double> Imath::V3d

Vec3 of double.

template<class T>
class Vec3

3-element vector

Subclassed by Imath::Color3< T >, Imath::Euler< T >

Direct access to elements

T x
T y
T z

Constructors and Assignment

Vec3()

Uninitialized by default.

constexpr Vec3(T a)

Initialize to a scalar (a,a,a)

constexpr Vec3(T a, T b, T c)

Initialize to given elements (a,b,c)

constexpr Vec3(const Vec3 &v)

Copy constructor.

template<class S>
constexpr Vec3(const Vec3<S> &v)

Construct from Vec3 of another base type.

template<class S>
constexpr Vec3(const Vec4<S> &v)

Vec4 to Vec3 conversion: divide x, y and z by w, even if w is 0.

The result depends on how the environment handles floating-point exceptions.

template<class S>
constexpr Vec3(const Vec4<S> &v, InfException)

Vec4 to Vec3 conversion: divide x, y and z by w.

Throws an exception if w is zero or if division by w would overflow.

constexpr const Vec3<T> &operator=(const Vec3 &v)

Assignment.

~Vec3()

Destructor.

Compatibility with Sb

template<class S>
void setValue(S a, S b, S c)

Set the value.

template<class S>
void setValue(const Vec3<S> &v)

Set the value.

template<class S>
void getValue(S &a, S &b, S &c) const

Return the value in a, b, and c

template<class S>
void getValue(Vec3<S> &v) const

Return the value in v

T *getValue()

Return a raw pointer to the array of values.

const T *getValue() const

Return a raw pointer to the array of values.

Arithmetic and Comparison

template<class S>
constexpr bool operator==(const Vec3<S> &v) const

Equality.

template<class S>
constexpr bool operator!=(const Vec3<S> &v) const

Inequality.

constexpr bool equalWithAbsError(const Vec3<T> &v, T e) const

Compare two matrices and test if they are “approximately equal”:

Return
True if the coefficients of this and m are the same with an absolute error of no more than e, i.e., for all i, j:
abs (this[i][j] - m[i][j]) <= e

constexpr bool equalWithRelError(const Vec3<T> &v, T e) const

Compare two matrices and test if they are “approximately equal”:

Return
True if the coefficients of this and m are the same with a relative error of no more than e, i.e., for all i, j:
abs (this[i] - v[i][j]) <= e * abs (this[i][j])

constexpr T dot(const Vec3 &v) const

Dot product.

constexpr T operator^(const Vec3 &v) const

Dot product.

constexpr Vec3<T> cross(const Vec3 &v) const

Right-handed cross product.

constexpr const Vec3<T> &operator%=(const Vec3 &v)

Right-handed cross product.

constexpr Vec3<T> operator%(const Vec3 &v) const

Right-handed cross product.

constexpr const Vec3<T> &operator+=(const Vec3 &v)

Component-wise addition.

constexpr Vec3<T> operator+(const Vec3 &v) const

Component-wise addition.

constexpr const Vec3<T> &operator-=(const Vec3 &v)

Component-wise subtraction.

constexpr Vec3<T> operator-(const Vec3 &v) const

Component-wise subtraction.

constexpr Vec3<T> operator-() const

Component-wise multiplication by -1.

constexpr const Vec3<T> &negate()

Component-wise multiplication by -1.

constexpr const Vec3<T> &operator*=(const Vec3 &v)

Component-wise multiplication.

constexpr const Vec3<T> &operator*=(T a)

Component-wise multiplication.

constexpr Vec3<T> operator*(const Vec3 &v) const

Component-wise multiplication.

constexpr Vec3<T> operator*(T a) const

Component-wise multiplication.

constexpr const Vec3<T> &operator/=(const Vec3 &v)

Component-wise division.

constexpr const Vec3<T> &operator/=(T a)

Component-wise division.

constexpr Vec3<T> operator/(const Vec3 &v) const

Component-wise division.

constexpr Vec3<T> operator/(T a) const

Component-wise division.

Query and Manipulation

T length() const

Return the Euclidean norm.

constexpr T length2() const

Return the square of the Euclidean norm, i.e.

the dot product with itself.

const Vec3<T> &normalize()

Normalize in place. If length()==0, return a null vector.

const Vec3<T> &normalizeExc()

Normalize in place. If length()==0, throw an exception.

const Vec3<T> &normalizeNonNull()

Normalize without any checks for length()==0.

Slightly faster than the other normalization routines, but if v.length() is 0.0, the result is undefined.

Vec3<T> normalized() const

Return a normalized vector. Does not modify *this.

Vec3<T> normalizedExc() const

Return a normalized vector.

Does not modify *this. Throw an exception if length()==0.

Vec3<T> normalizedNonNull() const

Return a normalized vector.

Does not modify *this, and does not check for length()==0. Slightly faster than the other normalization routines, but if v.length() is 0.0, the result is undefined.

Numeric Limits

static constexpr T baseTypeLowest()

Largest possible negative value.

static constexpr T baseTypeMax()

Largest possible positive value.

static constexpr T baseTypeSmallest()

Smallest possible positive value.

static constexpr T baseTypeEpsilon()

Smallest possible e for which 1+e != 1.

Public Types

typedef T BaseType

The base type: In templates that accept a parameter V, you can refer to T as V::BaseType

Public Functions

constexpr T &operator[](int i)

Element access by index.

constexpr const T &operator[](int i) const

Element access by index.

Public Static Functions

static constexpr unsigned int dimensions()

Return the number of dimensions, i.e. 3.

Warning

doxygenfunction: Unable to resolve multiple matches for function “operator<<” with arguments (std::ostream& s, const Vec3<T>& v) in doxygen xml output for project “Imath” from directory: /build/ilmbase-TFRjEc/ilmbase-3.1.11/obj-x86_64-linux-gnu/website/doxygen/xml. Potential matches:

- std::ostream &operator<<(std::ostream&, Imath::half)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Color4<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Euler<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Interval<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Line3<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Matrix22<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Matrix33<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Matrix44<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Plane3<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Quat<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Shear6<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Vec2<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Vec3<T>&)
- template<class T>
  std::ostream &Imath::operator<<(std::ostream&, const Vec4<T>&)