Check-in of baseline 2.6.34 tree
[linux-2.6.34-lpc32xx.git] / Documentation / DocBook / 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     <table pgwide="1" frame="none" id="v4l2-fmtdesc">
62       <title>struct <structname>v4l2_fmtdesc</structname></title>
63       <tgroup cols="3">
64         &cs-str;
65         <tbody valign="top">
66           <row>
67             <entry>__u32</entry>
68             <entry><structfield>index</structfield></entry>
69             <entry>Number of the format in the enumeration, set by
70 the application. This is in no way related to the <structfield>
71 pixelformat</structfield> field.</entry>
72           </row>
73           <row>
74             <entry>&v4l2-buf-type;</entry>
75             <entry><structfield>type</structfield></entry>
76             <entry>Type of the data stream, set by the application.
77 Only these types are valid here:
78 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
79 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
80 <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
81 defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
82 and higher.</entry>
83           </row>
84           <row>
85             <entry>__u32</entry>
86             <entry><structfield>flags</structfield></entry>
87             <entry>See <xref linkend="fmtdesc-flags" /></entry>
88           </row>
89           <row>
90             <entry>__u8</entry>
91             <entry><structfield>description</structfield>[32]</entry>
92             <entry>Description of the format, a NUL-terminated ASCII
93 string. This information is intended for the user, for example: "YUV
94 4:2:2".</entry>
95           </row>
96           <row>
97             <entry>__u32</entry>
98             <entry><structfield>pixelformat</structfield></entry>
99             <entry>The image format identifier. This is a
100 four character code as computed by the v4l2_fourcc()
101 macro:</entry>
102           </row>
103           <row>
104             <entry spanname="hspan"><para><programlisting id="v4l2-fourcc">
105 #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))
106 </programlisting></para><para>Several image formats are already
107 defined by this specification in <xref linkend="pixfmt" />. Note these
108 codes are not the same as those used in the Windows world.</para></entry>
109           </row>
110           <row>
111             <entry>__u32</entry>
112             <entry><structfield>reserved</structfield>[4]</entry>
113             <entry>Reserved for future extensions. Drivers must set
114 the array to zero.</entry>
115           </row>
116         </tbody>
117       </tgroup>
118     </table>
119
120     <table pgwide="1" frame="none" id="fmtdesc-flags">
121       <title>Image Format Description Flags</title>
122       <tgroup cols="3">
123         &cs-def;
124         <tbody valign="top">
125           <row>
126             <entry><constant>V4L2_FMT_FLAG_COMPRESSED</constant></entry>
127             <entry>0x0001</entry>
128             <entry>This is a compressed format.</entry>
129           </row>
130           <row>
131             <entry><constant>V4L2_FMT_FLAG_EMULATED</constant></entry>
132             <entry>0x0002</entry>
133             <entry>This format is not native to the device but emulated
134 through software (usually libv4l2), where possible try to use a native format
135 instead for better performance.</entry>
136           </row>
137         </tbody>
138       </tgroup>
139     </table>
140   </refsect1>
141
142   <refsect1>
143     &return-value;
144
145     <variablelist>
146       <varlistentry>
147         <term><errorcode>EINVAL</errorcode></term>
148         <listitem>
149           <para>The &v4l2-fmtdesc; <structfield>type</structfield>
150 is not supported or the <structfield>index</structfield> is out of
151 bounds.</para>
152         </listitem>
153       </varlistentry>
154     </variablelist>
155   </refsect1>
156 </refentry>
157
158 <!--
159 Local Variables:
160 mode: sgml
161 sgml-parent-document: "v4l2.sgml"
162 indent-tabs-mode: nil
163 End:
164 -->