Re: [PATCH v2 1/3] media: uapi: Introduce new control for video encoder ROI

From: Deepa Guthyappa Madivalara

Date: Thu Jul 16 2026 - 18:01:26 EST

On 7/15/2026 1:25 AM, Hans Verkuil wrote:

On 14/07/2026 21:00, Deepa Guthyappa Madivalara wrote:

Add custom control, V4L2_CID_MPEG_VIDEO_ROI_MB_DELTA_QP for
video encoder Region of Interest to allow applications to specify
different quality levels for specific regions in video frames. Define
V4L2_CID_MPEG_VIDEO_ROI_MB_SIZE to retrieve supported MB size based on
codec from the hardware encoder and set the corresponding ROI MB delta_qp
map that adjusts quantization relative to the frame QP's base value.

This enables use cases like prioritizing quality for faces in video
conferencing or important objects in surveillance footage while reducing
bitrate for less critical areas.

Signed-off-by: Deepa Guthyappa Madivalara <deepa.madivalara@xxxxxxxxxxxxxxxx>
---
Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst | 14 ++++++++++++++
.../userspace-api/media/v4l/videodev2.h.rst.exceptions | 1 +
.../userspace-api/media/v4l/vidioc-g-ext-ctrls.rst | 4 ++++
Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst | 6 ++++++
include/media/v4l2-ctrls.h | 1 +
include/uapi/linux/v4l2-controls.h | 2 ++
include/uapi/linux/videodev2.h | 3 +++
7 files changed, 31 insertions(+)

diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
index ab865a1a6ba929f1725ce2ab0fd3aeee4a69329a..1995e7335fb29611151c61561df577f2bdac7a48 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
@@ -1674,6 +1674,20 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type -
Codecs need to always use the specified range, rather then a HW custom range.
Applicable to encoders
+``V4L2_CID_MPEG_VIDEO_ROI_MB_DELTA_QP (integer)``
integer -> __s8

sorry, will update this in v3.

+ This custom control is used to set ROI MB map delta_Qp for whole frame.

Why is this a 'custom' control? This looks like a standard control to me.
Or do you perhaps mean that the value is HW dependent?

The array size is dependent on the max resolution reported by the hardware,
hence its defined as custom control with a dynamic array as input.

+ The frame is divided into grid with MB Size returned from querying

The frame is divided into a grid of MB Size by MB Size pixels (MB Size is
obtained from querying ``V4L2_CID_MPEG_VIDEO_ROI_MB_SIZE``).

More clear, thanks, will update this in v3.

+ V4L2_CID_MPEG_VIDEO_ROI_MB_SIZE. Each block is configured with delta_Qp
+ in raster order. The valid range for delta_Qp is encoder dependent.
+ Applicable to encoders.
+
+``V4L2_CID_MPEG_VIDEO_ROI_MB_SIZE (integer)``
+ This read-only control returns the MB Size for ROI MB delta_Qp map.
+ Its valid range depends on encoder supported codec format.
+ Example: For H.264, 16 is returned for 16x16 MB size.
+ For HEVC, 32 is returned for 32x32 MB size.
+ Depending on the size returned, delta_Qp Map is set to the encoder.

Sorry, it's not clear what you mean with that last sentence.

Is it possible to have codecs with non-square macroblocks? E.g. 32x16?

Regards,

Hans

No, only square Mbs are supported. If supported MBSize is returned as 16 for a
Qcif, the expected delta_Qp array size is 99(176x144/16x16).
I will update the documentation in v3.

