From aed8f79aa1d8fc0a83cca96db22ebca0b20ee014 Mon Sep 17 00:00:00 2001 From: David Williams Date: Mon, 28 Mar 2011 19:55:45 +0000 Subject: [PATCH] Documentation update. Fixed crash in flushAll(). --- examples/Basic/main.cpp | 6 +++++ library/PolyVoxCore/include/Volume.h | 37 +++++++++++++++++++++++--- library/PolyVoxCore/include/Volume.inl | 6 +++-- 3 files changed, 43 insertions(+), 6 deletions(-) diff --git a/examples/Basic/main.cpp b/examples/Basic/main.cpp index f4f984a3..dee9bfdf 100644 --- a/examples/Basic/main.cpp +++ b/examples/Basic/main.cpp @@ -24,6 +24,7 @@ freely, subject to the following restrictions: #include "OpenGLWidget.h" #include "MaterialDensityPair.h" +#include "Material.h" #include "CubicSurfaceExtractorWithNormals.h" #include "SurfaceMesh.h" #include "Volume.h" @@ -89,6 +90,11 @@ int main(int argc, char *argv[]) //Pass the surface to the OpenGL window openGLWidget.setSurfaceMeshToRender(mesh); + Volume volume(Region(Vector3DInt32(0,0,0), Vector3DInt32(63,127,255))); + volume.setVoxelAt(15, 90, 42, Material8(5)); + std::cout << "Voxel at (15, 90, 42) has value: " << volume.getVoxelAt(15, 90, 42).getMaterial() << std::endl; + std::cout << "Width = " << volume.getWidth() << ", Height = " << volume.getHeight() << ", Depth = " << volume.getDepth() << std::endl; + //Run the message pump. return app.exec(); } diff --git a/library/PolyVoxCore/include/Volume.h b/library/PolyVoxCore/include/Volume.h index 822a8575..9e134ba0 100644 --- a/library/PolyVoxCore/include/Volume.h +++ b/library/PolyVoxCore/include/Volume.h @@ -38,9 +38,31 @@ 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 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 PolyVox, - /// the Volume class is used to store and manipulate our data before we extract our SurfaceMeshs from it. + /// A Volume is essentially a 3D array in which each element (or voxel) is identified by a three dimensional (x,y,z) coordinate. + /// We use the Volume class to store our data in an efficient way, and it is the input to many of the algorithms (such as the surface + /// extractors) which form the heart of PolyVox. The Volume class is templatised so that different types of data can be stored with each voxel. + /// + /// Basic usage + /// The following code snippet shows how to construct a volume and demonstrates basic usage: + /// + /// Volume volume(Region(Vector3DInt32(0,0,0), Vector3DInt32(63,127,255))); + /// volume.setVoxelAt(15, 90, 42, Material8(5)); + /// std::cout << "Voxel at (15, 90, 42) has value: " << volume.getVoxelAt(15, 90, 42).getMaterial() << std::endl; + /// std::cout << "Width = " << volume.getWidth() << ", Height = " << volume.getHeight() << ", Depth = " << volume.getDepth() << std::endl; + /// + /// The Volume constructor takes a Region as a parameter. This specifies the valid range of voxels which can be held in the volume, so in this + /// particular case the valid voxel positions are (0,0,0) to (63, 127, 255). Attempts to access voxels outside this range can result in a crash + /// (or an assert() if running in debug mode). PolyVox also has support for near infinite volumes which will be discussed later. + /// + /// In this particular example each voxel in the Volume is of type 'Material', as specified by the template parameter. This is one of several + /// predefined voxel types, and it is also possible to define your own. The Material type simply holds an integer value where zero represents + /// empty space and any other value represents a solid material. + /// + /// Access to individual voxels is provided via the setVoxelAt() and getVoxelAt() member functions. Advanced users may also be interested in + /// the VolumeSampler class for faster read-only access to a large number of voxels. + /// + /// Lastly the example prints out some properties of the Volume. Note that the dimentsions width(), height(), and depth() are inclusive, such + /// 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 @@ -53,10 +75,17 @@ namespace PolyVox /// memory but it is hard to modify the data. Therefore, before any given voxel can be modified, its corresponding block must be uncompressed. /// /// The compression and decompression of block is a relatively slow process and so we aim to do this as rarely as possible. In order - /// to achive this, the volume class store a cache of recently used blocks and their associated uncompressed data. Each time a voxel + /// to achive this, the volume class stores a cache of recently used blocks and their associated uncompressed data. Each time a voxel /// is touched a timestamp is updated on the corresponding block, when the cache becomes full the block with the oldest timestamp is /// recompressed and moved out of the cache. /// + /// This compression scheme will typically allow you to load several billion voxels into a few hundred megabytes of memory, though 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 potentially unlimited amount + /// of data to be loaded, provided the user is able to take responsibility for storing any data which PolyVox cannot fit in memory, and then + /// returning it back to PolyVox on demand. For example, the user might choose to temporarilly store this data on disk or stream it to a + /// remote database. + /// /// Achieving high compression rates /// Note: This section is theorectical and not well tested. Please let us know if you find the tips below do or do not work. /// diff --git a/library/PolyVoxCore/include/Volume.inl b/library/PolyVoxCore/include/Volume.inl index c21ea0ad..80e82c84 100644 --- a/library/PolyVoxCore/include/Volume.inl +++ b/library/PolyVoxCore/include/Volume.inl @@ -414,9 +414,11 @@ namespace PolyVox void Volume::flushAll() { typename std::map::iterator i; - for(i = m_pBlocks.begin(); i != m_pBlocks.end(); i++) + //Replaced the for loop here as the call to + //eraseBlock was invalidating the iterator. + while(m_pBlocks.size() > 0) { - eraseBlock(i); + eraseBlock(m_pBlocks.begin()); } }