From f5b638957c32a2d3e11e504cf06d7368b2304d2f Mon Sep 17 00:00:00 2001 From: David Williams Date: Sat, 24 Nov 2012 23:36:46 +0100 Subject: [PATCH] More Region documentation. --- .../PolyVoxCore/include/PolyVoxCore/Region.h | 2 + library/PolyVoxCore/source/Region.cpp | 128 ++++++++++++++++++ 2 files changed, 130 insertions(+) diff --git a/library/PolyVoxCore/include/PolyVoxCore/Region.h b/library/PolyVoxCore/include/PolyVoxCore/Region.h index 6aff4b3c..65af8e65 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/Region.h +++ b/library/PolyVoxCore/include/PolyVoxCore/Region.h @@ -53,7 +53,9 @@ namespace PolyVox { public: + /// A Region with the lower corner set as low as possible and the upper corner set as high as possible. static const Region MaxRegion; + /// A Region with the lower corner set as high as possible and the upper corner set as low as possible. static const Region InvertedRegion; /// Constructor diff --git a/library/PolyVoxCore/source/Region.cpp b/library/PolyVoxCore/source/Region.cpp index 0479e918..1a2003c7 100644 --- a/library/PolyVoxCore/source/Region.cpp +++ b/library/PolyVoxCore/source/Region.cpp @@ -27,12 +27,19 @@ freely, subject to the following restrictions: namespace PolyVox { + //////////////////////////////////////////////////////////////////////////////// + //////////////////////////////////////////////////////////////////////////////// const Region Region::MaxRegion ( Vector3DInt32((std::numeric_limits::min)(), (std::numeric_limits::min)(), (std::numeric_limits::min)()), Vector3DInt32((std::numeric_limits::max)(), (std::numeric_limits::max)(), (std::numeric_limits::max)()) ); + //////////////////////////////////////////////////////////////////////////////// + /// This Region is not considered valid as defined by isValid(). It's main application + /// is to initialise a Region to this value and then() accumulate positions. The result + /// of this will be a Region which encompasses all positions specified. + //////////////////////////////////////////////////////////////////////////////// const Region Region::InvertedRegion ( Vector3DInt32((std::numeric_limits::max)(), (std::numeric_limits::max)(), (std::numeric_limits::max)()), @@ -109,6 +116,13 @@ namespace PolyVox return !(*this == rhs); } + //////////////////////////////////////////////////////////////////////////////// + /// The boundary value can be used to ensure a position is only considered to be inside + /// the Region if it is that far in in all directions. Also, the test is inclusive such + /// that positions lying exactly on the edge of the Region are considered to be inside it. + /// \param pos The position to test. + /// \param boundary The desired boundary value. + //////////////////////////////////////////////////////////////////////////////// bool Region::containsPoint(const Vector3DFloat& pos, float boundary) const { return (pos.getX() <= m_iUpperX - boundary) @@ -119,6 +133,13 @@ namespace PolyVox && (pos.getZ() >= m_iLowerZ + boundary); } + //////////////////////////////////////////////////////////////////////////////// + /// The boundary value can be used to ensure a position is only considered to be inside + /// the Region if it is that far in in all directions. Also, the test is inclusive such + /// that positions lying exactly on the edge of the Region are considered to be inside it. + /// \param pos The position to test. + /// \param boundary The desired boundary value. + //////////////////////////////////////////////////////////////////////////////// bool Region::containsPoint(const Vector3DInt32& pos, uint8_t boundary) const { return (pos.getX() <= m_iUpperX - boundary) @@ -129,42 +150,89 @@ namespace PolyVox && (pos.getZ() >= m_iLowerZ + boundary); } + //////////////////////////////////////////////////////////////////////////////// + /// The boundary value can be used to ensure a position is only considered to be inside + /// the Region if it is that far in in the 'x' direction. Also, the test is inclusive such + /// that positions lying exactly on the edge of the Region are considered to be inside it. + /// \param pos The position to test. + /// \param boundary The desired boundary value. + //////////////////////////////////////////////////////////////////////////////// bool Region::containsPointInX(float pos, float boundary) const { return (pos <= m_iUpperX - boundary) && (pos >= m_iLowerX + boundary); } + //////////////////////////////////////////////////////////////////////////////// + /// The boundary value can be used to ensure a position is only considered to be inside + /// the Region if it is that far in in the 'x' direction. Also, the test is inclusive such + /// that positions lying exactly on the edge of the Region are considered to be inside it. + /// \param pos The position to test. + /// \param boundary The desired boundary value. + //////////////////////////////////////////////////////////////////////////////// bool Region::containsPointInX(int32_t pos, uint8_t boundary) const { return (pos <= m_iUpperX - boundary) && (pos >= m_iLowerX + boundary); } + //////////////////////////////////////////////////////////////////////////////// + /// The boundary value can be used to ensure a position is only considered to be inside + /// the Region if it is that far in in the 'y' direction. Also, the test is inclusive such + /// that positions lying exactly on the edge of the Region are considered to be inside it. + /// \param pos The position to test. + /// \param boundary The desired boundary value. + //////////////////////////////////////////////////////////////////////////////// bool Region::containsPointInY(float pos, float boundary) const { return (pos <= m_iUpperY - boundary) && (pos >= m_iLowerY + boundary); } + //////////////////////////////////////////////////////////////////////////////// + /// The boundary value can be used to ensure a position is only considered to be inside + /// the Region if it is that far in in the 'y' direction. Also, the test is inclusive such + /// that positions lying exactly on the edge of the Region are considered to be inside it. + /// \param pos The position to test. + /// \param boundary The desired boundary value. + //////////////////////////////////////////////////////////////////////////////// bool Region::containsPointInY(int32_t pos, uint8_t boundary) const { return (pos <= m_iUpperY - boundary) && (pos >= m_iLowerY + boundary); } + //////////////////////////////////////////////////////////////////////////////// + /// The boundary value can be used to ensure a position is only considered to be inside + /// the Region if it is that far in in the 'z' direction. Also, the test is inclusive such + /// that positions lying exactly on the edge of the Region are considered to be inside it. + /// \param pos The position to test. + /// \param boundary The desired boundary value. + //////////////////////////////////////////////////////////////////////////////// bool Region::containsPointInZ(float pos, float boundary) const { return (pos <= m_iUpperZ - boundary) && (pos >= m_iLowerZ + boundary); } + //////////////////////////////////////////////////////////////////////////////// + /// The boundary value can be used to ensure a position is only considered to be inside + /// the Region if it is that far in in the 'z' direction. Also, the test is inclusive such + /// that positions lying exactly on the edge of the Region are considered to be inside it. + /// \param pos The position to test. + /// \param boundary The desired boundary value. + //////////////////////////////////////////////////////////////////////////////// bool Region::containsPointInZ(int32_t pos, uint8_t boundary) const { return (pos <= m_iUpperZ - boundary) && (pos >= m_iLowerZ + boundary); } + //////////////////////////////////////////////////////////////////////////////// + /// After calling this functions, the extents of this Region are given by the union + /// of this Region and the one it was cropped to. + /// \param other The Region to crop to. + //////////////////////////////////////////////////////////////////////////////// void Region::cropTo(const Region& other) { m_iLowerX = ((std::max)(m_iLowerX, other.m_iLowerX)); @@ -175,6 +243,11 @@ namespace PolyVox m_iUpperZ = ((std::min)(m_iUpperZ, other.m_iUpperZ)); } + //////////////////////////////////////////////////////////////////////////////// + /// The same amount of dilation is applied in all directions. Negative dilations + /// are possible but you should prefer the erode() function for clarity. + /// \param iAmount The amount to dilate by. + //////////////////////////////////////////////////////////////////////////////// void Region::dilate(int32_t iAmount) { m_iLowerX -= iAmount; @@ -186,6 +259,13 @@ namespace PolyVox m_iUpperZ += iAmount; } + //////////////////////////////////////////////////////////////////////////////// + /// The dilation can be specified seperatly for each direction. Negative dilations + /// are possible but you should prefer the erode() function for clarity. + /// \param iAmountX The amount to dilate by in 'x'. + /// \param iAmountY The amount to dilate by in 'y'. + /// \param iAmountZ The amount to dilate by in 'z'. + //////////////////////////////////////////////////////////////////////////////// void Region::dilate(int32_t iAmountX, int32_t iAmountY, int32_t iAmountZ) { m_iLowerX -= iAmountX; @@ -197,11 +277,21 @@ namespace PolyVox m_iUpperZ += iAmountZ; } + //////////////////////////////////////////////////////////////////////////////// + /// The dilation can be specified seperatly for each direction. Negative dilations + /// are possible but you should prefer the erode() function for clarity. + /// \param v3dAmount The amount to dilate by (one components for each direction). + //////////////////////////////////////////////////////////////////////////////// void Region::dilate(const Vector3DInt32& v3dAmount) { dilate(v3dAmount.getX(), v3dAmount.getY(), v3dAmount.getZ()); } + //////////////////////////////////////////////////////////////////////////////// + /// The same amount of erosion is applied in all directions. Negative erosions + /// are possible but you should prefer the dilate() function for clarity. + /// \param iAmount The amount to erode by. + //////////////////////////////////////////////////////////////////////////////// void Region::erode(int32_t iAmount) { m_iLowerX += iAmount; @@ -213,6 +303,13 @@ namespace PolyVox m_iUpperZ -= iAmount; } + //////////////////////////////////////////////////////////////////////////////// + /// The erosion can be specified seperatly for each direction. Negative erosions + /// are possible but you should prefer the dilate() function for clarity. + /// \param iAmountX The amount to erode by in 'x'. + /// \param iAmountY The amount to erode by in 'y'. + /// \param iAmountZ The amount to erode by in 'z'. + //////////////////////////////////////////////////////////////////////////////// void Region::erode(int32_t iAmountX, int32_t iAmountY, int32_t iAmountZ) { m_iLowerX += iAmountX; @@ -224,28 +321,48 @@ namespace PolyVox m_iUpperZ -= iAmountZ; } + //////////////////////////////////////////////////////////////////////////////// + /// The erosion can be specified seperatly for each direction. Negative erosions + /// are possible but you should prefer the dilate() function for clarity. + /// \param v3dAmount The amount to erode by (one components for each direction). + //////////////////////////////////////////////////////////////////////////////// void Region::erode(const Vector3DInt32& v3dAmount) { erode(v3dAmount.getX(), v3dAmount.getY(), v3dAmount.getZ()); } + //////////////////////////////////////////////////////////////////////////////// + //////////////////////////////////////////////////////////////////////////////// bool Region::isValid(void) { return (m_iUpperX >= m_iLowerX) && (m_iUpperY >= m_iLowerY) && (m_iUpperZ >= m_iLowerZ); } + //////////////////////////////////////////////////////////////////////////////// + /// \param iAmountX The amount to move the Region by in 'x'. + /// \param iAmountY The amount to move the Region by in 'y'. + /// \param iAmountZ The amount to move the Region by in 'z'. + //////////////////////////////////////////////////////////////////////////////// void Region::shift(int32_t iAmountX, int32_t iAmountY, int32_t iAmountZ) { shiftLowerCorner(iAmountX, iAmountY, iAmountZ); shiftUpperCorner(iAmountX, iAmountY, iAmountZ); } + //////////////////////////////////////////////////////////////////////////////// + /// \param v3dAmount The amount to move the Region by. + //////////////////////////////////////////////////////////////////////////////// void Region::shift(const Vector3DInt32& v3dAmount) { shiftLowerCorner(v3dAmount); shiftUpperCorner(v3dAmount); } + //////////////////////////////////////////////////////////////////////////////// + /// \param iAmountX The amount to move the lower corner by in 'x'. + /// \param iAmountY The amount to move the lower corner by in 'y'. + /// \param iAmountZ The amount to move the lower corner by in 'z'. + //////////////////////////////////////////////////////////////////////////////// void Region::shiftLowerCorner(int32_t iAmountX, int32_t iAmountY, int32_t iAmountZ) { m_iLowerX += iAmountX; @@ -253,11 +370,19 @@ namespace PolyVox m_iLowerZ += iAmountZ; } + //////////////////////////////////////////////////////////////////////////////// + /// \param v3dAmount The amount to move the lower corner by. + //////////////////////////////////////////////////////////////////////////////// void Region::shiftLowerCorner(const Vector3DInt32& v3dAmount) { shiftLowerCorner(v3dAmount.getX(), v3dAmount.getY(), v3dAmount.getZ()); } + //////////////////////////////////////////////////////////////////////////////// + /// \param iAmountX The amount to move the upper corner by in 'x'. + /// \param iAmountY The amount to move the upper corner by in 'y'. + /// \param iAmountZ The amount to move the upper corner by in 'z'. + //////////////////////////////////////////////////////////////////////////////// void Region::shiftUpperCorner(int32_t iAmountX, int32_t iAmountY, int32_t iAmountZ) { m_iUpperX += iAmountX; @@ -265,6 +390,9 @@ namespace PolyVox m_iUpperZ += iAmountZ; } + //////////////////////////////////////////////////////////////////////////////// + /// \param v3dAmount The amount to move the upper corner by. + //////////////////////////////////////////////////////////////////////////////// void Region::shiftUpperCorner(const Vector3DInt32& v3dAmount) { shiftUpperCorner(v3dAmount.getX(), v3dAmount.getY(), v3dAmount.getZ());