Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 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 |
| 18 | setting the field struct |
| 19 | :ref:`v4l2_pix_format <v4l2-pix-format>```::bytesperline``. |
| 20 | Introducing an image offsets could be done by modifying field struct |
| 21 | :ref:`v4l2_buffer <v4l2-buffer>```::m_userptr`` before calling |
Mauro Carvalho Chehab | 2212ff2 | 2016-07-01 14:33:56 -0300 | [diff] [blame^] | 22 | :ref:`VIDIOC_QBUF`. Those operations should be avoided because they are not |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 23 | portable (endianness), and do not work for macroblock and Bayer formats |
| 24 | and mmap buffers. The selection API deals with configuration of buffer |
| 25 | cropping/composing in a clear, intuitive and portable way. Next, with |
| 26 | the selection API the concepts of the padded target and constraints |
| 27 | flags are introduced. Finally, struct :ref:`v4l2_crop <v4l2-crop>` |
| 28 | and struct :ref:`v4l2_cropcap <v4l2-cropcap>` have no reserved |
| 29 | fields. Therefore there is no way to extend their functionality. The new |
| 30 | struct :ref:`v4l2_selection <v4l2-selection>` provides a lot of place |
| 31 | for future extensions. Driver developers are encouraged to implement |
| 32 | only selection API. The former cropping API would be simulated using the |
| 33 | new one. |
| 34 | |
| 35 | |
| 36 | .. ------------------------------------------------------------------------------ |
| 37 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 38 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 39 | .. from the linux kernel, refer to: |
| 40 | .. |
| 41 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 42 | .. ------------------------------------------------------------------------------ |