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

Documentation for Plane + add MakeXY methods 

Former-commit-id: 688a65089e6e332e3a2ffbed7966e4f9185b79cc
This commit is contained in:
Gawaboumga 2015-12-30 15:32:41 +01:00
parent f131fd2121
commit 53f4bacab6
2 changed files with 263 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
include/Nazara/Math/Plane.hpp
View File

@ -1,4 +1,4 @@
// Copyright (C) 2015 Jérôme Leclercq
// Copyright (C) 2015 Jérôme Leclercq
// This file is part of the "Nazara Engine - Mathematics module"
// For conditions of distribution and use, see copyright notice in Config.hpp
@ -26,8 +26,12 @@ namespace Nz
Plane(const Plane& plane) = default;
~Plane() = default;
T Distance(const Vector3<T>& point) const;
T Distance(T x, T y, T z) const;
T Distance(const Vector3<T>& point) const;
Plane& MakeXY();
Plane& MakeXZ();
Plane& MakeYZ();
Plane& Set(T normalX, T normalY, T normalZ, T Distance);
Plane& Set(const T plane[4]);

266
include/Nazara/Math/Plane.inl
View File

@ -11,36 +11,88 @@
namespace Nz
{
/*!
* \class Nz::Vector4<T>
* \brief Math class that represents a plane in 3D
*
* \remark The convention used in this class is: If you ask for plane with normal (0, 1, 0) and distance 1, you will get 0 * X + 1 * Y + 0 * Z - 1 = 0 or Y = 1. Notice the sign minus before the distance on the left side of the equation
*/
/*!
* \brief Constructs a Plane<T> object from its components
*
* \param normalX X component of the normal
* \param normalY Y component of the normal
* \param normalZ Z component of the normal
* \param D Distance to origin
*/
template<typename T>
Plane<T>::Plane(T normalX, T normalY, T normalZ, T D)
{
Set(normalX, normalY, normalZ, D);
}
/*!
* \brief Constructs a Plane<T> object from an array of four elements
*
* \param plane[4] plane[0] is X component, plane[1] is Y component, plane[2] is Z component and plane[3] is D
*/
template<typename T>
Plane<T>::Plane(const T plane[4])
{
Set(plane);
}
/*!
* \brief Constructs a Plane<T> object from a normal and a distance
*
* \param Normal normal of the vector
* \param D Distance to origin
*/
template<typename T>
Plane<T>::Plane(const Vector3<T>& Normal, T D)
{
Set(Normal, D);
}
/*!
* \brief Constructs a Plane<T> object from a normal and a point
*
* \param Normal Normal of the plane
* \param point Point which verifies the equation of the plane
*/
template<typename T>
Plane<T>::Plane(const Vector3<T>& Normal, const Vector3<T>& point)
{
Set(Normal, point);
}
/*!
* \brief Constructs a Plane<T> object from three points
*
* \param point1 First point
* \param point2 Second point
* \param point3 Third point
*
* \remark They are expected not to be colinear
*/
template<typename T>
Plane<T>::Plane(const Vector3<T>& point1, const Vector3<T>& point2, const Vector3<T>& point3)
{
Set(point1, point2, point3);
}
/*!
* \brief Constructs a Plane<T> object from another type of Plane
*
* \param plane Plane of type U to convert to type T
*/
template<typename T>
template<typename U>
Plane<T>::Plane(const Plane<U>& plane)
@ -48,11 +100,18 @@ namespace Nz
Set(plane);
}
template<typename T>
T Plane<T>::Distance(const Vector3<T>& point) const
{
return normal.DotProduct(point) - distance; // ax + by + cd - d = 0.
}
/*!
* \brief Returns the distance from the plane to the point
* \return Distance to the point
*
* \param X X position of the point
* \param Y Y position of the point
* \param Z Z position of the point
*
* \remark If T is negative, it means that the point is in the opposite direction of the normal
*
* \see Distance
*/
template<typename T>
T Plane<T>::Distance(T x, T y, T z) const
@ -60,6 +119,72 @@ namespace Nz
return Distance(Vector3<T>(x, y, z));
}
/*!
* \brief Returns the distance from the plane to the point
* \return Distance to the point
*
* \param point Position of the point
*
* \remark If T is negative, it means that the point is in the opposite direction of the normal
*
* \see Distance
*/
template<typename T>
T Plane<T>::Distance(const Vector3<T>& point) const
{
return normal.DotProduct(point) - distance; // ax + by + cd - d = 0.
}
/*!
* \brief Makes the plane (0, 0, 1, 0)
* \return A reference to this plane with components (0, 0, 1, 0)
*
* \see XY
*/
template<typename T>
Plane<T>& Plane<T>::MakeXY()
{
return Set(F(0.0), F(0.0), F(1.0), F(0.0));
}
/*!
* \brief Makes the plane (0, 1, 0, 0)
* \return A reference to this plane with components (0, 1, 0, 0)
*
* \see XZ
*/
template<typename T>
Plane<T>& Plane<T>::MakeXZ()
{
return Set(F(0.0), F(1.0), F(0.0), F(0.0));
}
/*!
* \brief Makes the plane (1, 0, 0, 0)
* \return A reference to this plane with components (1, 0, 0, 0)
*
* \see YZ
*/
template<typename T>
Plane<T>& Plane<T>::MakeYZ()
{
return Set(F(1.0), F(0.0), F(0.0), F(0.0));
}
/*!
* \brief Sets the components of the plane
* \return A reference to this plane
*
* \param normalX X component of the normal
* \param normalY Y component of the normal
* \param normalZ Z component of the normal
* \param D Distance to origin
*/
template<typename T>
Plane<T>& Plane<T>::Set(T normalX, T normalY, T normalZ, T D)
{
@ -69,6 +194,13 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the plane from an array of four elements
* \return A reference to this plane
*
* \param plane[4] plane[0] is X component, plane[1] is Y component, plane[2] is Z component and plane[3] is D
*/
template<typename T>
Plane<T>& Plane<T>::Set(const T plane[4])
{
@ -78,6 +210,13 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the plane from another plane
* \return A reference to this plane
*
* \param plane The other plane
*/
template<typename T>
Plane<T>& Plane<T>::Set(const Plane& plane)
{
@ -86,6 +225,14 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the plane from a normal and a distance
* \return A reference to this plane
*
* \param Normal Normal of the vector
* \param D Distance to origin
*/
template<typename T>
Plane<T>& Plane<T>::Set(const Vector3<T>& Normal, T D)
{
@ -95,6 +242,14 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the plane from a normal and a point
* \return A reference to this plane
*
* \param Normal Normal of the plane
* \param point Point which verifies the equation of the plane
*/
template<typename T>
Plane<T>& Plane<T>::Set(const Vector3<T>& Normal, const Vector3<T>& point)
{
@ -104,6 +259,17 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the plane from three points
* \return A reference to this plane
*
* \param point1 First point
* \param point2 Second point
* \param point3 Third point
*
* \remark They are expected not to be colinear
*/
template<typename T>
Plane<T>& Plane<T>::Set(const Vector3<T>& point1, const Vector3<T>& point2, const Vector3<T>& point3)
{
@ -117,6 +283,13 @@ namespace Nz
return *this;
}
/*!
* \brief Sets the components of the plane from another type of Plane
* \return A reference to this plane
*
* \param plane Plane of type U to convert its components
*/
template<typename T>
template<typename U>
Plane<T>& Plane<T>::Set(const Plane<U>& plane)
@ -127,6 +300,11 @@ namespace Nz
return *this;
}
/*!
* \brief Gives a string representation
* \return A string representation of the object: "Plane(Normal: Vector3(x, y, z); Distance: w)"
*/
template<typename T>
String Plane<T>::ToString() const
{
@ -135,18 +313,50 @@ namespace Nz
return ss << "Plane(Normal: " << normal.ToString() << "; Distance: " << distance << ')';
}
/*!
* \brief Compares the plane to other one
* \return true if the planes are the same
*
* \param vec Other vector to compare with
*
* \remark Plane with normal N and distance D is the same than with normal -N et distance -D
*/
template<typename T>
bool Plane<T>::operator==(const Plane& plane) const
{
return (normal == plane.normal && NumberEquals(distance, plane.distance)) || (normal == -plane.normal && NumberEquals(distance, -plane.distance));
}
/*!
* \brief Compares the plane to other one
* \return false if the planes are the same
*
* \param plane Other plane to compare with
*
* \remark Plane with normal N and distance D is the same than with normal -N et distance -D
*/
template<typename T>
bool Plane<T>::operator!=(const Plane& plane) const
{
return !operator==(plane);
}
/*!
* \brief Interpolates the plane to other one with a factor of interpolation
* \return A new plane which is the interpolation of two planes
*
* \param from Initial plane
* \param to Target plane
* \param interpolation Factor of interpolation
*
* \remark interpolation is meant to be between 0 and 1, other values are potentially undefined behavior
* \remark With NAZARA_DEBUG, a NazaraError is thrown and Plane() is returned
*
* \see Lerp
*/
template<typename T>
Plane<T> Plane<T>::Lerp(const Plane& from, const Plane& to, T interpolation)
{
@ -159,32 +369,70 @@ namespace Nz
#endif
Plane plane;
plane.distance = Lerp(from.distance, to.distance, interpolation);
plane.distance = Nz::Lerp(from.distance, to.distance, interpolation);
plane.normal = Vector3<T>::Lerp(from.normal, to.normal, interpolation);
plane.normal.Normalize();
return plane;
}
/*!
* \brief Shorthand for the plane (0, 0, 1, 0)
* \return A plane with components (0, 0, 1, 0)
*
* \see MakeXY
*/
template<typename T>
Plane<T> Plane<T>::XY()
{
return Plane<T>(F(0.0), F(0.0), F(1.0), F(0.0));
Plane plane;
plane.MakeXY();
return plane;
}
/*!
* \brief Shorthand for the plane (0, 1, 0, 0)
* \return A plane with components (0, 1, 0, 0)
*
* \see MakeXZ
*/
template<typename T>
Plane<T> Plane<T>::XZ()
{
return Plane<T>(F(0.0), F(1.0), F(0.0), F(0.0));
Plane plane;
plane.MakeXZ();
return plane;
}
/*!
* \brief Shorthand for the plane (1, 0, 0, 0)
* \return A plane with components (1, 0, 0, 0)
*
* \see MakeYZ
*/
template<typename T>
Plane<T> Plane<T>::YZ()
{
return Plane<T>(F(1.0), F(0.0), F(0.0), F(0.0));
Plane plane;
plane.MakeYZ();
return plane;
}
}
/*!
* \brief Output operator
* \return The stream
*
* \param out The stream
* \param plane The plane to output
*/
template<typename T>
std::ostream& operator<<(std::ostream& out, const Nz::Plane<T>& plane)
{