From 40d3d6b235b090821f00244e554fd82dec02691b Mon Sep 17 00:00:00 2001 From: Gawaboumga Date: Wed, 30 Dec 2015 15:32:59 +0100 Subject: [PATCH] Documentation for OrientedBox Former-commit-id: 77f7c82d7ca16348774ccdf1d4e98432710a585a --- include/Nazara/Math/OrientedBox.hpp | 4 +- include/Nazara/Math/OrientedBox.inl | 222 ++++++++++++++++++++++++++-- 2 files changed, 215 insertions(+), 11 deletions(-) diff --git a/include/Nazara/Math/OrientedBox.hpp b/include/Nazara/Math/OrientedBox.hpp index 0b579fcba..627f4cbe9 100644 --- a/include/Nazara/Math/OrientedBox.hpp +++ b/include/Nazara/Math/OrientedBox.hpp @@ -43,8 +43,8 @@ namespace Nz void Update(const Matrix4& transformMatrix); void Update(const Vector3& transformMatrix); - operator Vector3*(); - operator const Vector3*() const; + operator Vector3* (); + operator const Vector3* () const; Vector3& operator()(unsigned int i); Vector3 operator()(unsigned int i) const; diff --git a/include/Nazara/Math/OrientedBox.inl b/include/Nazara/Math/OrientedBox.inl index a54cdae79..c1668118c 100644 --- a/include/Nazara/Math/OrientedBox.inl +++ b/include/Nazara/Math/OrientedBox.inl @@ -13,24 +13,62 @@ namespace Nz { + /*! + * \class Nz::OrientedBox + * \brief Math class that represents an oriented three dimensional box + * + * \remark You need to call Update not to have undefined behaviour + */ + + /*! + * \brief Constructs a OrientedBox object from its position and sizes + * + * \param X X component of position + * \param Y Y component of position + * \param Z Z component of position + * \param Width Width of the box (following X) + * \param Height Height of the box (following Y) + * \param Depth Depth of the box (following Z) + */ + template OrientedBox::OrientedBox(T X, T Y, T Z, T Width, T Height, T Depth) { Set(X, Y, Z, Width, Height, Depth); } + /*! + * \brief Constructs a OrientedBox object from a box + * + * \param box Box object + */ + template OrientedBox::OrientedBox(const Box& box) { Set(box); } + /*! + * \brief Constructs a OrientedBox object from two vectors representing point of the space + * (X, Y, Z) will be the components minimum of the two vectors and the (width, height, depth) will be the components maximum - minimum + * + * \param vec1 First point + * \param vec2 Second point + */ + template OrientedBox::OrientedBox(const Vector3& vec1, const Vector3& vec2) { Set(vec1, vec2); } + /*! + * \brief Constructs a OrientedBox object from another type of OrientedBox + * + * \param orientedBox OrientedBox of type U to convert to type T + */ + template template OrientedBox::OrientedBox(const OrientedBox& orientedBox) @@ -38,6 +76,15 @@ namespace Nz Set(orientedBox); } + /*! + * \brief Gets the Vector3 for the corner + * \return The position of the corner of the oriented box according to enum BoxCorner + * + * \param corner Enumeration of type BoxCorner + * + * \remark If enumeration is not defined in BoxCorner, a NazaraError is thrown and a Vector3 uninitialised is returned + */ + template const Vector3& OrientedBox::GetCorner(BoxCorner corner) const { @@ -54,12 +101,24 @@ namespace Nz return m_corners[corner]; } + /*! + * \brief Checks whether this oriented box is valid + * \return true if the oriented box has a strictly positive width, height and depth + */ + template bool OrientedBox::IsValid() const { return localBox.IsValid(); } + /*! + * \brief Makes the oriented box position (0, 0, 0) and lengths (0, 0, 0) + * \return A reference to this oriented box with position (0, 0, 0) and lengths (0, 0, 0) + * + * \see Zero + */ + template OrientedBox& OrientedBox::MakeZero() { @@ -68,6 +127,18 @@ namespace Nz return *this; } + /*! + * \brief Sets the components of the oriented box + * \return A reference to this oriented box + * + * \param X X position + * \param Y Y position + * \param Z Z position + * \param Width Width of the oriented box (following X) + * \param Height Height of the oriented box (following Y) + * \param Depth Depth of the oriented box (following Z) + */ + template OrientedBox& OrientedBox::Set(T X, T Y, T Z, T Width, T Height, T Depth) { @@ -76,6 +147,13 @@ namespace Nz return *this; } + /*! + * \brief Sets the components of the oriented box from a box + * \return A reference to this oriented box + * + * \param box Box object + */ + template OrientedBox& OrientedBox::Set(const Box& box) { @@ -84,6 +162,13 @@ namespace Nz return *this; } + /*! + * \brief Sets the components of the oriented box with components from another + * \return A reference to this oriented box + * + * \param orientedBox The other OrientedBox + */ + template OrientedBox& OrientedBox::Set(const OrientedBox& orientedBox) { @@ -92,6 +177,14 @@ namespace Nz return *this; } + /*! + * \brief Sets a OrientedBox object from two vectors representing point of the space + * (X, Y, Z) will be the components minimum of the two vectors and the (width, height, depth) will be the components maximum - minimum + * + * \param vec1 First point + * \param vec2 Second point + */ + template OrientedBox& OrientedBox::Set(const Vector3& vec1, const Vector3& vec2) { @@ -100,6 +193,13 @@ namespace Nz return *this; } + /*! + * \brief Sets the components of the orientedBox from another type of OrientedBox + * \return A reference to this orientedBox + * + * \param orientedBox OrientedBox of type U to convert its components + */ + template template OrientedBox& OrientedBox::Set(const OrientedBox& orientedBox) @@ -112,21 +212,32 @@ namespace Nz return *this; } + /*! + * \brief Gives a string representation + * \return A string representation of the object: "OrientedBox(...)" + */ + template String OrientedBox::ToString() const { StringStream ss; return ss << "OrientedBox(FLB: " << m_corners[BoxCorner_FarLeftBottom].ToString() << "\n" - << " FLT: " << m_corners[BoxCorner_FarLeftTop].ToString() << "\n" - << " FRB: " << m_corners[BoxCorner_FarRightBottom].ToString() << "\n" - << " FRT: " << m_corners[BoxCorner_FarRightTop].ToString() << "\n" - << " NLB: " << m_corners[BoxCorner_NearLeftBottom].ToString() << "\n" - << " NLT: " << m_corners[BoxCorner_NearLeftTop].ToString() << "\n" - << " NRB: " << m_corners[BoxCorner_NearRightBottom].ToString() << "\n" - << " NRT: " << m_corners[BoxCorner_NearRightTop].ToString() << ")\n"; + << " FLT: " << m_corners[BoxCorner_FarLeftTop].ToString() << "\n" + << " FRB: " << m_corners[BoxCorner_FarRightBottom].ToString() << "\n" + << " FRT: " << m_corners[BoxCorner_FarRightTop].ToString() << "\n" + << " NLB: " << m_corners[BoxCorner_NearLeftBottom].ToString() << "\n" + << " NLT: " << m_corners[BoxCorner_NearLeftTop].ToString() << "\n" + << " NRB: " << m_corners[BoxCorner_NearRightBottom].ToString() << "\n" + << " NRT: " << m_corners[BoxCorner_NearRightTop].ToString() << ")\n"; } + /*! + * \brief Updates the corners of the box + * + * \param transformMatrix Matrix4 which represents the transformation to apply on the local box + */ + template void OrientedBox::Update(const Matrix4& transformMatrix) { @@ -134,6 +245,12 @@ namespace Nz m_corners[i] = transformMatrix.Transform(localBox.GetCorner(static_cast(i))); } + /*! + * \brief Updates the corners of the box + * + * \param translation Vector3 which represents the translation to apply on the local box + */ + template void OrientedBox::Update(const Vector3& translation) { @@ -141,18 +258,40 @@ namespace Nz m_corners[i] = localBox.GetCorner(static_cast(i)) + translation; } + /*! + * \brief Converts oriented box to pointer of Vector3 to its own corners + * \return A pointer to the own corners + * + * \remark Access to index greather than BoxCorner_Max is undefined behavior + */ + template - OrientedBox::operator Vector3*() + OrientedBox::operator Vector3* () { return &m_corners[0]; } + /*! + * \brief Converts oriented box to pointer of Vector3 to its own corners + * \return A const pointer to the own corners + * + * \remark Access to index greather than BoxCorner_Max is undefined behavior + */ + template - OrientedBox::operator const Vector3*() const + OrientedBox::operator const Vector3* () const { return &m_corners[0]; } + /*! + * \brief Gets the ith corner of the oriented box + * \return A reference to this corner + * + * \remark Produce a NazaraError if you try to access to index greather than BoxCorner_Max with NAZARA_MATH_SAFE defined. If not, it is undefined behaviour + * \throw std::out_of_range if NAZARA_MATH_SAFE is defined and you try to acces to index greather than BoxCorner_Max + */ + template Vector3& OrientedBox::operator()(unsigned int i) { @@ -170,6 +309,14 @@ namespace Nz return m_corners[i]; } + /*! + * \brief Gets the ith corner of the oriented box + * \return A reference to this corner + * + * \remark Produce a NazaraError if you try to access to index greather than BoxCorner_Max with NAZARA_MATH_SAFE defined. If not, it is undefined behaviour + * \throw std::out_of_range if NAZARA_MATH_SAFE is defined and you try to acces to index greather than BoxCorner_Max + */ + template Vector3 OrientedBox::operator()(unsigned int i) const { @@ -187,6 +334,13 @@ namespace Nz return m_corners[i]; } + /*! + * \brief Multiplies the lengths with the scalar + * \return A OrientedBox where the position is the same and width, height and depth are the product of the old width, height and depth and the scalar + * + * \param scale The scalar to multiply width, height and depth with + */ + template OrientedBox OrientedBox::operator*(T scalar) const { @@ -196,6 +350,13 @@ namespace Nz return box; } + /*! + * \brief Multiplies the lengths of this oriented box with the scalar + * \return A reference to this oriented box where lengths are the product of these lengths and the scalar + * + * \param scalar The scalar to multiply width, height and depth with + */ + template OrientedBox& OrientedBox::operator*=(T scalar) { @@ -204,18 +365,46 @@ namespace Nz return *this; } + /*! + * \brief Compares the oriented box to other one + * \return true if the two oriented boxes are the same + * + * \param box Other oriented box to compare with + */ + template bool OrientedBox::operator==(const OrientedBox& box) const { return localBox == box.localBox; } + /*! + * \brief Compares the oriented box to other one + * \return false if the two oriented boxes are the same + * + * \param box Other oriented box to compare with + */ + template bool OrientedBox::operator!=(const OrientedBox& box) const { return !operator==(box); } + /*! + * \brief Interpolates the oriented box to other one with a factor of interpolation + * \return A new oriented box which is the interpolation of two oriented boxes + * + * \param from Initial oriented box + * \param to Target oriented box + * \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 Zero() is returned + * + * \see Lerp + */ + template OrientedBox OrientedBox::Lerp(const OrientedBox& from, const OrientedBox& to, T interpolation) { @@ -225,6 +414,13 @@ namespace Nz return orientedBox; } + /*! + * \brief Shorthand for the oriented box (0, 0, 0, 0, 0, 0) + * \return A oriented box with position (0, 0, 0) and lengths (0, 0, 0) + * + * \see MakeZero + */ + template OrientedBox OrientedBox::Zero() { @@ -235,6 +431,14 @@ namespace Nz } } +/*! +* \brief Output operator +* \return The stream +* +* \param out The stream +* \param orientedBox The orientedBox to output +*/ + template std::ostream& operator<<(std::ostream& out, const Nz::OrientedBox& orientedBox) {