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

   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 ********************************
  13 Comparison with old cropping API
  14 ********************************
  15
  16 The selection API was introduced to cope with deficiencies of the
  17 older :ref:`CROP API <crop>`, that was designed to control simple
  18 capture devices. Later the cropping API was adopted by video output
  19 drivers. The ioctls are used to select a part of the display were the
  20 video signal is inserted. It should be considered as an API abuse
  21 because the described operation is actually the composing. The
  22 selection API makes a clear distinction between composing and cropping
  23 operations by setting the appropriate targets.
  24
  25 The CROP API lacks any support for composing to and cropping from an
  26 image inside a memory buffer. The application could configure a
  27 capture device to fill only a part of an image by abusing V4L2
  28 API. Cropping a smaller image from a larger one is achieved by setting
  29 the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`.
  30 Introducing 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
  33 because they are not portable (endianness), and do not work for
  34 macroblock and Bayer formats and mmap buffers.
  35
  36 The selection API deals with configuration of buffer
  37 cropping/composing in a clear, intuitive and portable way. Next, with
  38 the selection API the concepts of the padded target and constraints
  39 flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct
  40 :c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no
  41 way to extend their functionality. The new struct
  42 :c:type:`v4l2_selection` provides a lot of place for future
  43 extensions.
  44
  45 Driver developers are encouraged to implement only selection API. The
  46 former cropping API would be simulated using the new one.