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