| <refentry id="vidioc-subdev-g-selection"> | |
| <refmeta> | |
| <refentrytitle>ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</refentrytitle> | |
| &manvol; | |
| </refmeta> | |
| <refnamediv> | |
| <refname>VIDIOC_SUBDEV_G_SELECTION</refname> | |
| <refname>VIDIOC_SUBDEV_S_SELECTION</refname> | |
| <refpurpose>Get or set selection rectangles on a subdev pad</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_subdev_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_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_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 selections are used to configure various image | |
| processing functionality performed by the subdevs which affect the | |
| image size. This currently includes cropping, scaling and | |
| composition.</para> | |
| <para>The selection API replaces <link | |
| linkend="vidioc-subdev-g-crop">the old subdev crop API</link>. All | |
| the function of the crop API, and more, are supported by the | |
| selections API.</para> | |
| <para>See <xref linkend="subdev"></xref> for | |
| more information on how each selection target affects the image | |
| processing pipeline inside the subdevice.</para> | |
| <refsect2> | |
| <title>Types of selection targets</title> | |
| <para>There are two types of selection targets: actual and bounds. The | |
| actual targets are the targets which configure the hardware. The BOUNDS | |
| target will return a rectangle that contain all possible actual | |
| rectangles.</para> | |
| </refsect2> | |
| <refsect2> | |
| <title>Discovering supported features</title> | |
| <para>To discover which targets are supported, the user can | |
| perform <constant>VIDIOC_SUBDEV_G_SELECTION</constant> on them. | |
| Any unsupported target will return | |
| <constant>EINVAL</constant>.</para> | |
| <para>Selection targets and flags are documented in <xref | |
| linkend="v4l2-selections-common"/>.</para> | |
| <table pgwide="1" frame="none" id="v4l2-subdev-selection"> | |
| <title>struct <structname>v4l2_subdev_selection</structname></title> | |
| <tgroup cols="3"> | |
| &cs-str; | |
| <tbody valign="top"> | |
| <row> | |
| <entry>__u32</entry> | |
| <entry><structfield>which</structfield></entry> | |
| <entry>Active or try selection, from | |
| &v4l2-subdev-format-whence;.</entry> | |
| </row> | |
| <row> | |
| <entry>__u32</entry> | |
| <entry><structfield>pad</structfield></entry> | |
| <entry>Pad number as reported by the media framework.</entry> | |
| </row> | |
| <row> | |
| <entry>__u32</entry> | |
| <entry><structfield>target</structfield></entry> | |
| <entry>Target selection rectangle. See | |
| <xref linkend="v4l2-selections-common" />.</entry> | |
| </row> | |
| <row> | |
| <entry>__u32</entry> | |
| <entry><structfield>flags</structfield></entry> | |
| <entry>Flags. See | |
| <xref linkend="v4l2-selection-flags" />.</entry> | |
| </row> | |
| <row> | |
| <entry>&v4l2-rect;</entry> | |
| <entry><structfield>rect</structfield></entry> | |
| <entry>Selection rectangle, in pixels.</entry> | |
| </row> | |
| <row> | |
| <entry>__u32</entry> | |
| <entry><structfield>reserved</structfield>[8]</entry> | |
| <entry>Reserved for future extensions. Applications and drivers must | |
| set the array to zero.</entry> | |
| </row> | |
| </tbody> | |
| </tgroup> | |
| </table> | |
| </refsect2> | |
| </refsect1> | |
| <refsect1> | |
| &return-value; | |
| <variablelist> | |
| <varlistentry> | |
| <term><errorcode>EBUSY</errorcode></term> | |
| <listitem> | |
| <para>The selection rectangle can't be changed because the | |
| pad is currently busy. This can be caused, for instance, by | |
| an active video stream on the pad. The ioctl must not be | |
| retried without performing another action to fix the problem | |
| first. Only returned by | |
| <constant>VIDIOC_SUBDEV_S_SELECTION</constant></para> | |
| </listitem> | |
| </varlistentry> | |
| <varlistentry> | |
| <term><errorcode>EINVAL</errorcode></term> | |
| <listitem> | |
| <para>The &v4l2-subdev-selection; | |
| <structfield>pad</structfield> references a non-existing | |
| pad, the <structfield>which</structfield> field references a | |
| non-existing format, or the selection target is not | |
| supported on the given subdev pad.</para> | |
| </listitem> | |
| </varlistentry> | |
| </variablelist> | |
| </refsect1> | |
| </refentry> |