diff mbox series

[PATCHv3,2/6] media: v4l UAPI: document ROI selection targets

Message ID 20210319055342.127308-3-senozhatsky@chromium.org (mailing list archive)
State New, archived
Headers show
Series media: uvcvideo: implement UVC 1.5 ROI | expand

Commit Message

Sergey Senozhatsky March 19, 2021, 5:53 a.m. UTC 
Document V4L2 selection targets that will be used to ROI
implementation.

Signed-off-by: Sergey Senozhatsky <senozhatsky@chromium.org>
---
 .../media/v4l/selection-api-configuration.rst | 22 +++++++++++++++
 .../media/v4l/selection-api-examples.rst      | 28 +++++++++++++++++++
 .../media/v4l/v4l2-selection-targets.rst      | 24 ++++++++++++++++
 3 files changed, 74 insertions(+)

Comments

Ricardo Ribalda March 23, 2021, 4:05 p.m. UTC | #1 
Hi Sergey

On Fri, Mar 19, 2021 at 6:53 AM Sergey Senozhatsky
<senozhatsky@chromium.org> wrote:
>
> Document V4L2 selection targets that will be used to ROI
> implementation.
>
> Signed-off-by: Sergey Senozhatsky <senozhatsky@chromium.org>
> ---
>  .../media/v4l/selection-api-configuration.rst | 22 +++++++++++++++
>  .../media/v4l/selection-api-examples.rst      | 28 +++++++++++++++++++
>  .../media/v4l/v4l2-selection-targets.rst      | 24 ++++++++++++++++
>  3 files changed, 74 insertions(+)
>
> diff --git a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst
> index fee49bf1a1c0..b5fdd765e2db 100644
> --- a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst
> +++ b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst
> @@ -135,3 +135,25 @@ and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
>  ``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
>  scaling is applied. The application can compute the scaling ratios using
>  these values.
> +
> +Configuration of Region of Interest (ROI)
> +=========================================
> +
> +The range of auto-controls values and of coordinates of the top left
> +corner, width and height of areas that can be ROI is given by the
> +``V4L2_SEL_TGT_ROI_BOUNDS_MIN`` and ``V4L2_SEL_TGT_ROI_BOUNDS_MAX``
> +targets. It is recommended for the driver developers to put the top/left
> +corner at position ``(0,0)``.
> +
> +The top left corner, width and height of the Region of Interest area
> +and auto-controls currently being employed by the device are given by
> +the ``V4L2_SEL_TGT_ROI`` target. It uses the same coordinate system
> +as ``V4L2_SEL_TGT_ROI_BOUNDS_MIN`` and ``V4L2_SEL_TGT_ROI_BOUNDS_MAX``.
> +
> +In order to change active ROI top left, width and height coordinates
> +and ROI auto-controls use ``V4L2_SEL_TGT_ROI`` target.
> +
> +Each capture device has a default ROI rectangle and auto-controls
> +value given by the ``V4L2_SEL_TGT_ROI_DEFAULT`` target. Drivers shall

nit:  Drivers may, instead of shall?



> +set the ROI rectangle to the default when the driver is first loaded,
> +but not later.
> diff --git a/Documentation/userspace-api/media/v4l/selection-api-examples.rst b/Documentation/userspace-api/media/v4l/selection-api-examples.rst
> index 5f8e8a1f59d7..ad2664888700 100644
> --- a/Documentation/userspace-api/media/v4l/selection-api-examples.rst
> +++ b/Documentation/userspace-api/media/v4l/selection-api-examples.rst
> @@ -82,3 +82,31 @@ Example: Querying for scaling factors
>         /* computing scaling factors */
>         hscale = (double)compose.r.width / crop.r.width;
>         vscale = (double)compose.r.height / crop.r.height;
> +
> +Setting Region Of Interest area to half of the default value
> +
> +Example: Simple ROI
> +===========================
> +
> +.. code-block:: c
> +
> +       struct v4l2_selection roi = {
> +           .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
> +           .target = V4L2_SEL_TGT_ROI_DEFAULT,
> +       };
> +       struct v4l2_rect r;
> +
> +       ret = ioctl(fd, VIDIOC_G_SELECTION, &roi);
> +       if (ret)
> +           exit(-1);
> +       /* setting smaller ROI rectangle */
> +       r.width = roi.r.width / 2;
> +       r.height = roi.r.height / 2;
> +       r.left = roi.r.width / 4;
> +       r.top = roi.r.height / 4;
> +       roi.r = r;
> +       roi.target = V4L2_SEL_TGT_ROI;
> +       roi.flags = V4L2_SEL_FLAG_ROI_AUTO_EXPOSURE;
> +       ret = ioctl(fd, VIDIOC_S_SELECTION, &roi);
> +       if (ret)
> +           exit(-1);
> diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
> index b46bae984f35..d1dc9c50eb05 100644
> --- a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
> +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
> @@ -75,6 +75,30 @@ of the two interfaces they are used.
>         modified by hardware.
>        - Yes
>        - No
> +    * - ``V4L2_SEL_TGT_ROI``
> +      - 0x0200
> +      - Current Region of Interest rectangle and auto-controls value.
> +      - Yes
> +      - No
> +    * - ``V4L2_SEL_TGT_ROI_DEFAULT``
> +      - 0x0201
> +      - Suggested Region of Interest rectangle and auto-controls value.
> +      - Yes
> +      - No
> +    * - ``V4L2_SEL_TGT_ROI_BOUNDS_MIN``
> +      - 0x0202
> +      - Minimum bounds of the Region of Interest rectangle and minimum
> +       auto-controls value. All valid ROI rectangles and auto-controls
> +       should be within minimum-maximum range.
> +      - Yes
> +      - No
> +    * - ``V4L2_SEL_TGT_ROI_BOUNDS_MAX``
> +      - 0x0203
> +      - Maximum bounds of the Region of Interest rectangle and maximum
> +       auto-controls value. All valid ROI rectangles and auto-controls
> +       should be within minimum-maximum range.
> +      - Yes
> +      - No
>
>  .. raw:: latex
>
> --
> 2.31.0.rc2.261.g7f71774620-goog
>


