.\" 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 vpSetFilter 3 "" VolPack
.SH NAME
vpSetFilter \- define a resampling filter
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpSetFilter(\fIvpc, num_taps, num_phases, weights\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
int \fInum_taps, num_phases;\fR
.FA
float *\fIweights;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fInum_taps\fR
Number of filter taps.
.IP \fInum_phases\fR
Number of filter phases.
.IP \fIweights\fR
Array containing filter weights.
.SH DESCRIPTION
\fBvpSetFilter\fR is used to specify a table of filter weights before
resampling an array with \fBvpResample\fR.  The table can be used to
specify an arbitrary separable space-invariant filter.
.PP
The \fIvpc\fR argument is a VolPack context for storing a
description of the resampling filter.  The volume data and rendering
parameters currently stored in the context are not affected by calls
to \fBvpSetFilter\fR or \fBvpResample\fR.
.PP
The \fInum_taps\fR argument specifies the number of filter taps.  When
an array is resampled, the number of filter taps is equal to the
number of input array elements that contribute to one element of the
output array.  A filter weight is associated with each tap and
determines the contribution of the corresponding input array element
to the output array element.  Note that when upsampling the number of
taps depends only on the support of the filter kernel.  When
downsampling, the number of taps should also depend on the scale
factor (since the filter kernel must also be scaled).
.PP
The \fInum_phases\fR argument specifies the number of filter phases,
which is equal to the number of times the filter kernel is sampled.
The more filter phases, the more accurate the filtering operation.
However, there is a point of diminishing returns where increasing the
number of phases results in very little increase in accuracy, and has
the disadvantages of increased storage requirements and potentially
poor cache performance.  To allow for an efficient implementation,
\fInum_phases\fR must be a power of two.
.PP
The \fIweights\fR array contains the filter weights themselves.  The
array should have dimensions:
.DS
float weights[num_phases][num_taps];
.DE
Each element should normally be a number between 0.0 and 1.0 (negative
values are also possible but can lead to ringing), and for any
particular phase the entries for all of the taps should sum to 1.0 (or
else ripple is introduced into constant regions of the filtered array).
.PP
The easiest way to initialize the weight table is to call one of the
predefined routines described in the vpBoxFilter(3) man page.
.SH ERRORS
The normal return value is VP_OK.  The following error return values
are possible:
.IP VPERROR_BAD_VALUE
Either \fInum_taps\fR is non-positive or \fInum_phases\fR is not a
positive power of two.
.SH SEE ALSO
VolPack(3), vpBoxFilter(3), vpResample(3)