NAME

       vpCreateMinMaxOctree,  vpMinMaxOctreeThreshold,  vpDestroyMinMaxOctree  - create/destroy a
       min-max octree for optimized rendering

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpCreateMinMaxOctree(vpc, root_node_size, base_node_size)
           vpContext *vpc;
           int root_node_size, base_node_size;

       vpResult
       vpMinMaxOctreeThreshold(vpc, param_num, range)
           vpContext *vpc;
           int param_num, range;

       vpResult
       vpDestroyMinMaxOctree(vpc)
           vpContext *vpc;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       root_node_size
              Number of voxels per side in the top level (largest  nodes)  of  the  octree.   Not
              currently used.

       base_node_size
              Number of voxels per side in the bottom level (smallest nodes) of the octree.  Must
              be a power of 2.

       param_num
              Identifying number of one parameter of the opacity transfer function.

       range  Range threshold for one parameter of the opacity transfer function.  If  an  octree
              node spans a larger range then it is subdivided.

DESCRIPTION

       These routines are used to create and destroy a min-max octree, an internal data structure
       that is used to accelerate classifying and rendering volume data in a 3D voxel array.  The
       octree  is a hierarchical data structure that contains minimum and maximum values for each
       voxel field.  It does not duplicate the data in the voxel array.  The octree is  not  used
       with preclassified volumes (see vpClassifyVolume(3)).

       Before creating an octree, declare a 3D voxel array using vpSetVolumeSize, vpSetVoxelSize,
       vpSetVoxelField and vpSetRawVoxels, and initialize parameters  for  the  opacity  transfer
       function  by  calling  vpSetClassifierTable.  Then initialize the voxel data in the array.
       The lookup tables for the opacity transfer function do not need to be initialized.

       Now call vpMinMaxOctreeThreshold once for each parameter to the opacity transfer function.
       The  parameter  number  is  the  same  number  as  the  parameter number you would pass to
       vpClassifierTable.  The range argument  specifies  a  "small"  range  of  values  for  the
       corresponding  parameter.   The  opacity of a voxel should not vary much for voxels within
       this range of parameter space.  Choosing a value which is  too  small  or  too  large  may
       result  in  a reduced performance benefit during rendering.  The function vpOctreeMask can
       be used to visualize the effectiveness of various parameter ranges.  Note  that  you  must
       choose the voxel field associated with each opacity transfer function parameter in advance
       of creating the octree (by calling vpSetClassiferTable), but the opacity transfer function
       itself  does  not  need to be known since the lookup tables do not need to be initialized.
       In the current implementation all of the parameters must be one or two-byte voxel  fields;
       four-byte fields are not allowed.

       Finally,  call vpCreateMinMaxOctree to actually compute the octree.  The arguments specify
       the largest and smallest node size.  These values can be used to trade off storage size of
       the octree for increased resolution.  The octree is stored in the rendering context and is
       used automatically in subsequent calls to vpClassifyVolume  and  vpRenderRawVolume.   Only
       one  octree  may  be  stored  in  a  context  at a time.  If an octree already exists when
       vpCreateMinMaxOctree is called then the old octree is destroyed.

       If the data in the voxel  array  changes  then  the  min-max  octree  must  be  explicitly
       recomputed  by calling vpCreateMinMaxOctree again before the next call to vpClassifyVolume
       or vpRenderRawVolume.

       vpDestroyMinMaxOctree destroys  the  current  min-max  octree  and  frees  the  associated
       storage.

STATE VARIABLES

       The  current  octree  parameters  can be retrieved with the following state variable codes
       (see  vpGeti(3)):  VP_CLASSIFY_FIELD_COUNT,  VP_CLASSIFY_FIELDS,   VP_MMOCTREE_THRESHOLDS,
       VP_MMOCTREE_SIZE.

ERRORS

       The  normal  return  value  for all three functions is VP_OK.  vpMinMaxOctreeThreshold can
       return the following error value:

       VPERROR_BAD_VALUE
              The parameter number is invalid.

       vpCreateMinMaxOctree can return the following error values:

       VPERROR_BAD_VALUE
              The node size arguments are not a power of two.

       VPERROR_BAD_VOXEL
              The voxel size or the voxel fields have not been specified or have been incorrectly
              specified,  or  the  number of parameters to the opacity transfer function has 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  fields specified as parameters to the opacity transfer function are invalid or
              do not have valid sizes.

       VPERROR_LIMIT_EXCEEDED
              The volume is too large, so the maximum size  of  the  octree  has  been  exceeded.
              Change  the  constant  VP_MAX_OCTREE_LEVELS  in volpack.h and recompile the VolPack
              library.

SEE ALSO

       VolPack(3), vpCreateContext(3), vpClassifyVolume(3), vpOctreeMask(3), vpRenderRawVolume(3)