Provided by: libvolpack1-dev_1.0b3-9.1_amd64 bug

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

       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)