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) .. _selection-vs-crop:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) ********************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) Comparison with old cropping API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) ********************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) The selection API was introduced to cope with deficiencies of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) older :ref:`CROP API <crop>`, that was designed to control simple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) capture devices. Later the cropping API was adopted by video output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) drivers. The ioctls are used to select a part of the display were the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) video signal is inserted. It should be considered as an API abuse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) because the described operation is actually the composing. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) selection API makes a clear distinction between composing and cropping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) operations by setting the appropriate targets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) The CROP API lacks any support for composing to and cropping from an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) image inside a memory buffer. The application could configure a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) capture device to fill only a part of an image by abusing V4L2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) API. Cropping a smaller image from a larger one is achieved by setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Introducing an image offsets could be done by modifying field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ``m_userptr`` at struct :c:type:`v4l2_buffer` before calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) because they are not portable (endianness), and do not work for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) macroblock and Bayer formats and mmap buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) The selection API deals with configuration of buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) cropping/composing in a clear, intuitive and portable way. Next, with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) the selection API the concepts of the padded target and constraints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) :c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) way to extend their functionality. The new struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) :c:type:`v4l2_selection` provides a lot of place for future
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) extensions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Driver developers are encouraged to implement only selection API. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) former cropping API would be simulated using the new one.