diff --git a/include/Nazara/Math/Plane.hpp b/include/Nazara/Math/Plane.hpp index cd0856aa5..70bc06051 100644 --- a/include/Nazara/Math/Plane.hpp +++ b/include/Nazara/Math/Plane.hpp @@ -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& point) const; T Distance(T x, T y, T z) const; + T Distance(const Vector3& point) const; + + Plane& MakeXY(); + Plane& MakeXZ(); + Plane& MakeYZ(); Plane& Set(T normalX, T normalY, T normalZ, T Distance); Plane& Set(const T plane[4]); diff --git a/include/Nazara/Math/Plane.inl b/include/Nazara/Math/Plane.inl index fceeb9cc3..9b29ab48a 100644 --- a/include/Nazara/Math/Plane.inl +++ b/include/Nazara/Math/Plane.inl @@ -11,36 +11,88 @@ namespace Nz { + /*! + * \class Nz::Vector4 + * \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 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 Plane::Plane(T normalX, T normalY, T normalZ, T D) { Set(normalX, normalY, normalZ, D); } + /*! + * \brief Constructs a Plane 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 Plane::Plane(const T plane[4]) { Set(plane); } + /*! + * \brief Constructs a Plane object from a normal and a distance + * + * \param Normal normal of the vector + * \param D Distance to origin + */ + template Plane::Plane(const Vector3& Normal, T D) { Set(Normal, D); } + /*! + * \brief Constructs a Plane object from a normal and a point + * + * \param Normal Normal of the plane + * \param point Point which verifies the equation of the plane + */ + template Plane::Plane(const Vector3& Normal, const Vector3& point) { Set(Normal, point); } + /*! + * \brief Constructs a Plane 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 Plane::Plane(const Vector3& point1, const Vector3& point2, const Vector3& point3) { Set(point1, point2, point3); } + /*! + * \brief Constructs a Plane object from another type of Plane + * + * \param plane Plane of type U to convert to type T + */ + template template Plane::Plane(const Plane& plane) @@ -48,11 +100,18 @@ namespace Nz Set(plane); } - template - T Plane::Distance(const Vector3& 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 T Plane::Distance(T x, T y, T z) const @@ -60,6 +119,72 @@ namespace Nz return Distance(Vector3(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 + T Plane::Distance(const Vector3& 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 + Plane& Plane::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 + Plane& Plane::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 + Plane& Plane::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 Plane& Plane::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 Plane& Plane::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 Plane& Plane::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 Plane& Plane::Set(const Vector3& 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 Plane& Plane::Set(const Vector3& Normal, const Vector3& 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 Plane& Plane::Set(const Vector3& point1, const Vector3& point2, const Vector3& 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 template Plane& Plane::Set(const Plane& 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 String Plane::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 bool Plane::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 bool Plane::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 Plane Plane::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::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 Plane Plane::XY() { - return Plane(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 Plane Plane::XZ() { - return Plane(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 Plane Plane::YZ() { - return Plane(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 std::ostream& operator<<(std::ostream& out, const Nz::Plane& plane) {