[RFC v5 11/15] media: Documentation: Document luma-only mbus codes and CFA for cameras

Sakari Ailus
2025-02-03T08:59:51Z

Document the use of luma-only mbus codes for camera sensors and how the
V4L2_CID_COLOUR_PATTERN and V4L2_CID_COLOUR_PATTERN_FLIP controls are used
to convey the colour filter array pattern on UAPI.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
.../userspace-api/media/drivers/camera-sensor.rst | 13 +++++++++++++
.../media/v4l/ext-ctrls-image-source.rst | 4 ++++
2 files changed, 17 insertions(+)

diff --git a/Documentation/userspace-api/media/drivers/camera-sensor.rst b/Documentation/userspace-api/media/drivers/camera-sensor.rst
index 5bc4c79d230c..91e5305458b9 100644
--- a/Documentation/userspace-api/media/drivers/camera-sensor.rst
+++ b/Documentation/userspace-api/media/drivers/camera-sensor.rst
@@ -41,6 +41,19 @@ format set on a source pad at the end of the device's internal pipeline.

Most sensor drivers are implemented this way.

+V4L2_CID_COLOUR_PATTERN, luma-only mbus formats, flipping and cropping
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For raw image data originating from camera sensors, :ref:`luma-only mbus codes
+MEDIA_BUS_FMT_Yx_1Xx (where 'x' is the bit depth) <v4l2-mbus-pixelcode-yuv8>`
+are used as Colour Filter Array (CFA) agnostic raw formats. The
+``V4L2_CID_COLOUR_PATTERN <image-source-control-colour-pattern>`` control in the
+same sub-device defines the native colour pattern of the device. Flipping may
+further affect the readout pattern as indicated by the
+``V4L2_CID_COLOUR_PATTERN_FLIP <image-source-control-colour-pattern-flip>``
+control. Further on, cropping also has an effect on the pattern if cropped
+amount is not divisible by the size of the pattern, horizontally and vertically.
+
Frame interval configuration
----------------------------

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 ecfa38c118e3..4b98a740236a 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
@@ -93,6 +93,8 @@ Image Source Control IDs
is reported as being (say) 128, then a value of 192 would represent
a gain of exactly 1.5.

+.. _image-source-control-colour-pattern:
+
``V4L2_CID_COLOUR_PATTERN (integer)``
This control determines the colour components and pixel order in the
sensor's CFA (Colour Filter Array) when used in conjunction with
@@ -103,6 +105,8 @@ Image Source Control IDs

This is a read-only control.

+.. _image-source-control-colour-pattern-flip:
+
``V4L2_CID_COLOUR_PATTERN_FLIP (bitmask)``
Whether the horizontal or vertical flipping controls (V4L2_CID_HFLIP and
V4L2_CID_VFLIP) have an effect on the pixel order of the output colour
--
2.39.5