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@xxxxxxxxxxxxxxxx> > Based on info from: Hans Verkuil <hverkuil@xxxxxxxxx> > Cc: Hans Verkuil <hverkuil@xxxxxxxxx> > --- > 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. Regards, Hans > - > > Cropping Structures > =================== > diff --git a/Documentation/media/uapi/v4l/selection-api-005.rst b/Documentation/media/uapi/v4l/selection-api-005.rst > index 5b47a28ac6d7..2ad30a49184f 100644 > --- a/Documentation/media/uapi/v4l/selection-api-005.rst > +++ b/Documentation/media/uapi/v4l/selection-api-005.rst > @@ -1,5 +1,7 @@ > .. -*- coding: utf-8; mode: rst -*- > > +.. _selection-vs-crop: > + > ******************************** > Comparison with old cropping API > ******************************** > diff --git a/Documentation/media/uapi/v4l/selection-api.rst b/Documentation/media/uapi/v4l/selection-api.rst > index 81ea52d785b9..e4e623824b30 100644 > --- a/Documentation/media/uapi/v4l/selection-api.rst > +++ b/Documentation/media/uapi/v4l/selection-api.rst > @@ -2,8 +2,8 @@ > > .. _selection-api: > > -API for cropping, composing and scaling > -======================================= > +Cropping, composing and scaling -- the SELECTION API > +==================================================== > > > .. toctree:: >
