| Message ID | 20230704123819.156418-3-jacopo.mondi@ideasonboard.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Documentation: v4l: more camera sensor doc | expand |
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 >
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 +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.
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(+)