diff options
author | Sakari Ailus <sakari.ailus@iki.fi> | 2011-12-12 16:17:25 -0500 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@redhat.com> | 2012-04-10 16:11:27 -0400 |
commit | 955f645aea04f3130d39c7889e2c5bd7f6d638a3 (patch) | |
tree | a1f722a529b28c43293af376466718c78fec90fb | |
parent | 59ef29cc86afb3a22b2ba96a1c276d332639fc30 (diff) |
[media] v4l: Add subdev selections documentation
Add documentation for V4L2 subdev selection API. This changes also
experimental V4L2 subdev API so that scaling now works through selection API
only.
Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
-rw-r--r-- | Documentation/DocBook/media/Makefile | 4 | ||||
-rw-r--r-- | Documentation/DocBook/media/v4l/compat.xml | 9 | ||||
-rw-r--r-- | Documentation/DocBook/media/v4l/dev-subdev.xml | 202 | ||||
-rw-r--r-- | Documentation/DocBook/media/v4l/v4l2.xml | 15 | ||||
-rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml | 228 |
5 files changed, 432 insertions, 26 deletions
diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 6628b4b9cac4..362520992ced 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile | |||
@@ -70,6 +70,8 @@ IOCTLS = \ | |||
70 | VIDIOC_SUBDEV_ENUM_MBUS_CODE \ | 70 | VIDIOC_SUBDEV_ENUM_MBUS_CODE \ |
71 | VIDIOC_SUBDEV_ENUM_FRAME_SIZE \ | 71 | VIDIOC_SUBDEV_ENUM_FRAME_SIZE \ |
72 | VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL \ | 72 | VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL \ |
73 | VIDIOC_SUBDEV_G_SELECTION \ | ||
74 | VIDIOC_SUBDEV_S_SELECTION \ | ||
73 | 75 | ||
74 | TYPES = \ | 76 | TYPES = \ |
75 | $(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/linux/videodev2.h) \ | 77 | $(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/linux/videodev2.h) \ |
@@ -193,7 +195,7 @@ DVB_DOCUMENTED = \ | |||
193 | # | 195 | # |
194 | 196 | ||
195 | install_media_images = \ | 197 | install_media_images = \ |
196 | $(Q)cp $(OBJIMGFILES) $(MEDIA_OBJ_DIR)/media_api | 198 | $(Q)cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api |
197 | 199 | ||
198 | $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64 | 200 | $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64 |
199 | $(Q)base64 -d $< >$@ | 201 | $(Q)base64 -d $< >$@ |
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index d881520e1a54..0fc74ca81f0f 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml | |||
@@ -2417,6 +2417,11 @@ details.</para> | |||
2417 | <para>Added integer menus, the new type will be | 2417 | <para>Added integer menus, the new type will be |
2418 | V4L2_CTRL_TYPE_INTEGER_MENU.</para> | 2418 | V4L2_CTRL_TYPE_INTEGER_MENU.</para> |
2419 | </listitem> | 2419 | </listitem> |
2420 | <listitem> | ||
2421 | <para>Added selection API for V4L2 subdev interface: | ||
2422 | &VIDIOC-SUBDEV-G-SELECTION; and | ||
2423 | &VIDIOC-SUBDEV-S-SELECTION;.</para> | ||
2424 | </listitem> | ||
2420 | </orderedlist> | 2425 | </orderedlist> |
2421 | </section> | 2426 | </section> |
2422 | 2427 | ||
@@ -2533,6 +2538,10 @@ ioctls.</para> | |||
2533 | <listitem> | 2538 | <listitem> |
2534 | <para>Selection API. <xref linkend="selection-api" /></para> | 2539 | <para>Selection API. <xref linkend="selection-api" /></para> |
2535 | </listitem> | 2540 | </listitem> |
2541 | <listitem> | ||
2542 | <para>Sub-device selection API: &VIDIOC-SUBDEV-G-SELECTION; | ||
2543 | and &VIDIOC-SUBDEV-S-SELECTION; ioctls.</para> | ||
2544 | </listitem> | ||
2536 | </itemizedlist> | 2545 | </itemizedlist> |
2537 | </section> | 2546 | </section> |
2538 | 2547 | ||
diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index 0916a7343a16..4afcbbec5eda 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml | |||
@@ -76,11 +76,12 @@ | |||
76 | <wordasword>format</wordasword> means the combination of media bus data | 76 | <wordasword>format</wordasword> means the combination of media bus data |
77 | format, frame width and frame height.</para></note> | 77 | format, frame width and frame height.</para></note> |
78 | 78 | ||
79 | <para>Image formats are typically negotiated on video capture and output | 79 | <para>Image formats are typically negotiated on video capture and |
80 | devices using the <link linkend="crop">cropping and scaling</link> ioctls. | 80 | output devices using the format and <link |
81 | The driver is responsible for configuring every block in the video pipeline | 81 | linkend="vidioc-subdev-g-selection">selection</link> ioctls. The |
82 | according to the requested format at the pipeline input and/or | 82 | driver is responsible for configuring every block in the video |
83 | output.</para> | 83 | pipeline according to the requested format at the pipeline input |
84 | and/or output.</para> | ||
84 | 85 | ||
85 | <para>For complex devices, such as often found in embedded systems, | 86 | <para>For complex devices, such as often found in embedded systems, |
86 | identical image sizes at the output of a pipeline can be achieved using | 87 | identical image sizes at the output of a pipeline can be achieved using |
@@ -276,11 +277,11 @@ | |||
276 | </section> | 277 | </section> |
277 | 278 | ||
278 | <section> | 279 | <section> |
279 | <title>Cropping and scaling</title> | 280 | <title>Selections: cropping, scaling and composition</title> |
280 | 281 | ||
281 | <para>Many sub-devices support cropping frames on their input or output | 282 | <para>Many sub-devices support cropping frames on their input or output |
282 | pads (or possible even on both). Cropping is used to select the area of | 283 | pads (or possible even on both). Cropping is used to select the area of |
283 | interest in an image, typically on a video sensor or video decoder. It can | 284 | interest in an image, typically on an image sensor or a video decoder. It can |
284 | also be used as part of digital zoom implementations to select the area of | 285 | also be used as part of digital zoom implementations to select the area of |
285 | the image that will be scaled up.</para> | 286 | the image that will be scaled up.</para> |
286 | 287 | ||
@@ -288,26 +289,179 @@ | |||
288 | &v4l2-rect; by the coordinates of the top left corner and the rectangle | 289 | &v4l2-rect; by the coordinates of the top left corner and the rectangle |
289 | size. Both the coordinates and sizes are expressed in pixels.</para> | 290 | size. Both the coordinates and sizes are expressed in pixels.</para> |
290 | 291 | ||
291 | <para>The crop rectangle is retrieved and set using the | 292 | <para>As for pad formats, drivers store try and active |
292 | &VIDIOC-SUBDEV-G-CROP; and &VIDIOC-SUBDEV-S-CROP; ioctls. Like for pad | 293 | rectangles for the selection targets of ACTUAL type <xref |
293 | formats, drivers store try and active crop rectangles. The format | 294 | linkend="v4l2-subdev-selection-targets">.</xref></para> |
294 | negotiation mechanism applies to crop settings as well.</para> | 295 | |
295 | 296 | <para>On sink pads, cropping is applied relative to the | |
296 | <para>On input pads, cropping is applied relatively to the current pad | 297 | current pad format. The pad format represents the image size as |
297 | format. The pad format represents the image size as received by the | 298 | received by the sub-device from the previous block in the |
298 | sub-device from the previous block in the pipeline, and the crop rectangle | 299 | pipeline, and the crop rectangle represents the sub-image that |
299 | represents the sub-image that will be transmitted further inside the | 300 | will be transmitted further inside the sub-device for |
300 | sub-device for processing. The crop rectangle be entirely containted | 301 | processing.</para> |
301 | inside the input image size.</para> | 302 | |
302 | 303 | <para>The scaling operation changes the size of the image by | |
303 | <para>Input crop rectangle are reset to their default value when the input | 304 | scaling it to new dimensions. The scaling ratio isn't specified |
304 | image format is modified. Drivers should use the input image size as the | 305 | explicitly, but is implied from the original and scaled image |
305 | crop rectangle default value, but hardware requirements may prevent this. | 306 | sizes. Both sizes are represented by &v4l2-rect;.</para> |
306 | </para> | 307 | |
308 | <para>Scaling support is optional. When supported by a subdev, | ||
309 | the crop rectangle on the subdev's sink pad is scaled to the | ||
310 | size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL | ||
311 | using <constant>V4L2_SUBDEV_SEL_COMPOSE_ACTUAL</constant> | ||
312 | selection target on the same pad. If the subdev supports scaling | ||
313 | but not composing, the top and left values are not used and must | ||
314 | always be set to zero.</para> | ||
315 | |||
316 | <para>On source pads, cropping is similar to sink pads, with the | ||
317 | exception that the source size from which the cropping is | ||
318 | performed, is the COMPOSE rectangle on the sink pad. In both | ||
319 | sink and source pads, the crop rectangle must be entirely | ||
320 | contained inside the source image size for the crop | ||
321 | operation.</para> | ||
322 | |||
323 | <para>The drivers should always use the closest possible | ||
324 | rectangle the user requests on all selection targets, unless | ||
325 | specifically told otherwise. | ||
326 | <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant> and | ||
327 | <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant> flags may be | ||
328 | used to round the image size either up or down. <xref | ||
329 | linkend="v4l2-subdev-selection-flags"></xref></para> | ||
330 | </section> | ||
331 | |||
332 | <section> | ||
333 | <title>Types of selection targets</title> | ||
334 | |||
335 | <section> | ||
336 | <title>ACTUAL targets</title> | ||
337 | |||
338 | <para>ACTUAL targets reflect the actual hardware configuration | ||
339 | at any point of time. There is a BOUNDS target | ||
340 | corresponding to every ACTUAL.</para> | ||
341 | </section> | ||
342 | |||
343 | <section> | ||
344 | <title>BOUNDS targets</title> | ||
345 | |||
346 | <para>BOUNDS targets is the smallest rectangle that contains | ||
347 | all valid ACTUAL rectangles. It may not be possible to set the | ||
348 | ACTUAL rectangle as large as the BOUNDS rectangle, however. | ||
349 | This may be because e.g. a sensor's pixel array is not | ||
350 | rectangular but cross-shaped or round. The maximum size may | ||
351 | also be smaller than the BOUNDS rectangle.</para> | ||
352 | </section> | ||
307 | 353 | ||
308 | <para>Cropping behaviour on output pads is not defined.</para> | 354 | </section> |
355 | |||
356 | <section> | ||
357 | <title>Order of configuration and format propagation</title> | ||
358 | |||
359 | <para>Inside subdevs, the order of image processing steps will | ||
360 | always be from the sink pad towards the source pad. This is also | ||
361 | reflected in the order in which the configuration must be | ||
362 | performed by the user: the changes made will be propagated to | ||
363 | any subsequent stages. If this behaviour is not desired, the | ||
364 | user must set | ||
365 | <constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant> flag. This | ||
366 | flag causes no propagation of the changes are allowed in any | ||
367 | circumstances. This may also cause the accessed rectangle to be | ||
368 | adjusted by the driver, depending on the properties of the | ||
369 | underlying hardware.</para> | ||
370 | |||
371 | <para>The coordinates to a step always refer to the actual size | ||
372 | of the previous step. The exception to this rule is the source | ||
373 | compose rectangle, which refers to the sink compose bounds | ||
374 | rectangle --- if it is supported by the hardware.</para> | ||
375 | |||
376 | <orderedlist> | ||
377 | <listitem>Sink pad format. The user configures the sink pad | ||
378 | format. This format defines the parameters of the image the | ||
379 | entity receives through the pad for further processing.</listitem> | ||
380 | |||
381 | <listitem>Sink pad actual crop selection. The sink pad crop | ||
382 | defines the crop performed to the sink pad format.</listitem> | ||
383 | |||
384 | <listitem>Sink pad actual compose selection. The size of the | ||
385 | sink pad compose rectangle defines the scaling ratio compared | ||
386 | to the size of the sink pad crop rectangle. The location of | ||
387 | the compose rectangle specifies the location of the actual | ||
388 | sink compose rectangle in the sink compose bounds | ||
389 | rectangle.</listitem> | ||
390 | |||
391 | <listitem>Source pad actual crop selection. Crop on the source | ||
392 | pad defines crop performed to the image in the sink compose | ||
393 | bounds rectangle.</listitem> | ||
394 | |||
395 | <listitem>Source pad format. The source pad format defines the | ||
396 | output pixel format of the subdev, as well as the other | ||
397 | parameters with the exception of the image width and height. | ||
398 | Width and height are defined by the size of the source pad | ||
399 | actual crop selection.</listitem> | ||
400 | </orderedlist> | ||
401 | |||
402 | <para>Accessing any of the above rectangles not supported by the | ||
403 | subdev will return <constant>EINVAL</constant>. Any rectangle | ||
404 | referring to a previous unsupported rectangle coordinates will | ||
405 | instead refer to the previous supported rectangle. For example, | ||
406 | if sink crop is not supported, the compose selection will refer | ||
407 | to the sink pad format dimensions instead.</para> | ||
408 | |||
409 | <figure id="subdev-image-processing-crop"> | ||
410 | <title>Image processing in subdevs: simple crop example</title> | ||
411 | <mediaobject> | ||
412 | <imageobject> | ||
413 | <imagedata fileref="subdev-image-processing-crop.svg" | ||
414 | format="SVG" scale="200" /> | ||
415 | </imageobject> | ||
416 | </mediaobject> | ||
417 | </figure> | ||
418 | |||
419 | <para>In the above example, the subdev supports cropping on its | ||
420 | sink pad. To configure it, the user sets the media bus format on | ||
421 | the subdev's sink pad. Now the actual crop rectangle can be set | ||
422 | on the sink pad --- the location and size of this rectangle | ||
423 | reflect the location and size of a rectangle to be cropped from | ||
424 | the sink format. The size of the sink crop rectangle will also | ||
425 | be the size of the format of the subdev's source pad.</para> | ||
426 | |||
427 | <figure id="subdev-image-processing-scaling-multi-source"> | ||
428 | <title>Image processing in subdevs: scaling with multiple sources</title> | ||
429 | <mediaobject> | ||
430 | <imageobject> | ||
431 | <imagedata fileref="subdev-image-processing-scaling-multi-source.svg" | ||
432 | format="SVG" scale="200" /> | ||
433 | </imageobject> | ||
434 | </mediaobject> | ||
435 | </figure> | ||
436 | |||
437 | <para>In this example, the subdev is capable of first cropping, | ||
438 | then scaling and finally cropping for two source pads | ||
439 | individually from the resulting scaled image. The location of | ||
440 | the scaled image in the cropped image is ignored in sink compose | ||
441 | target. Both of the locations of the source crop rectangles | ||
442 | refer to the sink scaling rectangle, independently cropping an | ||
443 | area at location specified by the source crop rectangle from | ||
444 | it.</para> | ||
445 | |||
446 | <figure id="subdev-image-processing-full"> | ||
447 | <title>Image processing in subdevs: scaling and composition | ||
448 | with multiple sinks and sources</title> | ||
449 | <mediaobject> | ||
450 | <imageobject> | ||
451 | <imagedata fileref="subdev-image-processing-full.svg" | ||
452 | format="SVG" scale="200" /> | ||
453 | </imageobject> | ||
454 | </mediaobject> | ||
455 | </figure> | ||
456 | |||
457 | <para>The subdev driver supports two sink pads and two source | ||
458 | pads. The images from both of the sink pads are individually | ||
459 | cropped, then scaled and further composed on the composition | ||
460 | bounds rectangle. From that, two independent streams are cropped | ||
461 | and sent out of the subdev from the source pads.</para> | ||
309 | 462 | ||
310 | </section> | 463 | </section> |
464 | |||
311 | </section> | 465 | </section> |
312 | 466 | ||
313 | &sub-subdev-formats; | 467 | &sub-subdev-formats; |
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 864ba5d6873d..fbf808d242f7 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml | |||
@@ -96,6 +96,17 @@ Remote Controller chapter.</contrib> | |||
96 | </address> | 96 | </address> |
97 | </affiliation> | 97 | </affiliation> |
98 | </author> | 98 | </author> |
99 | |||
100 | <author> | ||
101 | <firstname>Sakari</firstname> | ||
102 | <surname>Ailus</surname> | ||
103 | <contrib>Subdev selections API.</contrib> | ||
104 | <affiliation> | ||
105 | <address> | ||
106 | <email>sakari.ailus@iki.fi</email> | ||
107 | </address> | ||
108 | </affiliation> | ||
109 | </author> | ||
99 | </authorgroup> | 110 | </authorgroup> |
100 | 111 | ||
101 | <copyright> | 112 | <copyright> |
@@ -131,7 +142,8 @@ applications. --> | |||
131 | <revnumber>3.5</revnumber> | 142 | <revnumber>3.5</revnumber> |
132 | <date>2012-04-02</date> | 143 | <date>2012-04-02</date> |
133 | <authorinitials>sa</authorinitials> | 144 | <authorinitials>sa</authorinitials> |
134 | <revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU. | 145 | <revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev |
146 | selections API. | ||
135 | </revremark> | 147 | </revremark> |
136 | </revision> | 148 | </revision> |
137 | 149 | ||
@@ -548,6 +560,7 @@ and discussions on the V4L mailing list.</revremark> | |||
548 | &sub-subdev-g-crop; | 560 | &sub-subdev-g-crop; |
549 | &sub-subdev-g-fmt; | 561 | &sub-subdev-g-fmt; |
550 | &sub-subdev-g-frame-interval; | 562 | &sub-subdev-g-frame-interval; |
563 | &sub-subdev-g-selection; | ||
551 | &sub-subscribe-event; | 564 | &sub-subscribe-event; |
552 | <!-- End of ioctls. --> | 565 | <!-- End of ioctls. --> |
553 | &sub-mmap; | 566 | &sub-mmap; |
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml new file mode 100644 index 000000000000..208e9f0da3f3 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml | |||
@@ -0,0 +1,228 @@ | |||
1 | <refentry id="vidioc-subdev-g-selection"> | ||
2 | <refmeta> | ||
3 | <refentrytitle>ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</refentrytitle> | ||
4 | &manvol; | ||
5 | </refmeta> | ||
6 | |||
7 | <refnamediv> | ||
8 | <refname>VIDIOC_SUBDEV_G_SELECTION</refname> | ||
9 | <refname>VIDIOC_SUBDEV_S_SELECTION</refname> | ||
10 | <refpurpose>Get or set selection rectangles on a subdev pad</refpurpose> | ||
11 | </refnamediv> | ||
12 | |||
13 | <refsynopsisdiv> | ||
14 | <funcsynopsis> | ||
15 | <funcprototype> | ||
16 | <funcdef>int <function>ioctl</function></funcdef> | ||
17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
19 | <paramdef>struct v4l2_subdev_selection *<parameter>argp</parameter></paramdef> | ||
20 | </funcprototype> | ||
21 | </funcsynopsis> | ||
22 | </refsynopsisdiv> | ||
23 | |||
24 | <refsect1> | ||
25 | <title>Arguments</title> | ||
26 | |||
27 | <variablelist> | ||
28 | <varlistentry> | ||
29 | <term><parameter>fd</parameter></term> | ||
30 | <listitem> | ||
31 | <para>&fd;</para> | ||
32 | </listitem> | ||
33 | </varlistentry> | ||
34 | <varlistentry> | ||
35 | <term><parameter>request</parameter></term> | ||
36 | <listitem> | ||
37 | <para>VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</para> | ||
38 | </listitem> | ||
39 | </varlistentry> | ||
40 | <varlistentry> | ||
41 | <term><parameter>argp</parameter></term> | ||
42 | <listitem> | ||
43 | <para></para> | ||
44 | </listitem> | ||
45 | </varlistentry> | ||
46 | </variablelist> | ||
47 | </refsect1> | ||
48 | |||
49 | <refsect1> | ||
50 | <title>Description</title> | ||
51 | |||
52 | <note> | ||
53 | <title>Experimental</title> | ||
54 | <para>This is an <link linkend="experimental">experimental</link> | ||
55 | interface and may change in the future.</para> | ||
56 | </note> | ||
57 | |||
58 | <para>The selections are used to configure various image | ||
59 | processing functionality performed by the subdevs which affect the | ||
60 | image size. This currently includes cropping, scaling and | ||
61 | composition.</para> | ||
62 | |||
63 | <para>The selection API replaces <link | ||
64 | linkend="vidioc-subdev-g-crop">the old subdev crop API</link>. All | ||
65 | the function of the crop API, and more, are supported by the | ||
66 | selections API.</para> | ||
67 | |||
68 | <para>See <xref linkend="subdev"></xref> for | ||
69 | more information on how each selection target affects the image | ||
70 | processing pipeline inside the subdevice.</para> | ||
71 | |||
72 | <section> | ||
73 | <title>Types of selection targets</title> | ||
74 | |||
75 | <para>There are two types of selection targets: actual and bounds. | ||
76 | The ACTUAL targets are the targets which configure the hardware. | ||
77 | The BOUNDS target will return a rectangle that contain all | ||
78 | possible ACTUAL rectangles.</para> | ||
79 | </section> | ||
80 | |||
81 | <section> | ||
82 | <title>Discovering supported features</title> | ||
83 | |||
84 | <para>To discover which targets are supported, the user can | ||
85 | perform <constant>VIDIOC_SUBDEV_G_SELECTION</constant> on them. | ||
86 | Any unsupported target will return | ||
87 | <constant>EINVAL</constant>.</para> | ||
88 | </section> | ||
89 | |||
90 | <table pgwide="1" frame="none" id="v4l2-subdev-selection-targets"> | ||
91 | <title>V4L2 subdev selection targets</title> | ||
92 | <tgroup cols="3"> | ||
93 | &cs-def; | ||
94 | <tbody valign="top"> | ||
95 | <row> | ||
96 | <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL</constant></entry> | ||
97 | <entry>0x0000</entry> | ||
98 | <entry>Actual crop. Defines the cropping | ||
99 | performed by the processing step.</entry> | ||
100 | </row> | ||
101 | <row> | ||
102 | <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS</constant></entry> | ||
103 | <entry>0x0002</entry> | ||
104 | <entry>Bounds of the crop rectangle.</entry> | ||
105 | </row> | ||
106 | <row> | ||
107 | <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL</constant></entry> | ||
108 | <entry>0x0100</entry> | ||
109 | <entry>Actual compose rectangle. Used to configure scaling | ||
110 | on sink pads and composition on source pads.</entry> | ||
111 | </row> | ||
112 | <row> | ||
113 | <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS</constant></entry> | ||
114 | <entry>0x0102</entry> | ||
115 | <entry>Bounds of the compose rectangle.</entry> | ||
116 | </row> | ||
117 | </tbody> | ||
118 | </tgroup> | ||
119 | </table> | ||
120 | |||
121 | <table pgwide="1" frame="none" id="v4l2-subdev-selection-flags"> | ||
122 | <title>V4L2 subdev selection flags</title> | ||
123 | <tgroup cols="3"> | ||
124 | &cs-def; | ||
125 | <tbody valign="top"> | ||
126 | <row> | ||
127 | <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant></entry> | ||
128 | <entry>(1 << 0)</entry> <entry>Suggest the driver it | ||
129 | should choose greater or equal rectangle (in size) than | ||
130 | was requested. Albeit the driver may choose a lesser size, | ||
131 | it will only do so due to hardware limitations. Without | ||
132 | this flag (and | ||
133 | <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant>) the | ||
134 | behaviour is to choose the closest possible | ||
135 | rectangle.</entry> | ||
136 | </row> | ||
137 | <row> | ||
138 | <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant></entry> | ||
139 | <entry>(1 << 1)</entry> <entry>Suggest the driver it | ||
140 | should choose lesser or equal rectangle (in size) than was | ||
141 | requested. Albeit the driver may choose a greater size, it | ||
142 | will only do so due to hardware limitations.</entry> | ||
143 | </row> | ||
144 | <row> | ||
145 | <entry><constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant></entry> | ||
146 | <entry>(1 << 2)</entry> | ||
147 | <entry>The configuration should not be propagated to any | ||
148 | further processing steps. If this flag is not given, the | ||
149 | configuration is propagated inside the subdevice to all | ||
150 | further processing steps.</entry> | ||
151 | </row> | ||
152 | </tbody> | ||
153 | </tgroup> | ||
154 | </table> | ||
155 | |||
156 | <table pgwide="1" frame="none" id="v4l2-subdev-selection"> | ||
157 | <title>struct <structname>v4l2_subdev_selection</structname></title> | ||
158 | <tgroup cols="3"> | ||
159 | &cs-str; | ||
160 | <tbody valign="top"> | ||
161 | <row> | ||
162 | <entry>__u32</entry> | ||
163 | <entry><structfield>which</structfield></entry> | ||
164 | <entry>Active or try selection, from | ||
165 | &v4l2-subdev-format-whence;.</entry> | ||
166 | </row> | ||
167 | <row> | ||
168 | <entry>__u32</entry> | ||
169 | <entry><structfield>pad</structfield></entry> | ||
170 | <entry>Pad number as reported by the media framework.</entry> | ||
171 | </row> | ||
172 | <row> | ||
173 | <entry>__u32</entry> | ||
174 | <entry><structfield>target</structfield></entry> | ||
175 | <entry>Target selection rectangle. See | ||
176 | <xref linkend="v4l2-subdev-selection-targets">.</xref>.</entry> | ||
177 | </row> | ||
178 | <row> | ||
179 | <entry>__u32</entry> | ||
180 | <entry><structfield>flags</structfield></entry> | ||
181 | <entry>Flags. See | ||
182 | <xref linkend="v4l2-subdev-selection-flags">.</xref></entry> | ||
183 | </row> | ||
184 | <row> | ||
185 | <entry>&v4l2-rect;</entry> | ||
186 | <entry><structfield>rect</structfield></entry> | ||
187 | <entry>Selection rectangle, in pixels.</entry> | ||
188 | </row> | ||
189 | <row> | ||
190 | <entry>__u32</entry> | ||
191 | <entry><structfield>reserved</structfield>[8]</entry> | ||
192 | <entry>Reserved for future extensions. Applications and drivers must | ||
193 | set the array to zero.</entry> | ||
194 | </row> | ||
195 | </tbody> | ||
196 | </tgroup> | ||
197 | </table> | ||
198 | |||
199 | </refsect1> | ||
200 | |||
201 | <refsect1> | ||
202 | &return-value; | ||
203 | |||
204 | <variablelist> | ||
205 | <varlistentry> | ||
206 | <term><errorcode>EBUSY</errorcode></term> | ||
207 | <listitem> | ||
208 | <para>The selection rectangle can't be changed because the | ||
209 | pad is currently busy. This can be caused, for instance, by | ||
210 | an active video stream on the pad. The ioctl must not be | ||
211 | retried without performing another action to fix the problem | ||
212 | first. Only returned by | ||
213 | <constant>VIDIOC_SUBDEV_S_SELECTION</constant></para> | ||
214 | </listitem> | ||
215 | </varlistentry> | ||
216 | <varlistentry> | ||
217 | <term><errorcode>EINVAL</errorcode></term> | ||
218 | <listitem> | ||
219 | <para>The &v4l2-subdev-selection; | ||
220 | <structfield>pad</structfield> references a non-existing | ||
221 | pad, the <structfield>which</structfield> field references a | ||
222 | non-existing format, or the selection target is not | ||
223 | supported on the given subdev pad.</para> | ||
224 | </listitem> | ||
225 | </varlistentry> | ||
226 | </variablelist> | ||
227 | </refsect1> | ||
228 | </refentry> | ||