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