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