Classes | Public Member Functions | Friends

PolyVox::LargeVolume< VoxelType > Class Template Reference

#include <LargeVolume.h>

Inheritance diagram for PolyVox::LargeVolume< VoxelType >:
Collaboration diagram for PolyVox::LargeVolume< VoxelType >:

List of all members.

Classes

struct  LoadedBlock
class  Sampler

Public Member Functions

 LargeVolume (polyvox_function< void(const ConstVolumeProxy< VoxelType > &, const Region &)> dataRequiredHandler, polyvox_function< void(const ConstVolumeProxy< VoxelType > &, const Region &)> dataOverflowHandler, uint16_t uBlockSideLength=32)
 Constructor for creating a very large paging volume.
 LargeVolume (const Region &regValid, polyvox_function< void(const ConstVolumeProxy< VoxelType > &, const Region &)> dataRequiredHandler=0, polyvox_function< void(const ConstVolumeProxy< VoxelType > &, const Region &)> dataOverflowHandler=0, bool bPagingEnabled=false, uint16_t uBlockSideLength=32)
 Constructor for creating a fixed size volume.
 LargeVolume (int32_t dont_use_this_constructor_1, int32_t dont_use_this_constructor_2, int32_t dont_use_this_constructor_3)
 Deprecated constructor - do not use.
 ~LargeVolume ()
 Destructor.
VoxelType getBorderValue (void) const
 Gets the value used for voxels which are outside the volume.
VoxelType getVoxelAt (int32_t uXPos, int32_t uYPos, int32_t uZPos) const
 Gets a voxel at the position given by x,y,z coordinates.
VoxelType getVoxelAt (const Vector3DInt32 &v3dPos) const
 Gets a voxel at the position given by a 3D vector.
void setCompressionEnabled (bool bCompressionEnabled)
 Enabling compression allows significantly more data to be stored in memory.
void setMaxNumberOfUncompressedBlocks (uint32_t uMaxNumberOfUncompressedBlocks)
 Sets the number of blocks for which uncompressed data is stored.
void setMaxNumberOfBlocksInMemory (uint32_t uMaxNumberOfBlocksInMemory)
 Sets the number of blocks which can be in memory before the paging system starts unloading them.
void setBorderValue (const VoxelType &tBorder)
 Sets the value used for voxels which are outside the volume.
bool setVoxelAt (int32_t uXPos, int32_t uYPos, int32_t uZPos, VoxelType tValue)
 Sets the voxel at the position given by x,y,z coordinates.
bool setVoxelAt (const Vector3DInt32 &v3dPos, VoxelType tValue)
 Sets the voxel at the position given by a 3D vector.
void prefetch (Region regPrefetch)
 Tries to ensure that the voxels within the specified Region are loaded into memory.
void flush (Region regFlush)
 Ensures that any voxels within the specified Region are removed from memory.
void flushAll ()
 Removes all voxels from memory.
void clearBlockCache (void)
 Empties the cache of uncompressed blocks.
float calculateCompressionRatio (void)
 Calculates the approximate compression ratio of the store volume data.
uint32_t calculateSizeInBytes (void)
 Calculates approximatly how many bytes of memory the volume is currently using.
void resize (const Region &regValidRegion, uint16_t uBlockSideLength)
 Deprecated - I don't think we should expose this function? Let us know if you disagree...

Friends

class ConstVolumeProxy< VoxelType >

Detailed Description

template<typename VoxelType>
class PolyVox::LargeVolume< VoxelType >

Definition at line 153 of file LargeVolume.h.


Constructor & Destructor Documentation

template<typename VoxelType>
PolyVox::LargeVolume< VoxelType >::LargeVolume ( polyvox_function< void(const ConstVolumeProxy< VoxelType > &, const Region &)>  dataRequiredHandler,
polyvox_function< void(const ConstVolumeProxy< VoxelType > &, const Region &)>  dataOverflowHandler,
uint16_t  uBlockSideLength = 32 
)

Constructor for creating a very large paging volume.

When construncting a very large volume you need to be prepared to handle the scenario where there is so much data that PolyVox cannot fit it all in memory.

When PolyVox runs out of memory, it identifies the least recently used data and hands it back to the application via a callback function. It is then the responsibility of the application to store this data until PolyVox needs it again (as signalled by another callback function). Please see the LargeVolume class documentation for a full description of this process and the required function signatures. If you really don't want to handle these events then you can provide null pointers here, in which case the data will be discarded and/or filled with default values.

Parameters:
dataRequiredHandler The callback function which will be called when PolyVox tries to use data which is not currently in momory.
dataOverflowHandler The callback function which will be called when PolyVox has too much data and needs to remove some from memory.
uBlockSideLength The size of the blocks making up the volume. Small blocks will compress/decompress faster, but there will also be more of them meaning voxel access could be slower.

Definition at line 37 of file LargeVolume.inl.

