UT/UT_Vector4.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Cristin Barghiel
 *      Side Effects Software Inc.
 *      20 Maud St.
 *      Toronto, Ontario,  M5V 2M5
 *      Canada
 *      416-366-4607
 *
 * NAME:        Utility Library (C++)
 *
 * COMMENTS:
 *      This class handles fpreal vectors of dimension 4.
 *
 * WARNING:
 *      This class should NOT contain any virtual methods, nor should it
 *      define more member data. The size of UT_Vector4 must always be 
 *      16 bytes (4 floats).
 *
 */

#ifndef __UT_Vector4_h__
#define __UT_Vector4_h__

#include "UT_API.h"
#include <math.h>
#include <limits.h>
#include <iostream.h>
#include "UT_Assert.h"
#include "UT_Math.h"
#include <vector>

class UT_Matrix4;
class UT_IStream;
class UT_DMatrix4;
class UT_Vector3;
class UT_Vector4;

// Free floating functions:

// Right-multiply operators (M*v) have been removed. They had previously
// been defined to return v*M, which was too counterintuitive. Once HDK
// etc. users have a chance to update their code (post 7.0) we could
// reintroduce a right-multiply operator that does a colVecMult.

inline UT_Vector4       operator*(const UT_Vector4 &v, const UT_Matrix4 &m);
inline UT_Vector4       operator*(const UT_Vector4 &v, const UT_DMatrix4 &m);
inline UT_Vector4       operator+(const UT_Vector4 &v1, const UT_Vector4 &v2);
inline UT_Vector4       operator-(const UT_Vector4 &v1, const UT_Vector4 &v2);
inline UT_Vector4       operator+(const UT_Vector4 &v, fpreal scalar);
inline UT_Vector4       operator-(const UT_Vector4 &v, fpreal scalar);
inline UT_Vector4       operator*(const UT_Vector4 &v, fpreal scalar);
inline UT_Vector4       operator/(const UT_Vector4 &v, fpreal scalar);
inline UT_Vector4       operator+(fpreal scalar, const UT_Vector4 &v);
inline UT_Vector4       operator-(fpreal scalar, const UT_Vector4 &v);
inline UT_Vector4       operator*(fpreal scalar, const UT_Vector4 &v);
inline UT_Vector4       operator/(fpreal scalar, const UT_Vector4 &v);

/// Although the cross product is undefined for 4D vectors, we believe it's
/// useful in practice to define a function that takes two 4D vectors and
/// computes the cross-product of their first 3 components
UT_API UT_Vector3       cross(const UT_Vector4 &v1, const UT_Vector4 &v2);

/// The dot product between two vectors
// @{
inline fpreal           dot(const UT_Vector4 &v1, const UT_Vector4 &v2);
inline fpreal           dot(const UT_Vector4 &v1, const UT_Vector3 &v2);
inline fpreal           dot(const UT_Vector3 &v1, const UT_Vector4 &v2);
// @}

/// Multiplication of a row or column vector by a matrix (ie. right vs. left
/// multiplication respectively). The operator*() declared above is an alias 
/// for rowVecMult().
// @{
//
// Notes on optimisation of matrix/vector multiplies:
// - multiply(dest, mat) functions have been deprecated in favour of
// rowVecMult/colVecMult routines, which produce temporaries. For these to
// offer comparable performance, the compiler has to optimize away the
// temporary, but most modern compilers can do this. Performance tests with
// gcc3.3 indicate that this is a realistic expectation for modern
// compilers.
// - since matrix/vector multiplies cannot be done without temporary data,
// the "primary" functions are the global matrix/vector
// rowVecMult/colVecMult routines, rather than the member functions.
// - inlining is explicitly requested only for functions involving the
// native types (UT_Vector4 and UT_Matrix4)
UT_API UT_Vector4       rowVecMult(const UT_Vector4 &v, const UT_Matrix4 &m);
UT_API UT_Vector4       rowVecMult(const UT_Vector4 &v, const UT_DMatrix4 &m);
UT_API UT_Vector4       colVecMult(const UT_Matrix4 &m, const UT_Vector4 &v);
UT_API UT_Vector4       colVecMult(const UT_DMatrix4 &m, const UT_Vector4 &v);

