.\" Copyright (c) 1994 The Board of Trustees of The Leland Stanford
.\" Junior University.  All rights reserved.
.\" 
.\" Permission to use, copy, modify and distribute this software and its
.\" documentation for any purpose is hereby granted without fee, provided
.\" that the above copyright notice and this permission notice appear in
.\" all copies of this software and that you do not sell the software.
.\" Commercial licensing is available by contacting the author.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
.\" 
.\" Author:
.\"    Phil Lacroute
.\"    Computer Systems Laboratory
.\"    Electrical Engineering Dept.
.\"    Stanford University
.\" 
.\" $Date: 1994/12/31 19:49:53 $
.\" $Revision: 1.1 $
.\"
.\" Macros
.\" .FS <type>  --  function start
.\"     <type> is return type of function
.\"     name and arguments follow on next line
.de FS
.PD 0v
.PP
\\$1
.HP 8
..
.\" .FA  --  function arguments
.\"     one argument declaration follows on next line
.de FA
.IP " " 4
..
.\" .FE  --  function end
.\"     end of function declaration
.de FE
.PD
..
.\" .DS  --  display start
.de DS
.IP " " 4
..
.\" .DE  --  display done
.de DE
.LP
..
.TH vpSetDepthCueing 3 "" VolPack
.SH NAME
vpSetDepthCueing \- set depth cueing parameters
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpSetDepthCueing(\fIvpc, front_factor, density\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
double \fIfront_factor;\fR
.FA
double \fIdensity;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIfront_factor\fR
Depth cueing factor at the front clipping plane.
.IP \fIdensity\fR
Fog density.
.SH DESCRIPTION
\fBvpSetDepthCueing\fR 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.
.PP
The \fIfront_factor\fR 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 \fIdensity\fR 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:
.DS
T = front_factor * exp(-density * depth)
.DE
where \fIdepth\fR 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.
.PP
By default, depth cueing is not enabled.  To enable it, call
\fBvpEnable\fR with the VP_DEPTH_CUE option.
.PP
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 \fBvpSetd\fR) 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.
.PP
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 \fBvpGeti\fR 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 \fBvpSeti\fR) 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.
.SH "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.
.SH ERRORS
The normal return value is VP_OK.  The following error return value is
possible:
.IP VPERROR_BAD_VALUE
The value of \fIfront_factor\fR is not positive.
.SH SEE ALSO
VolPack(3), vpCreateContext(3), vpSetLookupShader(3)