template<typename VoxelType>
PolyVox::LargeVolume< VoxelType >::LargeVolume ( const Region regValid,
polyvox_function< void(const ConstVolumeProxy< VoxelType > &, const Region &)>  dataRequiredHandler = 0,
polyvox_function< void(const ConstVolumeProxy< VoxelType > &, const Region &)>  dataOverflowHandler = 0,
bool  bPagingEnabled = false,
uint16_t  uBlockSideLength = 32 
)

Constructor for creating a fixed size volume.

This constructor creates a volume with a fixed size which is specified as a parameter.

By default this constructor will not enable paging but you can override this if desired. If you do wish to enable paging then you are required to provide the call back function (see the other LargeVolume constructor).

Parameters:
regValid Specifies the minimum and maximum valid voxel positions.
dataRequiredHandler The callback function which will be called when PolyVox tries to use data which is not currently in momory.
dataOverflowHandler The callback function which will be called when PolyVox has too much data and needs to remove some from memory.
bPagingEnabled Controls whether or not paging is enabled for this LargeVolume.
uBlockSideLength The size of the blocks making up the volume. Small blocks will compress/decompress faster, but there will also be more of them meaning voxel access could be slower.

Definition at line 82 of file LargeVolume.inl.

template<typename VoxelType>
PolyVox::LargeVolume< VoxelType >::LargeVolume ( int32_t  dont_use_this_constructor_1,
int32_t  dont_use_this_constructor_2,
int32_t  dont_use_this_constructor_3 
)

Deprecated constructor - do not use.

Deprecated - do not use this constructor.

Definition at line 56 of file LargeVolume.inl.

template<typename VoxelType >
PolyVox::LargeVolume< VoxelType >::~LargeVolume (  ) 

Destructor.

Destroys the volume The destructor will call flushAll() to ensure that a paging volume has the chance to save it's data via the dataOverflowHandler() if desired.

Definition at line 103 of file LargeVolume.inl.

Here is the call graph for this function:


Member Function Documentation

template<typename VoxelType >
float PolyVox::LargeVolume< VoxelType >::calculateCompressionRatio ( void   ) 

Calculates the approximate compression ratio of the store volume data.

Note: This function needs reviewing for accuracy...

Definition at line 618 of file LargeVolume.inl.

Here is the call graph for this function:

template<typename VoxelType >
uint32_t PolyVox::LargeVolume< VoxelType >::calculateSizeInBytes ( void   ) 

Calculates approximatly how many bytes of memory the volume is currently using.

Note: This function needs reviewing for accuracy...

Reimplemented from PolyVox::BaseVolume< VoxelType >.

Definition at line 629 of file LargeVolume.inl.

Referenced by PolyVox::LargeVolume< VoxelType >::calculateCompressionRatio().

template<typename VoxelType >
void PolyVox::LargeVolume< VoxelType >::clearBlockCache ( void   ) 
template<typename VoxelType >
void PolyVox::LargeVolume< VoxelType >::flush ( Region  regFlush  ) 

Ensures that any voxels within the specified Region are removed from memory.

Removes all voxels in the specified Region from memory, and calls dataOverflowHandler() to ensure the application has a chance to store the data.

It is possible that there are no voxels loaded in the Region, in which case the function will have no effect.

Definition at line 339 of file LargeVolume.inl.

Here is the call graph for this function:

template<typename VoxelType >
void PolyVox::LargeVolume< VoxelType >::flushAll (  ) 

Removes all voxels from memory.

Removes all voxels from memory, and calls dataOverflowHandler() to ensure the application has a chance to store the data.

Definition at line 324 of file LargeVolume.inl.

Referenced by PolyVox::LargeVolume< VoxelType >::setMaxNumberOfBlocksInMemory(), and PolyVox::LargeVolume< VoxelType >::~LargeVolume().

template<typename VoxelType >
VoxelType PolyVox::LargeVolume< VoxelType >::getBorderValue ( void   )  const

Gets the value used for voxels which are outside the volume.

The border value is returned whenever an atempt is made to read a voxel which is outside the extents of the volume.

Returns:
The value used for voxels outside of the volume

Reimplemented from PolyVox::BaseVolume< VoxelType >.

Definition at line 115 of file LargeVolume.inl.

Referenced by PolyVox::LargeVolume< VoxelType >::getVoxelAt().

template<typename VoxelType >
VoxelType PolyVox::LargeVolume< VoxelType >::getVoxelAt ( int32_t  uXPos,
int32_t  uYPos,
int32_t  uZPos 
) const

Gets a voxel at the position given by x,y,z coordinates.

Parameters:
uXPos The x position of the voxel
uYPos The y position of the voxel
uZPos The z position of the voxel
Returns:
The voxel value

Reimplemented from PolyVox::BaseVolume< VoxelType >.

Definition at line 127 of file LargeVolume.inl.

Referenced by PolyVox::VolumeChangeTracker< VoxelType >::getLastModifiedTimeForRegion(), and PolyVox::LargeVolume< VoxelType >::getVoxelAt().

Here is the call graph for this function:

