From 579d76deb1b106af5987670389604381c31116eb Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Mon, 14 May 2018 07:27:24 -0400 Subject: 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: Luca Ceresoli Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/crop.rst | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) (limited to 'Documentation/media/uapi/v4l/crop.rst') diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst index 182565b9ace49..45e8a895a3202 100644 --- a/Documentation/media/uapi/v4l/crop.rst +++ b/Documentation/media/uapi/v4l/crop.rst @@ -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 + `. The new API should be preferred in most cases, + with the exception of pixel aspect ratio detection, which is + implemented by :ref:`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 ` 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 ` + ioctl. Cropping Structures =================== -- cgit v1.2.3