Signed-off-by: Tomasz Stanislawski<t.stanislaws@xxxxxxxxxxx>
Signed-off-by: Kyungmin Park<kyungmin.park@xxxxxxxxxxx>
---
Documentation/DocBook/media/v4l/common.xml | 2 +
Documentation/DocBook/media/v4l/compat.xml | 9 +
Documentation/DocBook/media/v4l/selection-api.xml | 327 ++++++++++++++++++++
Documentation/DocBook/media/v4l/v4l2.xml | 1 +
.../DocBook/media/v4l/vidioc-g-selection.xml | 303 ++++++++++++++++++
5 files changed, 642 insertions(+), 0 deletions(-)
create mode 100644 Documentation/DocBook/media/v4l/selection-api.xml
create mode 100644 Documentation/DocBook/media/v4l/vidioc-g-selection.xml
diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
index a86f7a0..9c8db86 100644
--- a/Documentation/DocBook/media/v4l/common.xml
+++ b/Documentation/DocBook/media/v4l/common.xml
@@ -1168,6 +1168,8 @@ dheight = format.fmt.pix.height;
</section>
</section>
+&sub-selection-api;
+
<section id="streaming-par">
<title>Streaming Parameters</title>
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index 91410b6..7c430ca 100644
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2376,6 +2376,12 @@ that used it. It was originally scheduled for removal in 2.6.35.
<listitem>
<para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para>
</listitem>
+<listitem>
+ <para>Add selection API for extended control over cropping and
+composing. Does not affect the compatibility of current drivers and
+applications. See<link linkend="selection-api"> selection API</link> for
+details.</para>
+</listitem>
</orderedlist>
</section>
@@ -2486,6 +2492,9 @@ ioctls.</para>
<listitem>
<para>Flash API.<xref linkend="flash-controls" /></para>
</listitem>
+<listitem>
+ <para>Selection API.<xref linkend="selection-api" /></para>
+</listitem>
</itemizedlist>
</section>
diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml
new file mode 100644
index 0000000..3b6dfe0
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/selection-api.xml
@@ -0,0 +1,327 @@
+<section id="selection-api">
+
+<title>Experimental API for cropping, composing and scaling</title>
+
+<note>
+ <title>Experimental</title>
+
+ <para>This is an<link linkend="experimental">experimental</link>
+interface and may change in the future.</para>
+</note>
+
+<section>
+<title>Introduction</title>
+
+<para>Some video capture devices can sample a subsection of a picture and
+shrink or enlarge it to an image of arbitrary size. Next, the devices can
+insert the image into larger one. Some video output devices can crop part of an
+input image, scale it up or down and insert it at an arbitrary scan line and
+horizontal offset into a video signal. We call these abilities cropping,
+scaling and composing.</para>
+
+<para>On a video<emphasis>capture</emphasis> device the source is a video
+signal, and the cropping target determine the area actually sampled. The sink
+is an image stored in a memory buffer. The composing area specifies which part
+of the buffer is actually written to by the hardware.</para>
+
+<para>On a video<emphasis>output</emphasis> device the source is an image in a
+memory buffer, and the cropping target is a part of an image to be shown on a
+display. The sink is the display or the graphics screen. The application may
+select the part of display where the image should be displayed. The size and
+position of such a window is controlled by the compose target.</para>
+
+<para>Rectangles for all cropping and composing targets are defined even if the
+device does supports neither cropping nor composing. Their size and position
+will be fixed in such a case. If the device does not support scaling then the
+cropping and composing rectangles have the same size.</para>
+
+</section>
+
+<section>
+<title>Selection targets</title>
+
+<figure id="sel-targets-capture">
+ <title>Cropping and composing targets</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="selection.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <phrase>Targets used by a cropping, composing and scaling
+ process</phrase>
+ </textobject>
+ </mediaobject>
+</figure>
+</section>
+
+<section>
+
+<title>Configuration</title>
+
+<para>Applications can use the<link linkend="vidioc-g-selection">selection
+API</link> to select an area in a video signal or a buffer, and to query for
+default settings and hardware limits.</para>
+
+<para>Video hardware can have various cropping, composing and scaling
+limitations. It may only scale up or down, support only discrete scaling
+factors, or have different scaling abilities in the horizontal and vertical
+directions. Also it may not support scaling at all. At the same time the
+cropping/composing rectangles may have to be aligned, and both the source and
+the sink may have arbitrary upper and lower size limits. Therefore, as usual,
+drivers are expected to adjust the requested parameters and return the actual
+values selected. An application can control the rounding behaviour using<link
+linkend="v4l2-sel-flags"> constraint flags</link>.</para>
+
+<section>
+
+<title>Configuration of video capture</title>
+
+<para>See figure<xref linkend="sel-targets-capture" /> for examples of the
+selection targets available for a video capture device. It is recommended to
+configure the cropping targets before to the composing targets.</para>
+
+<para>The range of coordinates of the top left corner, width and height of
+areas that can be sampled is given by the<constant> V4L2_SEL_CROP_BOUNDS
+</constant> target. It is recommended for the driver developers to put the
+top/left corner at position<constant> (0,0)</constant>. The rectangle's
+coordinates are expressed in driver dependant units, although the coordinate
+system guarantees that if sizes of the active cropping and the active composing
+rectangles are equal then no scaling is performed.</para>
+
+<para>The top left corner, width and height of the source rectangle, that is
+the area actually sampled, is given by the<constant> V4L2_SEL_CROP_ACTIVE
+</constant> target. It uses the same coordinate system as<constant>
+V4L2_SEL_CROP_BOUNDS</constant>. The active cropping area must lie completely
+inside the capture boundaries. The driver may further adjust the requested size
+and/or position according to hardware limitations.</para>
+
+<para>Each capture device has a default source rectangle, given by the
+<constant> V4L2_SEL_CROP_DEFAULT</constant> target. This rectangle shall over
+what the driver writer considers the complete picture. Drivers shall set the
+active crop rectangle to the default when the driver is first loaded, but not
+later.</para>
+
+<para>The composing targets refer to a memory buffer. The limits of composing
+coordinates are obtained using<constant> V4L2_SEL_COMPOSE_BOUNDS</constant>.
+All coordinates are expressed in natural unit for given formats. Pixels are
+highly recommended. The rectangle's top/left corner must be located at
+position<constant> (0,0)</constant>. The width and height are equal to the
+image size set by<constant> VIDIOC_S_FMT</constant>.</para>
+
+<para>The part of a buffer into which the image is inserted by the hardware is
+controlled by the<constant> V4L2_SEL_COMPOSE_ACTIVE</constant> target. The
+rectangle's coordinates are also expressed in the same coordinate system as the
+bounds rectangle. The composing rectangle must lie completely inside bounds
+rectangle. The driver must adjust the composing rectangle to fit to the
+bounding limits. Moreover, the driver can perform other adjustments according
+to hardware limitations. The application can control rounding behaviour using
+<link linkend="v4l2-sel-flags"> constraint flags</link>.</para>
+
+<para>For capture devices the default composing rectangle is queried using
+<constant> V4L2_SEL_COMPOSE_DEFAULT</constant>. It is usually equal to the
+bounding rectangle.</para>
+
+<para>The part of a buffer that is modified by the hardware is given by
+<constant> V4L2_SEL_COMPOSE_PADDED</constant>. It contains all pixels defined
+using<constant> V4L2_SEL_COMPOSE_ACTIVE</constant> plus all padding data
+modified by hardware during insertion process. All pixels outside this rectangle
+<emphasis>must not</emphasis> be changed by the hardware. The content of pixels
+that lie inside the padded area but outside active area is undefined. The
+application can use the padded and active rectangles to detect where the
+rubbish pixels are located and remove them if needed.</para>
+
+</section>
+
+<section>
+
+<title>Configuration of video output</title>
+
+<para>For output devices targets and ioctls are used similarly to the video
+capture case. The<emphasis> composing</emphasis> rectangle refers to the
+insertion of an image into a video signal. The cropping rectangles refer to a
+memory buffer. It is recommended to configure the composing targets before to
+the cropping targets.</para>
+
+<para>The cropping targets refer to the memory buffer that contains an image to
+be inserted into a video signal or graphical screen. The limits of cropping
+coordinates are obtained using<constant> V4L2_SEL_CROP_BOUNDS</constant>. All
+coordinates are expressed in natural units for a given format. Pixels are
+highly recommended. The top/left corner is always point<constant> (0,0)
+</constant>. The width and height is equal to the image size specified using
+<constant> VIDIOC_S_FMT</constant> ioctl.</para>
+
+<para>The top left corner, width and height of the source rectangle, that is
+the area from which image date are processed by the hardware, is given by the
+<constant> V4L2_SEL_CROP_ACTIVE</constant>. Its coordinates are expressed in
+in the same coordinate system as the bounds rectangle. The active cropping area
+must lie completely inside the crop boundaries and the driver may further
+adjust the requested size and/or position according to hardware
+limitations.</para>
+
+<para>For output devices the default cropping rectangle is queried using
+<constant> V4L2_SEL_CROP_DEFAULT</constant>. It is usually equal to the
+bounding rectangle.</para>
+
+<para>The part of a video signal or graphics display where the image is
+inserted by the hardware is controlled by<constant> V4L2_SEL_COMPOSE_ACTIVE
+</constant> target. The rectangle's coordinates are expressed in driver
+dependant units. The only exception are digital outputs where the units are
+pixels. For other types of devices, the coordinate system guarantees that if
+sizes of the active cropping and the active composing rectangles are equal then
+no scaling is performed. The composing rectangle must lie completely inside
+the bounds rectangle. The driver must adjust the area to fit to the bounding
+limits. Moreover, the driver can perform other adjustments according to
+hardware limitations.</para>
+
+<para>The device has a default composing rectangle, given by the<constant>
+V4L2_SEL_COMPOSE_DEFAULT</constant> target. This rectangle shall cover what
+the driver writer considers the complete picture. It is recommended for the
+driver developers to put the top/left corner at position<constant> (0,0)
+</constant>. Drivers shall set the active composing rectangle to the default
+one when the driver is first loaded.</para>
+
+<para>The devices may introduce additional content to video signal other than
+an image from memory buffers. It includes borders around an image. However,
+such a padded area is driver-dependent feature not covered by this document.
+Driver developers are encouraged to keep padded rectangle equal to active one.
+The padded target is accessed by the<constant> V4L2_SEL_COMPOSE_PADDED
+</constant> identifier. It must contain all pixels from the<constant>
+V4L2_SEL_COMPOSE_ACTIVE</constant> target.</para>
+
+</section>
+
+<section>
+
+<title>Scaling control.</title>
+
+<para>An application can detect if scaling is performed by comparing the width
+and the height of rectangles obtained using<constant> V4L2_SEL_CROP_ACTIVE
+</constant> and<constant> V4L2_SEL_COMPOSE_ACTIVE</constant> targets. If
+these are not equal then the scaling is applied. The application can compute
+the scaling ratios using these values.</para>
+
+</section>
+
+</section>
+
+<section>
+
+<title>Comparison with old cropping API.</title>
+
+<para>The selection API was introduced to cope with deficiencies of previous
+<link linkend="crop"> API</link>, that was designed to control simple capture
+devices. Later the cropping API was adopted by video output drivers. The ioctls
+are used to select a part of the display were the video signal is inserted. It
+should be considered as an API abuse because the described operation is
+actually the composing. The selection API makes a clear distinction between
+composing and cropping operations by setting the appropriate targets. The V4L2
+API lacks any support for composing to and cropping from an image inside a
+memory buffer. The application could configure a capture device to fill only a
+part of an image by abusing V4L2 API. Cropping a smaller image from a larger
+one is achieved by setting the field<structfield>
+&v4l2-pix-format;::bytesperline</structfield>. Introducing an image offsets
+could be done by modifying field<structfield> &v4l2-buffer;::m:userptr
+</structfield> before calling<constant> VIDIOC_QBUF</constant>. Those
+operations should be avoided because they are not portable (endianness), and do
+not work for macroblock and Bayer formats and mmap buffers. The selection API
+deals with configuration of buffer cropping/composing in a clear, intuitive and
+portable way. Next, with the selection API the concepts of the padded target
+and constraints flags are introduced. Finally,<structname> &v4l2-crop;
+</structname> and<structname> &v4l2-cropcap;</structname> have no reserved
+fields. Therefore there is no way to extend their functionality. The new
+<structname> &v4l2-selection;</structname> provides a lot of place for future
+extensions. Driver developers are encouraged to implement only selection API.
+The former cropping API would be simulated using the new one.</para>
+
+</section>
+
+<section>
+<title>Examples</title>
+<example>
+ <title>Resetting the cropping parameters</title>
+
+ <para>(A video capture device is assumed; change<constant>
+V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other devices; change target to
+<constant> V4L2_SEL_COMPOSE_*</constant> family to configure composing
+area)</para>
+
+ <programlisting>
+
+ &v4l2-selection; sel = {
+ .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
+ .target = V4L2_SEL_CROP_DEFAULT,
+ };
+ ret = ioctl(fd,&VIDIOC-G-SELECTION;,&sel);
+ if (ret)
+ exit(-1);
+ sel.target = V4L2_SEL_CROP_ACTIVE;
+ ret = ioctl(fd,&VIDIOC-S-SELECTION;,&sel);
+ if (ret)
+ exit(-1);
+
+</programlisting>
+</example>
+
+<example>
+ <title>Simple downscaling</title>
+ <para>Setting a composing area on output of size of<emphasis> at most
+</emphasis> half of limit placed at a center of a display.</para>
+ <programlisting>
+
+ &v4l2-selection; sel = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_COMPOSE_BOUNDS,
+ };
+ struct v4l2_rect r;
+
+ ret = ioctl(fd,&VIDIOC-G-SELECTION;,&sel);
+ if (ret)
+ exit(-1);
+ /* setting smaller compose rectangle */
+ r.width = sel.r.width / 2;
+ r.height = sel.r.height / 2;
+ r.left = sel.r.width / 4;
+ r.top = sel.r.height / 4;
+ sel.r = r;
+ sel.target = V4L2_SEL_COMPOSE_ACTIVE;
+ sel.flags = V4L2_SEL_SIZE_LE;
+ ret = ioctl(fd,&VIDIOC-S-SELECTION;,&sel);
+ if (ret)
+ exit(-1);
+
+</programlisting>
+</example>
+
+<example>
+ <title>Querying for scaling factors</title>
+ <para>A video output device is assumed; change<constant>
+V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> for other devices</para>
+ <programlisting>
+
+ &v4l2-selection; compose = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_COMPOSE_ACTIVE,
+ };
+ &v4l2-selection; crop = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_CROP_ACTIVE,
+ };
+ double hscale, vscale;
+
+ ret = ioctl(fd,&VIDIOC-G-SELECTION;,&compose);
+ if (ret)
+ exit(-1);
+ ret = ioctl(fd,&VIDIOC-G-SELECTION;,&crop);
+ if (ret)
+ exit(-1);
+
+ /* computing scaling factors */
+ hscale = (double)compose.r.width / crop.r.width;
+ vscale = (double)compose.r.height / crop.r.height;
+
+ </programlisting>
+</example>
+
+</section>
+
+</section>
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index 40132c2..7f1b710 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -500,6 +500,7 @@ and discussions on the V4L mailing list.</revremark>
&sub-g-output;
&sub-g-parm;
&sub-g-priority;
+&sub-g-selection;
&sub-g-sliced-vbi-cap;
&sub-g-std;
&sub-g-tuner;
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
new file mode 100644
index 0000000..e0ef3e7
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
@@ -0,0 +1,303 @@
+<refentry id="vidioc-g-selection">
+
+<refmeta>
+<refentrytitle>ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION</refentrytitle>
+&manvol;
+</refmeta>
+
+<refnamediv>
+<refname>VIDIOC_G_SELECTION</refname>
+<refname>VIDIOC_S_SELECTION</refname>
+<refpurpose>Get or set one of the selection rectangles</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function>ioctl</function></funcdef>
+ <paramdef>int<parameter>fd</parameter></paramdef>
+ <paramdef>int<parameter>request</parameter></paramdef>
+ <paramdef>struct v4l2_selection *<parameter>argp</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Arguments</title>
+
+<variablelist>
+<varlistentry>
+ <term><parameter>fd</parameter></term>
+ <listitem>
+ <para>&fd;</para>
+ </listitem>
+</varlistentry>
+<varlistentry>
+ <term><parameter>request</parameter></term>
+ <listitem>
+ <para>VIDIOC_G_SELECTION, VIDIOC_S_SELECTION</para>
+ </listitem>
+</varlistentry>
+<varlistentry>
+ <term><parameter>argp</parameter></term>
+ <listitem>
+ <para></para>
+ </listitem>
+</varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1>
+<title>Description</title>
+
+<note>
+<title>Experimental</title>
+<para>This is an<link linkend="experimental"> experimental</link>
+ interface and may change in the future.</para>
+</note>
+
+<para>The ioctls are used to query and configure selection rectangles.</para>
+
+<para> To query the cropping (composing) rectangle set<structfield>
+&v4l2-selection;::type</structfield> to the respective buffer type. Do not
+use multiplanar buffers. Use<constant> V4L2_BUF_TYPE_VIDEO_CAPTURE
+</constant> instead of<constant> V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE
+</constant>. Use<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
+<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is
+setting<structfield> &v4l2-selection;::target</structfield> to value
+<constant> V4L2_SEL_CROP_ACTIVE</constant> (<constant> V4L2_SEL_COMPOSE_ACTIVE
+</constant>). Please refer to table<xref linkend="v4l2-sel-target" /> or
+<xref linkend="selection-api" /> for additional targets. Fields<structfield>
+&v4l2-selection;::flags</structfield> and<structfield>
+&v4l2-selection;::reserved</structfield> are ignored and they must be filled
+with zeros. The driver fills the rest of the structure or returns&EINVAL; if
+incorrect buffer type or target was used. If cropping (composing) is not
+supported then the active rectangle is not mutable and it is always equal to
+the bounds rectangle. Finally, structure<structfield> &v4l2-selection;::r
+</structfield> is filled with the current cropping (composing) coordinates. The
+coordinates are expressed in driver-dependent units. The only exception are
+rectangles for images in raw formats, whose coordinates are always expressed in
+pixels.</para>
+
+<para> To change the cropping (composing) rectangle set<structfield>
+&v4l2-selection;::type</structfield> to the respective buffer type. Do not
+use multiplanar buffers. Use<constant> V4L2_BUF_TYPE_VIDEO_CAPTURE
+</constant> instead of<constant> V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE
+</constant>. Use<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
+<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is
+setting<structfield> &v4l2-selection;::target</structfield> to value
+<constant> V4L2_SEL_CROP_ACTIVE</constant> (<constant> V4L2_SEL_COMPOSE_ACTIVE
+</constant>). Please refer to table<xref linkend="v4l2-sel-target" /> or<xref
+linkend="selection-api" /> for additional targets. Set desired active area
+into the field<structfield> &v4l2-selection;::r</structfield>. Field
+<structfield> &v4l2-selection;::reserved</structfield> is ignored and must be
+filled with zeros. The driver may adjust the rectangle coordinates. An
+application may introduce constraints to control rounding behaviour. Set the
+field<structfield> &v4l2-selection;::flags</structfield> to one of values:
+
+<itemizedlist>
+<listitem>
+<para><constant>0</constant> - The driver can adjust the rectangle size freely
+and shall choose a crop/compose rectangle as close as possible to the requested
+one.</para>
+</listitem>
+<listitem>
+<para><constant>V4L2_SEL_SIZE_GE</constant> - The driver is not allowed to
+shrink the rectangle. The original rectangle must lay inside the adjusted
+one.</para>
+</listitem>
+<listitem>
+<para><constant>V4L2_SEL_SIZE_LE</constant> - The driver is not allowed to
+enlarge the rectangle. The adjusted rectangle must lay inside the original
+one.</para>
+</listitem>
+<listitem>
+<para><constant>V4L2_SEL_SIZE_GE | V4L2_SEL_SIZE_LE</constant> - The driver
+must choose the size exactly the same as in the requested rectangle.</para>
+</listitem>
+</itemizedlist>
+
+Please refer to<xref linkend="sel-const-adjust" />.
+
+</para>
+
+<para> The driver may have to adjusts the requested dimensions against hardware
+limits and other parts as the pipeline, i.e. the bounds given by the
+capture/output window or TV display. The closest possible values of horizontal
+and vertical offset and sizes are chosen according to following priority:
+
+<orderedlist>
+<listitem>
+<para>Satisfy constraints from<structfield>&v4l2-selection;::flags</structfield>.</para>
+</listitem>
+<listitem>
+<para>Adjust width, height, left, and top to hardware limits and alignments.</para>
+</listitem>
+<listitem>
+<para>Keep center of adjusted rectangle as close as possible to the original one.</para>
+</listitem>
+<listitem>
+<para>Keep width and height as close as possible to original ones.</para>
+</listitem>
+<listitem>
+<para>Keep horizontal and vertical offset as close as possible to original ones.</para>
+</listitem>
+</orderedlist>
+
+On success the field<structfield> &v4l2-selection;::r</structfield> contains
+the adjusted rectangle. When the parameters are unsuitable the application may
+modify the cropping (composing) or image parameters and repeat the cycle until
+satisfactory parameters have been negotiated. If constraints flags have to be
+violated at then ERANGE is returned. The error indicates that<emphasis> there
+exist no rectangle</emphasis> that satisfies the constraints.</para>
+
+</refsect1>
+
+<refsect1>
+<table frame="none" pgwide="1" id="v4l2-sel-target">
+<title>Selection targets.</title>
+<tgroup cols="3">
+ &cs-def;
+ <tbody valign="top">
+ <row>
+<entry><constant>V4L2_SEL_CROP_ACTIVE</constant></entry>
+<entry>0</entry>
+<entry>area that is currently cropped by hardware</entry>
+ </row>
+ <row>
+<entry><constant>V4L2_SEL_CROP_DEFAULT</constant></entry>
+<entry>1</entry>
+<entry>suggested cropping rectangle that covers the "whole picture"</entry>
+ </row>
+ <row>
+<entry><constant>V4L2_SEL_CROP_BOUNDS</constant></entry>
+<entry>2</entry>
+<entry>limits for the cropping rectangle</entry>
+ </row>
+ <row>
+<entry><constant>V4L2_SEL_COMPOSE_ACTIVE</constant></entry>
+<entry>256</entry>
+<entry>area to which data are composed by hardware</entry>
+ </row>
+ <row>
+<entry><constant>V4L2_SEL_COMPOSE_DEFAULT</constant></entry>
+<entry>257</entry>
+<entry>suggested composing rectangle that covers the "whole picture"</entry>
+ </row>
+ <row>
+<entry><constant>V4L2_SEL_COMPOSE_BOUNDS</constant></entry>
+<entry>258</entry>
+<entry>limits for the composing rectangle</entry>
+ </row>
+ <row>
+<entry><constant>V4L2_SEL_COMPOSE_PADDED</constant></entry>
+<entry>259</entry>
+<entry>the active area and all padding pixels that are inserted or modified by the hardware</entry>
+ </row>
+ </tbody>
+</tgroup>
+</table>
+</refsect1>
+
+<refsect1>
+<table frame="none" pgwide="1" id="v4l2-sel-flags">
+<title>Selection constraint flags</title>
+<tgroup cols="3">
+ &cs-def;
+ <tbody valign="top">
+ <row>
+<entry><constant>V4L2_SEL_SIZE_GE</constant></entry>
+<entry>0x00000001</entry>
+<entry>indicate that adjusted rectangle must contain a rectangle from<structfield>&v4l2-selection;::r</structfield></entry>
+ </row>
+ <row>
+<entry><constant>V4L2_SEL_SIZE_LE</constant></entry>
+<entry>0x00000002</entry>
+<entry>indicate that adjusted rectangle must be inside a rectangle from<structfield>&v4l2-selection;::r</structfield></entry>
+ </row>
+ </tbody>
+</tgroup>
+</table>
+</refsect1>
+
+<section>
+<figure id="sel-const-adjust">
+ <title>Size adjustments with constraint flags.</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="constraints.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <phrase>Behaviour of rectangle adjustment for different constraint
+ flags.</phrase>
+ </textobject>
+ </mediaobject>
+</figure>
+</section>
+
+<refsect1>
+<table pgwide="1" frame="none" id="v4l2-selection">
+<title>struct<structname>v4l2_selection</structname></title>
+<tgroup cols="3">
+ &cs-str;
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>type</structfield></entry>
+ <entry>Type of the buffer (from&v4l2-buf-type;)</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>target</structfield></entry>
+<entry>used to select between<link linkend="v4l2-sel-target"> cropping and composing rectangles</link></entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>flags</structfield></entry>
+<entry>control over coordinates adjustments, refer to<link linkend="v4l2-sel-flags">selection flags</link></entry>
+ </row>
+ <row>
+ <entry>&v4l2-rect;</entry>
+ <entry><structfield>r</structfield></entry>
+ <entry>selection rectangle</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>reserved[9]</structfield></entry>
+ <entry>Reserved fields for future use</entry>
+ </row>
+ </tbody>
+</tgroup>
+</table>
+</refsect1>
+
+<refsect1>
+&return-value;
+<variablelist>
+<varlistentry>
+ <term><errorcode>EINVAL</errorcode></term>
+ <listitem>
+ <para>The buffer<structfield> &v4l2-selection;::type</structfield>
+or<structfield> &v4l2-selection;::target</structfield> is not supported, or
+the<structfield> &v4l2-selection;::flags</structfield> are invalid.</para>
+ </listitem>
+</varlistentry>
+<varlistentry>
+ <term><errorcode>ERANGE</errorcode></term>
+ <listitem>
+ <para>it is not possible to adjust a rectangle<structfield>
+&v4l2-selection;::r</structfield> that satisfies all contraints from
+<structfield> &v4l2-selection;::flags</structfield>.</para>
+ </listitem>
+</varlistentry>
+<varlistentry>
+ <term><errorcode>EBUSY</errorcode></term>
+ <listitem>
+ <para>it is not possible to apply change of selection rectangle at the moment.
+Usually because streaming is in progress.</para>
+ </listitem>
+</varlistentry>
+</variablelist>
+</refsect1>
+
+</refentry>
