NAME

       vpNormalIndex, vpNormal - encode/decode a surface normal vector

SYNOPSIS

       #include <volpack.h>

       int
       vpNormalIndex(nx, ny, nz)
           double nx, ny, nz;

       vpResult
       vpNormal(n, nx_ptr, ny_ptr, nz_ptr)
           int n;
           double *nx_ptr, *ny_ptr, *nz_ptr;

ARGUMENTS

       nx     X component of surface normal vector.

       ny     Y component of surface normal vector.

       nz     Z component of surface normal vector.

       n      Encoded surface normal vector.

       nx_ptr Pointer to storage for returning X component of surface normal vector.

       ny_ptr Pointer to storage for returning Y component of surface normal vector.

       nz_ptr Pointer to storage for returning Z component of surface normal vector.

DESCRIPTION

       These  two  routines  are  used  to  convert  surface  normal  vectors between encoded and
       unencoded forms.  An unencoded vector is described by  its  three  components  (stored  as
       double-precision  floating  point numbers) in an orthogonal coordinate system.  An encoded
       vector is described by a single integer that is suitable for use as an index in a  shading
       lookup  table.   VolPack's  built-in  shading  routines  require the use of surface normal
       vectors encoded using vpNormalIndex (or one of the higher-level normal vector  computation
       routines,  vpVolumeNormals or vpScanlineNormals).  User-defined shading routines or lookup
       tables are not required to use encoded normal vectors.

       vpNormalIndex computes an encoded vector from the components of an unencoded vector.   The
       vector  must  be normalized (nx*nx + ny*ny + nz*nz = 1).  The maximum possible value of an
       encoded normal is given by the constant VP_NORM_MAX.

       vpNormal computes the components of a vector from the encoded integer form.   The  encoded
       normal has less resolution than the unencoded form, so the vector computed by vpNormal may
       not be equal to the original vector passed to vpNormalIndex.

ERRORS

       vpNormalIndex always returns a valid encoded normal vector.

       vpNormal normally returns the value VP_OK.  The following return value is possible:

       VPERROR_BAD_VALUE
              The encoded normal vector is invalid.

SEE ALSO

       VolPack(3), vpVolumeNormals(3), vpScanlineNormals(3)