Changes to comment formatting for Doxygen.

library/PolyVoxCore/include/Volume.h

@@ -37,72 +37,72 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 namespace PolyVox
 {
 	///The Volume class provides a memory efficient method of storing voxel data while also allowing fast access and modification.
-	/*******************************************************************************
+	////////////////////////////////////////////////////////////////////////////////
-	A Volume is essentially a '3D image' in which each element (voxel) is identified
+	/// A Volume is essentially a '3D image' in which each element (voxel) is identified
-	by a three dimensional (x,y,z) coordinate, rather than the two dimensional (x,y)
+	/// by a three dimensional (x,y,z) coordinate, rather than the two dimensional (x,y)
-	coordinate which is used to identify an element (pixel) in a normal image. Within
+	/// coordinate which is used to identify an element (pixel) in a normal image. Within
-	PolyVox, the Volume class is used to store and manipulate our data before we extract 
+	/// PolyVox, the Volume class is used to store and manipulate our data before we extract 
-	our SurfacePatch's from it.
+	/// our SurfacePatch's from it.
-
+	/// 
-	<b>Data Representaion - feel free to skip</b>
+	/// <b>Data Representaion - feel free to skip</b>
-	If stored carelessly, volume data can take up a huge amount of memory. For example, a
+	/// If stored carelessly, volume data can take up a huge amount of memory. For example, a
-	volume of dimensions 1024x1024x1024 with 1 byte per voxel will require 1GB of memory
+	/// volume of dimensions 1024x1024x1024 with 1 byte per voxel will require 1GB of memory
-	if stored in an uncompressed form. Natuarally our Volume class is much more efficient
+	/// if stored in an uncompressed form. Natuarally our Volume class is much more efficient
-	than this and it is worth understanding (at least at a high level) the approach
+	/// than this and it is worth understanding (at least at a high level) the approach
-	which is used.
+	/// which is used.
-
+	/// 
-	Essentially, the Volume class stores its data as a collection of blocks. Each 
+	/// Essentially, the Volume class stores its data as a collection of blocks. Each 
-	of these block is much smaller than the whole volume, for example a typical size
+	/// of these block is much smaller than the whole volume, for example a typical size
-	might be 32x32x32 voxels (though is is configurable by the user). In this case,
+	/// might be 32x32x32 voxels (though is is configurable by the user). In this case,
-	a 256x512x1024 volume would contain 8x16x32 = 4096 blocks. However, it is unlikely that
+	/// a 256x512x1024 volume would contain 8x16x32 = 4096 blocks. However, it is unlikely that
-	all these blocks actually have to be stored because usually there are duplicates
+	/// all these blocks actually have to be stored because usually there are duplicates
-	in which case common data can be shared.
+	/// in which case common data can be shared.
-
+	/// 
-	Identifying duplicate blocks is in general a difficult task which involves looking at pairs
+	/// Identifying duplicate blocks is in general a difficult task which involves looking at pairs
-	of blocks and comparing all the voxels. This is a time consuming task which is not amiable 
+	/// of blocks and comparing all the voxels. This is a time consuming task which is not amiable 
-	to being performed when the volume is being modified in real time. However, there are two
+	/// to being performed when the volume is being modified in real time. However, there are two
-	specific scenarios which are easily spotted and which PolyVox uses to identify block
+	/// specific scenarios which are easily spotted and which PolyVox uses to identify block
-	sharing opportunities.
+	/// sharing opportunities.
-
+	/// 
-	-# Homogeneous blocks (those which contain just a single voxel value) are easy to
+	/// -# 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
+	/// 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
+	/// 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 immediatly as this would slow
-	down the process of modifying voxels, but you can use the tidyUpMemory() function
+	/// 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
+	/// to check for and remove duplicate homogeneous regions whenever you have spare
-	processing time.
+	/// processing time.
-
+	/// 
-	-# Copying a volume naturally means that all the voxels in the second voluem are
+	/// -# Copying a volume naturally means that all the voxels in the second voluem are
-	the same as the first. Therefore volume copying is a relatively fast operation in
+	/// the same as the first. Therefore volume copying is a relatively fast operation in
-	which all the blocks in the second volume simply reference the first volume. Future
+	/// which all the blocks in the second volume simply reference the first volume. Future
-	modifications to either volume will, of course, cause the blocks to become unshared.
+	/// modifications to either volume will, of course, cause the blocks to become unshared.
-
+	/// 
-	Other advantages of breaking the volume down into blocks include enhancing data locality
+	/// Other advantages of breaking the volume down into blocks include enhancing data locality
-	(i.e. voxels which are spatially near to each other are also likely to be near in
+	/// (i.e. voxels which are spatially near to each other are also likely to be near in
-	memory) and the ability to load larger volumes as no large contiguous areas of
+	/// memory) and the ability to load larger volumes as no large contiguous areas of
-	memory are needed. However, these advantages are more transparent to user code
+	/// memory are needed. However, these advantages are more transparent to user code
-	so we will not dwell on them here.
+	/// so we will not dwell on them here.
-
+	/// 
-	<b>Usage</b>
+	/// <b>Usage</b>
-	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
+	/// constructor. Note that for speed reasons only values which are a power of two
-	are permitted for these sidelengths.
+	/// are permitted for these sidelengths.
-
+	/// 
-	Access to specific voxels is provided by the getVoxelAt() and setVoxelAt fuctions.
+	/// 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
+	/// Each of these has two forms so that voxels can be identified by integer triples
-	or by Vector3DUint16's.
+	/// or by Vector3DUint16's.
-
+	/// 
-	The tidyUpMemory() function should normally be called after you first populate
+	/// 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.
+	/// the volume with data, and then at periodic intervals as the volume is modified.
-	However, you don't actually <i>have</i> to call it at all. See the functions
+	/// However, you don't actually <i>have</i> to call it at all. See the functions
-	documentation for further details.
+	/// documentation for further details.
-
+	/// 
-	One further important point of note is that this class is templatised on the voxel
+	/// 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,
+	/// 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.
+	/// 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
+	/// However, it is not guarentted that all functionality works correctly with non-integer
-	voxel types.
+	/// voxel types.
-	*******************************************************************************/
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	class Volume
 	{

library/PolyVoxCore/include/Volume.inl

@@ -35,20 +35,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 namespace PolyVox
 {
 	#pragma region Constructors/Destructors
-	/*******************************************************************************
+	////////////////////////////////////////////////////////////////////////////////
-	Builds a volume of the desired dimensions
+	/// Builds a volume of the desired dimensions
-	\param uWidth The desired width in voxels. This must be a power of two.
+	/// \param uWidth The desired width in voxels. This must be a power of two.
-	\param uHeight The desired height in voxels. This must be a power of two.
+	/// \param uHeight The desired height in voxels. This must be a power of two.
-	\param uDepth The desired depth in voxels. This must be a power of two.
+	/// \param uDepth The desired depth in voxels. This must be a power of two.
-	\param uBlockSideLength The size of the blocks which make up the volume. Small
+	/// \param uBlockSideLength The size of the blocks which make up the volume. Small
-	blocks are more likely to be homogeneous (so more easily shared) and have better
+	/// blocks are more likely to be homogeneous (so more easily shared) and have better
-	cache behaviour. However, there is a memory overhead per block so if they are
+	/// cache behaviour. However, there is a memory overhead per block so if they are
-	not shared it could actually be less efficient (this will depend on the data).
+	/// not shared it could actually be less efficient (this will depend on the data).
-	The size of the volume may also be a factor when choosing block size. Specifying
+	/// The size of the volume may also be a factor when choosing block size. Specifying
-	'0' for	the block side length will cause the blocks to be as large as possible,
+	/// '0' for	the block side length will cause the blocks to be as large as possible,
-	which will basically be the length of the shortest side. Accept the default if
+	/// which will basically be the length of the shortest side. Accept the default if
-	you are not sure what to choose here.
+	/// you are not sure what to choose here.
-	*******************************************************************************/
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	Volume<VoxelType>::Volume(uint16_t uWidth, uint16_t uHeight, uint16_t uDepth, uint16_t uBlockSideLength)
 		:m_pBlocks(0)
@@ -130,9 +130,9 @@ namespace PolyVox
 		m_fDiagonalLength = sqrtf(static_cast<float>(m_uWidth * m_uWidth + m_uHeight * m_uHeight + m_uDepth * m_uDepth));
 	}
 
-	/*******************************************************************************
+	////////////////////////////////////////////////////////////////////////////////
-	Destroys the volume and frees any blocks which are not in use by other volumes.
+	/// Destroys the volume and frees any blocks which are not in use by other volumes.
-	*******************************************************************************/
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	Volume<VoxelType>::~Volume()
 	{
@@ -143,76 +143,76 @@ namespace PolyVox
 	#pragma endregion		
 
 	#pragma region Getters
-	/*******************************************************************************
+	////////////////////////////////////////////////////////////////////////////////
-	The result will always have a lower corner at (0,0,0) and an upper corner at one
+	/// The result will always have a lower corner at (0,0,0) and an upper corner at one
-	less than the side length. For example, if a volume has dimensions 256x512x1024
+	/// less than the side length. For example, if a volume has dimensions 256x512x1024
-	then the upper corner of the enclosing region will be at (255,511,1023).
+	/// then the upper corner of the enclosing region will be at (255,511,1023).
-	\return A Region representing the extent of the volume.
+	/// \return A Region representing the extent of the volume.
-	*******************************************************************************/
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	Region Volume<VoxelType>::getEnclosingRegion(void) const
 	{
 		return Region(Vector3DInt32(0,0,0), Vector3DInt32(m_uWidth-1,m_uHeight-1,m_uDepth-1));
 	}
 
-	/*******************************************************************************
+	////////////////////////////////////////////////////////////////////////////////
-	\return The width of the volume in voxels
+	/// \return The width of the volume in voxels
-	\sa getHeight(), getDepth()
+	/// \sa getHeight(), getDepth()
-	*******************************************************************************/
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	uint16_t Volume<VoxelType>::getWidth(void) const
 	{
 		return m_uWidth;
 	}
 
-	/*******************************************************************************
+	////////////////////////////////////////////////////////////////////////////////
-	\return The height of the volume in voxels
+	/// \return The height of the volume in voxels
-	\sa getWidth(), getDepth()
+	/// \sa getWidth(), getDepth()
-	*******************************************************************************/
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	uint16_t Volume<VoxelType>::getHeight(void) const
 	{
 		return m_uHeight;
 	}
 
-	/*******************************************************************************
+	////////////////////////////////////////////////////////////////////////////////
-	\return The depth of the volume in voxels
+	/// \return The depth of the volume in voxels
-	\sa getWidth(), getHeight()
+	/// \sa getWidth(), getHeight()
-	*******************************************************************************/
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	uint16_t Volume<VoxelType>::getDepth(void) const
 	{
 		return m_uDepth;
 	}
 
-	/*******************************************************************************
+	////////////////////////////////////////////////////////////////////////////////
-	\return The length of the shortest side in voxels. For example, if a volume has
+	/// \return The length of the shortest side in voxels. For example, if a volume has
-	dimensions 256x512x1024 this function will return 256.
+	/// dimensions 256x512x1024 this function will return 256.
-	\sa getLongestSideLength(), getDiagonalLength()
+	/// \sa getLongestSideLength(), getDiagonalLength()
-	*******************************************************************************/
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	uint16_t Volume<VoxelType>::getShortestSideLength(void) const
 	{
 		return m_uShortestSideLength;
 	}
 
-	/*******************************************************************************
+	////////////////////////////////////////////////////////////////////////////////
-	\return The length of the longest side in voxels. For example, if a volume has
+	/// \return The length of the longest side in voxels. For example, if a volume has
-	dimensions 256x512x1024 this function will return 1024.
+	/// dimensions 256x512x1024 this function will return 1024.
-	\sa getShortestSideLength(), getDiagonalLength()
+	/// \sa getShortestSideLength(), getDiagonalLength()
-	*******************************************************************************/
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	uint16_t Volume<VoxelType>::getLongestSideLength(void) const
 	{
 		return m_uLongestSideLength;
 	}	
 
-	/*******************************************************************************
+	////////////////////////////////////////////////////////////////////////////////
-	\return The length of the diagonal in voxels. For example, if a volume has
+	/// \return The length of the diagonal in voxels. For example, if a volume has
-	dimensions 256x512x1024 this function will return sqrt(256*256+512*512+1024*1024)
+	/// dimensions 256x512x1024 this function will return sqrt(256*256+512*512+1024*1024)
-	= 1173.139. This value is computed on volume creation so retrieving it is fast.
+	/// = 1173.139. This value is computed on volume creation so retrieving it is fast.
-	\sa getShortestSideLength(), getLongestSideLength()
+	/// \sa getShortestSideLength(), getLongestSideLength()
-	*******************************************************************************/
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	float Volume<VoxelType>::getDiagonalLength(void) const
 	{