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

NAME

       vpSetShadowLookupShader - specify shading lookup tables for rendering shadows

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpSetShadowLookupShader(vpc,   color_channels,  num_materials,  color_field,  color_table,
               color_table_size,  weight_field,  weight_table,  weight_table_size,  shadow_table,
               shadow_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;
           float *shadow_table;
           int shadow_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.

       shadow_table
              Shadow color lookup table.

       shadow_table_size
              Size of shadow color lookup table in bytes.

DESCRIPTION

       vpSetShadowLookupShader  is  used  to specify lookup tables that define a shading function
       for rendering a volume with shadows.  It should be used instead of vpSetLookupShader  when
       shadows are enabled.

       VolPack  supports  a fast, one-pass shadow algorithm.  The algorithm computes the fraction
       of light from a given light source that reaches each voxel.  The fraction is then used  to
       attenuate  the  diffuse  and  specular  shading  terms  associated with that light source,
       producing  a  dark  shadow  in  areas  that  are  hidden  from  the  light  source.    The
       implementation  uses  lookup  tables  so  that  most  of  the  shading  calculation can be
       precomputed.

       In order to compute the shadows in a single pass the algorithm places a restriction on the
       direction  of  the  light  source:  the light casting the shadows must not be more than 45
       degrees from the viewing direction.  The quality of the shadows may degrade if  the  angle
       approaches 45 degrees.  The current implementation allows shadows to be cast only from one
       light source.  Additional lights may be enabled, but they will not cast shadows.

       To make a rendering with shadows, the following steps must be performed:

              Call vpSetShadowLookupShader to define the lookup tables (see discussion below).

              Call vpSeti with the VP_SHADOW_LIGHT  option  to  specify  which  light  will  cast
              shadows.  The current implementation only allows one light to be specified.

              Call  vpSeti  with  the  VP_SHADOW_BIAS  option  to  set the shadow bias value (see
              discussion below).

              Call vpEnable with the VP_SHADOW option to enable shadows.

              Call vpShadeTable as usual to initialize the lookup tables.

              Call one of the rendering routines.

       vpSetShadowLookupShader defines the lookup tables required for the shading  and  shadowing
       algorithm.   The first nine arguments are identical to the arguments for vpSetLookupShader
       (see the corresponding man page).  The remaining two arguments specify an additional color
       lookup  table, shadow_table, with the same dimensions as color_table.  The contents of the
       table will be initialized by vpShadeTable.

       The call to vpSeti with the VP_SHADOW_BIAS option specifies an offset to  eliminate  self-
       shadowing.  Self-shadowing is an intrinsic problem when implementing shadow algorithms for
       volume rendering.  Consider a  single  voxelized  object  consisting  of  an  opaque  core
       surrounded  by  a  "halo"  of  lower-opacity  voxels  (necessary for the scene to be band-
       limited).  As a light ray pierces the halo its strength is attenuated.  By  the  time  the
       light reaches the high-opacity region a significant fraction of the light may be obscured,
       resulting in a general darkening of the image even if no shadows should be  present.   The
       problem  can be corrected by moving the shadow a small distance along the direction of the
       light rays.  VP_SHADOW_BIAS specifies the distance of the bias in units  of  voxels.   The
       optimal  value  depends on the data set.  Increase the bias until it has no more effect on
       overall image brightness, but do not increase it too far or small  features  in  the  data
       will no longer produce correct shadows.

       vpShadeTable  initializes the shading lookup tables.  It operates differently when shadows
       are enabled.  Instead of computing one color for each surface normal  vector  and  storing
       the  results in color_table, the routine computes two colors terms.  The first term is the
       portion of the voxel color due to the diffuse and specular components of the shadow light.
       This  value  is  stored in shadow_table.  The second term contains the contribution of all
       other light source and the ambient light term,  and  is  stored  in  color_table.   During
       rendering  the color of a voxel is computed by extracting a surface normal from the voxel,
       using the surface normal to index both color_table and shadow_table, attenuating the value
       from shadow_table by the local strength of the shadow light, and then adding the two terms
       together.  The local strength of the shadow light is found by extracting a value from  the
       shadow buffer, an internal data structure that is updated during rendering.

       The  values  in  the  shading  lookup  tables  may  be initialized before or after calling
       vpSetShadowLookupShader.   Typically  vpSetShadowLookupShader  is  called  once   at   the
       beginning  of  a  rendering  session,  and  then  vpShadeTable is called whenever the user
       changes the lighting and shading parameters or the viewing direction.

       The shadow buffer is an internal 2D array used to maintain state during rendering.   There
       are  several  state  variables  that  can  be  used  to  query  its current size in pixels
       (VP_SHADOW_WIDTH and VP_SHADOW_HEIGHT) and to suggest  a  size  (VP_SHADOW_WIDTH_HINT  and
       VP_SHADOW_HEIGHT_HINT).   The  required  size  depends  on  the volume size and the shadow
       light's direction.  Normally the buffer is automatically resized when necessary.

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,        VP_SHADOW,        VP_SHADOW_LIGHT,
       VP_SHADOW_WIDTH_HINT,    VP_SHADOW_HEIGHT_HINT,     VP_SHADOW_WIDTH,     VP_SHADOW_HEIGHT,
       VP_SHADOW_COLOR_TABLE, VP_SHADOW_COLOR_SIZE, VP_SHADOW_BIAS

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), vpSetLookupShader(3)