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