18c2ecf20Sopenharmony_ci.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 28c2ecf20Sopenharmony_ci 38c2ecf20Sopenharmony_ci.. _selection-vs-crop: 48c2ecf20Sopenharmony_ci 58c2ecf20Sopenharmony_ci******************************** 68c2ecf20Sopenharmony_ciComparison with old cropping API 78c2ecf20Sopenharmony_ci******************************** 88c2ecf20Sopenharmony_ci 98c2ecf20Sopenharmony_ciThe selection API was introduced to cope with deficiencies of the 108c2ecf20Sopenharmony_ciolder :ref:`CROP API <crop>`, that was designed to control simple 118c2ecf20Sopenharmony_cicapture devices. Later the cropping API was adopted by video output 128c2ecf20Sopenharmony_cidrivers. The ioctls are used to select a part of the display were the 138c2ecf20Sopenharmony_civideo signal is inserted. It should be considered as an API abuse 148c2ecf20Sopenharmony_cibecause the described operation is actually the composing. The 158c2ecf20Sopenharmony_ciselection API makes a clear distinction between composing and cropping 168c2ecf20Sopenharmony_cioperations by setting the appropriate targets. 178c2ecf20Sopenharmony_ci 188c2ecf20Sopenharmony_ciThe CROP API lacks any support for composing to and cropping from an 198c2ecf20Sopenharmony_ciimage inside a memory buffer. The application could configure a 208c2ecf20Sopenharmony_cicapture device to fill only a part of an image by abusing V4L2 218c2ecf20Sopenharmony_ciAPI. Cropping a smaller image from a larger one is achieved by setting 228c2ecf20Sopenharmony_cithe field ``bytesperline`` at struct :c:type:`v4l2_pix_format`. 238c2ecf20Sopenharmony_ciIntroducing an image offsets could be done by modifying field 248c2ecf20Sopenharmony_ci``m_userptr`` at struct :c:type:`v4l2_buffer` before calling 258c2ecf20Sopenharmony_ci:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided 268c2ecf20Sopenharmony_cibecause they are not portable (endianness), and do not work for 278c2ecf20Sopenharmony_cimacroblock and Bayer formats and mmap buffers. 288c2ecf20Sopenharmony_ci 298c2ecf20Sopenharmony_ciThe selection API deals with configuration of buffer 308c2ecf20Sopenharmony_cicropping/composing in a clear, intuitive and portable way. Next, with 318c2ecf20Sopenharmony_cithe selection API the concepts of the padded target and constraints 328c2ecf20Sopenharmony_ciflags are introduced. Finally, struct :c:type:`v4l2_crop` and struct 338c2ecf20Sopenharmony_ci:c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no 348c2ecf20Sopenharmony_ciway to extend their functionality. The new struct 358c2ecf20Sopenharmony_ci:c:type:`v4l2_selection` provides a lot of place for future 368c2ecf20Sopenharmony_ciextensions. 378c2ecf20Sopenharmony_ci 388c2ecf20Sopenharmony_ciDriver developers are encouraged to implement only selection API. The 398c2ecf20Sopenharmony_ciformer cropping API would be simulated using the new one. 40