Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
vpSetShadowLookupShader(3) Library Functions Manual vpSetShadowLookupShader(3)

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_ta-
	       ble_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 in-
	      dex.

       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 com-
       putes 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 implementa-
       tion 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  de-
       grees.	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 per-
       formed:

	      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 identi-
       cal 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 con-
       tents 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-lim-
       ited).  As a light ray pierces the halo its strength is attenuated.  By
       the  time the light reaches the high-opacity region a significant frac-
       tion 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 dif-
       ferently	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  ren-
       dering.

       The  values  in	the shading lookup tables may be initialized before or
       after calling  vpSetShadowLookupShader.	 Typically  vpSetShadowLookup-
       Shader is called	once at	the beginning of a rendering session, and then
       vpShadeTable is called whenever the user	changes	the lighting and shad-
       ing 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 di-
       rection.	 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_CHAN-
       NELS, 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)

VolPack						    vpSetShadowLookupShader(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | STATE VARIABLES | ERRORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=volpack-Shadow&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help