| Message ID | 20241210-uvc-roi-v16-18-e8201f7e8e57@chromium.org (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | media: uvcvideo: Implement UVC v1.5 ROI | expand |
Hi, On 10-Dec-24 10:42 AM, Ricardo Ribalda wrote: > From: Yunke Cao <yunkec@google.com> > > Added documentation of V4L2_CID_UVC_REGION_OF_INTEREST_RECT and > V4L2_CID_UVC_REGION_OF_INTEREST_AUTO. > > An example of a userspace implementing this feature can be found at: > https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/release-R121-15699.B/camera/hal/usb/ > > Reviewed-by: Ricardo Ribalda <ribalda@chromium.org> > Reviewed-by: Sergey Senozhatsky <senozhatsky@chromium.org> > Signed-off-by: Yunke Cao <yunkec@google.com> > Tested-by: Yunke Cao <yunkec@google.com> > Signed-off-by: Ricardo Ribalda <ribalda@chromium.org> Thanks, new version looks good to me: Reviewed-by: Hans de Goede <hdegoede@redhat.com> Regards, Hans > --- > .../userspace-api/media/drivers/uvcvideo.rst | 64 ++++++++++++++++++++++ > 1 file changed, 64 insertions(+) > > diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst > index a290f9fadae9..dbb30ad389ae 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,66 @@ 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 using 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. > + > + 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. > + > + An example of use of this control, can be found in the: > + `Chrome OS USB camera HAL. > + <https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/release-R121-15699.B/camera/hal/usb/>` > + > + > +``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 bit causes automatic exposure to track the region of > + interest instead of the whole image. > + * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_IRIS`` > + - Setting this bit causes automatic iris to track the region of interest > + instead of the whole image. > + * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_WHITE_BALANCE`` > + - Setting this bit causes automatic white balance to track the region > + of interest instead of the whole image. > + * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FOCUS`` > + - Setting this bit 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 bit 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 bit 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 bit 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 bit enables automatically capture the specified region > + with higher quality if possible. >
diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst index a290f9fadae9..dbb30ad389ae 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,66 @@ 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 using 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. + + 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. + + An example of use of this control, can be found in the: + `Chrome OS USB camera HAL. + <https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/release-R121-15699.B/camera/hal/usb/>` + + +``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 bit causes automatic exposure to track the region of + interest instead of the whole image. + * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_IRIS`` + - Setting this bit causes automatic iris to track the region of interest + instead of the whole image. + * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_WHITE_BALANCE`` + - Setting this bit causes automatic white balance to track the region + of interest instead of the whole image. + * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FOCUS`` + - Setting this bit 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 bit 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 bit 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 bit 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 bit enables automatically capture the specified region + with higher quality if possible.