Man Linux: Main Page and Category List

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)