sid
/
NazaraEngine
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation for Vector4 + static DotProduct & Normalize 

Former-commit-id: 4a190589292f299d266e20f7b9723594f2c32468
This commit is contained in:
Gawaboumga 2015-12-30 15:36:38 +01:00
parent 95400fdfab
commit 139c495966
2 changed files with 505 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
include/Nazara/Math/Vector4.hpp
View File

@ -60,8 +60,8 @@ namespace Nz
String ToString() const;
operator T*();
operator const T*() const;
operator T* ();
operator const T* () const;
const Vector4& operator+() const;
Vector4 operator-() const;
@ -87,6 +87,9 @@ namespace Nz
bool operator>(const Vector4& vec) const;
bool operator>=(const Vector4& vec) const;
static T DotProduct(const Vector4& vec1, const Vector4& vec2);
static Vector4 Lerp(const Vector4& from, const Vector4& to, T interpolation);
static Vector4 Normalize(const Vector4& vec);
static Vector4 UnitX();
static Vector4 UnitY();
static Vector4 UnitZ();

507
include/Nazara/Math/Vector4.inl
View File

@ -14,54 +14,125 @@
namespace Nz
{
/*!
* \class Nz::Vector4<T>
* \brief Math class that represents an element of the three dimensional vector space with the notion of projectivity. When the fourth component is 1, it describes an 'usual' point and when it is 0, it represents the point at infinity
*/
/*!
* \brief Constructs a Vector4<T> object from its coordinates
*
* \param X X component
* \param Y Y component
* \param Z Z component
* \param W W component
*/
template<typename T>
Vector4<T>::Vector4(T X, T Y, T Z, T W)
{
Set(X, Y, Z, W);
}
/*!
* \brief Constructs a Vector4<T> object from two components and a Vector2<T>
*
* \param X X component
* \param Y Y component
* \param vec vec.X = Z component and vec.y = W component
*/
template<typename T>
Vector4<T>::Vector4(T X, T Y, const Vector2<T>& vec)
{
Set(X, Y, vec);
}
/*!
* \brief Constructs a Vector4<T> object from one component, a Vector2<T> and one component
*
* \param X X component
* \param vec vec.X = Y component and vec.y = Z component
* \param W W component
*/
template<typename T>
Vector4<T>::Vector4(T X, const Vector2<T>& vec, T W)
{
Set(X, vec, W);
}
/*!
* \brief Constructs a Vector4<T> object from one component and a Vector3<T>
*
* \param X X component
* \param vec vec.X = Y component, vec.y = Z component and vec.z = W component
*/
template<typename T>
Vector4<T>::Vector4(T X, const Vector3<T>& vec)
{
Set(X, vec);
}
/*!
* \brief Constructs explicitely a Vector4<T> object from its "scale"
*
* \param scale X component = Y component = Z component = W component
*/
template<typename T>
Vector4<T>::Vector4(T scale)
{
Set(scale);
}
/*!
* \brief Constructs a Vector4<T> object from an array of four elements
*
* \param vec[4] vec[0] is X component, vec[1] is Y component, vec[2] is Z component and vec[3] is W component
*/
template<typename T>
Vector4<T>::Vector4(const T vec[4])
{
Set(vec);
}
/*!
* \brief Constructs a Vector4<T> object from a Vector2<T> and two components
*
* \param vec vec.X = X component and vec.y = Y component
* \param Z Z component
* \param W W component
*/
template<typename T>
Vector4<T>::Vector4(const Vector2<T>& vec, T Z, T W)
{
Set(vec, Z, W);
}
/*!
* \brief Constructs a Vector4<T> object from one component and a Vector3<T>
*
* \param vec vec.X = X component, vec.y = Y component and vec.z = Z component
* \param W W component
*/
template<typename T>
Vector4<T>::Vector4(const Vector3<T>& vec, T W)
{
Set(vec, W);
}
/*!
* \brief Constructs a Vector4<T> object from another type of Vector4
*
* \param vec Vector of type U to convert to type T
*/
template<typename T>
template<typename U>
Vector4<T>::Vector4(const Vector4<U>& vec)
@ -69,18 +140,45 @@ namespace Nz
Set(vec);
}
/*!
* \brief Calculates the absolute dot (scalar) product with two vectors
* \return The dot product with absolutes values on each component
*
* \param vec The other vector to calculate the absolute dot product with
*
* \see DotProduct
*/
template<typename T>
T Vector4<T>::AbsDotProduct(const Vector4& vec) const
{
return std::abs(x * vec.x) + std::abs(y * vec.y) + std::abs(z * vec.z) + std::abs(w * vec.w);
}
/*!
* \brief Calculates the dot (scalar) product with two vectors
* \return The value of the dot product
*
* \param vec The other vector to calculate the dot product with
*
* \see AbsDotProduct, DotProduct
*/
template<typename T>
T Vector4<T>::DotProduct(const Vector4& vec) const
{
return x*vec.x + y*vec.y + z*vec.z + w*vec.w;
}
/*!
* \brief Gets a copy normalized of the vector
* \return A new vector which is the vector normalized
*
* \param length Optional argument to obtain the length's ratio of the vector and the unit-length in this case w
*
* \see Normalize
*/
template<typename T>
Vector4<T> Vector4<T>::GetNormal(T* length) const
{
@ -90,30 +188,67 @@ namespace Nz
return vec;
}
/*!
* \brief Makes the vector (1, 0, 0, 1)
* \return A reference to this vector with components (1, 0, 0, 1)
*
* \see UnitX
*/
template<typename T>
Vector4<T>& Vector4<T>::MakeUnitX()
{
return Set(F(1.0), F(0.0), F(0.0), F(1.0));
}
/*!
* \brief Makes the vector (0, 1, 0, 1)
* \return A reference to this vector with components (0, 1, 0, 1)
*
* \see UnitY
*/
template<typename T>
Vector4<T>& Vector4<T>::MakeUnitY()
{
return Set(F(0.0), F(1.0), F(0.0), F(1.0));
}
/*!
* \brief Makes the vector (0, 0, 1, 1)
* \return A reference to this vector with components (0, 0, 1, 1)
*
* \see UnitZ
*/
template<typename T>
Vector4<T>& Vector4<T>::MakeUnitZ()
{
return Set(F(0.0), F(0.0), F(1.0), F(1.0));
}
/*!
* \brief Makes the vector (0, 0, 0, 1)
* \return A reference to this vector with components (0, 0, 0, 1)
*
* \see Zero
*/
template<typename T>
Vector4<T>& Vector4<T>::MakeZero()
{
return Set(F(0.0), F(0.0), F(0.0), F(0.0));
return Set(F(0.0), F(0.0), F(0.0), F(1.0));
}
/*!
* \brief Sets this vector's components to the maximum of its own and other components
* \return A reference to this vector with replaced values with the corresponding max value
*
* \param vec Other vector to compare the components with
*
* \see Minimize
*/
template<typename T>
Vector4<T>& Vector4<T>::Maximize(const Vector4& vec)
{
@ -132,6 +267,15 @@ namespace Nz
return *this;
}
/*!
* \brief Sets this vector's components to the minimum of its own and other components
* \return A reference to this vector with replaced values with the corresponding min value
*
* \param vec Other vector to compare the components with
*
* \see Maximize
*/
template<typename T>
Vector4<T>& Vector4<T>::Minimize(const Vector4& vec)
{
@ -150,11 +294,20 @@ namespace Nz
return *this;
}
/*!
* \brief Gives the normalized vector
* \return A normalized vector from the vec with w = 1
*
* \param length Optional argument to obtain the length's ratio of the vector in this case w
*
* \see GetNormal
*/
template<typename T>
Vector4<T>& Vector4<T>::Normalize(T* length)
{
T invLength = F(1.0)/w;
x *= invLength; // Attention, briser cette logique casserait Frustum::Extract
x *= invLength; // Warning, change this logic will break Frustum::Extract
y *= invLength;
z *= invLength;
@ -166,6 +319,16 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the vector
* \return A reference to this vector
*
* \param X X component
* \param Y Y component
* \param Z Z component
* \param W W component
*/
template<typename T>
Vector4<T>& Vector4<T>::Set(T X, T Y, T Z, T W)
{
@ -177,6 +340,15 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the vector from two components and a Vector2
* \return A reference to this vector
*
* \param X X component
* \param Y Y component
* \param vec vec.X = Z component and vec.y = W component
*/
template<typename T>
Vector4<T>& Vector4<T>::Set(T X, T Y, const Vector2<T>& vec)
{
@ -188,6 +360,15 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the vector from one component, a Vector2 and one component
* \return A reference to this vector
*
* \param X X component
* \param vec vec.X = Y component and vec.y = Z component
* \param W W component
*/
template<typename T>
Vector4<T>& Vector4<T>::Set(T X, const Vector2<T>& vec, T W)
{
@ -199,6 +380,14 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the vector from one component and a Vector3
* \return A reference to this vector
*
* \param X X component
* \param vec vec.X = Y component, vec.y = Z component and vec.z = W component
*/
template<typename T>
Vector4<T>& Vector4<T>::Set(T X, const Vector3<T>& vec)
{
@ -210,6 +399,13 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the vector from a "scale"
* \return A reference to this vector
*
* \param scale X component = Y component = Z component = W component
*/
template<typename T>
Vector4<T>& Vector4<T>::Set(T scale)
{
@ -221,6 +417,13 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the vector from an array of four elements
* \return A reference to this vector
*
* \param vec[4] vec[0] is X component, vec[1] is Y component, vec[2] is Z component and vec[3] is W component
*/
template<typename T>
Vector4<T>& Vector4<T>::Set(const T vec[4])
{
@ -229,6 +432,14 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the vector from a Vector2 and two components
*
* \param vec vec.X = X component and vec.y = Y component
* \param Z Z component
* \param W W component
*/
template<typename T>
Vector4<T>& Vector4<T>::Set(const Vector2<T>& vec, T Z, T W)
{
@ -240,6 +451,13 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the vector from a Vector3 and one components
*
* \param vec vec.X = X component, vec.y = Y component and vec.z = Z component
* \param W W component
*/
template<typename T>
Vector4<T>& Vector4<T>::Set(const Vector3<T>& vec, T W)
{
@ -251,6 +469,13 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the vector from another vector
* \return A reference to this vector
*
* \param vec The other vector
*/
template<typename T>
Vector4<T>& Vector4<T>::Set(const Vector4& vec)
{
@ -259,6 +484,13 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the vector from another type of Vector4
* \return A reference to this vector
*
* \param vec Vector of type U to convert its components
*/
template<typename T>
template<typename U>
Vector4<T>& Vector4<T>::Set(const Vector4<U>& vec)
@ -271,6 +503,11 @@ namespace Nz
return *this;
}
/*!
* \brief Gives a string representation
* \return A string representation of the object: "Vector4(x, y, z, w)"
*/
template<typename T>
String Vector4<T>::ToString() const
{
@ -279,54 +516,116 @@ namespace Nz
return ss << "Vector4(" << x << ", " << y << ", " << z << ", " << w << ')';
}
/*!
* \brief Converts vector to pointer to its own data
* \return A pointer to the own data
*
* \remark Access to index greather than 3 is undefined behavior
*/
template<typename T>
Vector4<T>::operator T*()
Vector4<T>::operator T* ()
{
return &x;
}
/*!
* \brief Converts vector to const pointer to its own data
* \return A constant pointer to the own data
*
* \remark Access to index greather than 3 is undefined behavior
*/
template<typename T>
Vector4<T>::operator const T*() const
Vector4<T>::operator const T* () const
{
return &x;
}
/*!
* \brief Helps to represent the sign of the vector
* \return A constant reference to this vector
*/
template<typename T>
const Vector4<T>& Vector4<T>::operator+() const
{
return *this;
}
/*!
* \brief Negates the components of the vector
* \return A constant reference to this vector with negate components
*/
template<typename T>
Vector4<T> Vector4<T>::operator-() const
{
return Vector4(-x, -y, -z, -w);
}
/*!
* \brief Adds the components of the vector with other vector
* \return A vector where components are the sum of this vector and the other one
*
* \param vec The other vector to add components with
*/
template<typename T>
Vector4<T> Vector4<T>::operator+(const Vector4& vec) const
{
return Vector4(x + vec.x, y + vec.y, z + vec.z, w + vec.w);
}
/*!
* \brief Substracts the components of the vector with other vector
* \return A vector where components are the difference of this vector and the other one
*
* \param vec The other vector to substract components with
*/
template<typename T>
Vector4<T> Vector4<T>::operator-(const Vector4& vec) const
{
return Vector4(x - vec.x, y - vec.y, z - vec.z, w - vec.w);
}
/*!
* \brief Multiplies the components of the vector with other vector
* \return A vector where components are the product of this vector and the other one
*
* \param vec The other vector to multiply components with
*/
template<typename T>
Vector4<T> Vector4<T>::operator*(const Vector4& vec) const
{
return Vector4(x * vec.x, y * vec.y, z * vec.z, w * vec.w);
}
/*!
* \brief Multiplies the components of the vector with a scalar
* \return A vector where components are the product of this vector and the scalar
*
* \param scale The scalar to multiply components with
*/
template<typename T>
Vector4<T> Vector4<T>::operator*(T scale) const
{
return Vector4(x * scale, y * scale, z * scale, w * scale);
}
/*!
* \brief Divides the components of the vector with other vector
* \return A vector where components are the quotient of this vector and the other one
*
* \param vec The other vector to divide components with
*
* \remark Produce a NazaraError if one of the vec components is null with NAZARA_MATH_SAFE defined
* \throw std::domain_error if NAZARA_MATH_SAFE is defined and one of the vec components is null
*/
template<typename T>
Vector4<T> Vector4<T>::operator/(const Vector4& vec) const
{
@ -343,6 +642,16 @@ namespace Nz
return Vector4(x / vec.x, y / vec.y, z / vec.z, w / vec.w);
}
/*!
* \brief Divides the components of the vector with a scalar
* \return A vector where components are the quotient of this vector and the scalar
*
* \param scale The scalar to divide components with
*
* \remark Produce a NazaraError if scale is null with NAZARA_MATH_SAFE defined
* \throw std::domain_error if NAZARA_MATH_SAFE is defined and scale is null
*/
template<typename T>
Vector4<T> Vector4<T>::operator/(T scale) const
{
@ -359,6 +668,13 @@ namespace Nz
return Vector4(x / scale, y / scale, z / scale, w / scale);
}
/*!
* \brief Adds the components of other vector to this vector
* \return A reference to this vector where components are the sum of this vector and the other one
*
* \param vec The other vector to add components with
*/
template<typename T>
Vector4<T>& Vector4<T>::operator+=(const Vector4& vec)
{
@ -370,6 +686,13 @@ namespace Nz
return *this;
}
/*!
* \brief Substracts the components of other vector to this vector
* \return A reference to this vector where components are the difference of this vector and the other one
*
* \param vec The other vector to substract components with
*/
template<typename T>
Vector4<T>& Vector4<T>::operator-=(const Vector4& vec)
{
@ -381,6 +704,13 @@ namespace Nz
return *this;
}
/*!
* \brief Multiplies the components of other vector to this vector
* \return A reference to this vector where components are the product of this vector and the other one
*
* \param vec The other vector to multiply components with
*/
template<typename T>
Vector4<T>& Vector4<T>::operator*=(const Vector4& vec)
{
@ -392,6 +722,13 @@ namespace Nz
return *this;
}
/*!
* \brief Multiplies the components of other vector with a scalar
* \return A reference to this vector where components are the product of this vector and the scalar
*
* \param vec The other vector to multiply components with
*/
template<typename T>
Vector4<T>& Vector4<T>::operator*=(T scale)
{
@ -403,6 +740,16 @@ namespace Nz
return *this;
}
/*!
* \brief Multiplies the components of other vector to this vector
* \return A reference to this vector where components are the quotient of this vector and the other one
*
* \param vec The other vector to multiply components with
*
* \remark Produce a NazaraError if one of the vec components is null with NAZARA_MATH_SAFE defined
* \throw std::domain_error if NAZARA_MATH_SAFE is defined and one of the vec components is null
*/
template<typename T>
Vector4<T>& Vector4<T>::operator/=(const Vector4& vec)
{
@ -424,6 +771,16 @@ namespace Nz
return *this;
}
/*!
* \brief Divides the components of other vector with a scalar
* \return A reference to this vector where components are the quotient of this vector and the scalar
*
* \param vec The other vector to divide components with
*
* \remark Produce a NazaraError if scale is null with NAZARA_MATH_SAFE defined
* \throw std::domain_error if NAZARA_MATH_SAFE is defined and scale is null
*/
template<typename T>
Vector4<T>& Vector4<T>::operator/=(T scale)
{
@ -445,21 +802,42 @@ namespace Nz
return *this;
}
/*!
* \brief Compares the vector to other one
* \return true if the vectors are the same
*
* \param vec Other vector to compare with
*/
template<typename T>
bool Vector4<T>::operator==(const Vector4& vec) const
{
return NumberEquals(x, vec.x) &&
NumberEquals(y, vec.y) &&
NumberEquals(z, vec.z) &&
NumberEquals(w, vec.w);
NumberEquals(y, vec.y) &&
NumberEquals(z, vec.z) &&
NumberEquals(w, vec.w);
}
/*!
* \brief Compares the vector to other one
* \return false if the vectors are the same
*
* \param vec Other vector to compare with
*/
template<typename T>
bool Vector4<T>::operator!=(const Vector4& vec) const
{
return !operator==(vec);
}
/*!
* \brief Compares the vector to other one
* \return true if this vector has its first components inferior to the other ones
*
* \param vec Other vector to compare with
*/
template<typename T>
bool Vector4<T>::operator<(const Vector4& vec) const
{
@ -479,6 +857,13 @@ namespace Nz
return x < vec.x;
}
/*!
* \brief Compares the vector to other one
* \return true if this vector has its first components inferior or equal to the other ones
*
* \param vec Other vector to compare with
*/
template<typename T>
bool Vector4<T>::operator<=(const Vector4& vec) const
{
@ -498,18 +883,79 @@ namespace Nz
return x < vec.x;
}
/*!
* \brief Compares the vector to other one
* \return true if this vector has its first components superior to the other ones
*
* \param vec Other vector to compare with
*/
template<typename T>
bool Vector4<T>::operator>(const Vector4& vec) const
{
return !operator<=(vec);
}
/*!
* \brief Compares the vector to other one
* \return true if this vector has its first components superior or equal to the other ones
*
* \param vec Other vector to compare with
*/
template<typename T>
bool Vector4<T>::operator>=(const Vector4& vec) const
{
return !operator<(vec);
}
/*!
* \brief Interpolates the vector to other one with a factor of interpolation
* \return A new vector which is the interpolation of two vectors
*
* \param from Initial vector
* \param to Target vector
* \param interpolation Factor of interpolation
*
* \remark interpolation is meant to be between 0 and 1, other values are potentially undefined behavior
*
* \see Lerp
*/
template<typename T>
Vector4<T> Vector4<T>::Lerp(const Vector4& from, const Vector4& to, T interpolation)
{
Vector4 dummy;
dummy.x = Nz::Lerp(from.x, to.x, interpolation);
dummy.y = Nz::Lerp(from.y, to.y, interpolation);
dummy.z = Nz::Lerp(from.z, to.z, interpolation);
dummy.w = Nz::Lerp(from.w, to.w, interpolation);
return dummy;
}
/*!
* \brief Gives the normalized vector
* \return A normalized vector from the vec with w = 1
*
* \param vec Vector to normalize
*
* \see GetNormal
*/
template<typename T>
Vector4<T> Vector4<T>::Normalize(const Vector4& vec)
{
return vec.GetNormal();
}
/*!
* \brief Shorthand for the vector (1, 0, 0, 1)
* \return A vector with components (1, 0, 0, 1)
*
* \see MakeUnitX
*/
template<typename T>
Vector4<T> Vector4<T>::UnitX()
{
@ -519,6 +965,13 @@ namespace Nz
return vector;
}
/*!
* \brief Shorthand for the vector (0, 1, 0, 1)
* \return A vector with components (0, 1, 0, 1)
*
* \see MakeUnitY
*/
template<typename T>
Vector4<T> Vector4<T>::UnitY()
{
@ -528,6 +981,13 @@ namespace Nz
return vector;
}
/*!
* \brief Shorthand for the vector (0, 0, 1, 1)
* \return A vector with components (0, 0, 1, 1)
*
* \see MakeUnitZ
*/
template<typename T>
Vector4<T> Vector4<T>::UnitZ()
{
@ -537,6 +997,13 @@ namespace Nz
return vector;
}
/*!
* \brief Shorthand for the vector (0, 0, 0, 1)
* \return A vector with components (0, 0, 0, 1)
*
* \see MakeZero
*/
template<typename T>
Vector4<T> Vector4<T>::Zero()
{
@ -547,18 +1014,44 @@ namespace Nz
}
}
/*!
* \brief Output operator
* \return The stream
*
* \param out The stream
* \param vec The vector to output
*/
template<typename T>
std::ostream& operator<<(std::ostream& out, const Nz::Vector4<T>& vec)
{
return out << vec.ToString();
}
/*!
* \brief Multiplies the components of the vector with a scalar
* \return A vector where components are the product of this vector and the scalar
*
* \param scale The scalar to multiply components with
*/
template<typename T>
Nz::Vector4<T> operator*(T scale, const Nz::Vector4<T>& vec)
{
return Nz::Vector4<T>(scale * vec.x, scale * vec.y, scale * vec.z, scale * vec.w);
}
/*!
* \brief Divides the components of the vector with a scalar
* \return A vector where components are the quotient of this vector and the scalar
*
* \param scale The scalar to divide components with
*
* \remark Produce a NazaraError if scale is null with NAZARA_MATH_SAFE defined
* \throw std::domain_error if NAZARA_MATH_SAFE is defined and scale is null
*/
template<typename T>
Nz::Vector4<T> operator/(T scale, const Nz::Vector4<T>& vec)
{