NAME

       vpSetLight - set lighting properties

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpSetLight(vpc, light_num, property, n0, n1, n2)
           vpContext *vpc;
           int light_num;
           int property;
           double n0, n1, n2;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       light_num
              A  constant  specifying  a  particular  light  source  (VP_LIGHT0,  VP_LIGHT1, ...,
              VP_LIGHT5).

       property
              A constant specifying one lighting property (VP_COLOR or VP_DIRECTION).

       n0, n1, n2
              Components of an RGB color (for VP_COLOR) or a direction vector (for VP_DIRECTION).

DESCRIPTION

       vpSetLight is used to set the properties  of  a  light  source.   VolPack  currently  only
       supports  directional  light sources: each light is infinitely distant, so it can be fully
       characterized by a direction vector and a color.  The  lighting  properties  are  used  by
       vpShadeTable  to  compute  the shading lookup table, which is then used to compute a color
       for each voxel.

       To initialize the lighting environment, call vpSetLight twice for each light source  which
       will  be enabled.  One call should set the RGB components of the light color (by using the
       VP_COLOR code for the property parameter), and one call should set the XYZ  components  of
       the  light  direction  vector (by using the VP_DIRECTION code for the property parameter).
       The particular light source is specified with one of the light  source  codes  defined  in
       volpack.h:  VP_LIGHT0,  VP_LIGHT1, ..., VP_LIGHT5.  In the current implementation, at most
       six light sources may be specified.

       The RGB components of a light color should be numbers in the range 0.0 (zero intensity) to
       1.0 (full intensity).  For grayscale renderings only the first (red) component is used and
       the other components may be set to any legal value.  The default is white light (1.0, 1.0,
       1.0).

       The  light  direction  vector  points from the light source towards the lit object.  It is
       transformed by the current contents of the modeling matrix  (see  vpCurrentMatrix).   This
       allows  the  direction  vector to be specified in an arbitrary coordinate system, provided
       the current modeling matrix properly transforms the vector into  world  coordinates.   The
       default is the vector (1,1,1).

       Each  light source contributes to the shading computation only if it is enabled by calling
       vpEnable.  By default, VP_LIGHT0 is enabled and all other lights are disabled.   The  more
       light  sources  that  are  enabled,  the longer it takes to precompute the contents of the
       shading lookup table.

       One  additional  property   of   the   light   sources   can   be   set   with   vpEnable:
       VP_LIGHT_BOTH_SIDES.   With  this  option enabled each light source shines in two opposing
       directions, as if there were two light sources facing each other with  opposite  direction
       vectors.  No additional computation is required when this option is enabled.

STATE VARIABLES

       Information  about  the  current  lighting  properties can be retrieved with the following
       state variable codes (see vpGeti(3)): VP_LIGHT_BOTH_SIDES.

ERRORS

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

       VPERROR_LIMIT_EXCEEDED
              The light number is invalid or exceeds an implementation limit.

       VPERROR_SINGULAR
              The light direction vector is a zero vector.

       VPERROR_BAD_VALUE
              The RGB color components are out of range.

       VPERROR_BAD_OPTION
              The property argument is invalid.

SEE ALSO

       VolPack(3), vpCreateContext(3), vpSetLookupShader(3), vpShadeTable(3), vpGetLight(3)