Some small documentation changes to Vector.h

Deprecated operator<
Fix for normalise()

The CDash machine will probably give deprecated warnings - I'll fix those soon...

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 <uint32_t Size, typename StorageType, typename OperationType>
 	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<Size,StorageType,OperationType>& vector);
-		///Copy Constructor which performs casting.
+		/// Copy Constructor which performs casting.
 		template <typename CastType> explicit Vector(const Vector<Size,CastType>& vector);
-        ///Destructor.
+        /// Destructor.
         ~Vector(void);
 
-        ///Assignment Operator.
+        /// Assignment Operator.
         Vector<Size,StorageType,OperationType>& operator=(const Vector<Size,StorageType,OperationType>& rhs);
-        ///Equality Operator.
+        /// Equality Operator.
         bool operator==(const Vector<Size,StorageType,OperationType>& rhs) const;
-		///Inequality Operator.
+		/// Inequality Operator.
         bool operator!=(const Vector<Size,StorageType,OperationType>& rhs) const;
-		///Comparison Operator.
+		/// Comparison Operator.
-        bool operator<(const Vector<Size,StorageType,OperationType>& rhs) const;
+        POLYVOX_DEPRECATED bool operator<(const Vector<Size,StorageType,OperationType>& rhs) const;
-        ///Addition and Assignment Operator.
+        /// Addition and Assignment Operator.
         Vector<Size,StorageType,OperationType>& operator+=(const Vector<Size,StorageType,OperationType> &rhs);
-        ///Subtraction and Assignment Operator.
+        /// Subtraction and Assignment Operator.
         Vector<Size,StorageType,OperationType>& operator-=(const Vector<Size,StorageType,OperationType> &rhs);
-		///Multiplication and Assignment Operator.
+		/// Multiplication and Assignment Operator.
         Vector<Size,StorageType,OperationType>& operator*=(const Vector<Size,StorageType,OperationType> &rhs);
-        ///Division and Assignment Operator.
+        /// Division and Assignment Operator.
         Vector<Size,StorageType,OperationType>& operator/=(const Vector<Size,StorageType,OperationType> &rhs);
-        ///Multiplication and Assignment Operator.
+        /// Multiplication and Assignment Operator.
         Vector<Size,StorageType,OperationType>& operator*=(const StorageType& rhs);
