.\" 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 vpVolumeNormals 3 "" VolPack
.SH NAME
vpVolumeNormals \- compute surface normal vectors and gradient
magnitudes for a volume
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpVolumeNormals(\fIvpc, scalar_data, length, scalar_field,
grad_field, norm_field\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
unsigned char *\fIscalar_data;\fR
.FA
int \fIlength;\fR
.FA
int \fIscalar_field;\fR
.FA
int \fIgrad_field;\fR
.FA
int \fInorm_field;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIscalar_data\fR
3D array of scalar samples.
.IP \fIlength\fR
Size of \fIscalar_data\fR array in bytes.
.IP \fIscalar_field\fR
Voxel field number indicating the field in which to store the scalar
samples.
.IP \fIgrad_field\fR
Voxel field number indicating the field in which to store the gradient
magnitudes of the scalar samples.
.IP \fInorm_field\fR
Voxel field number indicating the field in which to store encoded
surface normal vectors.
.SH DESCRIPTION
\fBvpVolumeNormals\fR is used to precompute values for voxel fields
used in classification and shading algorithms.  The input is a 3D
array of scalar values; a separate routine is provided for processing
scanlines of voxel data (see vpScanlineNormals(3)).  For each voxel, the
routine computes an approximation for the gradient of the scalar field
(using a central-difference operator).  From this vector the routine
can compute the magnitude of the gradient, which is useful for some
classification schemes (see vpSetClassifierTable(3)), and a surface normal
vector in the direction of the gradient vector, which is used to
implement lighting models (see vpShadeTable(3)).  The scalar value,
gradient magnitude and surface normal vector are then stored into the
fields of the voxel array, which is separate from the array of scalar
values.
.PP
The scalar array must be an array of 8-bit values (other sizes are not
currently supported).  The dimensions of the array must match the
volume dimensions previously specified with \fBvpSetVolumeSize\fR.
The \fIsize\fR argument is used to make sure the array has the correct
size.  The voxel array must also be initialized by calling
\fBvpSetRawVoxels\fR prior to calling \fBvpVolumeNormals\fR.
.PP
The three voxel field number arguments indicate which voxel fields the
computed information should be stored into, and which field the scalar
samples should be copied to.  The field numbers must correspond to
appropriately-sized voxel fields previously specified with
\fBvpSetVoxelField\fR.  Any of these arguments can be the constant
VP_SKIP_FIELD, in which case the corresponding quantity is not
computed or copied.  The voxel fields for the scalar value and the
gradient magnitude must be one-byte fields, and the field for the
surface normal vector must be a two-byte field.  The constants
VP_SCALAR_MAX, VP_GRAD_MAX and VP_NORM_MAX give the maximum value that
might be stored in each field, respectively.  The value stored in the
surface normal vector field is actually an encoded surface normal; see
vpNormalIndex(3).
.SH ERRORS
The normal return value is VP_OK.  The following error return values are
possible:
.IP VPERROR_BAD_SIZE
The size of the scalar array does not match the volume dimensions.
.IP VPERROR_BAD_VALUE
One or more of the voxel fields specified is invalid, or the
corresponding voxel field has the wrong size.
.IP VPERROR_BAD_VOXEL
The voxel size or the voxel fields have not been specified or have
been incorrectly specified.
.IP VPERROR_BAD_VOLUME
The volume array or volume dimensions have not been specified, or the
size of the volume array does not match the volume dimensions.
.SH SEE ALSO
VolPack(3), vpCreateContext(3), vpNormalIndex(3),
vpScanlineNormals(3), vpSetClassifierTable(3), vpSetLookupShader(3)