Ubuntu Manpage: vpSetMaterial - set material properties

name
synopsis
arguments
description
state variables
errors
see also

Provided by: libvolpack1-dev_1.0b3-10_amd64

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.