[v14,11/11] media: uvcvideo: document UVC v1.5 ROI

Message ID	20231201071907.3080126-12-yunkec@google.com (mailing list archive)
State	New
Headers	show Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="RxZSZAxa" Date: Fri, 1 Dec 2023 16:19:02 +0900 In-Reply-To: <20231201071907.3080126-1-yunkec@google.com> Precedence: bulk Mime-Version: 1.0 References: <20231201071907.3080126-1-yunkec@google.com> Message-ID: <20231201071907.3080126-12-yunkec@google.com> Subject: [PATCH v14 11/11] media: uvcvideo: document UVC v1.5 ROI From: Yunke Cao <yunkec@google.com> To: Hans Verkuil <hverkuil-cisco@xs4all.nl>, Laurent Pinchart <laurent.pinchart@ideasonboard.com>, Daniel Scally <dan.scally@ideasonboard.com> Cc: Tomasz Figa <tfiga@chromium.org>, Sergey Senozhatsky <senozhatsky@chromium.org>, Ricardo Ribalda <ribalda@chromium.org>, linux-media@vger.kernel.org, Yunke Cao <yunkec@google.com> Content-Type: text/plain; charset="UTF-8"
Series	Implement UVC v1.5 ROI \| expand [v14,00/11] Implement UVC v1.5 ROI [v14,01/11] media: v4l2_ctrl: Add V4L2_CTRL_TYPE_RECT [v14,02/11] media: uvcvideo: add uvc_ctrl_get_boundary for getting default value [v14,03/11] media: uvcvideo: introduce __uvc_ctrl_get_std() [v14,04/11] media: uvcvideo: Split uvc_control_mapping.size to v4l2 and data size [v14,05/11] media: uvcvideo: Add support for compound controls [v14,06/11] v4l2-ctrls: add support for V4L2_CTRL_WHICH_MIN/MAX_VAL [v14,07/11] media: vivid: Add an rectangle control [v14,08/11] media: uvcvideo: support V4L2_CTRL_WHICH_MIN/MAX_VAL [v14,09/11] media: uvcvideo: implement UVC v1.5 ROI [v14,10/11] media: uvcvideo: initilaize ROI control to default value [v14,11/11] media: uvcvideo: document UVC v1.5 ROI

Message ID

20231201071907.3080126-12-yunkec@google.com (mailing list archive)

State

New

Headers

Date: Fri,  1 Dec 2023 16:19:02 +0900
In-Reply-To: <20231201071907.3080126-1-yunkec@google.com>
Precedence: bulk
Mime-Version: 1.0
References: <20231201071907.3080126-1-yunkec@google.com>
Message-ID: <20231201071907.3080126-12-yunkec@google.com>
Subject: [PATCH v14 11/11] media: uvcvideo: document UVC v1.5 ROI
From: Yunke Cao <yunkec@google.com>
To: Hans Verkuil <hverkuil-cisco@xs4all.nl>,
	Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
	Daniel Scally <dan.scally@ideasonboard.com>
Cc: Tomasz Figa <tfiga@chromium.org>,
 Sergey Senozhatsky <senozhatsky@chromium.org>,
	Ricardo Ribalda <ribalda@chromium.org>, linux-media@vger.kernel.org,
	Yunke Cao <yunkec@google.com>
Content-Type: text/plain; charset="UTF-8"

Series

Implement UVC v1.5 ROI | expand

Commit Message

Yunke Cao Dec. 1, 2023, 7:19 a.m. UTC

Added documentation of V4L2_CID_UVC_REGION_OF_INTEREST_RECT and
V4L2_CID_UVC_REGION_OF_INTEREST_AUTO.

Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
Reviewed-by: Sergey Senozhatsky <senozhatsky@chromium.org>
Signed-off-by: Yunke Cao <yunkec@google.com>
---
Changelog since v11:
- No change.
Changelog since v10:
- Added Reviewed-by from Sergey.
Changelog since v9:
- No change.
Changelog since v8:
- No change.
Changelog since v7:
- Fix documentation for automatic exposure based on comment in v7.

 .../userspace-api/media/drivers/uvcvideo.rst  | 62 +++++++++++++++++++
 1 file changed, 62 insertions(+)

Comments

Laurent Pinchart Dec. 8, 2023, 4 p.m. UTC | #1

Hi Yunke,

Thank you for the patch.

