[PATCH] libcamera: controls: Improve formatting of control descriptions in YAML
Kieran Bingham
kieran.bingham at ideasonboard.com
Thu Aug 15 23:49:12 CEST 2024
Quoting Laurent Pinchart (2024-08-10 03:39:04)
> 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.
>
I don't think I even realised that happened!
> 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
s/are/as/ maybe but it doesn't matter too much.
> 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>
> ---
> 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.
Interesting, so 'all' descriptions are now block comments even if
they're a single line. I think that's probably better to be consistent!.
No objectsions, this looks good to me.
Reviewed-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
> - 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