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