neuray API Programmer's Manual

mi::math::Vector< T, DIM> Template Class Reference

[Math Vector Class]

template< class T, Size DIM>

class mi::math::Vector< T, DIM>

Description

Fixed-size math vector class template with generic operations. This class template provides array-like storage for DIM many values of an arithmetic type T. Several functions and arithmetic operators support the work with vectors.

An instantiation of the vector class template is a model of the STL container concept. It provides random access to its elements and corresponding random access iterators.

The template parameters have the following requirements:

  • T: an arithmetic type supporting + - * / == != < > <= >= sqrt() .

  • DIM: a value > 0 of type mi::Size that defines the fixed dimension of the vector.

Depending on the dimension DIM, the mi::math::Vector class template offers element access through the conventional data members named x, y, z, and w. Assuming a vector vec of suitable dimension, the following expressions are valid

  • vec.x; equivalent to vec[0] and available if 1 <= DIM <= 4.

  • vec.y; equivalent to vec[1] and available if 2 <= DIM <= 4.

  • vec.z; equivalent to vec[2] and available if 3 <= DIM <= 4.

  • vec.w; equivalent to vec[3] and available if 4 <= DIM <= 4.

These data members allow users to access elements, as illustrated in the following example: 

‎    mi::math::Vector< mi::Float64, 3> vec( 0.0);
    vec.x = 4.0;

See also:

For the free functions and operators available for vectors and vector-like classes see Math Vector Class.

The underlying POD type mi::math::Vector_struct.

Include File:

#include <mi/math/vector.h>

mi::math::Vector_struct\< T, DIM \>Generic storage class template for math vector representations storing DIM elements of type T.

Public Typedefs

typedef Vector_struct< T, DIM> Pod_type
POD class corresponding to this vector.
typedef T *  const_pointer
Const pointer to element.
typedef T &  const_reference
Const reference to element.
typedef Difference difference_type
Difference type, signed.
typedef T *  pointer
Mutable pointer to element.
typedef T &  reference
Mutable reference to element.
typedef Size size_type
Size type, unsigned.
typedef Vector_struct< T, DIM> storage_type
Storage class used by this vector.
typedef T  value_type
Element type.

Public Constructors

 Vector()
The default constructor leaves the vector elements uninitialized.
 Vector( const Vector < T , DIM >& vec)
Default copy constructor.
 Vector( const Vector_struct < T , DIM >& vec)
Constructor from underlying storage type.
 Vector( T v)
Constructor initializes all vector elements to the value v.
template< typename Iterator> Vector( From_iterator_tag, Iterator p)
Constructor requires the mi::math::FROM_ITERATOR tag as first argument and initializes the vector elements with the first DIM elements from the sequence starting at the iterator p. More...
template< typename T2> Vector( const T2 (&) array[DIM])
Constructor initializes the vector elements from an array of dimension DIM. More...
template< typename T2> Vector( const Vector < T2 , DIM >& other)
Template constructor that allows explicit conversions from other vectors with assignment compatible element value type.
template< typename T2> Vector( const Vector_struct < T2 , DIM >& other)
Template constructor that allows explicit conversions from underlying storage type with assignment compatible element value type.
 Vector( T v1, T v2)
Dedicated constructor, for dimension 2 only, that initializes the vector elements from the two elements (v1,v2). More...
 Vector( T v1, T v2, T v3)
Dedicated constructor, for dimension 3 only, that initializes the vector elements from the three elements (v1,v2,v3). More...
 Vector( T v1, const Vector < T , 2 >& v2)
Dedicated constructor, for dimension 3 only, that initializes the vector elements from the three elements (v1,v2.x,v2.y). More...
 Vector( const Vector < T , 2 >& v1, T v2)
