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

On 8/4/2026 8:49 PM, Bryan O'Donoghue wrote:
> On 04/08/2026 21:05, 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 
>> <[email protected]>
>> ---
>>   .../userspace-api/media/v4l/ext-ctrls-codec.rst       | 19 
>> +++++++++++++++++++
>>   .../media/v4l/videodev2.h.rst.exceptions              |  1 +
>>   .../userspace-api/media/v4l/vidioc-g-ext-ctrls.rst    |  4 ++++
>>   .../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, 36 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..0f8179de8f742253a5152231592fb8b4355298f7 
>> 100644
>> --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
>> +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
>> @@ -1674,6 +1674,25 @@ 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 (__s8)``
>> +    This custom control is used to set ROI MB map delta_Qp for whole 
>> frame.
>
> "a whole frame" or "the whole frame"
>
Will update to "the whole frame in v4"
>> +    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``). 
>> 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)
>> +    A read-only control that reports the MB Size used for the ROI 
>> delta_QP map.
>> +    The supported MB Size depends on the encoder codec.
>> +    Only square macroblocks are supported. The value returned 
>> represents the
>
> macro-blocks ?
I will use MBs to keep it consistent. (in v4)
>
>> +    width and height of each block in pixels. The ROI delta_QP map 
>> provided
>> +    through the ROI control must use the MB Size reported by this 
>> control.
>> +    The number of entries in the ROI delta_QP array is determined by 
>> the
>> +    frame dimensions and the reported MB Size. For example, for a 
>> QCIF frame
>> +    (176x144) if reported MB Size is 16, the delta_QP array must 
>> contain
>> +    99 entries (176 x 144 / 16 x 16).
>> +
>>   .. 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 
>> d78328152b7552f8f0d30a9e2f7c104bfd4b70d3..fe5f8992389c32d8f35f432229ef2f734002644e 
>> 100644
>> --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
>> +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
>> @@ -188,6 +188,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 
>> 5373dba640fae3d19247ab1c74ba336e05dc0fe0..3ed343f8c81e0c9240d5a7e5b2dfe365a529fb6c 
>> 100644
>> --- a/include/uapi/linux/videodev2.h
>> +++ b/include/uapi/linux/videodev2.h
>> @@ -1884,6 +1884,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;
>> @@ -1961,6 +1962,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,
>>
>> @@ -1997,6 +1999,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,
>> +
>
> stray \n
>
sorry, will fix this in v4
>>   };
>>
>>   /*  Used in the VIDIOC_QUERYCTRL ioctl for querying controls */
>>
>> -- 
>> 2.34.1
>>
>