UT_API UT_Vector4       rowVecMult3(const UT_Vector4 &v, const UT_Matrix4 &m);
UT_API UT_Vector4       rowVecMult3(const UT_Vector4 &v, const UT_DMatrix4 &m);
UT_API UT_Vector4       colVecMult3(const UT_Matrix4 &m, const UT_Vector4 &v);
UT_API UT_Vector4       colVecMult3(const UT_DMatrix4 &m, const UT_Vector4 &v);
// @}

/// Compute the distance between two points
// @{
inline fpreal           distance4(const UT_Vector4 &p1, const UT_Vector4 &p2);
inline fpreal           distance3(const UT_Vector4 &p1, const UT_Vector4 &p2);
// @}

/// 4D Vector class.
class UT_API UT_Vector4 {
public:
    /// Default constructor.
    /// No data is initialized! Use it for extra speed.
    inline       UT_Vector4(void)
                 {
                    UT_ASSERT_COMPILETIME(sizeof(UT_Vector4) ==
                                          4 * sizeof(float));
                 }
    inline       UT_Vector4(fpreal vx, fpreal vy, fpreal vz, fpreal vw = 1.0f)
                 {
                    vec[0] = vx; vec[1] = vy; vec[2] = vz; vec[3] = vw;
                 }
    inline       UT_Vector4(const fpreal32 v[4])
                 {
                    vec[0] = v[0]; vec[1] = v[1]; vec[2] = v[2]; vec[3] = v[3];
                 }
    inline       UT_Vector4(const fpreal64 v[4])
                 {
                    vec[0] = (fpreal) v[0]; 
                    vec[1] = (fpreal) v[1]; 
                    vec[2] = (fpreal) v[2]; 
                    vec[3] = (fpreal) v[3];
                 }
    inline
    explicit     UT_Vector4(const UT_Vector3 &v, float w = 1.f);
    // Default copy constructor is fine.
    //           UT_Vector4(const UT_Vector4 &v);
                ~UT_Vector4(void) {}

    // Default assignment operator is fine.
    //UT_Vector4        &operator=(const UT_Vector4 &v);


    // TODO: We could remove this. It's not as error-prone as some other
    // conversions, but it might still be better to force the user to do
    // an explicit cast i.e., v4 = UT_Vector4(v3)

    /// Assignment operator that creates a V4 from a V3 by adding a '1' 
    /// element.
    UT_Vector4  &operator=(const UT_Vector3 &v);

    // The negate operator is not provided, because of potentially
    // unintuitive behaviour: you very rarely actually want to negate the
    // w component.
    //UT_Vector4        operator-() const
    
    inline
    UT_Vector4  &operator+=(const UT_Vector4 &v)
                 {
                    vec[0] += v.vec[0];
                    vec[1] += v.vec[1];
                    vec[2] += v.vec[2];
                    vec[3] += v.vec[3];
                    return *this;
                 }
    inline
    UT_Vector4  &operator-=(const UT_Vector4 &v)
                 {
                    vec[0] -= v.vec[0];
                    vec[1] -= v.vec[1];
                    vec[2] -= v.vec[2];
                    vec[3] -= v.vec[3];
                    return *this;
                 }
    unsigned     operator==(const UT_Vector4 &v) const
                 {
                    return (vec[0] == v.vec[0] && vec[1] == v.vec[1] &&
                            vec[2] == v.vec[2] && vec[3] == v.vec[3] );
                    
                 }
    unsigned     operator!=(const UT_Vector4 &v) const
                 { return !(*this == v); }      
    int          equalZero(fpreal tol = 0.00001f) const
                 {
                    return (vec[0] >= -tol && vec[0] <= tol) &&
                           (vec[1] >= -tol && vec[1] <= tol) &&
                           (vec[2] >= -tol && vec[2] <= tol) &&
                           (vec[3] >= -tol && vec[3] <= tol);
                 }
    int          equalZero3(fpreal tol = 0.00001f) const
                 {
                    return (vec[0] >= -tol && vec[0] <= tol) &&
                           (vec[1] >= -tol && vec[1] <= tol) &&
                           (vec[2] >= -tol && vec[2] <= tol);
                 }

