diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml')
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml | 165 |
1 files changed, 165 insertions, 0 deletions
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 00000000..1ba9e999 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -0,0 +1,165 @@ +<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> |