Dedicated constructor, for dimension 3 only, that initializes the vector elements from the three elements (v1.x,v1.y,v2). More...
 Vector( T v1, T v2, T v3, T v4)
Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1,v2,v3,v4). More...
 Vector( T v1, T v2, const Vector < T , 2 >& v3)
Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1,v2,v3.x,v3.y). More...
 Vector( T v1, const Vector < T , 2 >& v2, T v3)
Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1,v2.x,v2.y,v3). More...
 Vector( const Vector < T , 2 >& v1, T v2, T v3)
Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1.x,v1.y,v2,v3). More...
 Vector( const Vector < T , 2 >& v1, const Vector < T , 2 >& v2)
Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1.x,v1.y,v2.x,v2.y). More...
 Vector( T v1, const Vector < T , 3 >& v2)
Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1,v2.x,v2.y,v2.z). More...
 Vector( const Vector < T , 3 >& v1, T v2)
Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1.x,v1.y,v1.z,v2). More...
 Vector( const Color_struct& color)
Dedicated constructor, for dimension 4 only, that initializes the vector elements from a color interpreted as a vector (r,g,b,a). More...

Public Member Functions

T* begin()
Returns the pointer to the first vector element.
const T* begin() const
Returns the pointer to the first vector element.
T* end()
Returns the past-the-end pointer. More...
const T* end() const
Returns the past-the-end pointer. More...
const T& get( Size i) const
Returns the i-th vector element. More...
bool  normalize()
Normalizes this vector to unit length. More...
bool  operator!=( Vector < T , DIM > rhs) const
Returns true if lhs is elementwise not equal to rhs.
bool  operator<( Vector < T , DIM > rhs) const
Returns true if lhs is lexicographically less than rhs. More...
bool  operator<=( Vector < T , DIM > rhs) const
Returns true if lhs is lexicographically less than or equal to rhs. More...
Vector& operator=( const Vector& other)
Assignment.
Vector& operator=( T s)
Assignment from a scalar, setting all elements to s.
Vector& operator=( const Color_struct& color)
Assignment, for dimension 4 only, that assigns color interpreted as a vector (r,g,b,a) to this vector. More...
bool  operator==( Vector < T , DIM > rhs) const
Returns true if lhs is elementwise equal to rhs.
bool  operator>( Vector < T , DIM > rhs) const
Returns true if lhs is lexicographically greater than rhs. More...
bool  operator>=( Vector < T , DIM > rhs) const
Returns true if lhs is lexicographically greater than or equal to rhs. More...
T& operator[]( Size i)
Accesses the i-th vector element. More...
const T& operator[]( Size i) const
Accesses the i-th vector element. More...
void set( Size i, T value)
Sets the i-th vector element to value. More...

Static Public Member Functions

static Size max_size()
Constant maximum size of the vector.
static Size size()
Constant size of the vector.

Static Public Variables

static const Size DIMENSION = DIM
Constant dimension of the vector.
static const Size SIZE = DIM
Constant size of the vector.

Typedefs

typedef Vector_struct< T, DIM> mi::math::Vector< T, DIM>::Pod_type

POD class corresponding to this vector.

typedef T * mi::math::Vector< T, DIM>::const_pointer

Const pointer to element.

typedef T & mi::math::Vector< T, DIM>::const_reference

Const reference to element.

typedef Difference mi::math::Vector< T, DIM>::difference_type

Difference type, signed.

typedef T * mi::math::Vector< T, DIM>::pointer

Mutable pointer to element.

typedef T & mi::math::Vector< T, DIM>::reference

Mutable reference to element.

typedef Size mi::math::Vector< T, DIM>::size_type

Size type, unsigned.

typedef Vector_struct< T, DIM> mi::math::Vector< T, DIM>::storage_type

Storage class used by this vector.

typedef T mi::math::Vector< T, DIM>::value_type

Element type.

Constructors

mi::math::Vector< T, DIM>::Vector() [inline]

The default constructor leaves the vector elements uninitialized.

mi::math::Vector< T, DIM>::Vector( const Vector < T , DIM >& vec)

Default copy constructor.

