[PATCH] libcamera: controls: Improve formatting of control descriptions in YAML
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Mon Aug 12 12:43:51 CEST 2024
Hi Milan,
On Mon, Aug 12, 2024 at 09:07:59AM +0200, Milan Zamazal wrote:
> Laurent Pinchart <laurent.pinchart at ideasonboard.com> writes:
>
> > The control descriptions from YAML files are extracted to generate
> > Doxygen documentation blocks for the controls, which are then compiled
> > to HTML. The extraction script uses the first line of the description
> > as the Doxygen \brief, and preserves blank lines to keep paragraphs.
> >
> > The control descriptions in the YAML files have however not all been
> > written with this in mind. Many description elements are not formatted
> > as block string scalars, in the first place, so blank lines are lost
> > when parsing YAML. Furthermore, they often start with a long initial
> > paragraph, making the \brief description very long.
> >
> > Improve the documentation formatting by marking all multiline
> > descriptions are block string scalars, and try to provide a short
> > one-line first paragraph to be used as a \brief. While at it, reflow the
> > documentation to the 80 columns limit.
> >
> > The draft controls are left as-is, as they should evolve to non-draft
> > controls eventually (and ideally sooner than later).
> >
> > Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
>
> Reviewed-by: Milan Zamazal <mzamazal at redhat.com>
>
> It might be worth to unify "Report" / "Reports" / "" (noun only) for
> consistency, in a followup patch.
There are countless things I'd like to improve in the documentation :-)
Once we get closer to a v1.0, I think getting a professional tech writer
to polish up the documentation in the entire code base would help. Until
then, incremental improvements are always a good idea, and I like your
suggestion.
> > ---
> > src/libcamera/control_ids_core.yaml | 466 +++++++++++++++++-----------
> > src/libcamera/control_ids_rpi.yaml | 16 +-
> > 2 files changed, 291 insertions(+), 191 deletions(-)
> >
> > diff --git a/src/libcamera/control_ids_core.yaml b/src/libcamera/control_ids_core.yaml
> > index cf40771d3896..6381970b4d28 100644
> > --- a/src/libcamera/control_ids_core.yaml
> > +++ b/src/libcamera/control_ids_core.yaml
> > @@ -32,10 +32,11 @@ controls:
> > - AeMeteringMode:
> > type: int32_t
> > description: |
> > - Specify a metering mode for the AE algorithm to use. The metering
> > - modes determine which parts of the image are used to determine the
> > - scene brightness. Metering modes may be platform specific and not
> > - all metering modes may be supported.
> > + Specify a metering mode for the AE algorithm to use.
> > +
> > + The metering modes determine which parts of the image are used to
> > + determine the scene brightness. Metering modes may be platform specific
> > + and not all metering modes may be supported.
> > enum:
> > - name: MeteringCentreWeighted
> > value: 0
> > @@ -56,33 +57,41 @@ controls:
> > - AeConstraintMode:
> > type: int32_t
> > description: |
> > - Specify a constraint mode for the AE algorithm to use. These determine
> > - how the measured scene brightness is adjusted to reach the desired
> > - target exposure. Constraint modes may be platform specific, and not
> > - all constraint modes may be supported.
> > + Specify a constraint mode for the AE algorithm to use.
> > +
> > + The constraint modes determine how the measured scene brightness is
> > + adjusted to reach the desired target exposure. Constraint modes may be
> > + platform specific, and not all constraint modes may be supported.
> > enum:
> > - name: ConstraintNormal
> > value: 0
> > - description: Default constraint mode.
> > + description: |
> > + Default constraint mode.
> > +
> > This mode aims to balance the exposure of different parts of the
> > image so as to reach a reasonable average level. However, highlights
> > in the image may appear over-exposed and lowlights may appear
> > under-exposed.
> > - name: ConstraintHighlight
> > value: 1
> > - description: Highlight constraint mode.
> > + description: |
> > + Highlight constraint mode.
> > +
> > This mode adjusts the exposure levels in order to try and avoid
> > over-exposing the brightest parts (highlights) of an image.
> > Other non-highlight parts of the image may appear under-exposed.
> > - name: ConstraintShadows
> > value: 2
> > - description: Shadows constraint mode.
> > + description: |
> > + Shadows constraint mode.
> > +
> > This mode adjusts the exposure levels in order to try and avoid
> > under-exposing the dark parts (shadows) of an image. Other normally
> > exposed parts of the image may appear over-exposed.
> > - name: ConstraintCustom
> > value: 3
> > - description: Custom constraint mode.
> > + description: |
> > + Custom constraint mode.
> >
> > # AeExposureMode needs further attention:
> > # - Auto-generate max enum value.
> > @@ -90,10 +99,11 @@ controls:
> > - AeExposureMode:
> > type: int32_t
> > description: |
> > - Specify an exposure mode for the AE algorithm to use. These specify
> > - how the desired total exposure is divided between the shutter time
> > - and the sensor's analogue gain. The exposure modes are platform
> > - specific, and not all exposure modes may be supported.
> > + Specify an exposure mode for the AE algorithm to use.
> > +
> > + The exposure modes specify how the desired total exposure is divided
> > + between the shutter time and the sensor's analogue gain. They are
> > + platform specific, and not all exposure modes may be supported.
> > enum:
> > - name: ExposureNormal
> > value: 0
> > @@ -111,8 +121,10 @@ controls:
> > - ExposureValue:
> > type: float
> > description: |
> > - Specify an Exposure Value (EV) parameter. The EV parameter will only be
> > - applied if the AE algorithm is currently enabled.
> > + Specify an Exposure Value (EV) parameter.
> > +
> > + The EV parameter will only be applied if the AE algorithm is currently
> > + enabled.
> >
> > By convention EV adjusts the exposure as log2. For example
> > EV = [-2, -1, 0.5, 0, 0.5, 1, 2] results in an exposure adjustment
> > @@ -124,7 +136,9 @@ controls:
> > type: int32_t
> > description: |
> > Exposure time (shutter speed) for the frame applied in the sensor
> > - device. This value is specified in micro-seconds.
> > + device.
> > +
> > + This value is specified in micro-seconds.
> >
> > Setting this value means that it is now fixed and the AE algorithm may
> > not change it. Setting it back to zero returns it to the control of the
> > @@ -142,6 +156,7 @@ controls:
> > type: float
> > description: |
> > Analogue gain value applied in the sensor device.
> > +
> > The value of the control specifies the gain multiplier applied to all
> > colour channels. This value cannot be lower than 1.0.
> >
> > @@ -160,9 +175,11 @@ controls:
> > - AeFlickerMode:
> > type: int32_t
> > description: |
> > - Set the flicker mode, which determines whether, and how, the AGC/AEC
> > - algorithm attempts to hide flicker effects caused by the duty cycle of
> > - artificial lighting.
> > + Set the flicker avoidance mode for AGC/AEC.
> > +
> > + The flicker mode determines whether, and how, the AGC/AEC algorithm
> > + attempts to hide flicker effects caused by the duty cycle of artificial
> > + lighting.
> >
> > Although implementation dependent, many algorithms for "flicker
> > avoidance" work by restricting this exposure time to integer multiples
> > @@ -176,16 +193,21 @@ controls:
> > enum:
> > - name: FlickerOff
> > value: 0
> > - description: No flicker avoidance is performed.
> > + description: |
> > + No flicker avoidance is performed.
> > - name: FlickerManual
> > value: 1
> > - description: Manual flicker avoidance.
> > + description: |
> > + Manual flicker avoidance.
> > +
> > Suppress flicker effects caused by lighting running with a period
> > specified by the AeFlickerPeriod control.
> > \sa AeFlickerPeriod
> > - name: FlickerAuto
> > value: 2
> > - description: Automatic flicker period detection and avoidance.
> > + description: |
> > + Automatic flicker period detection and avoidance.
> > +
> > The system will automatically determine the most likely value of
> > flicker period, and avoid flicker of this frequency. Once flicker
> > is being corrected, it is implementation dependent whether the
> > @@ -194,7 +216,9 @@ controls:
> >
> > - AeFlickerPeriod:
> > type: int32_t
> > - description: Manual flicker period in microseconds.
> > + description: |
> > + Manual flicker period in microseconds.
> > +
> > This value sets the current flicker period to avoid. It is used when
> > AeFlickerMode is set to FlickerManual.
> >
> > @@ -212,7 +236,9 @@ controls:
> >
> > - AeFlickerDetected:
> > type: int32_t
> > - description: Flicker period detected in microseconds.
> > + description: |
> > + Flicker period detected in microseconds.
> > +
> > The value reported here indicates the currently detected flicker
> > period, or zero if no flicker at all is detected.
> >
> > @@ -233,21 +259,25 @@ controls:
> > - Brightness:
> > type: float
> > description: |
> > - Specify a fixed brightness parameter. Positive values (up to 1.0)
> > - produce brighter images; negative values (up to -1.0) produce darker
> > - images and 0.0 leaves pixels unchanged.
> > + Specify a fixed brightness parameter.
> > +
> > + Positive values (up to 1.0) produce brighter images; negative values
> > + (up to -1.0) produce darker images and 0.0 leaves pixels unchanged.
> >
> > - Contrast:
> > type: float
> > description: |
> > - Specify a fixed contrast parameter. Normal contrast is given by the
> > - value 1.0; larger values produce images with more contrast.
> > + Specify a fixed contrast parameter.
> > +
> > + Normal contrast is given by the value 1.0; larger values produce images
> > + with more contrast.
> >
> > - Lux:
> > type: float
> > description: |
> > - Report an estimate of the current illuminance level in lux. The Lux
> > - control can only be returned in metadata.
> > + Report an estimate of the current illuminance level in lux.
> > +
> > + The Lux control can only be returned in metadata.
> >
> > - AwbEnable:
> > type: bool
> > @@ -262,8 +292,10 @@ controls:
> > - AwbMode:
> > type: int32_t
> > description: |
> > - Specify the range of illuminants to use for the AWB algorithm. The modes
> > - supported are platform specific, and not all modes may be supported.
> > + Specify the range of illuminants to use for the AWB algorithm.
> > +
> > + The modes supported are platform specific, and not all modes may be
> > + supported.
> > enum:
> > - name: AwbAuto
> > value: 0
> > @@ -305,37 +337,43 @@ controls:
> > type: float
> > description: |
> > Pair of gain values for the Red and Blue colour channels, in that
> > - order. ColourGains can only be applied in a Request when the AWB is
> > - disabled.
> > + order.
> > +
> > + ColourGains can only be applied in a Request when the AWB is disabled.
> >
> > \sa AwbEnable
> > size: [2]
> >
> > - ColourTemperature:
> > type: int32_t
> > - description: Report the current estimate of the colour temperature, in
> > - kelvin, for this frame. The ColourTemperature control can only be
> > - returned in metadata.
> > + description: |
> > + Report the estimate of the colour temperature for the frame, in kelvin.
> > +
> > + The ColourTemperature control can only be returned in metadata.
> >
> > - Saturation:
> > type: float
> > description: |
> > - Specify a fixed saturation parameter. Normal saturation is given by
> > - the value 1.0; larger values produce more saturated colours; 0.0
> > - produces a greyscale image.
> > + Specify a fixed saturation parameter.
> > +
> > + Normal saturation is given by the value 1.0; larger values produce more
> > + saturated colours; 0.0 produces a greyscale image.
> >
> > - SensorBlackLevels:
> > type: int32_t
> > description: |
> > - Reports the sensor black levels used for processing a frame, in the
> > - order R, Gr, Gb, B. These values are returned as numbers out of a 16-bit
> > - pixel range (as if pixels ranged from 0 to 65535). The SensorBlackLevels
> > - control can only be returned in metadata.
> > + Reports the sensor black levels used for processing a frame.
> > +
> > + The values are in the order R, Gr, Gb, B. They are returned as numbers
> > + out of a 16-bit pixel range (as if pixels ranged from 0 to 65535). The
> > + SensorBlackLevels control can only be returned in metadata.
> > size: [4]
> >
> > - Sharpness:
> > type: float
> > description: |
> > + Intensity of the sharpening applied to the image.
> > +
> > A value of 0.0 means no sharpening. The minimum value means
> > minimal sharpening, and shall be 0.0 unless the camera can't
> > disable sharpening completely. The default value shall give a
> > @@ -349,6 +387,7 @@ controls:
> > type: int32_t
> > description: |
> > Reports a Figure of Merit (FoM) to indicate how in-focus the frame is.
> > +
> > A larger FocusFoM value indicates a more in-focus frame. This singular
> > value may be based on a combination of statistics gathered from
> > multiple focus regions within an image. The number of focus regions and
> > @@ -359,11 +398,13 @@ controls:
> > - ColourCorrectionMatrix:
> > type: float
> > description: |
> > - The 3x3 matrix that converts camera RGB to sRGB within the
> > - imaging pipeline. This should describe the matrix that is used
> > - after pixels have been white-balanced, but before any gamma
> > - transformation. The 3x3 matrix is stored in conventional reading
> > - order in an array of 9 floating point values.
> > + The 3x3 matrix that converts camera RGB to sRGB within the imaging
> > + pipeline.
> > +
> > + This should describe the matrix that is used after pixels have been
> > + white-balanced, but before any gamma transformation. The 3x3 matrix is
> > + stored in conventional reading order in an array of 9 floating point
> > + values.
> >
> > size: [3,3]
> >
> > @@ -371,10 +412,12 @@ controls:
> > type: Rectangle
> > description: |
> > Sets the image portion that will be scaled to form the whole of
> > - the final output image. The (x,y) location of this rectangle is
> > - relative to the PixelArrayActiveAreas that is being used. The units
> > - remain native sensor pixels, even if the sensor is being used in
> > - a binning or skipping mode.
> > + the final output image.
> > +
> > + The (x,y) location of this rectangle is relative to the
> > + PixelArrayActiveAreas that is being used. The units remain native
> > + sensor pixels, even if the sensor is being used in a binning or
> > + skipping mode.
> >
> > This control is only present when the pipeline supports scaling. Its
> > maximum valid value is given by the properties::ScalerCropMaximum
> > @@ -401,8 +444,9 @@ controls:
> > type: int64_t
> > description: |
> > The instantaneous frame duration from start of frame exposure to start
> > - of next exposure, expressed in microseconds. This control is meant to
> > - be returned in metadata.
> > + of next exposure, expressed in microseconds.
> > +
> > + This control is meant to be returned in metadata.
> >
> > - FrameDurationLimits:
> > type: int64_t
> > @@ -444,9 +488,11 @@ controls:
> > - SensorTemperature:
> > type: float
> > description: |
> > - Temperature measure from the camera sensor in Celsius. This is typically
> > - obtained by a thermal sensor present on-die or in the camera module. The
> > - range of reported temperatures is device dependent.
> > + Temperature measure from the camera sensor in Celsius.
> > +
> > + This value is typically obtained by a thermal sensor present on-die or
> > + in the camera module. The range of reported temperatures is device
> > + dependent.
> >
> > The SensorTemperature control will only be returned in metadata if a
> > thermal sensor is present.
> > @@ -468,7 +514,7 @@ controls:
> > - AfMode:
> > type: int32_t
> > description: |
> > - Control to set the mode of the AF (autofocus) algorithm.
> > + The mode of the AF (autofocus) algorithm.
> >
> > An implementation may choose not to implement all the modes.
> >
> > @@ -476,12 +522,12 @@ controls:
> > - name: AfModeManual
> > value: 0
> > description: |
> > - The AF algorithm is in manual mode. In this mode it will never
> > - perform any action nor move the lens of its own accord, but an
> > - application can specify the desired lens position using the
> > - LensPosition control.
> > + The AF algorithm is in manual mode.
> >
> > - In this mode the AfState will always report AfStateIdle.
> > + In this mode it will never perform any action nor move the lens of
> > + its own accord, but an application can specify the desired lens
> > + position using the LensPosition control. The AfState will always
> > + report AfStateIdle.
> >
> > If the camera is started in AfModeManual, it will move the focus
> > lens to the position specified by the LensPosition control.
> > @@ -492,31 +538,34 @@ controls:
> > - name: AfModeAuto
> > value: 1
> > description: |
> > - The AF algorithm is in auto mode. This means that the algorithm
> > - will never move the lens or change state unless the AfTrigger
> > - control is used. The AfTrigger control can be used to initiate a
> > - focus scan, the results of which will be reported by AfState.
> > + The AF algorithm is in auto mode.
> >
> > - If the autofocus algorithm is moved from AfModeAuto to another
> > - mode while a scan is in progress, the scan is cancelled
> > - immediately, without waiting for the scan to finish.
> > + In this mode the algorithm will never move the lens or change state
> > + unless the AfTrigger control is used. The AfTrigger control can be
> > + used to initiate a focus scan, the results of which will be
> > + reported by AfState.
> >
> > - When first entering this mode the AfState will report
> > - AfStateIdle. When a trigger control is sent, AfState will
> > - report AfStateScanning for a period before spontaneously
> > - changing to AfStateFocused or AfStateFailed, depending on
> > - the outcome of the scan. It will remain in this state until
> > - another scan is initiated by the AfTrigger control. If a scan is
> > - cancelled (without changing to another mode), AfState will return
> > - to AfStateIdle.
> > + If the autofocus algorithm is moved from AfModeAuto to another mode
> > + while a scan is in progress, the scan is cancelled immediately,
> > + without waiting for the scan to finish.
> > +
> > + When first entering this mode the AfState will report AfStateIdle.
> > + When a trigger control is sent, AfState will report AfStateScanning
> > + for a period before spontaneously changing to AfStateFocused or
> > + AfStateFailed, depending on the outcome of the scan. It will remain
> > + in this state until another scan is initiated by the AfTrigger
> > + control. If a scan is cancelled (without changing to another mode),
> > + AfState will return to AfStateIdle.
> > - name: AfModeContinuous
> > value: 2
> > description: |
> > - The AF algorithm is in continuous mode. This means that the lens can
> > - re-start a scan spontaneously at any moment, without any user
> > - intervention. The AfState still reports whether the algorithm is
> > - currently scanning or not, though the application has no ability to
> > - initiate or cancel scans, nor to move the lens for itself.
> > + The AF algorithm is in continuous mode.
> > +
> > + In this mode the lens can re-start a scan spontaneously at any
> > + moment, without any user intervention. The AfState still reports
> > + whether the algorithm is currently scanning or not, though the
> > + application has no ability to initiate or cancel scans, nor to move
> > + the lens for itself.
> >
> > However, applications can pause the AF algorithm from continuously
> > scanning by using the AfPause control. This allows video or still
> > @@ -529,34 +578,40 @@ controls:
> > - AfRange:
> > type: int32_t
> > description: |
> > - Control to set the range of focus distances that is scanned. An
> > - implementation may choose not to implement all the options here.
> > + The range of focus distances that is scanned.
> > +
> > + An implementation may choose not to implement all the options here.
> > enum:
> > - name: AfRangeNormal
> > value: 0
> > description: |
> > - A wide range of focus distances is scanned, all the way from
> > - infinity down to close distances, though depending on the
> > - implementation, possibly not including the very closest macro
> > - positions.
> > + A wide range of focus distances is scanned.
> > +
> > + Scanned distances cover all the way from infinity down to close
> > + distances, though depending on the implementation, possibly not
> > + including the very closest macro positions.
> > - name: AfRangeMacro
> > value: 1
> > - description: Only close distances are scanned.
> > + description: |
> > + Only close distances are scanned.
> > - name: AfRangeFull
> > value: 2
> > description: |
> > - The full range of focus distances is scanned just as with
> > - AfRangeNormal but this time including the very closest macro
> > - positions.
> > + The full range of focus distances is scanned.
> > +
> > + This range is similar to AfRangeNormal but includes the very
> > + closest macro positions.
> >
> > - AfSpeed:
> > type: int32_t
> > description: |
> > - Control that determines whether the AF algorithm is to move the lens
> > - as quickly as possible or more steadily. For example, during video
> > - recording it may be desirable not to move the lens too abruptly, but
> > - when in a preview mode (waiting for a still capture) it may be
> > - helpful to move the lens as quickly as is reasonably possible.
> > + Determine whether the AF is to move the lens as quickly as possible or
> > + more steadily.
> > +
> > + For example, during video recording it may be desirable not to move the
> > + lens too abruptly, but when in a preview mode (waiting for a still
> > + capture) it may be helpful to move the lens as quickly as is reasonably
> > + possible.
> > enum:
> > - name: AfSpeedNormal
> > value: 0
> > @@ -568,25 +623,27 @@ controls:
> > - AfMetering:
> > type: int32_t
> > description: |
> > - Instruct the AF algorithm how it should decide which parts of the image
> > - should be used to measure focus.
> > + The parts of the image used by the AF algorithm to measure focus.
> > enum:
> > - name: AfMeteringAuto
> > value: 0
> > - description: The AF algorithm should decide for itself where it will
> > - measure focus.
> > + description: |
> > + Let the AF algorithm decide for itself where it will measure focus.
> > - name: AfMeteringWindows
> > value: 1
> > - description: The AF algorithm should use the rectangles defined by
> > - the AfWindows control to measure focus. If no windows are specified
> > - the behaviour is platform dependent.
> > + description: |
> > + Use the rectangles defined by the AfWindows control to measure focus.
> > +
> > + If no windows are specified the behaviour is platform dependent.
> >
> > - AfWindows:
> > type: Rectangle
> > description: |
> > - Sets the focus windows used by the AF algorithm when AfMetering is set
> > - to AfMeteringWindows. The units used are pixels within the rectangle
> > - returned by the ScalerCropMaximum property.
> > + The focus windows used by the AF algorithm when AfMetering is set to
> > + AfMeteringWindows.
> > +
> > + The units used are pixels within the rectangle returned by the
> > + ScalerCropMaximum property.
> >
> > In order to be activated, a rectangle must be programmed with non-zero
> > width and height. Internally, these rectangles are intersected with the
> > @@ -611,23 +668,33 @@ controls:
> > - AfTrigger:
> > type: int32_t
> > description: |
> > - This control starts an autofocus scan when AfMode is set to AfModeAuto,
> > - and can also be used to terminate a scan early.
> > + Start an autofocus scan.
> >
> > - It is ignored if AfMode is set to AfModeManual or AfModeContinuous.
> > + This control starts an autofocus scan when AfMode is set to AfModeAuto,
> > + and is ignored if AfMode is set to AfModeManual or AfModeContinuous. It
> > + can also be used to terminate a scan early.
> >
> > enum:
> > - name: AfTriggerStart
> > value: 0
> > - description: Start an AF scan. Ignored if a scan is in progress.
> > + description: |
> > + Start an AF scan.
> > +
> > + Setting the control to AfTriggerStart is ignored if a scan is in
> > + progress.
> > - name: AfTriggerCancel
> > value: 1
> > - description: Cancel an AF scan. This does not cause the lens to move
> > - anywhere else. Ignored if no scan is in progress.
> > + description: |
> > + Cancel an AF scan.
> > +
> > + This does not cause the lens to move anywhere else. Ignored if no
> > + scan is in progress.
> >
> > - AfPause:
> > type: int32_t
> > description: |
> > + Pause lens movements when in continuous autofocus mode.
> > +
> > This control has no effect except when in continuous autofocus mode
> > (AfModeContinuous). It can be used to pause any lens movements while
> > (for example) images are captured. The algorithm remains inactive
> > @@ -637,17 +704,21 @@ controls:
> > - name: AfPauseImmediate
> > value: 0
> > description: |
> > - Pause the continuous autofocus algorithm immediately, whether or not
> > - any kind of scan is underway. AfPauseState will subsequently report
> > + Pause the continuous autofocus algorithm immediately.
> > +
> > + The autofocus algorithm is paused whether or not any kind of scan
> > + is underway. AfPauseState will subsequently report
> > AfPauseStatePaused. AfState may report any of AfStateScanning,
> > AfStateFocused or AfStateFailed, depending on the algorithm's state
> > when it received this control.
> > - name: AfPauseDeferred
> > value: 1
> > description: |
> > - This is similar to AfPauseImmediate, and if the AfState is currently
> > - reporting AfStateFocused or AfStateFailed it will remain in that
> > - state and AfPauseState will report AfPauseStatePaused.
> > + Pause the continuous autofocus algorithm at the end of the scan.
> > +
> > + This is similar to AfPauseImmediate, and if the AfState is
> > + currently reporting AfStateFocused or AfStateFailed it will remain
> > + in that state and AfPauseState will report AfPauseStatePaused.
> >
> > However, if the algorithm is scanning (AfStateScanning),
> > AfPauseState will report AfPauseStatePausing until the scan is
> > @@ -658,15 +729,18 @@ controls:
> > - name: AfPauseResume
> > value: 2
> > description: |
> > - Resume continuous autofocus operation. The algorithm starts again
> > - from exactly where it left off, and AfPauseState will report
> > - AfPauseStateRunning.
> > + Resume continuous autofocus operation.
> > +
> > + The algorithm starts again from exactly where it left off, and
> > + AfPauseState will report AfPauseStateRunning.
> >
> > - LensPosition:
> > type: float
> > description: |
> > - Acts as a control to instruct the lens to move to a particular position
> > - and also reports back the position of the lens for each frame.
> > + Set and report the focus lens position.
> > +
> > + This control instructs the lens to move to a particular position and
> > + also reports back the position of the lens for each frame.
> >
> > The LensPosition control is ignored unless the AfMode is set to
> > AfModeManual, though the value is reported back unconditionally in all
> > @@ -680,16 +754,16 @@ controls:
> >
> > For example:
> >
> > - 0 moves the lens to infinity.
> > - 0.5 moves the lens to focus on objects 2m away.
> > - 2 moves the lens to focus on objects 50cm away.
> > - And larger values will focus the lens closer.
> > + - 0 moves the lens to infinity.
> > + - 0.5 moves the lens to focus on objects 2m away.
> > + - 2 moves the lens to focus on objects 50cm away.
> > + - And larger values will focus the lens closer.
> >
> > - The default value of the control should indicate a good general position
> > - for the lens, often corresponding to the hyperfocal distance (the
> > - closest position for which objects at infinity are still acceptably
> > - sharp). The minimum will often be zero (meaning infinity), and the
> > - maximum value defines the closest focus position.
> > + The default value of the control should indicate a good general
> > + position for the lens, often corresponding to the hyperfocal distance
> > + (the closest position for which objects at infinity are still
> > + acceptably sharp). The minimum will often be zero (meaning infinity),
> > + and the maximum value defines the closest focus position.
> >
> > \todo Define a property to report the Hyperfocal distance of calibrated
> > lenses.
> > @@ -697,22 +771,25 @@ controls:
> > - AfState:
> > type: int32_t
> > description: |
> > - Reports the current state of the AF algorithm in conjunction with the
> > - reported AfMode value and (in continuous AF mode) the AfPauseState
> > - value. The possible state changes are described below, though we note
> > - the following state transitions that occur when the AfMode is changed.
> > + The current state of the AF algorithm.
> > +
> > + This control reports the current state of the AF algorithm in
> > + conjunction with the reported AfMode value and (in continuous AF mode)
> > + the AfPauseState value. The possible state changes are described below,
> > + though we note the following state transitions that occur when the
> > + AfMode is changed.
> >
> > If the AfMode is set to AfModeManual, then the AfState will always
> > - report AfStateIdle (even if the lens is subsequently moved). Changing to
> > - the AfModeManual state does not initiate any lens movement.
> > + report AfStateIdle (even if the lens is subsequently moved). Changing
> > + to the AfModeManual state does not initiate any lens movement.
> >
> > If the AfMode is set to AfModeAuto then the AfState will report
> > - AfStateIdle. However, if AfModeAuto and AfTriggerStart are sent together
> > - then AfState will omit AfStateIdle and move straight to AfStateScanning
> > - (and start a scan).
> > + AfStateIdle. However, if AfModeAuto and AfTriggerStart are sent
> > + together then AfState will omit AfStateIdle and move straight to
> > + AfStateScanning (and start a scan).
> >
> > - If the AfMode is set to AfModeContinuous then the AfState will initially
> > - report AfStateScanning.
> > + If the AfMode is set to AfModeContinuous then the AfState will
> > + initially report AfStateScanning.
> >
> > enum:
> > - name: AfStateIdle
> > @@ -725,11 +802,12 @@ controls:
> > value: 1
> > description: |
> > The AF algorithm is in auto mode (AfModeAuto), and a scan has been
> > - started using the AfTrigger control. The scan can be cancelled by
> > - sending AfTriggerCancel at which point the algorithm will either
> > - move back to AfStateIdle or, if the scan actually completes before
> > - the cancel request is processed, to one of AfStateFocused or
> > - AfStateFailed.
> > + started using the AfTrigger control.
> > +
> > + The scan can be cancelled by sending AfTriggerCancel at which point
> > + the algorithm will either move back to AfStateIdle or, if the scan
> > + actually completes before the cancel request is processed, to one
> > + of AfStateFocused or AfStateFailed.
> >
> > Alternatively the AF algorithm could be in continuous mode
> > (AfModeContinuous) at which point it may enter this state
> > @@ -750,9 +828,12 @@ controls:
> > - AfPauseState:
> > type: int32_t
> > description: |
> > - Only applicable in continuous (AfModeContinuous) mode, this reports
> > - whether the algorithm is currently running, paused or pausing (that is,
> > - will pause as soon as any in-progress scan completes).
> > + Report whether the autofocus is currently running, paused or pausing.
> > +
> > + This control is only applicable in continuous (AfModeContinuous) mode,
> > + and reports whether the algorithm is currently running, paused or
> > + pausing (that is, will pause as soon as any in-progress scan
> > + completes).
> >
> > Any change to AfMode will cause AfPauseStateRunning to be reported.
> >
> > @@ -766,22 +847,27 @@ controls:
> > value: 1
> > description: |
> > Continuous AF has been sent an AfPauseDeferred control, and will
> > - pause as soon as any in-progress scan completes (and then report
> > - AfPauseStatePaused). No new scans will be start spontaneously until
> > + pause as soon as any in-progress scan completes.
> > +
> > + When the scan completes, the AfPauseState control will report
> > + AfPauseStatePaused. No new scans will be start spontaneously until
> > the AfPauseResume control is sent.
> > - name: AfPauseStatePaused
> > value: 2
> > description: |
> > - Continuous AF is paused. No further state changes or lens movements
> > - will occur until the AfPauseResume control is sent.
> > + Continuous AF is paused.
> > +
> > + No further state changes or lens movements will occur until the
> > + AfPauseResume control is sent.
> >
> > - HdrMode:
> > type: int32_t
> > description: |
> > - Control to set the mode to be used for High Dynamic Range (HDR)
> > - imaging. HDR techniques typically include multiple exposure, image
> > - fusion and tone mapping techniques to improve the dynamic range of the
> > - resulting images.
> > + Set the mode to be used for High Dynamic Range (HDR) imaging.
> > +
> > + HDR techniques typically include multiple exposure, image fusion and
> > + tone mapping techniques to improve the dynamic range of the resulting
> > + images.
> >
> > When using an HDR mode, images are captured with different sets of AGC
> > settings called HDR channels. Channels indicate in particular the type
> > @@ -795,16 +881,18 @@ controls:
> > - name: HdrModeOff
> > value: 0
> > description: |
> > - HDR is disabled. Metadata for this frame will not include the
> > - HdrChannel control.
> > + HDR is disabled.
> > +
> > + Metadata for this frame will not include the HdrChannel control.
> > - name: HdrModeMultiExposureUnmerged
> > value: 1
> > description: |
> > Multiple exposures will be generated in an alternating fashion.
> > - However, they will not be merged together and will be returned to
> > - the application as they are. Each image will be tagged with the
> > - correct HDR channel, indicating what kind of exposure it is. The
> > - tag should be the same as in the HdrModeMultiExposure case.
> > +
> > + The multiple exposures will not be merged together and will be
> > + returned to the application as they are. Each image will be tagged
> > + with the correct HDR channel, indicating what kind of exposure it
> > + is. The tag should be the same as in the HdrModeMultiExposure case.
> >
> > The expectation is that an application using this mode would merge
> > the frames to create HDR images for itself if it requires them.
> > @@ -812,8 +900,10 @@ controls:
> > value: 2
> > description: |
> > Multiple exposures will be generated and merged to create HDR
> > - images. Each image will be tagged with the HDR channel (long, medium
> > - or short) that arrived and which caused this image to be output.
> > + images.
> > +
> > + Each image will be tagged with the HDR channel (long, medium or
> > + short) that arrived and which caused this image to be output.
> >
> > Systems that use two channels for HDR will return images tagged
> > alternately as the short and long channel. Systems that use three
> > @@ -823,24 +913,29 @@ controls:
> > value: 3
> > description: |
> > Multiple frames all at a single exposure will be used to create HDR
> > - images. These images should be reported as all corresponding to the
> > - HDR short channel.
> > + images.
> > +
> > + These images should be reported as all corresponding to the HDR
> > + short channel.
> > - name: HdrModeNight
> > value: 4
> > description: |
> > - Multiple frames will be combined to produce "night mode" images. It
> > - is up to the implementation exactly which HDR channels it uses, and
> > - the images will all be tagged accordingly with the correct HDR
> > + Multiple frames will be combined to produce "night mode" images.
> > +
> > + It is up to the implementation exactly which HDR channels it uses,
> > + and the images will all be tagged accordingly with the correct HDR
> > channel information.
> >
> > - HdrChannel:
> > type: int32_t
> > description: |
> > + The HDR channel used to capture the frame.
> > +
> > This value is reported back to the application so that it can discover
> > - whether this capture corresponds to the short or long exposure image (or
> > - any other image used by the HDR procedure). An application can monitor
> > - the HDR channel to discover when the differently exposed images have
> > - arrived.
> > + whether this capture corresponds to the short or long exposure image
> > + (or any other image used by the HDR procedure). An application can
> > + monitor the HDR channel to discover when the differently exposed images
> > + have arrived.
> >
> > This metadata is only available when an HDR mode has been enabled.
> >
> > @@ -868,8 +963,9 @@ controls:
> > - Gamma:
> > type: float
> > description: |
> > - Specify a fixed gamma value. Default must be 2.2 which closely mimics
> > - sRGB gamma. Note that this is camera gamma, so it is applied as
> > - 1.0/gamma.
> > + Specify a fixed gamma value.
> > +
> > + The default gamma value must be 2.2 which closely mimics sRGB gamma.
> > + Note that this is camera gamma, so it is applied as 1.0/gamma.
> >
> > ...
> > diff --git a/src/libcamera/control_ids_rpi.yaml b/src/libcamera/control_ids_rpi.yaml
> > index cb097f887e16..42c4bf5d408f 100644
> > --- a/src/libcamera/control_ids_rpi.yaml
> > +++ b/src/libcamera/control_ids_rpi.yaml
> > @@ -10,9 +10,11 @@ controls:
> > - StatsOutputEnable:
> > type: bool
> > description: |
> > - Toggles the Raspberry Pi IPA to output a binary dump of the hardware
> > - generated statistics through the Request metadata in the Bcm2835StatsOutput
> > - control.
> > + Toggles the Raspberry Pi IPA to output the hardware generated statistics.
> > +
> > + When this control is set to true, the IPA outputs a binary dump of the
> > + hardware generated statistics through the Request metadata in the
> > + Bcm2835StatsOutput control.
> >
> > \sa Bcm2835StatsOutput
> >
> > @@ -20,9 +22,11 @@ controls:
> > type: uint8_t
> > size: [n]
> > description: |
> > - Span of the BCM2835 ISP generated statistics for the current frame. This
> > - is sent in the Request metadata if the StatsOutputEnable is set to true.
> > - The statistics struct definition can be found in include/linux/bcm2835-isp.h.
> > + Span of the BCM2835 ISP generated statistics for the current frame.
> > +
> > + This is sent in the Request metadata if the StatsOutputEnable is set to
> > + true. The statistics struct definition can be found in
> > + include/linux/bcm2835-isp.h.
> >
> > \sa StatsOutputEnable
> >
> >
> > base-commit: 62760bd2605a83e663b9003244ff42f8946f8955
--
Regards,
Laurent Pinchart
More information about the libcamera-devel
mailing list