NAME

       vpOctreeMask - compute a mask representing one level of a min-max octree

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpOctreeMask(vpc, array, array_size, max_level)
           vpContext *vpc;
           unsigned char *array;
           int array_size;
           int max_level;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       array  A 3D array for storing the mask.

       array_size
              Size of array in bytes.

       max_level
              Maximum octree level to descend to.

DESCRIPTION

       vpOctreeMask  is  used  for  performance  debugging  when rendering volumes with a min-max
       octree.  During rendering the min-max octree is used to help determine  which  voxels  are
       transparent.   The  time  required  to  make  this  determination  can  be minimized by an
       appropriate choice for the range parameters for vpMinMaxOctreeThreshold and the node  size
       parameters  for  vpCreateMinMaxOctree.  vpOctreeMask provides information that can help to
       determine whether a set of parameters works effectively or not.

       The output of the routine is stored in a 3D array of bytes that has the same dimensions as
       the  volume  (although  each element is only one byte, regardless of the size of a voxel).
       For each voxel in the volume the  corresponding  byte  in  the  output  array  is  set  by
       vpOctreeMask  to one of three values: 0 if the voxel is definitely transparent, 255 if the
       voxel may be non-transparent, or 128 if the voxel may be non-transparent and there is more
       detailed  information available at unvisited levels of the octree.  The max_level argument
       specifies the deepest level of the octree to be visited (the root level is level 0).

       A suggested way to use this routine is to compute an octree  using  a  particular  set  of
       parameters  and  then  call vpOctreeMask with several different values for max_level.  For
       each resulting mask array, look at slices (or create a  volume  rendering!)  and  see  how
       accurately  the  mask  captures the general shape of the data in the original volume.  The
       best set of parameters results in a mask  that  captures  the  general  shape  without  an
       excessively  small  value  for  the minimum octree node size (which would result in a very
       large data structure and a lot of traversal overhead).

ERRORS

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

       VPERROR_BAD_SIZE
              There is no octree or the output array has the wrong size.

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

       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), vpCreateMinMaxOctree(3)