[{"id":30725,"web_url":"https://patchwork.libcamera.org/comment/30725/","msgid":"<871q2uw75c.fsf@redhat.com>","date":"2024-08-12T07:07:59","subject":"Re: [PATCH] libcamera: controls: Improve formatting of control\n\tdescriptions in YAML","submitter":{"id":177,"url":"https://patchwork.libcamera.org/api/people/177/","name":"Milan Zamazal","email":"mzamazal@redhat.com"},"content":"Hi Laurent,\n\nthank you for the cleanup.\n\nLaurent Pinchart writes:\n\n> The control descriptions from YAML files are extracted to generate\n> Doxygen documentation blocks for the controls, which are then compiled\n> to HTML. The extraction script uses the first line of the description\n> as the Doxygen \\brief, and preserves blank lines to keep paragraphs.\n>\n> The control descriptions in the YAML files have however not all been\n> written with this in mind. Many description elements are not formatted\n> as block string scalars, in the first place, so blank lines are lost\n> when parsing YAML. Furthermore, they often start with a long initial\n> paragraph, making the \\brief description very long.\n>\n> Improve the documentation formatting by marking all multiline\n> descriptions are block string scalars, and try to provide a short\n> one-line first paragraph to be used as a \\brief. While at it, reflow the\n> documentation to the 80 columns limit.\n>\n> The draft controls are left as-is, as they should evolve to non-draft\n> controls eventually (and ideally sooner than later).\n>\n> Signed-off-by: Laurent Pinchart \n\nReviewed-by: Milan Zamazal \n\nIt might be worth to unify \"Report\" / \"Reports\" / \"\" (noun only) for\nconsistency, in a followup patch.\n\n> ---\n> src/libcamera/control_ids_core.yaml | 466 +++++++++++++++++-----------\n> src/libcamera/control_ids_rpi.yaml | 16 +-\n> 2 files changed, 291 insertions(+), 191 deletions(-)\n>\n> diff --git a/src/libcamera/control_ids_core.yaml b/src/libcamera/control_ids_core.yaml\n> index cf40771d3896..6381970b4d28 100644\n> --- a/src/libcamera/control_ids_core.yaml\n> +++ b/src/libcamera/control_ids_core.yaml\n> @@ -32,10 +32,11 @@ controls:\n> - AeMeteringMode:\n> type: int32_t\n> description: |\n> - Specify a metering mode for the AE algorithm to use. The metering\n> - modes determine which parts of the image are used to determine the\n> - scene brightness. Metering modes may be platform specific and not\n> - all metering modes may be supported.\n> + Specify a metering mode for the AE algorithm to use.\n> +\n> + The metering modes determine which parts of the image are used to\n> + determine the scene brightness. Metering modes may be platform specific\n> + and not all metering modes may be supported.\n> enum:\n> - name: MeteringCentreWeighted\n> value: 0\n> @@ -56,33 +57,41 @@ controls:\n> - AeConstraintMode:\n> type: int32_t\n> description: |\n> - Specify a constraint mode for the AE algorithm to use. These determine\n> - how the measured scene brightness is adjusted to reach the desired\n> - target exposure. Constraint modes may be platform specific, and not\n> - all constraint modes may be supported.\n> + Specify a constraint mode for the AE algorithm to use.\n> +\n> + The constraint modes determine how the measured scene brightness is\n> + adjusted to reach the desired target exposure. Constraint modes may be\n> + platform specific, and not all constraint modes may be supported.\n> enum:\n> - name: ConstraintNormal\n> value: 0\n> - description: Default constraint mode.\n> + description: |\n> + Default constraint mode.\n> +\n> This mode aims to balance the exposure of different parts of the\n> image so as to reach a reasonable average level. However, highlights\n> in the image may appear over-exposed and lowlights may appear\n> under-exposed.\n> - name: ConstraintHighlight\n> value: 1\n> - description: Highlight constraint mode.\n> + description: |\n> + Highlight constraint mode.\n> +\n> This mode adjusts the exposure levels in order to try and avoid\n> over-exposing the brightest parts (highlights) of an image.\n> Other non-highlight parts of the image may appear under-exposed.\n> - name: ConstraintShadows\n> value: 2\n> - description: Shadows constraint mode.\n> + description: |\n> + Shadows constraint mode.\n> +\n> This mode adjusts the exposure levels in order to try and avoid\n> under-exposing the dark parts (shadows) of an image. Other normally\n> exposed parts of the image may appear over-exposed.\n> - name: ConstraintCustom\n> value: 3\n> - description: Custom constraint mode.\n> + description: |\n> + Custom constraint mode.\n> \n> # AeExposureMode needs further attention:\n> # - Auto-generate max enum value.\n> @@ -90,10 +99,11 @@ controls:\n> - AeExposureMode:\n> type: int32_t\n> description: |\n> - Specify an exposure mode for the AE algorithm to use. These specify\n> - how the desired total exposure is divided between the shutter time\n> - and the sensor's analogue gain. The exposure modes are platform\n> - specific, and not all exposure modes may be supported.\n> + Specify an exposure mode for the AE algorithm to use.\n> +\n> + The exposure modes specify how the desired total exposure is divided\n> + between the shutter time and the sensor's analogue gain. They are\n> + platform specific, and not all exposure modes may be supported.\n> enum:\n> - name: ExposureNormal\n> value: 0\n> @@ -111,8 +121,10 @@ controls:\n> - ExposureValue:\n> type: float\n> description: |\n> - Specify an Exposure Value (EV) parameter. The EV parameter will only be\n> - applied if the AE algorithm is currently enabled.\n> + Specify an Exposure Value (EV) parameter.\n> +\n> + The EV parameter will only be applied if the AE algorithm is currently\n> + enabled.\n> \n> By convention EV adjusts the exposure as log2. For example\n> EV = [-2, -1, 0.5, 0, 0.5, 1, 2] results in an exposure adjustment\n> @@ -124,7 +136,9 @@ controls:\n> type: int32_t\n> description: |\n> Exposure time (shutter speed) for the frame applied in the sensor\n> - device. This value is specified in micro-seconds.\n> + device.\n> +\n> + This value is specified in micro-seconds.\n> \n> Setting this value means that it is now fixed and the AE algorithm may\n> not change it. Setting it back to zero returns it to the control of the\n> @@ -142,6 +156,7 @@ controls:\n> type: float\n> description: |\n> Analogue gain value applied in the sensor device.\n> +\n> The value of the control specifies the gain multiplier applied to all\n> colour channels. This value cannot be lower than 1.0.\n> \n> @@ -160,9 +175,11 @@ controls:\n> - AeFlickerMode:\n> type: int32_t\n> description: |\n> - Set the flicker mode, which determines whether, and how, the AGC/AEC\n> - algorithm attempts to hide flicker effects caused by the duty cycle of\n> - artificial lighting.\n> + Set the flicker avoidance mode for AGC/AEC.\n> +\n> + The flicker mode determines whether, and how, the AGC/AEC algorithm\n> + attempts to hide flicker effects caused by the duty cycle of artificial\n> + lighting.\n> \n> Although implementation dependent, many algorithms for \"flicker\n> avoidance\" work by restricting this exposure time to integer multiples\n> @@ -176,16 +193,21 @@ controls:\n> enum:\n> - name: FlickerOff\n> value: 0\n> - description: No flicker avoidance is performed.\n> + description: |\n> + No flicker avoidance is performed.\n> - name: FlickerManual\n> value: 1\n> - description: Manual flicker avoidance.\n> + description: |\n> + Manual flicker avoidance.\n> +\n> Suppress flicker effects caused by lighting running with a period\n> specified by the AeFlickerPeriod control.\n> \\sa AeFlickerPeriod\n> - name: FlickerAuto\n> value: 2\n> - description: Automatic flicker period detection and avoidance.\n> + description: |\n> + Automatic flicker period detection and avoidance.\n> +\n> The system will automatically determine the most likely value of\n> flicker period, and avoid flicker of this frequency. Once flicker\n> is being corrected, it is implementation dependent whether the\n> @@ -194,7 +216,9 @@ controls:\n> \n> - AeFlickerPeriod:\n> type: int32_t\n> - description: Manual flicker period in microseconds.\n> + description: |\n> + Manual flicker period in microseconds.\n> +\n> This value sets the current flicker period to avoid. It is used when\n> AeFlickerMode is set to FlickerManual.\n> \n> @@ -212,7 +236,9 @@ controls:\n> \n> - AeFlickerDetected:\n> type: int32_t\n> - description: Flicker period detected in microseconds.\n> + description: |\n> + Flicker period detected in microseconds.\n> +\n> The value reported here indicates the currently detected flicker\n> period, or zero if no flicker at all is detected.\n> \n> @@ -233,21 +259,25 @@ controls:\n> - Brightness:\n> type: float\n> description: |\n> - Specify a fixed brightness parameter. Positive values (up to 1.0)\n> - produce brighter images; negative values (up to -1.0) produce darker\n> - images and 0.0 leaves pixels unchanged.\n> + Specify a fixed brightness parameter.\n> +\n> + Positive values (up to 1.0) produce brighter images; negative values\n> + (up to -1.0) produce darker images and 0.0 leaves pixels unchanged.\n> \n> - Contrast:\n> type: float\n> description: |\n> - Specify a fixed contrast parameter. Normal contrast is given by the\n> - value 1.0; larger values produce images with more contrast.\n> + Specify a fixed contrast parameter.\n> +\n> + Normal contrast is given by the value 1.0; larger values produce images\n> + with more contrast.\n> \n> - Lux:\n> type: float\n> description: |\n> - Report an estimate of the current illuminance level in lux. The Lux\n> - control can only be returned in metadata.\n> + Report an estimate of the current illuminance level in lux.\n> +\n> + The Lux control can only be returned in metadata.\n> \n> - AwbEnable:\n> type: bool\n> @@ -262,8 +292,10 @@ controls:\n> - AwbMode:\n> type: int32_t\n> description: |\n> - Specify the range of illuminants to use for the AWB algorithm. The modes\n> - supported are platform specific, and not all modes may be supported.\n> + Specify the range of illuminants to use for the AWB algorithm.\n> +\n> + The modes supported are platform specific, and not all modes may be\n> + supported.\n> enum:\n> - name: AwbAuto\n> value: 0\n> @@ -305,37 +337,43 @@ controls:\n> type: float\n> description: |\n> Pair of gain values for the Red and Blue colour channels, in that\n> - order. ColourGains can only be applied in a Request when the AWB is\n> - disabled.\n> + order.\n> +\n> + ColourGains can only be applied in a Request when the AWB is disabled.\n> \n> \\sa AwbEnable\n> size: [2]\n> \n> - ColourTemperature:\n> type: int32_t\n> - description: Report the current estimate of the colour temperature, in\n> - kelvin, for this frame. The ColourTemperature control can only be\n> - returned in metadata.\n> + description: |\n> + Report the estimate of the colour temperature for the frame, in kelvin.\n> +\n> + The ColourTemperature control can only be returned in metadata.\n> \n> - Saturation:\n> type: float\n> description: |\n> - Specify a fixed saturation parameter. Normal saturation is given by\n> - the value 1.0; larger values produce more saturated colours; 0.0\n> - produces a greyscale image.\n> + Specify a fixed saturation parameter.\n> +\n> + Normal saturation is given by the value 1.0; larger values produce more\n> + saturated colours; 0.0 produces a greyscale image.\n> \n> - SensorBlackLevels:\n> type: int32_t\n> description: |\n> - Reports the sensor black levels used for processing a frame, in the\n> - order R, Gr, Gb, B. These values are returned as numbers out of a 16-bit\n> - pixel range (as if pixels ranged from 0 to 65535). The SensorBlackLevels\n> - control can only be returned in metadata.\n> + Reports the sensor black levels used for processing a frame.\n> +\n> + The values are in the order R, Gr, Gb, B. They are returned as numbers\n> + out of a 16-bit pixel range (as if pixels ranged from 0 to 65535). The\n> + SensorBlackLevels control can only be returned in metadata.\n> size: [4]\n> \n> - Sharpness:\n> type: float\n> description: |\n> + Intensity of the sharpening applied to the image.\n> +\n> A value of 0.0 means no sharpening. The minimum value means\n> minimal sharpening, and shall be 0.0 unless the camera can't\n> disable sharpening completely. The default value shall give a\n> @@ -349,6 +387,7 @@ controls:\n> type: int32_t\n> description: |\n> Reports a Figure of Merit (FoM) to indicate how in-focus the frame is.\n> +\n> A larger FocusFoM value indicates a more in-focus frame. This singular\n> value may be based on a combination of statistics gathered from\n> multiple focus regions within an image. The number of focus regions and\n> @@ -359,11 +398,13 @@ controls:\n> - ColourCorrectionMatrix:\n> type: float\n> description: |\n> - The 3x3 matrix that converts camera RGB to sRGB within the\n> - imaging pipeline. This should describe the matrix that is used\n> - after pixels have been white-balanced, but before any gamma\n> - transformation. The 3x3 matrix is stored in conventional reading\n> - order in an array of 9 floating point values.\n> + The 3x3 matrix that converts camera RGB to sRGB within the imaging\n> + pipeline.\n> +\n> + This should describe the matrix that is used after pixels have been\n> + white-balanced, but before any gamma transformation. The 3x3 matrix is\n> + stored in conventional reading order in an array of 9 floating point\n> + values.\n> \n> size: [3,3]\n> \n> @@ -371,10 +412,12 @@ controls:\n> type: Rectangle\n> description: |\n> Sets the image portion that will be scaled to form the whole of\n> - the final output image. The (x,y) location of this rectangle is\n> - relative to the PixelArrayActiveAreas that is being used. The units\n> - remain native sensor pixels, even if the sensor is being used in\n> - a binning or skipping mode.\n> + the final output image.\n> +\n> + The (x,y) location of this rectangle is relative to the\n> + PixelArrayActiveAreas that is being used. The units remain native\n> + sensor pixels, even if the sensor is being used in a binning or\n> + skipping mode.\n> \n> This control is only present when the pipeline supports scaling. Its\n> maximum valid value is given by the properties::ScalerCropMaximum\n> @@ -401,8 +444,9 @@ controls:\n> type: int64_t\n> description: |\n> The instantaneous frame duration from start of frame exposure to start\n> - of next exposure, expressed in microseconds. This control is meant to\n> - be returned in metadata.\n> + of next exposure, expressed in microseconds.\n> +\n> + This control is meant to be returned in metadata.\n> \n> - FrameDurationLimits:\n> type: int64_t\n> @@ -444,9 +488,11 @@ controls:\n> - SensorTemperature:\n> type: float\n> description: |\n> - Temperature measure from the camera sensor in Celsius. This is typically\n> - obtained by a thermal sensor present on-die or in the camera module. The\n> - range of reported temperatures is device dependent.\n> + Temperature measure from the camera sensor in Celsius.\n> +\n> + This value is typically obtained by a thermal sensor present on-die or\n> + in the camera module. The range of reported temperatures is device\n> + dependent.\n> \n> The SensorTemperature control will only be returned in metadata if a\n> thermal sensor is present.\n> @@ -468,7 +514,7 @@ controls:\n> - AfMode:\n> type: int32_t\n> description: |\n> - Control to set the mode of the AF (autofocus) algorithm.\n> + The mode of the AF (autofocus) algorithm.\n> \n> An implementation may choose not to implement all the modes.\n> \n> @@ -476,12 +522,12 @@ controls:\n> - name: AfModeManual\n> value: 0\n> description: |\n> - The AF algorithm is in manual mode. In this mode it will never\n> - perform any action nor move the lens of its own accord, but an\n> - application can specify the desired lens position using the\n> - LensPosition control.\n> + The AF algorithm is in manual mode.\n> \n> - In this mode the AfState will always report AfStateIdle.\n> + In this mode it will never perform any action nor move the lens of\n> + its own accord, but an application can specify the desired lens\n> + position using the LensPosition control. The AfState will always\n> + report AfStateIdle.\n> \n> If the camera is started in AfModeManual, it will move the focus\n> lens to the position specified by the LensPosition control.\n> @@ -492,31 +538,34 @@ controls:\n> - name: AfModeAuto\n> value: 1\n> description: |\n> - The AF algorithm is in auto mode. This means that the algorithm\n> - will never move the lens or change state unless the AfTrigger\n> - control is used. The AfTrigger control can be used to initiate a\n> - focus scan, the results of which will be reported by AfState.\n> + The AF algorithm is in auto mode.\n> \n> - If the autofocus algorithm is moved from AfModeAuto to another\n> - mode while a scan is in progress, the scan is cancelled\n> - immediately, without waiting for the scan to finish.\n> + In this mode the algorithm will never move the lens or change state\n> + unless the AfTrigger control is used. The AfTrigger control can be\n> + used to initiate a focus scan, the results of which will be\n> + reported by AfState.\n> \n> - When first entering this mode the AfState will report\n> - AfStateIdle. When a trigger control is sent, AfState will\n> - report AfStateScanning for a period before spontaneously\n> - changing to AfStateFocused or AfStateFailed, depending on\n> - the outcome of the scan. It will remain in this state until\n> - another scan is initiated by the AfTrigger control. If a scan is\n> - cancelled (without changing to another mode), AfState will return\n> - to AfStateIdle.\n> + If the autofocus algorithm is moved from AfModeAuto to another mode\n> + while a scan is in progress, the scan is cancelled immediately,\n> + without waiting for the scan to finish.\n> +\n> + When first entering this mode the AfState will report AfStateIdle.\n> + When a trigger control is sent, AfState will report AfStateScanning\n> + for a period before spontaneously changing to AfStateFocused or\n> + AfStateFailed, depending on the outcome of the scan. It will remain\n> + in this state until another scan is initiated by the AfTrigger\n> + control. If a scan is cancelled (without changing to another mode),\n> + AfState will return to AfStateIdle.\n> - name: AfModeContinuous\n> value: 2\n> description: |\n> - The AF algorithm is in continuous mode. This means that the lens can\n> - re-start a scan spontaneously at any moment, without any user\n> - intervention. The AfState still reports whether the algorithm is\n> - currently scanning or not, though the application has no ability to\n> - initiate or cancel scans, nor to move the lens for itself.\n> + The AF algorithm is in continuous mode.\n> +\n> + In this mode the lens can re-start a scan spontaneously at any\n> + moment, without any user intervention. The AfState still reports\n> + whether the algorithm is currently scanning or not, though the\n> + application has no ability to initiate or cancel scans, nor to move\n> + the lens for itself.\n> \n> However, applications can pause the AF algorithm from continuously\n> scanning by using the AfPause control. This allows video or still\n> @@ -529,34 +578,40 @@ controls:\n> - AfRange:\n> type: int32_t\n> description: |\n> - Control to set the range of focus distances that is scanned. An\n> - implementation may choose not to implement all the options here.\n> + The range of focus distances that is scanned.\n> +\n> + An implementation may choose not to implement all the options here.\n> enum:\n> - name: AfRangeNormal\n> value: 0\n> description: |\n> - A wide range of focus distances is scanned, all the way from\n> - infinity down to close distances, though depending on the\n> - implementation, possibly not including the very closest macro\n> - positions.\n> + A wide range of focus distances is scanned.\n> +\n> + Scanned distances cover all the way from infinity down to close\n> + distances, though depending on the implementation, possibly not\n> + including the very closest macro positions.\n> - name: AfRangeMacro\n> value: 1\n> - description: Only close distances are scanned.\n> + description: |\n> + Only close distances are scanned.\n> - name: AfRangeFull\n> value: 2\n> description: |\n> - The full range of focus distances is scanned just as with\n> - AfRangeNormal but this time including the very closest macro\n> - positions.\n> + The full range of focus distances is scanned.\n> +\n> + This range is similar to AfRangeNormal but includes the very\n> + closest macro positions.\n> \n> - AfSpeed:\n> type: int32_t\n> description: |\n> - Control that determines whether the AF algorithm is to move the lens\n> - as quickly as possible or more steadily. For example, during video\n> - recording it may be desirable not to move the lens too abruptly, but\n> - when in a preview mode (waiting for a still capture) it may be\n> - helpful to move the lens as quickly as is reasonably possible.\n> + Determine whether the AF is to move the lens as quickly as possible or\n> + more steadily.\n> +\n> + For example, during video recording it may be desirable not to move the\n> + lens too abruptly, but when in a preview mode (waiting for a still\n> + capture) it may be helpful to move the lens as quickly as is reasonably\n> + possible.\n> enum:\n> - name: AfSpeedNormal\n> value: 0\n> @@ -568,25 +623,27 @@ controls:\n> - AfMetering:\n> type: int32_t\n> description: |\n> - Instruct the AF algorithm how it should decide which parts of the image\n> - should be used to measure focus.\n> + The parts of the image used by the AF algorithm to measure focus.\n> enum:\n> - name: AfMeteringAuto\n> value: 0\n> - description: The AF algorithm should decide for itself where it will\n> - measure focus.\n> + description: |\n> + Let the AF algorithm decide for itself where it will measure focus.\n> - name: AfMeteringWindows\n> value: 1\n> - description: The AF algorithm should use the rectangles defined by\n> - the AfWindows control to measure focus. If no windows are specified\n> - the behaviour is platform dependent.\n> + description: |\n> + Use the rectangles defined by the AfWindows control to measure focus.\n> +\n> + If no windows are specified the behaviour is platform dependent.\n> \n> - AfWindows:\n> type: Rectangle\n> description: |\n> - Sets the focus windows used by the AF algorithm when AfMetering is set\n> - to AfMeteringWindows. The units used are pixels within the rectangle\n> - returned by the ScalerCropMaximum property.\n> + The focus windows used by the AF algorithm when AfMetering is set to\n> + AfMeteringWindows.\n> +\n> + The units used are pixels within the rectangle returned by the\n> + ScalerCropMaximum property.\n> \n> In order to be activated, a rectangle must be programmed with non-zero\n> width and height. Internally, these rectangles are intersected with the\n> @@ -611,23 +668,33 @@ controls:\n> - AfTrigger:\n> type: int32_t\n> description: |\n> - This control starts an autofocus scan when AfMode is set to AfModeAuto,\n> - and can also be used to terminate a scan early.\n> + Start an autofocus scan.\n> \n> - It is ignored if AfMode is set to AfModeManual or AfModeContinuous.\n> + This control starts an autofocus scan when AfMode is set to AfModeAuto,\n> + and is ignored if AfMode is set to AfModeManual or AfModeContinuous. It\n> + can also be used to terminate a scan early.\n> \n> enum:\n> - name: AfTriggerStart\n> value: 0\n> - description: Start an AF scan. Ignored if a scan is in progress.\n> + description: |\n> + Start an AF scan.\n> +\n> + Setting the control to AfTriggerStart is ignored if a scan is in\n> + progress.\n> - name: AfTriggerCancel\n> value: 1\n> - description: Cancel an AF scan. This does not cause the lens to move\n> - anywhere else. Ignored if no scan is in progress.\n> + description: |\n> + Cancel an AF scan.\n> +\n> + This does not cause the lens to move anywhere else. Ignored if no\n> + scan is in progress.\n> \n> - AfPause:\n> type: int32_t\n> description: |\n> + Pause lens movements when in continuous autofocus mode.\n> +\n> This control has no effect except when in continuous autofocus mode\n> (AfModeContinuous). It can be used to pause any lens movements while\n> (for example) images are captured. The algorithm remains inactive\n> @@ -637,17 +704,21 @@ controls:\n> - name: AfPauseImmediate\n> value: 0\n> description: |\n> - Pause the continuous autofocus algorithm immediately, whether or not\n> - any kind of scan is underway. AfPauseState will subsequently report\n> + Pause the continuous autofocus algorithm immediately.\n> +\n> + The autofocus algorithm is paused whether or not any kind of scan\n> + is underway. AfPauseState will subsequently report\n> AfPauseStatePaused. AfState may report any of AfStateScanning,\n> AfStateFocused or AfStateFailed, depending on the algorithm's state\n> when it received this control.\n> - name: AfPauseDeferred\n> value: 1\n> description: |\n> - This is similar to AfPauseImmediate, and if the AfState is currently\n> - reporting AfStateFocused or AfStateFailed it will remain in that\n> - state and AfPauseState will report AfPauseStatePaused.\n> + Pause the continuous autofocus algorithm at the end of the scan.\n> +\n> + This is similar to AfPauseImmediate, and if the AfState is\n> + currently reporting AfStateFocused or AfStateFailed it will remain\n> + in that state and AfPauseState will report AfPauseStatePaused.\n> \n> However, if the algorithm is scanning (AfStateScanning),\n> AfPauseState will report AfPauseStatePausing until the scan is\n> @@ -658,15 +729,18 @@ controls:\n> - name: AfPauseResume\n> value: 2\n> description: |\n> - Resume continuous autofocus operation. The algorithm starts again\n> - from exactly where it left off, and AfPauseState will report\n> - AfPauseStateRunning.\n> + Resume continuous autofocus operation.\n> +\n> + The algorithm starts again from exactly where it left off, and\n> + AfPauseState will report AfPauseStateRunning.\n> \n> - LensPosition:\n> type: float\n> description: |\n> - Acts as a control to instruct the lens to move to a particular position\n> - and also reports back the position of the lens for each frame.\n> + Set and report the focus lens position.\n> +\n> + This control instructs the lens to move to a particular position and\n> + also reports back the position of the lens for each frame.\n> \n> The LensPosition control is ignored unless the AfMode is set to\n> AfModeManual, though the value is reported back unconditionally in all\n> @@ -680,16 +754,16 @@ controls:\n> \n> For example:\n> \n> - 0 moves the lens to infinity.\n> - 0.5 moves the lens to focus on objects 2m away.\n> - 2 moves the lens to focus on objects 50cm away.\n> - And larger values will focus the lens closer.\n> + - 0 moves the lens to infinity.\n> + - 0.5 moves the lens to focus on objects 2m away.\n> + - 2 moves the lens to focus on objects 50cm away.\n> + - And larger values will focus the lens closer.\n> \n> - The default value of the control should indicate a good general position\n> - for the lens, often corresponding to the hyperfocal distance (the\n> - closest position for which objects at infinity are still acceptably\n> - sharp). The minimum will often be zero (meaning infinity), and the\n> - maximum value defines the closest focus position.\n> + The default value of the control should indicate a good general\n> + position for the lens, often corresponding to the hyperfocal distance\n> + (the closest position for which objects at infinity are still\n> + acceptably sharp). The minimum will often be zero (meaning infinity),\n> + and the maximum value defines the closest focus position.\n> \n> \\todo Define a property to report the Hyperfocal distance of calibrated\n> lenses.\n> @@ -697,22 +771,25 @@ controls:\n> - AfState:\n> type: int32_t\n> description: |\n> - Reports the current state of the AF algorithm in conjunction with the\n> - reported AfMode value and (in continuous AF mode) the AfPauseState\n> - value. The possible state changes are described below, though we note\n> - the following state transitions that occur when the AfMode is changed.\n> + The current state of the AF algorithm.\n> +\n> + This control reports the current state of the AF algorithm in\n> + conjunction with the reported AfMode value and (in continuous AF mode)\n> + the AfPauseState value. The possible state changes are described below,\n> + though we note the following state transitions that occur when the\n> + AfMode is changed.\n> \n> If the AfMode is set to AfModeManual, then the AfState will always\n> - report AfStateIdle (even if the lens is subsequently moved). Changing to\n> - the AfModeManual state does not initiate any lens movement.\n> + report AfStateIdle (even if the lens is subsequently moved). Changing\n> + to the AfModeManual state does not initiate any lens movement.\n> \n> If the AfMode is set to AfModeAuto then the AfState will report\n> - AfStateIdle. However, if AfModeAuto and AfTriggerStart are sent together\n> - then AfState will omit AfStateIdle and move straight to AfStateScanning\n> - (and start a scan).\n> + AfStateIdle. However, if AfModeAuto and AfTriggerStart are sent\n> + together then AfState will omit AfStateIdle and move straight to\n> + AfStateScanning (and start a scan).\n> \n> - If the AfMode is set to AfModeContinuous then the AfState will initially\n> - report AfStateScanning.\n> + If the AfMode is set to AfModeContinuous then the AfState will\n> + initially report AfStateScanning.\n> \n> enum:\n> - name: AfStateIdle\n> @@ -725,11 +802,12 @@ controls:\n> value: 1\n> description: |\n> The AF algorithm is in auto mode (AfModeAuto), and a scan has been\n> - started using the AfTrigger control. The scan can be cancelled by\n> - sending AfTriggerCancel at which point the algorithm will either\n> - move back to AfStateIdle or, if the scan actually completes before\n> - the cancel request is processed, to one of AfStateFocused or\n> - AfStateFailed.\n> + started using the AfTrigger control.\n> +\n> + The scan can be cancelled by sending AfTriggerCancel at which point\n> + the algorithm will either move back to AfStateIdle or, if the scan\n> + actually completes before the cancel request is processed, to one\n> + of AfStateFocused or AfStateFailed.\n> \n> Alternatively the AF algorithm could be in continuous mode\n> (AfModeContinuous) at which point it may enter this state\n> @@ -750,9 +828,12 @@ controls:\n> - AfPauseState:\n> type: int32_t\n> description: |\n> - Only applicable in continuous (AfModeContinuous) mode, this reports\n> - whether the algorithm is currently running, paused or pausing (that is,\n> - will pause as soon as any in-progress scan completes).\n> + Report whether the autofocus is currently running, paused or pausing.\n> +\n> + This control is only applicable in continuous (AfModeContinuous) mode,\n> + and reports whether the algorithm is currently running, paused or\n> + pausing (that is, will pause as soon as any in-progress scan\n> + completes).\n> \n> Any change to AfMode will cause AfPauseStateRunning to be reported.\n> \n> @@ -766,22 +847,27 @@ controls:\n> value: 1\n> description: |\n> Continuous AF has been sent an AfPauseDeferred control, and will\n> - pause as soon as any in-progress scan completes (and then report\n> - AfPauseStatePaused). No new scans will be start spontaneously until\n> + pause as soon as any in-progress scan completes.\n> +\n> + When the scan completes, the AfPauseState control will report\n> + AfPauseStatePaused. No new scans will be start spontaneously until\n> the AfPauseResume control is sent.\n> - name: AfPauseStatePaused\n> value: 2\n> description: |\n> - Continuous AF is paused. No further state changes or lens movements\n> - will occur until the AfPauseResume control is sent.\n> + Continuous AF is paused.\n> +\n> + No further state changes or lens movements will occur until the\n> + AfPauseResume control is sent.\n> \n> - HdrMode:\n> type: int32_t\n> description: |\n> - Control to set the mode to be used for High Dynamic Range (HDR)\n> - imaging. HDR techniques typically include multiple exposure, image\n> - fusion and tone mapping techniques to improve the dynamic range of the\n> - resulting images.\n> + Set the mode to be used for High Dynamic Range (HDR) imaging.\n> +\n> + HDR techniques typically include multiple exposure, image fusion and\n> + tone mapping techniques to improve the dynamic range of the resulting\n> + images.\n> \n> When using an HDR mode, images are captured with different sets of AGC\n> settings called HDR channels. Channels indicate in particular the type\n> @@ -795,16 +881,18 @@ controls:\n> - name: HdrModeOff\n> value: 0\n> description: |\n> - HDR is disabled. Metadata for this frame will not include the\n> - HdrChannel control.\n> + HDR is disabled.\n> +\n> + Metadata for this frame will not include the HdrChannel control.\n> - name: HdrModeMultiExposureUnmerged\n> value: 1\n> description: |\n> Multiple exposures will be generated in an alternating fashion.\n> - However, they will not be merged together and will be returned to\n> - the application as they are. Each image will be tagged with the\n> - correct HDR channel, indicating what kind of exposure it is. The\n> - tag should be the same as in the HdrModeMultiExposure case.\n> +\n> + The multiple exposures will not be merged together and will be\n> + returned to the application as they are. Each image will be tagged\n> + with the correct HDR channel, indicating what kind of exposure it\n> + is. The tag should be the same as in the HdrModeMultiExposure case.\n> \n> The expectation is that an application using this mode would merge\n> the frames to create HDR images for itself if it requires them.\n> @@ -812,8 +900,10 @@ controls:\n> value: 2\n> description: |\n> Multiple exposures will be generated and merged to create HDR\n> - images. Each image will be tagged with the HDR channel (long, medium\n> - or short) that arrived and which caused this image to be output.\n> + images.\n> +\n> + Each image will be tagged with the HDR channel (long, medium or\n> + short) that arrived and which caused this image to be output.\n> \n> Systems that use two channels for HDR will return images tagged\n> alternately as the short and long channel. Systems that use three\n> @@ -823,24 +913,29 @@ controls:\n> value: 3\n> description: |\n> Multiple frames all at a single exposure will be used to create HDR\n> - images. These images should be reported as all corresponding to the\n> - HDR short channel.\n> + images.\n> +\n> + These images should be reported as all corresponding to the HDR\n> + short channel.\n> - name: HdrModeNight\n> value: 4\n> description: |\n> - Multiple frames will be combined to produce \"night mode\" images. It\n> - is up to the implementation exactly which HDR channels it uses, and\n> - the images will all be tagged accordingly with the correct HDR\n> + Multiple frames will be combined to produce \"night mode\" images.\n> +\n> + It is up to the implementation exactly which HDR channels it uses,\n> + and the images will all be tagged accordingly with the correct HDR\n> channel information.\n> \n> - HdrChannel:\n> type: int32_t\n> description: |\n> + The HDR channel used to capture the frame.\n> +\n> This value is reported back to the application so that it can discover\n> - whether this capture corresponds to the short or long exposure image (or\n> - any other image used by the HDR procedure). An application can monitor\n> - the HDR channel to discover when the differently exposed images have\n> - arrived.\n> + whether this capture corresponds to the short or long exposure image\n> + (or any other image used by the HDR procedure). An application can\n> + monitor the HDR channel to discover when the differently exposed images\n> + have arrived.\n> \n> This metadata is only available when an HDR mode has been enabled.\n> \n> @@ -868,8 +963,9 @@ controls:\n> - Gamma:\n> type: float\n> description: |\n> - Specify a fixed gamma value. Default must be 2.2 which closely mimics\n> - sRGB gamma. Note that this is camera gamma, so it is applied as\n> - 1.0/gamma.\n> + Specify a fixed gamma value.\n> +\n> + The default gamma value must be 2.2 which closely mimics sRGB gamma.\n> + Note that this is camera gamma, so it is applied as 1.0/gamma.\n> \n> ...\n> diff --git a/src/libcamera/control_ids_rpi.yaml b/src/libcamera/control_ids_rpi.yaml\n> index cb097f887e16..42c4bf5d408f 100644\n> --- a/src/libcamera/control_ids_rpi.yaml\n> +++ b/src/libcamera/control_ids_rpi.yaml\n> @@ -10,9 +10,11 @@ controls:\n> - StatsOutputEnable:\n> type: bool\n> description: |\n> - Toggles the Raspberry Pi IPA to output a binary dump of the hardware\n> - generated statistics through the Request metadata in the Bcm2835StatsOutput\n> - control.\n> + Toggles the Raspberry Pi IPA to output the hardware generated statistics.\n> +\n> + When this control is set to true, the IPA outputs a binary dump of the\n> + hardware generated statistics through the Request metadata in the\n> + Bcm2835StatsOutput control.\n> \n> \\sa Bcm2835StatsOutput\n> \n> @@ -20,9 +22,11 @@ controls:\n> type: uint8_t\n> size: [n]\n> description: |\n> - Span of the BCM2835 ISP generated statistics for the current frame. This\n> - is sent in the Request metadata if the StatsOutputEnable is set to true.\n> - The statistics struct definition can be found in include/linux/bcm2835-isp.h.\n> + Span of the BCM2835 ISP generated statistics for the current frame.\n> +\n> + This is sent in the Request metadata if the StatsOutputEnable is set to\n> + true. The statistics struct definition can be found in\n> + include/linux/bcm2835-isp.h.\n> \n> \\sa StatsOutputEnable\n> \n>\n> base-commit: 62760bd2605a83e663b9003244ff42f8946f8955","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 680A1C323E\n\tfor ;\n\tMon, 12 Aug 2024 07:08:10 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 6140A633B5;\n\tMon, 12 Aug 2024 09:08:09 +0200 (CEST)","from us-smtp-delivery-124.mimecast.com\n\t(us-smtp-delivery-124.mimecast.com [170.10.133.124])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 7802463394\n\tfor ;\n\tMon, 12 Aug 2024 09:08:07 +0200 (CEST)","from mail-lj1-f198.google.com (mail-lj1-f198.google.com\n\t[209.85.208.198]) by relay.mimecast.com with ESMTP with STARTTLS\n\t(version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id\n\tus-mta-620-0iX_0SAQM0GzOmFc0xD_IQ-1; Mon, 12 Aug 2024 03:08:04 -0400","by mail-lj1-f198.google.com with SMTP id\n\t38308e7fff4ca-2f14b6f64d3so37446821fa.0\n\tfor ;\n\tMon, 12 Aug 2024 00:08:04 -0700 (PDT)","from nuthatch (ip-77-48-47-2.net.vodafone.cz. [77.48.47.2])\n\tby smtp.gmail.com with ESMTPSA id\n\t5b1f17b1804b1-429c7fab973sm87279395e9.43.2024.08.12.00.08.00\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n\tMon, 12 Aug 2024 00:08:00 -0700 (PDT)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=redhat.com header.i=@redhat.com\n\theader.b=\"Wk5cufQ4\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;\n\ts=mimecast20190719; t=1723446486;\n\th=from:from:reply-to:subject:subject:date:date:message-id:message-id:\n\tto:to:cc:cc:mime-version:mime-version:content-type:content-type:\n\tin-reply-to:in-reply-to:references:references;\n\tbh=rL+ZJ37t4pnVW1VZ3uYhpcR6JWMdzZqcID1pJB1KQEw=;\n\tb=Wk5cufQ4M3F1QolvuvJXqSyq6EoJTs+ZoNLr582cIo2g2qz7f7sDbTifAQhl79sKcuiuR6\n\tzriwx2V/O194hZ9p7hyc+/cJqoOw3COZkQUH8NmTfamZEfQkYpprdBXhBz7OpUzPHxIiaJ\n\tmN3Y4L+U/Ofaew/Kk3V9QIyrUnB7WqQ=","X-MC-Unique":"0iX_0SAQM0GzOmFc0xD_IQ-1","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20230601; t=1723446483; x=1724051283;\n\th=mime-version:user-agent:message-id:date:references:in-reply-to\n\t:subject:cc:to:from:x-gm-message-state:from:to:cc:subject:date\n\t:message-id:reply-to;\n\tbh=rL+ZJ37t4pnVW1VZ3uYhpcR6JWMdzZqcID1pJB1KQEw=;\n\tb=NFX3tN8cSgYqViko/WWwEkUYg6Fv0O1eES4aUgl0SMZOd9b1KcK6sqdSwlOUySMwem\n\tNA2vwra11TBIsQPTk3+d4HNMFbgCNGXP8YtwrusSygtMRUIUOZXQVOyP/VmYB+7ZpHPy\n\tl2fxtsPDBmA+SiL6lACKD7ff+hirMJTshuYMf9SXbyT/NvRWY3LfIDFQmCY90wjNqlUE\n\toltryWEf7e39Vr1OtTI+IyEmH2K6LX62A61ahdfRGRNLm/QVMlOjOTRqwyA8bzlUbCy6\n\tcoN2vDPHokQcX8dlVNGUajLxoHoJuyUkDTsyNigdz/9Yajf3M5C260m88I6RLJxn1T7/\n\tKz3w==","X-Gm-Message-State":"AOJu0YxFfKtsRO5D2YQovdqNs4MYCscNMZ+23gq5MhaDDkkiNh4YWxIo\n\tps/uT8d2GAOM7EwjaSd9o3i2IBSQ9BASBhFGRnroSpVAnoGE6npH3yd+MRow8VqwRFuPceEquhJ\n\tpTKilBEpdgz0uVJ/bUlpkdfvb/IfM0A/wpmk6Rmram7K72WVsUumLt+IX00d2Z5UKPmIjGsK5Ig\n\tiDE6dsBvyvnXPKYc5sWu/IfBs1Q4qX8SYL9i27LVQ/67ZTVZFfgDmViuE=","X-Received":["by 2002:a2e:7307:0:b0:2ef:2e8f:73e9 with SMTP id\n\t38308e7fff4ca-2f1a6d58167mr51796001fa.37.1723446482111; \n\tMon, 12 Aug 2024 00:08:02 -0700 (PDT)","by 2002:a2e:7307:0:b0:2ef:2e8f:73e9 with SMTP id\n\t38308e7fff4ca-2f1a6d58167mr51795621fa.37.1723446480986; \n\tMon, 12 Aug 2024 00:08:00 -0700 (PDT)"],"X-Google-Smtp-Source":"AGHT+IGALdzDndqFsf/zE+PeJbEb5/4wBkV9dF5Buv8trFrqahWce4aEMubs8FeWr7Oxo+pCSiJbdQ==","From":"Milan Zamazal ","To":"Laurent Pinchart ","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH] libcamera: controls: Improve formatting of control\n\tdescriptions in YAML","In-Reply-To":"<20240810023904.25658-1-laurent.pinchart@ideasonboard.com>\n\t(Laurent Pinchart's message of \"Sat, 10 Aug 2024 05:39:04 +0300\")","References":"<20240810023904.25658-1-laurent.pinchart@ideasonboard.com>","Date":"Mon, 12 Aug 2024 09:07:59 +0200","Message-ID":"<871q2uw75c.fsf@redhat.com>","User-Agent":"Gnus/5.13 (Gnus v5.13)","MIME-Version":"1.0","X-Mimecast-Spam-Score":"0","X-Mimecast-Originator":"redhat.com","Content-Type":"text/plain","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}},{"id":30727,"web_url":"https://patchwork.libcamera.org/comment/30727/","msgid":"<20240812104351.GC18729@pendragon.ideasonboard.com>","date":"2024-08-12T10:43:51","subject":"Re: [PATCH] libcamera: controls: Improve formatting of control\n\tdescriptions in YAML","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Milan,\n\nOn Mon, Aug 12, 2024 at 09:07:59AM +0200, Milan Zamazal wrote:\n> Laurent Pinchart writes:\n> \n> > The control descriptions from YAML files are extracted to generate\n> > Doxygen documentation blocks for the controls, which are then compiled\n> > to HTML. The extraction script uses the first line of the description\n> > as the Doxygen \\brief, and preserves blank lines to keep paragraphs.\n> >\n> > The control descriptions in the YAML files have however not all been\n> > written with this in mind. Many description elements are not formatted\n> > as block string scalars, in the first place, so blank lines are lost\n> > when parsing YAML. Furthermore, they often start with a long initial\n> > paragraph, making the \\brief description very long.\n> >\n> > Improve the documentation formatting by marking all multiline\n> > descriptions are block string scalars, and try to provide a short\n> > one-line first paragraph to be used as a \\brief. While at it, reflow the\n> > documentation to the 80 columns limit.\n> >\n> > The draft controls are left as-is, as they should evolve to non-draft\n> > controls eventually (and ideally sooner than later).\n> >\n> > Signed-off-by: Laurent Pinchart \n> \n> Reviewed-by: Milan Zamazal \n> \n> It might be worth to unify \"Report\" / \"Reports\" / \"\" (noun only) for\n> consistency, in a followup patch.\n\nThere are countless things I'd like to improve in the documentation :-)\nOnce we get closer to a v1.0, I think getting a professional tech writer\nto polish up the documentation in the entire code base would help. Until\nthen, incremental improvements are always a good idea, and I like your\nsuggestion.\n\n> > ---\n> > src/libcamera/control_ids_core.yaml | 466 +++++++++++++++++-----------\n> > src/libcamera/control_ids_rpi.yaml | 16 +-\n> > 2 files changed, 291 insertions(+), 191 deletions(-)\n> >\n> > diff --git a/src/libcamera/control_ids_core.yaml b/src/libcamera/control_ids_core.yaml\n> > index cf40771d3896..6381970b4d28 100644\n> > --- a/src/libcamera/control_ids_core.yaml\n> > +++ b/src/libcamera/control_ids_core.yaml\n> > @@ -32,10 +32,11 @@ controls:\n> > - AeMeteringMode:\n> > type: int32_t\n> > description: |\n> > - Specify a metering mode for the AE algorithm to use. The metering\n> > - modes determine which parts of the image are used to determine the\n> > - scene brightness. Metering modes may be platform specific and not\n> > - all metering modes may be supported.\n> > + Specify a metering mode for the AE algorithm to use.\n> > +\n> > + The metering modes determine which parts of the image are used to\n> > + determine the scene brightness. Metering modes may be platform specific\n> > + and not all metering modes may be supported.\n> > enum:\n> > - name: MeteringCentreWeighted\n> > value: 0\n> > @@ -56,33 +57,41 @@ controls:\n> > - AeConstraintMode:\n> > type: int32_t\n> > description: |\n> > - Specify a constraint mode for the AE algorithm to use. These determine\n> > - how the measured scene brightness is adjusted to reach the desired\n> > - target exposure. Constraint modes may be platform specific, and not\n> > - all constraint modes may be supported.\n> > + Specify a constraint mode for the AE algorithm to use.\n> > +\n> > + The constraint modes determine how the measured scene brightness is\n> > + adjusted to reach the desired target exposure. Constraint modes may be\n> > + platform specific, and not all constraint modes may be supported.\n> > enum:\n> > - name: ConstraintNormal\n> > value: 0\n> > - description: Default constraint mode.\n> > + description: |\n> > + Default constraint mode.\n> > +\n> > This mode aims to balance the exposure of different parts of the\n> > image so as to reach a reasonable average level. However, highlights\n> > in the image may appear over-exposed and lowlights may appear\n> > under-exposed.\n> > - name: ConstraintHighlight\n> > value: 1\n> > - description: Highlight constraint mode.\n> > + description: |\n> > + Highlight constraint mode.\n> > +\n> > This mode adjusts the exposure levels in order to try and avoid\n> > over-exposing the brightest parts (highlights) of an image.\n> > Other non-highlight parts of the image may appear under-exposed.\n> > - name: ConstraintShadows\n> > value: 2\n> > - description: Shadows constraint mode.\n> > + description: |\n> > + Shadows constraint mode.\n> > +\n> > This mode adjusts the exposure levels in order to try and avoid\n> > under-exposing the dark parts (shadows) of an image. Other normally\n> > exposed parts of the image may appear over-exposed.\n> > - name: ConstraintCustom\n> > value: 3\n> > - description: Custom constraint mode.\n> > + description: |\n> > + Custom constraint mode.\n> > \n> > # AeExposureMode needs further attention:\n> > # - Auto-generate max enum value.\n> > @@ -90,10 +99,11 @@ controls:\n> > - AeExposureMode:\n> > type: int32_t\n> > description: |\n> > - Specify an exposure mode for the AE algorithm to use. These specify\n> > - how the desired total exposure is divided between the shutter time\n> > - and the sensor's analogue gain. The exposure modes are platform\n> > - specific, and not all exposure modes may be supported.\n> > + Specify an exposure mode for the AE algorithm to use.\n> > +\n> > + The exposure modes specify how the desired total exposure is divided\n> > + between the shutter time and the sensor's analogue gain. They are\n> > + platform specific, and not all exposure modes may be supported.\n> > enum:\n> > - name: ExposureNormal\n> > value: 0\n> > @@ -111,8 +121,10 @@ controls:\n> > - ExposureValue:\n> > type: float\n> > description: |\n> > - Specify an Exposure Value (EV) parameter. The EV parameter will only be\n> > - applied if the AE algorithm is currently enabled.\n> > + Specify an Exposure Value (EV) parameter.\n> > +\n> > + The EV parameter will only be applied if the AE algorithm is currently\n> > + enabled.\n> > \n> > By convention EV adjusts the exposure as log2. For example\n> > EV = [-2, -1, 0.5, 0, 0.5, 1, 2] results in an exposure adjustment\n> > @@ -124,7 +136,9 @@ controls:\n> > type: int32_t\n> > description: |\n> > Exposure time (shutter speed) for the frame applied in the sensor\n> > - device. This value is specified in micro-seconds.\n> > + device.\n> > +\n> > + This value is specified in micro-seconds.\n> > \n> > Setting this value means that it is now fixed and the AE algorithm may\n> > not change it. Setting it back to zero returns it to the control of the\n> > @@ -142,6 +156,7 @@ controls:\n> > type: float\n> > description: |\n> > Analogue gain value applied in the sensor device.\n> > +\n> > The value of the control specifies the gain multiplier applied to all\n> > colour channels. This value cannot be lower than 1.0.\n> > \n> > @@ -160,9 +175,11 @@ controls:\n> > - AeFlickerMode:\n> > type: int32_t\n> > description: |\n> > - Set the flicker mode, which determines whether, and how, the AGC/AEC\n> > - algorithm attempts to hide flicker effects caused by the duty cycle of\n> > - artificial lighting.\n> > + Set the flicker avoidance mode for AGC/AEC.\n> > +\n> > + The flicker mode determines whether, and how, the AGC/AEC algorithm\n> > + attempts to hide flicker effects caused by the duty cycle of artificial\n> > + lighting.\n> > \n> > Although implementation dependent, many algorithms for \"flicker\n> > avoidance\" work by restricting this exposure time to integer multiples\n> > @@ -176,16 +193,21 @@ controls:\n> > enum:\n> > - name: FlickerOff\n> > value: 0\n> > - description: No flicker avoidance is performed.\n> > + description: |\n> > + No flicker avoidance is performed.\n> > - name: FlickerManual\n> > value: 1\n> > - description: Manual flicker avoidance.\n> > + description: |\n> > + Manual flicker avoidance.\n> > +\n> > Suppress flicker effects caused by lighting running with a period\n> > specified by the AeFlickerPeriod control.\n> > \\sa AeFlickerPeriod\n> > - name: FlickerAuto\n> > value: 2\n> > - description: Automatic flicker period detection and avoidance.\n> > + description: |\n> > + Automatic flicker period detection and avoidance.\n> > +\n> > The system will automatically determine the most likely value of\n> > flicker period, and avoid flicker of this frequency. Once flicker\n> > is being corrected, it is implementation dependent whether the\n> > @@ -194,7 +216,9 @@ controls:\n> > \n> > - AeFlickerPeriod:\n> > type: int32_t\n> > - description: Manual flicker period in microseconds.\n> > + description: |\n> > + Manual flicker period in microseconds.\n> > +\n> > This value sets the current flicker period to avoid. It is used when\n> > AeFlickerMode is set to FlickerManual.\n> > \n> > @@ -212,7 +236,9 @@ controls:\n> > \n> > - AeFlickerDetected:\n> > type: int32_t\n> > - description: Flicker period detected in microseconds.\n> > + description: |\n> > + Flicker period detected in microseconds.\n> > +\n> > The value reported here indicates the currently detected flicker\n> > period, or zero if no flicker at all is detected.\n> > \n> > @@ -233,21 +259,25 @@ controls:\n> > - Brightness:\n> > type: float\n> > description: |\n> > - Specify a fixed brightness parameter. Positive values (up to 1.0)\n> > - produce brighter images; negative values (up to -1.0) produce darker\n> > - images and 0.0 leaves pixels unchanged.\n> > + Specify a fixed brightness parameter.\n> > +\n> > + Positive values (up to 1.0) produce brighter images; negative values\n> > + (up to -1.0) produce darker images and 0.0 leaves pixels unchanged.\n> > \n> > - Contrast:\n> > type: float\n> > description: |\n> > - Specify a fixed contrast parameter. Normal contrast is given by the\n> > - value 1.0; larger values produce images with more contrast.\n> > + Specify a fixed contrast parameter.\n> > +\n> > + Normal contrast is given by the value 1.0; larger values produce images\n> > + with more contrast.\n> > \n> > - Lux:\n> > type: float\n> > description: |\n> > - Report an estimate of the current illuminance level in lux. The Lux\n> > - control can only be returned in metadata.\n> > + Report an estimate of the current illuminance level in lux.\n> > +\n> > + The Lux control can only be returned in metadata.\n> > \n> > - AwbEnable:\n> > type: bool\n> > @@ -262,8 +292,10 @@ controls:\n> > - AwbMode:\n> > type: int32_t\n> > description: |\n> > - Specify the range of illuminants to use for the AWB algorithm. The modes\n> > - supported are platform specific, and not all modes may be supported.\n> > + Specify the range of illuminants to use for the AWB algorithm.\n> > +\n> > + The modes supported are platform specific, and not all modes may be\n> > + supported.\n> > enum:\n> > - name: AwbAuto\n> > value: 0\n> > @@ -305,37 +337,43 @@ controls:\n> > type: float\n> > description: |\n> > Pair of gain values for the Red and Blue colour channels, in that\n> > - order. ColourGains can only be applied in a Request when the AWB is\n> > - disabled.\n> > + order.\n> > +\n> > + ColourGains can only be applied in a Request when the AWB is disabled.\n> > \n> > \\sa AwbEnable\n> > size: [2]\n> > \n> > - ColourTemperature:\n> > type: int32_t\n> > - description: Report the current estimate of the colour temperature, in\n> > - kelvin, for this frame. The ColourTemperature control can only be\n> > - returned in metadata.\n> > + description: |\n> > + Report the estimate of the colour temperature for the frame, in kelvin.\n> > +\n> > + The ColourTemperature control can only be returned in metadata.\n> > \n> > - Saturation:\n> > type: float\n> > description: |\n> > - Specify a fixed saturation parameter. Normal saturation is given by\n> > - the value 1.0; larger values produce more saturated colours; 0.0\n> > - produces a greyscale image.\n> > + Specify a fixed saturation parameter.\n> > +\n> > + Normal saturation is given by the value 1.0; larger values produce more\n> > + saturated colours; 0.0 produces a greyscale image.\n> > \n> > - SensorBlackLevels:\n> > type: int32_t\n> > description: |\n> > - Reports the sensor black levels used for processing a frame, in the\n> > - order R, Gr, Gb, B. These values are returned as numbers out of a 16-bit\n> > - pixel range (as if pixels ranged from 0 to 65535). The SensorBlackLevels\n> > - control can only be returned in metadata.\n> > + Reports the sensor black levels used for processing a frame.\n> > +\n> > + The values are in the order R, Gr, Gb, B. They are returned as numbers\n> > + out of a 16-bit pixel range (as if pixels ranged from 0 to 65535). The\n> > + SensorBlackLevels control can only be returned in metadata.\n> > size: [4]\n> > \n> > - Sharpness:\n> > type: float\n> > description: |\n> > + Intensity of the sharpening applied to the image.\n> > +\n> > A value of 0.0 means no sharpening. The minimum value means\n> > minimal sharpening, and shall be 0.0 unless the camera can't\n> > disable sharpening completely. The default value shall give a\n> > @@ -349,6 +387,7 @@ controls:\n> > type: int32_t\n> > description: |\n> > Reports a Figure of Merit (FoM) to indicate how in-focus the frame is.\n> > +\n> > A larger FocusFoM value indicates a more in-focus frame. This singular\n> > value may be based on a combination of statistics gathered from\n> > multiple focus regions within an image. The number of focus regions and\n> > @@ -359,11 +398,13 @@ controls:\n> > - ColourCorrectionMatrix:\n> > type: float\n> > description: |\n> > - The 3x3 matrix that converts camera RGB to sRGB within the\n> > - imaging pipeline. This should describe the matrix that is used\n> > - after pixels have been white-balanced, but before any gamma\n> > - transformation. The 3x3 matrix is stored in conventional reading\n> > - order in an array of 9 floating point values.\n> > + The 3x3 matrix that converts camera RGB to sRGB within the imaging\n> > + pipeline.\n> > +\n> > + This should describe the matrix that is used after pixels have been\n> > + white-balanced, but before any gamma transformation. The 3x3 matrix is\n> > + stored in conventional reading order in an array of 9 floating point\n> > + values.\n> > \n> > size: [3,3]\n> > \n> > @@ -371,10 +412,12 @@ controls:\n> > type: Rectangle\n> > description: |\n> > Sets the image portion that will be scaled to form the whole of\n> > - the final output image. The (x,y) location of this rectangle is\n> > - relative to the PixelArrayActiveAreas that is being used. The units\n> > - remain native sensor pixels, even if the sensor is being used in\n> > - a binning or skipping mode.\n> > + the final output image.\n> > +\n> > + The (x,y) location of this rectangle is relative to the\n> > + PixelArrayActiveAreas that is being used. The units remain native\n> > + sensor pixels, even if the sensor is being used in a binning or\n> > + skipping mode.\n> > \n> > This control is only present when the pipeline supports scaling. Its\n> > maximum valid value is given by the properties::ScalerCropMaximum\n> > @@ -401,8 +444,9 @@ controls:\n> > type: int64_t\n> > description: |\n> > The instantaneous frame duration from start of frame exposure to start\n> > - of next exposure, expressed in microseconds. This control is meant to\n> > - be returned in metadata.\n> > + of next exposure, expressed in microseconds.\n> > +\n> > + This control is meant to be returned in metadata.\n> > \n> > - FrameDurationLimits:\n> > type: int64_t\n> > @@ -444,9 +488,11 @@ controls:\n> > - SensorTemperature:\n> > type: float\n> > description: |\n> > - Temperature measure from the camera sensor in Celsius. This is typically\n> > - obtained by a thermal sensor present on-die or in the camera module. The\n> > - range of reported temperatures is device dependent.\n> > + Temperature measure from the camera sensor in Celsius.\n> > +\n> > + This value is typically obtained by a thermal sensor present on-die or\n> > + in the camera module. The range of reported temperatures is device\n> > + dependent.\n> > \n> > The SensorTemperature control will only be returned in metadata if a\n> > thermal sensor is present.\n> > @@ -468,7 +514,7 @@ controls:\n> > - AfMode:\n> > type: int32_t\n> > description: |\n> > - Control to set the mode of the AF (autofocus) algorithm.\n> > + The mode of the AF (autofocus) algorithm.\n> > \n> > An implementation may choose not to implement all the modes.\n> > \n> > @@ -476,12 +522,12 @@ controls:\n> > - name: AfModeManual\n> > value: 0\n> > description: |\n> > - The AF algorithm is in manual mode. In this mode it will never\n> > - perform any action nor move the lens of its own accord, but an\n> > - application can specify the desired lens position using the\n> > - LensPosition control.\n> > + The AF algorithm is in manual mode.\n> > \n> > - In this mode the AfState will always report AfStateIdle.\n> > + In this mode it will never perform any action nor move the lens of\n> > + its own accord, but an application can specify the desired lens\n> > + position using the LensPosition control. The AfState will always\n> > + report AfStateIdle.\n> > \n> > If the camera is started in AfModeManual, it will move the focus\n> > lens to the position specified by the LensPosition control.\n> > @@ -492,31 +538,34 @@ controls:\n> > - name: AfModeAuto\n> > value: 1\n> > description: |\n> > - The AF algorithm is in auto mode. This means that the algorithm\n> > - will never move the lens or change state unless the AfTrigger\n> > - control is used. The AfTrigger control can be used to initiate a\n> > - focus scan, the results of which will be reported by AfState.\n> > + The AF algorithm is in auto mode.\n> > \n> > - If the autofocus algorithm is moved from AfModeAuto to another\n> > - mode while a scan is in progress, the scan is cancelled\n> > - immediately, without waiting for the scan to finish.\n> > + In this mode the algorithm will never move the lens or change state\n> > + unless the AfTrigger control is used. The AfTrigger control can be\n> > + used to initiate a focus scan, the results of which will be\n> > + reported by AfState.\n> > \n> > - When first entering this mode the AfState will report\n> > - AfStateIdle. When a trigger control is sent, AfState will\n> > - report AfStateScanning for a period before spontaneously\n> > - changing to AfStateFocused or AfStateFailed, depending on\n> > - the outcome of the scan. It will remain in this state until\n> > - another scan is initiated by the AfTrigger control. If a scan is\n> > - cancelled (without changing to another mode), AfState will return\n> > - to AfStateIdle.\n> > + If the autofocus algorithm is moved from AfModeAuto to another mode\n> > + while a scan is in progress, the scan is cancelled immediately,\n> > + without waiting for the scan to finish.\n> > +\n> > + When first entering this mode the AfState will report AfStateIdle.\n> > + When a trigger control is sent, AfState will report AfStateScanning\n> > + for a period before spontaneously changing to AfStateFocused or\n> > + AfStateFailed, depending on the outcome of the scan. It will remain\n> > + in this state until another scan is initiated by the AfTrigger\n> > + control. If a scan is cancelled (without changing to another mode),\n> > + AfState will return to AfStateIdle.\n> > - name: AfModeContinuous\n> > value: 2\n> > description: |\n> > - The AF algorithm is in continuous mode. This means that the lens can\n> > - re-start a scan spontaneously at any moment, without any user\n> > - intervention. The AfState still reports whether the algorithm is\n> > - currently scanning or not, though the application has no ability to\n> > - initiate or cancel scans, nor to move the lens for itself.\n> > + The AF algorithm is in continuous mode.\n> > +\n> > + In this mode the lens can re-start a scan spontaneously at any\n> > + moment, without any user intervention. The AfState still reports\n> > + whether the algorithm is currently scanning or not, though the\n> > + application has no ability to initiate or cancel scans, nor to move\n> > + the lens for itself.\n> > \n> > However, applications can pause the AF algorithm from continuously\n> > scanning by using the AfPause control. This allows video or still\n> > @@ -529,34 +578,40 @@ controls:\n> > - AfRange:\n> > type: int32_t\n> > description: |\n> > - Control to set the range of focus distances that is scanned. An\n> > - implementation may choose not to implement all the options here.\n> > + The range of focus distances that is scanned.\n> > +\n> > + An implementation may choose not to implement all the options here.\n> > enum:\n> > - name: AfRangeNormal\n> > value: 0\n> > description: |\n> > - A wide range of focus distances is scanned, all the way from\n> > - infinity down to close distances, though depending on the\n> > - implementation, possibly not including the very closest macro\n> > - positions.\n> > + A wide range of focus distances is scanned.\n> > +\n> > + Scanned distances cover all the way from infinity down to close\n> > + distances, though depending on the implementation, possibly not\n> > + including the very closest macro positions.\n> > - name: AfRangeMacro\n> > value: 1\n> > - description: Only close distances are scanned.\n> > + description: |\n> > + Only close distances are scanned.\n> > - name: AfRangeFull\n> > value: 2\n> > description: |\n> > - The full range of focus distances is scanned just as with\n> > - AfRangeNormal but this time including the very closest macro\n> > - positions.\n> > + The full range of focus distances is scanned.\n> > +\n> > + This range is similar to AfRangeNormal but includes the very\n> > + closest macro positions.\n> > \n> > - AfSpeed:\n> > type: int32_t\n> > description: |\n> > - Control that determines whether the AF algorithm is to move the lens\n> > - as quickly as possible or more steadily. For example, during video\n> > - recording it may be desirable not to move the lens too abruptly, but\n> > - when in a preview mode (waiting for a still capture) it may be\n> > - helpful to move the lens as quickly as is reasonably possible.\n> > + Determine whether the AF is to move the lens as quickly as possible or\n> > + more steadily.\n> > +\n> > + For example, during video recording it may be desirable not to move the\n> > + lens too abruptly, but when in a preview mode (waiting for a still\n> > + capture) it may be helpful to move the lens as quickly as is reasonably\n> > + possible.\n> > enum:\n> > - name: AfSpeedNormal\n> > value: 0\n> > @@ -568,25 +623,27 @@ controls:\n> > - AfMetering:\n> > type: int32_t\n> > description: |\n> > - Instruct the AF algorithm how it should decide which parts of the image\n> > - should be used to measure focus.\n> > + The parts of the image used by the AF algorithm to measure focus.\n> > enum:\n> > - name: AfMeteringAuto\n> > value: 0\n> > - description: The AF algorithm should decide for itself where it will\n> > - measure focus.\n> > + description: |\n> > + Let the AF algorithm decide for itself where it will measure focus.\n> > - name: AfMeteringWindows\n> > value: 1\n> > - description: The AF algorithm should use the rectangles defined by\n> > - the AfWindows control to measure focus. If no windows are specified\n> > - the behaviour is platform dependent.\n> > + description: |\n> > + Use the rectangles defined by the AfWindows control to measure focus.\n> > +\n> > + If no windows are specified the behaviour is platform dependent.\n> > \n> > - AfWindows:\n> > type: Rectangle\n> > description: |\n> > - Sets the focus windows used by the AF algorithm when AfMetering is set\n> > - to AfMeteringWindows. The units used are pixels within the rectangle\n> > - returned by the ScalerCropMaximum property.\n> > + The focus windows used by the AF algorithm when AfMetering is set to\n> > + AfMeteringWindows.\n> > +\n> > + The units used are pixels within the rectangle returned by the\n> > + ScalerCropMaximum property.\n> > \n> > In order to be activated, a rectangle must be programmed with non-zero\n> > width and height. Internally, these rectangles are intersected with the\n> > @@ -611,23 +668,33 @@ controls:\n> > - AfTrigger:\n> > type: int32_t\n> > description: |\n> > - This control starts an autofocus scan when AfMode is set to AfModeAuto,\n> > - and can also be used to terminate a scan early.\n> > + Start an autofocus scan.\n> > \n> > - It is ignored if AfMode is set to AfModeManual or AfModeContinuous.\n> > + This control starts an autofocus scan when AfMode is set to AfModeAuto,\n> > + and is ignored if AfMode is set to AfModeManual or AfModeContinuous. It\n> > + can also be used to terminate a scan early.\n> > \n> > enum:\n> > - name: AfTriggerStart\n> > value: 0\n> > - description: Start an AF scan. Ignored if a scan is in progress.\n> > + description: |\n> > + Start an AF scan.\n> > +\n> > + Setting the control to AfTriggerStart is ignored if a scan is in\n> > + progress.\n> > - name: AfTriggerCancel\n> > value: 1\n> > - description: Cancel an AF scan. This does not cause the lens to move\n> > - anywhere else. Ignored if no scan is in progress.\n> > + description: |\n> > + Cancel an AF scan.\n> > +\n> > + This does not cause the lens to move anywhere else. Ignored if no\n> > + scan is in progress.\n> > \n> > - AfPause:\n> > type: int32_t\n> > description: |\n> > + Pause lens movements when in continuous autofocus mode.\n> > +\n> > This control has no effect except when in continuous autofocus mode\n> > (AfModeContinuous). It can be used to pause any lens movements while\n> > (for example) images are captured. The algorithm remains inactive\n> > @@ -637,17 +704,21 @@ controls:\n> > - name: AfPauseImmediate\n> > value: 0\n> > description: |\n> > - Pause the continuous autofocus algorithm immediately, whether or not\n> > - any kind of scan is underway. AfPauseState will subsequently report\n> > + Pause the continuous autofocus algorithm immediately.\n> > +\n> > + The autofocus algorithm is paused whether or not any kind of scan\n> > + is underway. AfPauseState will subsequently report\n> > AfPauseStatePaused. AfState may report any of AfStateScanning,\n> > AfStateFocused or AfStateFailed, depending on the algorithm's state\n> > when it received this control.\n> > - name: AfPauseDeferred\n> > value: 1\n> > description: |\n> > - This is similar to AfPauseImmediate, and if the AfState is currently\n> > - reporting AfStateFocused or AfStateFailed it will remain in that\n> > - state and AfPauseState will report AfPauseStatePaused.\n> > + Pause the continuous autofocus algorithm at the end of the scan.\n> > +\n> > + This is similar to AfPauseImmediate, and if the AfState is\n> > + currently reporting AfStateFocused or AfStateFailed it will remain\n> > + in that state and AfPauseState will report AfPauseStatePaused.\n> > \n> > However, if the algorithm is scanning (AfStateScanning),\n> > AfPauseState will report AfPauseStatePausing until the scan is\n> > @@ -658,15 +729,18 @@ controls:\n> > - name: AfPauseResume\n> > value: 2\n> > description: |\n> > - Resume continuous autofocus operation. The algorithm starts again\n> > - from exactly where it left off, and AfPauseState will report\n> > - AfPauseStateRunning.\n> > + Resume continuous autofocus operation.\n> > +\n> > + The algorithm starts again from exactly where it left off, and\n> > + AfPauseState will report AfPauseStateRunning.\n> > \n> > - LensPosition:\n> > type: float\n> > description: |\n> > - Acts as a control to instruct the lens to move to a particular position\n> > - and also reports back the position of the lens for each frame.\n> > + Set and report the focus lens position.\n> > +\n> > + This control instructs the lens to move to a particular position and\n> > + also reports back the position of the lens for each frame.\n> > \n> > The LensPosition control is ignored unless the AfMode is set to\n> > AfModeManual, though the value is reported back unconditionally in all\n> > @@ -680,16 +754,16 @@ controls:\n> > \n> > For example:\n> > \n> > - 0 moves the lens to infinity.\n> > - 0.5 moves the lens to focus on objects 2m away.\n> > - 2 moves the lens to focus on objects 50cm away.\n> > - And larger values will focus the lens closer.\n> > + - 0 moves the lens to infinity.\n> > + - 0.5 moves the lens to focus on objects 2m away.\n> > + - 2 moves the lens to focus on objects 50cm away.\n> > + - And larger values will focus the lens closer.\n> > \n> > - The default value of the control should indicate a good general position\n> > - for the lens, often corresponding to the hyperfocal distance (the\n> > - closest position for which objects at infinity are still acceptably\n> > - sharp). The minimum will often be zero (meaning infinity), and the\n> > - maximum value defines the closest focus position.\n> > + The default value of the control should indicate a good general\n> > + position for the lens, often corresponding to the hyperfocal distance\n> > + (the closest position for which objects at infinity are still\n> > + acceptably sharp). The minimum will often be zero (meaning infinity),\n> > + and the maximum value defines the closest focus position.\n> > \n> > \\todo Define a property to report the Hyperfocal distance of calibrated\n> > lenses.\n> > @@ -697,22 +771,25 @@ controls:\n> > - AfState:\n> > type: int32_t\n> > description: |\n> > - Reports the current state of the AF algorithm in conjunction with the\n> > - reported AfMode value and (in continuous AF mode) the AfPauseState\n> > - value. The possible state changes are described below, though we note\n> > - the following state transitions that occur when the AfMode is changed.\n> > + The current state of the AF algorithm.\n> > +\n> > + This control reports the current state of the AF algorithm in\n> > + conjunction with the reported AfMode value and (in continuous AF mode)\n> > + the AfPauseState value. The possible state changes are described below,\n> > + though we note the following state transitions that occur when the\n> > + AfMode is changed.\n> > \n> > If the AfMode is set to AfModeManual, then the AfState will always\n> > - report AfStateIdle (even if the lens is subsequently moved). Changing to\n> > - the AfModeManual state does not initiate any lens movement.\n> > + report AfStateIdle (even if the lens is subsequently moved). Changing\n> > + to the AfModeManual state does not initiate any lens movement.\n> > \n> > If the AfMode is set to AfModeAuto then the AfState will report\n> > - AfStateIdle. However, if AfModeAuto and AfTriggerStart are sent together\n> > - then AfState will omit AfStateIdle and move straight to AfStateScanning\n> > - (and start a scan).\n> > + AfStateIdle. However, if AfModeAuto and AfTriggerStart are sent\n> > + together then AfState will omit AfStateIdle and move straight to\n> > + AfStateScanning (and start a scan).\n> > \n> > - If the AfMode is set to AfModeContinuous then the AfState will initially\n> > - report AfStateScanning.\n> > + If the AfMode is set to AfModeContinuous then the AfState will\n> > + initially report AfStateScanning.\n> > \n> > enum:\n> > - name: AfStateIdle\n> > @@ -725,11 +802,12 @@ controls:\n> > value: 1\n> > description: |\n> > The AF algorithm is in auto mode (AfModeAuto), and a scan has been\n> > - started using the AfTrigger control. The scan can be cancelled by\n> > - sending AfTriggerCancel at which point the algorithm will either\n> > - move back to AfStateIdle or, if the scan actually completes before\n> > - the cancel request is processed, to one of AfStateFocused or\n> > - AfStateFailed.\n> > + started using the AfTrigger control.\n> > +\n> > + The scan can be cancelled by sending AfTriggerCancel at which point\n> > + the algorithm will either move back to AfStateIdle or, if the scan\n> > + actually completes before the cancel request is processed, to one\n> > + of AfStateFocused or AfStateFailed.\n> > \n> > Alternatively the AF algorithm could be in continuous mode\n> > (AfModeContinuous) at which point it may enter this state\n> > @@ -750,9 +828,12 @@ controls:\n> > - AfPauseState:\n> > type: int32_t\n> > description: |\n> > - Only applicable in continuous (AfModeContinuous) mode, this reports\n> > - whether the algorithm is currently running, paused or pausing (that is,\n> > - will pause as soon as any in-progress scan completes).\n> > + Report whether the autofocus is currently running, paused or pausing.\n> > +\n> > + This control is only applicable in continuous (AfModeContinuous) mode,\n> > + and reports whether the algorithm is currently running, paused or\n> > + pausing (that is, will pause as soon as any in-progress scan\n> > + completes).\n> > \n> > Any change to AfMode will cause AfPauseStateRunning to be reported.\n> > \n> > @@ -766,22 +847,27 @@ controls:\n> > value: 1\n> > description: |\n> > Continuous AF has been sent an AfPauseDeferred control, and will\n> > - pause as soon as any in-progress scan completes (and then report\n> > - AfPauseStatePaused). No new scans will be start spontaneously until\n> > + pause as soon as any in-progress scan completes.\n> > +\n> > + When the scan completes, the AfPauseState control will report\n> > + AfPauseStatePaused. No new scans will be start spontaneously until\n> > the AfPauseResume control is sent.\n> > - name: AfPauseStatePaused\n> > value: 2\n> > description: |\n> > - Continuous AF is paused. No further state changes or lens movements\n> > - will occur until the AfPauseResume control is sent.\n> > + Continuous AF is paused.\n> > +\n> > + No further state changes or lens movements will occur until the\n> > + AfPauseResume control is sent.\n> > \n> > - HdrMode:\n> > type: int32_t\n> > description: |\n> > - Control to set the mode to be used for High Dynamic Range (HDR)\n> > - imaging. HDR techniques typically include multiple exposure, image\n> > - fusion and tone mapping techniques to improve the dynamic range of the\n> > - resulting images.\n> > + Set the mode to be used for High Dynamic Range (HDR) imaging.\n> > +\n> > + HDR techniques typically include multiple exposure, image fusion and\n> > + tone mapping techniques to improve the dynamic range of the resulting\n> > + images.\n> > \n> > When using an HDR mode, images are captured with different sets of AGC\n> > settings called HDR channels. Channels indicate in particular the type\n> > @@ -795,16 +881,18 @@ controls:\n> > - name: HdrModeOff\n> > value: 0\n> > description: |\n> > - HDR is disabled. Metadata for this frame will not include the\n> > - HdrChannel control.\n> > + HDR is disabled.\n> > +\n> > + Metadata for this frame will not include the HdrChannel control.\n> > - name: HdrModeMultiExposureUnmerged\n> > value: 1\n> > description: |\n> > Multiple exposures will be generated in an alternating fashion.\n> > - However, they will not be merged together and will be returned to\n> > - the application as they are. Each image will be tagged with the\n> > - correct HDR channel, indicating what kind of exposure it is. The\n> > - tag should be the same as in the HdrModeMultiExposure case.\n> > +\n> > + The multiple exposures will not be merged together and will be\n> > + returned to the application as they are. Each image will be tagged\n> > + with the correct HDR channel, indicating what kind of exposure it\n> > + is. The tag should be the same as in the HdrModeMultiExposure case.\n> > \n> > The expectation is that an application using this mode would merge\n> > the frames to create HDR images for itself if it requires them.\n> > @@ -812,8 +900,10 @@ controls:\n> > value: 2\n> > description: |\n> > Multiple exposures will be generated and merged to create HDR\n> > - images. Each image will be tagged with the HDR channel (long, medium\n> > - or short) that arrived and which caused this image to be output.\n> > + images.\n> > +\n> > + Each image will be tagged with the HDR channel (long, medium or\n> > + short) that arrived and which caused this image to be output.\n> > \n> > Systems that use two channels for HDR will return images tagged\n> > alternately as the short and long channel. Systems that use three\n> > @@ -823,24 +913,29 @@ controls:\n> > value: 3\n> > description: |\n> > Multiple frames all at a single exposure will be used to create HDR\n> > - images. These images should be reported as all corresponding to the\n> > - HDR short channel.\n> > + images.\n> > +\n> > + These images should be reported as all corresponding to the HDR\n> > + short channel.\n> > - name: HdrModeNight\n> > value: 4\n> > description: |\n> > - Multiple frames will be combined to produce \"night mode\" images. It\n> > - is up to the implementation exactly which HDR channels it uses, and\n> > - the images will all be tagged accordingly with the correct HDR\n> > + Multiple frames will be combined to produce \"night mode\" images.\n> > +\n> > + It is up to the implementation exactly which HDR channels it uses,\n> > + and the images will all be tagged accordingly with the correct HDR\n> > channel information.\n> > \n> > - HdrChannel:\n> > type: int32_t\n> > description: |\n> > + The HDR channel used to capture the frame.\n> > +\n> > This value is reported back to the application so that it can discover\n> > - whether this capture corresponds to the short or long exposure image (or\n> > - any other image used by the HDR procedure). An application can monitor\n> > - the HDR channel to discover when the differently exposed images have\n> > - arrived.\n> > + whether this capture corresponds to the short or long exposure image\n> > + (or any other image used by the HDR procedure). An application can\n> > + monitor the HDR channel to discover when the differently exposed images\n> > + have arrived.\n> > \n> > This metadata is only available when an HDR mode has been enabled.\n> > \n> > @@ -868,8 +963,9 @@ controls:\n> > - Gamma:\n> > type: float\n> > description: |\n> > - Specify a fixed gamma value. Default must be 2.2 which closely mimics\n> > - sRGB gamma. Note that this is camera gamma, so it is applied as\n> > - 1.0/gamma.\n> > + Specify a fixed gamma value.\n> > +\n> > + The default gamma value must be 2.2 which closely mimics sRGB gamma.\n> > + Note that this is camera gamma, so it is applied as 1.0/gamma.\n> > \n> > ...\n> > diff --git a/src/libcamera/control_ids_rpi.yaml b/src/libcamera/control_ids_rpi.yaml\n> > index cb097f887e16..42c4bf5d408f 100644\n> > --- a/src/libcamera/control_ids_rpi.yaml\n> > +++ b/src/libcamera/control_ids_rpi.yaml\n> > @@ -10,9 +10,11 @@ controls:\n> > - StatsOutputEnable:\n> > type: bool\n> > description: |\n> > - Toggles the Raspberry Pi IPA to output a binary dump of the hardware\n> > - generated statistics through the Request metadata in the Bcm2835StatsOutput\n> > - control.\n> > + Toggles the Raspberry Pi IPA to output the hardware generated statistics.\n> > +\n> > + When this control is set to true, the IPA outputs a binary dump of the\n> > + hardware generated statistics through the Request metadata in the\n> > + Bcm2835StatsOutput control.\n> > \n> > \\sa Bcm2835StatsOutput\n> > \n> > @@ -20,9 +22,11 @@ controls:\n> > type: uint8_t\n> > size: [n]\n> > description: |\n> > - Span of the BCM2835 ISP generated statistics for the current frame. This\n> > - is sent in the Request metadata if the StatsOutputEnable is set to true.\n> > - The statistics struct definition can be found in include/linux/bcm2835-isp.h.\n> > + Span of the BCM2835 ISP generated statistics for the current frame.\n> > +\n> > + This is sent in the Request metadata if the StatsOutputEnable is set to\n> > + true. The statistics struct definition can be found in\n> > + include/linux/bcm2835-isp.h.\n> > \n> > \\sa StatsOutputEnable\n> > \n> >\n> > base-commit: 62760bd2605a83e663b9003244ff42f8946f8955","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 0F53BC323E\n\tfor ;\n\tMon, 12 Aug 2024 10:44:19 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id CE31B633B5;\n\tMon, 12 Aug 2024 12:44:17 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id BFC3963369\n\tfor ;\n\tMon, 12 Aug 2024 12:44:15 +0200 (CEST)","from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi\n\t[81.175.209.231])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 9953D6B5;\n\tMon, 12 Aug 2024 12:43:18 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"npMFSzYi\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723459399;\n\tbh=MZSbxLwur088Y7whPSKgwiYWtE/8qsbZmHrfbvFegNA=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=npMFSzYiR6fn3b9RvSp0RQHlFIazQaPs8OvmAQVxD8ecfnBSVBujktz/nYmQ1FICd\n\t9Mvp6AK8KAj1Mt4qKdBbSICnrK8oY7YPV9sIfdZ4d88Smb66K8fv+BVE0M2FSjT6ZB\n\tDaG1Cj5tiMIUAhxJ9+KuCnaN1/S1BtlxcjhGXRaU=","Date":"Mon, 12 Aug 2024 13:43:51 +0300","From":"Laurent Pinchart ","To":"Milan Zamazal ","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH] libcamera: controls: Improve formatting of control\n\tdescriptions in YAML","Message-ID":"<20240812104351.GC18729@pendragon.ideasonboard.com>","References":"<20240810023904.25658-1-laurent.pinchart@ideasonboard.com>\n\t<871q2uw75c.fsf@redhat.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<871q2uw75c.fsf@redhat.com>","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}},{"id":30845,"web_url":"https://patchwork.libcamera.org/comment/30845/","msgid":"<172375855226.129190.3864727950074612030@ping.linuxembedded.co.uk>","date":"2024-08-15T21:49:12","subject":"Re: [PATCH] libcamera: controls: Improve formatting of control\n\tdescriptions in YAML","submitter":{"id":4,"url":"https://patchwork.libcamera.org/api/people/4/","name":"Kieran Bingham","email":"kieran.bingham@ideasonboard.com"},"content":"Quoting Laurent Pinchart (2024-08-10 03:39:04)\n> The control descriptions from YAML files are extracted to generate\n> Doxygen documentation blocks for the controls, which are then compiled\n> to HTML. The extraction script uses the first line of the description\n> as the Doxygen \\brief, and preserves blank lines to keep paragraphs.\n> \n\nI don't think I even realised that happened!\n\n> The control descriptions in the YAML files have however not all been\n> written with this in mind. Many description elements are not formatted\n> as block string scalars, in the first place, so blank lines are lost\n> when parsing YAML. Furthermore, they often start with a long initial\n> paragraph, making the \\brief description very long.\n> \n> Improve the documentation formatting by marking all multiline\n> descriptions are block string scalars, and try to provide a short\n\ns/are/as/ maybe but it doesn't matter too much.\n\n> one-line first paragraph to be used as a \\brief. While at it, reflow the\n> documentation to the 80 columns limit.\n> \n> The draft controls are left as-is, as they should evolve to non-draft\n> controls eventually (and ideally sooner than later).\n> \n> Signed-off-by: Laurent Pinchart \n> ---\n> src/libcamera/control_ids_core.yaml | 466 +++++++++++++++++-----------\n> src/libcamera/control_ids_rpi.yaml | 16 +-\n> 2 files changed, 291 insertions(+), 191 deletions(-)\n> \n> diff --git a/src/libcamera/control_ids_core.yaml b/src/libcamera/control_ids_core.yaml\n> index cf40771d3896..6381970b4d28 100644\n> --- a/src/libcamera/control_ids_core.yaml\n> +++ b/src/libcamera/control_ids_core.yaml\n> @@ -32,10 +32,11 @@ controls:\n> - AeMeteringMode:\n> type: int32_t\n> description: |\n> - Specify a metering mode for the AE algorithm to use. The metering\n> - modes determine which parts of the image are used to determine the\n> - scene brightness. Metering modes may be platform specific and not\n> - all metering modes may be supported.\n> + Specify a metering mode for the AE algorithm to use.\n> +\n> + The metering modes determine which parts of the image are used to\n> + determine the scene brightness. Metering modes may be platform specific\n> + and not all metering modes may be supported.\n> enum:\n> - name: MeteringCentreWeighted\n> value: 0\n> @@ -56,33 +57,41 @@ controls:\n> - AeConstraintMode:\n> type: int32_t\n> description: |\n> - Specify a constraint mode for the AE algorithm to use. These determine\n> - how the measured scene brightness is adjusted to reach the desired\n> - target exposure. Constraint modes may be platform specific, and not\n> - all constraint modes may be supported.\n> + Specify a constraint mode for the AE algorithm to use.\n> +\n> + The constraint modes determine how the measured scene brightness is\n> + adjusted to reach the desired target exposure. Constraint modes may be\n> + platform specific, and not all constraint modes may be supported.\n> enum:\n> - name: ConstraintNormal\n> value: 0\n> - description: Default constraint mode.\n> + description: |\n> + Default constraint mode.\n> +\n> This mode aims to balance the exposure of different parts of the\n> image so as to reach a reasonable average level. However, highlights\n> in the image may appear over-exposed and lowlights may appear\n> under-exposed.\n> - name: ConstraintHighlight\n> value: 1\n> - description: Highlight constraint mode.\n> + description: |\n> + Highlight constraint mode.\n> +\n> This mode adjusts the exposure levels in order to try and avoid\n> over-exposing the brightest parts (highlights) of an image.\n> Other non-highlight parts of the image may appear under-exposed.\n> - name: ConstraintShadows\n> value: 2\n> - description: Shadows constraint mode.\n> + description: |\n> + Shadows constraint mode.\n> +\n> This mode adjusts the exposure levels in order to try and avoid\n> under-exposing the dark parts (shadows) of an image. Other normally\n> exposed parts of the image may appear over-exposed.\n> - name: ConstraintCustom\n> value: 3\n> - description: Custom constraint mode.\n> + description: |\n> + Custom constraint mode.\n> \n> # AeExposureMode needs further attention:\n> # - Auto-generate max enum value.\n> @@ -90,10 +99,11 @@ controls:\n> - AeExposureMode:\n> type: int32_t\n> description: |\n> - Specify an exposure mode for the AE algorithm to use. These specify\n> - how the desired total exposure is divided between the shutter time\n> - and the sensor's analogue gain. The exposure modes are platform\n> - specific, and not all exposure modes may be supported.\n> + Specify an exposure mode for the AE algorithm to use.\n> +\n> + The exposure modes specify how the desired total exposure is divided\n> + between the shutter time and the sensor's analogue gain. They are\n> + platform specific, and not all exposure modes may be supported.\n> enum:\n> - name: ExposureNormal\n> value: 0\n> @@ -111,8 +121,10 @@ controls:\n> - ExposureValue:\n> type: float\n> description: |\n> - Specify an Exposure Value (EV) parameter. The EV parameter will only be\n> - applied if the AE algorithm is currently enabled.\n> + Specify an Exposure Value (EV) parameter.\n> +\n> + The EV parameter will only be applied if the AE algorithm is currently\n> + enabled.\n> \n> By convention EV adjusts the exposure as log2. For example\n> EV = [-2, -1, 0.5, 0, 0.5, 1, 2] results in an exposure adjustment\n> @@ -124,7 +136,9 @@ controls:\n> type: int32_t\n> description: |\n> Exposure time (shutter speed) for the frame applied in the sensor\n> - device. This value is specified in micro-seconds.\n> + device.\n> +\n> + This value is specified in micro-seconds.\n> \n> Setting this value means that it is now fixed and the AE algorithm may\n> not change it. Setting it back to zero returns it to the control of the\n> @@ -142,6 +156,7 @@ controls:\n> type: float\n> description: |\n> Analogue gain value applied in the sensor device.\n> +\n> The value of the control specifies the gain multiplier applied to all\n> colour channels. This value cannot be lower than 1.0.\n> \n> @@ -160,9 +175,11 @@ controls:\n> - AeFlickerMode:\n> type: int32_t\n> description: |\n> - Set the flicker mode, which determines whether, and how, the AGC/AEC\n> - algorithm attempts to hide flicker effects caused by the duty cycle of\n> - artificial lighting.\n> + Set the flicker avoidance mode for AGC/AEC.\n> +\n> + The flicker mode determines whether, and how, the AGC/AEC algorithm\n> + attempts to hide flicker effects caused by the duty cycle of artificial\n> + lighting.\n> \n> Although implementation dependent, many algorithms for \"flicker\n> avoidance\" work by restricting this exposure time to integer multiples\n> @@ -176,16 +193,21 @@ controls:\n> enum:\n> - name: FlickerOff\n> value: 0\n> - description: No flicker avoidance is performed.\n> + description: |\n> + No flicker avoidance is performed.\n\nInteresting, so 'all' descriptions are now block comments even if\nthey're a single line. I think that's probably better to be consistent!.\n\n\nNo objectsions, this looks good to me.\n\n\nReviewed-by: Kieran Bingham \n\n> - name: FlickerManual\n> value: 1\n> - description: Manual flicker avoidance.\n> + description: |\n> + Manual flicker avoidance.\n> +\n> Suppress flicker effects caused by lighting running with a period\n> specified by the AeFlickerPeriod control.\n> \\sa AeFlickerPeriod\n> - name: FlickerAuto\n> value: 2\n> - description: Automatic flicker period detection and avoidance.\n> + description: |\n> + Automatic flicker period detection and avoidance.\n> +\n> The system will automatically determine the most likely value of\n> flicker period, and avoid flicker of this frequency. Once flicker\n> is being corrected, it is implementation dependent whether the\n> @@ -194,7 +216,9 @@ controls:\n> \n> - AeFlickerPeriod:\n> type: int32_t\n> - description: Manual flicker period in microseconds.\n> + description: |\n> + Manual flicker period in microseconds.\n> +\n> This value sets the current flicker period to avoid. It is used when\n> AeFlickerMode is set to FlickerManual.\n> \n> @@ -212,7 +236,9 @@ controls:\n> \n> - AeFlickerDetected:\n> type: int32_t\n> - description: Flicker period detected in microseconds.\n> + description: |\n> + Flicker period detected in microseconds.\n> +\n> The value reported here indicates the currently detected flicker\n> period, or zero if no flicker at all is detected.\n> \n> @@ -233,21 +259,25 @@ controls:\n> - Brightness:\n> type: float\n> description: |\n> - Specify a fixed brightness parameter. Positive values (up to 1.0)\n> - produce brighter images; negative values (up to -1.0) produce darker\n> - images and 0.0 leaves pixels unchanged.\n> + Specify a fixed brightness parameter.\n> +\n> + Positive values (up to 1.0) produce brighter images; negative values\n> + (up to -1.0) produce darker images and 0.0 leaves pixels unchanged.\n> \n> - Contrast:\n> type: float\n> description: |\n> - Specify a fixed contrast parameter. Normal contrast is given by the\n> - value 1.0; larger values produce images with more contrast.\n> + Specify a fixed contrast parameter.\n> +\n> + Normal contrast is given by the value 1.0; larger values produce images\n> + with more contrast.\n> \n> - Lux:\n> type: float\n> description: |\n> - Report an estimate of the current illuminance level in lux. The Lux\n> - control can only be returned in metadata.\n> + Report an estimate of the current illuminance level in lux.\n> +\n> + The Lux control can only be returned in metadata.\n> \n> - AwbEnable:\n> type: bool\n> @@ -262,8 +292,10 @@ controls:\n> - AwbMode:\n> type: int32_t\n> description: |\n> - Specify the range of illuminants to use for the AWB algorithm. The modes\n> - supported are platform specific, and not all modes may be supported.\n> + Specify the range of illuminants to use for the AWB algorithm.\n> +\n> + The modes supported are platform specific, and not all modes may be\n> + supported.\n> enum:\n> - name: AwbAuto\n> value: 0\n> @@ -305,37 +337,43 @@ controls:\n> type: float\n> description: |\n> Pair of gain values for the Red and Blue colour channels, in that\n> - order. ColourGains can only be applied in a Request when the AWB is\n> - disabled.\n> + order.\n> +\n> + ColourGains can only be applied in a Request when the AWB is disabled.\n> \n> \\sa AwbEnable\n> size: [2]\n> \n> - ColourTemperature:\n> type: int32_t\n> - description: Report the current estimate of the colour temperature, in\n> - kelvin, for this frame. The ColourTemperature control can only be\n> - returned in metadata.\n> + description: |\n> + Report the estimate of the colour temperature for the frame, in kelvin.\n> +\n> + The ColourTemperature control can only be returned in metadata.\n> \n> - Saturation:\n> type: float\n> description: |\n> - Specify a fixed saturation parameter. Normal saturation is given by\n> - the value 1.0; larger values produce more saturated colours; 0.0\n> - produces a greyscale image.\n> + Specify a fixed saturation parameter.\n> +\n> + Normal saturation is given by the value 1.0; larger values produce more\n> + saturated colours; 0.0 produces a greyscale image.\n> \n> - SensorBlackLevels:\n> type: int32_t\n> description: |\n> - Reports the sensor black levels used for processing a frame, in the\n> - order R, Gr, Gb, B. These values are returned as numbers out of a 16-bit\n> - pixel range (as if pixels ranged from 0 to 65535). The SensorBlackLevels\n> - control can only be returned in metadata.\n> + Reports the sensor black levels used for processing a frame.\n> +\n> + The values are in the order R, Gr, Gb, B. They are returned as numbers\n> + out of a 16-bit pixel range (as if pixels ranged from 0 to 65535). The\n> + SensorBlackLevels control can only be returned in metadata.\n> size: [4]\n> \n> - Sharpness:\n> type: float\n> description: |\n> + Intensity of the sharpening applied to the image.\n> +\n> A value of 0.0 means no sharpening. The minimum value means\n> minimal sharpening, and shall be 0.0 unless the camera can't\n> disable sharpening completely. The default value shall give a\n> @@ -349,6 +387,7 @@ controls:\n> type: int32_t\n> description: |\n> Reports a Figure of Merit (FoM) to indicate how in-focus the frame is.\n> +\n> A larger FocusFoM value indicates a more in-focus frame. This singular\n> value may be based on a combination of statistics gathered from\n> multiple focus regions within an image. The number of focus regions and\n> @@ -359,11 +398,13 @@ controls:\n> - ColourCorrectionMatrix:\n> type: float\n> description: |\n> - The 3x3 matrix that converts camera RGB to sRGB within the\n> - imaging pipeline. This should describe the matrix that is used\n> - after pixels have been white-balanced, but before any gamma\n> - transformation. The 3x3 matrix is stored in conventional reading\n> - order in an array of 9 floating point values.\n> + The 3x3 matrix that converts camera RGB to sRGB within the imaging\n> + pipeline.\n> +\n> + This should describe the matrix that is used after pixels have been\n> + white-balanced, but before any gamma transformation. The 3x3 matrix is\n> + stored in conventional reading order in an array of 9 floating point\n> + values.\n> \n> size: [3,3]\n> \n> @@ -371,10 +412,12 @@ controls:\n> type: Rectangle\n> description: |\n> Sets the image portion that will be scaled to form the whole of\n> - the final output image. The (x,y) location of this rectangle is\n> - relative to the PixelArrayActiveAreas that is being used. The units\n> - remain native sensor pixels, even if the sensor is being used in\n> - a binning or skipping mode.\n> + the final output image.\n> +\n> + The (x,y) location of this rectangle is relative to the\n> + PixelArrayActiveAreas that is being used. The units remain native\n> + sensor pixels, even if the sensor is being used in a binning or\n> + skipping mode.\n> \n> This control is only present when the pipeline supports scaling. Its\n> maximum valid value is given by the properties::ScalerCropMaximum\n> @@ -401,8 +444,9 @@ controls:\n> type: int64_t\n> description: |\n> The instantaneous frame duration from start of frame exposure to start\n> - of next exposure, expressed in microseconds. This control is meant to\n> - be returned in metadata.\n> + of next exposure, expressed in microseconds.\n> +\n> + This control is meant to be returned in metadata.\n> \n> - FrameDurationLimits:\n> type: int64_t\n> @@ -444,9 +488,11 @@ controls:\n> - SensorTemperature:\n> type: float\n> description: |\n> - Temperature measure from the camera sensor in Celsius. This is typically\n> - obtained by a thermal sensor present on-die or in the camera module. The\n> - range of reported temperatures is device dependent.\n> + Temperature measure from the camera sensor in Celsius.\n> +\n> + This value is typically obtained by a thermal sensor present on-die or\n> + in the camera module. The range of reported temperatures is device\n> + dependent.\n> \n> The SensorTemperature control will only be returned in metadata if a\n> thermal sensor is present.\n> @@ -468,7 +514,7 @@ controls:\n> - AfMode:\n> type: int32_t\n> description: |\n> - Control to set the mode of the AF (autofocus) algorithm.\n> + The mode of the AF (autofocus) algorithm.\n> \n> An implementation may choose not to implement all the modes.\n> \n> @@ -476,12 +522,12 @@ controls:\n> - name: AfModeManual\n> value: 0\n> description: |\n> - The AF algorithm is in manual mode. In this mode it will never\n> - perform any action nor move the lens of its own accord, but an\n> - application can specify the desired lens position using the\n> - LensPosition control.\n> + The AF algorithm is in manual mode.\n> \n> - In this mode the AfState will always report AfStateIdle.\n> + In this mode it will never perform any action nor move the lens of\n> + its own accord, but an application can specify the desired lens\n> + position using the LensPosition control. The AfState will always\n> + report AfStateIdle.\n> \n> If the camera is started in AfModeManual, it will move the focus\n> lens to the position specified by the LensPosition control.\n> @@ -492,31 +538,34 @@ controls:\n> - name: AfModeAuto\n> value: 1\n> description: |\n> - The AF algorithm is in auto mode. This means that the algorithm\n> - will never move the lens or change state unless the AfTrigger\n> - control is used. The AfTrigger control can be used to initiate a\n> - focus scan, the results of which will be reported by AfState.\n> + The AF algorithm is in auto mode.\n> \n> - If the autofocus algorithm is moved from AfModeAuto to another\n> - mode while a scan is in progress, the scan is cancelled\n> - immediately, without waiting for the scan to finish.\n> + In this mode the algorithm will never move the lens or change state\n> + unless the AfTrigger control is used. The AfTrigger control can be\n> + used to initiate a focus scan, the results of which will be\n> + reported by AfState.\n> \n> - When first entering this mode the AfState will report\n> - AfStateIdle. When a trigger control is sent, AfState will\n> - report AfStateScanning for a period before spontaneously\n> - changing to AfStateFocused or AfStateFailed, depending on\n> - the outcome of the scan. It will remain in this state until\n> - another scan is initiated by the AfTrigger control. If a scan is\n> - cancelled (without changing to another mode), AfState will return\n> - to AfStateIdle.\n> + If the autofocus algorithm is moved from AfModeAuto to another mode\n> + while a scan is in progress, the scan is cancelled immediately,\n> + without waiting for the scan to finish.\n> +\n> + When first entering this mode the AfState will report AfStateIdle.\n> + When a trigger control is sent, AfState will report AfStateScanning\n> + for a period before spontaneously changing to AfStateFocused or\n> + AfStateFailed, depending on the outcome of the scan. It will remain\n> + in this state until another scan is initiated by the AfTrigger\n> + control. If a scan is cancelled (without changing to another mode),\n> + AfState will return to AfStateIdle.\n> - name: AfModeContinuous\n> value: 2\n> description: |\n> - The AF algorithm is in continuous mode. This means that the lens can\n> - re-start a scan spontaneously at any moment, without any user\n> - intervention. The AfState still reports whether the algorithm is\n> - currently scanning or not, though the application has no ability to\n> - initiate or cancel scans, nor to move the lens for itself.\n> + The AF algorithm is in continuous mode.\n> +\n> + In this mode the lens can re-start a scan spontaneously at any\n> + moment, without any user intervention. The AfState still reports\n> + whether the algorithm is currently scanning or not, though the\n> + application has no ability to initiate or cancel scans, nor to move\n> + the lens for itself.\n> \n> However, applications can pause the AF algorithm from continuously\n> scanning by using the AfPause control. This allows video or still\n> @@ -529,34 +578,40 @@ controls:\n> - AfRange:\n> type: int32_t\n> description: |\n> - Control to set the range of focus distances that is scanned. An\n> - implementation may choose not to implement all the options here.\n> + The range of focus distances that is scanned.\n> +\n> + An implementation may choose not to implement all the options here.\n> enum:\n> - name: AfRangeNormal\n> value: 0\n> description: |\n> - A wide range of focus distances is scanned, all the way from\n> - infinity down to close distances, though depending on the\n> - implementation, possibly not including the very closest macro\n> - positions.\n> + A wide range of focus distances is scanned.\n> +\n> + Scanned distances cover all the way from infinity down to close\n> + distances, though depending on the implementation, possibly not\n> + including the very closest macro positions.\n> - name: AfRangeMacro\n> value: 1\n> - description: Only close distances are scanned.\n> + description: |\n> + Only close distances are scanned.\n> - name: AfRangeFull\n> value: 2\n> description: |\n> - The full range of focus distances is scanned just as with\n> - AfRangeNormal but this time including the very closest macro\n> - positions.\n> + The full range of focus distances is scanned.\n> +\n> + This range is similar to AfRangeNormal but includes the very\n> + closest macro positions.\n> \n> - AfSpeed:\n> type: int32_t\n> description: |\n> - Control that determines whether the AF algorithm is to move the lens\n> - as quickly as possible or more steadily. For example, during video\n> - recording it may be desirable not to move the lens too abruptly, but\n> - when in a preview mode (waiting for a still capture) it may be\n> - helpful to move the lens as quickly as is reasonably possible.\n> + Determine whether the AF is to move the lens as quickly as possible or\n> + more steadily.\n> +\n> + For example, during video recording it may be desirable not to move the\n> + lens too abruptly, but when in a preview mode (waiting for a still\n> + capture) it may be helpful to move the lens as quickly as is reasonably\n> + possible.\n> enum:\n> - name: AfSpeedNormal\n> value: 0\n> @@ -568,25 +623,27 @@ controls:\n> - AfMetering:\n> type: int32_t\n> description: |\n> - Instruct the AF algorithm how it should decide which parts of the image\n> - should be used to measure focus.\n> + The parts of the image used by the AF algorithm to measure focus.\n> enum:\n> - name: AfMeteringAuto\n> value: 0\n> - description: The AF algorithm should decide for itself where it will\n> - measure focus.\n> + description: |\n> + Let the AF algorithm decide for itself where it will measure focus.\n> - name: AfMeteringWindows\n> value: 1\n> - description: The AF algorithm should use the rectangles defined by\n> - the AfWindows control to measure focus. If no windows are specified\n> - the behaviour is platform dependent.\n> + description: |\n> + Use the rectangles defined by the AfWindows control to measure focus.\n> +\n> + If no windows are specified the behaviour is platform dependent.\n> \n> - AfWindows:\n> type: Rectangle\n> description: |\n> - Sets the focus windows used by the AF algorithm when AfMetering is set\n> - to AfMeteringWindows. The units used are pixels within the rectangle\n> - returned by the ScalerCropMaximum property.\n> + The focus windows used by the AF algorithm when AfMetering is set to\n> + AfMeteringWindows.\n> +\n> + The units used are pixels within the rectangle returned by the\n> + ScalerCropMaximum property.\n> \n> In order to be activated, a rectangle must be programmed with non-zero\n> width and height. Internally, these rectangles are intersected with the\n> @@ -611,23 +668,33 @@ controls:\n> - AfTrigger:\n> type: int32_t\n> description: |\n> - This control starts an autofocus scan when AfMode is set to AfModeAuto,\n> - and can also be used to terminate a scan early.\n> + Start an autofocus scan.\n> \n> - It is ignored if AfMode is set to AfModeManual or AfModeContinuous.\n> + This control starts an autofocus scan when AfMode is set to AfModeAuto,\n> + and is ignored if AfMode is set to AfModeManual or AfModeContinuous. It\n> + can also be used to terminate a scan early.\n> \n> enum:\n> - name: AfTriggerStart\n> value: 0\n> - description: Start an AF scan. Ignored if a scan is in progress.\n> + description: |\n> + Start an AF scan.\n> +\n> + Setting the control to AfTriggerStart is ignored if a scan is in\n> + progress.\n> - name: AfTriggerCancel\n> value: 1\n> - description: Cancel an AF scan. This does not cause the lens to move\n> - anywhere else. Ignored if no scan is in progress.\n> + description: |\n> + Cancel an AF scan.\n> +\n> + This does not cause the lens to move anywhere else. Ignored if no\n> + scan is in progress.\n> \n> - AfPause:\n> type: int32_t\n> description: |\n> + Pause lens movements when in continuous autofocus mode.\n> +\n> This control has no effect except when in continuous autofocus mode\n> (AfModeContinuous). It can be used to pause any lens movements while\n> (for example) images are captured. The algorithm remains inactive\n> @@ -637,17 +704,21 @@ controls:\n> - name: AfPauseImmediate\n> value: 0\n> description: |\n> - Pause the continuous autofocus algorithm immediately, whether or not\n> - any kind of scan is underway. AfPauseState will subsequently report\n> + Pause the continuous autofocus algorithm immediately.\n> +\n> + The autofocus algorithm is paused whether or not any kind of scan\n> + is underway. AfPauseState will subsequently report\n> AfPauseStatePaused. AfState may report any of AfStateScanning,\n> AfStateFocused or AfStateFailed, depending on the algorithm's state\n> when it received this control.\n> - name: AfPauseDeferred\n> value: 1\n> description: |\n> - This is similar to AfPauseImmediate, and if the AfState is currently\n> - reporting AfStateFocused or AfStateFailed it will remain in that\n> - state and AfPauseState will report AfPauseStatePaused.\n> + Pause the continuous autofocus algorithm at the end of the scan.\n> +\n> + This is similar to AfPauseImmediate, and if the AfState is\n> + currently reporting AfStateFocused or AfStateFailed it will remain\n> + in that state and AfPauseState will report AfPauseStatePaused.\n> \n> However, if the algorithm is scanning (AfStateScanning),\n> AfPauseState will report AfPauseStatePausing until the scan is\n> @@ -658,15 +729,18 @@ controls:\n> - name: AfPauseResume\n> value: 2\n> description: |\n> - Resume continuous autofocus operation. The algorithm starts again\n> - from exactly where it left off, and AfPauseState will report\n> - AfPauseStateRunning.\n> + Resume continuous autofocus operation.\n> +\n> + The algorithm starts again from exactly where it left off, and\n> + AfPauseState will report AfPauseStateRunning.\n> \n> - LensPosition:\n> type: float\n> description: |\n> - Acts as a control to instruct the lens to move to a particular position\n> - and also reports back the position of the lens for each frame.\n> + Set and report the focus lens position.\n> +\n> + This control instructs the lens to move to a particular position and\n> + also reports back the position of the lens for each frame.\n> \n> The LensPosition control is ignored unless the AfMode is set to\n> AfModeManual, though the value is reported back unconditionally in all\n> @@ -680,16 +754,16 @@ controls:\n> \n> For example:\n> \n> - 0 moves the lens to infinity.\n> - 0.5 moves the lens to focus on objects 2m away.\n> - 2 moves the lens to focus on objects 50cm away.\n> - And larger values will focus the lens closer.\n> + - 0 moves the lens to infinity.\n> + - 0.5 moves the lens to focus on objects 2m away.\n> + - 2 moves the lens to focus on objects 50cm away.\n> + - And larger values will focus the lens closer.\n> \n> - The default value of the control should indicate a good general position\n> - for the lens, often corresponding to the hyperfocal distance (the\n> - closest position for which objects at infinity are still acceptably\n> - sharp). The minimum will often be zero (meaning infinity), and the\n> - maximum value defines the closest focus position.\n> + The default value of the control should indicate a good general\n> + position for the lens, often corresponding to the hyperfocal distance\n> + (the closest position for which objects at infinity are still\n> + acceptably sharp). The minimum will often be zero (meaning infinity),\n> + and the maximum value defines the closest focus position.\n> \n> \\todo Define a property to report the Hyperfocal distance of calibrated\n> lenses.\n> @@ -697,22 +771,25 @@ controls:\n> - AfState:\n> type: int32_t\n> description: |\n> - Reports the current state of the AF algorithm in conjunction with the\n> - reported AfMode value and (in continuous AF mode) the AfPauseState\n> - value. The possible state changes are described below, though we note\n> - the following state transitions that occur when the AfMode is changed.\n> + The current state of the AF algorithm.\n> +\n> + This control reports the current state of the AF algorithm in\n> + conjunction with the reported AfMode value and (in continuous AF mode)\n> + the AfPauseState value. The possible state changes are described below,\n> + though we note the following state transitions that occur when the\n> + AfMode is changed.\n> \n> If the AfMode is set to AfModeManual, then the AfState will always\n> - report AfStateIdle (even if the lens is subsequently moved). Changing to\n> - the AfModeManual state does not initiate any lens movement.\n> + report AfStateIdle (even if the lens is subsequently moved). Changing\n> + to the AfModeManual state does not initiate any lens movement.\n> \n> If the AfMode is set to AfModeAuto then the AfState will report\n> - AfStateIdle. However, if AfModeAuto and AfTriggerStart are sent together\n> - then AfState will omit AfStateIdle and move straight to AfStateScanning\n> - (and start a scan).\n> + AfStateIdle. However, if AfModeAuto and AfTriggerStart are sent\n> + together then AfState will omit AfStateIdle and move straight to\n> + AfStateScanning (and start a scan).\n> \n> - If the AfMode is set to AfModeContinuous then the AfState will initially\n> - report AfStateScanning.\n> + If the AfMode is set to AfModeContinuous then the AfState will\n> + initially report AfStateScanning.\n> \n> enum:\n> - name: AfStateIdle\n> @@ -725,11 +802,12 @@ controls:\n> value: 1\n> description: |\n> The AF algorithm is in auto mode (AfModeAuto), and a scan has been\n> - started using the AfTrigger control. The scan can be cancelled by\n> - sending AfTriggerCancel at which point the algorithm will either\n> - move back to AfStateIdle or, if the scan actually completes before\n> - the cancel request is processed, to one of AfStateFocused or\n> - AfStateFailed.\n> + started using the AfTrigger control.\n> +\n> + The scan can be cancelled by sending AfTriggerCancel at which point\n> + the algorithm will either move back to AfStateIdle or, if the scan\n> + actually completes before the cancel request is processed, to one\n> + of AfStateFocused or AfStateFailed.\n> \n> Alternatively the AF algorithm could be in continuous mode\n> (AfModeContinuous) at which point it may enter this state\n> @@ -750,9 +828,12 @@ controls:\n> - AfPauseState:\n> type: int32_t\n> description: |\n> - Only applicable in continuous (AfModeContinuous) mode, this reports\n> - whether the algorithm is currently running, paused or pausing (that is,\n> - will pause as soon as any in-progress scan completes).\n> + Report whether the autofocus is currently running, paused or pausing.\n> +\n> + This control is only applicable in continuous (AfModeContinuous) mode,\n> + and reports whether the algorithm is currently running, paused or\n> + pausing (that is, will pause as soon as any in-progress scan\n> + completes).\n> \n> Any change to AfMode will cause AfPauseStateRunning to be reported.\n> \n> @@ -766,22 +847,27 @@ controls:\n> value: 1\n> description: |\n> Continuous AF has been sent an AfPauseDeferred control, and will\n> - pause as soon as any in-progress scan completes (and then report\n> - AfPauseStatePaused). No new scans will be start spontaneously until\n> + pause as soon as any in-progress scan completes.\n> +\n> + When the scan completes, the AfPauseState control will report\n> + AfPauseStatePaused. No new scans will be start spontaneously until\n> the AfPauseResume control is sent.\n> - name: AfPauseStatePaused\n> value: 2\n> description: |\n> - Continuous AF is paused. No further state changes or lens movements\n> - will occur until the AfPauseResume control is sent.\n> + Continuous AF is paused.\n> +\n> + No further state changes or lens movements will occur until the\n> + AfPauseResume control is sent.\n> \n> - HdrMode:\n> type: int32_t\n> description: |\n> - Control to set the mode to be used for High Dynamic Range (HDR)\n> - imaging. HDR techniques typically include multiple exposure, image\n> - fusion and tone mapping techniques to improve the dynamic range of the\n> - resulting images.\n> + Set the mode to be used for High Dynamic Range (HDR) imaging.\n> +\n> + HDR techniques typically include multiple exposure, image fusion and\n> + tone mapping techniques to improve the dynamic range of the resulting\n> + images.\n> \n> When using an HDR mode, images are captured with different sets of AGC\n> settings called HDR channels. Channels indicate in particular the type\n> @@ -795,16 +881,18 @@ controls:\n> - name: HdrModeOff\n> value: 0\n> description: |\n> - HDR is disabled. Metadata for this frame will not include the\n> - HdrChannel control.\n> + HDR is disabled.\n> +\n> + Metadata for this frame will not include the HdrChannel control.\n> - name: HdrModeMultiExposureUnmerged\n> value: 1\n> description: |\n> Multiple exposures will be generated in an alternating fashion.\n> - However, they will not be merged together and will be returned to\n> - the application as they are. Each image will be tagged with the\n> - correct HDR channel, indicating what kind of exposure it is. The\n> - tag should be the same as in the HdrModeMultiExposure case.\n> +\n> + The multiple exposures will not be merged together and will be\n> + returned to the application as they are. Each image will be tagged\n> + with the correct HDR channel, indicating what kind of exposure it\n> + is. The tag should be the same as in the HdrModeMultiExposure case.\n> \n> The expectation is that an application using this mode would merge\n> the frames to create HDR images for itself if it requires them.\n> @@ -812,8 +900,10 @@ controls:\n> value: 2\n> description: |\n> Multiple exposures will be generated and merged to create HDR\n> - images. Each image will be tagged with the HDR channel (long, medium\n> - or short) that arrived and which caused this image to be output.\n> + images.\n> +\n> + Each image will be tagged with the HDR channel (long, medium or\n> + short) that arrived and which caused this image to be output.\n> \n> Systems that use two channels for HDR will return images tagged\n> alternately as the short and long channel. Systems that use three\n> @@ -823,24 +913,29 @@ controls:\n> value: 3\n> description: |\n> Multiple frames all at a single exposure will be used to create HDR\n> - images. These images should be reported as all corresponding to the\n> - HDR short channel.\n> + images.\n> +\n> + These images should be reported as all corresponding to the HDR\n> + short channel.\n> - name: HdrModeNight\n> value: 4\n> description: |\n> - Multiple frames will be combined to produce \"night mode\" images. It\n> - is up to the implementation exactly which HDR channels it uses, and\n> - the images will all be tagged accordingly with the correct HDR\n> + Multiple frames will be combined to produce \"night mode\" images.\n> +\n> + It is up to the implementation exactly which HDR channels it uses,\n> + and the images will all be tagged accordingly with the correct HDR\n> channel information.\n> \n> - HdrChannel:\n> type: int32_t\n> description: |\n> + The HDR channel used to capture the frame.\n> +\n> This value is reported back to the application so that it can discover\n> - whether this capture corresponds to the short or long exposure image (or\n> - any other image used by the HDR procedure). An application can monitor\n> - the HDR channel to discover when the differently exposed images have\n> - arrived.\n> + whether this capture corresponds to the short or long exposure image\n> + (or any other image used by the HDR procedure). An application can\n> + monitor the HDR channel to discover when the differently exposed images\n> + have arrived.\n> \n> This metadata is only available when an HDR mode has been enabled.\n> \n> @@ -868,8 +963,9 @@ controls:\n> - Gamma:\n> type: float\n> description: |\n> - Specify a fixed gamma value. Default must be 2.2 which closely mimics\n> - sRGB gamma. Note that this is camera gamma, so it is applied as\n> - 1.0/gamma.\n> + Specify a fixed gamma value.\n> +\n> + The default gamma value must be 2.2 which closely mimics sRGB gamma.\n> + Note that this is camera gamma, so it is applied as 1.0/gamma.\n> \n> ...\n> diff --git a/src/libcamera/control_ids_rpi.yaml b/src/libcamera/control_ids_rpi.yaml\n> index cb097f887e16..42c4bf5d408f 100644\n> --- a/src/libcamera/control_ids_rpi.yaml\n> +++ b/src/libcamera/control_ids_rpi.yaml\n> @@ -10,9 +10,11 @@ controls:\n> - StatsOutputEnable:\n> type: bool\n> description: |\n> - Toggles the Raspberry Pi IPA to output a binary dump of the hardware\n> - generated statistics through the Request metadata in the Bcm2835StatsOutput\n> - control.\n> + Toggles the Raspberry Pi IPA to output the hardware generated statistics.\n> +\n> + When this control is set to true, the IPA outputs a binary dump of the\n> + hardware generated statistics through the Request metadata in the\n> + Bcm2835StatsOutput control.\n> \n> \\sa Bcm2835StatsOutput\n> \n> @@ -20,9 +22,11 @@ controls:\n> type: uint8_t\n> size: [n]\n> description: |\n> - Span of the BCM2835 ISP generated statistics for the current frame. This\n> - is sent in the Request metadata if the StatsOutputEnable is set to true.\n> - The statistics struct definition can be found in include/linux/bcm2835-isp.h.\n> + Span of the BCM2835 ISP generated statistics for the current frame.\n> +\n> + This is sent in the Request metadata if the StatsOutputEnable is set to\n> + true. The statistics struct definition can be found in\n> + include/linux/bcm2835-isp.h.\n> \n> \\sa StatsOutputEnable\n> \n> \n> base-commit: 62760bd2605a83e663b9003244ff42f8946f8955\n> -- \n> Regards,\n> \n> Laurent Pinchart\n>","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 79A15BDB13\n\tfor ;\n\tThu, 15 Aug 2024 21:49:18 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 4337B633B3;\n\tThu, 15 Aug 2024 23:49:17 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 1807761955\n\tfor ;\n\tThu, 15 Aug 2024 23:49:15 +0200 (CEST)","from pendragon.ideasonboard.com\n\t(cpc89244-aztw30-2-0-cust6594.18-1.cable.virginm.net [86.31.185.195])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 3769A827;\n\tThu, 15 Aug 2024 23:48:16 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"gVQbaIh6\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723758496;\n\tbh=GSScTcibP+ejFyb2YE9KtLC/ZRMnZerSb0csg0qZShc=;\n\th=In-Reply-To:References:Subject:From:To:Date:From;\n\tb=gVQbaIh68sUFV9mIHscOFCpYPcHOKAHhCLtefEs1Gb+be9F3PhjOuyu4rhr6FMyhy\n\tzRKQDfykBUEJCVqibWDm+LXYUyUi6mU5uKgjP9p+ZH5LBhPiKCdKscbLTWzNiFXqdW\n\tXm3je8GFnk7wxe5NPtO5w5Ei4GGURabjxtAo7J6s=","Content-Type":"text/plain; charset=\"utf-8\"","MIME-Version":"1.0","Content-Transfer-Encoding":"quoted-printable","In-Reply-To":"<20240810023904.25658-1-laurent.pinchart@ideasonboard.com>","References":"<20240810023904.25658-1-laurent.pinchart@ideasonboard.com>","Subject":"Re: [PATCH] libcamera: controls: Improve formatting of control\n\tdescriptions in YAML","From":"Kieran Bingham ","To":"Laurent Pinchart ,\n\tlibcamera-devel@lists.libcamera.org","Date":"Thu, 15 Aug 2024 22:49:12 +0100","Message-ID":"<172375855226.129190.3864727950074612030@ping.linuxembedded.co.uk>","User-Agent":"alot/0.10","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]