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

   1 <refentry id="vidioc-enum-fmt">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_ENUM_FMT</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_ENUM_FMT</refname>
   9     <refpurpose>Enumerate image formats</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcprototype>
  15         <funcdef>int <function>ioctl</function></funcdef>
  16         <paramdef>int <parameter>fd</parameter></paramdef>
  17         <paramdef>int <parameter>request</parameter></paramdef>
  18         <paramdef>struct v4l2_fmtdesc
  19 *<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_ENUM_FMT</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>To enumerate image formats applications initialize the
  53 <structfield>type</structfield> and <structfield>index</structfield>
  54 field of &v4l2-fmtdesc; and call the
  55 <constant>VIDIOC_ENUM_FMT</constant> ioctl with a pointer to this
  56 structure. Drivers fill the rest of the structure or return an
  57 &EINVAL;. All formats are enumerable by beginning at index zero and
  58 incrementing by one until <errorcode>EINVAL</errorcode> is
  59 returned.</para>
  60
  61     <para>Note that after switching input or output the list of enumerated image
  62 formats may be different.</para>
  63
  64     <table pgwide="1" frame="none" id="v4l2-fmtdesc">
  65       <title>struct <structname>v4l2_fmtdesc</structname></title>
  66       <tgroup cols="3">
  67         &cs-str;
  68         <tbody valign="top">
  69           <row>
  70             <entry>__u32</entry>
  71             <entry><structfield>index</structfield></entry>
  72             <entry>Number of the format in the enumeration, set by
  73 the application. This is in no way related to the <structfield>
  74 pixelformat</structfield> field.</entry>
  75           </row>
  76           <row>
  77             <entry>__u32</entry>
  78             <entry><structfield>type</structfield></entry>
  79             <entry>Type of the data stream, set by the application.
  80 Only these types are valid here:
  81 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
  82 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>,
  83 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
  84 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>,
  85 <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
  86 defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
  87 and higher. See <xref linkend="v4l2-buf-type" />.</entry>
  88           </row>
  89           <row>
  90             <entry>__u32</entry>
  91             <entry><structfield>flags</structfield></entry>
  92             <entry>See <xref linkend="fmtdesc-flags" /></entry>
  93           </row>
  94           <row>
  95             <entry>__u8</entry>
  96             <entry><structfield>description</structfield>[32]</entry>
  97             <entry>Description of the format, a NUL-terminated ASCII
  98 string. This information is intended for the user, for example: "YUV
  99 4:2:2".</entry>
 100           </row>
 101           <row>
 102             <entry>__u32</entry>
 103             <entry><structfield>pixelformat</structfield></entry>
 104             <entry>The image format identifier. This is a
 105 four character code as computed by the v4l2_fourcc()
 106 macro:</entry>
 107           </row>
 108           <row>
 109             <entry spanname="hspan"><para><programlisting id="v4l2-fourcc">
 110 #define v4l2_fourcc(a,b,c,d) (((__u32)(a)&lt;&lt;0)|((__u32)(b)&lt;&lt;8)|((__u32)(c)&lt;&lt;16)|((__u32)(d)&lt;&lt;24))
 111 </programlisting></para><para>Several image formats are already
 112 defined by this specification in <xref linkend="pixfmt" />. Note these
 113 codes are not the same as those used in the Windows world.</para></entry>
 114           </row>
 115           <row>
 116             <entry>__u32</entry>
 117             <entry><structfield>reserved</structfield>[4]</entry>
 118             <entry>Reserved for future extensions. Drivers must set
 119 the array to zero.</entry>
 120           </row>
 121         </tbody>
 122       </tgroup>
 123     </table>
 124
 125     <table pgwide="1" frame="none" id="fmtdesc-flags">
 126       <title>Image Format Description Flags</title>
 127       <tgroup cols="3">
 128         &cs-def;
 129         <tbody valign="top">
 130           <row>
 131             <entry><constant>V4L2_FMT_FLAG_COMPRESSED</constant></entry>
 132             <entry>0x0001</entry>
 133             <entry>This is a compressed format.</entry>
 134           </row>
 135           <row>
 136             <entry><constant>V4L2_FMT_FLAG_EMULATED</constant></entry>
 137             <entry>0x0002</entry>
 138             <entry>This format is not native to the device but emulated
 139 through software (usually libv4l2), where possible try to use a native format
 140 instead for better performance.</entry>
 141           </row>
 142         </tbody>
 143       </tgroup>
 144     </table>
 145   </refsect1>
 146
 147   <refsect1>
 148     &return-value;
 149
 150     <variablelist>
 151       <varlistentry>
 152         <term><errorcode>EINVAL</errorcode></term>
 153         <listitem>
 154           <para>The &v4l2-fmtdesc; <structfield>type</structfield>
 155 is not supported or the <structfield>index</structfield> is out of
 156 bounds.</para>
 157         </listitem>
 158       </varlistentry>
 159     </variablelist>
 160   </refsect1>
 161 </refentry>