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

FreeBSD Manual Pages

  
 
  

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

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 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.

DESCRIPTION
       vpSetLookupShader  is used to specify lookup tables that	define a shad-
       ing function.  The lookup-table shading algorithm provided  by  VolPack
       is  designed to support the following shading model.  Each voxel	is as-
       sumed 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	direc-
       tional (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	evalu-
       ated 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 com-
       pute  the contents of the tables.  See vpSetDepthCueing(3) for informa-
       tion 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  render-
       ing.   To  define  a  callback  shader,	call  vpSetCallback  with  the
       VP_GRAY_SHADE_FUNC or VP_RGB_SHADE_FUNC	option	code  (see  vpSetCall-
       back(3)).   The	lookup	tables are used	if the last successful call to
       vpSetLookupShader occurred after	the last successful call to vpSetCall-
       back 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_mate-
       rials  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 val-
       ues 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_in-
       dex, a weighted color is	computed from the formula: color  =  color_ta-
       ble[color_index][material_index]	*
		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 sepa-
       rately 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  vec-
       tor; this should	be the same field as the norm_field argument to	vpVol-
       umeNormals 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 ini-
       tializes	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_ta-
       ble[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 mate-
       rial 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  ta-
       ble 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_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

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

VolPack							  vpSetLookupShader(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-LookupShader&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help