Orange Pi5 kernel

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