[PATCH 1/5] media: docs: selection: fix typos

[PATCH 1/5] media: docs: selection: fix typos

[Luca Ceresoli]

Cc: Hans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/media/uapi/v4l/selection-api-004.rst | 2 +-
 Documentation/media/uapi/v4l/selection.svg         | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/media/uapi/v4l/selection-api-004.rst b/Documentation/media/uapi/v4l/selection-api-004.rst
index d782cd5b2117..0a4ddc2d71db 100644
--- a/Documentation/media/uapi/v4l/selection-api-004.rst
+++ b/Documentation/media/uapi/v4l/selection-api-004.rst
@@ -41,7 +41,7 @@ The driver may further adjust the requested size and/or position
 according to hardware limitations.
 
 Each capture device has a default source rectangle, given by the
-``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall over what the
+``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the
 driver writer considers the complete picture. Drivers shall set the
 active crop rectangle to the default when the driver is first loaded,
 but not later.
diff --git a/Documentation/media/uapi/v4l/selection.svg b/Documentation/media/uapi/v4l/selection.svg
index a93e3b59786d..911062bd2844 100644
--- a/Documentation/media/uapi/v4l/selection.svg
+++ b/Documentation/media/uapi/v4l/selection.svg
@@ -1128,11 +1128,11 @@
    </text>
   </g>
   <text transform="matrix(.96106 0 0 1.0405 48.571 195.53)" x="2438.062" y="1368.429" enable-background="new" font-size="50" style="line-height:125%">
-   <tspan x="2438.062" y="1368.429">COMPOSE_BONDS</tspan>
+   <tspan x="2438.062" y="1368.429">COMPOSE_BOUNDS</tspan>
   </text>
   <g font-size="40">
    <text transform="translate(48.571 195.53)" x="8.082" y="1438.896" enable-background="new" style="line-height:125%">
-    <tspan x="8.082" y="1438.896" font-size="50">CROP_BONDS</tspan>
+    <tspan x="8.082" y="1438.896" font-size="50">CROP_BOUNDS</tspan>
    </text>
    <text transform="translate(48.571 195.53)" x="1455.443" y="-26.808" enable-background="new" style="line-height:125%">
     <tspan x="1455.443" y="-26.808" font-size="50">overscan area</tspan>
-- 
2.7.4

[PATCH 2/5] media: docs: clarify relationship between crop and selection APIs

[Luca Ceresoli]

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.
-
 
 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::
-- 
2.7.4

[PATCH 3/5] media: docs: selection: rename files to something meaningful

[Luca Ceresoli]

These files have an automatically-generated numbering. Replaname them
to something that suggests their meaning.

Reported-by: Hans Verkuil <hverkuil@xs4all.nl>
Cc: Hans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 .../{selection-api-004.rst => selection-api-configuration.rst} |  0
 .../v4l/{selection-api-006.rst => selection-api-examples.rst}  |  0
 .../v4l/{selection-api-002.rst => selection-api-intro.rst}     |  0
 .../v4l/{selection-api-003.rst => selection-api-targets.rst}   |  0
 .../{selection-api-005.rst => selection-api-vs-crop-api.rst}   |  0
 Documentation/media/uapi/v4l/selection-api.rst                 | 10 +++++-----
 6 files changed, 5 insertions(+), 5 deletions(-)
 rename Documentation/media/uapi/v4l/{selection-api-004.rst => selection-api-configuration.rst} (100%)
 rename Documentation/media/uapi/v4l/{selection-api-006.rst => selection-api-examples.rst} (100%)
 rename Documentation/media/uapi/v4l/{selection-api-002.rst => selection-api-intro.rst} (100%)
 rename Documentation/media/uapi/v4l/{selection-api-003.rst => selection-api-targets.rst} (100%)
 rename Documentation/media/uapi/v4l/{selection-api-005.rst => selection-api-vs-crop-api.rst} (100%)

