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)