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)