Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml

   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     <para>The selections are used to configure various image
  53     processing functionality performed by the subdevs which affect the
  54     image size. This currently includes cropping, scaling and
  55     composition.</para>
  56
  57     <para>The selection API replaces <link
  58     linkend="vidioc-subdev-g-crop">the old subdev crop API</link>. All
  59     the function of the crop API, and more, are supported by the
  60     selections API.</para>
  61
  62     <para>See <xref linkend="subdev"></xref> for
  63     more information on how each selection target affects the image
  64     processing pipeline inside the subdevice.</para>
  65
  66     <refsect2>
  67       <title>Types of selection targets</title>
  68
  69       <para>There are two types of selection targets: actual and bounds. The
  70       actual targets are the targets which configure the hardware. The BOUNDS
  71       target will return a rectangle that contain all possible actual
  72       rectangles.</para>
  73     </refsect2>
  74
  75     <refsect2>
  76       <title>Discovering supported features</title>
  77
  78       <para>To discover which targets are supported, the user can
  79       perform <constant>VIDIOC_SUBDEV_G_SELECTION</constant> on them.
  80       Any unsupported target will return
  81       <constant>EINVAL</constant>.</para>
  82
  83     <para>Selection targets and flags are documented in <xref
  84     linkend="v4l2-selections-common"/>.</para>
  85
  86     <table pgwide="1" frame="none" id="v4l2-subdev-selection">
  87       <title>struct <structname>v4l2_subdev_selection</structname></title>
  88       <tgroup cols="3">
  89         &cs-str;
  90         <tbody valign="top">
  91           <row>
  92             <entry>__u32</entry>
  93             <entry><structfield>which</structfield></entry>
  94             <entry>Active or try selection, from
  95             &v4l2-subdev-format-whence;.</entry>
  96           </row>
  97           <row>
  98             <entry>__u32</entry>
  99             <entry><structfield>pad</structfield></entry>
 100             <entry>Pad number as reported by the media framework.</entry>
 101           </row>
 102           <row>
 103             <entry>__u32</entry>
 104             <entry><structfield>target</structfield></entry>
 105             <entry>Target selection rectangle. See
 106             <xref linkend="v4l2-selections-common" />.</entry>
 107           </row>
 108           <row>
 109             <entry>__u32</entry>
 110             <entry><structfield>flags</structfield></entry>
 111             <entry>Flags. See
 112             <xref linkend="v4l2-selection-flags" />.</entry>
 113           </row>
 114           <row>
 115             <entry>&v4l2-rect;</entry>
 116             <entry><structfield>r</structfield></entry>
 117             <entry>Selection rectangle, in pixels.</entry>
 118           </row>
 119           <row>
 120             <entry>__u32</entry>
 121             <entry><structfield>reserved</structfield>[8]</entry>
 122             <entry>Reserved for future extensions. Applications and drivers must
 123             set the array to zero.</entry>
 124           </row>
 125         </tbody>
 126       </tgroup>
 127     </table>
 128     </refsect2>
 129
 130   </refsect1>
 131
 132   <refsect1>
 133     &return-value;
 134
 135     <variablelist>
 136       <varlistentry>
 137         <term><errorcode>EBUSY</errorcode></term>
 138         <listitem>
 139           <para>The selection rectangle can't be changed because the
 140           pad is currently busy. This can be caused, for instance, by
 141           an active video stream on the pad. The ioctl must not be
 142           retried without performing another action to fix the problem
 143           first. Only returned by
 144           <constant>VIDIOC_SUBDEV_S_SELECTION</constant></para>
 145         </listitem>
 146       </varlistentry>
 147       <varlistentry>
 148         <term><errorcode>EINVAL</errorcode></term>
 149         <listitem>
 150           <para>The &v4l2-subdev-selection;
 151           <structfield>pad</structfield> references a non-existing
 152           pad, the <structfield>which</structfield> field references a
 153           non-existing format, or the selection target is not
 154           supported on the given subdev pad.</para>
 155         </listitem>
 156       </varlistentry>
 157     </variablelist>
 158   </refsect1>
 159 </refentry>