NAME

vzParameterClipTexture - Parameter representing a 3-dimensional clip-texture hierarchy.

INHERITS FROM

vzParameter

HEADER FILE

#include <Volumizer2/ParameterClipTexture.h>

PUBLIC METHOD SUMMARY

   Constructor

vzParameterClipTexture (

const int dataDimensions[3], vzTextureType dataType, vzExternalTextureFormat externalFormat, vzInternalTextureFormat internalFormat=VZ_DEFAULT_INTERNAL_FORMAT);

   Visible region settings

void setCenterOfInterest (

const int coi[3]);

void setRoamingWindowSize (

const int dimensions[3]);

void setRegionDirty (

const int offset[3], const int level, const int dimensions[3]);

   Data Loader methods

void setDataLoaderCB (

const vzDataLoaderCB loaderCB, void* userData);

void setMaxThreads (

const int numThreads);

   Other parameters

void setPhysicalMemorySize (

const unsigned long maxMemorySize);

void setBrickDimensions (

const int dims[3]);

void setGeometryROI (

const double geometryROI[6]);

   Get methods

void getDataDimensions (

int dim[3]);

void getGeometryROI (

double geometryROI[6]);

int getNumLevels (

);

void getBrickDimensions (

int dim[3]);

vzTextureType getDataType (

);

vzExternalTextureFormat getDataFormat (

);

vzInternalTextureFormat getInternalTextureFormat (

);

void getCenterOfInterest (

int coi[3]);

void getRoamingWindowSize (

int dimensions[3]);

void getDataLoaderCB (

vzDataLoaderCB& loaderCB, void*& userData);

unsigned long getPhysicalMemorySize (

);

PROTECTED METHOD SUMMARY

virtual ~vzParameterClipTexture (

);

CLASS DESCRIPTION

vzParameterClipTexture represents a 3-dimensional clip-texture. The clip-texture is internally represented as a collection of mip-mapped texture levels, clipped to fit in the main memory of the system. The texture data is organized into separate texture bricks to organize the data at the various levels of the hierarchy. The complete volume data does not need to be in main memory and is paged in from disk asynchronously. This is done by using a loader callback provided by the application (see ).

The following other parameters effect the way the hierarchy is set up and so, these values can either be set using the constructor or immediately after the construction when the clip-texture has not been managed and or drawn using the vzClipRenderAction.

• Data dimensions - Size of the whole volume data. Used to compute the total number of bricks in the volume and the number of levels in the hierarchy.
• Texture type and formats - Includes the texture format, type and internal format. Used to compute the number of bytes per texel and create the volume textures representing the sub-bricks.
• Texture brick dimensions - Size of the texture brick. Must be defined in terms of {X, Y, Z} texels.
• Geometry ROI - Used to map the texture data onto world coordinates. Each of the sub-textures will be assigned a roi accordingly. Default values are {0, 0, 0} to {1, 1, 1}.
• Data load callback - Used to load data from the disk. Sample callbacks are provided with the demo code

The following other parameters are used by the application to update the clip-texture depending on the user interaction, potentially on a per-frame basis:

• Center of interest - The {X, Y, Z} index in volume data space, corresponding to the current center of interest.
• Roaming window size - The dimensions of the actual roaming window containing the visible volume data. By default, all the data is assumed to be visible.

The following parameters are computed by the clip-texture class from the parameters specified above:

• Number of levels - Number of levels of resolution for the clip texture. The number of levels depends on the texture brick size and the original data dimensions. Level zero corresponds to the original data resolution and higher levels correspond to sub-sampled versions of the original data.
• Number of threads - Maximum number of threads to be used to page in texture data from the disk. The default number is equal to the number of clip-levels in the heirarchy (see setMaxThreads())

All the set methods also have corresponding get methods.

METHOD DESCRIPTIONS

   vzParameterClipTexture()

vzParameterClipTexture (

const int dataDimensions[3], vzTextureType dataType, vzExternalTextureFormat externalFormat, vzInternalTextureFormat internalFormat=VZ_DEFAULT_INTERNAL_FORMAT);

Constructor for the clip-texture heirarchy.

   ~vzParameterClipTexture()

virtual ~vzParameterClipTexture (

);

Destructor for the vzParameterClipTexture. Destroys the clip-texture hierarchy and the data loader threads used to load volume data.

   getBrickDimensions()

void getBrickDimensions (

int dim[3]);

Get the dimensions of the texture bricks in the heirarchy.

   getCenterOfInterest()

void getCenterOfInterest (

int coi[3]);

Get the current center of interest for the clip-texture.

   getDataDimensions()

void getDataDimensions (

int dim[3]);

Get the data dimensions of the highest level-of-resolution in the heirarchy.

   getDataFormat()

vzExternalTextureFormat getDataFormat (

);

Get the data format for the texture.

   getDataLoaderCB()

void getDataLoaderCB (

vzDataLoaderCB& loaderCB, void*& userData);

Get the data load callback and the user data pointer.

   getDataType()

vzTextureType getDataType (

);

