NAME

vzParameterVolumeTexture - Parameter representing a 3-dimensional texture.

INHERITS FROM

vzParameter

HEADER FILE

#include <Volumizer2/ParameterVolumeTexture.h>

PUBLIC METHOD SUMMARY

vzParameterVolumeTexture (

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

vzParameterVolumeTexture (

const int dataDimensions[3], const int dataROI[6], void* dataPtr, vzTextureType dataType, vzExternalTextureFormat externalFormat, vzInternalTextureFormat internalFormat=VZ_DEFAULT_INTERNAL_FORMAT);

void getDataDimensions (

int dims[3]) const;

vzExternalTextureFormat getDataFormat (

) const;

vzInternalTextureFormat getInternalTextureFormat (

) const;

vzTextureType getDataType (

) const;

void setDataPtr (

void* data);

void* getDataPtr (

) const;

void getDataROI (

int dataROI[6]) const;

void setGeometryROI (

const double geometryROI[6]);

void optimize (

);

bool isOptimized (

) const;

void getGeometryROI (

double geometryROI[6]) const;

PROTECTED METHOD SUMMARY

virtual ~vzParameterVolumeTexture (

);

CLASS DESCRIPTION

vzParameterVolumeTexture provides an abstraction for a 3-D texture, together with a transformation which maps the texture into geometry space (see setGeometryROI().) The class stores a pointer to the volume data, along with methods that control the format and type of the data.

METHOD DESCRIPTIONS

   vzParameterVolumeTexture()

vzParameterVolumeTexture (

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

Constructor for a volume texture parameter. dataDimensions specify the x,y, and z dimensions of the data stored in dataPtr. dataType describes the OpenGL data type of the texture. externalFormat describes the external (user) format of the texture. internalFormat describes the internal (texture memory) format of the texture. If the internal format is not specified, a default will be inferred from the external format and data type. The following shows an example use of the above constructor -

// Create a volume texture of size (256, 256,256) given the data pointer
vzParameterVolumeTexture *createTexture(void *dataPtr) {
  
    // Data dimensions
    int dataDimensions[3] = {256, 256, 256};

    // Create the texture
    vzParameterVolumeTexture *texture = new vzParameterVolumeTexture (
                                            dataDimensions,
                                            dataPtr,
                                            VZ_LUMINANCE,
                                            VZ_UNSIGNED_BYTE, 
                                            VZ_DEFAULT_INTERNAL_FORMAT);
     
    return(texture);
}

See vzTextureType, vzExternalTextureFormat and vzInternalTextureFormat for a list of supported texture types and formats. The default values for the geometry ROI is (0, 0, 0) to (1, 1, 1).

   vzParameterVolumeTexture()

vzParameterVolumeTexture (

const int dataDimensions[3], const int dataROI[6], void* dataPtr, vzTextureType dataType, vzExternalTextureFormat externalFormat, vzInternalTextureFormat internalFormat=VZ_DEFAULT_INTERNAL_FORMAT);

Alternate constructor for a volume texture parameter, for cases when a sub-cubic texture region of interest (dataROI) must be specified. dataDimensions specify the x,y, and z dimensions of the data stored in dataPtr. dataROI defines a sub-region of interest within the data pointer. Texture samples outside the dataROI will be ignored during all subsequent operations.

The Data ROI dimensions should be specified in the order (xmin, ymin, zmin, xmax, ymax, zmax). Remaining arguments are the same as the other constructor. The following constructor can be used to create a texture of dimensions (32, 32, 32) at an offset of (64, 64, 64) in the above example -

// Define a data ROI 
int dataROI[6] = {64, 64, 64, 95, 95, 95};

// Create the texture
vzParameterVolumeTexture *texture = new vzParameterVolumeTexture (
                                           dataDimensions,
                                           dataROI, 
                                           dataPtr,
                                           VZ_LUMINANCE,
                                           VZ_UNSIGNED_BYTE, 
                                           VZ_DEFAULT_INTERNAL_FORMAT);

   ~vzParameterVolumeTexture()

virtual ~vzParameterVolumeTexture (

);

Destructor for a volume texture parameter.

   getDataDimensions()

void getDataDimensions (

int dims[3]) const;

Get the dimensions of the volume data.

   getDataFormat()

vzExternalTextureFormat getDataFormat (

) const;

Get the external format of the volume texture.

   getDataPtr()

void* getDataPtr (

) const;

Retrieve the data pointer for the texture data.

   getDataROI()

void getDataROI (

int dataROI[6]) const;

Retrieve the current region of interest for this volume texture data. The region of interest is specified in the form (xmin, ymin, zmin, xmax, ymax, zmax).

   getDataType()

vzTextureType getDataType (

) const;

Get the data type of the volume texture.

   getGeometryROI()

void getGeometryROI (

double geometryROI[6]) const;

Returns the current geometryROI by retrieving the coordinates (xmin, ymin, zmin, xmax, ymax, zmax).

   getInternalTextureFormat()

vzInternalTextureFormat getInternalTextureFormat (

) const;

Get the internal format of the volume texture. This indicates the format the data is stored in texture memory.

   isOptimized()

bool isOptimized (

) const;

Returns true if optimize() was called on this texture. Note that this returns true only if the application has requested this texture to be optimized explicitly by calling optimize(). If a render action does other transparent optimizations on the texture data, then this method would still return false.

   optimize()

void optimize (

);

Optimize the texture data in order to improve performance. On Infinite Reality systems, this will interleave the texture data if needed. The texture is interleaved according to the external and internal texture formats specified by the constructor. If the internal format is VZ_DEFAULT_INTERNAL_FORMAT, then the appropriate formats would be inferred. The optimized data would be stored in the texture and will be re-usable for any subsequent operations by the render action.

Note: the interleaving process might be delayed until the shape containing the texture is actually managed for the first time. Hence, you cannot delete the original data pointer after calling this method.

If you do not call optimize() and specify an interleaved internal format, then the render action assumes that your texture data is already interleaved. Also, the data should be compliant with OpenGL's texture specifications. For example, the textures should fit in texture memory and should have power-of-two dimensions.

   setDataPtr()

void setDataPtr (

void* data);

Set the data pointer for the texture data. Note: data is NOT copied, so all memory allocation must be done by the user. This method marks the entire texture as dirty. It will be reloaded into texture memory the next time it is needed. Also, if the texture was marked to be optimized (see optimize()), then the texture data would be re-processed.

   setGeometryROI()

void setGeometryROI (

const double geometryROI[6]);

Explicitly set the geometry ROI in terms of (xmin, ymin, zmin, xmax, ymax, zmax). This value is used to map the texture data ROI, to the geometry space. Changing the values allows you to arbitrarily scale and translate your texture to fit the geometry that you have defined. Specifically, voxel samples along the border of the texture are mapped so that they lie exactly along the boundaries of the geometryROI. Geometry outside the geometryROI will be clipped out during rasterization. The default values for the geometry ROI is (0, 0, 0) to (1, 1, 1).

SEE ALSO

vzExternalTextureFormat, vzInternalTextureFormat, vzParameter, vzTextureType

Back to Index