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