154f38fcaSMauro Carvalho Chehab.. Permission is granted to copy, distribute and/or modify this
254f38fcaSMauro Carvalho Chehab.. document under the terms of the GNU Free Documentation License,
354f38fcaSMauro Carvalho Chehab.. Version 1.1 or any later version published by the Free Software
454f38fcaSMauro Carvalho Chehab.. Foundation, with no Invariant Sections, no Front-Cover Texts
554f38fcaSMauro Carvalho Chehab.. and no Back-Cover Texts. A copy of the license is included at
654f38fcaSMauro Carvalho Chehab.. Documentation/userspace-api/media/fdl-appendix.rst.
754f38fcaSMauro Carvalho Chehab..
854f38fcaSMauro Carvalho Chehab.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
954f38fcaSMauro Carvalho Chehab
1054f38fcaSMauro Carvalho Chehab**********************
1154f38fcaSMauro Carvalho ChehabStandard Image Formats
1254f38fcaSMauro Carvalho Chehab**********************
1354f38fcaSMauro Carvalho Chehab
1454f38fcaSMauro Carvalho ChehabIn order to exchange images between drivers and applications, it is
1554f38fcaSMauro Carvalho Chehabnecessary to have standard image data formats which both sides will
1654f38fcaSMauro Carvalho Chehabinterpret the same way. V4L2 includes several such formats, and this
1754f38fcaSMauro Carvalho Chehabsection is intended to be an unambiguous specification of the standard
1854f38fcaSMauro Carvalho Chehabimage data formats in V4L2.
1954f38fcaSMauro Carvalho Chehab
2054f38fcaSMauro Carvalho ChehabV4L2 drivers are not limited to these formats, however. Driver-specific
2154f38fcaSMauro Carvalho Chehabformats are possible. In that case the application may depend on a codec
2254f38fcaSMauro Carvalho Chehabto convert images to one of the standard formats when needed. But the
2354f38fcaSMauro Carvalho Chehabdata can still be stored and retrieved in the proprietary format. For
2454f38fcaSMauro Carvalho Chehabexample, a device may support a proprietary compressed format.
2554f38fcaSMauro Carvalho ChehabApplications can still capture and save the data in the compressed
2654f38fcaSMauro Carvalho Chehabformat, saving much disk space, and later use a codec to convert the
2754f38fcaSMauro Carvalho Chehabimages to the X Windows screen format when the video is to be displayed.
2854f38fcaSMauro Carvalho Chehab
2954f38fcaSMauro Carvalho ChehabEven so, ultimately, some standard formats are needed, so the V4L2
3054f38fcaSMauro Carvalho Chehabspecification would not be complete without well-defined standard
3154f38fcaSMauro Carvalho Chehabformats.
3254f38fcaSMauro Carvalho Chehab
3354f38fcaSMauro Carvalho ChehabThe V4L2 standard formats are mainly uncompressed formats. The pixels
3454f38fcaSMauro Carvalho Chehabare always arranged in memory from left to right, and from top to
3554f38fcaSMauro Carvalho Chehabbottom. The first byte of data in the image buffer is always for the
3654f38fcaSMauro Carvalho Chehableftmost pixel of the topmost row. Following that is the pixel
3754f38fcaSMauro Carvalho Chehabimmediately to its right, and so on until the end of the top row of
3854f38fcaSMauro Carvalho Chehabpixels. Following the rightmost pixel of the row there may be zero or
3954f38fcaSMauro Carvalho Chehabmore bytes of padding to guarantee that each row of pixel data has a
4054f38fcaSMauro Carvalho Chehabcertain alignment. Following the pad bytes, if any, is data for the
4154f38fcaSMauro Carvalho Chehableftmost pixel of the second row from the top, and so on. The last row
4254f38fcaSMauro Carvalho Chehabhas just as many pad bytes after it as the other rows.
4354f38fcaSMauro Carvalho Chehab
4454f38fcaSMauro Carvalho ChehabIn V4L2 each format has an identifier which looks like ``PIX_FMT_XXX``,
4554f38fcaSMauro Carvalho Chehabdefined in the :ref:`videodev2.h <videodev>` header file. These
4654f38fcaSMauro Carvalho Chehabidentifiers represent
4754f38fcaSMauro Carvalho Chehab:ref:`four character (FourCC) codes <v4l2-fourcc>` which are also
4854f38fcaSMauro Carvalho Chehablisted below, however they are not the same as those used in the Windows
4954f38fcaSMauro Carvalho Chehabworld.
5054f38fcaSMauro Carvalho Chehab
5154f38fcaSMauro Carvalho ChehabFor some formats, data is stored in separate, discontiguous memory
5254f38fcaSMauro Carvalho Chehabbuffers. Those formats are identified by a separate set of FourCC codes
5354f38fcaSMauro Carvalho Chehaband are referred to as "multi-planar formats". For example, a
5454f38fcaSMauro Carvalho Chehab:ref:`YUV422 <V4L2-PIX-FMT-YUV422M>` frame is normally stored in one
5554f38fcaSMauro Carvalho Chehabmemory buffer, but it can also be placed in two or three separate
5654f38fcaSMauro Carvalho Chehabbuffers, with Y component in one buffer and CbCr components in another
5754f38fcaSMauro Carvalho Chehabin the 2-planar version or with each component in its own buffer in the
5854f38fcaSMauro Carvalho Chehab3-planar case. Those sub-buffers are referred to as "*planes*".
59