Get the data type for the texture.

   getGeometryROI()

void getGeometryROI (

double geometryROI[6]);

Get the geometry ROI for the complete clip-texture.

   getInternalTextureFormat()

vzInternalTextureFormat getInternalTextureFormat (

);

Get the texture internal format for the texture.

   getNumLevels()

int getNumLevels (

);

Get the number of levels in the heirarchy.

   getPhysicalMemorySize()

unsigned long getPhysicalMemorySize (

);

Get the size of the physical memory for this clip-texture. Note that this value is only approximate and the actual amount of memory used can be greater than or smaller than this value.

   getRoamingWindowSize()

void getRoamingWindowSize (

int dimensions[3]);

Get the current roaming window size for the clip-texture.

   setBrickDimensions()

void setBrickDimensions (

const int dims[3]);

Set the dimensions of the texture bricks. This method should be called before the clip-texture is managed/drawn for the first time. The default value for the brick size is {128, 128, 128}.

   setCenterOfInterest()

void setCenterOfInterest (

const int coi[3]);

Set the center of interest for the current frame. Texture bricks closer to the center of interest will be paged in earlier compared to the bricks which are further away. This can be computed using the viewer's position of viewing direction. The position needs to be specified in the "data space", i.e. in the range [0 ... dataDimensions[i] - 1].

   setDataLoaderCB()

void setDataLoaderCB (

const vzDataLoaderCB loaderCB, void* userData);

The callback for loading volume data from disk has the following format:

typedef bool (*vzDataLoaderCB)(const int offset[3], const int level, const int dim[3], void *data, void *userData);

Callback used to load in volume data is passed the position offset and level level. The dimensions of the data to be loaded is given by dimensions. The resulting data will be set in data. The following code uses the provided sample IFL loaders to load in the volume data.

void loadDataCB(int offset[3], int level, int dimensions[3], void *data, void *userData) {
   IFLLoader *loader = ((ClipLoaders **)userData)->getLoaderForLevel(level);
   loader->loadBrick(data, offset, dimensions);
}

   setGeometryROI()

void setGeometryROI (

const double geometryROI[6]);

Set the geometry ROI for the whole clip-texture. This defines the mapping of the texture data onto geometry space. The default value is {0, 0, 0} - {1, 1, 1}. All the bricks in the clip-texture are scaled appropriately.

   setMaxThreads()

void setMaxThreads (

const int numThreads);

Maximum number of threads to be used for paging textures from the disk. The default number of threads created is equal to the number of levels in the hierarchy.

Note on Thread-safe loaders: When using multiple loader threads, multiple threads might be scheduled to load different bricks from the same clip-level. In this case, the loader used for the clip-level needs to be thread safe. For example, if the loader uses the same file for all the bricks in a clip-level and multiple invocations of the loader callback use the same file descriptor, the loader might not be thread-safe. The clip-texture implementation currently assumes that the loaders are not thread safe and does not schedule multiple threads to load bricks from the same clip-level simultaneously. This can however reduce the performance of the disk paging algorithm. In order to allow multiple threads to load bricks from the same clip-level, use thread-safe loaders (e.g. RoamLoader version 3.0 shipped with Volumizer 2.4 onwards) and then enable concurrent reads from a clip-level by setting the environment variable VOLUMIZER_THREAD_SAFE_LOADER. The above is done automatically by ClipGen3d shipped with Volumizer 2.4 when you select the -level0 option and the remaining options are default (-roamVersion 3.0). The ClipLoader class in src/lib/loaders/ checks for thread-safe loaders and sets the above environment variable, if loaders are thread-safe.

   setPhysicalMemorySize()

void setPhysicalMemorySize (

const unsigned long maxMemorySize);

Limit the size of the volumetric data to be kept in main memory to maxMemorySize. This value should be set depending on the total memory available on the system. Specifying a small value will mean that less high-resolution bricks will be resident in main memory at any given instant and hence lower resolution levels of the clip-texture will be rendered and vice-versa. The default value is computed to be four times the texture memory available on the graphics sub-system. For example, the physical memory size when running on InfiniteReality3 graphics systems (256 MB texture memory) will be 1 GB. Note that the value specified here is an approproximate value and actual memory usage would normally differ from the specified value.

   setRegionDirty()

void setRegionDirty (

const int offset[3], const int level, const int dimensions[3]);

Mark the volumetric data in the given region as dirty. This would force the bricks which intersect the given region to be invalidated and re-loaded as needed. The interface for this is similar to the data loader callback. This can be used by applications to implement techniques like volumetric tagging to mask out the volume data which is no longer needed. This method is not implemented currently.

   setRoamingWindowSize()

void setRoamingWindowSize (

const int dimensions[3]);

Set the size of roaming window. This window is used as the roaming window in conjunction with the center of interest. The dimensions are assumed to be specified according to the original data dimensions. The actual roaming window dimensions for each clip-level is computed depending on the total physical memory that clip-texture is allowed to use.

SEE ALSO

vzClipRenderAction, vzParameter

Back to Index