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