NAME
vpSetFilter - define a resampling filter
SYNOPSIS
#include <volpack.h>
vpResult
vpSetFilter(vpc, num_taps, num_phases, weights)
vpContext *vpc;
int num_taps, num_phases;
float *weights;
ARGUMENTS
vpc VolPack context from vpCreateContext.
num_taps
Number of filter taps.
num_phases
Number of filter phases.
weights
Array containing filter weights.
DESCRIPTION
vpSetFilter is used to specify a table of filter weights before
resampling an array with vpResample. The table can be used to specify
an arbitrary separable space-invariant filter.
The vpc 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 vpSetFilter or
vpResample.
The num_taps 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).
The num_phases 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,
num_phases must be a power of two.
The weights array contains the filter weights themselves. The array
should have dimensions:
float weights[num_phases][num_taps];
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).
The easiest way to initialize the weight table is to call one of the
predefined routines described in the vpBoxFilter(3) man page.
ERRORS
The normal return value is VP_OK. The following error return values
are possible:
VPERROR_BAD_VALUE
Either num_taps is non-positive or num_phases is not a positive
power of two.
SEE ALSO
VolPack(3), vpBoxFilter(3), vpResample(3)