Provided by: libvolpack1-dev_1.0b3-3_amd64 bug

NAME

       vpSetDepthCueing - set depth cueing parameters

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpSetDepthCueing(vpc, front_factor, density)
           vpContext *vpc;
           double front_factor;
           double density;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       front_factor
              Depth cueing factor at the front clipping plane.

       density
              Fog density.

DESCRIPTION

       vpSetDepthCueing  is  used  to  set  the  parameters  for depth cueing.  Depth cueing is a
       simulated fog that makes objects in the distance appear darker  than  foreground  objects.
       Depth  cueing  is  independent  of  the  shading method.  It can be used with lookup-table
       shading or callback-function shading.  Depth cueing is not stored in  the  shading  lookup
       table; it is always applied to voxels at rendering time.

       The  front_factor argument is the transparency of the fog at the front clipping plane (see
       vpWindow(3) or vpWindowPHIGS(3)).  It must be a positive number and is usually  less  than
       1.0  (although  larger  numbers  can  be  used  to  brighten the foreground).  The density
       argument controls the "density" of the fog.  Increasing  the  density  causes  objects  to
       recede  into  darkness  over a shorter distance.  The equation for the transparency of the
       fog at a particular voxel is: T = front_factor * exp(-density * depth) where depth is 0 at
       the  front clipping plane and 1 at the back clipping plane.  Each voxel color component is
       multiplied by the fog transparency during rendering.

       By default,  depth  cueing  is  not  enabled.   To  enable  it,  call  vpEnable  with  the
       VP_DEPTH_CUE option.

       Depth  cueing  is  implemented  using  an  internal lookup table (unrelated to the shading
       lookup table).  There are several VolPack state variables that  affect  the  depth  cueing
       table,  although  they  should  not  usually  be changed.  The table contains depth cueing
       factors as a function of depth.  The table must contain entries for depths  in  the  range
       0.0-1.0,  and  possibly  for negative depths depending upon the current viewing parameters
       (the reason for this is beyond the scope of a man  page).   The  VP_DEPTH_CUE_QUANTIZATION
       variable  (which can be set by calling vpSetd) determines the depth difference between two
       adjacent entries in the depth cueing table.  For instance,  the  default  quantization  of
       1/255  specifies  that each entry in the table represents 1/255 times the distance between
       the front and back clipping planes.  Reducing the  quantization  increases  the  size  and
       accuracy of the depth cueing table.

       Normally   the  depth  cueing  table  is  resized  and  recomputed  only  when  necessary.
       Recomputation may be required if the viewpoint changes,  increasing  the  range  of  voxel
       depths  that  are encountered (recall that there is no lower bound on the depth).  You can
       use vpGeti with the VP_DEPTH_CUE_TABLE_SIZE state variable code to get the current  number
       of  table  entries.   You  can  also  set the value of VP_DEPTH_CUE_TABLE_SIZE_HINT (using
       vpSeti) to suggest a size for the table.  This might be desirable if you plan  to  compute
       an  animation  loop  and  want  to  ensure that the depth cueing table does not need to be
       recomputed in the middle of  the  sequence.   However,  since  recomputing  the  table  is
       relatively inexpensive, it should not be necessary to use this option.

STATE VARIABLES

       Information  about the current depth cueing properties can be retrieved with the following
       state    variable    codes    (see    vpGeti(3)):    VP_DEPTH_CUE,     VP_DEPTH_CUE_FRONT,
       VP_DEPTH_CUE_DENSITY,           VP_DEPTH_CUE_TABLE_SIZE,           VP_DEPTH_CUE_SIZE_HINT,
       VP_DEPTH_CUE_QUANTIZATION.

ERRORS

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

       VPERROR_BAD_VALUE
              The value of front_factor is not positive.

SEE ALSO

       VolPack(3), vpCreateContext(3), vpSetLookupShader(3)