    void         clampZero(fpreal tol = 0.00001f) 
                 {
                    if (vec[0] >= -tol && vec[0] <= tol) vec[0] = 0;
                    if (vec[1] >= -tol && vec[1] <= tol) vec[1] = 0;
                    if (vec[2] >= -tol && vec[2] <= tol) vec[2] = 0;
                    if (vec[3] >= -tol && vec[3] <= tol) vec[3] = 0;
                 }

    void         clampZero3(fpreal tol = 0.00001f) 
                 {
                    if (vec[0] >= -tol && vec[0] <= tol) vec[0] = 0;
                    if (vec[1] >= -tol && vec[1] <= tol) vec[1] = 0;
                    if (vec[2] >= -tol && vec[2] <= tol) vec[2] = 0;
                 }

    void         negate3()
                 { vec[0]= -vec[0]; vec[1]= -vec[1]; vec[2]= -vec[2]; }
    void         negate() { vec[0]= -vec[0]; vec[1]= -vec[1]; vec[2]= -vec[2];
                           vec[3] = -vec[3]; }

    void         multiplyComponents(const UT_Vector4 &v)
                 {
                     vec[0] *= v.vec[0];
                     vec[1] *= v.vec[1];
                     vec[2] *= v.vec[2];
                     vec[3] *= v.vec[3];
                 }

    int          isEqual(const UT_Vector4 &v, fpreal tol = 0.00001f) const
                 {
                    return ((vec[0]>=v.vec[0]-tol) && (vec[0]<=v.vec[0]+tol) &&
                            (vec[1]>=v.vec[1]-tol) && (vec[1]<=v.vec[1]+tol) &&
                            (vec[2]>=v.vec[2]-tol) && (vec[2]<=v.vec[2]+tol) &&
                            (vec[3]>=v.vec[3]-tol) && (vec[3]<=v.vec[3]+tol));
                 }
    int          isEqual(const UT_Vector3 &vect, fpreal tol = 0.00001f) const;

    /// If you need a multiplication operator that left multiplies the vector
    /// by a matrix (M * v), use the following colVecMult() functions. If
    /// you'd rather not use operator*=() for right-multiplications (v * M),
    /// use the following rowVecMult() functions.
    // @{
    inline void  rowVecMult(const UT_Matrix4 &m)
                 { operator=(::rowVecMult(*this, m)); }
    void         rowVecMult(const UT_DMatrix4 &m)
                 { operator=(::rowVecMult(*this, m)); }
    void         colVecMult(const UT_Matrix4 &m)
                 { operator=(::colVecMult(m, *this)); }
    void         colVecMult(const UT_DMatrix4 &m)
                 { operator=(::colVecMult(m, *this)); }
    // @}

    /// This multiply will ignore the 4th component both in the vector an in
    /// the matrix. This helps when you want to avoid affecting the 'w'
    /// component. This in turns annihilates the translation components (row 4)
    /// in mat, so be careful.
    // @{
    void          rowVecMult3(const UT_Matrix4 &m)
                  { operator=(::rowVecMult3(*this, m)); }
    void          rowVecMult3(const UT_DMatrix4 &m)
                  { operator=(::rowVecMult3(*this, m)); }
    // @}

    // The *= and multiply3 routines are provided for
    // legacy reasons. They all assume that *this is a row vector. Generally,
    // the rowVecMult and colVecMult methods are preferred, since they're
    // more explicit about the row vector assumption.
    // @{
    inline
    UT_Vector4  &operator*=(const UT_Matrix4 &mat)
                 { rowVecMult(mat); return *this; }
    UT_Vector4  &operator*=(const UT_DMatrix4 &mat)
                 { rowVecMult(mat); return *this; }