diff --git a/Documentation/media/uapi/v4l/selection-api-004.rst b/Documentation/media/uapi/v4l/selection-api-configuration.rst
similarity index 100%
rename from Documentation/media/uapi/v4l/selection-api-004.rst
rename to Documentation/media/uapi/v4l/selection-api-configuration.rst
diff --git a/Documentation/media/uapi/v4l/selection-api-006.rst b/Documentation/media/uapi/v4l/selection-api-examples.rst
similarity index 100%
rename from Documentation/media/uapi/v4l/selection-api-006.rst
rename to Documentation/media/uapi/v4l/selection-api-examples.rst
diff --git a/Documentation/media/uapi/v4l/selection-api-002.rst b/Documentation/media/uapi/v4l/selection-api-intro.rst
similarity index 100%
rename from Documentation/media/uapi/v4l/selection-api-002.rst
rename to Documentation/media/uapi/v4l/selection-api-intro.rst
diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-targets.rst
similarity index 100%
rename from Documentation/media/uapi/v4l/selection-api-003.rst
rename to Documentation/media/uapi/v4l/selection-api-targets.rst
diff --git a/Documentation/media/uapi/v4l/selection-api-005.rst b/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst
similarity index 100%
rename from Documentation/media/uapi/v4l/selection-api-005.rst
rename to Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst
diff --git a/Documentation/media/uapi/v4l/selection-api.rst b/Documentation/media/uapi/v4l/selection-api.rst
index e4e623824b30..390233f704a3 100644
--- a/Documentation/media/uapi/v4l/selection-api.rst
+++ b/Documentation/media/uapi/v4l/selection-api.rst
@@ -9,8 +9,8 @@ Cropping, composing and scaling -- the SELECTION API
 .. toctree::
     :maxdepth: 1
 
-    selection-api-002
-    selection-api-003
-    selection-api-004
-    selection-api-005
-    selection-api-006
+    selection-api-intro.rst
+    selection-api-targets.rst
+    selection-api-configuration.rst
+    selection-api-vs-crop-api.rst
+    selection-api-examples.rst
-- 
2.7.4

[PATCH 4/5] media: docs: selection: improve formatting

[Luca Ceresoli]

Split section "Comparison with old cropping API" in paragraphs for
easier reading and improve visible links text.

Cc: Hans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 .../media/uapi/v4l/selection-api-vs-crop-api.rst   | 55 ++++++++++++----------
 1 file changed, 29 insertions(+), 26 deletions(-)

diff --git a/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst b/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst
index 2ad30a49184f..ba1064a244a0 100644
--- a/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst
+++ b/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst
@@ -6,31 +6,34 @@
 Comparison with old cropping API
 ********************************
 
