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