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