-The selection API was introduced to cope with deficiencies of previous
-:ref:`API <crop>`, that was designed to control simple capture
-devices. Later the cropping API was adopted by video output drivers. The
-ioctls are used to select a part of the display were the video signal is
-inserted. It should be considered as an API abuse because the described
-operation is actually the composing. The selection API makes a clear
-distinction between composing and cropping operations by setting the
-appropriate targets. The V4L2 API lacks any support for composing to and
-cropping from an image inside a memory buffer. The application could
-configure a capture device to fill only a part of an image by abusing
-V4L2 API. Cropping a smaller image from a larger one is achieved by
-setting the field ``bytesperline`` at struct
-:c:type:`v4l2_pix_format`.
-Introducing an image offsets could be done by modifying field ``m_userptr``
-at struct
-:c:type:`v4l2_buffer` before calling
-:ref:`VIDIOC_QBUF`. Those operations should be avoided because they are not
-portable (endianness), and do not work for macroblock and Bayer formats
-and mmap buffers. The selection API deals with configuration of buffer
+The selection API was introduced to cope with deficiencies of the
+older :ref:`CROP API <crop>`, that was designed to control simple
+capture devices. Later the cropping API was adopted by video output
+drivers. The ioctls are used to select a part of the display were the
+video signal is inserted. It should be considered as an API abuse
+because the described operation is actually the composing. The
+selection API makes a clear distinction between composing and cropping
+operations by setting the appropriate targets.
+
+The V4L2 API lacks any support for composing to and cropping from an
+image inside a memory buffer. The application could configure a
+capture device to fill only a part of an image by abusing V4L2
+API. Cropping a smaller image from a larger one is achieved by setting
+the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`.
+Introducing an image offsets could be done by modifying field
+``m_userptr`` at struct :c:type:`v4l2_buffer` before calling
+:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided
+because they are not portable (endianness), and do not work for
+macroblock and Bayer formats and mmap buffers.
+
+The selection API deals with configuration of buffer
 cropping/composing in a clear, intuitive and portable way. Next, with
 the selection API the concepts of the padded target and constraints
-flags are introduced. Finally, struct :c:type:`v4l2_crop`
-and struct :c:type:`v4l2_cropcap` have no reserved
-fields. Therefore there is no way to extend their functionality. The new
-struct :c:type:`v4l2_selection` provides a lot of place
-for future extensions. Driver developers are encouraged to implement
-only selection API. The former cropping API would be simulated using the
-new one.
+flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct
+:c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no
+way to extend their functionality. The new struct
+:c:type:`v4l2_selection` provides a lot of place for future
+extensions.
+
+Driver developers are encouraged to implement only selection API. The
+former cropping API would be simulated using the new one.
-- 
2.7.4

[PATCH 5/5] media: docs: selection: fix misleading sentence about the CROP API

[Luca Ceresoli]

The API limitation described here is about the CROP API, not about the
entire V4L2.

Cc: Hans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst b/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst
index ba1064a244a0..e7455fb1e572 100644
--- a/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst
+++ b/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst
@@ -15,7 +15,7 @@ because the described operation is actually the composing. The
 selection API makes a clear distinction between composing and cropping
 operations by setting the appropriate targets.
 
-The V4L2 API lacks any support for composing to and cropping from an
+The CROP API lacks any support for composing to and cropping from an
 image inside a memory buffer. The application could configure a
 capture device to fill only a part of an image by abusing V4L2
 API. Cropping a smaller image from a larger one is achieved by setting
-- 
2.7.4

Re: [PATCH 2/5] media: docs: clarify relationship between crop and selection APIs

[Hans Verkuil]

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::
> 

Re: [PATCH 1/5] media: docs: selection: fix typos

[Hans Verkuil]

On 04/03/2018 11:15 PM, Luca Ceresoli wrote:

Please add a commit message here. Yes, it can be as simple as 'Fixed typos in the
selection documentation.'

Regards,

	Hans

> Cc: Hans Verkuil <hverkuil@xs4all.nl>
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/media/uapi/v4l/selection-api-004.rst | 2 +-
>  Documentation/media/uapi/v4l/selection.svg         | 4 ++--
>  2 files changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/media/uapi/v4l/selection-api-004.rst b/Documentation/media/uapi/v4l/selection-api-004.rst
> index d782cd5b2117..0a4ddc2d71db 100644
> --- a/Documentation/media/uapi/v4l/selection-api-004.rst
> +++ b/Documentation/media/uapi/v4l/selection-api-004.rst
> @@ -41,7 +41,7 @@ The driver may further adjust the requested size and/or position
>  according to hardware limitations.
>  
>  Each capture device has a default source rectangle, given by the
> -``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall over what the
> +``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the
>  driver writer considers the complete picture. Drivers shall set the
>  active crop rectangle to the default when the driver is first loaded,
>  but not later.
> diff --git a/Documentation/media/uapi/v4l/selection.svg b/Documentation/media/uapi/v4l/selection.svg
> index a93e3b59786d..911062bd2844 100644
> --- a/Documentation/media/uapi/v4l/selection.svg
> +++ b/Documentation/media/uapi/v4l/selection.svg
> @@ -1128,11 +1128,11 @@
>     </text>
>    </g>
>    <text transform="matrix(.96106 0 0 1.0405 48.571 195.53)" x="2438.062" y="1368.429" enable-background="new" font-size="50" style="line-height:125%">
> -   <tspan x="2438.062" y="1368.429">COMPOSE_BONDS</tspan>
> +   <tspan x="2438.062" y="1368.429">COMPOSE_BOUNDS</tspan>
>    </text>
>    <g font-size="40">
>     <text transform="translate(48.571 195.53)" x="8.082" y="1438.896" enable-background="new" style="line-height:125%">
> -    <tspan x="8.082" y="1438.896" font-size="50">CROP_BONDS</tspan>
> +    <tspan x="8.082" y="1438.896" font-size="50">CROP_BOUNDS</tspan>
>     </text>
>     <text transform="translate(48.571 195.53)" x="1455.443" y="-26.808" enable-background="new" style="line-height:125%">
>      <tspan x="1455.443" y="-26.808" font-size="50">overscan area</tspan>
> 

Re: [PATCH 3/5] media: docs: selection: rename files to something meaningful

[Hans Verkuil]

On 04/03/2018 11:15 PM, Luca Ceresoli wrote:
> These files have an automatically-generated numbering. Replaname them

Replaname -> Replace

> to something that suggests their meaning.

to -> with

Regards,

	Hans

> 
> Reported-by: Hans Verkuil <hverkuil@xs4all.nl>
> Cc: Hans Verkuil <hverkuil@xs4all.nl>
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  .../{selection-api-004.rst => selection-api-configuration.rst} |  0
>  .../v4l/{selection-api-006.rst => selection-api-examples.rst}  |  0
>  .../v4l/{selection-api-002.rst => selection-api-intro.rst}     |  0
>  .../v4l/{selection-api-003.rst => selection-api-targets.rst}   |  0
>  .../{selection-api-005.rst => selection-api-vs-crop-api.rst}   |  0
>  Documentation/media/uapi/v4l/selection-api.rst                 | 10 +++++-----
>  6 files changed, 5 insertions(+), 5 deletions(-)
>  rename Documentation/media/uapi/v4l/{selection-api-004.rst => selection-api-configuration.rst} (100%)
>  rename Documentation/media/uapi/v4l/{selection-api-006.rst => selection-api-examples.rst} (100%)
>  rename Documentation/media/uapi/v4l/{selection-api-002.rst => selection-api-intro.rst} (100%)
>  rename Documentation/media/uapi/v4l/{selection-api-003.rst => selection-api-targets.rst} (100%)
>  rename Documentation/media/uapi/v4l/{selection-api-005.rst => selection-api-vs-crop-api.rst} (100%)
> 
> diff --git a/Documentation/media/uapi/v4l/selection-api-004.rst b/Documentation/media/uapi/v4l/selection-api-configuration.rst
> similarity index 100%
> rename from Documentation/media/uapi/v4l/selection-api-004.rst
> rename to Documentation/media/uapi/v4l/selection-api-configuration.rst
> diff --git a/Documentation/media/uapi/v4l/selection-api-006.rst b/Documentation/media/uapi/v4l/selection-api-examples.rst
> similarity index 100%
> rename from Documentation/media/uapi/v4l/selection-api-006.rst
> rename to Documentation/media/uapi/v4l/selection-api-examples.rst
> diff --git a/Documentation/media/uapi/v4l/selection-api-002.rst b/Documentation/media/uapi/v4l/selection-api-intro.rst
> similarity index 100%
> rename from Documentation/media/uapi/v4l/selection-api-002.rst
> rename to Documentation/media/uapi/v4l/selection-api-intro.rst
> diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-targets.rst
> similarity index 100%
> rename from Documentation/media/uapi/v4l/selection-api-003.rst
> rename to Documentation/media/uapi/v4l/selection-api-targets.rst
> diff --git a/Documentation/media/uapi/v4l/selection-api-005.rst b/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst
> similarity index 100%
> rename from Documentation/media/uapi/v4l/selection-api-005.rst
> rename to Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst
> diff --git a/Documentation/media/uapi/v4l/selection-api.rst b/Documentation/media/uapi/v4l/selection-api.rst
> index e4e623824b30..390233f704a3 100644
> --- a/Documentation/media/uapi/v4l/selection-api.rst
> +++ b/Documentation/media/uapi/v4l/selection-api.rst
> @@ -9,8 +9,8 @@ Cropping, composing and scaling -- the SELECTION API
>  .. toctree::
>      :maxdepth: 1
>  
> -    selection-api-002
> -    selection-api-003
> -    selection-api-004
> -    selection-api-005
> -    selection-api-006
> +    selection-api-intro.rst
> +    selection-api-targets.rst
> +    selection-api-configuration.rst
> +    selection-api-vs-crop-api.rst
> +    selection-api-examples.rst
> 

Re: [PATCH 1/5] media: docs: selection: fix typos

[Hans Verkuil]

Hi Luca,

My apologies for the long delay in reviewing this.

It all looks very good and if you can post a v2 with these small issues
fixed, then I'll merge it for 4.18.

Regards,

	Hans

On 05/13/2018 11:13 AM, Hans Verkuil wrote:
> On 04/03/2018 11:15 PM, Luca Ceresoli wrote:
> 
> Please add a commit message here. Yes, it can be as simple as 'Fixed typos in the
> selection documentation.'
> 
> Regards,
> 
> 	Hans
> 
>> Cc: Hans Verkuil <hverkuil@xs4all.nl>
>> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
>> ---
>>  Documentation/media/uapi/v4l/selection-api-004.rst | 2 +-
>>  Documentation/media/uapi/v4l/selection.svg         | 4 ++--
>>  2 files changed, 3 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/media/uapi/v4l/selection-api-004.rst b/Documentation/media/uapi/v4l/selection-api-004.rst
>> index d782cd5b2117..0a4ddc2d71db 100644
>> --- a/Documentation/media/uapi/v4l/selection-api-004.rst
>> +++ b/Documentation/media/uapi/v4l/selection-api-004.rst
>> @@ -41,7 +41,7 @@ The driver may further adjust the requested size and/or position
>>  according to hardware limitations.
>>  
>>  Each capture device has a default source rectangle, given by the
>> -``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall over what the
>> +``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the
>>  driver writer considers the complete picture. Drivers shall set the
>>  active crop rectangle to the default when the driver is first loaded,
>>  but not later.
>> diff --git a/Documentation/media/uapi/v4l/selection.svg b/Documentation/media/uapi/v4l/selection.svg
>> index a93e3b59786d..911062bd2844 100644
>> --- a/Documentation/media/uapi/v4l/selection.svg
>> +++ b/Documentation/media/uapi/v4l/selection.svg
>> @@ -1128,11 +1128,11 @@
>>     </text>
>>    </g>
>>    <text transform="matrix(.96106 0 0 1.0405 48.571 195.53)" x="2438.062" y="1368.429" enable-background="new" font-size="50" style="line-height:125%">
>> -   <tspan x="2438.062" y="1368.429">COMPOSE_BONDS</tspan>
>> +   <tspan x="2438.062" y="1368.429">COMPOSE_BOUNDS</tspan>
>>    </text>
>>    <g font-size="40">
>>     <text transform="translate(48.571 195.53)" x="8.082" y="1438.896" enable-background="new" style="line-height:125%">
>> -    <tspan x="8.082" y="1438.896" font-size="50">CROP_BONDS</tspan>
>> +    <tspan x="8.082" y="1438.896" font-size="50">CROP_BOUNDS</tspan>
>>     </text>
>>     <text transform="translate(48.571 195.53)" x="1455.443" y="-26.808" enable-background="new" style="line-height:125%">
>>      <tspan x="1455.443" y="-26.808" font-size="50">overscan area</tspan>
>>
> 

Re: [PATCH 2/5] media: docs: clarify relationship between crop and selection APIs

[Luca Ceresoli]

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

Re: [PATCH 1/5] media: docs: selection: fix typos

[Luca Ceresoli]

Hi Hans,

On 13/05/2018 11:19, Hans Verkuil wrote:
> Hi Luca,
> 
> My apologies for the long delay in reviewing this.
> 
> It all looks very good and if you can post a v2 with these small issues
> fixed, then I'll merge it for 4.18.

On its way!

Thanks,
-- 
Luca