-        ///Division and Assignment Operator.
+        /// Division and Assignment Operator.
         Vector<Size,StorageType,OperationType>& 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<Size,StorageType,OperationType>& 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<Size,StorageType,OperationType> cross(const Vector<Size,StorageType,OperationType>& 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<Size,StorageType,OperationType>& 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. 
+    // Non-member overloaded operators. 
-	///Addition operator.
+	/// Addition operator.
 	template <uint32_t Size,typename StorageType,typename OperationType>
 	    Vector<Size,StorageType,OperationType> operator+(const Vector<Size,StorageType,OperationType>& lhs, const Vector<Size,StorageType,OperationType>& rhs);
-	///Subtraction operator.
+	/// Subtraction operator.
 	template <uint32_t Size,typename StorageType,typename OperationType>
 	    Vector<Size,StorageType,OperationType> operator-(const Vector<Size,StorageType,OperationType>& lhs, const Vector<Size,StorageType,OperationType>& rhs);
-	///Multiplication operator.
+	/// Multiplication operator.
 	template <uint32_t Size,typename StorageType,typename OperationType>
 	    Vector<Size,StorageType,OperationType> operator*(const Vector<Size,StorageType,OperationType>& lhs, const Vector<Size,StorageType,OperationType>& rhs);
-	///Division operator.
+	/// Division operator.
 	template <uint32_t Size,typename StorageType,typename OperationType>
 	    Vector<Size,StorageType,OperationType> operator/(const Vector<Size,StorageType,OperationType>& lhs, const Vector<Size,StorageType,OperationType>& rhs);
-	///Multiplication operator.
+	/// Multiplication operator.
 	template <uint32_t Size,typename StorageType,typename OperationType>
 	    Vector<Size,StorageType,OperationType> operator*(const Vector<Size,StorageType,OperationType>& lhs, const StorageType& rhs);
-	///Division operator.
+	/// Division operator.
 	template <uint32_t Size,typename StorageType,typename OperationType>
 	    Vector<Size,StorageType,OperationType> operator/(const Vector<Size,StorageType,OperationType>& lhs, const StorageType& rhs);
-    ///Stream insertion operator.
+    /// Stream insertion operator.
     template <uint32_t Size, typename StorageType,typename OperationType>
         std::ostream& operator<<(std::ostream& os, const Vector<Size,StorageType,OperationType>& 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;
 
 

library/PolyVoxCore/include/PolyVoxCore/Vector.inl

@@ -33,8 +33,8 @@ namespace PolyVox
 	}
 
 	/**
-    Creates a Vector object and initialises it with given values.
+    Creates a Vector object and initialises all components with the given value.
-    \param x x component to set.
+    \param tFillValue The value to write to every component.
     */
     template <uint32_t Size,typename StorageType, typename OperationType>
 	Vector<Size,StorageType,OperationType>::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 x The X component to set.
-    \param y y component to set.
+    \param y The Y component to set.
     */
     template <uint32_t Size,typename StorageType, typename OperationType>
     Vector<Size,StorageType,OperationType>::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 x The X component to set.
-	\param y y component to set.
+	\param y The Y component to set.
-	\param z z component to set.
+	\param z the Z component to set.
 	*/
 	template <uint32_t Size,typename StorageType, typename OperationType>
 	Vector<Size,StorageType,OperationType>::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 x The X component to set.
-	\param y y component to set.
+	\param y The Y component to set.
-	\param z z component to set.
+	\param z The Z component to set.
-	\param w w component to set.
+	\param w The W component to set.
 	*/
 	template <uint32_t Size,typename StorageType, typename OperationType>
 	Vector<Size,StorageType,OperationType>::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<Vector3DFloat>(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 <uint32_t Size, typename StorageType, typename OperationType>
 	inline bool Vector<Size, StorageType, OperationType>::operator<(const Vector<Size, StorageType, OperationType> &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 <uint32_t Size, typename StorageType, typename OperationType>
@@ -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 <uint32_t Size, typename StorageType, typename OperationType>
@@ -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 <uint32_t Size, typename StorageType, typename OperationType>
@@ -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 <uint32_t Size, typename StorageType, typename OperationType>
@@ -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 <uint32_t Size, typename StorageType, typename OperationType>
@@ -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 <uint32_t Size, typename StorageType, typename OperationType>
@@ -306,8 +308,8 @@ namespace PolyVox
 
 	/**
     Addition operator adds corresponding elements of the two Vectors.
-	\param lhs Vector to add to.
+	\param lhs The Vector to add to.
-    \param rhs Vector to add.
+    \param rhs The Vector to add.
     \return The resulting Vector.
     */
 	template <uint32_t Size,typename StorageType, typename OperationType>
@@ -320,8 +322,8 @@ namespace PolyVox
 
 	/**
     Subtraction operator subtracts corresponding elements of one Vector from the other.
-	\param lhs Vector to subtract from.
+	\param lhs The Vector to subtract from.
-    \param rhs Vector to subtract.
+    \param rhs The Vector to subtract.
     \return The resulting Vector.
     */
 	template <uint32_t Size,typename StorageType, typename OperationType>
@@ -334,8 +336,8 @@ namespace PolyVox
 
 	/**
     Multiplication operator mulitplies corresponding elements of the two Vectors.
-	\param lhs Vector to multiply.
+	\param lhs The Vector to multiply.
-    \param rhs Vector to multiply by.
+    \param rhs The Vector to multiply by.
     \return The resulting Vector.
     */
 	template <uint32_t Size,typename StorageType, typename OperationType>
@@ -348,8 +350,8 @@ namespace PolyVox
 
 	/**
     Division operator divides corresponding elements of one Vector by the other.
-	\param lhs Vector to divide.
+	\param lhs The Vector to divide.
-    \param rhs Vector to divide by.
+    \param rhs The Vector to divide by.
     \return The resulting Vector.
     */
 	template <uint32_t Size,typename StorageType, typename OperationType>
@@ -362,8 +364,8 @@ namespace PolyVox
 
 	/**
     Multiplication operator multiplies each element of the Vector by a number.
-	\param lhs the Vector to multiply.
+	\param lhs The Vector to multiply.
-    \param rhs the number the Vector is multiplied by.
+    \param rhs The number the Vector is multiplied by.
     \return The resulting Vector.
     */
 	template <uint32_t Size,typename StorageType, typename OperationType>
@@ -376,8 +378,8 @@ namespace PolyVox
 
 	/**
 	Division operator divides each element of the Vector by a number.
-	\param lhs the Vector to divide.
+	\param lhs The Vector to divide.
-	\param rhs the number the Vector is divided by.
+	\param rhs The number the Vector is divided by.
 	\return The resulting Vector.
     */
 	template <uint32_t Size,typename StorageType, typename OperationType>
@@ -479,8 +481,8 @@ namespace PolyVox
 
 	/**
     Sets several elements of a vector at once.
-    \param x x component to set.
+    \param x The X component to set.
-    \param y y component to set.
+    \param y The Y component to set.
     */
     template <uint32_t Size,typename StorageType, typename OperationType>
 	inline void Vector<Size,StorageType,OperationType>::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 x The X component to set.
-	\param y y component to set.
+	\param y The Y component to set.
-	\param z z component to set.
+	\param z The Z component to set.
 	*/
 	template <uint32_t Size,typename StorageType, typename OperationType>
 	inline void Vector<Size,StorageType,OperationType>::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 x The X component to set.
-	\param y y component to set.
+	\param y The Y component to set.
-	\param z z component to set.
+	\param z The Z component to set.
-	\param w w component to set.
+	\param w The W component to set.
 	*/
 	template <uint32_t Size,typename StorageType, typename OperationType>
 	inline void Vector<Size,StorageType,OperationType>::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.
+	\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 Length of the Vector.
+    \return The length of the Vector.
     */
     template <uint32_t Size, typename StorageType, typename OperationType>
 	inline float Vector<Size, StorageType, OperationType>::length(void) const
@@ -579,7 +581,7 @@ namespace PolyVox
     }
 
     /**
-    \return Squared length of the Vector.
+    \return The squared length of the Vector.
     */
     template <uint32_t Size, typename StorageType, typename OperationType>
 	inline OperationType Vector<Size, StorageType, OperationType>::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 <uint32_t Size, typename StorageType, typename OperationType>
 	inline void Vector<Size, StorageType, OperationType>::normalise(void)
     {
-        StorageType tLength = static_cast<StorageType>(this->length());
+        float fLength = this->length();
-		//FIXME - throw div by zero exception?
-		if(tLength < 0.0001f)
-		{
-			return;
-		}
 		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