.\" 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 vpGetTimer 3 "" VolPack
.SH NAME
vpGetTimer, vpClearTimer \- interval timer facility
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpGetTimer(\fIvpc, option, iptr\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
int \fIoption;\fR
.FA
int *\fIiptr;\fR;
.FE
.sp
.FS vpResult
\fBvpClearTimer(\fIvpc, option\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
int \fIoption;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIoption\fR
Constant that specifies a particular timer.
.IP \fIiptr\fR
Location for storing the timer value.
.SH DESCRIPTION
These functions are used for measuring the performance of the VolPack
library.  To use them, the library must be compiled with a special
flag: either -DHAVE_LORES_TIMER (for machine that support the
gettimeofday C library call) or -DHAVE_HIRES_TIMER (for SGI machines
that support high-resolution memory-mapped I/O timers; on a Challenge
or ONYX, the -DHAVE_64BIT_TIMER must also be specified).  If one of
these flags is specified at compile time then VolPack maintains a
table recording the accumulated time spent in various operations.
Note that some of the operations can only be timed with a
high-resolution timer; time values will not be recorded and will
appear to be zero if a low resolution timer is specified at compile time.
.PP
\fBvpGetTimer\fR retrieves the accumulated time for a particular
operation.  The \fIoption\fR argument specifies which operation:
.IP VPTIMER_SHADE
Time the routine that computes the contents of the shading lookup table.
.IP VPTIMER_RENDER
Time the routine that renders a volume (includes VPTIMER_CLSFY_OCTREE,
VPTIMER_COMPOSITE, VPTIMER_DEPTHCUE, and VPTIMER_WARP).
.IP VPTIMER_COMPOSITE
Time the routine that computes the intermediate image from the volume
(includes VPTIMER_CLEAR, VPTIMER_TRAVERSE_OCTREE, VPTIMER_ERT,
VPTIMER_TRAVERSE_RUNS, and VPTIMER_PROCESS_VOXELS).
.IP VPTIMER_DEPTHCUE
Time the routine that performs the depth cueing fixup on the
intermediate image.
.IP VPTIMER_WARP
Time the routine that warps the intermediate image into the final image.
.IP VPTIMER_TRAVERSE_RUNS
Time the portion of the compositing routine devoted to traversing
the volume data structures.
.IP VPTIMER_PROCESS_VOXELS
Time the portion of the compositing routine devoted to compositing
voxels into the intermediate image.
.IP VPTIMER_ERT
Time the early-ray termination checks during compositing.
.IP VPTIMER_CLSFY_OCTREE
Time the octree classification stage.
.IP VPTIMER_TRAVERSE_OCTREE
Time the portion of the compositing routine devoted to traversing the
octree.
.IP VPTIMER_CLEAR
Time the routine that clears the intermediate image at the beginning
of compositing.
.LP
The routine stores the accumulated time since the last call to
\fIvpClearTimer\fR (or since the beginning of the program) in the
location specified by \fIiptr.\fR  The units of the value are
microseconds.
.PP
\fIvpClearTimer\fR sets the specified timer value back to zero.
.SH ERRORS
The normal return value is VP_OK.  The following error return value is
possible:
.IP VPERROR_BAD_OPTION
The \fIoption\fR argument is invalid.
.SH SEE ALSO
VolPack(3), vpCreateContext(3)