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)