Added some documentation and small performance improvements.

library/PolyVoxCore/include/MeshDecimator.h

@@ -28,6 +28,37 @@ freely, subject to the following restrictions:
 
 namespace PolyVox
 {
+	/// The MeshDecimator reduces the number of triangles in a mesh.
+	////////////////////////////////////////////////////////////////////////////////
+	/// Meshes generated by the PolyVox surface extractors typically have a very high
+	/// number of triangles in them. This can pose difficulties both for the rendering
+	/// storage of such meshes. The MeshDecimator provides a way of reducing the triangle
+	/// count with minimal visual effect.
+	///
+	/// The MeshDecimator is based on the principle of edge collapse, and currently works
+	/// with meshes generated by the SurfaceExtractor or CubicSurfaceExtractor. It does
+	/// not work with meshes generated by the CubicSurfaceExtractorWithNormals, although
+	/// this may be addressed in the future. The algorithm iterates over each pair of 
+	/// connected vertices in the mesh and attemps to determine if they can be collapsed
+	/// into a single vertex.
+	///
+	/// The main criteria used in deciding whether two vertices can collapse is whether
+	/// they have the same normal. In the case of the cubic surfaces the normals must be
+	/// exactly the same, whereas in the case of the Marching Cubes surfaces a threshold
+	/// is used to determine whether two normals are 'close enough'. Additional constraints
+	/// apply to vertices which lie on the edges of regions or on the boundary between two
+	/// regions - these vertices are much less likely to be collapsed.
+	///
+	/// Given a mesh called 'mesh', you can create a decimated version as follows:
+	/// \code
+	/// SurfaceMesh<PositionMaterial> decimatedMesh;
+	/// MeshDecimator<PositionMaterial> decimator(&mesh, &decimatedMesh);
+	/// decimator.execute();
+	/// \endcode
+	/// 
+	/// The above applies for a cubic mesh, for a Marching Cubes mesh you need to parametise
+	/// the MeshDecimator and resulting SurfaceMesh on the 'PositionMaterialNormal' type
+	/// instead of the 'PositionMaterial' type.
 	template <typename VertexType>
 	class MeshDecimator
 	{
@@ -62,8 +93,10 @@ namespace PolyVox
 			Vector3DFloat normal;
 		};
 	public:
+		///Constructor
 		MeshDecimator(const SurfaceMesh<VertexType>* pInputMesh, SurfaceMesh<VertexType>* pOutputMesh, float fEdgeCollapseThreshold = 0.95f);
 
+		///Performs the decimation.
 		void execute();
 
 	private: