xiaomi-sm8450/android_kernel_xiaomi_sm8450
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

media: docs: selection: improve formatting

Browse Source 
Split section "Comparison with old cropping API" in paragraphs for
easier reading and improve visible links text.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
This commit is contained in:
Luca Ceresoli
2018-05-14 07:27:26 -04:00
committed by Mauro Carvalho Chehab
parent ff9273f5b8
commit 119e30d395
1 changed files with 29 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -6,31 +6,34 @@
Comparison with old cropping API Comparison with old cropping API
******************************** ********************************
The selection API was introduced to cope with deficiencies of previous The selection API was introduced to cope with deficiencies of the
:ref:`API <crop>`, that was designed to control simple capture older :ref:`CROP API <crop>`, that was designed to control simple
devices. Later the cropping API was adopted by video output drivers. The capture devices. Later the cropping API was adopted by video output
ioctls are used to select a part of the display were the video signal is drivers. The ioctls are used to select a part of the display were the
inserted. It should be considered as an API abuse because the described video signal is inserted. It should be considered as an API abuse
operation is actually the composing. The selection API makes a clear because the described operation is actually the composing. The
distinction between composing and cropping operations by setting the selection API makes a clear distinction between composing and cropping
appropriate targets. The V4L2 API lacks any support for composing to and operations by setting the appropriate targets.
cropping from an image inside a memory buffer. The application could
configure a capture device to fill only a part of an image by abusing The V4L2 API lacks any support for composing to and cropping from an
V4L2 API. Cropping a smaller image from a larger one is achieved by image inside a memory buffer. The application could configure a
setting the field ``bytesperline`` at struct capture device to fill only a part of an image by abusing V4L2
:c:type:`v4l2_pix_format`. API. Cropping a smaller image from a larger one is achieved by setting
Introducing an image offsets could be done by modifying field ``m_userptr`` the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`.
at struct Introducing an image offsets could be done by modifying field
:c:type:`v4l2_buffer` before calling ``m_userptr`` at struct :c:type:`v4l2_buffer` before calling
:ref:`VIDIOC_QBUF`. Those operations should be avoided because they are not :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided
portable (endianness), and do not work for macroblock and Bayer formats because they are not portable (endianness), and do not work for
and mmap buffers. The selection API deals with configuration of buffer macroblock and Bayer formats and mmap buffers.
The selection API deals with configuration of buffer
cropping/composing in a clear, intuitive and portable way. Next, with cropping/composing in a clear, intuitive and portable way. Next, with
the selection API the concepts of the padded target and constraints the selection API the concepts of the padded target and constraints
flags are introduced. Finally, struct :c:type:`v4l2_crop` flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct
and struct :c:type:`v4l2_cropcap` have no reserved :c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no
fields. Therefore there is no way to extend their functionality. The new way to extend their functionality. The new struct
struct :c:type:`v4l2_selection` provides a lot of place :c:type:`v4l2_selection` provides a lot of place for future
for future extensions. Driver developers are encouraged to implement extensions.
only selection API. The former cropping API would be simulated using the
new one. Driver developers are encouraged to implement only selection API. The
former cropping API would be simulated using the new one.