Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | ********************** | |
4 | Standard Image Formats | |
5 | ********************** | |
6 | ||
7 | In order to exchange images between drivers and applications, it is | |
8 | necessary to have standard image data formats which both sides will | |
9 | interpret the same way. V4L2 includes several such formats, and this | |
10 | section is intended to be an unambiguous specification of the standard | |
11 | image data formats in V4L2. | |
12 | ||
13 | V4L2 drivers are not limited to these formats, however. Driver-specific | |
14 | formats are possible. In that case the application may depend on a codec | |
15 | to convert images to one of the standard formats when needed. But the | |
16 | data can still be stored and retrieved in the proprietary format. For | |
17 | example, a device may support a proprietary compressed format. | |
18 | Applications can still capture and save the data in the compressed | |
19 | format, saving much disk space, and later use a codec to convert the | |
20 | images to the X Windows screen format when the video is to be displayed. | |
21 | ||
22 | Even so, ultimately, some standard formats are needed, so the V4L2 | |
23 | specification would not be complete without well-defined standard | |
24 | formats. | |
25 | ||
26 | The V4L2 standard formats are mainly uncompressed formats. The pixels | |
27 | are always arranged in memory from left to right, and from top to | |
28 | bottom. The first byte of data in the image buffer is always for the | |
29 | leftmost pixel of the topmost row. Following that is the pixel | |
30 | immediately to its right, and so on until the end of the top row of | |
31 | pixels. Following the rightmost pixel of the row there may be zero or | |
32 | more bytes of padding to guarantee that each row of pixel data has a | |
33 | certain alignment. Following the pad bytes, if any, is data for the | |
34 | leftmost pixel of the second row from the top, and so on. The last row | |
35 | has just as many pad bytes after it as the other rows. | |
36 | ||
37 | In V4L2 each format has an identifier which looks like ``PIX_FMT_XXX``, | |
38 | defined in the :ref:`videodev2.h <videodev>` header file. These | |
39 | identifiers represent | |
40 | :ref:`four character (FourCC) codes <v4l2-fourcc>` which are also | |
41 | listed below, however they are not the same as those used in the Windows | |
42 | world. | |
43 | ||
44 | For some formats, data is stored in separate, discontiguous memory | |
45 | buffers. Those formats are identified by a separate set of FourCC codes | |
5f4c1385 MCC |
46 | and are referred to as "multi-planar formats". For example, a |
47 | :ref:`YUV422 <V4L2-PIX-FMT-YUV422M>` frame is normally stored in one | |
48 | memory buffer, but it can also be placed in two or three separate | |
49 | buffers, with Y component in one buffer and CbCr components in another | |
50 | in the 2-planar version or with each component in its own buffer in the | |
51 | 3-planar case. Those sub-buffers are referred to as "*planes*". |