| Message ID | 1522790146-16061-2-git-send-email-luca@lucaceresoli.net (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
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. 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:: >
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,
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. - 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::
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(-)