On Fri, Dec 01, 2023 at 04:19:02PM +0900, Yunke Cao wrote:
> Added documentation of V4L2_CID_UVC_REGION_OF_INTEREST_RECT and
> V4L2_CID_UVC_REGION_OF_INTEREST_AUTO.

It would be useful to point here to the userspace code that uses those
controls. A link to the appropriate Chrome OS git tree would be useful,
to showcase a real user.

> Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> Reviewed-by: Sergey Senozhatsky <senozhatsky@chromium.org>
> Signed-off-by: Yunke Cao <yunkec@google.com>
> ---
> Changelog since v11:
> - No change.
> Changelog since v10:
> - Added Reviewed-by from Sergey.
> Changelog since v9:
> - No change.
> Changelog since v8:
> - No change.
> Changelog since v7:
> - Fix documentation for automatic exposure based on comment in v7.
> 
>  .../userspace-api/media/drivers/uvcvideo.rst  | 62 +++++++++++++++++++
>  1 file changed, 62 insertions(+)
> 
> diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst
> index aab4304e6bb5..3dc062221f8b 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,64 @@ 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
> +
> +
> +Driver-specific V4L2 controls
> +-----------------------------
> +
> +The uvcvideo driver implements the following UVC-specific controls:
> +
> +``V4L2_CID_UVC_REGION_OF_INTEREST_RECT (struct)``
> +	This control determines the region of interest (ROI). ROI is a
> +	rectangular area represented by a struct :c:type:`v4l2_rect`. The
> +	rectangle is in global sensor coordinates and pixel units. 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. The left/top coordinates of a minimum or
> +	maximum rectangle are always 0. For example, a device can have a minimum
> +	ROI rectangle of 1x1@0x0 and a maximum of 640x480@0x0.

Is that actually true ? The UVC 1.5 specification states

    GET_MAX shall return the current Window as specified by
    CT_DIGITAL_WINDOW_CONTROL.

And the window can have non-zero left and right coordinates.

> +
> +	Setting a ROI 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

s/on board/on-board/

> +	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_UVC_REGION_OF_INTEREST_AUTO_EXPOSURE``
> +      - Setting this to true causes automatic exposure to track the region of

Maybe "Setting this bit causes..." as those values are bit flags, not
booleans. Same below.

> +	interest instead of the whole image.
> +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_IRIS``
> +      - Setting this to true causes automatic iris to track the region of
> +	interest instead of the whole image.
> +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_WHITE_BALANCE``
> +      - Setting this to true causes automatic white balance to track the region
> +	of interest instead of the whole image.
> +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FOCUS``
> +      - Setting this to true causes automatic focus adjustment to track the
> +	region of interest instead of the whole image.
> +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FACE_DETECT``
> +      - Setting this to true causes automatic face detection to track the
> +	region of interest instead of the whole image.
> +    * - ``V4L2_UVC_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_UVC_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_UVC_REGION_OF_INTEREST_AUTO_HIGHER_QUALITY``
> +      - Setting this to true enables automatically capture the specified region

