aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/v4l/vidioc-enum-fmt.xml
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@redhat.com>2009-09-13 21:16:04 -0400
committerMauro Carvalho Chehab <mchehab@redhat.com>2009-09-18 22:47:55 -0400
commit8e080c2e6cadada82a6b520e0c23a1cb974822d5 (patch)
tree991450ff1abba98e5313906478c33816a202ccab /Documentation/DocBook/v4l/vidioc-enum-fmt.xml
parentf4e96deb4513d044653027d4921fd7592195503a (diff)
V4L/DVB (12761): DocBook: add media API specs
The V4L and DVB API's are there for a long time. however, up to now, no efforts were done to merge them to kernel DocBook. This patch adds the current versions of the specs as an unique compendium. Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/DocBook/v4l/vidioc-enum-fmt.xml')
-rw-r--r--Documentation/DocBook/v4l/vidioc-enum-fmt.xml164
1 files changed, 164 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml
new file mode 100644
index 000000000000..960d44615ca6
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml
@@ -0,0 +1,164 @@
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>
54field of &v4l2-fmtdesc; and call the
55<constant>VIDIOC_ENUM_FMT</constant> ioctl with a pointer to this
56structure. Drivers fill the rest of the structure or return an
57&EINVAL;. All formats are enumerable by beginning at index zero and
58incrementing by one until <errorcode>EINVAL</errorcode> is
59returned.</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
70the application. This is in no way related to the <structfield>
71pixelformat</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.
77Only 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
81defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
82and 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
93string. This information is intended for the user, for example: "YUV
944: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
100four character code as computed by the v4l2_fourcc()
101macro:</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
107defined by this specification in <xref linkend="pixfmt" />. Note these
108codes 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
114the 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
134through software (usually libv4l2), where possible try to use a native format
135instead 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>
150is not supported or the <structfield>index</structfield> is out of
151bounds.</para>
152 </listitem>
153 </varlistentry>
154 </variablelist>
155 </refsect1>
156</refentry>
157
158<!--
159Local Variables:
160mode: sgml
161sgml-parent-document: "v4l2.sgml"
162indent-tabs-mode: nil
163End:
164-->