    void         multiply3(const UT_Matrix4 &mat)
                 { rowVecMult3(mat); }
    void         multiply3(const UT_DMatrix4 &mat)
                 { rowVecMult3(mat); }
    void         multiply3(UT_Vector4 &dest, const UT_Matrix4 &mat) const
                 { dest = ::rowVecMult3(*this, mat); }
    // @}

    UT_Vector4  &operator=(fpreal scalar)
                 {
                    vec[0] = vec[1] = vec[2] = vec[3] = scalar;
                    return *this;
                 }
    UT_Vector4  &operator+=(fpreal scalar)
                 {
                    vec[0] += scalar; vec[1] += scalar;
                    vec[2] += scalar; vec[3] += scalar;
                    return *this;
                 }
    UT_Vector4  &operator-=(fpreal scalar)
                 {
                    return operator+=(-scalar);
                 }
    inline
    UT_Vector4  &operator*=(fpreal scalar)
                 {
                    vec[0] *= scalar; vec[1] *= scalar;
                    vec[2] *= scalar; vec[3] *= scalar;
                    return *this;
                 }
    inline
    UT_Vector4  &operator*=(const UT_Vector4 &v)
                 {
                    vec[0] *= v.vec[0];
                    vec[1] *= v.vec[1];
                    vec[2] *= v.vec[2];
                    vec[3] *= v.vec[3];
                    return *this;
                 }
    inline
    UT_Vector4  &operator/=(fpreal scalar)
                 {
                    return operator*=( 1.0f/scalar );
                 }
    inline
    UT_Vector4  &operator/=(const UT_Vector4 &v)
                 {
                    vec[0] /= v.vec[0];
                    vec[1] /= v.vec[1];
                    vec[2] /= v.vec[2];
                    vec[3] /= v.vec[3];
                    return *this;
                 }

    fpreal       maxComponent() const
                 {
                    fpreal      m = vec[0];
                    if (vec[1] > m) m = vec[1];
                    if (vec[2] > m) m = vec[2];
                    if (vec[3] > m) m = vec[3];
                    return m;
                 }
    fpreal       minComponent() const
                 {
                    fpreal      m = vec[0];
                    if (vec[1] < m) m = vec[1];
                    if (vec[2] < m) m = vec[2];
                    if (vec[3] < m) m = vec[3];
                    return m;
                 }
    fpreal       avgComponent() const
                 {
                    return (vec[0]+vec[1]+vec[2]+vec[3])*0.25F;
                 }

    /// These allow you to find out what indices to use for different axes
    // @{
    int          findMinAbsAxis() const
                 {
                    if (SYSabs(x()) < SYSabs(y()))
                        if (SYSabs(z()) < SYSabs(x()))
                            if (SYSabs(w()) < SYSabs(z()))
                                return 3;
                            else
                                return 2;
                        else
                            if (SYSabs(w()) < SYSabs(x()))
                                return 3;
                            else
                                return 0;
                    else
                        if (SYSabs(z()) < SYSabs(y()))
                            if (SYSabs(w()) < SYSabs(z()))
                                return 3;
                            else
                                return 2;
                        else
                            if (SYSabs(w()) < SYSabs(y()))
                                return 3;
                            else
                                return 1;
                 }
    int          findMaxAbsAxis() const
                 {
                    if (SYSabs(x()) >= SYSabs(y()))
                        if (SYSabs(z()) >= SYSabs(x()))
                            if (SYSabs(w()) >= SYSabs(z()))
                                return 3;
                            else
                                return 2;
                        else
                            if (SYSabs(w()) >= SYSabs(x()))
                                return 3;
                            else
                                return 0;
                    else
                        if (SYSabs(z()) >= SYSabs(y()))
                            if (SYSabs(w()) >= SYSabs(z()))
                                return 3;
                            else
                                return 2;
                        else
                            if (SYSabs(w()) >= SYSabs(y()))
                                return 3;
                            else
                                return 1;
                 }
    // @}

    inline
    fpreal       dot(const UT_Vector4 &v) const
                 {
                    return ::dot(*this, v);
                 }
    void         normalize (void)
                 {
                    fpreal dn   = vec[0]*vec[0] + vec[1]*vec[1] +
                                 vec[2]*vec[2] + vec[3]*vec[3];
                    if (dn > FLT_MIN)
                        (*this) *= (((fpreal)1.)/SYSsqrt(dn) );
                 }

