Ubuntu Manpage: vpSetLookupShader - specify shading lookup tables

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

NAME

       vpSetLookupShader - specify shading lookup tables

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpSetLookupShader(vpc,    color_channels,    num_materials,    color_field,   color_table,
               color_table_size, weight_field, weight_table, weight_table_size)
           vpContext *vpc;
           int color_channels, num_materials;
           int color_field;
           float *color_table;
           int color_table_size;
           int weight_field;
           float *weight_table;
           int weight_table_size;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       color_channels
              The number of color channels per pixel (1 or 3).

       num_materials
              The number of material types.

       color_field
              Field number for voxel field containing color lookup table index.

       color_table
              Color lookup table.

       color_table_size
              Size of color lookup table in bytes.

       weight_field
              Field number for voxel field containing material weight lookup table index.

       weight_table
              Material weight lookup table.

       weight_table_size
              Size of material weight lookup table in bytes.

DESCRIPTION

vpSetLookupShader is used to specify lookup tables that define a shading function. The
lookup-table shading algorithm provided by VolPack is designed to support the following
shading model. Each voxel is assumed to contain a mixture of some set of basic material
types. Each material type has its own shading parameters for the Phong shading equation
(for example, the diffuse color components and the shinyness). The color of a voxel is
found by computing a color for each material type and then combining the colors in
proportion to the fraction of each material in the voxel. The shading model also supports
directional (infinite-distance) light sources.

This shading model is implemented using lookup tables. The tables can be precomputed so
that the shading equation does not have to be evaluated for every voxel. VolPack provides
routines to compute the lookup tables (see vpShadeTable(3)). The lookup tables can also
be used to implement other shading models by using a user-supplied routine to compute the
contents of the tables. See vpSetDepthCueing(3) for information about depth cueing.

It is also possible to define a callback function that will be called to shade each voxel
during rendering, instead of using a lookup table. This method allows more general
shading models but slows down rendering. To define a callback shader, call vpSetCallback
with the VP_GRAY_SHADE_FUNC or VP_RGB_SHADE_FUNC option code (see vpSetCallback(3)). The
lookup tables are used if the last successful call to vpSetLookupShader occurred after the
last successful call to vpSetCallback with one of the VP_*_SHADE_FUNC options.

The color_channels argument determines whether the shading table will contain grayscale (1
channel) or RGB (3 channel) pixels. The num_materials argument specifies the number of
basic material types out of which each voxel can be composed (at least 1). The
color_table and weight_table arguments specify two lookup tables, and the color_field and
weight_field arguments specify two voxel fields that are used to index the tables. The
size of the color_table array must be: float
color_table[n][num_materials][color_channels]; where n is the number of possible values in
the color_field field of the voxel (the maximum value plus one). The size of the
weight_table argument must be: float weight_table[m][num_materials]; where m is the number
of possible values in the weight_field field of the voxel (the maximum value plus one).
If there is only one material then weight_table is not used and may be a NULL pointer.

During rendering the shading lookup tables are accessed as follows. Suppose a particular
voxel to be shaded has the value color_index in the field specified by color_field and the
value weight_index in the field specified by weight_field. For each material number
material_index, a weighted color is computed from the formula: color =
color_table[color_index][material_index] *
168u' weight_table[weight_index][material_index] Then the weighted colors for each
material type are added up to give the voxel color. If color_table contains RGB values
then each component is treated separately using the above formula. If there is only one
material type then the constant 1.0 is substituted for the weight_table value.

The suggested way to use the tables is as follows. The voxel field specified by
color_field should contain an encoded surface normal vector; this should be the same field
as the norm_field argument to vpVolumeNormals or vpClassifyScalars. In the color_table
array, for each possible encoded surface normal (the color index) and material type (the
material index) the array should contain the color of the material given the current
viewing direction and lighting arrangement. The color is independent of the voxel
location because the light sources are assumed to be infinitely distant. The function
vpShadeTable initializes the contents of color_table in this way.

The voxel field specified by weight_field should contain some quantity that determines the
material composition of the voxel. For example, a field containing the scalar value could
be used. In the weight_table array, for each possible value of weight_field there should
be one row of material occupancy fractions. Each entry should be a number in the range
0.0-1.0 that specifies the fraction of the voxel occupied by the corresponding material.
For example, if there are two material types and a voxel's weight_field contains the value
62, then weight_table[62][0] gives the fraction of the voxel occupied by material 0, and
weight_table[62][1] gives the fraction of the voxel occupied by material 1. Normally, the
numbers in a given row of weight_table should add up to 1.0 (although special effects can
be achieved by bending the rules). The function vpRamp is useful for initializing the
weight table with piece-wise linear ramps.

The values in the shading lookup tables may be initialized before or after calling
vpSetLookupShader. Typically vpSetLookupShader is called once at the beginning of a
rendering session, and then the values in the shading tables are modified as the user
changes the lighting and shading parameters or the viewing direction.

STATE VARIABLES

       Information about the current shading table parameters can be retrieved with the following
       state   variable   codes   (see   vpGeti(3)):   VP_COLOR_CHANNELS,   VP_SHADE_COLOR_TABLE,
       VP_SHADE_COLOR_SIZE,  VP_SHADE_WEIGHT_TABLE,  VP_SHADE_WEIGHT_SIZE,  VP_SHADE_COLOR_FIELD,
       VP_SHADE_WEIGHT_FIELD, VP_MATERIAL_COUNT

ERRORS