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)