From: Sergey Senozhatsky <senozhatsky@chromium.org>
To: Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
Ricardo Ribalda <ribalda@chromium.org>
Cc: Tomasz Figa <tfiga@chromium.org>,
Mauro Carvalho Chehab <mchehab@kernel.org>,
Hans Verkuil <hverkuil-cisco@xs4all.nl>,
linux-media@vger.kernel.org, linux-kernel@vger.kernel.org,
Sergey Senozhatsky <senozhatsky@chromium.org>
Subject: [PATCHv5 2/5] media: v4l UAPI: document ROI selection targets
Date: Sat, 1 May 2021 17:19:58 +0900 [thread overview]
Message-ID: <20210501082001.100533-3-senozhatsky@chromium.org> (raw)
In-Reply-To: <20210501082001.100533-1-senozhatsky@chromium.org>
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 | 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.31.1.527.g47e6f16901-goog
next prev parent reply other threads:[~2021-05-01 8:20 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-01 8:19 [PATCHv5 0/5] media: uvcvideo: implement UVC 1.5 ROI Sergey Senozhatsky
2021-05-01 8:19 ` [PATCHv5 1/5] media: v4l UAPI: add ROI selection targets Sergey Senozhatsky
2021-05-01 8:19 ` Sergey Senozhatsky [this message]
2021-05-01 8:19 ` [PATCHv5 3/5] media: uvcvideo: add ROI auto controls Sergey Senozhatsky
2021-05-01 8:20 ` [PATCHv5 4/5] media: v4l UAPI: document ROI auto_controls Sergey Senozhatsky
2021-05-01 8:20 ` [PATCHv5 5/5] media: uvcvideo: add UVC 1.5 ROI control Sergey Senozhatsky
2021-05-26 10:38 ` [PATCHv5 0/5] media: uvcvideo: implement UVC 1.5 ROI Hans Verkuil
2021-06-01 8:46 ` Sergey Senozhatsky
2021-06-01 8:52 ` Hans Verkuil
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210501082001.100533-3-senozhatsky@chromium.org \
--to=senozhatsky@chromium.org \
--cc=hverkuil-cisco@xs4all.nl \
--cc=laurent.pinchart@ideasonboard.com \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=mchehab@kernel.org \
--cc=ribalda@chromium.org \
--cc=tfiga@chromium.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).