1vpSetFilter(3)             Library Functions Manual             vpSetFilter(3)
2
3
4

NAME

6       vpSetFilter - define a resampling filter
7

SYNOPSIS

9       #include <volpack.h>
10
11       vpResult
12       vpSetFilter(vpc, num_taps, num_phases, weights)
13           vpContext *vpc;
14           int num_taps, num_phases;
15           float *weights;
16

ARGUMENTS

18       vpc    VolPack context from vpCreateContext.
19
20       num_taps
21              Number of filter taps.
22
23       num_phases
24              Number of filter phases.
25
26       weights
27              Array containing filter weights.
28

DESCRIPTION

30       vpSetFilter  is used to specify a table of filter weights before resam‐
31       pling an array with vpResample.  The table can be used  to  specify  an
32       arbitrary separable space-invariant filter.
33
34       The  vpc argument is a VolPack context for storing a description of the
35       resampling filter.  The volume data and rendering parameters  currently
36       stored in the context are not affected by calls to vpSetFilter or vpRe‐
37       sample.
38
39       The num_taps argument specifies the number of  filter  taps.   When  an
40       array is resampled, the number of filter taps is equal to the number of
41       input array elements that contribute  to  one  element  of  the  output
42       array.   A filter weight is associated with each tap and determines the
43       contribution of the corresponding input array  element  to  the  output
44       array  element.   Note  that when upsampling the number of taps depends
45       only on the support of the filter kernel.  When downsampling, the  num‐
46       ber  of  taps  should also depend on the scale factor (since the filter
47       kernel must also be scaled).
48
49       The num_phases argument specifies the number of filter phases, which is
50       equal  to  the  number of times the filter kernel is sampled.  The more
51       filter phases, the more accurate  the  filtering  operation.   However,
52       there  is a point of diminishing returns where increasing the number of
53       phases results in very little increase in accuracy, and has the  disad‐
54       vantages  of  increased storage requirements and potentially poor cache
55       performance.  To allow for an efficient implementation, num_phases must
56       be a power of two.
57
58       The  weights  array  contains the filter weights themselves.  The array
59       should have dimensions: float weights[num_phases][num_taps]; Each  ele‐
60       ment  should  normally be a number between 0.0 and 1.0 (negative values
61       are also possible but can lead to  ringing),  and  for  any  particular
62       phase the entries for all of the taps should sum to 1.0 (or else ripple
63       is introduced into constant regions of the filtered array).
64
65       The easiest way to initialize the weight table is to call  one  of  the
66       predefined routines described in the vpBoxFilter(3) man page.
67

ERRORS

69       The  normal  return  value is VP_OK.  The following error return values
70       are possible:
71
72       VPERROR_BAD_VALUE
73              Either num_taps is non-positive or num_phases is not a  positive
74              power of two.
75

SEE ALSO

77       VolPack(3), vpBoxFilter(3), vpResample(3)
78
79
80
81VolPack                                                         vpSetFilter(3)
Impressum