mi::math::Vector< T, DIM>::Vector( const Vector_struct < T , DIM >& vec) [inline]

Constructor from underlying storage type.

mi::math::Vector< T, DIM>::Vector( T v) [inline, explicit]

Constructor initializes all vector elements to the value v.

template< typename Iterator>

mi::math::Vector< T, DIM>::Vector( From_iterator_tag, Iterator p) [inline]

Constructor requires the mi::math::FROM_ITERATOR tag as first argument and initializes the vector elements with the first DIM elements from the sequence starting at the iterator p. Iterator must be a model of an input iterator. The value type of Iterator must be assignment compatible with the vector elements type T.

An example: 

‎        std::vector<int> data( 10, 42); // ten elements of value 42
        mi::math::Vector< mi::Float64,  3> vec( mi::math::FROM_ITERATOR, data.begin());

template< typename T2>

mi::math::Vector< T, DIM>::Vector( const T2 (&) array[DIM]) [inline, explicit]

Constructor initializes the vector elements from an array of dimension DIM. The value type T2 of the array must be assignment compatible with the vector elements type T.

An example: 

‎        int data[3] = { 1, 2, 4};
        mi::math::Vector< mi::Float64,  3> vec( data);

template< typename T2>

mi::math::Vector< T, DIM>::Vector( const Vector < T2 , DIM >& other) [inline, explicit]

Template constructor that allows explicit conversions from other vectors with assignment compatible element value type.

template< typename T2>

mi::math::Vector< T, DIM>::Vector( const Vector_struct < T2 , DIM >& other) [inline, explicit]

Template constructor that allows explicit conversions from underlying storage type with assignment compatible element value type.

mi::math::Vector< T, DIM>::Vector( T v1, T v2) [inline]

Dedicated constructor, for dimension 2 only, that initializes the vector elements from the two elements (v1,v2).

Precondition:

DIM == 2

mi::math::Vector< T, DIM>::Vector( T v1, T v2, T v3) [inline]

Dedicated constructor, for dimension 3 only, that initializes the vector elements from the three elements (v1,v2,v3).

Precondition:

DIM == 3

mi::math::Vector< T, DIM>::Vector( T v1, const Vector < T , 2 >& v2) [inline]

Dedicated constructor, for dimension 3 only, that initializes the vector elements from the three elements (v1,v2.x,v2.y).

Precondition:

DIM == 3

mi::math::Vector< T, DIM>::Vector( const Vector < T , 2 >& v1, T v2) [inline]

Dedicated constructor, for dimension 3 only, that initializes the vector elements from the three elements (v1.x,v1.y,v2).

Precondition:

DIM == 3

mi::math::Vector< T, DIM>::Vector( T v1, T v2, T v3, T v4) [inline]

Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1,v2,v3,v4).

Precondition:

DIM == 4

mi::math::Vector< T, DIM>::Vector( T v1, T v2, const Vector < T , 2 >& v3) [inline]

Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1,v2,v3.x,v3.y).

Precondition:

DIM == 4

mi::math::Vector< T, DIM>::Vector( T v1, const Vector < T , 2 >& v2, T v3) [inline]

Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1,v2.x,v2.y,v3).

Precondition:

DIM == 4

mi::math::Vector< T, DIM>::Vector( const Vector < T , 2 >& v1, T v2, T v3) [inline]

Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1.x,v1.y,v2,v3).

Precondition:

DIM == 4

mi::math::Vector< T, DIM>::Vector( const Vector < T , 2 >& v1, const Vector < T , 2 >& v2) [inline]

Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1.x,v1.y,v2.x,v2.y).

Precondition:

DIM == 4

mi::math::Vector< T, DIM>::Vector( T v1, const Vector < T , 3 >& v2) [inline]

Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1,v2.x,v2.y,v2.z).

Precondition:

DIM == 4

mi::math::Vector< T, DIM>::Vector( const Vector < T , 3 >& v1, T v2) [inline]

