0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _selection-vs-crop:
0004
0005 ********************************
0006 Comparison with old cropping API
0007 ********************************
0008
0009 The selection API was introduced to cope with deficiencies of the
0010 older :ref:`CROP API <crop>`, that was designed to control simple
0011 capture devices. Later the cropping API was adopted by video output
0012 drivers. The ioctls are used to select a part of the display were the
0013 video signal is inserted. It should be considered as an API abuse
0014 because the described operation is actually the composing. The
0015 selection API makes a clear distinction between composing and cropping
0016 operations by setting the appropriate targets.
0017
0018 The CROP API lacks any support for composing to and cropping from an
0019 image inside a memory buffer. The application could configure a
0020 capture device to fill only a part of an image by abusing V4L2
0021 API. Cropping a smaller image from a larger one is achieved by setting
0022 the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`.
0023 Introducing an image offsets could be done by modifying field
0024 ``m_userptr`` at struct :c:type:`v4l2_buffer` before calling
0025 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided
0026 because they are not portable (endianness), and do not work for
0027 macroblock and Bayer formats and mmap buffers.
0028
0029 The selection API deals with configuration of buffer
0030 cropping/composing in a clear, intuitive and portable way. Next, with
0031 the selection API the concepts of the padded target and constraints
0032 flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct
0033 :c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no
0034 way to extend their functionality. The new struct
0035 :c:type:`v4l2_selection` provides a lot of place for future
0036 extensions.
0037
0038 Driver developers are encouraged to implement only selection API. The
0039 former cropping API would be simulated using the new one.
