From e8b10fd2b94a3cf03bf6a20041d72dfe74f9d3e3 Mon Sep 17 00:00:00 2001 From: Matt Williams Date: Mon, 5 Jul 2010 15:57:24 +0000 Subject: [PATCH] Add and cleanup some of the API documentation. --- library/Doxyfile.in | 11 +++++----- library/PolyVoxCore/include/Array.h | 5 +++-- library/PolyVoxCore/include/Array.inl | 2 +- library/PolyVoxCore/include/Log.h | 5 ++++- library/PolyVoxCore/include/Vector.h | 26 +++++++++++++++++++++- library/PolyVoxCore/include/Vector.inl | 22 ------------------- library/PolyVoxCore/include/Volume.h | 28 ++++++++++++++++++------ library/PolyVoxCore/include/Volume.inl | 30 ++++++++++++++++++++++++++ 8 files changed, 89 insertions(+), 40 deletions(-) diff --git a/library/Doxyfile.in b/library/Doxyfile.in index 77e62464..aa58a061 100644 --- a/library/Doxyfile.in +++ b/library/Doxyfile.in @@ -224,7 +224,7 @@ OPTIMIZE_OUTPUT_VHDL = NO # func(std::string) {}). This also make the inheritance and collaboration # diagrams that involve STL classes more complete and accurate. -BUILTIN_STL_SUPPORT = NO +BUILTIN_STL_SUPPORT = YES # If you use Microsoft's C++/CLI language, you should set this option to YES to # enable parsing support. @@ -244,7 +244,7 @@ SIP_SUPPORT = NO # setting a simple type. If this is not the case, or you want to show the # methods anyway, you should set this option to NO. -IDL_PROPERTY_SUPPORT = YES +IDL_PROPERTY_SUPPORT = NO # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES, then doxygen will reuse the documentation of the first @@ -373,7 +373,7 @@ INTERNAL_DOCS = NO # in case and if your file system supports case sensitive file names. Windows # and Mac users are advised to set this option to NO. -CASE_SENSE_NAMES = YES +CASE_SENSE_NAMES = NO # If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen # will show members with their full class and namespace scopes in the @@ -642,8 +642,7 @@ RECURSIVE = YES # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. -EXCLUDE = ${PolyVoxCore_SOURCE_DIR}/include/boost \ - ${PolyVoxCore_SOURCE_DIR}/include/PolyVoxImpl \ +EXCLUDE = ${PolyVoxCore_SOURCE_DIR}/include/PolyVoxImpl \ ${PolyVoxCore_SOURCE_DIR}/source/PolyVoxImpl # The EXCLUDE_SYMLINKS tag can be used select whether or not files or @@ -909,7 +908,7 @@ DOCSET_BUNDLE_ID = org.thermite3d.PolyVox # Microsoft HTML help workshop to generate a compiled HTML help file (.chm) # of the generated HTML documentation. -GENERATE_HTMLHELP = YES +GENERATE_HTMLHELP = NO # If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can # be used to specify the file name of the resulting .chm file. You diff --git a/library/PolyVoxCore/include/Array.h b/library/PolyVoxCore/include/Array.h index f12dc985..b9cc5207 100644 --- a/library/PolyVoxCore/include/Array.h +++ b/library/PolyVoxCore/include/Array.h @@ -50,6 +50,7 @@ namespace PolyVox /// int height = 10; /// int depth = 20; /// + /// //Creates a 3D array of integers with dimensions 5x10x20 /// Array<3, int> myArray(ArraySizes(width)(height)(depth)); /// /// int ct = 1; @@ -66,13 +67,13 @@ namespace PolyVox /// } /// \endcode /// - /// Although the constructor and resize() function both take the required dimensions + /// Although the constructor and resize() functions both take the required dimensions /// as an array of ints, note that the ArraySizes class can be used to build this /// inline. This is a more convienient way of specifying these dimensions. /// /// Note also that this class has a private assignment operator and copy constructor /// in order to prevent copying. This is because a deep copy is a potentially slow - /// operation and can often be performed inadvertantly by functions such as std::swap, + /// operation and can often be performed inadvertently by functions such as std::swap, /// while a shallow copy introduces confusion over memory ownership. //////////////////////////////////////////////////////////////////////////////// template diff --git a/library/PolyVoxCore/include/Array.inl b/library/PolyVoxCore/include/Array.inl index 61164a75..ecf28e86 100644 --- a/library/PolyVoxCore/include/Array.inl +++ b/library/PolyVoxCore/include/Array.inl @@ -25,7 +25,7 @@ namespace PolyVox { //////////////////////////////////////////////////////////////////////////////// /// Creates an empty array with no elements. You will have to call resize() on this - /// array befire it can be used. + /// array before it can be used. //////////////////////////////////////////////////////////////////////////////// template Array::Array() diff --git a/library/PolyVoxCore/include/Log.h b/library/PolyVoxCore/include/Log.h index 3842315e..670918bc 100644 --- a/library/PolyVoxCore/include/Log.h +++ b/library/PolyVoxCore/include/Log.h @@ -34,9 +34,12 @@ freely, subject to the following restrictions: namespace PolyVox { + //////////////////////////////////////////////////////////////////////////////// + /// Log levels for filtering logging events + //////////////////////////////////////////////////////////////////////////////// enum LogSeverity { - LS_DEBUG, + LS_DEBUG, ///< Only displayed if it is a debug build LS_INFO, LS_WARN, LS_ERROR diff --git a/library/PolyVoxCore/include/Vector.h b/library/PolyVoxCore/include/Vector.h index cea5d820..d554453c 100644 --- a/library/PolyVoxCore/include/Vector.h +++ b/library/PolyVoxCore/include/Vector.h @@ -34,7 +34,31 @@ freely, subject to the following restrictions: namespace PolyVox { - ///Represents a vector in space. + /** + Represents a vector in space. + + This Vector class is templated on both size and data type. It is designed to be + generic but so far had only been tested with vectors of size 2 and 3. Also note + that some of the operations do not make sense with integer types, for example it + does not make conceptual sense to try and normalise an integer Vector. + + The elements of the Vector are accessed via the overloaded () operator which takes + an index indicating the element to fetch. They are set using the set() function which + takes an index indicating the element to set and a new value for that element. For + convienience, the functions getX(), setX(), getY(), setY(), getZ(), setZ(), getw() and setW() + do the same thing for the first 4 elements of the Vector. + + A variety of overloaded operators are also provided for comparison and arithmetic + operations. For most of these arithmetic operators only the unary versions are + documented below - however often binary versions are also generated by std::operators. + + Lastly, note that for convienience a set of typedefs are included for 2 and 3 dimensional + vectors with type float, double, int32_t, and uint32_t. They are used as follows: + + \code + Vector2DInt4 test(1,2); //Declares a 2 dimensional Vector of type int4. + \endcode + */ template class Vector { diff --git a/library/PolyVoxCore/include/Vector.inl b/library/PolyVoxCore/include/Vector.inl index c54f7c42..1476b0bf 100644 --- a/library/PolyVoxCore/include/Vector.inl +++ b/library/PolyVoxCore/include/Vector.inl @@ -30,28 +30,6 @@ freely, subject to the following restrictions: namespace PolyVox { - /** - This Vector class is templated on both size and data type. It is designed to be - generic but so far had only been tested with vectors of size 2 and 3. Also note - that some of the operations do not make sense with integer types, for example it - does not make conceptual sense to try and normalise an integer Vector. - - The elements of the Vector are accessed via the overloaded () operator which takes - an index indicating the element to fetch. They are set using the set() function which - takes an index indicating the element to set and a new value for that element. For - convienience, the functions getX(), setX(), getY(), setY(), getZ(), setZ, w() and setW() - do the same thing for the first 4 elements of the Vector. - - A variety of overloaded operators are also provided for comparison and arithmetic - operations. For most of these arithmetic operators only the unary versions are - documented below - however often binary versions are also generated by std::operators. - - Lastly, note that for convienience a set of typedefs are included for 2 and 3 dimentionsal - vectors with type float, double, int32_t, and uint32_t. They are used as follows: - - Vector2DInt4 test(1,2); //Declares a 2 dimensional Vector of type int4. - */ - #pragma region Constructors/Destructors //-------------------------- Constructors, etc --------------------------------- /** diff --git a/library/PolyVoxCore/include/Volume.h b/library/PolyVoxCore/include/Volume.h index 84bc55de..1c64dbb6 100644 --- a/library/PolyVoxCore/include/Volume.h +++ b/library/PolyVoxCore/include/Volume.h @@ -70,7 +70,7 @@ namespace PolyVox /// -# Homogeneous blocks (those which contain just a single voxel value) are easy to /// spot and fairly common becuase volumes often contain large homogeous regions. Any time /// you change the value of a voxel you have potentially made the block which contains - /// it homogeneous. PolyVox does not check the homogeneity immediatly as this would slow + /// it homogeneous. PolyVox does not check the homogeneity immediately as this would slow /// down the process of modifying voxels, but you can use the tidyUpMemory() function /// to check for and remove duplicate homogeneous regions whenever you have spare /// processing time. @@ -87,23 +87,33 @@ namespace PolyVox /// so we will not dwell on them here. /// /// Usage - /// Volumes are constructed by passing the desired width height and depth to the + /// Volumes are constructed by passing the desired width, height and depth to the /// constructor. Note that for speed reasons only values which are a power of two /// are permitted for these sidelengths. /// - /// Access to specific voxels is provided by the getVoxelAt() and setVoxelAt fuctions. + /// \code + /// Volume volData(g_uVolumeSideLength, g_uVolumeSideLength, g_uVolumeSideLength); + /// \endcode + /// + /// Access to specific voxels is provided by the getVoxelAt() and setVoxelAt() fuctions. /// Each of these has two forms so that voxels can be identified by integer triples - /// or by Vector3DUint16's. + /// or by Vector3DUint16%s. + /// + /// \code + /// volData.setVoxelAt(12, 186, 281, 3); + /// uint8_t voxelValue = volData.getVoxelAt(12, 186, 281); + /// //voxelValue is now 3 + /// \endcode /// /// The tidyUpMemory() function should normally be called after you first populate /// the volume with data, and then at periodic intervals as the volume is modified. - /// However, you don't actually have to call it at all. See the functions + /// However, you don't actually have to call it at all. See the function's /// documentation for further details. /// /// One further important point of note is that this class is templatised on the voxel /// type. This allows you to store volumes of data types you might not normally expect, - /// for example theOpenGL example 'abuses' this class to store a 3D grid of pointers. - /// However, it is not guarentted that all functionality works correctly with non-integer + /// for example the OpenGL example 'abuses' this class to store a 3D grid of pointers. + /// However, it is not guaranteed that all functionality works correctly with non-integer /// voxel types. //////////////////////////////////////////////////////////////////////////////// template @@ -132,10 +142,14 @@ namespace PolyVox uint16_t getShortestSideLength(void) const; ///Gets the length of the diagonal in voxels float getDiagonalLength(void) const; + ///Gets a voxel by x,y,z position VoxelType getVoxelAt(uint16_t uXPos, uint16_t uYPos, uint16_t uZPos, VoxelType tDefault = VoxelType()) const; + ///Gets a voxel by 3D vector position VoxelType getVoxelAt(const Vector3DUint16& v3dPos, VoxelType tDefault = VoxelType()) const; + ///Sets the voxel at an x,y,z position bool setVoxelAt(uint16_t uXPos, uint16_t uYPos, uint16_t uZPos, VoxelType tValue); + ///Sets the voxel at a 3D vector position bool setVoxelAt(const Vector3DUint16& v3dPos, VoxelType tValue); void tidyUpMemory(uint32_t uNoOfBlocksToProcess = (std::numeric_limits::max)()); diff --git a/library/PolyVoxCore/include/Volume.inl b/library/PolyVoxCore/include/Volume.inl index b0dbac50..c92030f6 100644 --- a/library/PolyVoxCore/include/Volume.inl +++ b/library/PolyVoxCore/include/Volume.inl @@ -223,6 +223,13 @@ namespace PolyVox return m_fDiagonalLength; } + //////////////////////////////////////////////////////////////////////////////// + /// \param uXPos the \c x position of the voxel + /// \param uYPos the \c y position of the voxel + /// \param uZPos the \c z position of the voxel + /// \param tDefault the voxel to be returned if the requested position is outside the volume + /// \return the voxel value + //////////////////////////////////////////////////////////////////////////////// template VoxelType Volume::getVoxelAt(uint16_t uXPos, uint16_t uYPos, uint16_t uZPos, VoxelType tDefault) const { @@ -253,6 +260,11 @@ namespace PolyVox } } + //////////////////////////////////////////////////////////////////////////////// + /// \param v3dPos the 3D position of the voxel + /// \param tDefault the voxel to be returned if the requested position is outside the volume + /// \return the voxel value + //////////////////////////////////////////////////////////////////////////////// template VoxelType Volume::getVoxelAt(const Vector3DUint16& v3dPos, VoxelType tDefault) const { @@ -261,6 +273,13 @@ namespace PolyVox #pragma endregion #pragma region Setters + //////////////////////////////////////////////////////////////////////////////// + /// \param uXPos the \c x position of the voxel + /// \param uYPos the \c y position of the voxel + /// \param uZPos the \c z position of the voxel + /// \param tValue the value to which the voxel will be set + /// \return whether the requested position is inside the volume + //////////////////////////////////////////////////////////////////////////////// template bool Volume::setVoxelAt(uint16_t uXPos, uint16_t uYPos, uint16_t uZPos, VoxelType tValue) { @@ -313,6 +332,11 @@ namespace PolyVox } } + //////////////////////////////////////////////////////////////////////////////// + /// \param v3dPos the 3D position of the voxel + /// \param tValue the value to which the voxel will be set + /// \return whether the requested position is inside the volume + //////////////////////////////////////////////////////////////////////////////// template bool Volume::setVoxelAt(const Vector3DUint16& v3dPos, VoxelType tValue) { @@ -321,6 +345,12 @@ namespace PolyVox #pragma endregion #pragma region Other + //////////////////////////////////////////////////////////////////////////////// + /// Clean up the memory usage of the volume. Checks for any blocks which are + /// homogeneous and flags them as such for faster processing and reduced memory + /// usage. + /// \param uNoOfBlocksToProcess the number of blocks to process + //////////////////////////////////////////////////////////////////////////////// template void Volume::tidyUpMemory(uint32_t uNoOfBlocksToProcess) {