diff --git a/library/PolyVoxCore/include/PolyVoxCore/LargeVolume.h b/library/PolyVoxCore/include/PolyVoxCore/LargeVolume.h index 7d05a391..c7e44db1 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/LargeVolume.h +++ b/library/PolyVoxCore/include/PolyVoxCore/LargeVolume.h @@ -42,6 +42,8 @@ freely, subject to the following restrictions: namespace PolyVox { + template class ConstVolumeProxy; + /// The LargeVolume class provides a memory efficient method of storing voxel data while also allowing fast access and modification. //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// /// A LargeVolume is essentially a 3D array in which each element (or voxel) is identified by a three dimensional (x,y,z) coordinate. @@ -49,6 +51,7 @@ namespace PolyVox /// extractors) which form the heart of PolyVox. The LargeVolume class is templatised so that different types of data can be stored within each voxel. /// /// Basic usage + /// /// The following code snippet shows how to construct a volume and demonstrates basic usage: /// /// \code @@ -73,6 +76,7 @@ namespace PolyVox /// that the width is 64 when the range of valid x coordinates goes from 0 to 63. /// /// Data Representaion + /// /// 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 if stored in an uncompressed form. Natuarally our LargeVolume class is much more efficient /// than this and it is worth understanding (at least at a high level) the approach which is used. @@ -88,6 +92,7 @@ namespace PolyVox /// recompressed and moved out of the cache. /// /// Achieving high compression rates + /// /// The compression rates which can be achieved can vary significantly depending the nature of the data you are storing, but you can /// encourage high compression rates by making your data as homogenous as possible. If you are simply storing a material with each /// voxel then this will probably happen naturally. Games such as Minecraft which use this approach will typically involve large areas @@ -99,6 +104,7 @@ namespace PolyVox /// your density values to reduce this problem (this threasholding should only be applied to voxels who don't contribute to the surface). /// /// Paging large volumes + /// /// The compression scheme described previously will typically allow you to load several billion voxels into a few hundred megabytes of memory, /// though as explained the exact compression rate is highly dependant on your data. If you have more data than this then PolyVox provides a /// mechanism by which parts of the volume can be paged out of memory by calling user supplied callback functions. This mechanism allows a @@ -129,6 +135,7 @@ namespace PolyVox /// anymore. But you still need to be ready to then provide something to PolyVox (even if it's just default data) in the event that it is requested. /// /// Cache-aware traversal + /// /// You might be suprised at just how many cache misses can occur when you traverse the volume in a naive manner. Consider a 1024x1024x1024 volume /// with blocks of size 32x32x32. And imagine you iterate over this volume with a simple three-level for loop which iterates over x, the y, then z. /// If you start at position (0,0,0) then ny the time you reach position (1023,0,0) you have touched 1024 voxels along one edge of the volume and @@ -142,13 +149,11 @@ namespace PolyVox /// is your cache sise is only one. Of course the logic is more complex, but writing code in such a cache-aware manner may be beneficial in some situations. /// /// Threading + /// /// The LargeVolume class does not make any guarentees about thread safety. You should ensure that all accesses are performed from the same thread. /// This is true even if you are only reading data from the volume, as concurrently reading from different threads can invalidate the contents /// of the block cache (amoung other problems). //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// - - template class ConstVolumeProxy; - template class LargeVolume : public BaseVolume {