.\" Copyright (c) 1994 The Board of Trustees of The Leland Stanford .\" Junior University. All rights reserved. .\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation for any purpose is hereby granted without fee, provided .\" that the above copyright notice and this permission notice appear in .\" all copies of this software and that you do not sell the software. .\" Commercial licensing is available by contacting the author. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. .\" .\" Author: .\" Phil Lacroute .\" Computer Systems Laboratory .\" Electrical Engineering Dept. .\" Stanford University .\" .\" $Date: 1994/12/31 19:49:53 $ .\" $Revision: 1.1 $ .\" .\" Macros .\" .FS -- function start .\" is return type of function .\" name and arguments follow on next line .de FS .PD 0v .PP \\$1 .HP 8 .. .\" .FA -- function arguments .\" one argument declaration follows on next line .de FA .IP " " 4 .. .\" .FE -- function end .\" end of function declaration .de FE .PD .. .\" .DS -- display start .de DS .IP " " 4 .. .\" .DE -- display done .de DE .LP .. .TH vpSetLookupShader 3 "" VolPack .SH NAME vpSetLookupShader \- specify shading lookup tables .SH SYNOPSIS #include .sp .FS vpResult \fBvpSetLookupShader(\fIvpc, color_channels, num_materials, color_field, color_table, color_table_size, weight_field, weight_table, weight_table_size\fB)\fR .FA vpContext *\fIvpc;\fR .FA int \fIcolor_channels, num_materials;\fR .FA int \fIcolor_field;\fR .FA float *\fIcolor_table;\fR .FA int \fIcolor_table_size;\fR .FA int \fIweight_field;\fR .FA float *\fIweight_table;\fR .FA int \fIweight_table_size;\fR .FE .SH ARGUMENTS .IP \fIvpc\fR VolPack context from \fBvpCreateContext.\fR .IP \fIcolor_channels\fR The number of color channels per pixel (1 or 3). .IP \fInum_materials\fR The number of material types. .IP \fIcolor_field\fR Field number for voxel field containing color lookup table index. .IP \fIcolor_table\fR Color lookup table. .IP \fIcolor_table_size\fR Size of color lookup table in bytes. .IP \fIweight_field\fR Field number for voxel field containing material weight lookup table index. .IP \fIweight_table\fR Material weight lookup table. .IP \fIweight_table_size\fR Size of material weight lookup table in bytes. .SH DESCRIPTION \fBvpSetLookupShader\fR 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. .PP 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. .PP 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 \fBvpSetCallback\fR 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 \fBvpSetLookupShader\fR occurred after the last successful call to \fBvpSetCallback\fR with one of the VP_*_SHADE_FUNC options. .PP The \fIcolor_channels\fR argument determines whether the shading table will contain grayscale (1 channel) or RGB (3 channel) pixels. The \fInum_materials\fR argument specifies the number of basic material types out of which each voxel can be composed (at least 1). The \fIcolor_table\fR and \fIweight_table\fR arguments specify two lookup tables, and the \fIcolor_field\fR and \fIweight_field\fR arguments specify two voxel fields that are used to index the tables. The size of the \fIcolor_table\fR array must be: .DS float \fIcolor_table[n][num_materials][color_channels];\fR .DE where \fIn\fR is the number of possible values in the \fIcolor_field\fR field of the voxel (the maximum value plus one). The size of the \fIweight_table\fR argument must be: .DS float \fIweight_table[m][num_materials];\fR .DE where \fIm\fR is the number of possible values in the \fIweight_field\fR field of the voxel (the maximum value plus one). If there is only one material then \fIweight_table\fR is not used and may be a NULL pointer. .PP During rendering the shading lookup tables are accessed as follows. Suppose a particular voxel to be shaded has the value \fIcolor_index\fR in the field specified by \fIcolor_field\fR and the value \fIweight_index\fR in the field specified by \fIweight_field\fR. For each material number \fImaterial_index,\fR a weighted color is computed from the formula: .DS color =\kx color_table[color_index][material_index] * .br \h.\nxu' weight_table[weight_index][material_index] .DE Then the weighted colors for each material type are added up to give the voxel color. If \fIcolor_table\fR 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 \fIweight_table\fR value. .PP The suggested way to use the tables is as follows. The voxel field specified by \fIcolor_field\fR should contain an encoded surface normal vector; this should be the same field as the \fInorm_field\fR argument to \fBvpVolumeNormals\fR or \fBvpClassifyScalars\fR. In the \fIcolor_table\fR array, for each possible encoded surface normal (the \fIcolor\fR index) and material type (the \fImaterial\fR 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 \fBvpShadeTable\fR initializes the contents of \fIcolor_table\fR in this way. .PP The voxel field specified by \fIweight_field\fR 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 \fIweight_table\fR array, for each possible value of \fIweight_field\fR 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 \fIweight_field\fR contains the value 62, then \fIweight_table\fR[62][0] gives the fraction of the voxel occupied by material 0, and \fIweight_table\fR[62][1] gives the fraction of the voxel occupied by material 1. Normally, the numbers in a given row of \fIweight_table\fR should add up to 1.0 (although special effects can be achieved by bending the rules). The function \fBvpRamp\fR is useful for initializing the weight table with piece-wise linear ramps. .PP The values in the shading lookup tables may be initialized before or after calling \fBvpSetLookupShader.\fR Typically \fBvpSetLookupShader\fR 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. .SH "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 .SH ERRORS The normal return value is VP_OK. The following error return values are possible: .IP VPERROR_BAD_VALUE One or more of the arguments has an invalid value or is out of range. .IP VPERROR_LIMIT_EXCEEDED The \fInum_materials\fR argument has exceeded an internal limit. Change the value of VP_MAX_MATERIAL in volpack.h and recompile the VolPack library. .SH SEE ALSO VolPack(3), vpCreateContext(3), vpShadeTable(3), vpSetCallback(3), vpRamp(3), vpVolumeNormals(3), vpClassifyScalars(3), vpSetDepthCueing(3)