162306a36Sopenharmony_ci.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 262306a36Sopenharmony_ci 362306a36Sopenharmony_ci.. _selection-vs-crop: 462306a36Sopenharmony_ci 562306a36Sopenharmony_ci******************************** 662306a36Sopenharmony_ciComparison with old cropping API 762306a36Sopenharmony_ci******************************** 862306a36Sopenharmony_ci 962306a36Sopenharmony_ciThe selection API was introduced to cope with deficiencies of the 1062306a36Sopenharmony_ciolder :ref:`CROP API <crop>`, that was designed to control simple 1162306a36Sopenharmony_cicapture devices. Later the cropping API was adopted by video output 1262306a36Sopenharmony_cidrivers. The ioctls are used to select a part of the display were the 1362306a36Sopenharmony_civideo signal is inserted. It should be considered as an API abuse 1462306a36Sopenharmony_cibecause the described operation is actually the composing. The 1562306a36Sopenharmony_ciselection API makes a clear distinction between composing and cropping 1662306a36Sopenharmony_cioperations by setting the appropriate targets. 1762306a36Sopenharmony_ci 1862306a36Sopenharmony_ciThe CROP API lacks any support for composing to and cropping from an 1962306a36Sopenharmony_ciimage inside a memory buffer. The application could configure a 2062306a36Sopenharmony_cicapture device to fill only a part of an image by abusing V4L2 2162306a36Sopenharmony_ciAPI. Cropping a smaller image from a larger one is achieved by setting 2262306a36Sopenharmony_cithe field ``bytesperline`` at struct :c:type:`v4l2_pix_format`. 2362306a36Sopenharmony_ciIntroducing an image offsets could be done by modifying field 2462306a36Sopenharmony_ci``m_userptr`` at struct :c:type:`v4l2_buffer` before calling 2562306a36Sopenharmony_ci:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided 2662306a36Sopenharmony_cibecause they are not portable (endianness), and do not work for 2762306a36Sopenharmony_cimacroblock and Bayer formats and mmap buffers. 2862306a36Sopenharmony_ci 2962306a36Sopenharmony_ciThe selection API deals with configuration of buffer 3062306a36Sopenharmony_cicropping/composing in a clear, intuitive and portable way. Next, with 3162306a36Sopenharmony_cithe selection API the concepts of the padded target and constraints 3262306a36Sopenharmony_ciflags are introduced. Finally, struct :c:type:`v4l2_crop` and struct 3362306a36Sopenharmony_ci:c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no 3462306a36Sopenharmony_ciway to extend their functionality. The new struct 3562306a36Sopenharmony_ci:c:type:`v4l2_selection` provides a lot of place for future 3662306a36Sopenharmony_ciextensions. 3762306a36Sopenharmony_ci 3862306a36Sopenharmony_ciDriver developers are encouraged to implement only selection API. The 3962306a36Sopenharmony_ciformer cropping API would be simulated using the new one. 40