1mlib_ImageFilteredSubsamplem(e3dMiLaILBi)b Library Fumnlcitbi_oInmsageFilteredSubsample(3MLIB)
2
3
4

NAME

6       mlib_ImageFilteredSubsample, mlib_ImageFilteredSubsample_Fp - antialias
7       filters and subsamples an image
8

SYNOPSIS

10       cc [ flag... ] file... -lmlib [ library... ]
11       #include <mlib.h>
12
13       mlib_status mlib_ImageFilteredSubsample(mlib_image *dst,
14            const mlib_image *src, mlib_s32 scaleX, mlib_s32 scaleY,
15            mlib_s32 transX, mlib_s32 transY,
16            const mlib_d64 *hKernel, const mlib_d64 *vKernel, mlib_s32 hSize,
17            mlib_s32 vSize, mlib_s32 hParity, mlib_s32 vParity, mlib_edge edge);
18
19
20       mlib_status mlib_ImageFilteredSubsample_Fp(mlib_image *dst,
21            const mlib_image *src, mlib_s32 scaleX, mlib_s32 scaleY,
22            mlib_s32 transX, mlib_s32 transY,
23            const mlib_d64 *hKernel, const mlib_d64 *vKernel, mlib_s32 hSize,
24            mlib_s32 vSize, mlib_s32 hParity, mlib_s32 vParity, mlib_edge edge);
25
26

DESCRIPTION

28       Each of the functions antialias filters and subsamples an image.
29
30
31       The effect of one of the functions on an image is  equivalent  to  per‐
32       forming convolution (filter) followed by subsampling (zoom out).
33
34
35       The   functions   are  similar  to  the  mlib_ImageZoomTranslate()  and
36       mlib_ImageZoomTranslate_Fp() functions. But they have different defini‐
37       tions on scale factors and translations, hence use different coordinate
38       mapping equations. The scaleX and scaleY used by mlib_ImageFilteredSub‐
39       sample()  and  mlib_ImageFilteredSubsample_Fp()  are the reciprocals of
40       the zoomx and zoomy, respectively,  used  by  mlib_ImageZoomTranslate()
41       and mlib_ImageZoomTranslate_Fp().
42
43
44       The functions use the following equations for coordinate mapping:
45
46         xS = xD*scaleX + transX
47         yS = yD*scaleY + transY
48
49
50
51       where,  a point (xD, yD) in the destination image is backward mapped to
52       a point (xS, yS) in the source image. The arguments transX  and  transY
53       are provided to support tiling.
54
55
56       The  subsample  terms,  i.e.,  the scale factors scaleX and scaleY, are
57       restricted to positive integral values. Geometrically, one  destination
58       pixel  maps  to scaleX by scaleY source pixels. With odd scale factors,
59       destination pixel centers map directly onto source pixel centers.  With
60       even  scale  factors,  destination  pixel  centers map squarely between
61       source pixel centers. Below are examples of even, odd, and  combination
62       cases.
63
64           s   s   s   s   s   s           s   s   s   s   s   s
65             d       d       d
66           s   s   s   s   s   s           s   d   s   s   d   s
67
68           s   s   s   s   s   s           s   s   s   s   s   s
69             d       d       d
70           s   s   s   s   s   s           s   s   s   s   s   s
71
72           s   s   s   s   s   s           s   d   s   s   d   s
73             d       d       d
74           s   s   s   s   s   s           s   s   s   s   s   s
75
76           Even scaleX/Y factors           Odd scaleX/Y factors
77
78           s   s   s   s   s   s           s   s   s   s   s   s
79               d           d
80           s   s   s   s   s   s           s d s   s d s   s d s
81
82           s   s   s   s   s   s           s   s   s   s   s   s
83               d           d
84           s   s   s   s   s   s           s   s   s   s   s   s
85
86           s   s   s   s   s   s           s d s   s d s   s d s
87               d           d
88           s   s   s   s   s   s           s   s   s   s   s   s
89
90           Odd/even scaleX/Y factors       Even/odd scaleX/Y factors
91
92
93
94       where
95
96           s = source pixel centers
97           d = destination pixel centers mapped to source
98
99
100
101       The  applied filter is quadrant symmetric (typically antialias + resam‐
102       ple). The filter  is  product-separable,  quadrant  symmetric,  and  is
103       defined by half of its span. Parity is used to signify whether the sym‐
104       metric kernel has a double center (even  parity)  or  a  single  center
105       value (odd parity). For example, if hParity == 0 (even), the horizontal
106       kernel is defined as:
107
108         hKernel[hSize-1], ..., hKernel[0], hKernel[0], ...,
109         hKernel[hSize-1]
110
111
112
113       Otherwise, if hParity == 1 (odd), the horizontal kernel is defined as:
114
115         hKernel[hSize-1], ..., hKernel[0], ...,
116         hKernel[hSize-1]
117
118
119
120       Horizontal and vertical kernels representing convolved resample  (i.e.,
121       the combined separable kernels) can be computed from a convolution fil‐
122       ter (with odd parity), a resample filter,  and  because  the  subsample
123       factors affect resample weights, the subsample scale factors. It is the
124       user's responsibility to provide meaningful combined kernels.
125
126
127       To compute the value of a pixel centered at point (xD, yD) in the  des‐
128       tination image, apply the combined kernel to the source image by align‐
129       ing the kernel's geometric center to the backward mapped point (xS, yS)
130       in  the source image. In the cases that it can not be exactly on top of
131       point (xS, yS), the kernel's center should be half-pixel  right  and/or
132       below  that point. When this is done in a separable manner, the centers
133       of horizontal and vertical kernels should align with xS and yS, respec‐
134       tively.
135
136
137       The  combination  of subsampling and filtering has performance benefits
138       over sequential fucntion usage in part due to the symmetry  constraints
139       imposed by only allowing integer parameters for scaling and only allow‐
140       ing separable symmetric filters.
141

