diff options
author | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2016-07-08 11:40:06 -0300 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2016-07-08 11:59:40 -0300 |
commit | 60c2820d0f6d3497975b6488e2599f8f611d8b95 (patch) | |
tree | b3b03707c6438ea9b99cc57e847ebf517f968ab1 /Documentation/media/uapi/v4l/selection-api-005.rst | |
parent | a97369b5e21ea9b8b5fef7c0f4f48bbe60c07ca3 (diff) | |
download | op-kernel-dev-60c2820d0f6d3497975b6488e2599f8f611d8b95.zip op-kernel-dev-60c2820d0f6d3497975b6488e2599f8f611d8b95.tar.gz |
doc_rst: rename the media Sphinx suff to Documentation/media
The name of the subsystem is "media", and not "linux_tv". Also,
as we plan to add other stuff there in the future, let's
rename also the media uAPI book to media_uapi, to make it
clearer.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'Documentation/media/uapi/v4l/selection-api-005.rst')
-rw-r--r-- | Documentation/media/uapi/v4l/selection-api-005.rst | 34 |
1 files changed, 34 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/selection-api-005.rst b/Documentation/media/uapi/v4l/selection-api-005.rst new file mode 100644 index 0000000..94731a1 --- /dev/null +++ b/Documentation/media/uapi/v4l/selection-api-005.rst @@ -0,0 +1,34 @@ +.. -*- 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 +:ref:`v4l2_pix_format <v4l2-pix-format>`. +Introducing an image offsets could be done by modifying field ``m_userptr`` +at struct +:ref:`v4l2_buffer <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 :ref:`v4l2_crop <v4l2-crop>` +and struct :ref:`v4l2_cropcap <v4l2-cropcap>` have no reserved +fields. Therefore there is no way to extend their functionality. The new +struct :ref:`v4l2_selection <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. |