[v2,1/2] Documentation: v4l: Flip handling for RAW sensors
Commit Message
Document the requirement of notifying to userspace the possible
re-ordering of the color sample components when a vertical or horizontal
flip is applied to a RAW camera sensor.
Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
---
Documentation/driver-api/media/camera-sensor.rst | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
Comments
On Tue, 4 Jul 2023 at 13:38, Jacopo Mondi <jacopo.mondi@ideasonboard.com> wrote:
>
> Document the requirement of notifying to userspace the possible
> re-ordering of the color sample components when a vertical or horizontal
> flip is applied to a RAW camera sensor.
>
> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> ---
> Documentation/driver-api/media/camera-sensor.rst | 16 ++++++++++++++++
> 1 file changed, 16 insertions(+)
>
> diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
> index 93f4f2536c25..7516d61a903d 100644
> --- a/Documentation/driver-api/media/camera-sensor.rst
> +++ b/Documentation/driver-api/media/camera-sensor.rst
> @@ -173,3 +173,19 @@ V4L2_CID_VFLIP controls with the 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.
> +
> +Flip handling for raw camera color sensors
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Applying vertical and horizontal flips on raw camera sensors inverts the color
> +sample reading direction on the sensor's pixel array. This may cause the
> +re-ordering of the color samples on the sensor's output frame. As an example, a
> +raw camera sensor with a Bayer pattern color filter array with a native RGGB
> +Bayer order will produce frames with GRBG component ordering when an horizontal
> +flip is applied. Camera sensor drivers where inverting the reading order
> +direction causes a re-ordering of the color components are requested to register
requested or required?
I'm not that fussed either way, just down to how strict you want the spec to be.
Reviewed-by: Dave Stevenson <dave.stevenson@raspberrypi.com>
> +the ``V4L2_CID_VFLIP`` and ``V4L2_CID_HFLIP`` controls with the
> +``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag enabled to notify userspace that enabling
> +a flip can potentially change the output buffer content layout. Flips should
> +also be taken into account when enumerating and handling media bus formats
> +on the camera sensor source pads.
> --
> 2.40.1
>
@@ -173,3 +173,19 @@ V4L2_CID_VFLIP controls with the 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.
+
+Flip handling for raw camera color sensors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Applying vertical and horizontal flips on raw camera sensors inverts the color
+sample reading direction on the sensor's pixel array. This may cause the
+re-ordering of the color samples on the sensor's output frame. As an example, a
+raw camera sensor with a Bayer pattern color filter array with a native RGGB
+Bayer order will produce frames with GRBG component ordering when an horizontal
+flip is applied. Camera sensor drivers where inverting the reading order
+direction causes a re-ordering of the color components are requested to register
+the ``V4L2_CID_VFLIP`` and ``V4L2_CID_HFLIP`` controls with the
+``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag enabled to notify userspace that enabling
+a flip can potentially change the output buffer content layout. Flips should
+also be taken into account when enumerating and handling media bus formats
+on the camera sensor source pads.