PARAMETERS

143       The function takes the following arguments:
144
145       dst        Pointer to destination image.
146
147
148       src        Pointer to source image.
149
150
151       scaleX     The x scale factor of subsampling.
152
153
154       scaleY     The y scale factor of subsampling.
155
156
157       transX     The x translation.
158
159
160       transY     The y translation.
161
162
163       hKernel    Pointer to the compact form of horizontal kernel.
164
165
166       vKernel    Pointer to the compact form of vertical kernel.
167
168
169       hSize      Size of array hKernel.
170
171
172       vSize      Size of array vKernel.
173
174
175       hParity    Parity of horizontal kernel (0: even, 1: odd).
176
177
178       vParity    Parity of vertical kernel (0: even, 1: odd).
179
180
181       edge       Type of edge condition. It can be one of the following:
182
183                    MLIB_EDGE_DST_NO_WRITE
184
185
186

RETURN VALUES

188       The function returns MLIB_SUCCESS if successful. Otherwise  it  returns
189       MLIB_FAILURE.
190

ATTRIBUTES

192       See attributes(5) for descriptions of the following attributes:
193
194
195
196
197       ┌─────────────────────────────┬─────────────────────────────┐
198       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
199       ├─────────────────────────────┼─────────────────────────────┤
200       │Interface Stability          │Committed                    │
201       ├─────────────────────────────┼─────────────────────────────┤
202       │MT-Level                     │MT-Safe                      │
203       └─────────────────────────────┴─────────────────────────────┘
204

SEE ALSO

206       mlib_ImageSubsampleAverage(3MLIB),      mlib_ImageZoomTranslate(3MLIB),
207       mlib_ImageZoomTranslate_Fp(3MLIB), attributes(5)
208
209
210
211SunOS 5.11                        2 Mar 2007mlib_ImageFilteredSubsample(3MLIB)
Impressum