NAME

       vpVolumeNormals - compute surface normal vectors and gradient magnitudes for a volume

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpVolumeNormals(vpc, scalar_data, length, scalar_field, grad_field, norm_field)
           vpContext *vpc;
           unsigned char *scalar_data;
           int length;
           int scalar_field;
           int grad_field;
           int norm_field;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       scalar_data
              3D array of scalar samples.

       length Size of scalar_data array in bytes.

       scalar_field
              Voxel field number indicating the field in which to store the scalar samples.

       grad_field
              Voxel  field  number indicating the field in which to store the gradient magnitudes
              of the scalar samples.

       norm_field
              Voxel field number indicating the field in which to store  encoded  surface  normal
              vectors.

DESCRIPTION

       vpVolumeNormals  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.

       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 vpSetVolumeSize.  The size argument is used to make sure the array has  the
       correct size.  The voxel array must also be initialized by calling vpSetRawVoxels prior to
       calling vpVolumeNormals.

       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  vpSetVoxelField.  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).

ERRORS

       The normal return value is VP_OK.  The following error return values are possible:

       VPERROR_BAD_SIZE
              The size of the scalar array does not match the volume dimensions.

       VPERROR_BAD_VALUE
              One  or  more  of the voxel fields specified is invalid, or the corresponding voxel
              field has the wrong size.

       VPERROR_BAD_VOXEL
              The voxel size or the voxel fields have not been specified or have been incorrectly
              specified.

       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.

SEE ALSO

       VolPack(3),       vpCreateContext(3),       vpNormalIndex(3),        vpScanlineNormals(3),
       vpSetClassifierTable(3), vpSetLookupShader(3)