vpSetFilter(3) | 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 |