mirror of
https://github.com/AuxXxilium/linux_dsm_epyc7002.git
synced 2024-12-21 08:17:42 +07:00
e8be7e97e6
instead of declaring the uAPI structs using usual refs, e. g.: .. _foo-struct: Use the C domain way: .. c:type:: foo_struct This way, the kAPI documentation can use cross-references to point to the uAPI symbols. That solves about ~100 undefined warnings like: WARNING: c:type reference target not found: foo_struct Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
35 lines
1.8 KiB
ReStructuredText
35 lines
1.8 KiB
ReStructuredText
.. -*- coding: utf-8; mode: rst -*-
|
|
|
|
********************************
|
|
Comparison with old cropping API
|
|
********************************
|
|
|
|
The selection API was introduced to cope with deficiencies of previous
|
|
:ref:`API <crop>`, that was designed to control simple capture
|
|
devices. Later the cropping API was adopted by video output drivers. The
|
|
ioctls are used to select a part of the display were the video signal is
|
|
inserted. It should be considered as an API abuse because the described
|
|
operation is actually the composing. The selection API makes a clear
|
|
distinction between composing and cropping operations by setting the
|
|
appropriate targets. The V4L2 API lacks any support for composing to and
|
|
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
|
|
V4L2 API. Cropping a smaller image from a larger one is achieved by
|
|
setting the field ``bytesperline`` at struct
|
|
:c:type:`v4l2_pix_format`.
|
|
Introducing an image offsets could be done by modifying field ``m_userptr``
|
|
at struct
|
|
:c:type:`v4l2_buffer` before calling
|
|
:ref:`VIDIOC_QBUF`. Those operations should be avoided because they are not
|
|
portable (endianness), and do not work for 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
|
|
the selection API the concepts of the padded target and constraints
|
|
flags are introduced. Finally, struct :c:type:`v4l2_crop`
|
|
and struct :c:type:`v4l2_cropcap` have no reserved
|
|
fields. Therefore there is no way to extend their functionality. The new
|
|
struct :c:type:`v4l2_selection` provides a lot of place
|
|
for future extensions. Driver developers are encouraged to implement
|
|
only selection API. The former cropping API would be simulated using the
|
|
new one.
|