Documentation/DocBook/media/v4l/vidioc-g-parm.xml

   1 <refentry id="vidioc-g-parm">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_G_PARM</refname>
   9     <refname>VIDIOC_S_PARM</refname>
  10     <refpurpose>Get or set streaming parameters</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>v4l2_streamparm *<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_G_PARM, VIDIOC_S_PARM</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 current video standard determines a nominal number of
  53 frames per second. If less than this number of frames is to be
  54 captured or output, applications can request frame skipping or
  55 duplicating on the driver side. This is especially useful when using
  56 the <function>read()</function> or <function>write()</function>, which
  57 are not augmented by timestamps or sequence counters, and to avoid
  58 unnecessary data copying.</para>
  59
  60     <para>Further these ioctls can be used to determine the number of
  61 buffers used internally by a driver in read/write mode. For
  62 implications see the section discussing the &func-read;
  63 function.</para>
  64
  65     <para>To get and set the streaming parameters applications call
  66 the <constant>VIDIOC_G_PARM</constant> and
  67 <constant>VIDIOC_S_PARM</constant> ioctl, respectively. They take a
  68 pointer to a struct <structname>v4l2_streamparm</structname> which
  69 contains a union holding separate parameters for input and output
  70 devices.</para>
  71
  72     <table pgwide="1" frame="none" id="v4l2-streamparm">
  73       <title>struct <structname>v4l2_streamparm</structname></title>
  74       <tgroup cols="4">
  75         &cs-ustr;
  76         <tbody valign="top">
  77           <row>
  78             <entry>&v4l2-buf-type;</entry>
  79             <entry><structfield>type</structfield></entry>
  80             <entry></entry>
  81             <entry>The buffer (stream) type, same as &v4l2-format;
  82 <structfield>type</structfield>, set by the application.</entry>
  83           </row>
  84           <row>
  85             <entry>union</entry>
  86             <entry><structfield>parm</structfield></entry>
  87             <entry></entry>
  88             <entry></entry>
  89           </row>
  90           <row>
  91             <entry></entry>
  92             <entry>&v4l2-captureparm;</entry>
  93             <entry><structfield>capture</structfield></entry>
  94             <entry>Parameters for capture devices, used when
  95 <structfield>type</structfield> is
  96 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.</entry>
  97           </row>
  98           <row>
  99             <entry></entry>
 100             <entry>&v4l2-outputparm;</entry>
 101             <entry><structfield>output</structfield></entry>
 102             <entry>Parameters for output devices, used when
 103 <structfield>type</structfield> is
 104 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>.</entry>
 105           </row>
 106           <row>
 107             <entry></entry>
 108             <entry>__u8</entry>
 109             <entry><structfield>raw_data</structfield>[200]</entry>
 110             <entry>A place holder for future extensions and custom
 111 (driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and
 112 higher.</entry>
 113           </row>
 114         </tbody>
 115       </tgroup>
 116     </table>
 117
 118     <table pgwide="1" frame="none" id="v4l2-captureparm">
 119       <title>struct <structname>v4l2_captureparm</structname></title>
 120       <tgroup cols="3">
 121         &cs-str;
 122         <tbody valign="top">
 123           <row>
 124             <entry>__u32</entry>
 125             <entry><structfield>capability</structfield></entry>
 126             <entry>See <xref linkend="parm-caps" />.</entry>
 127           </row>
 128           <row>
 129             <entry>__u32</entry>
 130             <entry><structfield>capturemode</structfield></entry>
 131             <entry>Set by drivers and applications, see <xref linkend="parm-flags" />.</entry>
 132           </row>
 133           <row>
 134             <entry>&v4l2-fract;</entry>
 135             <entry><structfield>timeperframe</structfield></entry>
 136             <entry><para>This is is the desired period between
 137 successive frames captured by the driver, in seconds. The
 138 field is intended to skip frames on the driver side, saving I/O
 139 bandwidth.</para><para>Applications store here the desired frame
 140 period, drivers return the actual frame period, which must be greater
 141 or equal to the nominal frame period determined by the current video
 142 standard (&v4l2-standard; <structfield>frameperiod</structfield>
 143 field). Changing the video standard (also implicitly by switching the
 144 video input) may reset this parameter to the nominal frame period. To
 145 reset manually applications can just set this field to
 146 zero.</para><para>Drivers support this function only when they set the
 147 <constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the
 148 <structfield>capability</structfield> field.</para></entry>
 149           </row>
 150           <row>
 151             <entry>__u32</entry>
 152             <entry><structfield>extendedmode</structfield></entry>
 153             <entry>Custom (driver specific) streaming parameters. When
 154 unused, applications and drivers must set this field to zero.
 155 Applications using this field should check the driver name and
 156 version, see <xref linkend="querycap" />.</entry>
 157           </row>
 158           <row>
 159             <entry>__u32</entry>
 160             <entry><structfield>readbuffers</structfield></entry>
 161             <entry>Applications set this field to the desired number
 162 of buffers used internally by the driver in &func-read; mode. Drivers
 163 return the actual number of buffers. When an application requests zero
 164 buffers, drivers should just return the current setting rather than
 165 the minimum or an error code. For details see <xref
 166                 linkend="rw" />.</entry>
 167           </row>
 168           <row>
 169             <entry>__u32</entry>
 170             <entry><structfield>reserved</structfield>[4]</entry>
 171             <entry>Reserved for future extensions. Drivers and
 172 applications must set the array to zero.</entry>
 173           </row>
 174         </tbody>
 175       </tgroup>
 176     </table>
 177
 178     <table pgwide="1" frame="none" id="v4l2-outputparm">
 179       <title>struct <structname>v4l2_outputparm</structname></title>
 180       <tgroup cols="3">
 181         &cs-str;
 182         <tbody valign="top">
 183           <row>
 184             <entry>__u32</entry>
 185             <entry><structfield>capability</structfield></entry>
 186             <entry>See <xref linkend="parm-caps" />.</entry>
 187           </row>
 188           <row>
 189             <entry>__u32</entry>
 190             <entry><structfield>outputmode</structfield></entry>
 191             <entry>Set by drivers and applications, see <xref
 192             linkend="parm-flags" />.</entry>
 193           </row>
 194           <row>
 195             <entry>&v4l2-fract;</entry>
 196             <entry><structfield>timeperframe</structfield></entry>
 197             <entry>This is is the desired period between
 198 successive frames output by the driver, in seconds.</entry>
 199           </row>
 200           <row>
 201             <entry spanname="hspan"><para>The field is intended to
 202 repeat frames on the driver side in &func-write; mode (in streaming
 203 mode timestamps can be used to throttle the output), saving I/O
 204 bandwidth.</para><para>Applications store here the desired frame
 205 period, drivers return the actual frame period, which must be greater
 206 or equal to the nominal frame period determined by the current video
 207 standard (&v4l2-standard; <structfield>frameperiod</structfield>
 208 field). Changing the video standard (also implicitly by switching the
 209 video output) may reset this parameter to the nominal frame period. To
 210 reset manually applications can just set this field to
 211 zero.</para><para>Drivers support this function only when they set the
 212 <constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the
 213 <structfield>capability</structfield> field.</para></entry>
 214           </row>
 215           <row>
 216             <entry>__u32</entry>
 217             <entry><structfield>extendedmode</structfield></entry>
 218             <entry>Custom (driver specific) streaming parameters. When
 219 unused, applications and drivers must set this field to zero.
 220 Applications using this field should check the driver name and
 221 version, see <xref linkend="querycap" />.</entry>
 222           </row>
 223           <row>
 224             <entry>__u32</entry>
 225             <entry><structfield>writebuffers</structfield></entry>
 226             <entry>Applications set this field to the desired number
 227 of buffers used internally by the driver in
 228 <function>write()</function> mode. Drivers return the actual number of
 229 buffers. When an application requests zero buffers, drivers should
 230 just return the current setting rather than the minimum or an error
 231 code. For details see <xref linkend="rw" />.</entry>
 232           </row>
 233           <row>
 234             <entry>__u32</entry>
 235             <entry><structfield>reserved</structfield>[4]</entry>
 236             <entry>Reserved for future extensions. Drivers and
 237 applications must set the array to zero.</entry>
 238           </row>
 239         </tbody>
 240       </tgroup>
 241     </table>
 242
 243     <table pgwide="1" frame="none" id="parm-caps">
 244       <title>Streaming Parameters Capabilites</title>
 245       <tgroup cols="3">
 246         &cs-def;
 247         <tbody valign="top">
 248           <row>
 249             <entry><constant>V4L2_CAP_TIMEPERFRAME</constant></entry>
 250             <entry>0x1000</entry>
 251             <entry>The frame skipping/repeating controlled by the
 252 <structfield>timeperframe</structfield> field is supported.</entry>
 253           </row>
 254         </tbody>
 255       </tgroup>
 256     </table>
 257
 258     <table pgwide="1" frame="none" id="parm-flags">
 259       <title>Capture Parameters Flags</title>
 260       <tgroup cols="3">
 261         &cs-def;
 262         <tbody valign="top">
 263           <row>
 264             <entry><constant>V4L2_MODE_HIGHQUALITY</constant></entry>
 265             <entry>0x0001</entry>
 266             <entry><para>High quality imaging mode. High quality mode
 267 is intended for still imaging applications. The idea is to get the
 268 best possible image quality that the hardware can deliver. It is not
 269 defined how the driver writer may achieve that; it will depend on the
 270 hardware and the ingenuity of the driver writer. High quality mode is
 271 a different mode from the the regular motion video capture modes. In
 272 high quality mode:<itemizedlist>
 273                   <listitem>
 274                     <para>The driver may be able to capture higher
 275 resolutions than for motion capture.</para>
 276                   </listitem>
 277                   <listitem>
 278                     <para>The driver may support fewer pixel formats
 279 than motion capture (eg; true color).</para>
 280                   </listitem>
 281                   <listitem>
 282                     <para>The driver may capture and arithmetically
 283 combine multiple successive fields or frames to remove color edge
 284 artifacts and reduce the noise in the video data.
 285 </para>
 286                   </listitem>
 287                   <listitem>
 288                     <para>The driver may capture images in slices like
 289 a scanner in order to handle larger format images than would otherwise
 290 be possible. </para>
 291                   </listitem>
 292                   <listitem>
 293                     <para>An image capture operation may be
 294 significantly slower than motion capture. </para>
 295                   </listitem>
 296                   <listitem>
 297                     <para>Moving objects in the image might have
 298 excessive motion blur. </para>
 299                   </listitem>
 300                   <listitem>
 301                     <para>Capture might only work through the
 302 <function>read()</function> call.</para>
 303                   </listitem>
 304                 </itemizedlist></para></entry>
 305           </row>
 306         </tbody>
 307       </tgroup>
 308     </table>
 309
 310   </refsect1>
 311
 312   <refsect1>
 313     &return-value;
 314   </refsect1>
 315 </refentry>