    /// The vector length (not to be confused with the vector dimension).
    inline
    fpreal       length(void) const
                 { return SYSsqrt(dot(*this)); }
    /// The vector length squared.
    inline
    fpreal       length2(void) const
                 { return dot(*this); }

    /// Return the components of the vector. The () operator does NOT check
    /// for the boundary condition.
    // @{
    const float *data(void) const       { return &vec[0]; }
    float       *data(void)             { return &vec[0]; }
    inline float&x(void)                { return vec[0]; } 
    inline float x(void) const          { return vec[0]; } 
    inline float&y(void)                { return vec[1]; } 
    inline float y(void) const          { return vec[1]; } 
    inline float&z(void)                { return vec[2]; } 
    inline float z(void) const          { return vec[2]; } 
    inline float&w(void)                { return vec[3]; } 
    inline float w(void) const          { return vec[3]; } 
    inline float&operator()(unsigned i)
                 {
                     UT_ASSERT_P(i < 4);
                     return vec[i];
                 }
    inline float operator()(unsigned i) const
                 {
                     UT_ASSERT_P(i < 4);
                     return vec[i];
                 }
    inline float&operator[](unsigned i)
                 {
                     UT_ASSERT_P(i < 4);
                     return vec[i];
                 }
    inline float operator[](unsigned i) const
                 {
                     UT_ASSERT_P(i < 4);
                     return vec[i];
                 }
    std::vector<float> asStdVector() const;
    // @}

    // TODO: eliminate these methods. They're redundant, given good inline
    // constructors.
    /// Set the values of the vector components
    void         assign(fpreal xx = 0.0f, fpreal yy = 0.0f, fpreal zz = 0.0f, 
                        fpreal ww = 1.0f)
                 {
                     vec[0] = xx; vec[1] = yy; vec[2] = zz; vec[3] = ww;
                 }
    /// Set the values of the vector components
    void         assign(const float *v, int size = 4)
                 {
                     vec[0] = v[0];
                     vec[1] = v[1];
                     vec[2] = v[2];
                     if (size == 4) vec[3] = v[3];
                 }

    /// Express the point in homogeneous coordinates or vice-versa
    // @{
    void         homogenize(void)
                 {
                     vec[0] *= vec[3];
                     vec[1] *= vec[3];
                     vec[2] *= vec[3];
                 }
    void         dehomogenize(void)
                 {
                     fpreal denom = 1.0f / vec[3];
                     vec[0] *= denom;
                     vec[1] *= denom;
                     vec[2] *= denom;
                 }
    // @}

    void        save(ostream &os, int binary=0) const;
    bool        load(UT_IStream &is);

private:
    /// I/O friends
    // @{
    friend ostream      &operator<<(ostream &os, const UT_Vector4 &v)
                        {
                            v.save(os);
                            return os;
                        }
    // @}

    /// The data.
    float vec[4];
};

#include "UT_Vector3.h"

inline UT_Vector4::UT_Vector4(const UT_Vector3 &v, float vw)
{
    vec[0] = v.x();
    vec[1] = v.y();
    vec[2] = v.z();
    vec[3] = vw;
}

inline int
UT_Vector4::isEqual(const UT_Vector3 &vect, fpreal tol) const
{
    return ((vec[0]>=vect.x()-tol) && (vec[0]<=vect.x()+tol) &&
            (vec[1]>=vect.y()-tol) && (vec[1]<=vect.y()+tol) &&
            (vec[2]>=vect.z()-tol) && (vec[2]<=vect.z()+tol));
}

