[PATCH v12 28/86] media: uapi: Add controls for sub-sampling configuration

Sakari Ailus
2026-04-09T20:15:29Z

Sub-sampling is a way to decrease the data rates after the pixel array by
systematically discarding some samples, either vertically or horizontally
or both. Add two controls for the purpose and document them. The
sub-sampling configuration is taken into account in the compose rectangle.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
---
.../media/drivers/camera-sensor.rst | 16 +++++++++++++---
.../media/v4l/ext-ctrls-image-source.rst | 11 +++++++++++
drivers/media/v4l2-core/v4l2-ctrls-defs.c | 2 ++
include/uapi/linux/v4l2-controls.h | 2 ++
4 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/Documentation/userspace-api/media/drivers/camera-sensor.rst b/Documentation/userspace-api/media/drivers/camera-sensor.rst
index 12f075379bc8..aa05681c7090 100644
--- a/Documentation/userspace-api/media/drivers/camera-sensor.rst
+++ b/Documentation/userspace-api/media/drivers/camera-sensor.rst
@@ -120,8 +120,8 @@ values programmed by the register sequences. The default values of these
controls shall be 0 (disabled). Especially these controls shall not be inverted,
independently of the sensor's mounting rotation.

-Binning
--------
+Binning and sub-sampling
+------------------------

Binning has traditionally been configured using :ref:`the compose selection
rectangle <v4l2-selection-targets-table>`. The :ref:`V4L2_CID_BINNING
@@ -130,7 +130,17 @@ configuration and users should use it when it's available. Drivers supporting
the control shall also support the compose rectangle, albeit the rectangle may
be read-only when the control is present.

-Binning isn't affected by flipping.
+Sub-sampling is often supported as part of a camera sensor's binning
+functionality and performed after the binning operation. Sub-sampling typically
+produces quality-wise worse results than binning. Sub-sampling factors are
+independent horizontally and vertically and they are controlled using two
+controls, :ref:`V4L2_CID_SUBSAMPLING_HORIZONTAL and
+V4L2_CID_SUBSAMPLING_VERTICAL <image_source_control_subsampling>`. In
+sub-sampling, the image size before sub-sampling is horizontally and vertically
+divided by the respective sub-sampling factors. Drivers supporting the control shall
+also reflect the sub-sampling configuration in the compose rectangle.
+
+Binning and sub-sampling aren't affected by flipping.

.. _media_using_camera_sensor_drivers_embedded_data:

diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
index 0ef76b02a6e1..63e53c883db6 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
@@ -190,3 +190,14 @@ Image Source Control IDs

For instance, a value of ``0x0001000300020003`` indicates binning by 3
(horizontally) * 3/2 (vertically).
+
+.. _image_source_control_subsampling:
+
+``V4L2_CID_SUBSAMPLING_HORIZONTAL`` and ``V4L2_CID_SUBSAMPLING_VERTICAL``
+(integer)
+
+ Horizontal and vertical subsampling factors.
+
+ Sub-sampling is used to downscale an image, horizontally and vertically, by
+ discarding a part of the image data. Typically sub-sampling produces lower
+ quality images than binning.
diff --git a/drivers/media/v4l2-core/v4l2-ctrls-defs.c b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
index fee343667b69..227bcb5a549d 100644
--- a/drivers/media/v4l2-core/v4l2-ctrls-defs.c
+++ b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
@@ -1161,6 +1161,8 @@ const char *v4l2_ctrl_get_name(u32 id)
case V4L2_CID_CFA_PATTERN_FLIP: return "CFA Pattern Flip";
case V4L2_CID_METADATA_LAYOUT: return "Metadata Layout";
case V4L2_CID_BINNING_FACTORS: return "Binning Factors";
+ case V4L2_CID_SUBSAMPLING_HORIZONTAL: return "Sub-Sampling Factor, Horizontal";
+ case V4L2_CID_SUBSAMPLING_VERTICAL: return "Sub-Sampling Factor, Vertical";

/* Image processing controls */
/* Keep the order of the 'case's the same as in v4l2-controls.h! */
diff --git a/include/uapi/linux/v4l2-controls.h b/include/uapi/linux/v4l2-controls.h
index 5496b1664432..acb6f9ad4d1b 100644
--- a/include/uapi/linux/v4l2-controls.h
+++ b/include/uapi/linux/v4l2-controls.h
@@ -1250,6 +1250,8 @@ enum v4l2_jpeg_chroma_subsampling {
#define V4L2_CID_METADATA_LAYOUT (V4L2_CID_IMAGE_SOURCE_CLASS_BASE + 12)

#define V4L2_CID_BINNING_FACTORS (V4L2_CID_IMAGE_SOURCE_CLASS_BASE + 13)
+#define V4L2_CID_SUBSAMPLING_HORIZONTAL (V4L2_CID_IMAGE_SOURCE_CLASS_BASE + 14)
+#define V4L2_CID_SUBSAMPLING_VERTICAL (V4L2_CID_IMAGE_SOURCE_CLASS_BASE + 15)

/* Image processing controls */

--
2.47.3