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)