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