.\" 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 vpBoxFilter 3 "" VolPack
.SH NAME
vpBoxFilter, vpLinearFilter, vpBicubicFilter, vpGaussianFilter
\- initialize a filter weight table
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpBoxFilter(\fInum_taps, num_phases, weights, weights_bytes\fB)\fR
.FA
int \fInum_taps, num_phases\fR;
.FA
float *\fIweights\fR;
.FA
int \fIweights_bytes\fR;
.FE
.sp
.FS vpResult
\fBvpLinearFilter(\fInum_taps, num_phases, weights, weights_bytes\fB)\fR
.FA
int \fInum_taps, num_phases\fR;
.FA
float *\fIweights\fR;
.FA
int \fIweights_bytes\fR;
.FE
.sp
.FS vpResult
\fBvpBicubicFilter(\fIb_value, c_value, num_taps, num_phases, weights,
weights_bytes\fB)\fR
.FA
double \fIb_value, c_value\fR;
.FA
int \fInum_taps, num_phases\fR;
.FA
float *\fIweights\fR;
.FA
int \fIweights_bytes\fR;
.FE
.sp
.FS vpResult
\fBvpGaussianFilter(\fIsigma, num_taps, num_phases, weights,
weights_bytes\fB)\fR
.FA
double \fIsigma\fR;
.FA
int \fInum_taps, num_phases\fR;
.FA
float *\fIweights\fR;
.FA
int \fIweights_bytes\fR;
.FE
.SH ARGUMENTS
.IP \fInum_taps\fR
Number of filter taps.
.IP \fInum_phases\fR
Number of filter phases.
.IP \fIweights\fR
Array containing filter weights.
.IP \fIweights_bytes\fR
Size (in bytes) of array containing filter weights.
.IP \fIb_value\fR
"B" parameter in the formula for a Mitchell bicubic.
.IP \fIc_value\fR
"C" parameter in the formula for a Mitchell bicubic.
.IP \fIsigma\fR
Standard deviation for a Gaussian.
.SH DESCRIPTION
These routines can be used to initialize filter weight tables for use
with \fBvpSetFilter\fR and \fBvpResample\fR.  See the
\fBvpSetFilter\fR man page for information on the \fInum_taps\fR and
\fInum_phases\fR arguments.
.PP
\fBvpBoxFilter\fR creates a filter table for a box filter (a zero-order
filter).  With \fInum_taps\fR equal to 1 the filter is a
nearest-neighbor filter, suitable for low-quality upsampling.  To
create a decimation filter that averages down, the number of taps
should equal the decimation factor (as nearly as possible).
.PP
\fBvpLinearFilter\fR creates a filter table for a linear filter (a
first-order or tent filter).  With \fInum_taps\fR equal to 2 the
filter performs linear interpolation.
.PP
\fBvpBicubicFilter\fR creates a filter table for a Mitchell
bicubic filter.  The first two arguments can be used to modify the
shape of the filter kernel.  Some standard parameter values are:
.IP "\fIb_value\fR = 1, \fIc_value = 0\fR"
Cubic B-spline.
.IP "\fIb_value\fR = 0, \fIc_value = 0.5\fR"
Catmull-Rom spline.
.PP
With four filter taps the cubic B-spline filter is suitable for
upsampling.  For more details, see the following paper: Mitchell,
D.P. and Netravali, A.N., "Reconstruction filters in computer graphics,"
Proc. SIGGRAPH '88 (Computer Graphics V22 N4), p. 221-8.
.PP
\fBvpGaussianFilter\fR creates a filter table for a gaussian filter.
The first argument is the standard deviation of the gaussian.
.SH ERRORS
The normal return value is VP_OK.  The following error return values
are possible:
.IP VPERROR_BAD_SIZE
The filter weight table size is invalid.
.IP VPERROR_BAD_VALUE
The number of phases is not a positive power of two.
.SH SEE ALSO
VolPack(3), vpResample(3), vpSetFilter(3)