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)