Dedicated constructor, for dimension 4 only, that initializes the vector elements from the four elements (v1.x,v1.y,v1.z,v2).

Precondition:

DIM == 4

mi::math::Vector< T, DIM>::Vector( const Color_struct& color) [inline, explicit]

Dedicated constructor, for dimension 4 only, that initializes the vector elements from a color interpreted as a vector (r,g,b,a).

Precondition:

DIM == 4

Member Functions

T* mi::math::Vector< T, DIM>::begin() [inline]

Returns the pointer to the first vector element.

const T* mi::math::Vector< T, DIM>::begin() const [inline]

Returns the pointer to the first vector element.

T* mi::math::Vector< T, DIM>::end() [inline]

Returns the past-the-end pointer. The range [begin(),end()) forms the range over all vector elements.

const T* mi::math::Vector< T, DIM>::end() const [inline]

Returns the past-the-end pointer. The range [begin(),end()) forms the range over all vector elements.

const T& mi::math::Vector< T, DIM>::get( Size i) const [inline]

Returns the i-th vector element.

Precondition:

0 <= i < size()

static Size mi::math::Vector< T, DIM>::max_size() [inline, static]

Constant maximum size of the vector.

bool mi::math::Vector< T, DIM>::normalize() [inline]

Normalizes this vector to unit length. Returns false if normalization fails because the vector norm is zero, and true otherwise. This vector remains unchanged if normalization failed.

Uses an unqualified call to sqrt(...) on the vector element type.

bool mi::math::Vector< T, DIM>::operator!=( Vector < T , DIM > rhs) const [inline]

Returns true if lhs is elementwise not equal to rhs.

bool mi::math::Vector< T, DIM>::operator<( Vector < T , DIM > rhs) const [inline]

Returns true if lhs is lexicographically less than rhs.

See also:

mi_def_lexicographic_order

bool mi::math::Vector< T, DIM>::operator<=( Vector < T , DIM > rhs) const [inline]

Returns true if lhs is lexicographically less than or equal to rhs.

See also:

mi_def_lexicographic_order

Vector& mi::math::Vector< T, DIM>::operator=( const Vector& other)

Assignment.

Vector& mi::math::Vector< T, DIM>::operator=( T s) [inline]

Assignment from a scalar, setting all elements to s.

Vector& mi::math::Vector< T, DIM>::operator=( const Color_struct& color) [inline]

Assignment, for dimension 4 only, that assigns color interpreted as a vector (r,g,b,a) to this vector.

Precondition:

DIM == 4

bool mi::math::Vector< T, DIM>::operator==( Vector < T , DIM > rhs) const [inline]

Returns true if lhs is elementwise equal to rhs.

bool mi::math::Vector< T, DIM>::operator>( Vector < T , DIM > rhs) const [inline]

Returns true if lhs is lexicographically greater than rhs.

See also:

mi_def_lexicographic_order

bool mi::math::Vector< T, DIM>::operator>=( Vector < T , DIM > rhs) const [inline]

Returns true if lhs is lexicographically greater than or equal to rhs.

See also:

mi_def_lexicographic_order

T& mi::math::Vector< T, DIM>::operator[]( Size i) [inline]

Accesses the i-th vector element.

Precondition:

0 <= i < size()

const T& mi::math::Vector< T, DIM>::operator[]( Size i) const [inline]

Accesses the i-th vector element.

Precondition:

0 <= i < size()

void mi::math::Vector< T, DIM>::set( Size i, T value) [inline]

Sets the i-th vector element to value.

Precondition:

0 <= i < size()

static Size mi::math::Vector< T, DIM>::size() [inline, static]

Constant size of the vector.

Variables

const Size mi::math::Vector< T, DIM>::DIMENSION = DIM [static]

Constant dimension of the vector.

const Size mi::math::Vector< T, DIM>::SIZE = DIM [static]

Constant size of the vector.