NAME

       vpClassifyVolume, vpDestroyClassifiedVolume - create/destroy a preclassified volume for fast rendering

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpClassifyVolume(vpc)
           vpContext *vpc;

       vpResult
       vpDestroyClassifyVolume(vpc)
           vpContext *vpc;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

DESCRIPTION

       vpClassifyVolume  is  used  to  compute  a  preclassified  volume  for the fast rendering algorithm.  The
       preclassified volume is an internal data  structure  optimized  for  rendering  speed.   vpClassifyVolume
       should   be  called  after  a  voxel  array  has  been  defined  (with  vpSetVolumeSize,  vpSetVoxelSize,
       vpSetVoxelField, and vpSetRawVoxels) and initialized (with vpVolumeNormals or  a  user-defined  routine).
       An  opacity  transfer  function  must  also be defined with vpSetClassifierTable, and the minimum opacity
       threshold should be set with the VP_MIN_VOXEL_OPACITY parameter to vpSeti.  Two alternative routines  are
       provided  to  compute  a  preclassified  volume  directly  from a 3D scalar array or a sequence of scalar
       scanlines  in  order  to  avoid  allocating  a  large  3D  voxel  array  (see  vpClassifyScalars(3)   and
       vpClassifyScanline(3)).

       vpClassifyVolume  classifies  and  processes  the  data  in  the  voxel  array  and  creates  a  separate
       preclassified volume.  The preclassified data is stored in a run-length encoded format, and  voxels  that
       have opacities less than or equal to the minimum opacity threshold are discarded.  Normally, three copies
       of  the  preclassified volume are created, one for each of the three principal viewing axis.  If only one
       or two copies are necessary for the required range of viewpoints then vpSeti may be called  with  one  or
       more  of  the  following parameters to specify which copies are required: VP_VIEW_X_AXIS, VP_VIEW_Y_AXIS,
       VP_VIEW_Z_AXIS.  Using these parameters is not recommended unless swap space is lacking.

       If a min-max octree is present in the rendering context (see vpCreateMinMaxOctree(3)) then it is used  to
       accelerate computation of the preclassified volume.  It is advantageous to create a min-max octree if the
       same volume data will be classified multiple times (with different opacity transfer functions).

       Once  vpClassifyVolume is finished, the original voxel array is no longer necessary for rendering as long
       as the opacity transfer function and the volume data do not change.  If any changes are  made,  then  the
       preclassified  volume  must  be  explicitly  recomputed  by  calling  vpClassifyVolume  again.   Only one
       preclassified volume may be stored in a rendering context at a time.  Calling vpClassifyVolume causes any
       existing preclassified volume to be destroyed.

       vpDestroyClassifiedVolume destroys the current preclassified volume and frees the associated space.

STATE VARIABLES

       Information about the current preclassified volume can be retrieved with  the  following  state  variable
       codes  (see  vpGeti(3)):  VP_VIEW_X_SIZE, VP_VIEW_Y_SIZE, VP_VIEW_Z_SIZE, VP_VIEW_X_AXIS, VP_VIEW_Y_AXIS,
       VP_VIEW_Z_AXIS.

ERRORS

       The normal return value is VP_OK.  The following error return values are possible:

       VPERROR_BAD_VOXEL
              The voxel size or the voxel fields have not been specified or have been incorrectly specified.

       VPERROR_BAD_VOLUME
              The volume array or volume dimensions have not been specified, or the size  of  the  volume  array
              does not match the volume dimensions.

       VPERROR_BAD_CLASSIFIER
              The  opacity  transfer  function  tables  have  invalid sizes or are associated with invalid voxel
              fields or have been incorrectly specified.

SEE ALSO

       VolPack(3), vpCreateContext(3), vpSetClassifierTable(3), vpClassifyScalars(3), vpClassifyScanline(3)

VolPack                                                                                      vpClassifyVolume(3)