From: Sergey Senozhatsky <senozhatsky@xxxxxxxxxxxx>
Document new v4l2-selection target which will be used for the
Region of Interest v4l2 control.
Signed-off-by: Sergey Senozhatsky <senozhatsky@xxxxxxxxxxxx>
---
.../media/v4l/selection-api-configuration.rst | 23 +++++++++++++++++++
.../media/v4l/v4l2-selection-targets.rst | 21 +++++++++++++++++
include/uapi/linux/v4l2-common.h | 8 +++++++
3 files changed, 52 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..9f69d71803f6 100644
--- a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst
+++ b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst
@@ -135,3 +135,26 @@ 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 coordinates of the top left corner, width and height of
+areas that can be ROI is given by the ``V4L2_SEL_TGT_ROI_BOUNDS`` target.
+It is recommended for the driver developers to put the top/left corner
+at position ``(0,0)``. The rectangle's coordinates are in global sensor
+coordinates. The units are in pixels and independent of the field of view.
+They are not impacted by any cropping or scaling that is currently being
+used.
+
+The top left corner, width and height of the Region of Interest area
+currently being employed by the device is given by the
+``V4L2_SEL_TGT_ROI_CURRENT`` target. It uses the same coordinate system
+as ``V4L2_SEL_TGT_ROI_BOUNDS``.
+
+In order to change active ROI top left, width and height coordinates
+use ``V4L2_SEL_TGT_ROI`` target.
+
+Each capture device has a default ROI rectangle, 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/v4l2-selection-targets.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
index e877ebbdb32e..cb3809418fa6 100644
--- a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
+++ b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
@@ -69,3 +69,24 @@ of the two interfaces they are used.
modified by hardware.
- Yes
- No
+ * - ``V4L2_SEL_TGT_ROI_CURRENT``
+ - 0x0200
+ - Current Region of Interest rectangle.
+ - Yes
+ - No
+ * - ``V4L2_SEL_TGT_ROI_DEFAULT``
+ - 0x0201
+ - Suggested Region of Interest rectangle.
+ - Yes
+ - No
+ * - ``V4L2_SEL_TGT_ROI_BOUNDS``
+ - 0x0202
+ - Bounds of the Region of Interest rectangle. All valid ROI rectangles fit
+ inside the ROI bounds rectangle.
+ - Yes
+ - No
+ * - ``V4L2_SEL_TGT_ROI``
+ - 0x0203
+ - Sets the new Region of Interest rectangle.
+ - Yes
+ - No
diff --git a/include/uapi/linux/v4l2-common.h b/include/uapi/linux/v4l2-common.h
index 7d21c1634b4d..d0c108fba638 100644
--- a/include/uapi/linux/v4l2-common.h
+++ b/include/uapi/linux/v4l2-common.h
@@ -78,6 +78,14 @@
#define V4L2_SEL_TGT_COMPOSE_BOUNDS 0x0102
/* Current composing area plus all padding pixels */
#define V4L2_SEL_TGT_COMPOSE_PADDED 0x0103
+/* Current Region of Interest area */
+#define V4L2_SEL_TGT_ROI_CURRENT 0x0200
+/* Default Region of Interest area */
+#define V4L2_SEL_TGT_ROI_DEFAULT 0x0201
+/* Region of Interest bounds */
+#define V4L2_SEL_TGT_ROI_BOUNDS 0x0202
+/* Set Region of Interest area */
+#define V4L2_SEL_TGT_ROI 0x0203
/* Selection flags */
#define V4L2_SEL_FLAG_GE (1 << 0)
--
2.30.0
