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