// Free floating functions:
inline UT_Vector4       operator+(const UT_Vector4 &v1, const UT_Vector4 &v2)
{
    return UT_Vector4(v1.x()+v2.x(), v1.y()+v2.y(),
                      v1.z()+v2.z(), v1.w()+v2.w());
}
inline UT_Vector4       operator-(const UT_Vector4 &v1, const UT_Vector4 &v2)
{
    return UT_Vector4(v1.x()-v2.x(), v1.y()-v2.y(),
                      v1.z()-v2.z(), v1.w()-v2.w());
}
inline UT_Vector4       operator*(const UT_Vector4 &v1, const UT_Vector4 &v2)
{
    return UT_Vector4(v1.x()*v2.x(), v1.y()*v2.y(), v1.z()*v2.z(), v1.w()*v2.w());
}

inline UT_Vector4       operator/(const UT_Vector4 &v1, const UT_Vector4 &v2)
{
    return UT_Vector4(v1.x()/v2.x(), v1.y()/v2.y(), v1.z()/v2.z(), v1.w()/v2.w());
}

inline UT_Vector4       operator+(const UT_Vector4 &v, fpreal scalar)
{
    return UT_Vector4(v.x()+scalar, v.y()+scalar, v.z()+scalar, v.w()+scalar);
}
inline UT_Vector4       operator+(fpreal scalar, const UT_Vector4 &v)
{
    return UT_Vector4(v.x()+scalar, v.y()+scalar, v.z()+scalar, v.w()+scalar);
}
inline UT_Vector4       operator-(const UT_Vector4 &v, fpreal scalar)
{
    return UT_Vector4(v.x()-scalar, v.y()-scalar, v.z()-scalar, v.w()-scalar);
}
inline UT_Vector4       operator-(fpreal scalar, const UT_Vector4 &v)
{
    return UT_Vector4(scalar-v.x(), scalar-v.y(), scalar-v.z(), v.w()-scalar);
}
inline UT_Vector4       operator*(const UT_Vector4 &v, fpreal scalar)
{
    return UT_Vector4(v.x()*scalar, v.y()*scalar, v.z()*scalar, v.w()*scalar);
}
inline UT_Vector4       operator*(fpreal scalar, const UT_Vector4 &v)
{
    return UT_Vector4(v.x()*scalar, v.y()*scalar, v.z()*scalar, v.w()*scalar);
}
inline UT_Vector4       operator/(const UT_Vector4 &v, fpreal scalar)
{
    return UT_Vector4(v.x()/scalar, v.y()/scalar, v.z()/scalar, v.w()/scalar);
}
inline UT_Vector4       operator/(fpreal scalar, const UT_Vector4 &v)
{
    return UT_Vector4(scalar/v.x(), scalar/v.y(), scalar/v.z(), scalar/v.w());
}
inline fpreal           dot(const UT_Vector4 &v1, const UT_Vector4 &v2)
{
    return v1.x()*v2.x() + v1.y()*v2.y() + v1.z()*v2.z() + v1.w()*v2.w();
}
inline fpreal           dot(const UT_Vector4 &v1, const UT_Vector3 &v2)
{
    return v1.x()*v2.x() + v1.y()*v2.y() + v1.z()*v2.z();
}
inline fpreal           dot(const UT_Vector3 &v1, const UT_Vector4 &v2)
{
    return v1.x()*v2.x() + v1.y()*v2.y() + v1.z()*v2.z();
}

inline UT_Vector4       operator*(const UT_Vector4 &v, const UT_Matrix4 &m)
{
    return rowVecMult(v, m);
}
inline UT_Vector4       operator*(const UT_Vector4 &v, const UT_DMatrix4 &m)
{
    return rowVecMult(v, m);
}
inline fpreal           distance(const UT_Vector4 &v1, const UT_Vector4 &v2)
{
    fpreal      x = v1.x()-v2.x();
    fpreal      y = v1.y()-v2.y();
    fpreal      z = v1.z()-v2.z();
    fpreal      w = v1.w()-v2.w();
    return SYSsqrt(x*x + y*y + z*z + w*w);
}
inline fpreal           distance3(const UT_Vector4 &v1, const UT_Vector4 &v2)
{
    fpreal      x = v1.x()-v2.x();
    fpreal      y = v1.y()-v2.y();
    fpreal      z = v1.z()-v2.z();
    return SYSsqrt(x*x + y*y + z*z);
}

#endif

---