lkml.org 
[lkml]   [2018]   [May]   [14]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH 2/5] media: docs: clarify relationship between crop and selection APIs
From
Date
Hi Hans,

thanks for the review.

On 13/05/2018 11:12, Hans Verkuil wrote:
> On 04/03/2018 11:15 PM, Luca Ceresoli wrote:
>> 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
>>
>> Also remove a note that is incorrect (correct wording is in
>> vidioc-cropcap.rst).
>>
>> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
>> Based on info from: Hans Verkuil <hverkuil@xs4all.nl>
>> Cc: Hans Verkuil <hverkuil@xs4all.nl>
>> ---
>> Documentation/media/uapi/v4l/common.rst | 2 +-
>> Documentation/media/uapi/v4l/crop.rst | 21 ++++++++++++---------
>> Documentation/media/uapi/v4l/selection-api-005.rst | 2 ++
>> Documentation/media/uapi/v4l/selection-api.rst | 4 ++--
>> 4 files changed, 17 insertions(+), 12 deletions(-)
>>
>> diff --git a/Documentation/media/uapi/v4l/common.rst b/Documentation/media/uapi/v4l/common.rst
>> index 13f2ed3fc5a6..5f93e71122ef 100644
>> --- a/Documentation/media/uapi/v4l/common.rst
>> +++ b/Documentation/media/uapi/v4l/common.rst
>> @@ -41,6 +41,6 @@ applicable to all devices.
>> extended-controls
>> format
>> planar-apis
>> - crop
>> selection-api
>> + crop
>> streaming-par
>> diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst
>> index 182565b9ace4..83fa16eb347e 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
>> + <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
>> @@ -40,12 +49,6 @@ support scaling or the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
>> :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls. Their size (and position
>> 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.
>
> This note should be rewritten, not deleted:
>
> All capture and output devices that support the CROP or SELECTION API
> will also support the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl.

I don't remember exactly the reationale for this removal, perhaps it's
that I added a note above with similar content. But reading that again
now I realize the added not does not clearly state "VIDIOC_CROPCAP is
mandatory".

Thus I added the updated note to v2 as you suggested.

Bye,
--
Luca

\
 
 \ /
  Last update: 2018-05-14 13:25    [W:0.091 / U:1.772 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site