[v4,4/4] media: uvcvideo: document UVC v1.5 ROI
Commit Message
Added documentation of V4L2_CID_UVC_REGION_OF_INTEREST_RECT and
V4L2_CID_UVC_REGION_OF_INTEREST_AUTO.
Signed-off-by: Yunke Cao <yunkec@google.com>
---
.../userspace-api/media/drivers/uvcvideo.rst | 60 +++++++++++++++++++
1 file changed, 60 insertions(+)
Comments
Hi Yunke
On Tue, 24 May 2022 at 06:45, Yunke Cao <yunkec@google.com> wrote:
>
> Added documentation of V4L2_CID_UVC_REGION_OF_INTEREST_RECT and
> V4L2_CID_UVC_REGION_OF_INTEREST_AUTO.
>
> Signed-off-by: Yunke Cao <yunkec@google.com>
> ---
> .../userspace-api/media/drivers/uvcvideo.rst | 60 +++++++++++++++++++
> 1 file changed, 60 insertions(+)
>
> diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst
> index e5fd8fad333c..9b96c8b90b7a 100644
> --- a/Documentation/userspace-api/media/drivers/uvcvideo.rst
> +++ b/Documentation/userspace-api/media/drivers/uvcvideo.rst
> @@ -181,6 +181,7 @@ Argument: struct uvc_xu_control_mapping
> UVC_CTRL_DATA_TYPE_BOOLEAN Boolean
> UVC_CTRL_DATA_TYPE_ENUM Enumeration
> UVC_CTRL_DATA_TYPE_BITMASK Bitmask
> + UVC_CTRL_DATA_TYPE_RECT Rectangular area
>
>
> UVCIOC_CTRL_QUERY - Query a UVC XU control
> @@ -255,3 +256,62 @@ Argument: struct uvc_xu_control_query
> __u8 query Request code to send to the device
> __u16 size Control data size (in bytes)
> __u8 *data Control value
> +
> +Private V4L2 controls
> +---------------------
> +
> +A few UVC specific V4L2 control IDs are listed below.
> +
> +``V4L2_CID_UVC_REGION_OF_INTEREST_RECT (struct)``
> + This control determines the region of interest. Region of interest is an
This control determines the Region Of Interest (ROI). ROI is a
> + rectangular area represented by a struct v4l2_rect. The rectangle is in
struct :c:type:`v4l2_rect`.
> + pixel units and global coordinates. It is independent of the field of view,
> + not impacted by any cropping or scaling.
> +
> + Use ``V4L2_CTRL_WHICH_MIN_VAL`` and ``V4L2_CTRL_WHICH_MAX_VAL`` to query the
> + range of rectangle sizes. For example, a device can have a minimum ROI
> + rectangle of 1x1@0x0, a maximum of 640x480@0x0.
rectangle of 1x1@0x0 and a maximum of 640x480@0x0.
> +
> + Setting a region of interest allows the camera to optimize the capture for
ROI
> + the region. The value of ``V4L2_CID_REGION_OF_INTEREST_AUTO`` control
> + determines the detailed behavior.
> +
> +
> +``V4L2_CID_UVC_REGION_OF_INTEREST_AUTO (bitmask)``
> + This determines which, if any, on board features should track to the
> + Region of Interest specified by the current value of
> + ``V4L2_CID_UVD__REGION_OF_INTEREST_RECT``.
> +
> + Max value is a mask indicating all supported Auto
> + Controls.
> +
> +.. flat-table::
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - ``V4L2_REGION_OF_INTEREST_AUTO_EXPOSURE``
> + - Setting this to true enables automatic exposure time for the specified
> + region.
> + * - ``V4L2_REGION_OF_INTEREST_AUTO_IRIS``
> + - Setting this to true enables automatic iris aperture for the specified
> + region.
> + * - ``V4L2_REGION_OF_INTEREST_AUTO_WHITE_BALANCE``
> + - Setting this to true enables automatic white balance adjustment for the
> + specified region.
> + * - ``V4L2_REGION_OF_INTEREST_AUTO_FOCUS``
> + - Setting this to true enables automatic focus adjustment for the
> + specified region.
> + * - ``V4L2_REGION_OF_INTEREST_AUTO_FACE_DETECT``
> + - Setting this to true enables automatic face detection for the
> + specified region.
> + * - ``V4L2_REGION_OF_INTEREST_AUTO_DETECT_AND_TRACK``
> + - Setting this to true enables automatic face detection and tracking. The
> + current value of ``V4L2_CID_REGION_OF_INTEREST_RECT`` may be updated by
> + the driver.
> + * - ``V4L2_REGION_OF_INTEREST_AUTO_IMAGE_STABILIZATION``
> + - Setting this to true enables automatic image stabilization. The
> + current value of ``V4L2_CID_REGION_OF_INTEREST_RECT`` may be updated by
> + the driver.
> + * - ``V4L2_REGION_OF_INTEREST_AUTO_HIGHER_QUALITY``
> + - Setting this to true enables automatically capture the specified region
> + with higher quality if possible.
> --
> 2.36.1.124.g0e6072fb45-goog
>
@@ -181,6 +181,7 @@ Argument: struct uvc_xu_control_mapping
UVC_CTRL_DATA_TYPE_BOOLEAN Boolean
UVC_CTRL_DATA_TYPE_ENUM Enumeration
UVC_CTRL_DATA_TYPE_BITMASK Bitmask
+ UVC_CTRL_DATA_TYPE_RECT Rectangular area
UVCIOC_CTRL_QUERY - Query a UVC XU control
@@ -255,3 +256,62 @@ Argument: struct uvc_xu_control_query
__u8 query Request code to send to the device
__u16 size Control data size (in bytes)
__u8 *data Control value
+
+Private V4L2 controls
+---------------------
+
+A few UVC specific V4L2 control IDs are listed below.
+
+``V4L2_CID_UVC_REGION_OF_INTEREST_RECT (struct)``
+ This control determines the region of interest. Region of interest is an
+ rectangular area represented by a struct v4l2_rect. The rectangle is in
+ pixel units and global coordinates. It is independent of the field of view,
+ not impacted by any cropping or scaling.
+
+ Use ``V4L2_CTRL_WHICH_MIN_VAL`` and ``V4L2_CTRL_WHICH_MAX_VAL`` to query the
+ range of rectangle sizes. For example, a device can have a minimum ROI
+ rectangle of 1x1@0x0, a maximum of 640x480@0x0.
+
+ Setting a region of interest allows the camera to optimize the capture for
+ the region. The value of ``V4L2_CID_REGION_OF_INTEREST_AUTO`` control
+ determines the detailed behavior.
+
+
+``V4L2_CID_UVC_REGION_OF_INTEREST_AUTO (bitmask)``
+ This determines which, if any, on board features should track to the
+ Region of Interest specified by the current value of
+ ``V4L2_CID_UVD__REGION_OF_INTEREST_RECT``.
+
+ Max value is a mask indicating all supported Auto
+ Controls.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - ``V4L2_REGION_OF_INTEREST_AUTO_EXPOSURE``
+ - Setting this to true enables automatic exposure time for the specified
+ region.
+ * - ``V4L2_REGION_OF_INTEREST_AUTO_IRIS``
+ - Setting this to true enables automatic iris aperture for the specified
+ region.
+ * - ``V4L2_REGION_OF_INTEREST_AUTO_WHITE_BALANCE``
+ - Setting this to true enables automatic white balance adjustment for the
+ specified region.
+ * - ``V4L2_REGION_OF_INTEREST_AUTO_FOCUS``
+ - Setting this to true enables automatic focus adjustment for the
+ specified region.
+ * - ``V4L2_REGION_OF_INTEREST_AUTO_FACE_DETECT``
+ - Setting this to true enables automatic face detection for the
+ specified region.
+ * - ``V4L2_REGION_OF_INTEREST_AUTO_DETECT_AND_TRACK``
+ - Setting this to true enables automatic face detection and tracking. The
+ current value of ``V4L2_CID_REGION_OF_INTEREST_RECT`` may be updated by
+ the driver.
+ * - ``V4L2_REGION_OF_INTEREST_AUTO_IMAGE_STABILIZATION``
+ - Setting this to true enables automatic image stabilization. The
+ current value of ``V4L2_CID_REGION_OF_INTEREST_RECT`` may be updated by
+ the driver.
+ * - ``V4L2_REGION_OF_INTEREST_AUTO_HIGHER_QUALITY``
+ - Setting this to true enables automatically capture the specified region
+ with higher quality if possible.