--
Ricardo Ribalda
diff mbox series

Patch

diff --git a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst
index fee49bf1a1c0..b5fdd765e2db 100644
--- a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst
+++ b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst
@@ -135,3 +135,25 @@  and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
 ``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
 scaling is applied. The application can compute the scaling ratios using
 these values.
+
+Configuration of Region of Interest (ROI)
+=========================================
+
+The range of auto-controls values and of coordinates of the top left
+corner, width and height of areas that can be ROI is given by the
+``V4L2_SEL_TGT_ROI_BOUNDS_MIN`` and ``V4L2_SEL_TGT_ROI_BOUNDS_MAX``
+targets. It is recommended for the driver developers to put the top/left
+corner at position ``(0,0)``.
+
+The top left corner, width and height of the Region of Interest area
+and auto-controls currently being employed by the device are given by
+the ``V4L2_SEL_TGT_ROI`` target. It uses the same coordinate system
+as ``V4L2_SEL_TGT_ROI_BOUNDS_MIN`` and ``V4L2_SEL_TGT_ROI_BOUNDS_MAX``.
+
+In order to change active ROI top left, width and height coordinates
+and ROI auto-controls use ``V4L2_SEL_TGT_ROI`` target.
+
+Each capture device has a default ROI rectangle and auto-controls
+value given by the ``V4L2_SEL_TGT_ROI_DEFAULT`` target. Drivers shall
+set the ROI rectangle to the default when the driver is first loaded,
+but not later.
diff --git a/Documentation/userspace-api/media/v4l/selection-api-examples.rst b/Documentation/userspace-api/media/v4l/selection-api-examples.rst
index 5f8e8a1f59d7..ad2664888700 100644
--- a/Documentation/userspace-api/media/v4l/selection-api-examples.rst
+++ b/Documentation/userspace-api/media/v4l/selection-api-examples.rst
@@ -82,3 +82,31 @@  Example: Querying for scaling factors
 	/* computing scaling factors */
 	hscale = (double)compose.r.width / crop.r.width;
 	vscale = (double)compose.r.height / crop.r.height;
+
+Setting Region Of Interest area to half of the default value
+
+Example: Simple ROI
+===========================
+
+.. code-block:: c
+
+	struct v4l2_selection roi = {
+	    .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
+	    .target = V4L2_SEL_TGT_ROI_DEFAULT,
+	};
+	struct v4l2_rect r;
+
+	ret = ioctl(fd, VIDIOC_G_SELECTION, &roi);
+	if (ret)
+	    exit(-1);
+	/* setting smaller ROI rectangle */
+	r.width = roi.r.width / 2;
+	r.height = roi.r.height / 2;
+	r.left = roi.r.width / 4;
+	r.top = roi.r.height / 4;
+	roi.r = r;
+	roi.target = V4L2_SEL_TGT_ROI;
+	roi.flags = V4L2_SEL_FLAG_ROI_AUTO_EXPOSURE;
+	ret = ioctl(fd, VIDIOC_S_SELECTION, &roi);
+	if (ret)
+	    exit(-1);
diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
index b46bae984f35..d1dc9c50eb05 100644
--- a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
+++ b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
@@ -75,6 +75,30 @@  of the two interfaces they are used.
 	modified by hardware.
       - Yes
       - No
+    * - ``V4L2_SEL_TGT_ROI``
+      - 0x0200
+      - Current Region of Interest rectangle and auto-controls value.
+      - Yes
+      - No
+    * - ``V4L2_SEL_TGT_ROI_DEFAULT``
+      - 0x0201
+      - Suggested Region of Interest rectangle and auto-controls value.
+      - Yes
+      - No
+    * - ``V4L2_SEL_TGT_ROI_BOUNDS_MIN``
+      - 0x0202
+      - Minimum bounds of the Region of Interest rectangle and minimum
+	auto-controls value. All valid ROI rectangles and auto-controls
+	should be within minimum-maximum range.
+      - Yes
+      - No
+    * - ``V4L2_SEL_TGT_ROI_BOUNDS_MAX``
+      - 0x0203
+      - Maximum bounds of the Region of Interest rectangle and maximum
+	auto-controls value. All valid ROI rectangles and auto-controls
+	should be within minimum-maximum range.
+      - Yes
+      - No
 
 .. raw:: latex