18c2ecf20Sopenharmony_ci.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 28c2ecf20Sopenharmony_ci 38c2ecf20Sopenharmony_ci********************** 48c2ecf20Sopenharmony_ciStandard Image Formats 58c2ecf20Sopenharmony_ci********************** 68c2ecf20Sopenharmony_ci 78c2ecf20Sopenharmony_ciIn order to exchange images between drivers and applications, it is 88c2ecf20Sopenharmony_cinecessary to have standard image data formats which both sides will 98c2ecf20Sopenharmony_ciinterpret the same way. V4L2 includes several such formats, and this 108c2ecf20Sopenharmony_cisection is intended to be an unambiguous specification of the standard 118c2ecf20Sopenharmony_ciimage data formats in V4L2. 128c2ecf20Sopenharmony_ci 138c2ecf20Sopenharmony_ciV4L2 drivers are not limited to these formats, however. Driver-specific 148c2ecf20Sopenharmony_ciformats are possible. In that case the application may depend on a codec 158c2ecf20Sopenharmony_cito convert images to one of the standard formats when needed. But the 168c2ecf20Sopenharmony_cidata can still be stored and retrieved in the proprietary format. For 178c2ecf20Sopenharmony_ciexample, a device may support a proprietary compressed format. 188c2ecf20Sopenharmony_ciApplications can still capture and save the data in the compressed 198c2ecf20Sopenharmony_ciformat, saving much disk space, and later use a codec to convert the 208c2ecf20Sopenharmony_ciimages to the X Windows screen format when the video is to be displayed. 218c2ecf20Sopenharmony_ci 228c2ecf20Sopenharmony_ciEven so, ultimately, some standard formats are needed, so the V4L2 238c2ecf20Sopenharmony_cispecification would not be complete without well-defined standard 248c2ecf20Sopenharmony_ciformats. 258c2ecf20Sopenharmony_ci 268c2ecf20Sopenharmony_ciThe V4L2 standard formats are mainly uncompressed formats. The pixels 278c2ecf20Sopenharmony_ciare always arranged in memory from left to right, and from top to 288c2ecf20Sopenharmony_cibottom. The first byte of data in the image buffer is always for the 298c2ecf20Sopenharmony_cileftmost pixel of the topmost row. Following that is the pixel 308c2ecf20Sopenharmony_ciimmediately to its right, and so on until the end of the top row of 318c2ecf20Sopenharmony_cipixels. Following the rightmost pixel of the row there may be zero or 328c2ecf20Sopenharmony_cimore bytes of padding to guarantee that each row of pixel data has a 338c2ecf20Sopenharmony_cicertain alignment. Following the pad bytes, if any, is data for the 348c2ecf20Sopenharmony_cileftmost pixel of the second row from the top, and so on. The last row 358c2ecf20Sopenharmony_cihas just as many pad bytes after it as the other rows. 368c2ecf20Sopenharmony_ci 378c2ecf20Sopenharmony_ciIn V4L2 each format has an identifier which looks like ``PIX_FMT_XXX``, 388c2ecf20Sopenharmony_cidefined in the :ref:`videodev2.h <videodev>` header file. These 398c2ecf20Sopenharmony_ciidentifiers represent 408c2ecf20Sopenharmony_ci:ref:`four character (FourCC) codes <v4l2-fourcc>` which are also 418c2ecf20Sopenharmony_cilisted below, however they are not the same as those used in the Windows 428c2ecf20Sopenharmony_ciworld. 438c2ecf20Sopenharmony_ci 448c2ecf20Sopenharmony_ciFor some formats, data is stored in separate, discontiguous memory 458c2ecf20Sopenharmony_cibuffers. Those formats are identified by a separate set of FourCC codes 468c2ecf20Sopenharmony_ciand are referred to as "multi-planar formats". For example, a 478c2ecf20Sopenharmony_ci:ref:`YUV422 <V4L2-PIX-FMT-YUV422M>` frame is normally stored in one 488c2ecf20Sopenharmony_cimemory buffer, but it can also be placed in two or three separate 498c2ecf20Sopenharmony_cibuffers, with Y component in one buffer and CbCr components in another 508c2ecf20Sopenharmony_ciin the 2-planar version or with each component in its own buffer in the 518c2ecf20Sopenharmony_ci3-planar case. Those sub-buffers are referred to as "*planes*". 52