NAME¶
vpSetMaterial - set material properties
SYNOPSIS¶
#include <volpack.h>
vpResult
vpSetMaterial(vpc,
material, property, surface_side, r, g, b )
-
- vpContext *vpc;
-
- int material;
-
- int property;
-
- int surface_side;
-
- double r, g, b;
ARGUMENTS¶
- vpc
- VolPack context from vpCreateContext.
- material
- A constant specifying a particular material number
(VP_MATERIAL0, VP_MATERIAL1, ..., VP_MATERIAL5).
- property
- A constant specifying one material property (VP_AMBIENT,
VP_DIFFUSE, VP_SPECULAR or VP_SHINYNESS).
- surface_side
- A constant specifying which side of the material surface
the properties apply to (VP_EXTERIOR, VP_INTERIOR or VP_BOTH_SIDES).
- r, g, b
- RGB components of the color associated with the property.
For VP_SHINYNESS, g and b are not used.
DESCRIPTION¶
vpSetMaterial is used to set the properties of a material type. Each
voxel may be composed of a mixture of several different material types, as
described in vpSetLookupShader(3). Each material type has its own color and
light reflection properties. The properties are used as parameters to the
Phong shading equation for computing the color of the material given a set of
light sources and a viewing direction (see vpShadeTable(3)).
To initialize the material parameters, call
vpSetMaterial for each
property of each material type to be used. The total number of materials is
specified as an argument to
vpSetLookupShader. The first material is
specified by the constant VP_MATERIAL0, the second is VP_MATERIAL1, and so on.
The VP_AMBIENT property specifies the RGB ambient light coefficients of the
material. This term represents the intensity of background light reflected by
the material. Each of the RGB components specifies the coefficient for the
corresponding light basis function. The values of the coefficients should be
in the range 0.0-1.0. Default: 0.1
The VP_DIFFUSE property specifies the RGB diffuse light coefficients of the
material. This term represents the fraction of incident light intensity that
is reflected diffusely (with a dull, matte appearance). The values of the
coefficients should be in the range 0.0-1.0. Default: 0.4
The VP_SPECULAR property specifies the RGB specular light coefficients of the
material. This term represents the fraction of incident light intensity that
is reflected specularly (with a shiny, mirror-like appearance). The values of
the coefficients should be in the range 0.0-1.0. Default: 0.5
The VP_SHINYNESS property specifies a single exponent that modifies the spread
of specular highlights. The higher the number, the smaller and more intense
the specular highlights. The exponent is specified with the
r argument
and can have any value; the generally-useful range is 1.0 to 100.0. The
g and
b arguments are ignored for this property. Default: 10.0
The
surface_side argument specifies which side of the material surface
the properties apply to. By default, the "interior" side of a voxel
is the side in the direction of the surface normal. During rendering, if the
normal points closer to the direction of the viewer than the opposite of the
normal then the viewer is looking at the exterior side of the voxel rather
than the interior. Different material parameters can be applied to the two
surface sides by calling
vpSetMaterial separately for each side. The
option VP_BOTH_SIDES allows the same property to be set for both sides with
only one function call. It is possible to reverse the definition of interior
and exterior sides by calling
vpEnable with the
VP_REVERSE_SURFACE_SIDES option.
Voxels are shaded using the following equation:
-
- I = A + L * (D * n_dot_l + S * pow(n_dot_h, E))
I intensity for one color channel
A ambient intensity coefficient
D diffuse reflection coefficient
S specular reflection coefficient
E shinyness
L light intensity
n_dot_l dot product of normal and light vectors
n_dot_h dot product of normal and highlight vectors
This equation is evaluated separately for each color channel. If multiple light
sources are enabled an additional term identical to the second term above is
added for each light source (with different values for L, n_dot_l and n_dot_h
corresponding to the particular light source).
STATE VARIABLES¶
Information about the current material properties can be retrieved with the
following state variable codes (see vpGeti(3)): VP_MATERIAL_COUNT,
VP_REVERSE_SURFACE_SIDES
ERRORS¶
The normal return value is VP_OK. The following error return values are
possible:
- VPERROR_BAD_VALUE
- Either the material number or the RGB components are
invalid.
- VPERROR_BAD_OPTION
- Either the surface_side or property arguments
are invalid.
SEE ALSO¶
VolPack(3), vpCreateContext(3), vpSetLookupShader(3), vpShadeTable(3),
vpGetMaterial(3)