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