| <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> |
| |
| <section> |
| <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> |
| </section> |
| |
| <section> |
| <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> |
| </section> |
| |
| <table pgwide="1" frame="none" id="v4l2-subdev-selection-targets"> |
| <title>V4L2 subdev selection targets</title> |
| <tgroup cols="3"> |
| &cs-def; |
| <tbody valign="top"> |
| <row> |
| <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL</constant></entry> |
| <entry>0x0000</entry> |
| <entry>Actual crop. Defines the cropping |
| performed by the processing step.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS</constant></entry> |
| <entry>0x0002</entry> |
| <entry>Bounds of the crop rectangle.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL</constant></entry> |
| <entry>0x0100</entry> |
| <entry>Actual compose rectangle. Used to configure scaling |
| on sink pads and composition on source pads.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS</constant></entry> |
| <entry>0x0102</entry> |
| <entry>Bounds of the compose rectangle.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="v4l2-subdev-selection-flags"> |
| <title>V4L2 subdev selection flags</title> |
| <tgroup cols="3"> |
| &cs-def; |
| <tbody valign="top"> |
| <row> |
| <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant></entry> |
| <entry>(1 << 0)</entry> <entry>Suggest the driver it |
| should choose greater or equal rectangle (in size) than |
| was requested. Albeit the driver may choose a lesser size, |
| it will only do so due to hardware limitations. Without |
| this flag (and |
| <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant>) the |
| behaviour is to choose the closest possible |
| rectangle.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant></entry> |
| <entry>(1 << 1)</entry> <entry>Suggest the driver it |
| should choose lesser or equal rectangle (in size) than was |
| requested. Albeit the driver may choose a greater size, it |
| will only do so due to hardware limitations.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant></entry> |
| <entry>(1 << 2)</entry> |
| <entry>The configuration should not be propagated to any |
| further processing steps. If this flag is not given, the |
| configuration is propagated inside the subdevice to all |
| further processing steps.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <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-subdev-selection-targets">.</xref>.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>flags</structfield></entry> |
| <entry>Flags. See |
| <xref linkend="v4l2-subdev-selection-flags">.</xref></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> |
| |
| </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> |
