diff --git a/library/PolyVoxCore/include/PolyVoxCore/Vector.h b/library/PolyVoxCore/include/PolyVoxCore/Vector.h index fc689dc5..6181acb9 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/Vector.h +++ b/library/PolyVoxCore/include/PolyVoxCore/Vector.h @@ -59,169 +59,175 @@ namespace PolyVox \code Vector2DInt4 test(1,2); //Declares a 2 dimensional Vector of type int4. \endcode + + Extra things to mention when I when I fill this out shortly: + Vector must have at least two elements. + Use of 'OperationType' + Floating point return values are always single precision + Component order is WYZW */ template class Vector { public: - ///Constructor + /// Constructor Vector(void); - ///Constructor. + /// Constructor. Vector(StorageType tFillValue); - ///Constructor. + /// Constructor. Vector(StorageType x, StorageType y); - ///Constructor. + /// Constructor. Vector(StorageType x, StorageType y, StorageType z); - ///Constructor. + /// Constructor. Vector(StorageType x, StorageType y, StorageType z, StorageType w); - ///Copy Constructor. + /// Copy Constructor. Vector(const Vector& vector); - ///Copy Constructor which performs casting. + /// Copy Constructor which performs casting. template explicit Vector(const Vector& vector); - ///Destructor. + /// Destructor. ~Vector(void); - ///Assignment Operator. + /// Assignment Operator. Vector& operator=(const Vector& rhs); - ///Equality Operator. + /// Equality Operator. bool operator==(const Vector& rhs) const; - ///Inequality Operator. + /// Inequality Operator. bool operator!=(const Vector& rhs) const; - ///Comparison Operator. - bool operator<(const Vector& rhs) const; - ///Addition and Assignment Operator. + /// Comparison Operator. + POLYVOX_DEPRECATED bool operator<(const Vector& rhs) const; + /// Addition and Assignment Operator. Vector& operator+=(const Vector &rhs); - ///Subtraction and Assignment Operator. + /// Subtraction and Assignment Operator. Vector& operator-=(const Vector &rhs); - ///Multiplication and Assignment Operator. + /// Multiplication and Assignment Operator. Vector& operator*=(const Vector &rhs); - ///Division and Assignment Operator. + /// Division and Assignment Operator. Vector& operator/=(const Vector &rhs); - ///Multiplication and Assignment Operator. + /// Multiplication and Assignment Operator. Vector& operator*=(const StorageType& rhs); - ///Division and Assignment Operator. + /// Division and Assignment Operator. Vector& operator/=(const StorageType& rhs); - ///Element Access. + /// Element Access. StorageType getElement(uint32_t index) const; - ///Get the x component of the vector. + /// Get the x component of the vector. StorageType getX(void) const; - ///Get the y component of the vector. + /// Get the y component of the vector. StorageType getY(void) const; - ///Get the z component of the vector. + /// Get the z component of the vector. StorageType getZ(void) const; - ///Get the w component of the vector. + /// Get the w component of the vector. StorageType getW(void) const; - ///Element Access. + /// Element Access. void setElement(uint32_t index, StorageType tValue); - ///Element Access. + /// Element Access. void setElements(StorageType x, StorageType y); - ///Element Access. + /// Element Access. void setElements(StorageType x, StorageType y, StorageType z); - ///Element Access. + /// Element Access. void setElements(StorageType x, StorageType y, StorageType z, StorageType w); - ///Set the x component of the vector. + /// Set the x component of the vector. void setX(StorageType tX); - ///Set the y component of the vector. + /// Set the y component of the vector. void setY(StorageType tY); - ///Set the z component of the vector. + /// Set the z component of the vector. void setZ(StorageType tZ); - ///Set the w component of the vector. + /// Set the w component of the vector. void setW(StorageType tW); - ///Get the length of the vector. + /// Get the length of the vector. float length(void) const; - ///Get the squared length of the vector. + /// Get the squared length of the vector. OperationType lengthSquared(void) const; - ///Find the angle between this vector and that which is passed as a parameter. + /// Find the angle between this vector and that which is passed as a parameter. float angleTo(const Vector& vector) const; - ///Find the cross product between this vector and the vector passed as a parameter. + /// Find the cross product between this vector and the vector passed as a parameter. Vector cross(const Vector& vector) const; - ///Find the dot product between this vector and the vector passed as a parameter. + /// Find the dot product between this vector and the vector passed as a parameter. OperationType dot(const Vector& rhs) const; - ///Normalise the vector. + /// Normalise the vector. void normalise(void); private: - //Values for the vector + // Values for the vector StorageType m_tElements[Size]; }; - //Non-member overloaded operators. - ///Addition operator. + // Non-member overloaded operators. + /// Addition operator. template Vector operator+(const Vector& lhs, const Vector& rhs); - ///Subtraction operator. + /// Subtraction operator. template Vector operator-(const Vector& lhs, const Vector& rhs); - ///Multiplication operator. + /// Multiplication operator. template Vector operator*(const Vector& lhs, const Vector& rhs); - ///Division operator. + /// Division operator. template Vector operator/(const Vector& lhs, const Vector& rhs); - ///Multiplication operator. + /// Multiplication operator. template Vector operator*(const Vector& lhs, const StorageType& rhs); - ///Division operator. + /// Division operator. template Vector operator/(const Vector& lhs, const StorageType& rhs); - ///Stream insertion operator. + /// Stream insertion operator. template std::ostream& operator<<(std::ostream& os, const Vector& vector); - + //Some handy typedefs - ///A 2D Vector of floats. + /// A 2D Vector of floats. typedef Vector<2,float,float> Vector2DFloat; - ///A 2D Vector of doubles. + /// A 2D Vector of doubles. typedef Vector<2,double,double> Vector2DDouble; - ///A 2D Vector of signed 8-bit values. + /// A 2D Vector of signed 8-bit values. typedef Vector<2,int8_t,int32_t> Vector2DInt8; - ///A 2D Vector of unsigned 8-bit values. + /// A 2D Vector of unsigned 8-bit values. typedef Vector<2,uint8_t,int32_t> Vector2DUint8; - ///A 2D Vector of signed 16-bit values. + /// A 2D Vector of signed 16-bit values. typedef Vector<2,int16_t,int32_t> Vector2DInt16; - ///A 2D Vector of unsigned 16-bit values. + /// A 2D Vector of unsigned 16-bit values. typedef Vector<2,uint16_t,int32_t> Vector2DUint16; - ///A 2D Vector of signed 32-bit values. + /// A 2D Vector of signed 32-bit values. typedef Vector<2,int32_t,int32_t> Vector2DInt32; - ///A 2D Vector of unsigned 32-bit values. + /// A 2D Vector of unsigned 32-bit values. typedef Vector<2,uint32_t,int32_t> Vector2DUint32; - ///A 3D Vector of floats. + /// A 3D Vector of floats. typedef Vector<3,float,float> Vector3DFloat; - ///A 3D Vector of doubles. + /// A 3D Vector of doubles. typedef Vector<3,double,double> Vector3DDouble; - ///A 3D Vector of signed 8-bit values. + /// A 3D Vector of signed 8-bit values. typedef Vector<3,int8_t,int32_t> Vector3DInt8; - ///A 3D Vector of unsigned 8-bit values. + /// A 3D Vector of unsigned 8-bit values. typedef Vector<3,uint8_t,int32_t> Vector3DUint8; - ///A 3D Vector of signed 16-bit values. + /// A 3D Vector of signed 16-bit values. typedef Vector<3,int16_t,int32_t> Vector3DInt16; - ///A 3D Vector of unsigned 16-bit values. + /// A 3D Vector of unsigned 16-bit values. typedef Vector<3,uint16_t,int32_t> Vector3DUint16; - ///A 3D Vector of signed 32-bit values. + /// A 3D Vector of signed 32-bit values. typedef Vector<3,int32_t,int32_t> Vector3DInt32; - ///A 3D Vector of unsigned 32-bit values. + /// A 3D Vector of unsigned 32-bit values. typedef Vector<3,uint32_t,int32_t> Vector3DUint32; - ///A 4D Vector of floats. + /// A 4D Vector of floats. typedef Vector<4,float,float> Vector4DFloat; - ///A 4D Vector of doubles. + /// A 4D Vector of doubles. typedef Vector<4,double,double> Vector4DDouble; - ///A 4D Vector of signed 8-bit values. + /// A 4D Vector of signed 8-bit values. typedef Vector<4,int8_t,int32_t> Vector4DInt8; - ///A 4D Vector of unsigned 8-bit values. + /// A 4D Vector of unsigned 8-bit values. typedef Vector<4,uint8_t,int32_t> Vector4DUint8; - ///A 4D Vector of signed 16-bit values. + /// A 4D Vector of signed 16-bit values. typedef Vector<4,int16_t,int32_t> Vector4DInt16; - ///A 4D Vector of unsigned 16-bit values. + /// A 4D Vector of unsigned 16-bit values. typedef Vector<4,uint16_t,int32_t> Vector4DUint16; - ///A 4D Vector of signed 32-bit values. + /// A 4D Vector of signed 32-bit values. typedef Vector<4,int32_t,int32_t> Vector4DInt32; - ///A 4D Vector of unsigned 32-bit values. + /// A 4D Vector of unsigned 32-bit values. typedef Vector<4,uint32_t,int32_t> Vector4DUint32; diff --git a/library/PolyVoxCore/include/PolyVoxCore/Vector.inl b/library/PolyVoxCore/include/PolyVoxCore/Vector.inl index c93a0b9b..cf8374ca 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/Vector.inl +++ b/library/PolyVoxCore/include/PolyVoxCore/Vector.inl @@ -33,8 +33,8 @@ namespace PolyVox } /** - Creates a Vector object and initialises it with given values. - \param x x component to set. + Creates a Vector object and initialises all components with the given value. + \param tFillValue The value to write to every component. */ template Vector::Vector(StorageType tFillValue) @@ -47,8 +47,8 @@ namespace PolyVox /** Creates a Vector object and initialises it with given values. - \param x x component to set. - \param y y component to set. + \param x The X component to set. + \param y The Y component to set. */ template Vector::Vector(StorageType x, StorageType y) @@ -63,9 +63,9 @@ namespace PolyVox /** Creates a Vector3D object and initialises it with given values. - \param x x component to set. - \param y y component to set. - \param z z component to set. + \param x The X component to set. + \param y The Y component to set. + \param z the Z component to set. */ template Vector::Vector(StorageType x, StorageType y, StorageType z) @@ -82,10 +82,10 @@ namespace PolyVox /** Creates a Vector3D object and initialises it with given values. - \param x x component to set. - \param y y component to set. - \param z z component to set. - \param w w component to set. + \param x The X component to set. + \param y The Y component to set. + \param z The Z component to set. + \param w The W component to set. */ template Vector::Vector(StorageType x, StorageType y, StorageType z, StorageType w) @@ -112,7 +112,7 @@ namespace PolyVox /** This copy constructor allows casting between vectors with different data types. - It is now possible to use code such as: + It makes it possible to use code such as: Vector3DDouble v3dDouble(1.0,2.0,3.0); Vector3DFloat v3dFloat = static_cast(v3dDouble); //Casting @@ -197,9 +197,11 @@ namespace PolyVox /** Checks whether this vector is less than the parameter. The metric is meaningless but it allows Vectors to me used as key in sdt::map, etc. + This function is deprecated. You should specify a seperate comparator to the std:map if you need one. \param rhs The Vector to compare to. \return true if this is less than the parameter \see operator!= + \deprecated */ template inline bool Vector::operator<(const Vector &rhs) const @@ -216,7 +218,7 @@ namespace PolyVox /** Addition operator adds corresponding elements of the two Vectors. - \param rhs Vector to add + \param rhs The Vector to add \return The resulting Vector. */ template @@ -231,7 +233,7 @@ namespace PolyVox /** Subtraction operator subtracts corresponding elements of one Vector from the other. - \param rhs Vector to subtract + \param rhs The Vector to subtract \return The resulting Vector. */ template @@ -246,7 +248,7 @@ namespace PolyVox /** Multiplication operator multiplies corresponding elements of the two Vectors. - \param rhs Vector to multiply by + \param rhs The Vector to multiply by \return The resulting Vector. */ template @@ -261,7 +263,7 @@ namespace PolyVox /** Division operator divides corresponding elements of one Vector by the other. - \param rhs Vector to divide by + \param rhs The Vector to divide by \return The resulting Vector. */ template @@ -276,7 +278,7 @@ namespace PolyVox /** Multiplication operator multiplies each element of the Vector by a number. - \param rhs the number the Vector is multiplied by. + \param rhs The number the Vector is multiplied by. \return The resulting Vector. */ template @@ -291,7 +293,7 @@ namespace PolyVox /** Division operator divides each element of the Vector by a number. - \param rhs the number the Vector is divided by. + \param rhs The number the Vector is divided by. \return The resulting Vector. */ template @@ -306,8 +308,8 @@ namespace PolyVox /** Addition operator adds corresponding elements of the two Vectors. - \param lhs Vector to add to. - \param rhs Vector to add. + \param lhs The Vector to add to. + \param rhs The Vector to add. \return The resulting Vector. */ template @@ -320,8 +322,8 @@ namespace PolyVox /** Subtraction operator subtracts corresponding elements of one Vector from the other. - \param lhs Vector to subtract from. - \param rhs Vector to subtract. + \param lhs The Vector to subtract from. + \param rhs The Vector to subtract. \return The resulting Vector. */ template @@ -334,8 +336,8 @@ namespace PolyVox /** Multiplication operator mulitplies corresponding elements of the two Vectors. - \param lhs Vector to multiply. - \param rhs Vector to multiply by. + \param lhs The Vector to multiply. + \param rhs The Vector to multiply by. \return The resulting Vector. */ template @@ -348,8 +350,8 @@ namespace PolyVox /** Division operator divides corresponding elements of one Vector by the other. - \param lhs Vector to divide. - \param rhs Vector to divide by. + \param lhs The Vector to divide. + \param rhs The Vector to divide by. \return The resulting Vector. */ template @@ -362,8 +364,8 @@ namespace PolyVox /** Multiplication operator multiplies each element of the Vector by a number. - \param lhs the Vector to multiply. - \param rhs the number the Vector is multiplied by. + \param lhs The Vector to multiply. + \param rhs The number the Vector is multiplied by. \return The resulting Vector. */ template @@ -376,8 +378,8 @@ namespace PolyVox /** Division operator divides each element of the Vector by a number. - \param lhs the Vector to divide. - \param rhs the number the Vector is divided by. + \param lhs The Vector to divide. + \param rhs The number the Vector is divided by. \return The resulting Vector. */ template @@ -479,8 +481,8 @@ namespace PolyVox /** Sets several elements of a vector at once. - \param x x component to set. - \param y y component to set. + \param x The X component to set. + \param y The Y component to set. */ template inline void Vector::setElements(StorageType x, StorageType y) @@ -492,9 +494,9 @@ namespace PolyVox /** Sets several elements of a vector at once. - \param x x component to set. - \param y y component to set. - \param z z component to set. + \param x The X component to set. + \param y The Y component to set. + \param z The Z component to set. */ template inline void Vector::setElements(StorageType x, StorageType y, StorageType z) @@ -509,10 +511,10 @@ namespace PolyVox /** Sets several elements of a vector at once. - \param x x component to set. - \param y y component to set. - \param z z component to set. - \param w w component to set. + \param x The X component to set. + \param y The Y component to set. + \param z The Z component to set. + \param w The W component to set. */ template inline void Vector::setElements(StorageType x, StorageType y, StorageType z, StorageType w) @@ -569,8 +571,8 @@ namespace PolyVox } /** - \note This function does not make much sense on integer Vectors. - \return Length of the Vector. + \note This function always returns a single precision floating point value, even when the StorageType is a double precision floating point value or an integer. + \return The length of the Vector. */ template inline float Vector::length(void) const @@ -579,7 +581,7 @@ namespace PolyVox } /** - \return Squared length of the Vector. + \return The squared length of the Vector. */ template inline OperationType Vector::lengthSquared(void) const @@ -596,7 +598,7 @@ namespace PolyVox This function is commutative, such that a.angleTo(b) == b.angleTo(a). The angle returned is in radians and varies between 0 and 3.14(pi). It is always positive. - \note This function does not make much sense on integer Vectors. + \note This function always returns a single precision floating point value, even when the StorageType is a double precision floating point value or an integer. \param vector The Vector to find the angle to. \return The angle between them in radians. @@ -647,22 +649,21 @@ namespace PolyVox } /** - Divides the i, j, and k components by the length to give a Vector of length 1.0. + Divides the i, j, and k components by the length to give a Vector of length 1.0. If the vector is + very short (or zero) then a divide by zero may cause elements to take on invalid values. You may + want to check for this before normalising. - \note This function does not make much sense on integer Vectors. + \note You should not attempt to normalise a vector whose StorageType is an integer. */ template inline void Vector::normalise(void) { - StorageType tLength = static_cast(this->length()); - //FIXME - throw div by zero exception? - if(tLength < 0.0001f) - { - return; - } + float fLength = this->length(); for(uint32_t ct = 0; ct < Size; ++ct) { - m_tElements[ct] /= tLength; + // Standard float rules apply for divide-by-zero + m_tElements[ct] /= fLength; + assert(m_tElements[ct] == m_tElements[ct]); //Will assert if NAN } } }//namespace PolyVox