Ubuntu Manpage: vpSetDepthCueing - set depth cueing parameters

Provided by: libvolpack1-dev_1.0b3-9_amd64

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