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)

VolPack                                                                                            vpSetLight(3)