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)