Commit | Line | Data |
---|---|---|
8e080c2e MCC |
1 | <title>Image Formats</title> |
2 | ||
3 | <para>The V4L2 API was primarily designed for devices exchanging | |
4 | image data with applications. The | |
5 | <structname>v4l2_pix_format</structname> structure defines the format | |
6 | and layout of an image in memory. Image formats are negotiated with | |
7 | the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video | |
8 | capturing and output, for overlay frame buffer formats see also | |
9 | &VIDIOC-G-FBUF;.)</para> | |
10 | ||
11 | <table pgwide="1" frame="none" id="v4l2-pix-format"> | |
12 | <title>struct <structname>v4l2_pix_format</structname></title> | |
13 | <tgroup cols="3"> | |
14 | &cs-str; | |
15 | <tbody valign="top"> | |
16 | <row> | |
17 | <entry>__u32</entry> | |
18 | <entry><structfield>width</structfield></entry> | |
19 | <entry>Image width in pixels.</entry> | |
20 | </row> | |
21 | <row> | |
22 | <entry>__u32</entry> | |
23 | <entry><structfield>height</structfield></entry> | |
24 | <entry>Image height in pixels.</entry> | |
25 | </row> | |
26 | <row> | |
27 | <entry spanname="hspan">Applications set these fields to | |
28 | request an image size, drivers return the closest possible values. In | |
29 | case of planar formats the <structfield>width</structfield> and | |
30 | <structfield>height</structfield> applies to the largest plane. To | |
31 | avoid ambiguities drivers must return values rounded up to a multiple | |
32 | of the scale factor of any smaller planes. For example when the image | |
33 | format is YUV 4:2:0, <structfield>width</structfield> and | |
34 | <structfield>height</structfield> must be multiples of two.</entry> | |
35 | </row> | |
36 | <row> | |
37 | <entry>__u32</entry> | |
38 | <entry><structfield>pixelformat</structfield></entry> | |
39 | <entry>The pixel format or type of compression, set by the | |
40 | application. This is a little endian <link | |
41 | linkend="v4l2-fourcc">four character code</link>. V4L2 defines | |
42 | standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref | |
43 | linkend="yuv-formats" />, and reserved codes in <xref | |
44 | linkend="reserved-formats" /></entry> | |
45 | </row> | |
46 | <row> | |
47 | <entry>&v4l2-field;</entry> | |
48 | <entry><structfield>field</structfield></entry> | |
49 | <entry>Video images are typically interlaced. Applications | |
50 | can request to capture or output only the top or bottom field, or both | |
51 | fields interlaced or sequentially stored in one buffer or alternating | |
52 | in separate buffers. Drivers return the actual field order selected. | |
53 | For details see <xref linkend="field-order" />.</entry> | |
54 | </row> | |
55 | <row> | |
56 | <entry>__u32</entry> | |
57 | <entry><structfield>bytesperline</structfield></entry> | |
58 | <entry>Distance in bytes between the leftmost pixels in two | |
59 | adjacent lines.</entry> | |
60 | </row> | |
61 | <row> | |
62 | <entry spanname="hspan"><para>Both applications and drivers | |
63 | can set this field to request padding bytes at the end of each line. | |
64 | Drivers however may ignore the value requested by the application, | |
65 | returning <structfield>width</structfield> times bytes per pixel or a | |
66 | larger value required by the hardware. That implies applications can | |
67 | just set this field to zero to get a reasonable | |
68 | default.</para><para>Video hardware may access padding bytes, | |
69 | therefore they must reside in accessible memory. Consider cases where | |
70 | padding bytes after the last line of an image cross a system page | |
71 | boundary. Input devices may write padding bytes, the value is | |
72 | undefined. Output devices ignore the contents of padding | |
73 | bytes.</para><para>When the image format is planar the | |
74 | <structfield>bytesperline</structfield> value applies to the largest | |
75 | plane and is divided by the same factor as the | |
76 | <structfield>width</structfield> field for any smaller planes. For | |
77 | example the Cb and Cr planes of a YUV 4:2:0 image have half as many | |
78 | padding bytes following each line as the Y plane. To avoid ambiguities | |
79 | drivers must return a <structfield>bytesperline</structfield> value | |
80 | rounded up to a multiple of the scale factor.</para></entry> | |
81 | </row> | |
82 | <row> | |
83 | <entry>__u32</entry> | |
84 | <entry><structfield>sizeimage</structfield></entry> | |
85 | <entry>Size in bytes of the buffer to hold a complete image, | |
86 | set by the driver. Usually this is | |
87 | <structfield>bytesperline</structfield> times | |
88 | <structfield>height</structfield>. When the image consists of variable | |
89 | length compressed data this is the maximum number of bytes required to | |
90 | hold an image.</entry> | |
91 | </row> | |
92 | <row> | |
93 | <entry>&v4l2-colorspace;</entry> | |
94 | <entry><structfield>colorspace</structfield></entry> | |
95 | <entry>This information supplements the | |
96 | <structfield>pixelformat</structfield> and must be set by the driver, | |
97 | see <xref linkend="colorspaces" />.</entry> | |
98 | </row> | |
99 | <row> | |
100 | <entry>__u32</entry> | |
101 | <entry><structfield>priv</structfield></entry> | |
102 | <entry>Reserved for custom (driver defined) additional | |
103 | information about formats. When not used drivers and applications must | |
104 | set this field to zero.</entry> | |
105 | </row> | |
106 | </tbody> | |
107 | </tgroup> | |
108 | </table> | |
109 | ||
110 | <section> | |
111 | <title>Standard Image Formats</title> | |
112 | ||
113 | <para>In order to exchange images between drivers and | |
114 | applications, it is necessary to have standard image data formats | |
115 | which both sides will interpret the same way. V4L2 includes several | |
116 | such formats, and this section is intended to be an unambiguous | |
117 | specification of the standard image data formats in V4L2.</para> | |
118 | ||
119 | <para>V4L2 drivers are not limited to these formats, however. | |
120 | Driver-specific formats are possible. In that case the application may | |
121 | depend on a codec to convert images to one of the standard formats | |
122 | when needed. But the data can still be stored and retrieved in the | |
123 | proprietary format. For example, a device may support a proprietary | |
124 | compressed format. Applications can still capture and save the data in | |
125 | the compressed format, saving much disk space, and later use a codec | |
126 | to convert the images to the X Windows screen format when the video is | |
127 | to be displayed.</para> | |
128 | ||
129 | <para>Even so, ultimately, some standard formats are needed, so | |
130 | the V4L2 specification would not be complete without well-defined | |
131 | standard formats.</para> | |
132 | ||
133 | <para>The V4L2 standard formats are mainly uncompressed formats. The | |
134 | pixels are always arranged in memory from left to right, and from top | |
135 | to bottom. The first byte of data in the image buffer is always for | |
136 | the leftmost pixel of the topmost row. Following that is the pixel | |
137 | immediately to its right, and so on until the end of the top row of | |
138 | pixels. Following the rightmost pixel of the row there may be zero or | |
139 | more bytes of padding to guarantee that each row of pixel data has a | |
140 | certain alignment. Following the pad bytes, if any, is data for the | |
141 | leftmost pixel of the second row from the top, and so on. The last row | |
142 | has just as many pad bytes after it as the other rows.</para> | |
143 | ||
144 | <para>In V4L2 each format has an identifier which looks like | |
145 | <constant>PIX_FMT_XXX</constant>, defined in the <link | |
146 | linkend="videodev">videodev.h</link> header file. These identifiers | |
147 | represent <link linkend="v4l2-fourcc">four character codes</link> | |
148 | which are also listed below, however they are not the same as those | |
149 | used in the Windows world.</para> | |
150 | </section> | |
151 | ||
152 | <section id="colorspaces"> | |
153 | <title>Colorspaces</title> | |
154 | ||
155 | <para>[intro]</para> | |
156 | ||
157 | <!-- See proposal by Billy Biggs, video4linux-list@redhat.com | |
158 | on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and | |
159 | http://vektor.theorem.ca/graphics/ycbcr/ and | |
e5b20214 | 160 | http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html --> |
8e080c2e MCC |
161 | |
162 | <para> | |
163 | <variablelist> | |
164 | <varlistentry> | |
165 | <term>Gamma Correction</term> | |
166 | <listitem> | |
167 | <para>[to do]</para> | |
168 | <para>E'<subscript>R</subscript> = f(R)</para> | |
169 | <para>E'<subscript>G</subscript> = f(G)</para> | |
170 | <para>E'<subscript>B</subscript> = f(B)</para> | |
171 | </listitem> | |
172 | </varlistentry> | |
173 | <varlistentry> | |
174 | <term>Construction of luminance and color-difference | |
175 | signals</term> | |
176 | <listitem> | |
177 | <para>[to do]</para> | |
178 | <para>E'<subscript>Y</subscript> = | |
179 | Coeff<subscript>R</subscript> E'<subscript>R</subscript> | |
180 | + Coeff<subscript>G</subscript> E'<subscript>G</subscript> | |
181 | + Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> | |
182 | <para>(E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = E'<subscript>R</subscript> | |
183 | - Coeff<subscript>R</subscript> E'<subscript>R</subscript> | |
184 | - Coeff<subscript>G</subscript> E'<subscript>G</subscript> | |
185 | - Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> | |
186 | <para>(E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = E'<subscript>B</subscript> | |
187 | - Coeff<subscript>R</subscript> E'<subscript>R</subscript> | |
188 | - Coeff<subscript>G</subscript> E'<subscript>G</subscript> | |
189 | - Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> | |
190 | </listitem> | |
191 | </varlistentry> | |
192 | <varlistentry> | |
193 | <term>Re-normalized color-difference signals</term> | |
194 | <listitem> | |
195 | <para>The color-difference signals are scaled back to unity | |
196 | range [-0.5;+0.5]:</para> | |
197 | <para>K<subscript>B</subscript> = 0.5 / (1 - Coeff<subscript>B</subscript>)</para> | |
198 | <para>K<subscript>R</subscript> = 0.5 / (1 - Coeff<subscript>R</subscript>)</para> | |
199 | <para>P<subscript>B</subscript> = | |
200 | K<subscript>B</subscript> (E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = | |
201 | 0.5 (Coeff<subscript>R</subscript> / Coeff<subscript>B</subscript>) E'<subscript>R</subscript> | |
202 | + 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>B</subscript>) E'<subscript>G</subscript> | |
203 | + 0.5 E'<subscript>B</subscript></para> | |
204 | <para>P<subscript>R</subscript> = | |
205 | K<subscript>R</subscript> (E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = | |
206 | 0.5 E'<subscript>R</subscript> | |
207 | + 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>R</subscript>) E'<subscript>G</subscript> | |
208 | + 0.5 (Coeff<subscript>B</subscript> / Coeff<subscript>R</subscript>) E'<subscript>B</subscript></para> | |
209 | </listitem> | |
210 | </varlistentry> | |
211 | <varlistentry> | |
212 | <term>Quantization</term> | |
213 | <listitem> | |
214 | <para>[to do]</para> | |
215 | <para>Y' = (Lum. Levels - 1) · E'<subscript>Y</subscript> + Lum. Offset</para> | |
216 | <para>C<subscript>B</subscript> = (Chrom. Levels - 1) | |
217 | · P<subscript>B</subscript> + Chrom. Offset</para> | |
218 | <para>C<subscript>R</subscript> = (Chrom. Levels - 1) | |
219 | · P<subscript>R</subscript> + Chrom. Offset</para> | |
220 | <para>Rounding to the nearest integer and clamping to the range | |
221 | [0;255] finally yields the digital color components Y'CbCr | |
222 | stored in YUV images.</para> | |
223 | </listitem> | |
224 | </varlistentry> | |
225 | </variablelist> | |
226 | </para> | |
227 | ||
228 | <example> | |
229 | <title>ITU-R Rec. BT.601 color conversion</title> | |
230 | ||
231 | <para>Forward Transformation</para> | |
232 | ||
233 | <programlisting> | |
234 | int ER, EG, EB; /* gamma corrected RGB input [0;255] */ | |
235 | int Y1, Cb, Cr; /* output [0;255] */ | |
236 | ||
237 | double r, g, b; /* temporaries */ | |
238 | double y1, pb, pr; | |
239 | ||
240 | int | |
241 | clamp (double x) | |
242 | { | |
243 | int r = x; /* round to nearest */ | |
244 | ||
245 | if (r < 0) return 0; | |
246 | else if (r > 255) return 255; | |
247 | else return r; | |
248 | } | |
249 | ||
250 | r = ER / 255.0; | |
251 | g = EG / 255.0; | |
252 | b = EB / 255.0; | |
253 | ||
254 | y1 = 0.299 * r + 0.587 * g + 0.114 * b; | |
255 | pb = -0.169 * r - 0.331 * g + 0.5 * b; | |
256 | pr = 0.5 * r - 0.419 * g - 0.081 * b; | |
257 | ||
258 | Y1 = clamp (219 * y1 + 16); | |
259 | Cb = clamp (224 * pb + 128); | |
260 | Cr = clamp (224 * pr + 128); | |
261 | ||
262 | /* or shorter */ | |
263 | ||
264 | y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB; | |
265 | ||
266 | Y1 = clamp ( (219 / 255.0) * y1 + 16); | |
267 | Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128); | |
268 | Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128); | |
269 | </programlisting> | |
270 | ||
271 | <para>Inverse Transformation</para> | |
272 | ||
273 | <programlisting> | |
274 | int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */ | |
275 | int ER, EG, EB; /* output [0;255] */ | |
276 | ||
277 | double r, g, b; /* temporaries */ | |
278 | double y1, pb, pr; | |
279 | ||
280 | int | |
281 | clamp (double x) | |
282 | { | |
283 | int r = x; /* round to nearest */ | |
284 | ||
285 | if (r < 0) return 0; | |
286 | else if (r > 255) return 255; | |
287 | else return r; | |
288 | } | |
289 | ||
290 | y1 = (255 / 219.0) * (Y1 - 16); | |
291 | pb = (255 / 224.0) * (Cb - 128); | |
292 | pr = (255 / 224.0) * (Cr - 128); | |
293 | ||
294 | r = 1.0 * y1 + 0 * pb + 1.402 * pr; | |
295 | g = 1.0 * y1 - 0.344 * pb - 0.714 * pr; | |
296 | b = 1.0 * y1 + 1.772 * pb + 0 * pr; | |
297 | ||
298 | ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */ | |
299 | EG = clamp (g * 255); | |
300 | EB = clamp (b * 255); | |
301 | </programlisting> | |
302 | </example> | |
303 | ||
304 | <table pgwide="1" id="v4l2-colorspace" orient="land"> | |
305 | <title>enum v4l2_colorspace</title> | |
306 | <tgroup cols="11" align="center"> | |
307 | <colspec align="left" /> | |
308 | <colspec align="center" /> | |
309 | <colspec align="left" /> | |
310 | <colspec colname="cr" /> | |
311 | <colspec colname="cg" /> | |
312 | <colspec colname="cb" /> | |
313 | <colspec colname="wp" /> | |
314 | <colspec colname="gc" /> | |
315 | <colspec colname="lum" /> | |
316 | <colspec colname="qy" /> | |
317 | <colspec colname="qc" /> | |
318 | <spanspec namest="cr" nameend="cb" spanname="chrom" /> | |
319 | <spanspec namest="qy" nameend="qc" spanname="quant" /> | |
320 | <spanspec namest="lum" nameend="qc" spanname="spam" /> | |
321 | <thead> | |
322 | <row> | |
323 | <entry morerows="1">Identifier</entry> | |
324 | <entry morerows="1">Value</entry> | |
325 | <entry morerows="1">Description</entry> | |
326 | <entry spanname="chrom">Chromaticities<footnote> | |
327 | <para>The coordinates of the color primaries are | |
328 | given in the CIE system (1931)</para> | |
329 | </footnote></entry> | |
330 | <entry morerows="1">White Point</entry> | |
331 | <entry morerows="1">Gamma Correction</entry> | |
332 | <entry morerows="1">Luminance E'<subscript>Y</subscript></entry> | |
333 | <entry spanname="quant">Quantization</entry> | |
334 | </row> | |
335 | <row> | |
336 | <entry>Red</entry> | |
337 | <entry>Green</entry> | |
338 | <entry>Blue</entry> | |
339 | <entry>Y'</entry> | |
340 | <entry>Cb, Cr</entry> | |
341 | </row> | |
342 | </thead> | |
343 | <tbody valign="top"> | |
344 | <row> | |
345 | <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> | |
346 | <entry>1</entry> | |
347 | <entry>NTSC/PAL according to <xref linkend="smpte170m" />, | |
348 | <xref linkend="itu601" /></entry> | |
349 | <entry>x = 0.630, y = 0.340</entry> | |
350 | <entry>x = 0.310, y = 0.595</entry> | |
351 | <entry>x = 0.155, y = 0.070</entry> | |
352 | <entry>x = 0.3127, y = 0.3290, | |
353 | Illuminant D<subscript>65</subscript></entry> | |
354 | <entry>E' = 4.5 I for I ≤0.018, | |
355 | 1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> | |
356 | <entry>0.299 E'<subscript>R</subscript> | |
357 | + 0.587 E'<subscript>G</subscript> | |
358 | + 0.114 E'<subscript>B</subscript></entry> | |
359 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | |
360 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | |
361 | </row> | |
362 | <row> | |
363 | <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> | |
364 | <entry>2</entry> | |
365 | <entry>1125-Line (US) HDTV, see <xref | |
366 | linkend="smpte240m" /></entry> | |
367 | <entry>x = 0.630, y = 0.340</entry> | |
368 | <entry>x = 0.310, y = 0.595</entry> | |
369 | <entry>x = 0.155, y = 0.070</entry> | |
370 | <entry>x = 0.3127, y = 0.3290, | |
371 | Illuminant D<subscript>65</subscript></entry> | |
372 | <entry>E' = 4 I for I ≤0.0228, | |
373 | 1.1115 I<superscript>0.45</superscript> - 0.1115 for 0.0228 < I</entry> | |
374 | <entry>0.212 E'<subscript>R</subscript> | |
375 | + 0.701 E'<subscript>G</subscript> | |
376 | + 0.087 E'<subscript>B</subscript></entry> | |
377 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | |
378 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | |
379 | </row> | |
380 | <row> | |
381 | <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> | |
382 | <entry>3</entry> | |
383 | <entry>HDTV and modern devices, see <xref | |
384 | linkend="itu709" /></entry> | |
385 | <entry>x = 0.640, y = 0.330</entry> | |
386 | <entry>x = 0.300, y = 0.600</entry> | |
387 | <entry>x = 0.150, y = 0.060</entry> | |
388 | <entry>x = 0.3127, y = 0.3290, | |
389 | Illuminant D<subscript>65</subscript></entry> | |
390 | <entry>E' = 4.5 I for I ≤0.018, | |
391 | 1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> | |
392 | <entry>0.2125 E'<subscript>R</subscript> | |
393 | + 0.7154 E'<subscript>G</subscript> | |
394 | + 0.0721 E'<subscript>B</subscript></entry> | |
395 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | |
396 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | |
397 | </row> | |
398 | <row> | |
399 | <entry><constant>V4L2_COLORSPACE_BT878</constant></entry> | |
400 | <entry>4</entry> | |
401 | <entry>Broken Bt878 extents<footnote> | |
402 | <para>The ubiquitous Bt878 video capture chip | |
403 | quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range | |
404 | of Y' = 16 … 253, unlike Rec. 601 Y' = 16 … | |
405 | 235. This is not a typo in the Bt878 documentation, it has been | |
406 | implemented in silicon. The chroma extents are unclear.</para> | |
407 | </footnote>, <xref linkend="itu601" /></entry> | |
408 | <entry>?</entry> | |
409 | <entry>?</entry> | |
410 | <entry>?</entry> | |
411 | <entry>?</entry> | |
412 | <entry>?</entry> | |
413 | <entry>0.299 E'<subscript>R</subscript> | |
414 | + 0.587 E'<subscript>G</subscript> | |
415 | + 0.114 E'<subscript>B</subscript></entry> | |
416 | <entry><emphasis>237</emphasis> E'<subscript>Y</subscript> + 16</entry> | |
417 | <entry>224 P<subscript>B,R</subscript> + 128 (probably)</entry> | |
418 | </row> | |
419 | <row> | |
420 | <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry> | |
421 | <entry>5</entry> | |
422 | <entry>M/NTSC<footnote> | |
423 | <para>No identifier exists for M/PAL which uses | |
424 | the chromaticities of M/NTSC, the remaining parameters are equal to B and | |
425 | G/PAL.</para> | |
426 | </footnote> according to <xref linkend="itu470" />, <xref | |
427 | linkend="itu601" /></entry> | |
428 | <entry>x = 0.67, y = 0.33</entry> | |
429 | <entry>x = 0.21, y = 0.71</entry> | |
430 | <entry>x = 0.14, y = 0.08</entry> | |
431 | <entry>x = 0.310, y = 0.316, Illuminant C</entry> | |
432 | <entry>?</entry> | |
433 | <entry>0.299 E'<subscript>R</subscript> | |
434 | + 0.587 E'<subscript>G</subscript> | |
435 | + 0.114 E'<subscript>B</subscript></entry> | |
436 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | |
437 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | |
438 | </row> | |
439 | <row> | |
440 | <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry> | |
441 | <entry>6</entry> | |
442 | <entry>625-line PAL and SECAM systems according to <xref | |
443 | linkend="itu470" />, <xref linkend="itu601" /></entry> | |
444 | <entry>x = 0.64, y = 0.33</entry> | |
445 | <entry>x = 0.29, y = 0.60</entry> | |
446 | <entry>x = 0.15, y = 0.06</entry> | |
447 | <entry>x = 0.313, y = 0.329, | |
448 | Illuminant D<subscript>65</subscript></entry> | |
449 | <entry>?</entry> | |
450 | <entry>0.299 E'<subscript>R</subscript> | |
451 | + 0.587 E'<subscript>G</subscript> | |
452 | + 0.114 E'<subscript>B</subscript></entry> | |
453 | <entry>219 E'<subscript>Y</subscript> + 16</entry> | |
454 | <entry>224 P<subscript>B,R</subscript> + 128</entry> | |
455 | </row> | |
456 | <row> | |
457 | <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> | |
458 | <entry>7</entry> | |
459 | <entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry> | |
460 | <entry>?</entry> | |
461 | <entry>?</entry> | |
462 | <entry>?</entry> | |
463 | <entry>?</entry> | |
464 | <entry>?</entry> | |
465 | <entry>0.299 E'<subscript>R</subscript> | |
466 | + 0.587 E'<subscript>G</subscript> | |
467 | + 0.114 E'<subscript>B</subscript></entry> | |
468 | <entry>256 E'<subscript>Y</subscript> + 16<footnote> | |
469 | <para>Note JFIF quantizes | |
470 | Y'P<subscript>B</subscript>P<subscript>R</subscript> in range [0;+1] and | |
471 | [-0.5;+0.5] to <emphasis>257</emphasis> levels, however Y'CbCr signals | |
472 | are still clamped to [0;255].</para> | |
473 | </footnote></entry> | |
474 | <entry>256 P<subscript>B,R</subscript> + 128</entry> | |
475 | </row> | |
476 | <row> | |
477 | <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> | |
478 | <entry>8</entry> | |
479 | <entry>[?]</entry> | |
480 | <entry>x = 0.640, y = 0.330</entry> | |
481 | <entry>x = 0.300, y = 0.600</entry> | |
482 | <entry>x = 0.150, y = 0.060</entry> | |
483 | <entry>x = 0.3127, y = 0.3290, | |
484 | Illuminant D<subscript>65</subscript></entry> | |
485 | <entry>E' = 4.5 I for I ≤0.018, | |
486 | 1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> | |
487 | <entry spanname="spam">n/a</entry> | |
488 | </row> | |
489 | </tbody> | |
490 | </tgroup> | |
491 | </table> | |
492 | </section> | |
493 | ||
494 | <section id="pixfmt-indexed"> | |
495 | <title>Indexed Format</title> | |
496 | ||
497 | <para>In this format each pixel is represented by an 8 bit index | |
498 | into a 256 entry ARGB palette. It is intended for <link | |
499 | linkend="osd">Video Output Overlays</link> only. There are no ioctls to | |
500 | access the palette, this must be done with ioctls of the Linux framebuffer API.</para> | |
501 | ||
502 | <table pgwide="0" frame="none"> | |
503 | <title>Indexed Image Format</title> | |
504 | <tgroup cols="37" align="center"> | |
505 | <colspec colname="id" align="left" /> | |
506 | <colspec colname="fourcc" /> | |
507 | <colspec colname="bit" /> | |
508 | ||
509 | <colspec colnum="4" colname="b07" align="center" /> | |
510 | <colspec colnum="5" colname="b06" align="center" /> | |
511 | <colspec colnum="6" colname="b05" align="center" /> | |
512 | <colspec colnum="7" colname="b04" align="center" /> | |
513 | <colspec colnum="8" colname="b03" align="center" /> | |
514 | <colspec colnum="9" colname="b02" align="center" /> | |
515 | <colspec colnum="10" colname="b01" align="center" /> | |
516 | <colspec colnum="11" colname="b00" align="center" /> | |
517 | ||
518 | <spanspec namest="b07" nameend="b00" spanname="b0" /> | |
519 | <spanspec namest="b17" nameend="b10" spanname="b1" /> | |
520 | <spanspec namest="b27" nameend="b20" spanname="b2" /> | |
521 | <spanspec namest="b37" nameend="b30" spanname="b3" /> | |
522 | <thead> | |
523 | <row> | |
524 | <entry>Identifier</entry> | |
525 | <entry>Code</entry> | |
526 | <entry> </entry> | |
527 | <entry spanname="b0">Byte 0</entry> | |
528 | </row> | |
529 | <row> | |
530 | <entry> </entry> | |
531 | <entry> </entry> | |
532 | <entry>Bit</entry> | |
533 | <entry>7</entry> | |
534 | <entry>6</entry> | |
535 | <entry>5</entry> | |
536 | <entry>4</entry> | |
537 | <entry>3</entry> | |
538 | <entry>2</entry> | |
539 | <entry>1</entry> | |
540 | <entry>0</entry> | |
541 | </row> | |
542 | </thead> | |
543 | <tbody valign="top"> | |
544 | <row id="V4L2-PIX-FMT-PAL8"> | |
545 | <entry><constant>V4L2_PIX_FMT_PAL8</constant></entry> | |
546 | <entry>'PAL8'</entry> | |
547 | <entry></entry> | |
548 | <entry>i<subscript>7</subscript></entry> | |
549 | <entry>i<subscript>6</subscript></entry> | |
550 | <entry>i<subscript>5</subscript></entry> | |
551 | <entry>i<subscript>4</subscript></entry> | |
552 | <entry>i<subscript>3</subscript></entry> | |
553 | <entry>i<subscript>2</subscript></entry> | |
554 | <entry>i<subscript>1</subscript></entry> | |
555 | <entry>i<subscript>0</subscript></entry> | |
556 | </row> | |
557 | </tbody> | |
558 | </tgroup> | |
559 | </table> | |
560 | </section> | |
561 | ||
562 | <section id="pixfmt-rgb"> | |
563 | <title>RGB Formats</title> | |
564 | ||
565 | &sub-packed-rgb; | |
566 | &sub-sbggr8; | |
567 | &sub-sgbrg8; | |
568 | &sub-sgrbg8; | |
569 | &sub-sbggr16; | |
570 | </section> | |
571 | ||
572 | <section id="yuv-formats"> | |
573 | <title>YUV Formats</title> | |
574 | ||
575 | <para>YUV is the format native to TV broadcast and composite video | |
576 | signals. It separates the brightness information (Y) from the color | |
577 | information (U and V or Cb and Cr). The color information consists of | |
578 | red and blue <emphasis>color difference</emphasis> signals, this way | |
579 | the green component can be reconstructed by subtracting from the | |
580 | brightness component. See <xref linkend="colorspaces" /> for conversion | |
581 | examples. YUV was chosen because early television would only transmit | |
582 | brightness information. To add color in a way compatible with existing | |
583 | receivers a new signal carrier was added to transmit the color | |
584 | difference signals. Secondary in the YUV format the U and V components | |
585 | usually have lower resolution than the Y component. This is an analog | |
586 | video compression technique taking advantage of a property of the | |
587 | human visual system, being more sensitive to brightness | |
588 | information.</para> | |
589 | ||
590 | &sub-packed-yuv; | |
591 | &sub-grey; | |
592 | &sub-y16; | |
593 | &sub-yuyv; | |
594 | &sub-uyvy; | |
595 | &sub-yvyu; | |
596 | &sub-vyuy; | |
597 | &sub-y41p; | |
598 | &sub-yuv420; | |
599 | &sub-yuv410; | |
600 | &sub-yuv422p; | |
601 | &sub-yuv411p; | |
602 | &sub-nv12; | |
603 | &sub-nv16; | |
604 | </section> | |
605 | ||
606 | <section> | |
607 | <title>Compressed Formats</title> | |
608 | ||
609 | <table pgwide="1" frame="none" id="compressed-formats"> | |
610 | <title>Compressed Image Formats</title> | |
611 | <tgroup cols="3" align="left"> | |
612 | &cs-def; | |
613 | <thead> | |
614 | <row> | |
615 | <entry>Identifier</entry> | |
616 | <entry>Code</entry> | |
617 | <entry>Details</entry> | |
618 | </row> | |
619 | </thead> | |
620 | <tbody valign="top"> | |
621 | <row id="V4L2-PIX-FMT-JPEG"> | |
622 | <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry> | |
623 | <entry>'JPEG'</entry> | |
624 | <entry>TBD. See also &VIDIOC-G-JPEGCOMP;, | |
625 | &VIDIOC-S-JPEGCOMP;.</entry> | |
626 | </row> | |
627 | <row id="V4L2-PIX-FMT-MPEG"> | |
628 | <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry> | |
629 | <entry>'MPEG'</entry> | |
630 | <entry>MPEG stream. The actual format is determined by | |
631 | extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see | |
632 | <xref linkend="mpeg-control-id" />.</entry> | |
633 | </row> | |
634 | </tbody> | |
635 | </tgroup> | |
636 | </table> | |
637 | </section> | |
638 | ||
639 | <section id="pixfmt-reserved"> | |
640 | <title>Reserved Format Identifiers</title> | |
641 | ||
642 | <para>These formats are not defined by this specification, they | |
643 | are just listed for reference and to avoid naming conflicts. If you | |
644 | want to register your own format, send an e-mail to the linux-media mailing | |
645 | list &v4l-ml; for inclusion in the <filename>videodev2.h</filename> | |
646 | file. If you want to share your format with other developers add a | |
647 | link to your documentation and send a copy to the linux-media mailing list | |
648 | for inclusion in this section. If you think your format should be listed | |
649 | in a standard format section please make a proposal on the linux-media mailing | |
650 | list.</para> | |
651 | ||
652 | <table pgwide="1" frame="none" id="reserved-formats"> | |
653 | <title>Reserved Image Formats</title> | |
654 | <tgroup cols="3" align="left"> | |
655 | &cs-def; | |
656 | <thead> | |
657 | <row> | |
658 | <entry>Identifier</entry> | |
659 | <entry>Code</entry> | |
660 | <entry>Details</entry> | |
661 | </row> | |
662 | </thead> | |
663 | <tbody valign="top"> | |
664 | <row id="V4L2-PIX-FMT-DV"> | |
665 | <entry><constant>V4L2_PIX_FMT_DV</constant></entry> | |
666 | <entry>'dvsd'</entry> | |
667 | <entry>unknown</entry> | |
668 | </row> | |
669 | <row id="V4L2-PIX-FMT-ET61X251"> | |
670 | <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry> | |
671 | <entry>'E625'</entry> | |
672 | <entry>Compressed format of the ET61X251 driver.</entry> | |
673 | </row> | |
674 | <row id="V4L2-PIX-FMT-HI240"> | |
675 | <entry><constant>V4L2_PIX_FMT_HI240</constant></entry> | |
676 | <entry>'HI24'</entry> | |
677 | <entry><para>8 bit RGB format used by the BTTV driver.</para></entry> | |
678 | </row> | |
679 | <row id="V4L2-PIX-FMT-HM12"> | |
680 | <entry><constant>V4L2_PIX_FMT_HM12</constant></entry> | |
681 | <entry>'HM12'</entry> | |
682 | <entry><para>YUV 4:2:0 format used by the | |
683 | IVTV driver, <ulink url="http://www.ivtvdriver.org/"> | |
684 | http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the | |
685 | kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename> | |
686 | </para></entry> | |
687 | </row> | |
688 | <row id="V4L2-PIX-FMT-SPCA501"> | |
689 | <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry> | |
690 | <entry>'S501'</entry> | |
691 | <entry>YUYV per line used by the gspca driver.</entry> | |
692 | </row> | |
693 | <row id="V4L2-PIX-FMT-SPCA505"> | |
694 | <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry> | |
695 | <entry>'S505'</entry> | |
696 | <entry>YYUV per line used by the gspca driver.</entry> | |
697 | </row> | |
698 | <row id="V4L2-PIX-FMT-SPCA508"> | |
699 | <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry> | |
700 | <entry>'S508'</entry> | |
701 | <entry>YUVY per line used by the gspca driver.</entry> | |
702 | </row> | |
703 | <row id="V4L2-PIX-FMT-SPCA561"> | |
704 | <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry> | |
705 | <entry>'S561'</entry> | |
706 | <entry>Compressed GBRG Bayer format used by the gspca driver.</entry> | |
707 | </row> | |
708 | <row id="V4L2-PIX-FMT-SGRBG10"> | |
709 | <entry><constant>V4L2_PIX_FMT_SGRBG10</constant></entry> | |
710 | <entry>'DA10'</entry> | |
711 | <entry>10 bit raw Bayer, expanded to 16 bits.</entry> | |
712 | </row> | |
713 | <row id="V4L2-PIX-FMT-SGRBG10DPCM8"> | |
714 | <entry><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></entry> | |
715 | <entry>'DB10'</entry> | |
716 | <entry>10 bit raw Bayer DPCM compressed to 8 bits.</entry> | |
717 | </row> | |
718 | <row id="V4L2-PIX-FMT-PAC207"> | |
719 | <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry> | |
720 | <entry>'P207'</entry> | |
721 | <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> | |
722 | </row> | |
723 | <row id="V4L2-PIX-FMT-MR97310A"> | |
724 | <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry> | |
725 | <entry>'M310'</entry> | |
726 | <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> | |
727 | </row> | |
728 | <row id="V4L2-PIX-FMT-OV511"> | |
729 | <entry><constant>V4L2_PIX_FMT_OV511</constant></entry> | |
730 | <entry>'O511'</entry> | |
731 | <entry>OV511 JPEG format used by the gspca driver.</entry> | |
732 | </row> | |
733 | <row id="V4L2-PIX-FMT-OV518"> | |
734 | <entry><constant>V4L2_PIX_FMT_OV518</constant></entry> | |
735 | <entry>'O518'</entry> | |
736 | <entry>OV518 JPEG format used by the gspca driver.</entry> | |
737 | </row> | |
738 | <row id="V4L2-PIX-FMT-PJPG"> | |
739 | <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry> | |
740 | <entry>'PJPG'</entry> | |
741 | <entry>Pixart 73xx JPEG format used by the gspca driver.</entry> | |
742 | </row> | |
743 | <row id="V4L2-PIX-FMT-SQ905C"> | |
744 | <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry> | |
745 | <entry>'905C'</entry> | |
746 | <entry>Compressed RGGB bayer format used by the gspca driver.</entry> | |
747 | </row> | |
748 | <row id="V4L2-PIX-FMT-MJPEG"> | |
749 | <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry> | |
750 | <entry>'MJPG'</entry> | |
751 | <entry>Compressed format used by the Zoran driver</entry> | |
752 | </row> | |
753 | <row id="V4L2-PIX-FMT-PWC1"> | |
754 | <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry> | |
755 | <entry>'PWC1'</entry> | |
756 | <entry>Compressed format of the PWC driver.</entry> | |
757 | </row> | |
758 | <row id="V4L2-PIX-FMT-PWC2"> | |
759 | <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry> | |
760 | <entry>'PWC2'</entry> | |
761 | <entry>Compressed format of the PWC driver.</entry> | |
762 | </row> | |
763 | <row id="V4L2-PIX-FMT-SN9C10X"> | |
764 | <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry> | |
765 | <entry>'S910'</entry> | |
766 | <entry>Compressed format of the SN9C102 driver.</entry> | |
767 | </row> | |
768 | <row id="V4L2-PIX-FMT-SN9C20X-I420"> | |
769 | <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry> | |
770 | <entry>'S920'</entry> | |
771 | <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry> | |
772 | </row> | |
47a50307 HV |
773 | <row id="V4L2-PIX-FMT-STV0680"> |
774 | <entry><constant>V4L2_PIX_FMT_STV0680</constant></entry> | |
775 | <entry>'S680'</entry> | |
776 | <entry>Bayer format of the gspca stv0680 driver.</entry> | |
777 | </row> | |
8e080c2e MCC |
778 | <row id="V4L2-PIX-FMT-WNVA"> |
779 | <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry> | |
780 | <entry>'WNVA'</entry> | |
781 | <entry><para>Used by the Winnov Videum driver, <ulink | |
782 | url="http://www.thedirks.org/winnov/"> | |
783 | http://www.thedirks.org/winnov/</ulink></para></entry> | |
784 | </row> | |
4e5fee2b MCC |
785 | <row id="V4L2-PIX-FMT-TM6000"> |
786 | <entry><constant>V4L2_PIX_FMT_TM6000</constant></entry> | |
787 | <entry>'TM60'</entry> | |
788 | <entry><para>Used by Trident tm6000</para></entry> | |
789 | </row> | |
516c714c MCC |
790 | <row id="V4L2_PIX_FMT_CIT_YYVYUY"> |
791 | <entry><constant>V4L2_PIX_FMT_CIT_YYVYUY</constant></entry> | |
792 | <entry>'CITV'</entry> | |
793 | <entry><para>Used by xirlink CIT, found at IBM webcams.</para> | |
794 | <para>Uses one line of Y then 1 line of VYUY</para> | |
795 | </entry> | |
796 | </row> | |
797 | <row id="V4L2_PIX_FMT_KONICA420"> | |
798 | <entry><constant>V4L2_PIX_FMT_KONICA420</constant></entry> | |
799 | <entry>'KONI'</entry> | |
800 | <entry><para>Used by Konica webcams.</para> | |
801 | <para>YUV420 planar in blocks of 256 pixels.</para> | |
802 | </entry> | |
803 | </row> | |
8e080c2e MCC |
804 | <row id="V4L2-PIX-FMT-YYUV"> |
805 | <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry> | |
806 | <entry>'YYUV'</entry> | |
807 | <entry>unknown</entry> | |
808 | </row> | |
b3e212dc HV |
809 | <row id="V4L2-PIX-FMT-Y4"> |
810 | <entry><constant>V4L2_PIX_FMT_Y4</constant></entry> | |
811 | <entry>'Y04 '</entry> | |
812 | <entry>Old 4-bit greyscale format. Only the least significant 4 bits of each byte are used, | |
813 | the other bits are set to 0.</entry> | |
814 | </row> | |
815 | <row id="V4L2-PIX-FMT-Y6"> | |
816 | <entry><constant>V4L2_PIX_FMT_Y6</constant></entry> | |
817 | <entry>'Y06 '</entry> | |
818 | <entry>Old 6-bit greyscale format. Only the least significant 6 bits of each byte are used, | |
819 | the other bits are set to 0.</entry> | |
820 | </row> | |
8e080c2e MCC |
821 | </tbody> |
822 | </tgroup> | |
823 | </table> | |
824 | </section> | |
825 | ||
826 | <!-- | |
827 | Local Variables: | |
828 | mode: sgml | |
829 | sgml-parent-document: "v4l2.sgml" | |
830 | indent-tabs-mode: nil | |
831 | End: | |
832 | --> |