1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
2
3 .. _crop:
4
5 **********************************************
6 Image Cropping, Insertion and Scaling -- the C
7 **********************************************
8
9 .. note::
10
11 The CROP API is mostly superseded by the ne
12 <selection-api>`. The new API should be pre
13 with the exception of pixel aspect ratio de
14 implemented by :ref:`VIDIOC_CROPCAP <VIDIOC
15 equivalent in the SELECTION API. See :ref:`
16 comparison of the two APIs.
17
18 Some video capture devices can sample a subsec
19 shrink or enlarge it to an image of arbitrary
20 abilities cropping and scaling. Some video out
21 image up or down and insert it at an arbitrary
22 offset into a video signal.
23
24 Applications can use the following API to sele
25 signal, query the default area and the hardwar
26
27 .. note::
28
29 Despite their name, the :ref:`VIDIOC_CROPCA
30 :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :r
31 <VIDIOC_G_CROP>` ioctls apply to input as w
32
33 Scaling requires a source and a target. On a v
34 device the source is the video signal, and the
35 the area actually sampled. The target are imag
36 or overlaid onto the graphics screen. Their si
37 overlay) is negotiated with the :ref:`VIDIOC_G
38 and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls.
39
40 On a video output device the source are the im
41 application, and their size is again negotiate
42 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`V
43 ioctls, or may be encoded in a compressed vide
44 the video signal, and the cropping ioctls dete
45 images are inserted.
46
47 Source and target rectangles are defined even
48 support scaling or the :ref:`VIDIOC_G_CROP <VI
49 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls. T
50 where applicable) will be fixed in this case.
51
52 .. note::
53
54 All capture and output devices that support
55 API will also support the :ref:`VIDIOC_CROP
56 ioctl.
57
58 Cropping Structures
59 ===================
60
61
62 .. _crop-scale:
63
64 .. kernel-figure:: crop.svg
65 :alt: crop.svg
66 :align: center
67
68 Image Cropping, Insertion and Scaling
69
70 The cropping, insertion and scaling proces
71
72
73
74 For capture devices the coordinates of the top
75 height of the area which can be sampled is giv
76 substructure of the struct :c:type:`v4l2_cropc
77 by the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`
78 range of hardware this specification does not
79 However by convention drivers should horizonta
80 relative to 0H (the leading edge of the horizo
81 :ref:`vbi-hsync`). Vertically ITU-R line numbe
82 (see ITU R-525 line numbering for :ref:`525 li
83 :ref:`625 lines <vbi-625>`), multiplied by two
84 can capture both fields.
85
86 The top left corner, width and height of the s
87 the area actually sampled, is given by struct
88 :c:type:`v4l2_crop` using the same coordinate
89 struct :c:type:`v4l2_cropcap`. Applications ca
90 :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:
91 ioctls to get and set this rectangle. It must
92 capture boundaries and the driver may further
93 and/or position according to hardware limitati
94
95 Each capture device has a default source recta
96 ``defrect`` substructure of struct
97 :c:type:`v4l2_cropcap`. The center of this rec
98 shall align with the center of the active pict
99 signal, and cover what the driver writer consi
100 Drivers shall reset the source rectangle to th
101 is first loaded, but not later.
102
103 For output devices these structures and ioctls
104 defining the *target* rectangle where the imag
105 the video signal.
106
107
108 Scaling Adjustments
109 ===================
110
111 Video hardware can have various cropping, inse
112 limitations. It may only scale up or down, sup
113 factors, or have different scaling abilities i
114 direction. Also it may not support scaling at
115 struct :c:type:`v4l2_crop` rectangle may have
116 and both the source and target rectangles may
117 lower size limits. In particular the maximum `
118 struct :c:type:`v4l2_crop` may be smaller than
119 :c:type:`v4l2_cropcap`. ``bounds`` area. There
120 usual, drivers are expected to adjust the requ
121 return the actual values selected.
122
123 Applications can change the source or the targ
124 they may prefer a particular image size or a c
125 signal. If the driver has to adjust both to sa
126 limitations, the last requested rectangle shal
127 driver should preferably adjust the opposite o
128 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl how
129 the driver state and therefore only adjust the
130
131 Suppose scaling on a video capture device is r
132 or 2:1 in either direction and the target imag
133 of 16 × 16 pixels. The source cropping rectan
134 which are also the upper limit in this example
135 offset 0, 0. An application requests an image
136 assuming video will be scaled down from the "f
137 The driver sets the image size to the closest
138 then chooses the cropping rectangle closest to
139 is 608 × 224 (224 × 2:1 would exceed the lim
140 still valid, thus unmodified. Given the defaul
141 reported by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPC
142 easily propose another offset to center the cr
143
144 Now the application may insist on covering an
145 aspect ratio closer to the original request, s
146 rectangle of 608 × 456 pixels. The present sc
147 cropping to 640 × 384, so the driver returns
148 and adjusts the image size to closest possible
149
150
151 Examples
152 ========
153
154 Source and target rectangles shall remain unch
155 reopening a device, such that piping data into
156 work without special preparations. More advanc
157 ensure the parameters are suitable before star
158
159 .. note::
160
161 On the next two examples, a video capture d
162 change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for
163
164 Example: Resetting the cropping parameters
165 ==========================================
166
167 .. code-block:: c
168
169 struct v4l2_cropcap cropcap;
170 struct v4l2_crop crop;
171
172 memset (&cropcap, 0, sizeof (cropcap));
173 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE
174
175 if (-1 == ioctl (fd, VIDIOC_CROPCAP, &crop
176 perror ("VIDIOC_CROPCAP");
177 exit (EXIT_FAILURE);
178 }
179
180 memset (&crop, 0, sizeof (crop));
181 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
182 crop.c = cropcap.defrect;
183
184 /* Ignore if cropping is not supported (EI
185
186 if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
187 && errno != EINVAL) {
188 perror ("VIDIOC_S_CROP");
189 exit (EXIT_FAILURE);
190 }
191
192
193 Example: Simple downscaling
194 ===========================
195
196 .. code-block:: c
197
198 struct v4l2_cropcap cropcap;
199 struct v4l2_format format;
200
201 reset_cropping_parameters ();
202
203 /* Scale down to 1/4 size of full picture.
204
205 memset (&format, 0, sizeof (format)); /* d
206
207 format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
208
209 format.fmt.pix.width = cropcap.defrect.wid
210 format.fmt.pix.height = cropcap.defrect.he
211 format.fmt.pix.pixelformat = V4L2_PIX_FMT_
212
213 if (-1 == ioctl (fd, VIDIOC_S_FMT, &format
214 perror ("VIDIOC_S_FORMAT");
215 exit (EXIT_FAILURE);
216 }
217
218 /* We could check the actual image size no
219 or if the driver can scale at all. */
220
221 Example: Selecting an output area
222 =================================
223
224 .. note:: This example assumes an output devic
225
226 .. code-block:: c
227
228 struct v4l2_cropcap cropcap;
229 struct v4l2_crop crop;
230
231 memset (&cropcap, 0, sizeof (cropcap));
232 cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
233
234 if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cro
235 perror ("VIDIOC_CROPCAP");
236 exit (EXIT_FAILURE);
237 }
238
239 memset (&crop, 0, sizeof (crop));
240
241 crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
242 crop.c = cropcap.defrect;
243
244 /* Scale the width and height to 50 % of t
245 and center the output. */
246
247 crop.c.width /= 2;
248 crop.c.height /= 2;
249 crop.c.left += crop.c.width / 2;
250 crop.c.top += crop.c.height / 2;
251
252 /* Ignore if cropping is not supported (EI
253
254 if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
255 && errno != EINVAL) {
256 perror ("VIDIOC_S_CROP");
257 exit (EXIT_FAILURE);
258 }
259
260 Example: Current scaling factor and pixel aspe
261 ==============================================
262
263 .. note:: This example assumes a video capture
264
265 .. code-block:: c
266
267 struct v4l2_cropcap cropcap;
268 struct v4l2_crop crop;
269 struct v4l2_format format;
270 double hscale, vscale;
271 double aspect;
272 int dwidth, dheight;
273
274 memset (&cropcap, 0, sizeof (cropcap));
275 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE
276
277 if (-1 == ioctl (fd, VIDIOC_CROPCAP, &crop
278 perror ("VIDIOC_CROPCAP");
279 exit (EXIT_FAILURE);
280 }
281
282 memset (&crop, 0, sizeof (crop));
283 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
284
285 if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)
286 if (errno != EINVAL) {
287 perror ("VIDIOC_G_CROP");
288 exit (EXIT_FAILURE);
289 }
290
291 /* Cropping not supported. */
292 crop.c = cropcap.defrect;
293 }
294
295 memset (&format, 0, sizeof (format));
296 format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPT
297
298 if (-1 == ioctl (fd, VIDIOC_G_FMT, &format
299 perror ("VIDIOC_G_FMT");
300 exit (EXIT_FAILURE);
301 }
302
303 /* The scaling applied by the driver. */
304
305 hscale = format.fmt.pix.width / (double) c
306 vscale = format.fmt.pix.height / (double)
307
308 aspect = cropcap.pixelaspect.numerator /
309 (double) cropcap.pixelaspect.denomina
310 aspect = aspect * hscale / vscale;
311
312 /* Devices following ITU-R BT.601 do not c
313 square pixels. For playback on a comput
314 we should scale the images to this size
315
316 dwidth = format.fmt.pix.width / aspect;
317 dheight = format.fmt.pix.height;
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.