[v2,2/2] Documentation: v4l: Exposure/gain for camera sensor
Commit Message
Document the suggested way to exposure controls for exposure and gain
for camera sensor drivers.
Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
---
.../driver-api/media/camera-sensor.rst | 27 +++++++++++++++++++
1 file changed, 27 insertions(+)
Comments
On Tue, 4 Jul 2023 at 13:38, Jacopo Mondi <jacopo.mondi@ideasonboard.com> wrote:
>
> Document the suggested way to exposure controls for exposure and gain
> for camera sensor drivers.
>
> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> ---
> .../driver-api/media/camera-sensor.rst | 27 +++++++++++++++++++
> 1 file changed, 27 insertions(+)
>
> diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
> index 7516d61a903d..fb70d55f6671 100644
> --- a/Documentation/driver-api/media/camera-sensor.rst
> +++ b/Documentation/driver-api/media/camera-sensor.rst
> @@ -189,3 +189,30 @@ the ``V4L2_CID_VFLIP`` and ``V4L2_CID_HFLIP`` controls with the
> 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.
> +
> +Exposure and Gain Control
> +-------------------------
> +
> +Camera sensor drivers that allow applications to control the image exposure
> +and gain should do so by exposing dedicated controls to applications.
> +
> +Exposure time is controlled by registering the ``V4L2_CID_EXPOSURE`` control.
> +The control definition does not specify a unit to allow maximum flexibility
> +for multiple device types, but when used for camera sensor drivers it should be
> +expressed in unit of lines whenever possible.
> +
> +To convert lines into units of time, the total line length (visible and
> +not visible pixels) has to be divided by the pixel rate::
> +
> + line duration = total line length / pixel rate
> + = (image width + horizontal blanking) / pixel rate
> +
> +Camera sensor driver should try whenever possible to distinguish between the
> +analogue and digital gain control functions. Analogue gain is a multiplier
nit: multiplication factor
> +factor applied to all color channels on the pixel array before they get
> +converted in the digital domain. It should be made controllable by
nit: converted into the digital domain
> +registering the ``V4L2_CID_ANALOGUE_GAIN`` control, expressed as a device
> +specific gain code. Digital gain control is optional and should be exposed to
> +applications by registering ``V4L2_CID_DIGITAL_GAIN``. Camera sensor drivers are
> +discouraged from using ``V4L2_CID_GAIN`` as it doesn't allow differentiation of
> +analogue vs digital gain.
Sorry to have missed those first time around. With or without:
Reviewed-by: Dave Stevenson <dave.stevenson@raspberrypi.com>
> --
> 2.40.1
>
@@ -189,3 +189,30 @@ the ``V4L2_CID_VFLIP`` and ``V4L2_CID_HFLIP`` controls with the
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.
+
+Exposure and Gain Control
+-------------------------
+
+Camera sensor drivers that allow applications to control the image exposure
+and gain should do so by exposing dedicated controls to applications.
+
+Exposure time is controlled by registering the ``V4L2_CID_EXPOSURE`` control.
+The control definition does not specify a unit to allow maximum flexibility
+for multiple device types, but when used for camera sensor drivers it should be
+expressed in unit of lines whenever possible.
+
+To convert lines into units of time, the total line length (visible and
+not visible pixels) has to be divided by the pixel rate::
+
+ line duration = total line length / pixel rate
+ = (image width + horizontal blanking) / pixel rate
+
+Camera sensor driver should try whenever possible to distinguish between the
+analogue and digital gain control functions. Analogue gain is a multiplier
+factor applied to all color channels on the pixel array before they get
+converted in the digital domain. It should be made controllable by
+registering the ``V4L2_CID_ANALOGUE_GAIN`` control, expressed as a device
+specific gain code. Digital gain control is optional and should be exposed to
+applications by registering ``V4L2_CID_DIGITAL_GAIN``. Camera sensor drivers are
+discouraged from using ``V4L2_CID_GAIN`` as it doesn't allow differentiation of
+analogue vs digital gain.