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