1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/media/uapi/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _selection-vs-crop:
11
12********************************
13Comparison with old cropping API
14********************************
15
16The selection API was introduced to cope with deficiencies of the
17older :ref:`CROP API <crop>`, that was designed to control simple
18capture devices. Later the cropping API was adopted by video output
19drivers. The ioctls are used to select a part of the display were the
20video signal is inserted. It should be considered as an API abuse
21because the described operation is actually the composing. The
22selection API makes a clear distinction between composing and cropping
23operations by setting the appropriate targets.
24
25The CROP API lacks any support for composing to and cropping from an
26image inside a memory buffer. The application could configure a
27capture device to fill only a part of an image by abusing V4L2
28API. Cropping a smaller image from a larger one is achieved by setting
29the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`.
30Introducing an image offsets could be done by modifying field
31``m_userptr`` at struct :c:type:`v4l2_buffer` before calling
32:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided
33because they are not portable (endianness), and do not work for
34macroblock and Bayer formats and mmap buffers.
35
36The selection API deals with configuration of buffer
37cropping/composing in a clear, intuitive and portable way. Next, with
38the selection API the concepts of the padded target and constraints
39flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct
40:c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no
41way to extend their functionality. The new struct
42:c:type:`v4l2_selection` provides a lot of place for future
43extensions.
44
45Driver developers are encouraged to implement only selection API. The
46former cropping API would be simulated using the new one.
47