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

   1 <refentry id="vidioc-g-fmt">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT,
   4 VIDIOC_TRY_FMT</refentrytitle>
   5     &manvol;
   6   </refmeta>
   7
   8   <refnamediv>
   9     <refname>VIDIOC_G_FMT</refname>
  10     <refname>VIDIOC_S_FMT</refname>
  11     <refname>VIDIOC_TRY_FMT</refname>
  12     <refpurpose>Get or set the data format, try a format</refpurpose>
  13   </refnamediv>
  14
  15   <refsynopsisdiv>
  16     <funcsynopsis>
  17       <funcprototype>
  18         <funcdef>int <function>ioctl</function></funcdef>
  19         <paramdef>int <parameter>fd</parameter></paramdef>
  20         <paramdef>int <parameter>request</parameter></paramdef>
  21         <paramdef>struct v4l2_format
  22 *<parameter>argp</parameter></paramdef>
  23       </funcprototype>
  24     </funcsynopsis>
  25   </refsynopsisdiv>
  26
  27   <refsect1>
  28     <title>Arguments</title>
  29
  30     <variablelist>
  31       <varlistentry>
  32         <term><parameter>fd</parameter></term>
  33         <listitem>
  34           <para>&fd;</para>
  35         </listitem>
  36       </varlistentry>
  37       <varlistentry>
  38         <term><parameter>request</parameter></term>
  39         <listitem>
  40           <para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para>
  41         </listitem>
  42       </varlistentry>
  43       <varlistentry>
  44         <term><parameter>argp</parameter></term>
  45         <listitem>
  46           <para></para>
  47         </listitem>
  48       </varlistentry>
  49     </variablelist>
  50   </refsect1>
  51
  52   <refsect1>
  53     <title>Description</title>
  54
  55     <para>These ioctls are used to negotiate the format of data
  56 (typically image format) exchanged between driver and
  57 application.</para>
  58
  59     <para>To query the current parameters applications set the
  60 <structfield>type</structfield> field of a struct
  61 <structname>v4l2_format</structname> to the respective buffer (stream)
  62 type. For example video capture devices use
  63 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
  64 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application
  65 calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
  66 this structure the driver fills the respective member of the
  67 <structfield>fmt</structfield> union. In case of video capture devices
  68 that is either the &v4l2-pix-format; <structfield>pix</structfield> or
  69 the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member.
  70 When the requested buffer type is not supported drivers return an
  71 &EINVAL;.</para>
  72
  73     <para>To change the current format parameters applications
  74 initialize the <structfield>type</structfield> field and all
  75 fields of the respective <structfield>fmt</structfield>
  76 union member. For details see the documentation of the various devices
  77 types in <xref linkend="devices" />. Good practice is to query the
  78 current parameters first, and to
  79 modify only those parameters not suitable for the application. When
  80 the application calls the <constant>VIDIOC_S_FMT</constant> ioctl
  81 with a pointer to a <structname>v4l2_format</structname> structure
  82 the driver checks
  83 and adjusts the parameters against hardware abilities. Drivers
  84 should not return an error code unless the input is ambiguous, this is
  85 a mechanism to fathom device capabilities and to approach parameters
  86 acceptable for both the application and driver. On success the driver
  87 may program the hardware, allocate resources and generally prepare for
  88 data exchange.
  89 Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the
  90 current format parameters as <constant>VIDIOC_G_FMT</constant> does.
  91 Very simple, inflexible devices may even ignore all input and always
  92 return the default parameters. However all V4L2 devices exchanging
  93 data with the application must implement the
  94 <constant>VIDIOC_G_FMT</constant> and
  95 <constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer
  96 type is not supported drivers return an &EINVAL; on a
  97 <constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in
  98 progress or the resource is not available for other reasons drivers
  99 return the &EBUSY;.</para>
 100
 101     <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent
 102 to <constant>VIDIOC_S_FMT</constant> with one exception: it does not
 103 change driver state. It can also be called at any time, never
 104 returning <errorcode>EBUSY</errorcode>. This function is provided to
 105 negotiate parameters, to learn about hardware limitations, without
 106 disabling I/O or possibly time consuming hardware preparations.
 107 Although strongly recommended drivers are not required to implement
 108 this ioctl.</para>
 109
 110     <table pgwide="1" frame="none" id="v4l2-format">
 111       <title>struct <structname>v4l2_format</structname></title>
 112       <tgroup cols="4">
 113         <colspec colname="c1" />
 114         <colspec colname="c2" />
 115         <colspec colname="c3" />
 116         <colspec colname="c4" />
 117         <tbody valign="top">
 118           <row>
 119             <entry>&v4l2-buf-type;</entry>
 120             <entry><structfield>type</structfield></entry>
 121             <entry></entry>
 122             <entry>Type of the data stream, see <xref
 123                 linkend="v4l2-buf-type" />.</entry>
 124           </row>
 125           <row>
 126             <entry>union</entry>
 127             <entry><structfield>fmt</structfield></entry>
 128           </row>
 129           <row>
 130             <entry></entry>
 131             <entry>&v4l2-pix-format;</entry>
 132             <entry><structfield>pix</structfield></entry>
 133             <entry>Definition of an image format, see <xref
 134                 linkend="pixfmt" />, used by video capture and output
 135 devices.</entry>
 136           </row>
 137           <row>
 138             <entry></entry>
 139             <entry>&v4l2-pix-format-mplane;</entry>
 140             <entry><structfield>pix_mp</structfield></entry>
 141             <entry>Definition of an image format, see <xref
 142                 linkend="pixfmt" />, used by video capture and output
 143 devices that support the <link linkend="planar-apis">multi-planar
 144 version of the API</link>.</entry>
 145           </row>
 146           <row>
 147             <entry></entry>
 148             <entry>&v4l2-window;</entry>
 149             <entry><structfield>win</structfield></entry>
 150             <entry>Definition of an overlaid image, see <xref
 151             linkend="overlay" />, used by video overlay devices.</entry>
 152           </row>
 153           <row>
 154             <entry></entry>
 155             <entry>&v4l2-vbi-format;</entry>
 156             <entry><structfield>vbi</structfield></entry>
 157             <entry>Raw VBI capture or output parameters. This is
 158 discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI
 159 capture and output devices.</entry>
 160           </row>
 161           <row>
 162             <entry></entry>
 163             <entry>&v4l2-sliced-vbi-format;</entry>
 164             <entry><structfield>sliced</structfield></entry>
 165             <entry>Sliced VBI capture or output parameters. See
 166 <xref linkend="sliced" /> for details. Used by sliced VBI
 167 capture and output devices.</entry>
 168           </row>
 169           <row>
 170             <entry></entry>
 171             <entry>__u8</entry>
 172             <entry><structfield>raw_data</structfield>[200]</entry>
 173             <entry>Place holder for future extensions and custom
 174 (driver defined) formats with <structfield>type</structfield>
 175 <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry>
 176           </row>
 177         </tbody>
 178       </tgroup>
 179     </table>
 180   </refsect1>
 181
 182   <refsect1>
 183     &return-value;
 184
 185     <variablelist>
 186       <varlistentry>
 187         <term><errorcode>EINVAL</errorcode></term>
 188         <listitem>
 189           <para>The &v4l2-format; <structfield>type</structfield>
 190 field is invalid, the requested buffer type not supported, or the
 191 format is not supported with this buffer type.</para>
 192         </listitem>
 193       </varlistentry>
 194     </variablelist>
 195   </refsect1>
 196 </refentry>