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)

VolPack                                                                                           vpSetFilter(3)