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)