[RFC v5 15/15] media: Documentation: Add binning and sub-sampling controls

Sakari Ailus
2025-02-03T09:00:05Z

Document the binning and scaling controls (V4L2_CID_BINNING and
V4L2_CID_SUBSAMPLING_{HORIZONTAL,VERTICAL}) in the common raw sensor
model.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
---
.../media/v4l/subdev-config-model.rst | 20 ++++++++++++++-----
1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/Documentation/userspace-api/media/v4l/subdev-config-model.rst b/Documentation/userspace-api/media/v4l/subdev-config-model.rst
index f15e5495cc34..84957dc62800 100644
--- a/Documentation/userspace-api/media/v4l/subdev-config-model.rst
+++ b/Documentation/userspace-api/media/v4l/subdev-config-model.rst
@@ -113,8 +113,12 @@ separately horizontally and vertically.

Binning and sub-sampling are configured using the ``V4L2_SEL_TGT_COMPOSE``
rectangle, relative to the analogue crop rectangle, on (pad, stream) pair
-1/0. The driver implementation determines how to configure binning and
-sub-sampling to achieve the desired size.
+1/0. It depends on the driver which of these operations are being used to
+achieve the resulting size. Binning and sub-sampling are also directly
+configured using :ref:`V4L2_CID_BINNING_FACTORS
+<v4l2-cid-camera-sensor-binning>` and :ref:`V4L2_CID_SUBSAMPLING_HORIZONTAL and
+V4L2_CID_SUBSAMPLING_VERTICAL <v4l2-cid-camera-sensor-subsampling>` controls on
+drivers that support them.

The digital crop operation takes place after binning and sub-sampling. It is
configured by setting the ``V4L2_SEL_TGT_CROP`` rectangle on (pad, stream) pair
@@ -173,9 +177,15 @@ Also refer to :ref:`Selection targets <v4l2-selection-targets-table>`.
- \-
- X
- Binning and sub-sampling. This rectangle is relative to the
- ``V4L2_SEL_TGT_CROP`` rectangle on the same (pad, stream). The
- combination of binning and sub-sampling is configured using this
- selection target.
+ ``V4L2_SEL_TGT_CROP`` rectangle on the same (pad, stream). Binning is
+ configured using the :ref:`V4L2_CID_BINNING_FACTORS
+ <v4l2-cid-camera-sensor-binning>` control and sub-sampling is configured
+ using the :ref:`V4L2_CID_SUBSAMPLING_HORIZONTAL and
+ V4L2_CID_SUBSAMPLING_VERTICAL <v4l2-cid-camera-sensor-subsampling>`
+ controls on drivers that support these controls. To configure binning
+ and sub-sampling on drivers that do not support these controls, the
+ selection rectangle may be changed directly to configure the combined
+ effect on the image size.
* - 2/0
- Format
- X
--
2.39.5