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] *
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
The normal return value is VP_OK. The following error return values
are possible:
VPERROR_BAD_VALUE
One or more of the arguments has an invalid value or is out of
range.
VPERROR_LIMIT_EXCEEDED
The num_materials argument has exceeded an internal limit.
Change the value of VP_MAX_MATERIAL in volpack.h and recompile
the VolPack library.
SEE ALSO
VolPack(3), vpCreateContext(3), vpShadeTable(3), vpSetCallback(3),
vpRamp(3), vpVolumeNormals(3), vpClassifyScalars(3),
vpSetDepthCueing(3)