From e32d47ed8dbc912b6ee4f8487a61f78243378a9e Mon Sep 17 00:00:00 2001 From: David Williams Date: Sat, 24 Nov 2012 23:02:26 +0100 Subject: [PATCH] Documentation of Region class. --- .../PolyVoxCore/include/PolyVoxCore/Region.h | 106 +++++++++++++++--- library/PolyVoxCore/source/Region.cpp | 41 +++++-- 2 files changed, 122 insertions(+), 25 deletions(-) diff --git a/library/PolyVoxCore/include/PolyVoxCore/Region.h b/library/PolyVoxCore/include/PolyVoxCore/Region.h index 13eff277..6aff4b3c 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/Region.h +++ b/library/PolyVoxCore/include/PolyVoxCore/Region.h @@ -86,22 +86,22 @@ namespace PolyVox /// Gets the position of the upper corner. Vector3DInt32 getUpperCorner(void) const; - /// Gets the width of the region measured in voxels + /// Gets the width of the region measured in voxels. int32_t getWidthInVoxels(void) const; - /// Gets the height of the region measured in voxels + /// Gets the height of the region measured in voxels. int32_t getHeightInVoxels(void) const; - /// Gets the depth of the region measured in voxels + /// Gets the depth of the region measured in voxels. int32_t getDepthInVoxels(void) const; - /// Gets the dimensions of the region measured in voxels + /// Gets the dimensions of the region measured in voxels. Vector3DInt32 getDimensionsInVoxels(void) const; - /// Gets the width of the region measured in cells + /// Gets the width of the region measured in cells. int32_t getWidthInCells(void) const; - /// Gets the height of the region measured in cells + /// Gets the height of the region measured in cells. int32_t getHeightInCells(void) const; - /// Gets the depth of the region measured in cells + /// Gets the depth of the region measured in cells. int32_t getDepthInCells(void) const; - /// Gets the dimensions of the region measured in cells + /// Gets the dimensions of the region measured in cells. Vector3DInt32 getDimensionsInCells(void) const; /// Sets the 'x' position of the lower corner. @@ -186,116 +186,193 @@ namespace PolyVox // 'inline' keyword is used for the definition rather than the declaration. // See also http://www.parashift.com/c++-faq-lite/inline-functions.html + //////////////////////////////////////////////////////////////////////////////// + /// \return The 'x' position of the lower corner. + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getLowerX(void) const { return m_iLowerX; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The 'y' position of the lower corner. + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getLowerY(void) const { return m_iLowerY; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The 'z' position of the lower corner. + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getLowerZ(void) const { return m_iLowerZ; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The 'x' position of the upper corner. + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getUpperX(void) const { return m_iUpperX; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The 'y' position of the upper corner. + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getUpperY(void) const { return m_iUpperY; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The 'z' position of the upper corner. + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getUpperZ(void) const { return m_iUpperZ; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The position of the lower corner. + //////////////////////////////////////////////////////////////////////////////// inline Vector3DInt32 Region::getLowerCorner(void) const { return Vector3DInt32(m_iLowerX, m_iLowerY, m_iLowerZ); } + //////////////////////////////////////////////////////////////////////////////// + /// \return The position of the upper corner. + //////////////////////////////////////////////////////////////////////////////// inline Vector3DInt32 Region::getUpperCorner(void) const { return Vector3DInt32(m_iUpperX, m_iUpperY, m_iUpperZ); } + //////////////////////////////////////////////////////////////////////////////// + /// \return The width of the region measured in voxels. + /// \sa getWidthInCells() + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getWidthInVoxels(void) const { return getWidthInCells() + 1; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The height of the region measured in voxels. + /// \sa getHeightInCells() + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getHeightInVoxels(void) const { return getHeightInCells() + 1; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The depth of the region measured in voxels. + /// \sa getDepthInCells() + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getDepthInVoxels(void) const { return getDepthInCells() + 1; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The dimensions of the region measured in voxels. + /// \sa getDimensionsInCells() + //////////////////////////////////////////////////////////////////////////////// inline Vector3DInt32 Region::getDimensionsInVoxels(void) const { return getDimensionsInCells() + Vector3DInt32(1, 1, 1); } + //////////////////////////////////////////////////////////////////////////////// + /// \return The width of the region measured in cells. + /// \sa getWidthInVoxels() + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getWidthInCells(void) const { return m_iUpperX - m_iLowerX; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The height of the region measured in cells. + /// \sa getHeightInVoxels() + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getHeightInCells(void) const { return m_iUpperY - m_iLowerY; } - inline Vector3DInt32 Region::getDimensionsInCells(void) const - { - return Vector3DInt32(getWidthInCells(), getHeightInCells(), getDepthInCells()); - } - + //////////////////////////////////////////////////////////////////////////////// + /// \return The depth of the region measured in cells. + /// \sa getDepthInVoxels() + //////////////////////////////////////////////////////////////////////////////// inline int32_t Region::getDepthInCells(void) const { return m_iUpperZ - m_iLowerZ; } + //////////////////////////////////////////////////////////////////////////////// + /// \return The dimensions of the region measured in cells. + /// \sa getDimensionsInVoxels() + //////////////////////////////////////////////////////////////////////////////// + inline Vector3DInt32 Region::getDimensionsInCells(void) const + { + return Vector3DInt32(getWidthInCells(), getHeightInCells(), getDepthInCells()); + } + + //////////////////////////////////////////////////////////////////////////////// + /// \param iX The new 'x' position of the lower corner. + //////////////////////////////////////////////////////////////////////////////// inline void Region::setLowerX(int32_t iX) { m_iLowerX = iX; } + //////////////////////////////////////////////////////////////////////////////// + /// \param iY The new 'y' position of the lower corner. + //////////////////////////////////////////////////////////////////////////////// inline void Region::setLowerY(int32_t iY) { m_iLowerY = iY; } + //////////////////////////////////////////////////////////////////////////////// + /// \param iZ The new 'z' position of the lower corner. + //////////////////////////////////////////////////////////////////////////////// inline void Region::setLowerZ(int32_t iZ) { m_iLowerZ = iZ; } + //////////////////////////////////////////////////////////////////////////////// + /// \param iX The new 'x' position of the upper corner. + //////////////////////////////////////////////////////////////////////////////// inline void Region::setUpperX(int32_t iX) { m_iUpperX = iX; } + //////////////////////////////////////////////////////////////////////////////// + /// \param iY The new 'y' position of the upper corner. + //////////////////////////////////////////////////////////////////////////////// inline void Region::setUpperY(int32_t iY) { m_iUpperY = iY; } + //////////////////////////////////////////////////////////////////////////////// + /// \param iZ The new 'z' position of the upper corner. + //////////////////////////////////////////////////////////////////////////////// inline void Region::setUpperZ(int32_t iZ) { m_iUpperZ = iZ; } + //////////////////////////////////////////////////////////////////////////////// + /// \param v3dLowerCorner The new position of the lower corner. + //////////////////////////////////////////////////////////////////////////////// inline void Region::setLowerCorner(const Vector3DInt32& v3dLowerCorner) { m_iLowerX = v3dLowerCorner.getX(); @@ -303,6 +380,9 @@ namespace PolyVox m_iLowerZ = v3dLowerCorner.getZ(); } + //////////////////////////////////////////////////////////////////////////////// + /// \param v3dUpperCorner The new position of the upper corner. + //////////////////////////////////////////////////////////////////////////////// inline void Region::setUpperCorner(const Vector3DInt32& v3dUpperCorner) { m_iUpperX = v3dUpperCorner.getX(); diff --git a/library/PolyVoxCore/source/Region.cpp b/library/PolyVoxCore/source/Region.cpp index c202d71e..0479e918 100644 --- a/library/PolyVoxCore/source/Region.cpp +++ b/library/PolyVoxCore/source/Region.cpp @@ -39,6 +39,9 @@ namespace PolyVox Vector3DInt32((std::numeric_limits::min)(), (std::numeric_limits::min)(), (std::numeric_limits::min)()) ); + //////////////////////////////////////////////////////////////////////////////// + /// Constructs a Region and clears all extents to zero. + //////////////////////////////////////////////////////////////////////////////// Region::Region() :m_iLowerX(0) ,m_iLowerY(0) @@ -49,6 +52,11 @@ namespace PolyVox { } + //////////////////////////////////////////////////////////////////////////////// + /// Constructs a Region and sets the lower and upper corners to the specified values. + /// \param v3dLowerCorner The desired lower corner of the Region. + /// \param v3dUpperCorner The desired upper corner of the Region. + //////////////////////////////////////////////////////////////////////////////// Region::Region(const Vector3DInt32& v3dLowerCorner, const Vector3DInt32& v3dUpperCorner) :m_iLowerX(v3dLowerCorner.getX()) ,m_iLowerY(v3dLowerCorner.getY()) @@ -59,6 +67,15 @@ namespace PolyVox { } + //////////////////////////////////////////////////////////////////////////////// + /// Constructs a Region and sets the extents to the specified values. + /// \param iLowerX The desired lower 'x' extent of the Region. + /// \param iLowerY The desired lower 'y' extent of the Region. + /// \param iLowerZ The desired lower 'z' extent of the Region. + /// \param iUpperX The desired upper 'x' extent of the Region. + /// \param iUpperY The desired upper 'y' extent of the Region. + /// \param iUpperZ The desired upper 'z' extent of the Region. + //////////////////////////////////////////////////////////////////////////////// Region::Region(int32_t iLowerX, int32_t iLowerY, int32_t iLowerZ, int32_t iUpperX, int32_t iUpperY, int32_t iUpperZ) :m_iLowerX(iLowerX) ,m_iLowerY(iLowerY) @@ -69,24 +86,24 @@ namespace PolyVox { } - /** - Checks whether two Regions are equal. - \param rhs The Region to compare to. - \return true if the Regions match. - \see operator!= - */ + //////////////////////////////////////////////////////////////////////////////// + /// Two regions are considered equal if all their extents match. + /// \param rhs The Region to compare to. + /// \return true if the Regions match. + /// \sa operator!= + //////////////////////////////////////////////////////////////////////////////// bool Region::operator==(const Region& rhs) const { return ((m_iLowerX == rhs.m_iLowerX) && (m_iLowerY == rhs.m_iLowerY) && (m_iLowerZ == rhs.m_iLowerZ) && (m_iUpperX == rhs.m_iUpperX) && (m_iUpperY == rhs.m_iUpperY) && (m_iUpperZ == rhs.m_iUpperZ)); } - /** - Checks whether two Regions are not equal. - \param rhs The Region to compare to. - \return true if the Regions do not match. - \see operator== - */ + //////////////////////////////////////////////////////////////////////////////// + /// Two regions are considered different if any of their extents differ. + /// \param rhs The Region to compare to. + /// \return true if the Regions are different. + /// \sa operator== + //////////////////////////////////////////////////////////////////////////////// bool Region::operator!=(const Region& rhs) const { return !(*this == rhs);