Man Linux: Main Page and Category List

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)