+
.. raw:: latex
\normalsize
diff --git a/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions
index 6182b4e2d2ee002c0d3562e1cc3bc2fd9c4286d6..b036ed3ec2f0744175cad1cbc4e73fe828e0c955 100644
--- a/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions
+++ b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions
@@ -141,6 +141,7 @@ replace symbol V4L2_CTRL_TYPE_STRING :c:type:`V4L.v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_U16 :c:type:`V4L.v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_U32 :c:type:`V4L.v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_U8 :c:type:`V4L.v4l2_ctrl_type`
+replace symbol V4L2_CTRL_TYPE_S8 :c:type:`V4L.v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_MPEG2_SEQUENCE :c:type:`V4L.v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_MPEG2_PICTURE :c:type:`V4L.v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTISATION :c:type:`V4L.v4l2_ctrl_type`
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
index b8698b85bd808979fc590715125f689880e5a30e..8d5eec357509700c9a582b98c14843bb5e483be0 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
@@ -185,6 +185,10 @@ still cause this situation.
- ``p_u32``
- A pointer to a matrix control of unsigned 32-bit values. Valid if
this control is of type ``V4L2_CTRL_TYPE_U32``.
+ * - __s8 *
+ - ``p_s8``
+ - A pointer to a matrix control of signed 8-bit values. Valid if
+ this control is of type ``V4L2_CTRL_TYPE_S8``.
* - __s32 *
- ``p_s32``
- A pointer to a matrix control of signed 32-bit values. Valid if
diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
index 82c8b52e771ce9301491b3f752e501a8fe7e2434..57e1652ae72e0324742142446acf32a16b94941c 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
@@ -425,6 +425,12 @@ See also the examples in :ref:`control`.
- any
- An unsigned 32-bit valued control ranging from minimum to maximum
inclusive. The step value indicates the increment between values.
+ * - ``V4L2_CTRL_TYPE_S8``
+ - any
+ - any
+ - any
+ - A signed 8-bit valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
* - ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``
- n/a
- n/a
diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index 327976b14d50b73a631e4d2ed95d9f4d146c45ab..a1806ddbc797efa52e83cd3f685ef70d5b5483d2 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -64,6 +64,7 @@ union v4l2_ctrl_ptr {
s32 *p_s32;
s64 *p_s64;
u8 *p_u8;
+ s8 *p_s8;
u16 *p_u16;
u32 *p_u32;
char *p_char;
diff --git a/include/uapi/linux/v4l2-controls.h b/include/uapi/linux/v4l2-controls.h
index affec0ab4781507be761cb791ff737460acf9cb7..00a2c48630bd198faa9a2b833a9aa346d8357555 100644
--- a/include/uapi/linux/v4l2-controls.h
+++ b/include/uapi/linux/v4l2-controls.h
@@ -920,6 +920,8 @@ enum v4l2_mpeg_video_av1_level {
};
#define V4L2_CID_MPEG_VIDEO_AVERAGE_QP (V4L2_CID_CODEC_BASE + 657)
+#define V4L2_CID_MPEG_VIDEO_ROI_MB_DELTA_QP (V4L2_CID_CODEC_BASE + 658)
+#define V4L2_CID_MPEG_VIDEO_ROI_MB_SIZE (V4L2_CID_CODEC_BASE + 659)
/* MPEG-class control IDs specific to the CX2341x driver as defined by V4L2 */
#define V4L2_CID_CODEC_CX2341X_BASE (V4L2_CTRL_CLASS_CODEC | 0x1000)
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index eda4492e40dc14a90a230601d8e23b0e13845d34..1e307781645543960e4b73ba46fdf83279fda4dd 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -1880,6 +1880,7 @@ struct v4l2_ext_control {
__s64 value64;
char __user *string;
__u8 __user *p_u8;
+ __s8 __user *p_s8;
__u16 __user *p_u16;
__u32 __user *p_u32;
__s32 __user *p_s32;
@@ -1957,6 +1958,7 @@ enum v4l2_ctrl_type {
V4L2_CTRL_TYPE_U8 = 0x0100,
V4L2_CTRL_TYPE_U16 = 0x0101,
V4L2_CTRL_TYPE_U32 = 0x0102,
+ V4L2_CTRL_TYPE_S8 = 0x0103,
V4L2_CTRL_TYPE_AREA = 0x0106,
V4L2_CTRL_TYPE_RECT = 0x0107,
@@ -1993,6 +1995,7 @@ enum v4l2_ctrl_type {
V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY = 0x281,
V4L2_CTRL_TYPE_AV1_FRAME = 0x282,
V4L2_CTRL_TYPE_AV1_FILM_GRAIN = 0x283,
+
};
/* Used in the VIDIOC_QUERYCTRL ioctl for querying controls */