1*059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 254f38fcaSMauro Carvalho Chehab 354f38fcaSMauro Carvalho Chehab.. _selection-vs-crop: 454f38fcaSMauro Carvalho Chehab 554f38fcaSMauro Carvalho Chehab******************************** 654f38fcaSMauro Carvalho ChehabComparison with old cropping API 754f38fcaSMauro Carvalho Chehab******************************** 854f38fcaSMauro Carvalho Chehab 954f38fcaSMauro Carvalho ChehabThe selection API was introduced to cope with deficiencies of the 1054f38fcaSMauro Carvalho Chehabolder :ref:`CROP API <crop>`, that was designed to control simple 1154f38fcaSMauro Carvalho Chehabcapture devices. Later the cropping API was adopted by video output 1254f38fcaSMauro Carvalho Chehabdrivers. The ioctls are used to select a part of the display were the 1354f38fcaSMauro Carvalho Chehabvideo signal is inserted. It should be considered as an API abuse 1454f38fcaSMauro Carvalho Chehabbecause the described operation is actually the composing. The 1554f38fcaSMauro Carvalho Chehabselection API makes a clear distinction between composing and cropping 1654f38fcaSMauro Carvalho Chehaboperations by setting the appropriate targets. 1754f38fcaSMauro Carvalho Chehab 1854f38fcaSMauro Carvalho ChehabThe CROP API lacks any support for composing to and cropping from an 1954f38fcaSMauro Carvalho Chehabimage inside a memory buffer. The application could configure a 2054f38fcaSMauro Carvalho Chehabcapture device to fill only a part of an image by abusing V4L2 2154f38fcaSMauro Carvalho ChehabAPI. Cropping a smaller image from a larger one is achieved by setting 2254f38fcaSMauro Carvalho Chehabthe field ``bytesperline`` at struct :c:type:`v4l2_pix_format`. 2354f38fcaSMauro Carvalho ChehabIntroducing an image offsets could be done by modifying field 2454f38fcaSMauro Carvalho Chehab``m_userptr`` at struct :c:type:`v4l2_buffer` before calling 2554f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided 2654f38fcaSMauro Carvalho Chehabbecause they are not portable (endianness), and do not work for 2754f38fcaSMauro Carvalho Chehabmacroblock and Bayer formats and mmap buffers. 2854f38fcaSMauro Carvalho Chehab 2954f38fcaSMauro Carvalho ChehabThe selection API deals with configuration of buffer 3054f38fcaSMauro Carvalho Chehabcropping/composing in a clear, intuitive and portable way. Next, with 3154f38fcaSMauro Carvalho Chehabthe selection API the concepts of the padded target and constraints 3254f38fcaSMauro Carvalho Chehabflags are introduced. Finally, struct :c:type:`v4l2_crop` and struct 3354f38fcaSMauro Carvalho Chehab:c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no 3454f38fcaSMauro Carvalho Chehabway to extend their functionality. The new struct 3554f38fcaSMauro Carvalho Chehab:c:type:`v4l2_selection` provides a lot of place for future 3654f38fcaSMauro Carvalho Chehabextensions. 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho ChehabDriver developers are encouraged to implement only selection API. The 3954f38fcaSMauro Carvalho Chehabformer cropping API would be simulated using the new one. 40