Commit 579d76de authored by Luca Ceresoli's avatar Luca Ceresoli Committed by Mauro Carvalho Chehab
Browse files

media: docs: clarify relationship between crop and selection APIs 



Having two somewhat similar and largely overlapping APIs is confusing,
especially since the older one appears in the docs before the newer
and most featureful counterpart.

Clarify all of this in several ways:
 - swap the two sections
 - give a name to the two APIs in the section names
 - add a note at the beginning of the CROP API section
 - update note about VIDIOC_CROPCAP

Also remove a note that is incorrect (correct wording is in
vidioc-cropcap.rst).

Signed-off-by: default avatarLuca Ceresoli <luca@lucaceresoli.net>
Signed-off-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
parent e81ff408

Documentation/media/uapi/v4l/common.rst

+1 −1
Original line number Diff line number Diff line
@@ -41,6 +41,6 @@ applicable to all devices. 
    extended-controls

    format

    planar-apis

    crop

    selection-api

    crop

    streaming-par

Documentation/media/uapi/v4l/crop.rst

+15 −7
Original line number Diff line number Diff line
@@ -2,9 +2,18 @@ 


.. _crop:



*************************************

Image Cropping, Insertion and Scaling

*************************************

*****************************************************

Image Cropping, Insertion and Scaling -- the CROP API

*****************************************************



.. note::



   The CROP API is mostly superseded by the newer :ref:`SELECTION API

   <selection-api>`. The new API should be preferred in most cases,

   with the exception of pixel aspect ratio detection, which is

   implemented by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` and has no

   equivalent in the SELECTION API. See :ref:`selection-vs-crop` for a

   comparison of the two APIs.



Some video capture devices can sample a subsection of the picture and

shrink or enlarge it to an image of arbitrary size. We call these
@@ -42,10 +51,9 @@ where applicable) will be fixed in this case. 


.. note::



   All capture and output devices must support the

   :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl such that applications

   can determine if scaling takes place.



   All capture and output devices that support the CROP or SELECTION

   API will also support the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`

   ioctl.



Cropping Structures

===================

Documentation/media/uapi/v4l/selection-api-005.rst

+2 −0
Original line number Diff line number Diff line 
.. -*- coding: utf-8; mode: rst -*-



.. _selection-vs-crop:



********************************

Comparison with old cropping API

********************************

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

+2 −2
Original line number Diff line number Diff line
@@ -2,8 +2,8 @@ 


.. _selection-api:



API for cropping, composing and scaling

=======================================

Cropping, composing and scaling -- the SELECTION API

====================================================





.. toctree::

CRA Git | Maintained and supported by SUSTech CRA and CCSE