]>
Commit | Line | Data |
---|---|---|
8af4922f TS |
1 | <section id="selection-api"> |
2 | ||
079dda54 | 3 | <title>API for cropping, composing and scaling</title> |
8af4922f TS |
4 | |
5 | <section> | |
6 | <title>Introduction</title> | |
7 | ||
8 | <para>Some video capture devices can sample a subsection of a picture and | |
9 | shrink or enlarge it to an image of arbitrary size. Next, the devices can | |
10 | insert the image into larger one. Some video output devices can crop part of an | |
11 | input image, scale it up or down and insert it at an arbitrary scan line and | |
12 | horizontal offset into a video signal. We call these abilities cropping, | |
13 | scaling and composing.</para> | |
14 | ||
15 | <para>On a video <emphasis>capture</emphasis> device the source is a video | |
16 | signal, and the cropping target determine the area actually sampled. The sink | |
17 | is an image stored in a memory buffer. The composing area specifies which part | |
18 | of the buffer is actually written to by the hardware. </para> | |
19 | ||
20 | <para>On a video <emphasis>output</emphasis> device the source is an image in a | |
21 | memory buffer, and the cropping target is a part of an image to be shown on a | |
22 | display. The sink is the display or the graphics screen. The application may | |
23 | select the part of display where the image should be displayed. The size and | |
24 | position of such a window is controlled by the compose target.</para> | |
25 | ||
26 | <para>Rectangles for all cropping and composing targets are defined even if the | |
27 | device does supports neither cropping nor composing. Their size and position | |
28 | will be fixed in such a case. If the device does not support scaling then the | |
29 | cropping and composing rectangles have the same size.</para> | |
30 | ||
31 | </section> | |
32 | ||
33 | <section> | |
34 | <title>Selection targets</title> | |
35 | ||
071408b6 | 36 | <para> |
8af4922f TS |
37 | <figure id="sel-targets-capture"> |
38 | <title>Cropping and composing targets</title> | |
39 | <mediaobject> | |
40 | <imageobject> | |
41 | <imagedata fileref="selection.png" format="PNG" /> | |
42 | </imageobject> | |
43 | <textobject> | |
44 | <phrase>Targets used by a cropping, composing and scaling | |
45 | process</phrase> | |
46 | </textobject> | |
47 | </mediaobject> | |
48 | </figure> | |
071408b6 | 49 | </para> |
9080d5d3 | 50 | |
071408b6 HV |
51 | <para>See <xref linkend="v4l2-selection-targets" /> for more |
52 | information.</para> | |
8af4922f TS |
53 | </section> |
54 | ||
55 | <section> | |
56 | ||
57 | <title>Configuration</title> | |
58 | ||
59 | <para>Applications can use the <link linkend="vidioc-g-selection">selection | |
60 | API</link> to select an area in a video signal or a buffer, and to query for | |
61 | default settings and hardware limits.</para> | |
62 | ||
63 | <para>Video hardware can have various cropping, composing and scaling | |
64 | limitations. It may only scale up or down, support only discrete scaling | |
65 | factors, or have different scaling abilities in the horizontal and vertical | |
66 | directions. Also it may not support scaling at all. At the same time the | |
67 | cropping/composing rectangles may have to be aligned, and both the source and | |
68 | the sink may have arbitrary upper and lower size limits. Therefore, as usual, | |
69 | drivers are expected to adjust the requested parameters and return the actual | |
70 | values selected. An application can control the rounding behaviour using <link | |
9fe75aac | 71 | linkend="v4l2-selection-flags"> constraint flags </link>.</para> |
8af4922f TS |
72 | |
73 | <section> | |
74 | ||
75 | <title>Configuration of video capture</title> | |
76 | ||
77 | <para>See figure <xref linkend="sel-targets-capture" /> for examples of the | |
78 | selection targets available for a video capture device. It is recommended to | |
79 | configure the cropping targets before to the composing targets.</para> | |
80 | ||
81 | <para>The range of coordinates of the top left corner, width and height of | |
d2dbd9d5 HV |
82 | areas that can be sampled is given by the <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant> |
83 | target. It is recommended for the driver developers to put the | |
84 | top/left corner at position <constant>(0,0)</constant>. The rectangle's | |
aa73ab96 | 85 | coordinates are expressed in pixels.</para> |
8af4922f TS |
86 | |
87 | <para>The top left corner, width and height of the source rectangle, that is | |
d2dbd9d5 HV |
88 | the area actually sampled, is given by the <constant>V4L2_SEL_TGT_CROP</constant> |
89 | target. It uses the same coordinate system as <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>. | |
90 | The active cropping area must lie completely inside the capture boundaries. The | |
91 | driver may further adjust the requested size and/or position according to hardware | |
92 | limitations.</para> | |
8af4922f TS |
93 | |
94 | <para>Each capture device has a default source rectangle, given by the | |
d2dbd9d5 | 95 | <constant>V4L2_SEL_TGT_CROP_DEFAULT</constant> target. This rectangle shall |
8af4922f TS |
96 | over what the driver writer considers the complete picture. Drivers shall set |
97 | the active crop rectangle to the default when the driver is first loaded, but | |
98 | not later.</para> | |
99 | ||
100 | <para>The composing targets refer to a memory buffer. The limits of composing | |
d2dbd9d5 HV |
101 | coordinates are obtained using <constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant>. |
102 | All coordinates are expressed in pixels. The rectangle's top/left | |
103 | corner must be located at position <constant>(0,0)</constant>. The width and | |
104 | height are equal to the image size set by <constant>VIDIOC_S_FMT</constant>. | |
aa73ab96 | 105 | </para> |
8af4922f TS |
106 | |
107 | <para>The part of a buffer into which the image is inserted by the hardware is | |
d2dbd9d5 | 108 | controlled by the <constant>V4L2_SEL_TGT_COMPOSE</constant> target. |
8af4922f TS |
109 | The rectangle's coordinates are also expressed in the same coordinate system as |
110 | the bounds rectangle. The composing rectangle must lie completely inside bounds | |
111 | rectangle. The driver must adjust the composing rectangle to fit to the | |
112 | bounding limits. Moreover, the driver can perform other adjustments according | |
113 | to hardware limitations. The application can control rounding behaviour using | |
d2dbd9d5 | 114 | <link linkend="v4l2-selection-flags"> constraint flags</link>.</para> |
8af4922f TS |
115 | |
116 | <para>For capture devices the default composing rectangle is queried using | |
d2dbd9d5 | 117 | <constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant>. It is usually equal to the |
8af4922f TS |
118 | bounding rectangle.</para> |
119 | ||
120 | <para>The part of a buffer that is modified by the hardware is given by | |
d2dbd9d5 HV |
121 | <constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant>. It contains all pixels |
122 | defined using <constant>V4L2_SEL_TGT_COMPOSE</constant> plus all | |
8af4922f TS |
123 | padding data modified by hardware during insertion process. All pixels outside |
124 | this rectangle <emphasis>must not</emphasis> be changed by the hardware. The | |
125 | content of pixels that lie inside the padded area but outside active area is | |
126 | undefined. The application can use the padded and active rectangles to detect | |
127 | where the rubbish pixels are located and remove them if needed.</para> | |
128 | ||
129 | </section> | |
130 | ||
131 | <section> | |
132 | ||
133 | <title>Configuration of video output</title> | |
134 | ||
135 | <para>For output devices targets and ioctls are used similarly to the video | |
d2dbd9d5 | 136 | capture case. The <emphasis>composing</emphasis> rectangle refers to the |
8af4922f TS |
137 | insertion of an image into a video signal. The cropping rectangles refer to a |
138 | memory buffer. It is recommended to configure the composing targets before to | |
139 | the cropping targets.</para> | |
140 | ||
141 | <para>The cropping targets refer to the memory buffer that contains an image to | |
142 | be inserted into a video signal or graphical screen. The limits of cropping | |
d2dbd9d5 | 143 | coordinates are obtained using <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>. |
aa73ab96 | 144 | All coordinates are expressed in pixels. The top/left corner is always point |
d2dbd9d5 HV |
145 | <constant>(0,0)</constant>. The width and height is equal to the image size |
146 | specified using <constant>VIDIOC_S_FMT</constant> ioctl.</para> | |
8af4922f TS |
147 | |
148 | <para>The top left corner, width and height of the source rectangle, that is | |
149 | the area from which image date are processed by the hardware, is given by the | |
d2dbd9d5 | 150 | <constant>V4L2_SEL_TGT_CROP</constant>. Its coordinates are expressed |
8af4922f TS |
151 | in in the same coordinate system as the bounds rectangle. The active cropping |
152 | area must lie completely inside the crop boundaries and the driver may further | |
153 | adjust the requested size and/or position according to hardware | |
154 | limitations.</para> | |
155 | ||
156 | <para>For output devices the default cropping rectangle is queried using | |
d2dbd9d5 | 157 | <constant>V4L2_SEL_TGT_CROP_DEFAULT</constant>. It is usually equal to the |
8af4922f TS |
158 | bounding rectangle.</para> |
159 | ||
160 | <para>The part of a video signal or graphics display where the image is | |
d2dbd9d5 HV |
161 | inserted by the hardware is controlled by <constant>V4L2_SEL_TGT_COMPOSE</constant> |
162 | target. The rectangle's coordinates are expressed in pixels. The composing | |
163 | rectangle must lie completely inside the bounds rectangle. The driver must | |
164 | adjust the area to fit to the bounding limits. Moreover, the driver can | |
165 | perform other adjustments according to hardware limitations.</para> | |
166 | ||
167 | <para>The device has a default composing rectangle, given by the | |
168 | <constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant> target. This rectangle shall cover what | |
8af4922f | 169 | the driver writer considers the complete picture. It is recommended for the |
d2dbd9d5 HV |
170 | driver developers to put the top/left corner at position <constant>(0,0)</constant>. |
171 | Drivers shall set the active composing rectangle to the default | |
8af4922f TS |
172 | one when the driver is first loaded.</para> |
173 | ||
174 | <para>The devices may introduce additional content to video signal other than | |
175 | an image from memory buffers. It includes borders around an image. However, | |
176 | such a padded area is driver-dependent feature not covered by this document. | |
177 | Driver developers are encouraged to keep padded rectangle equal to active one. | |
d2dbd9d5 HV |
178 | The padded target is accessed by the <constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant> |
179 | identifier. It must contain all pixels from the <constant>V4L2_SEL_TGT_COMPOSE</constant> | |
180 | target.</para> | |
8af4922f TS |
181 | |
182 | </section> | |
183 | ||
184 | <section> | |
185 | ||
9080d5d3 | 186 | <title>Scaling control</title> |
8af4922f TS |
187 | |
188 | <para>An application can detect if scaling is performed by comparing the width | |
d2dbd9d5 HV |
189 | and the height of rectangles obtained using <constant>V4L2_SEL_TGT_CROP</constant> |
190 | and <constant>V4L2_SEL_TGT_COMPOSE</constant> targets. If | |
8af4922f TS |
191 | these are not equal then the scaling is applied. The application can compute |
192 | the scaling ratios using these values.</para> | |
193 | ||
194 | </section> | |
195 | ||
196 | </section> | |
197 | ||
198 | <section> | |
199 | ||
9080d5d3 | 200 | <title>Comparison with old cropping API</title> |
8af4922f TS |
201 | |
202 | <para>The selection API was introduced to cope with deficiencies of previous | |
d2dbd9d5 | 203 | <link linkend="crop"> API</link>, that was designed to control simple capture |
8af4922f TS |
204 | devices. Later the cropping API was adopted by video output drivers. The ioctls |
205 | are used to select a part of the display were the video signal is inserted. It | |
206 | should be considered as an API abuse because the described operation is | |
207 | actually the composing. The selection API makes a clear distinction between | |
208 | composing and cropping operations by setting the appropriate targets. The V4L2 | |
209 | API lacks any support for composing to and cropping from an image inside a | |
210 | memory buffer. The application could configure a capture device to fill only a | |
211 | part of an image by abusing V4L2 API. Cropping a smaller image from a larger | |
071408b6 HV |
212 | one is achieved by setting the field |
213 | &v4l2-pix-format;<structfield>::bytesperline</structfield>. Introducing an image offsets | |
214 | could be done by modifying field &v4l2-buffer;<structfield>::m_userptr</structfield> | |
d2dbd9d5 | 215 | before calling <constant>VIDIOC_QBUF</constant>. Those |
8af4922f TS |
216 | operations should be avoided because they are not portable (endianness), and do |
217 | not work for macroblock and Bayer formats and mmap buffers. The selection API | |
218 | deals with configuration of buffer cropping/composing in a clear, intuitive and | |
219 | portable way. Next, with the selection API the concepts of the padded target | |
071408b6 HV |
220 | and constraints flags are introduced. Finally, &v4l2-crop; and &v4l2-cropcap; |
221 | have no reserved fields. Therefore there is no way to extend their functionality. | |
222 | The new &v4l2-selection; provides a lot of place for future | |
8af4922f | 223 | extensions. Driver developers are encouraged to implement only selection API. |
d2dbd9d5 | 224 | The former cropping API would be simulated using the new one.</para> |
8af4922f TS |
225 | |
226 | </section> | |
227 | ||
228 | <section> | |
229 | <title>Examples</title> | |
230 | <example> | |
231 | <title>Resetting the cropping parameters</title> | |
232 | ||
d2dbd9d5 HV |
233 | <para>(A video capture device is assumed; change |
234 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other devices; change target to | |
235 | <constant>V4L2_SEL_TGT_COMPOSE_*</constant> family to configure composing | |
8af4922f TS |
236 | area)</para> |
237 | ||
238 | <programlisting> | |
239 | ||
240 | &v4l2-selection; sel = { | |
241 | .type = V4L2_BUF_TYPE_VIDEO_CAPTURE, | |
242 | .target = V4L2_SEL_TGT_CROP_DEFAULT, | |
243 | }; | |
244 | ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); | |
245 | if (ret) | |
246 | exit(-1); | |
c1334823 | 247 | sel.target = V4L2_SEL_TGT_CROP; |
8af4922f TS |
248 | ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); |
249 | if (ret) | |
250 | exit(-1); | |
251 | ||
252 | </programlisting> | |
253 | </example> | |
254 | ||
255 | <example> | |
256 | <title>Simple downscaling</title> | |
257 | <para>Setting a composing area on output of size of <emphasis> at most | |
258 | </emphasis> half of limit placed at a center of a display.</para> | |
259 | <programlisting> | |
260 | ||
261 | &v4l2-selection; sel = { | |
262 | .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, | |
263 | .target = V4L2_SEL_TGT_COMPOSE_BOUNDS, | |
264 | }; | |
265 | struct v4l2_rect r; | |
266 | ||
267 | ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); | |
268 | if (ret) | |
269 | exit(-1); | |
270 | /* setting smaller compose rectangle */ | |
271 | r.width = sel.r.width / 2; | |
272 | r.height = sel.r.height / 2; | |
273 | r.left = sel.r.width / 4; | |
274 | r.top = sel.r.height / 4; | |
275 | sel.r = r; | |
c1334823 | 276 | sel.target = V4L2_SEL_TGT_COMPOSE; |
8af4922f TS |
277 | sel.flags = V4L2_SEL_FLAG_LE; |
278 | ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); | |
279 | if (ret) | |
280 | exit(-1); | |
281 | ||
282 | </programlisting> | |
283 | </example> | |
284 | ||
285 | <example> | |
286 | <title>Querying for scaling factors</title> | |
d2dbd9d5 HV |
287 | <para>A video output device is assumed; change |
288 | <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> for other devices</para> | |
8af4922f TS |
289 | <programlisting> |
290 | ||
291 | &v4l2-selection; compose = { | |
292 | .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, | |
c1334823 | 293 | .target = V4L2_SEL_TGT_COMPOSE, |
8af4922f TS |
294 | }; |
295 | &v4l2-selection; crop = { | |
296 | .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, | |
c1334823 | 297 | .target = V4L2_SEL_TGT_CROP, |
8af4922f TS |
298 | }; |
299 | double hscale, vscale; | |
300 | ||
301 | ret = ioctl(fd, &VIDIOC-G-SELECTION;, &compose); | |
302 | if (ret) | |
303 | exit(-1); | |
304 | ret = ioctl(fd, &VIDIOC-G-SELECTION;, &crop); | |
305 | if (ret) | |
306 | exit(-1); | |
307 | ||
308 | /* computing scaling factors */ | |
309 | hscale = (double)compose.r.width / crop.r.width; | |
310 | vscale = (double)compose.r.height / crop.r.height; | |
311 | ||
312 | </programlisting> | |
313 | </example> | |
314 | ||
315 | </section> | |
316 | ||
317 | </section> |