NAME
vpRenderRawVolume, vpRenderClassifiedVolume - render a volume
SYNOPSIS
#include <volpack.h>
vpResult
vpRenderRawVolume(vpc)
vpContext *vpc;
vpResult
vpRenderClassifiedVolume(vpc)
vpContext *vpc;
ARGUMENTS
vpc VolPack context from vpCreateContext.
DESCRIPTION
These routines are used to render a volume using the parameters in a
rendering context. vpRenderRawVolume renders the data in the current
voxel array and stores the result in the current image array. If an
octree is present in the context (see vpCreateMinMaxOctree(3)) then it
is used to accelerate rendering. vpRenderClassifiedVolume is identical
in function except that it renders the current preclassified volume
(see vpClassifyVolume(3)) instead of the voxel array, and the octree is
not used.
vpRenderClassifiedVolume should be used when the same volume is
rendered multiple times with the same opacity transfer function. This
rendering mode is the fastest. The opacity transfer function must not
change because the voxel opacities must be fixed to compute a
preclassified volume.
vpRenderRawVolume should be used when the volume data or the opacity
transfer function changes in between renderings. If the volume data
remains fixed then a min-max octree should be computed to accelerate
rendering. Rendering is significantly faster with an octree than
without, although it is still slower than rendering with
vpRenderClassifiedVolume.
Before the rendering routines are called the rendering context must be
initialized to set the volume parameters, classification parameters
(vpRenderRawVolume only), viewing parameters, shading and lighting
parameters, and image array. See VolPack(3) for a list of relevant
functions.
One important state variable should be adjusted before calling the
rendering routines: the maximum opacity threshold. This number
specifies a threshold value for the opacity of an image pixel. If the
opacity of the pixel reaches the threshold then no more voxels are
composited into the pixel. The threshold should be a number slightly
less than one (0.95 is a good value); numbers closer to 1.0 result in
longer rendering times, but less error. The value of the threshold is
changed by calling vpSetd with the VP_MAX_RAY_OPACITY option. The
default value is 1.0.
There are two additional state variables that can be adjusted to set
the size of an internal data structure. During rendering, a work
buffer called the intermediate image is used to hold temporary results.
The size of this data structure depends on the size of the volume and
the current view transformation matrix. Over the course of an
animation sequence the intermediate image may have to be enlarged
multiple times, resulting in many calls to the memory allocator.
Normally the overhead of reallocating the data structure is negligible
and can be ignored. However, this overhead can be eliminated by
specifying hints for the maximum size of the intermediate image. The
data structure will then be allocated once, and will never be
reallocated unless an even larger intermediate image is required. To
set the size hints, call vpSeti with the VP_INT_WIDTH_HINT and
VP_INT_HEIGHT_HINT state variable codes. If the viewing transformation
does not include any scaling, then the maximum possible size of each
dimension of the intermediate image is twice the size of the largest
dimension of the volume. To get a more precise bound, the intermediate
image size required for rendering a volume with the current viewing
parameters can be found by calling vpGeti with the
VP_INTERMEDIATE_WIDTH and VP_INTERMEDIATE_HEIGHT state variable codes.
ERRORS
The normal return value is VP_OK. The following error return values
are possible:
VPERROR_BAD_SHADER
The shading lookup tables are sized incorrectly, or one of the
voxel fields used to index the tables is invalid, or the number
of material types is invalid.
VPERROR_SINGULAR
One of the current view transformation matrices is singular.
VPERROR_BAD_VOLUME
The volume size has not been set or is invalid, or there is no
volume data.
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. (vpRenderRawVolume only)
VPERROR_BAD_SHADOW
The angle between the shadow light vector and the viewing
direction is too large (must be less than 45 degrees). Either
change the light direction or disable shadows (see
vpSetShadowLookupShader).
SEE ALSO
VolPack(3), vpCreateContext(3)