I wonder what this means, the UVC 1.5 specification doesn't document
this bit clearly :-(

> +	with higher quality if possible.

Yunke Cao Dec. 12, 2023, 4:45 a.m. UTC | #2

Hi Laurent,

Thanks for the review!

On Sat, Dec 9, 2023 at 1:00 AM Laurent Pinchart
<laurent.pinchart@ideasonboard.com> wrote:
>
> Hi Yunke,
>
> Thank you for the patch.
>
> On Fri, Dec 01, 2023 at 04:19:02PM +0900, Yunke Cao wrote:
> > Added documentation of V4L2_CID_UVC_REGION_OF_INTEREST_RECT and
> > V4L2_CID_UVC_REGION_OF_INTEREST_AUTO.
>
> It would be useful to point here to the userspace code that uses those
> controls. A link to the appropriate Chrome OS git tree would be useful,
> to showcase a real user.

Does https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform2/camera/hal/usb/
work?
Do you think we need the link in both the commit message and this .rst file?

>
> > Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> > Reviewed-by: Sergey Senozhatsky <senozhatsky@chromium.org>
> > Signed-off-by: Yunke Cao <yunkec@google.com>
> > ---
> > Changelog since v11:
> > - No change.
> > Changelog since v10:
> > - Added Reviewed-by from Sergey.
> > Changelog since v9:
> > - No change.
> > Changelog since v8:
> > - No change.
> > Changelog since v7:
> > - Fix documentation for automatic exposure based on comment in v7.
> >
> >  .../userspace-api/media/drivers/uvcvideo.rst  | 62 +++++++++++++++++++
> >  1 file changed, 62 insertions(+)
> >
> > diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst
> > index aab4304e6bb5..3dc062221f8b 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,64 @@ 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
> > +
> > +
> > +Driver-specific V4L2 controls
> > +-----------------------------
> > +
> > +The uvcvideo driver implements the following UVC-specific controls:
> > +
> > +``V4L2_CID_UVC_REGION_OF_INTEREST_RECT (struct)``
> > +     This control determines the region of interest (ROI). ROI is a
> > +     rectangular area represented by a struct :c:type:`v4l2_rect`. The
> > +     rectangle is in global sensor coordinates and pixel units. 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. The left/top coordinates of a minimum or
> > +     maximum rectangle are always 0. For example, a device can have a minimum
> > +     ROI rectangle of 1x1@0x0 and a maximum of 640x480@0x0.
>
> Is that actually true ? The UVC 1.5 specification states
>
>     GET_MAX shall return the current Window as specified by
>     CT_DIGITAL_WINDOW_CONTROL.
>
> And the window can have non-zero left and right coordinates.
>

Ah, you are right. I think I will just remove "The left/top
coordinates of a minimum or maximum rectangle are always 0."

> > +
> > +     Setting a ROI 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
>
> s/on board/on-board/
>
> > +     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_UVC_REGION_OF_INTEREST_AUTO_EXPOSURE``
> > +      - Setting this to true causes automatic exposure to track the region of
>
> Maybe "Setting this bit causes..." as those values are bit flags, not
> booleans. Same below.
>

Sounds good.

> > +     interest instead of the whole image.
> > +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_IRIS``
> > +      - Setting this to true causes automatic iris to track the region of
> > +     interest instead of the whole image.
> > +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_WHITE_BALANCE``
> > +      - Setting this to true causes automatic white balance to track the region
> > +     of interest instead of the whole image.
> > +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FOCUS``
> > +      - Setting this to true causes automatic focus adjustment to track the
> > +     region of interest instead of the whole image.
> > +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FACE_DETECT``
> > +      - Setting this to true causes automatic face detection to track the
> > +     region of interest instead of the whole image.
> > +    * - ``V4L2_UVC_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_UVC_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_UVC_REGION_OF_INTEREST_AUTO_HIGHER_QUALITY``
> > +      - Setting this to true enables automatically capture the specified region
>
> I wonder what this means, the UVC 1.5 specification doesn't document
> this bit clearly :-(
>

I have no idea :-( . I haven't seen any camera module in Chrome OS
attempt to implement this bit, either.

Best,
Yunke

> > +     with higher quality if possible.
>
> --
> Regards,
>
> Laurent Pinchart

Laurent Pinchart Dec. 18, 2023, 3:44 a.m. UTC | #3

Hi Yunke,

On Tue, Dec 12, 2023 at 01:45:00PM +0900, Yunke Cao wrote:
> On Sat, Dec 9, 2023 at 1:00 AM Laurent Pinchart wrote:
> > On Fri, Dec 01, 2023 at 04:19:02PM +0900, Yunke Cao wrote:
> > > Added documentation of V4L2_CID_UVC_REGION_OF_INTEREST_RECT and
> > > V4L2_CID_UVC_REGION_OF_INTEREST_AUTO.
> >
> > It would be useful to point here to the userspace code that uses those
> > controls. A link to the appropriate Chrome OS git tree would be useful,
> > to showcase a real user.
> 
> Does https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform2/camera/hal/usb/
> work?

I would pin it to a branch, as it may disappear from the main branch
later:

https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/release-R121-15699.B/camera/hal/usb/

> Do you think we need the link in both the commit message and this .rst file?

Sounds good to me.

> > > Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> > > Reviewed-by: Sergey Senozhatsky <senozhatsky@chromium.org>
> > > Signed-off-by: Yunke Cao <yunkec@google.com>
> > > ---
> > > Changelog since v11:
> > > - No change.
> > > Changelog since v10:
> > > - Added Reviewed-by from Sergey.
> > > Changelog since v9:
> > > - No change.
> > > Changelog since v8:
> > > - No change.
> > > Changelog since v7:
> > > - Fix documentation for automatic exposure based on comment in v7.
> > >
> > >  .../userspace-api/media/drivers/uvcvideo.rst  | 62 +++++++++++++++++++
> > >  1 file changed, 62 insertions(+)
> > >
> > > diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst
> > > index aab4304e6bb5..3dc062221f8b 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,64 @@ 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
> > > +
> > > +
> > > +Driver-specific V4L2 controls
> > > +-----------------------------
> > > +
> > > +The uvcvideo driver implements the following UVC-specific controls:
> > > +
> > > +``V4L2_CID_UVC_REGION_OF_INTEREST_RECT (struct)``
> > > +     This control determines the region of interest (ROI). ROI is a
> > > +     rectangular area represented by a struct :c:type:`v4l2_rect`. The
> > > +     rectangle is in global sensor coordinates and pixel units. 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. The left/top coordinates of a minimum or
> > > +     maximum rectangle are always 0. For example, a device can have a minimum
> > > +     ROI rectangle of 1x1@0x0 and a maximum of 640x480@0x0.
> >
> > Is that actually true ? The UVC 1.5 specification states
> >
> >     GET_MAX shall return the current Window as specified by
> >     CT_DIGITAL_WINDOW_CONTROL.
> >
> > And the window can have non-zero left and right coordinates.
> 
> Ah, you are right. I think I will just remove "The left/top
> coordinates of a minimum or maximum rectangle are always 0."

The rectangle would still be relative to CT_DIGITAL_WINDOW_CONTROL,
which isn't exposed by the driver to userspace. Isn't that a problem ?

> > > +
> > > +     Setting a ROI 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
> >
> > s/on board/on-board/
> >
> > > +     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_UVC_REGION_OF_INTEREST_AUTO_EXPOSURE``
> > > +      - Setting this to true causes automatic exposure to track the region of
> >
> > Maybe "Setting this bit causes..." as those values are bit flags, not
> > booleans. Same below.
> 
> Sounds good.
> 
> > > +     interest instead of the whole image.
> > > +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_IRIS``
> > > +      - Setting this to true causes automatic iris to track the region of
> > > +     interest instead of the whole image.
> > > +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_WHITE_BALANCE``
> > > +      - Setting this to true causes automatic white balance to track the region
> > > +     of interest instead of the whole image.
> > > +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FOCUS``
> > > +      - Setting this to true causes automatic focus adjustment to track the
> > > +     region of interest instead of the whole image.
> > > +    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FACE_DETECT``
> > > +      - Setting this to true causes automatic face detection to track the
> > > +     region of interest instead of the whole image.
> > > +    * - ``V4L2_UVC_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_UVC_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_UVC_REGION_OF_INTEREST_AUTO_HIGHER_QUALITY``
> > > +      - Setting this to true enables automatically capture the specified region
> >
> > I wonder what this means, the UVC 1.5 specification doesn't document
> > this bit clearly :-(
> 
> I have no idea :-( . I haven't seen any camera module in Chrome OS
> attempt to implement this bit, either.
> 
> > > +     with higher quality if possible.

diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst
index aab4304e6bb5..3dc062221f8b 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,64 @@  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
+
+
+Driver-specific V4L2 controls
+-----------------------------
+
+The uvcvideo driver implements the following UVC-specific controls:
+
+``V4L2_CID_UVC_REGION_OF_INTEREST_RECT (struct)``
+	This control determines the region of interest (ROI). ROI is a
+	rectangular area represented by a struct :c:type:`v4l2_rect`. The
+	rectangle is in global sensor coordinates and pixel units. 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. The left/top coordinates of a minimum or
+	maximum rectangle are always 0. For example, a device can have a minimum
+	ROI rectangle of 1x1@0x0 and a maximum of 640x480@0x0.
+
+	Setting a ROI 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_UVC_REGION_OF_INTEREST_AUTO_EXPOSURE``
+      - Setting this to true causes automatic exposure to track the region of
+	interest instead of the whole image.
+    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_IRIS``
+      - Setting this to true causes automatic iris to track the region of
+	interest instead of the whole image.
+    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_WHITE_BALANCE``
+      - Setting this to true causes automatic white balance to track the region
+	of interest instead of the whole image.
+    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FOCUS``
+      - Setting this to true causes automatic focus adjustment to track the
+	region of interest instead of the whole image.
+    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FACE_DETECT``
+      - Setting this to true causes automatic face detection to track the
+	region of interest instead of the whole image.
+    * - ``V4L2_UVC_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_UVC_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_UVC_REGION_OF_INTEREST_AUTO_HIGHER_QUALITY``
+      - Setting this to true enables automatically capture the specified region
+	with higher quality if possible.

[v14,11/11] media: uvcvideo: document UVC v1.5 ROI

Commit Message

Comments

Patch