Debian Codegraph @

Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst

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