Add V4L2_CID_BINNING control for configuting binning and enumerating a
camera sensor's binning capabilities. The control combines horizontal and
vertical binning into a single control as the two are generally related.
New drivers should use this control to configure binning.
Signed-off-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx>
---
.../media/drivers/camera-sensor.rst | 10 +++++++
.../media/v4l/ext-ctrls-camera.rst | 29 +++++++++++++++++++
drivers/media/v4l2-core/v4l2-ctrls-defs.c | 2 ++
include/uapi/linux/v4l2-controls.h | 1 +
4 files changed, 42 insertions(+)
diff --git a/Documentation/userspace-api/media/drivers/camera-sensor.rst b/Documentation/userspace-api/media/drivers/camera-sensor.rst
index 5bc4c79d230c..c6167c91f46c 100644
--- a/Documentation/userspace-api/media/drivers/camera-sensor.rst
+++ b/Documentation/userspace-api/media/drivers/camera-sensor.rst
@@ -107,6 +107,16 @@ 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 has traditionally been configured using :ref:`the compose selection
+rectangle <v4l2-selection-targets-table>`. The :ref:`V4L2_CID_BINNING
+<v4l2-cid-camera-sensor-binning>` is also available for binning 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.
+
.. _media_using_camera_sensor_drivers_embedded_data:
Embedded data
diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst
index cdc515c60468..3fbab0e78719 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst
@@ -672,3 +672,32 @@ enum v4l2_scene_mode -
As modes differ for each sensor, menu items are not standardized by this
control and are left to the programmer.
+
+.. _v4l2-cid-camera-sensor-binning:
+
+``V4L2_CID_BINNING (integer menu)``
+
+ Horizontal and vertical binning factors. Binning combines several
+ horizontal, vertical or both pixel values into a single pixel. It is a way
+ to scale an image. Binning typically produces fairly good quality output.
+
+ Determines both horizontal and vertical binning factors for a camera
+ sensor. The values are encoded in the following way:
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Bits
+ - Synopsis
+ * - 48--63
+ - Horizontal binning numerator.
+ * - 32--47
+ - Horizontal binning denominator.
+ * - 16--31
+ - Vertical binning numerator.
+ * - 0--15
+ - Vertical binning denominator.
+
+For instance, a value of ``0x0001000300020003`` indicates binning by 3
+(horizontally) * 3/2 (vertically).
diff --git a/drivers/media/v4l2-core/v4l2-ctrls-defs.c b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
index 24c9c25e20d1..3a84051ec11c 100644
--- a/drivers/media/v4l2-core/v4l2-ctrls-defs.c
+++ b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
@@ -1087,6 +1087,7 @@ const char *v4l2_ctrl_get_name(u32 id)
case V4L2_CID_CAMERA_ORIENTATION: return "Camera Orientation";
case V4L2_CID_CAMERA_SENSOR_ROTATION: return "Camera Sensor Rotation";
case V4L2_CID_HDR_SENSOR_MODE: return "HDR Sensor Mode";
+ case V4L2_CID_BINNING: return "Binning Factors";
/* FM Radio Modulator controls */
/* Keep the order of the 'case's the same as in v4l2-controls.h! */
@@ -1424,6 +1425,7 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
case V4L2_CID_HDR_SENSOR_MODE:
*type = V4L2_CTRL_TYPE_MENU;
break;
+ case V4L2_CID_BINNING:
case V4L2_CID_LINK_FREQ:
*type = V4L2_CTRL_TYPE_INTEGER_MENU;
break;
diff --git a/include/uapi/linux/v4l2-controls.h b/include/uapi/linux/v4l2-controls.h
index 0152240229ab..8d5815a058d7 100644
--- a/include/uapi/linux/v4l2-controls.h
+++ b/include/uapi/linux/v4l2-controls.h
@@ -1088,6 +1088,7 @@ enum v4l2_auto_focus_range {
#define V4L2_CID_CAMERA_SENSOR_ROTATION (V4L2_CID_CAMERA_CLASS_BASE+35)
#define V4L2_CID_HDR_SENSOR_MODE (V4L2_CID_CAMERA_CLASS_BASE+36)
+#define V4L2_CID_BINNING_FACTORS (V4L2_CID_CAMERA_CLASS_BASE+37)
/* FM Modulator class control IDs */
--
2.39.5
