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

[Mirela Rabulea <mirela.rabulea@nxp.com>]

Hi Sakari,

On 03.02.2025 10:58, Sakari Ailus wrote:
> Caution: This is an external email. Please take care when clicking links or opening attachments. When in doubt, report the message using the 'Report this email' button
>
>
> 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.
> +

Ok, so it is clear now, the V4L2_CID_COLOUR_PATTERN stands for the 
"native colour pattern", as opposed to the "readout pattern". It is good 
to make the distinction.

Maybe the V4L2_CID_COLOUR_PATTERN control description in patch #7 could 
also be made more clear with regards to native vs readout pattern?

"This control determines the colour components and pixel order in the 
sensor's CFA (Colour Filter Array)..." => "This control reports the 
colour components and native pixel order in the sensor's CFA (Colour 
Filter Array)..." ?

Thanks,

Mirela

>   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
>