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

FreeBSD Manual Pages

  
 
  

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

NAME
       vpCreateMinMaxOctree,  vpMinMaxOctreeThreshold, vpDestroyMinMaxOctree -
       create/destroy a	min-max	octree for optimized rendering

SYNOPSIS
       #include	<volpack.h>

       vpResult
       vpCreateMinMaxOctree(vpc, root_node_size, base_node_size)
	   vpContext *vpc;
	   int root_node_size, base_node_size;

       vpResult
       vpMinMaxOctreeThreshold(vpc, param_num, range)
	   vpContext *vpc;
	   int param_num, range;

       vpResult
       vpDestroyMinMaxOctree(vpc)
	   vpContext *vpc;

ARGUMENTS
       vpc    VolPack context from vpCreateContext.

       root_node_size
	      Number of	voxels per side	in the top level  (largest  nodes)  of
	      the octree.  Not currently used.

       base_node_size
	      Number  of  voxels per side in the bottom	level (smallest	nodes)
	      of the octree.  Must be a	power of 2.

       param_num
	      Identifying number of one	 parameter  of	the  opacity  transfer
	      function.

       range  Range  threshold for one parameter of the	opacity	transfer func-
	      tion.  If	an octree node spans a larger range then it is	subdi-
	      vided.

DESCRIPTION
       These  routines are used	to create and destroy a	min-max	octree,	an in-
       ternal data structure that is used to accelerate	classifying  and  ren-
       dering  volume  data in a 3D voxel array.  The octree is	a hierarchical
       data structure that contains minimum and	maximum	values for each	 voxel
       field.	It does	not duplicate the data in the voxel array.  The	octree
       is not used with	preclassified volumes (see vpClassifyVolume(3)).

       Before creating an octree, declare a 3D voxel array using  vpSetVolume-
       Size,  vpSetVoxelSize, vpSetVoxelField and vpSetRawVoxels, and initial-
       ize parameters for the opacity transfer function	by calling  vpSetClas-
       sifierTable.   Then initialize the voxel	data in	the array.  The	lookup
       tables for the opacity transfer function	do not need to be initialized.

       Now call	vpMinMaxOctreeThreshold	once for each parameter	to the opacity
       transfer	 function.  The	parameter number is the	same number as the pa-
       rameter number you would	pass to	vpClassifierTable.  The	range argument
       specifies  a  "small"  range of values for the corresponding parameter.
       The opacity of a	voxel should not vary  much  for  voxels  within  this
       range  of  parameter space.  Choosing a value which is too small	or too
       large may result	in a reduced  performance  benefit  during  rendering.
       The function vpOctreeMask can be	used to	visualize the effectiveness of
       various parameter ranges.  Note that you	must choose  the  voxel	 field
       associated  with	each opacity transfer function parameter in advance of
       creating	the octree (by calling vpSetClassiferTable), but  the  opacity
       transfer	function itself	does not need to be known since	the lookup ta-
       bles do not need	to be initialized.  In the current implementation  all
       of  the	parameters  must  be  one  or two-byte voxel fields; four-byte
       fields are not allowed.

       Finally,	call vpCreateMinMaxOctree to actually compute the octree.  The
       arguments specify the largest and smallest node size.  These values can
       be used to trade	off storage size of the	octree for  increased  resolu-
       tion.   The octree is stored in the rendering context and is used auto-
       matically in subsequent calls to	vpClassifyVolume  and  vpRenderRawVol-
       ume.   Only one octree may be stored in a context at a time.  If	an oc-
       tree already exists when	vpCreateMinMaxOctree is	called	then  the  old
       octree is destroyed.

       If  the data in the voxel array changes then the	min-max	octree must be
       explicitly recomputed by	calling	vpCreateMinMaxOctree again before  the
       next call to vpClassifyVolume or	vpRenderRawVolume.

       vpDestroyMinMaxOctree destroys the current min-max octree and frees the
       associated storage.

STATE VARIABLES
       The current octree parameters can be retrieved with the following state
       variable	  codes	 (see  vpGeti(3)):  VP_CLASSIFY_FIELD_COUNT,  VP_CLAS-
       SIFY_FIELDS, VP_MMOCTREE_THRESHOLDS, VP_MMOCTREE_SIZE.

ERRORS
       The normal return value for all three functions is VP_OK.   vpMinMaxOc-
       treeThreshold can return	the following error value:

       VPERROR_BAD_VALUE
	      The parameter number is invalid.

       vpCreateMinMaxOctree can	return the following error values:

       VPERROR_BAD_VALUE
	      The node size arguments are not a	power of two.

       VPERROR_BAD_VOXEL
	      The  voxel  size	or the voxel fields have not been specified or
	      have been	incorrectly specified, or the number of	parameters  to
	      the opacity transfer function has	been incorrectly specified.

       VPERROR_BAD_VOLUME
	      The  volume  array or volume dimensions have not been specified,
	      or the size of the volume	array does not match the volume	dimen-
	      sions.

       VPERROR_BAD_CLASSIFIER
	      The fields specified as parameters to the	opacity	transfer func-
	      tion are invalid or do not have valid sizes.

       VPERROR_LIMIT_EXCEEDED
	      The volume is too	large, so the maximum size of the  octree  has
	      been exceeded.  Change the constant VP_MAX_OCTREE_LEVELS in vol-
	      pack.h and recompile the VolPack library.

SEE ALSO
       VolPack(3), vpCreateContext(3),	vpClassifyVolume(3),  vpOctreeMask(3),
       vpRenderRawVolume(3)

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

home | help