DragonFly On-Line Manual Pages

vpSetFilter(3)        DragonFly Library Functions Manual        vpSetFilter(3)

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)