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.