template<typename VoxelType >
VoxelType PolyVox::LargeVolume< VoxelType >::getVoxelAt ( const Vector3DInt32 v3dPos  )  const

Gets a voxel at the position given by a 3D vector.

Parameters:
v3dPos The 3D position of the voxel
Returns:
The voxel value

Reimplemented from PolyVox::BaseVolume< VoxelType >.

Definition at line 154 of file LargeVolume.inl.

Here is the call graph for this function:

template<typename VoxelType >
void PolyVox::LargeVolume< VoxelType >::prefetch ( Region  regPrefetch  ) 

Tries to ensure that the voxels within the specified Region are loaded into memory.

Note that if MaxNumberOfBlocksInMemory is not large enough to support the region this function will only load part of the region.

In this case it is undefined which parts will actually be loaded. If all the voxels in the given region are already loaded, this function will not do anything. Other voxels might be unloaded to make space for the new voxels.

Parameters:
regPrefetch The Region of voxels to prefetch into memory.

Definition at line 267 of file LargeVolume.inl.

Here is the call graph for this function:

template<typename VoxelType >
void PolyVox::LargeVolume< VoxelType >::resize ( const Region regValidRegion,
uint16_t  uBlockSideLength 
)

Deprecated - I don't think we should expose this function? Let us know if you disagree...

This function should probably be made internal...

Definition at line 394 of file LargeVolume.inl.

Here is the call graph for this function:

template<typename VoxelType>
void PolyVox::LargeVolume< VoxelType >::setBorderValue ( const VoxelType &  tBorder  ) 

Sets the value used for voxels which are outside the volume.

Parameters:
tBorder The value to use for voxels outside the volume.

Reimplemented from PolyVox::BaseVolume< VoxelType >.

Definition at line 215 of file LargeVolume.inl.

template<typename VoxelType >
void PolyVox::LargeVolume< VoxelType >::setCompressionEnabled ( bool  bCompressionEnabled  ) 

Enabling compression allows significantly more data to be stored in memory.

Parameters:
bCompressionEnabled Specifies whether compression is enabled.

Definition at line 164 of file LargeVolume.inl.

Here is the call graph for this function:

template<typename VoxelType >
void PolyVox::LargeVolume< VoxelType >::setMaxNumberOfBlocksInMemory ( uint32_t  uMaxNumberOfBlocksInMemory  ) 

Sets the number of blocks which can be in memory before the paging system starts unloading them.

Increasing the number of blocks in memory causes fewer calls to dataRequiredHandler()/dataOverflowHandler().

Parameters:
uMaxBlocks The number of blocks

Definition at line 202 of file LargeVolume.inl.

Here is the call graph for this function:

template<typename VoxelType >
void PolyVox::LargeVolume< VoxelType >::setMaxNumberOfUncompressedBlocks ( uint32_t  uMaxNumberOfUncompressedBlocks  ) 

Sets the number of blocks for which uncompressed data is stored.

Increasing the size of the block cache will increase memory but may improve performance.

You may want to set this to a large value (e.g. 1024) when you are first loading your volume data and then set it to a smaller value (e.g.64) for general processing.

Parameters:
uBlockCacheSize The number of blocks for which uncompressed data can be cached.

Definition at line 190 of file LargeVolume.inl.

Referenced by PolyVox::LargeVolume< VoxelType >::resize().

Here is the call graph for this function:

template<typename VoxelType>
bool PolyVox::LargeVolume< VoxelType >::setVoxelAt ( int32_t  uXPos,
int32_t  uYPos,
int32_t  uZPos,
VoxelType  tValue 
)

Sets the voxel at the position given by x,y,z coordinates.

Parameters:
uXPos the x position of the voxel
uYPos the y position of the voxel
uZPos the z position of the voxel
tValue the value to which the voxel will be set
Returns:
whether the requested position is inside the volume

Reimplemented from PolyVox::BaseVolume< VoxelType >.

Definition at line 230 of file LargeVolume.inl.

Referenced by PolyVox::VolumeChangeTracker< VoxelType >::setAllRegionsModified(), PolyVox::VolumeChangeTracker< VoxelType >::setVoxelAt(), PolyVox::LargeVolume< VoxelType >::setVoxelAt(), and PolyVox::VolumeChangeTracker< VoxelType >::unlockRegion().

Here is the call graph for this function:

template<typename VoxelType>
bool PolyVox::LargeVolume< VoxelType >::setVoxelAt ( const Vector3DInt32 v3dPos,
VoxelType  tValue 
)

Sets the voxel at the position given by a 3D vector.

Parameters:
v3dPos the 3D position of the voxel
tValue the value to which the voxel will be set
Returns:
whether the requested position is inside the volume

Reimplemented from PolyVox::BaseVolume< VoxelType >.

Definition at line 256 of file LargeVolume.inl.

Here is the call graph for this function:


Friends And Related Function Documentation

template<typename VoxelType>
friend class ConstVolumeProxy< VoxelType > [friend]

Definition at line 229 of file LargeVolume.h.


The documentation for this class was generated from the following files: