| From 27ae344fc62ad05acd7b5c55867d19ac5cd6c824 Mon Sep 17 00:00:00 2001 |
| From: Sergey Senozhatsky <senozhatsky@chromium.org> |
| Date: Wed, 23 Jun 2021 12:08:02 +0900 |
| Subject: [PATCH] BACKPORT: FROMLIST: media: v4l UAPI: document ROI selection |
| targets |
| |
| Document V4L2 selection targets that will be used to ROI |
| implementation. |
| |
| (am from https://lore.kernel.org/lkml/20210501082001.100533-3-senozhatsky@chromium.org) |
| |
| BUG=b:186835892 |
| TEST=backport of a series that was tested on v4.19 kernel |
| TEST=v4l2-ctl on hatch and drallion |
| |
| Signed-off-by: Sergey Senozhatsky <senozhatsky@chromium.org> |
| Change-Id: I8d4164cf92611bbb60fc553090a412028d2af33e |
| Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/third_party/kernel/+/2981315 |
| Reviewed-by: Ricardo Ribalda <ribalda@chromium.org> |
| --- |
| .../media/v4l/selection-api-configuration.rst | 22 +++++++++++++++ |
| .../media/v4l/selection-api-examples.rst | 27 +++++++++++++++++++ |
| .../media/v4l/v4l2-selection-targets.rst | 24 +++++++++++++++++ |
| 3 files changed, 73 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 |
| +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..39aba98d55f1 100644 |
| --- a/Documentation/userspace-api/media/v4l/selection-api-examples.rst |
| +++ b/Documentation/userspace-api/media/v4l/selection-api-examples.rst |
| @@ -82,3 +82,30 @@ 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; |
| + 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.17.1 |
| |