[PATCH 1/3] media: uapi: Introduce new control for video encoder ROI
From: Deepa Guthyappa Madivalara
Date: Tue Jun 16 2026 - 19:40:56 EST
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 ++++++++++++++
include/media/v4l2-ctrls.h | 1 +
include/uapi/linux/v4l2-controls.h | 2 ++
include/uapi/linux/videodev2.h | 3 +++
4 files changed, 20 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)``
+ This custom control is used to set ROI MB map delta_Qp for whole frame.
+ The frame is divided into grid with MB Size returned from querying
+ 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.
+
.. raw:: latex
\normalsize
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..ce217c41c471042eb9b920532a4102a87c991d5b 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;
@@ -1993,6 +1994,8 @@ 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,
+
+ V4L2_CTRL_TYPE_S8 = 0x284,
};
/* Used in the VIDIOC_QUERYCTRL ioctl for querying controls */
--
2.34.1