.\" Copyright (c) 1994 The Board of Trustees of The Leland Stanford
.\" Junior University.  All rights reserved.
.\" 
.\" Permission to use, copy, modify and distribute this software and its
.\" documentation for any purpose is hereby granted without fee, provided
.\" that the above copyright notice and this permission notice appear in
.\" all copies of this software and that you do not sell the software.
.\" Commercial licensing is available by contacting the author.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
.\" 
.\" Author:
.\"    Phil Lacroute
.\"    Computer Systems Laboratory
.\"    Electrical Engineering Dept.
.\"    Stanford University
.\" 
.\" $Date: 1994/12/31 19:49:53 $
.\" $Revision: 1.1 $
.\"
.\" Macros
.\" .FS <type>  --  function start
.\"     <type> is return type of function
.\"     name and arguments follow on next line
.de FS
.PD 0v
.PP
\\$1
.HP 8
..
.\" .FA  --  function arguments
.\"     one argument declaration follows on next line
.de FA
.IP " " 4
..
.\" .FE  --  function end
.\"     end of function declaration
.de FE
.PD
..
.\" .DS  --  display start
.de DS
.IP " " 4
..
.\" .DE  --  display done
.de DE
.LP
..
.TH vpOctreeMask 3 "" VolPack
.SH NAME
vpOctreeMask \- compute a mask representing one level of a min-max octree
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpOctreeMask(\fIvpc, array, array_size, max_level\fB)\fR
.FA
vpContext \fI*vpc;\fR
.FA
unsigned char *\fIarray;\fR
.FA
int \fIarray_size;\fR
.FA
int \fImax_level;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIarray\fR
A 3D array for storing the mask.
.IP \fIarray_size\fR
Size of \fIarray\fR in bytes.
.IP \fImax_level\fR
Maximum octree level to descend to.
.SH DESCRIPTION
\fBvpOctreeMask\fR is used for performance debugging when rendering
volumes with a min-max octree.  During rendering the min-max octree is
used to help determine which voxels are transparent.  The time
required to make this determination can be minimized by an appropriate
choice for the range parameters for \fBvpMinMaxOctreeThreshold\fR
and the node size parameters for \fBvpCreateMinMaxOctree\fR.
\fBvpOctreeMask\fR provides information that can help to determine
whether a set of parameters works effectively or not.
.PP
The output of the routine is stored in a 3D array of bytes that has
the same dimensions as the volume (although each element is only one
byte, regardless of the size of a voxel).  For each voxel in the volume the
corresponding byte in the output array is set by \fBvpOctreeMask\fR to
one of three values: 0 if the voxel is definitely transparent, 255 if
the voxel may be non-transparent, or 128 if the voxel may be
non-transparent and there is more detailed information available at
unvisited levels of the octree.  The \fImax_level\fR argument
specifies the deepest level of the octree to be visited (the root
level is level 0).
.PP
A suggested way to use this routine is to compute an octree using a
particular set of parameters and then call \fBvpOctreeMask\fR with
several different values for \fImax_level.\fR  For each resulting
mask array, look at slices (or create a volume rendering!) and see how
accurately the mask captures the general shape of the data in the
original volume.  The best set of parameters results in a mask that captures
the general shape without an excessively small value for the minimum
octree node size (which would result in a very large data structure
and a lot of traversal overhead).
.SH ERRORS
The normal return value is VP_OK.  The following error return values are
possible:
.IP VPERROR_BAD_SIZE
There is no octree or the output array has the wrong size.
.IP VPERROR_BAD_VOXEL
The voxel size or the voxel fields have not been specified or have
been incorrectly specified.
.IP VPERROR_BAD_CLASSIFIER
The opacity transfer function tables have invalid sizes or are
associated with invalid voxel fields or have been incorrectly
specified.
.SH SEE ALSO
VolPack(3), vpCreateContext(3), vpCreateMinMaxOctree(3)