1vpSetLookupShader(3) Library Functions Manual vpSetLookupShader(3)
2
6 vpSetLookupShader - specify shading lookup tables
7
9 #include <volpack.h>
10 vpResult
12 vpSetLookupShader(vpc, color_channels, num_materials, color_field,
13 color_table, color_table_size, weight_field, weight_table,
14 weight_table_size)
15 vpContext *vpc;
16 int color_channels, num_materials;
17 int color_field;
18 float *color_table;
19 int color_table_size;
20 int weight_field;
21 float *weight_table;
22 int weight_table_size;
23
25 vpc VolPack context from vpCreateContext.
26 color_channels
28 The number of color channels per pixel (1 or 3).
29 num_materials
31 The number of material types.
32 color_field
34 Field number for voxel field containing color lookup table
35 index.
36 color_table
38 Color lookup table.
39 color_table_size
41 Size of color lookup table in bytes.
42 weight_field
44 Field number for voxel field containing material weight lookup
45 table index.
46 weight_table
48 Material weight lookup table.
49 weight_table_size
51 Size of material weight lookup table in bytes.
52
54 vpSetLookupShader is used to specify lookup tables that define a shad‐
55 ing function. The lookup-table shading algorithm provided by VolPack
56 is designed to support the following shading model. Each voxel is
57 assumed to contain a mixture of some set of basic material types. Each
58 material type has its own shading parameters for the Phong shading
59 equation (for example, the diffuse color components and the shinyness).
60 The color of a voxel is found by computing a color for each material
61 type and then combining the colors in proportion to the fraction of
62 each material in the voxel. The shading model also supports direc‐
63 tional (infinite-distance) light sources.
64 This shading model is implemented using lookup tables. The tables can
66 be precomputed so that the shading equation does not have to be evalu‐
67 ated for every voxel. VolPack provides routines to compute the lookup
68 tables (see vpShadeTable(3)). The lookup tables can also be used to
69 implement other shading models by using a user-supplied routine to com‐
70 pute the contents of the tables. See vpSetDepthCueing(3) for informa‐
71 tion about depth cueing.
72 It is also possible to define a callback function that will be called
74 to shade each voxel during rendering, instead of using a lookup table.
75 This method allows more general shading models but slows down render‐
76 ing. To define a callback shader, call vpSetCallback with the
77 VP_GRAY_SHADE_FUNC or VP_RGB_SHADE_FUNC option code (see vpSetCall‐
78 back(3)). The lookup tables are used if the last successful call to
79 vpSetLookupShader occurred after the last successful call to vpSetCall‐
80 back with one of the VP_*_SHADE_FUNC options.
81 The color_channels argument determines whether the shading table will
83 contain grayscale (1 channel) or RGB (3 channel) pixels. The num_mate‐
84 rials argument specifies the number of basic material types out of
85 which each voxel can be composed (at least 1). The color_table and
86 weight_table arguments specify two lookup tables, and the color_field
87 and weight_field arguments specify two voxel fields that are used to
88 index the tables. The size of the color_table array must be: float
89 color_table[n][num_materials][color_channels]; where n is the number of
90 possible values in the color_field field of the voxel (the maximum
91 value plus one). The size of the weight_table argument must be: float
92 weight_table[m][num_materials]; where m is the number of possible val‐
93 ues in the weight_field field of the voxel (the maximum value plus
94 one). If there is only one material then weight_table is not used and
95 may be a NULL pointer.
96 During rendering the shading lookup tables are accessed as follows.
98 Suppose a particular voxel to be shaded has the value color_index in
99 the field specified by color_field and the value weight_index in the
100 field specified by weight_field. For each material number mate‐
101 rial_index, a weighted color is computed from the formula: color =
102 color_table[color_index][material_index] *
103 weight_table[weight_index][material_index] Then the weighted
104 colors for each material type are added up to give the voxel color. If
105 color_table contains RGB values then each component is treated sepa‐
106 rately using the above formula. If there is only one material type
107 then the constant 1.0 is substituted for the weight_table value.
108 The suggested way to use the tables is as follows. The voxel field
110 specified by color_field should contain an encoded surface normal vec‐
111 tor; this should be the same field as the norm_field argument to vpVol‐
112 umeNormals or vpClassifyScalars. In the color_table array, for each
113 possible encoded surface normal (the color index) and material type
114 (the material index) the array should contain the color of the material
115 given the current viewing direction and lighting arrangement. The
116 color is independent of the voxel location because the light sources
117 are assumed to be infinitely distant. The function vpShadeTable ini‐
118 tializes the contents of color_table in this way.
119 The voxel field specified by weight_field should contain some quantity
121 that determines the material composition of the voxel. For example, a
122 field containing the scalar value could be used. In the weight_table
123 array, for each possible value of weight_field there should be one row
124 of material occupancy fractions. Each entry should be a number in the
125 range 0.0-1.0 that specifies the fraction of the voxel occupied by the
126 corresponding material. For example, if there are two material types
127 and a voxel's weight_field contains the value 62, then weight_ta‐
128 ble[62][0] gives the fraction of the voxel occupied by material 0, and
129 weight_table[62][1] gives the fraction of the voxel occupied by mate‐
130 rial 1. Normally, the numbers in a given row of weight_table should
131 add up to 1.0 (although special effects can be achieved by bending the
132 rules). The function vpRamp is useful for initializing the weight ta‐
133 ble with piece-wise linear ramps.
134 The values in the shading lookup tables may be initialized before or
136 after calling vpSetLookupShader. Typically vpSetLookupShader is called
137 once at the beginning of a rendering session, and then the values in
138 the shading tables are modified as the user changes the lighting and
139 shading parameters or the viewing direction.
140
142 Information about the current shading table parameters can be retrieved
143 with the following state variable codes (see vpGeti(3)): VP_COLOR_CHAN‐
144 NELS, VP_SHADE_COLOR_TABLE, VP_SHADE_COLOR_SIZE, VP_SHADE_WEIGHT_TABLE,
145 VP_SHADE_WEIGHT_SIZE, VP_SHADE_COLOR_FIELD, VP_SHADE_WEIGHT_FIELD,
146 VP_MATERIAL_COUNT
147
149 The normal return value is VP_OK. The following error return values
150 are possible:
151 VPERROR_BAD_VALUE
153 One or more of the arguments has an invalid value or is out of
154 range.
155 VPERROR_LIMIT_EXCEEDED
157 The num_materials argument has exceeded an internal limit.
158 Change the value of VP_MAX_MATERIAL in volpack.h and recompile
159 the VolPack library.
160
162 VolPack(3), vpCreateContext(3), vpShadeTable(3), vpSetCallback(3),
163 vpRamp(3), vpVolumeNormals(3), vpClassifyScalars(3), vpSetDepthCue‐
164 ing(3)
165VolPack vpSetLookupShader(3)