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)