<div dir="ltr">Hi Jacopo<br><br>On Tue, 5 Jul 2022 at 10:17, Jacopo Mondi <<a href="mailto:jacopo@jmondi.org">jacopo@jmondi.org</a>> wrote:<br>><br>> Hi Naush,<br>><br>> On Tue, Jul 05, 2022 at 09:06:39AM +0100, Naushir Patuck wrote:<br>> > Hi Jacopo and Paul,<br>> ><br>> > On Mon, 4 Jul 2022 at 16:30, Jacopo Mondi <<a href="mailto:jacopo@jmondi.org">jacopo@jmondi.org</a>> wrote:<br>> > ><br>> > > Hi Naush,<br>> > >   sorry Paul if I reply in your place, but I just got through this so<br>> > > I might have it slightly fresher<br>> > ><br>> > > On Mon, Jul 04, 2022 at 11:02:47AM +0100, Naushir Patuck via<br>> > libcamera-devel wrote:<br>> > > > Hi Paul,<br>> > > ><br>> > > > Thank you for your work.  It's nice to see these changes to solidify<br>> > the AE<br>> > > > controls.<br>> > > > I do have a few thoughts/comments below.<br>> > ><br>> > > Can I ask you to have a look at the final result with the fixups I<br>> > > sent in reply applied on top of this patch ?<br>> ><br>> ><br>> > Yes will do!<br>> ><br>> ><br>> > ><br>> > > ><br>> > > ><br>> > > > On Wed, 18 May 2022 at 14:47, Paul Elder via libcamera-devel <<br>> > > > <a href="mailto:libcamera-devel@lists.libcamera.org">libcamera-devel@lists.libcamera.org</a>> wrote:<br>> > > ><br>> > > > > We have multiple goals:<br>> > > > > - we need a lock of some sort, to instruct the AEGC to not update<br>> > output<br>> > > > >   results<br>> > > > > - we need manual modes, to override the values computed by the AEGC<br>> > ><br>> > > > > - we need to support seamless transitions from auto -> manual, and do<br>> > so<br>> > > > >   without flickering<br>> > > > > - we need custom minimum values for the manual controls, that is no<br>> > > > >   magic values for enabling/disabling auto<br>> > > > > - all of these need to be done with AE sub-controls (exposure time,<br>> > > > >   analogue gain)<br>> > > > ><br>> > > > > To achieve these goals, we introduce mode controls for the AE<br>> > > > > sub-controls: ExposureTimeMode and AnalogueGainMode. These have an<br>> > auto<br>> > > > > state, and a disabled state. The disabled state has an internal<br>> > one-way<br>> > > > > state change from locked to manual, triggered by the presence of the<br>> > > > > value-controls (ExposureTime and AnalogueGain).<br>> > > > ><br>> > > > > We then remove the AeEnable control, as it is a redundant control in<br>> > the<br>> > > > > face of these two mode controls.<br>> > > > ><br>> > > > > We also remove AeLocked, as it is insufficient for reporting the AE<br>> > > > > state, and we promote AeState to non-draft to fill its role. Notably,<br>> > > > > the locked state is removed, since this information can be obtained<br>> > from<br>> > > > > the aforementioned mode controls.<br>> > > > ><br>> > > > > Bug: <a href="https://bugs.libcamera.org/show_bug.cgi?id=42">https://bugs.libcamera.org/show_bug.cgi?id=42</a><br>> > > > > Bug: <a href="https://bugs.libcamera.org/show_bug.cgi?id=43">https://bugs.libcamera.org/show_bug.cgi?id=43</a><br>> > > > > Bug: <a href="https://bugs.libcamera.org/show_bug.cgi?id=47">https://bugs.libcamera.org/show_bug.cgi?id=47</a><br>> > > > > Signed-off-by: Paul Elder <<a href="mailto:paul.elder@ideasonboard.com">paul.elder@ideasonboard.com</a>><br>> > > > ><br>> > > > > ---<br>> > > > > Changes in v4:<br>> > > > > - remove FlashRequired and Precapture from AeState<br>> > > > > - upgrade documentation of all the controls<br>> > > > ><br>> > > > > Changes in v3:<br>> > > > > - improve wording of the control descriptions<br>> > > > >   - make more succinct and clear<br>> > > > > - add description of how to do a flickerless transition<br>> > > > ><br>> > > > > Changes in v2:<br>> > > > > - No changes, just resubmitting at the head of this series so that<br>> > it's<br>> > > > >   together and so that /people will actually see it/<br>> > > > ><br>> > > > > Initial version:<br>> > > > > Still RFC as I haven't updated the users of the control yet, and I<br>> > want<br>> > > > > to check that these are the controls and docs that we want.<br>> > > > ><br>> > > > > We've decided that the "master AE control" will be implemented by a<br>> > > > > helper... but looking at uvcvideo and the V4L2 controls I'm wondering<br>> > if<br>> > > > > such helper should come earlier than later?<br>> > > > ><br>> > > ><br>> > > > Yes, I agree having the "master AE control" earlier will be beneficial<br>> > for<br>> > > > application developers.<br>> > > ><br>> > ><br>> > > Do you envision this as something that could be part of your<br>> > > applications in example, or in a layer part of libcamera itself ?<br>> ><br>> ><br>> > My preference would be to have a helper in libcamera do this if possible.<br>> > This way, applications don't need to duplicate code to set all AE controls.<br>> > But either way, it's not too big of a deal to put it in the application.<br>> ><br>> > ><br>> > ><br>> > > ><br>> > > > > ---<br>> > > > >  src/libcamera/control_ids.yaml | 262<br>> > +++++++++++++++++++++++++--------<br>> > > > >  1 file changed, 200 insertions(+), 62 deletions(-)<br>> > > > ><br>> > > > > diff --git a/src/libcamera/control_ids.yaml<br>> > > > > b/src/libcamera/control_ids.yaml<br>> > > > > index 9d4638ae..9f5ce5e8 100644<br>> > > > > --- a/src/libcamera/control_ids.yaml<br>> > > > > +++ b/src/libcamera/control_ids.yaml<br>> > > > > @@ -7,23 +7,46 @@<br>> > > > >  # Unless otherwise stated, all controls are bi-directional, i.e.<br>> > they can<br>> > > > > be<br>> > > > >  # set through Request::controls() and returned out through<br>> > > > > Request::metadata().<br>> > > > >  controls:<br>> > > > > -  - AeEnable:<br>> > > > > -      type: bool<br>> > > > > +  - AeState:<br>> > > > > +      type: int32_t<br>> > > > >        description: |<br>> > > > > -        Enable or disable the AE.<br>> > > > > +        Control to report the AE algorithm state associated with the<br>> > > > > capture<br>> > > > > +        result.<br>> > > > ><br>> > > > > -        \sa ExposureTime AnalogueGain<br>> > > > > +        The state is still reported even if ExposureTimeMode or<br>> > > > > +        AnalogueGainMode is set to Disabled.<br>> > > > ><br>> > > > > -  - AeLocked:<br>> > > > > -      type: bool<br>> > > > > -      description: |<br>> > > > > -        Report the lock status of a running AE algorithm.<br>> > > > > +        \sa AnalogueGain<br>> > > > > +        \sa AnalogueGainMode<br>> > > > > +        \sa ExposureTime<br>> > > > > +        \sa ExposureTimeMode<br>> > > > ><br>> > > > > -        If the AE algorithm is locked the value shall be set to<br>> > true, if<br>> > > > > it's<br>> > > > > -        converging it shall be set to false. If the AE algorithm is<br>> > not<br>> > > > > -        running the control shall not be present in the metadata<br>> > control<br>> > > > > list.<br>> > > > > +      enum:<br>> > > > > +        - name: AeStateInactive<br>> > > > > +          value: 0<br>> > > > > +          description: |<br>> > > > > +            The AE algorithm is inactive.<br>> > > > ><br>> > > > > -        \sa AeEnable<br>> > > > > +            This state should be returned if both AnalogueGainMode<br>> > and<br>> > > > > +            ExposureTimeMode are set to disabled (or one, if the<br>> > camera<br>> > > > > only<br>> > > > > +            supports one of the two controls).<br>> > > > > +        - name: AeStateSearching<br>> > > > > +          value: 1<br>> > > > > +          description: |<br>> > > > > +            The AE algorithm has not converged yet.<br>> > > > > +<br>> > > > > +            This state should be returned if at least one of<br>> > > > > AnalogueGainMode<br>> > > > > +            or ExposureTimeMode is set to auto, and the AE algorithm<br>> > > > > hasn't<br>> > > > > +            converged yet. If the AE algorithm converges, the state<br>> > shall<br>> > > > > go to<br>> > > > > +            AeStateConverged.<br>> > > > > +        - name: AeStateConverged<br>> > > > > +          value: 2<br>> > > > > +          description: |<br>> > > > > +            The AE algorithm has converged.<br>> > > > > +<br>> > > > > +            This state should be returned if at least one of<br>> > > > > AnalogueGainMode<br>> > > > > +            or ExposureTimeMode is set to auto, and the AE algorithm<br>> > has<br>> > > > > +            converged.<br>> > > > ><br>> > > > >    # AeMeteringMode needs further attention:<br>> > > > >    # - Auto-generate max enum value.<br>> > > > > @@ -93,6 +116,13 @@ controls:<br>> > > > >          how the desired total exposure is divided between the<br>> > shutter time<br>> > > > >          and the sensor's analogue gain. The exposure modes are<br>> > platform<br>> > > > >          specific, and not all exposure modes may be supported.<br>> > > > > +<br>> > > > > +        When one of AnalogueGainMode or ExposureTimeMode is set to<br>> > > > > Disabled,<br>> > > > > +        the fixed values will override any choices made by<br>> > AeExposureMode.<br>> > > > > +<br>> > > > > +        \sa AnalogueGainMode<br>> > > > > +        \sa ExposureTimeMode<br>> > > > > +<br>> > > > >        enum:<br>> > > > >          - name: ExposureNormal<br>> > > > >            value: 0<br>> > > > > @@ -111,13 +141,15 @@ controls:<br>> > > > >        type: float<br>> > > > >        description: |<br>> > > > >          Specify an Exposure Value (EV) parameter. The EV parameter<br>> > will<br>> > > > > only be<br>> > > > > -        applied if the AE algorithm is currently enabled.<br>> > > > > +        applied if the AE algorithm is currently enabled, that is, at<br>> > > > > least one<br>> > > > > +        of AnalogueGainMode and ExposureTimeMode are auto.<br>> > > > ><br>> > > > >          By convention EV adjusts the exposure as log2. For example<br>> > > > >          EV = [-2, -1, 0.5, 0, 0.5, 1, 2] results in an exposure<br>> > adjustment<br>> > > > >          of [1/4x, 1/2x, 1/sqrt(2)x, 1x, sqrt(2)x, 2x, 4x].<br>> > > > ><br>> > > > > -        \sa AeEnable<br>> > > > > +        \sa AnalogueGainMode<br>> > > > > +        \sa ExposureTimeMode<br>> > > > ><br>> > > > >    - ExposureTime:<br>> > > > >        type: int32_t<br>> > > > > @@ -125,17 +157,85 @@ controls:<br>> > > > >          Exposure time (shutter speed) for the frame applied in the<br>> > sensor<br>> > > > >          device. This value is specified in micro-seconds.<br>> > > > ><br>> > > > > -        Setting this value means that it is now fixed and the AE<br>> > > > > algorithm may<br>> > > > > -        not change it. Setting it back to zero returns it to the<br>> > control<br>> > > > > of the<br>> > > > > -        AE algorithm.<br>> > > > > +        This control will only take effect if ExposureTimeMode is<br>> > > > > Disabled. If<br>> > > > > +        this control is set when ExposureTimeMode is Auto, the value<br>> > will<br>> > > > > be<br>> > > > > +        ignored and will not be retained.<br>> > > > > +<br>> > > > > +        When reported in metadata, this control indicates what<br>> > exposure<br>> > > > > time<br>> > > > > +        was used for the current request, regardless of<br>> > ExposureTimeMode.<br>> > > > > +        ExposureTimeMode will indicate the source of the exposure<br>> > time<br>> > > > > value,<br>> > > > > +        whether it came from the AE algorithm or not.<br>> > > > > +<br>> > > > > +        \sa AnalogueGain<br>> > > > > +        \sa ExposureTimeMode<br>> > > > > +<br>> > > > > +  - ExposureTimeMode:<br>> > > > > +      type: int32_t<br>> > > > > +      description: |<br>> > > > > +        Controls the source of the exposure time that is applied to<br>> > the<br>> > > > > image<br>> > > > > +        sensor. When set to Auto, the AE algorithm computes the<br>> > exposure<br>> > > > > time<br>> > > > > +        and configures the image sensor accordingly. When set to<br>> > Disabled,<br>> > > > > +        exposure time specified in ExposureTime is applied to the<br>> > image<br>> > > > > sensor.<br>> > > > > +        If ExposureTime is not set, then the value last computed by<br>> > the AE<br>> > > > > +        algorithm when the mode was Auto will be used.<br>> > > > ><br>> > > ><br>> > > > Can we un-set ExposureTime?  If it ever gets set once at any point in<br>> > the<br>> > > > application,<br>> > > > then ExposureTimeModeDisabled will always use the last set value for<br>> > > > ExposureTime.<br>> > > ><br>> > ><br>> > > If I interpret your question right, are you wondering if the<br>> > > ExposureTime value is retained if an application sends it when the<br>> > > AEGC is actually in auto mode (and so the ExposureTime from application<br>> > > is not applied) ?<br>> > ><br>> > > We discussed this, and I think Paul tried to clarify it in the<br>> > > ExposureTime documentation by saying:<br>> > ><br>> > >   - name: ExposureTimeModeDisabled<br>> > >        If ExposureTime is set while this mode is active, it<br>> > >        will be ignored, and it will also not be retained.<br>> > ><br>> > > which means that by design, the ExposureTime is just ignored if sent<br>> > > when the AEGC is in auto mode.<br>> > ><br>> > > Do you think that's not the expected behaviour ?<br>> ><br>> ><br>> > Not exactly... I was considering the following sequence:<br>> ><br>> > 1) ExposureTimeMode is Auto - AE adjusts exposure time as needed.<br>> > 2) ExposureTimeMode set to Disabled - AE stops adjusting exposure time.<br>> > No ExposureTime value set yet, so keep the last AE exposure time.<br>> > 3) Set ExposureTime to some desired value.<br>> > 4) ExposureTimeMode set to Auto - AE adjusts exposure time as needed again.<br>> > 5) ExposureTimeMode  set to  Disabled - AE stops adjusting exposure time.<br>> ><br>> > In step 5, does the IPA switch back to the ExposureTime set in step 3, or<br>> > does<br>> > setting ExposureTimeMode to Auto invalidate the existing ExposureTime<br>> > value? If<br>><br>> I would expect step 3 to re-cycle the state machine and invalidate the<br>> manually programmed exposure time<br>><br>> Is this what application developers would expect in your opinion ?<br><br>That seems reasonable to me, but perhaps worth adding some text to the<br>documention clarifying this.<br><br>><br>> > the ExposureTime value is still valid, should we consider a way to<br>> > invalidate<br>> > (unset) it if the application wanted to just use the AE selected exposure<br>> > time<br>> > at step 5?<br>> ><br>> > ><br>> > ><br>> > > ><br>> > > > > +<br>> > > > > +        If ExposureTime is not set and the mode is<br>> > > > > ExposureTimeModeDisabled and<br>> > > > > +        AE was never Auto (either because the camera started in<br>> > Disabled<br>> > > > > mode,<br>> > > > > +        or Auto is not supported by the camera), the camera should<br>> > use a<br>> > > > > +        best-effort default value.<br>> > > > > +<br>> > > > > +        When ExposureTimeMode is set Auto, the value set in<br>> > ExposureTime<br>> > > > > is<br>> > > > > +        ignored and is not retained. This means that if<br>> > ExposureTimeMode<br>> > > > > is set<br>> > > > > +        to Disabled and ExposureTime is not also set, the exposure<br>> > time<br>> > > > > that<br>> > > > > +        was last computed by the AE algorithm while the mode was Auto<br>> > > > > will be<br>> > > > > +        applied to the sensor.<br>> > > > > +<br>> > > > > +        If ExposureTimeModeDisabled is supported, the ExposureTime<br>> > > > > control must<br>> > > > > +        also be supported.<br>> > > > > +<br>> > > > > +        The set of ExposureTimeMode modes that are supported by the<br>> > > > > camera must<br>> > > > > +        have an intersection with the supported set of<br>> > AnalogueGainMode<br>> > > > > modes.<br>> > > > ><br>> > > > > -        \sa AnalogueGain AeEnable<br>> > > > > +        As it takes a few frames to apply the exposure time, there<br>> > is a<br>> > > > > period of<br>> > > > > +        time between submitting a request with ExposureTimeMode set<br>> > to<br>> > > > > Disabled<br>> > > > > +        and the exposure time component of the AE actually being<br>> > disabled,<br>> > > > > +        during which the AE algorithm can still update the exposure<br>> > time.<br>> > > > > If an<br>> > > > > +        application is switching from automatic and manual control<br>> > and<br>> > > > > wishes<br>> > > > > +        to eliminate any flicker during the switch, the following<br>> > > > > procedure is<br>> > > > > +        recommended.<br>> > > > ><br>> > > ><br>> > > > I'm a bit confused by this bit to be honest.  If a user switches<br>> > > > ExposureTimeMode from<br>> > > > Auto to Disabled with the intention of setting a manual ExposureTime,<br>> > how<br>> > > > can we ever<br>> > > > avoid a glitch in the brightness (unless we also change AnalogueGain<br>> > > > appropriately)?<br>> > > ><br>> > ><br>> > > See below<br>> > ><br>> > > ><br>> > > > > -        \todo Document the interactions between AeEnable and setting<br>> > a<br>> > > > > fixed<br>> > > > > -        value for this control. Consider interactions with other AE<br>> > > > > features,<br>> > > > > -        such as aperture and aperture/shutter priority mode, and<br>> > decide if<br>> > > > > -        control of which features should be automatically adjusted<br>> > > > > shouldn't<br>> > > > > -        better be handled through a separate AE mode control.<br>> > > > > +        1. Start with ExposureTimeMode set to Auto<br>> > > > > +<br>> > > > > +        2. Set ExposureTimeMode to Disabled<br>> > > > > +<br>> > > > > +        3. Wait for the first request to be output that has<br>> > > > > ExposureTimeMode<br>> > > > > +        set to Disabled<br>> > > > ><br>> > > ><br>> > > > How would the application know this time point?  Would the AE algorithm<br>> > > > have to<br>> > > > count frames once it has been given a ExposureTimeModeDisabled ctrl then<br>> > > > return out the same in the metadata when it knows that it's last<br>> > requested<br>> > > > exposure<br>> > > > time change has been applied?<br>> > > ><br>> > ><br>> > > Not sure this is going to answer your question, but let's start by<br>> > > defining what a "glitch" is for us in this definition. I think it's<br>> > > useful to validate our understanding against your experience of providing<br>> > > this features to the vast number of users you have.<br>> > ><br>> > > The idea is that applications willing to control the exposure time<br>> > > explicitly might want to do so by minimizing the difference between<br>> > > the last value computed by the AEGC algorithm and their newly set<br>> > > value, to avoid a sudden change in exposure and gain which result in a<br>> > > visible "glitch". En example, suddenly moving the exposure time and<br>> > > gain to the opposite of the spectrum of what the AEGC was computing<br>> > > will result in images going very bright or very dark in just a few<br>> > > frames.<br>> > ><br>> > > The way to implement a smooth transition is to start from the values<br>> > > lastly computed by the AEGC (as available in metadata) and then "slowly"<br>> > > moving towards the desired manual value. Of course this is not<br>> > > mandatory, application might desire a sudden change of exposure, or simply<br>> > > won't care about smooth transitions. If they do, however, they have to<br>> > > consider that there will always be a number of requests in the queue<br>> > > that will be processed by the camera before the one with<br>> > > "ExposureTimeDisabled" gets to be processed.<br>> > ><br>> > > During the processing of those requests in the queue, the AEGC will still<br>> > > be active and might still change the exposure time (and gain) to values<br>> > quite<br>> > > different from the ones visible at the application at the time it<br>> > > queued the request with "ExposureTimeModeDisabled".<br>> > ><br>> > > The steps proposed here suggest to applications to wait until the<br>> > > "ExposureTimeModeDisabled" request is returned and the AEGC is<br>> > > actually off. From the definitions we gave here, this mean the<br>> > > exposure time (and gain) won't be updated by the now inactive AEGC<br>> > > block until an "ExposureTime" value is submitted by applications (more<br>> > > or less like your agc::pause()/resume() work, if I recall correctly).<br>> > ><br>> > > When the "ExposureTimeModeDisabled" request has completed,<br>> > > applications know that the exposure time won't be updated from that<br>> > > point on, and can use the ExposureTime and AnalogueGain metadata values<br>> > > as a "stable" starting point for their values.<br>> > ><br>> > > Does this make sense to you ?<br>> ><br>> > Yes it does, thanks for the clarification!<br>> ><br>> > One question still remains - how does the application know when the AE has<br>> > actullay finished - i.e. all the AE adjusted frames have been delivered?<br>> > Should<br>> > the IPA report "ExposureTimeModeDisabled" only when the AE adjust frames<br>> > have<br>> > been completed, or report it immediately?  The former will require AE to<br>><br>> I do expect IPAs to process all requests with AE activated until they<br>> don't get to crunch the one that has "ExposureTimeModeDisabled" in the<br>> controls list, then "pause" their AGC and set<br>> "ExposureTimeModeDisabled" in metadata (with the currently programmed<br>> exposure time in "ExposureTime"). From that point on the<br>> exposure time won't be updated anymore by AEGC.<br>><br>> Between the time an application sends a request with<br>> "ExposureTimeModeDisabled" and the time it should send one with an<br>> "ExposureTime" specified there will be a number of requests completed<br>> with the AEGC still reported as active.<br><br>That answers my question!<br><br>><br>> > hold<br>> > extra state and keep "running" even when it might be disabled, but it's not<br>> > too<br>> > big of a problem I suppose.<br>> ><br>><br>> I'm missing why the AEGC should keep a state, so I'm probably missing<br>> part of your reasoning<br><br>Actually, I was wrong, it's not EGC that keeps state, it is the IPA that does to<br>know when to send "ExposureTimeModeDisabled" metadat.<br><br>Thanks for the clarification.<br><br>Regards,<br>Naush<br><br><br>><br>> > ><br>> > > In my fixups I proposed a rework of the introduction section of this<br>> > > part, could you have a look to see if that's more clear ?<br>> > ><br>> > > ><br>> > > > > +<br>> > > > > +        4. Copy the value reported in ExposureTime into a new<br>> > request, and<br>> > > > > +        submit it<br>> > > > > +<br>> > > > > +        5. Proceed to run manual exposure time<br>> > > > ><br>> > > ><br>> > > > Again, I am unclear how this avoids glitches.  Say the AE chooses an<br>> > > > exposure<br>> > > > time of 33ms, then the user wants to switch to 15ms.  There is always<br>> > going<br>> > > > to<br>> > > > be a jump in brightness.  Perhaps my interpretation of this glitch is<br>> > not<br>> > > > the same<br>> > > > as what you are describing?<br>> > ><br>> > > If an application decides not to care and halves the exposure time<br>> > > from one request to the following one, the above procedure is useless<br>> > > indeed.<br>> > ><br>> > > But as explained above, an application might want to approach 15ms more<br>> > > smoothly and the above text suggests how to do so.<br>> > ><br>> > > I feel like this is mostly directed to applications that wants to<br>> > > drive the AEGC with some sort of algorithm instead of application<br>> > > that simply take a value in from users and apply it directly. In<br>> > > this latter case the values input from the user might very well be 1ms<br>> > > hence approaching it slowly might not even be desired.<br>> ><br>> > Thanks, I do understand when this might be needed now.  But I struggle to<br>> > see<br>> > why any application might want to do something like this, but that's not to<br>> > say<br>> > they won't :-)<br>><br>> To be honest the idea to have such a section in documentation comes<br>> from the fact android does describe it, so I presumed it was kind of a<br>> common parameter.<br>><br>> Thanks for review<br>><br>> ><br>> > Regards,<br>> > Naush<br>> ><br>> > ><br>> > > Thanks for commenting!<br>> > ><br>> > > ><br>> > > > Ditto comments for the AnalogueGain changes.<br>> > > ><br>> > > > Regards,<br>> > > > Naush<br>> > > ><br>> > > ><br>> > > > > +<br>> > > > > +        \sa ExposureTime<br>> > > > > +      enum:<br>> > > > > +        - name: ExposureTimeModeAuto<br>> > > > > +          value: 0<br>> > > > > +          description: |<br>> > > > > +            The exposure time will be calculated automatically and<br>> > set by<br>> > > > > the<br>> > > > > +            AE algorithm. If ExposureTime is set while this mode is<br>> > > > > active, it<br>> > > > > +            will be ignored, and it will also not be retained.<br>> > > > > +        - name: ExposureTimeModeDisabled<br>> > > > > +          value: 1<br>> > > > > +          description: |<br>> > > > > +            The exposure time will not be updated by the AE<br>> > algorithm. It<br>> > > > > will<br>> > > > > +            come from the last calculated value when the mode was<br>> > Auto,<br>> > > > > or from<br>> > > > > +            the value specified in ExposureTime.<br>> > > > > +<br>> > > > > +            When transitioning from Auto to Disabled mode, the last<br>> > > > > computed<br>> > > > > +            exposure value is used until a new value is specified<br>> > through<br>> > > > > the<br>> > > > > +            ExposureTime control. If an ExposureTime value is<br>> > specified<br>> > > > > in the<br>> > > > > +            same request where the ExposureTimeMode is changed from<br>> > Auto<br>> > > > > to<br>> > > > > +            Disabled, the provided ExposureTime is applied.<br>> > > > ><br>> > > > >    - AnalogueGain:<br>> > > > >        type: float<br>> > > > > @@ -144,17 +244,85 @@ controls:<br>> > > > >          The value of the control specifies the gain multiplier<br>> > applied to<br>> > > > > all<br>> > > > >          colour channels. This value cannot be lower than 1.0.<br>> > > > ><br>> > > > > -        Setting this value means that it is now fixed and the AE<br>> > > > > algorithm may<br>> > > > > -        not change it. Setting it back to zero returns it to the<br>> > control<br>> > > > > of the<br>> > > > > -        AE algorithm.<br>> > > > > +        This control will only take effect if AnalogueGainMode is<br>> > > > > Disabled. If<br>> > > > > +        this control is set when AnalogueGainMode is Auto, the value<br>> > will<br>> > > > > be<br>> > > > > +        ignored and will not be retained.<br>> > > > > +<br>> > > > > +        When reported in metadata, this control indicates what<br>> > analogue<br>> > > > > gain<br>> > > > > +        was used for the current request, regardless of<br>> > AnalogueGainMode.<br>> > > > > +        AnalogueGainMode will indicate the source of the analogue<br>> > gain<br>> > > > > value,<br>> > > > > +        whether it came from the AE algorithm or not.<br>> > > > > +<br>> > > > > +        \sa ExposureTime<br>> > > > > +        \sa AnalogueGainMode<br>> > > > > +<br>> > > > > +  - AnalogueGainMode:<br>> > > > > +      type: int32_t<br>> > > > > +      description: |<br>> > > > > +        Controls the source of the analogue gain that is applied to<br>> > the<br>> > > > > image<br>> > > > > +        sensor. When set to Auto, the AE algorithm computes the<br>> > analogue<br>> > > > > gain<br>> > > > > +        and configures the image sensor accordingly. When set to<br>> > Disabled,<br>> > > > > +        analogue gain specified in AnalogueGain is applied to the<br>> > image<br>> > > > > sensor.<br>> > > > > +        If AnalogueGain is not set, then the value last computed by<br>> > the AE<br>> > > > > +        algorithm when the mode was Auto will be used.<br>> > > > > +<br>> > > > > +        If AnalogueGain is not set and the mode is<br>> > > > > AnalogueGainModeDisabled and<br>> > > > > +        AE was never Auto (either because the camera started in<br>> > Disabled<br>> > > > > mode,<br>> > > > > +        or Auto is not supported by the camera), the camera should<br>> > use a<br>> > > > > +        best-effort default value.<br>> > > > > +<br>> > > > > +        When AnalogueGainMode is set Auto, the value set in<br>> > AnalogueGain<br>> > > > > is<br>> > > > > +        ignored and is not retained. This means that if<br>> > AnalogueGainMode<br>> > > > > is set<br>> > > > > +        to Disabled and AnalogueGain is not also set, the analogue<br>> > gain<br>> > > > > that<br>> > > > > +        was last computed by the AE algorithm while the mode was Auto<br>> > > > > will be<br>> > > > > +        applied to the sensor.<br>> > > > ><br>> > > > > -        \sa ExposureTime AeEnable<br>> > > > > +        If AnalogueGainModeDisabled is supported, the AnalogueGain<br>> > > > > control must<br>> > > > > +        also be supported.<br>> > > > > +<br>> > > > > +        The set of AnalogueGainMode modes that are supported by the<br>> > > > > camera must<br>> > > > > +        have an intersection with the supported set of<br>> > ExposureTimeMode<br>> > > > > modes.<br>> > > > > +<br>> > > > > +        As it takes a few frames to apply the analogue gain, there<br>> > is a<br>> > > > > period of<br>> > > > > +        time between submitting a request with AnalogueGainMode set<br>> > to<br>> > > > > Disabled<br>> > > > > +        and the analogue gain component of the AE actually being<br>> > disabled,<br>> > > > > +        during which the AE algorithm can still update the analogue<br>> > gain.<br>> > > > > If an<br>> > > > > +        application is switching from automatic and manual control<br>> > and<br>> > > > > wishes<br>> > > > > +        to eliminate any flicker during the switch, the following<br>> > > > > procedure is<br>> > > > > +        recommended.<br>> > > > > +<br>> > > > > +        1. Start with AnalogueGainMode set to Auto<br>> > > > > +<br>> > > > > +        2. Set AnalogueGainMode to Disabled<br>> > > > > +<br>> > > > > +        3. Wait for the first request to be output that has<br>> > > > > AnalogueGainMode<br>> > > > > +        set to Disabled<br>> > > > > +<br>> > > > > +        4. Copy the value reported in AnalogueGain into a new<br>> > request, and<br>> > > > > +        submit it<br>> > > > > +<br>> > > > > +        5. Proceed to run manual analogue gain<br>> > > > ><br>> > > > +<br>> > > > > +        \sa AnalogueGain<br>> > > > > +      enum:<br>> > > > > +        - name: AnalogueGainModeAuto<br>> > > > > +          value: 0<br>> > > > > +          description: |<br>> > > > > +            The analogue gain will be calculated automatically and<br>> > set by<br>> > > > > the<br>> > > > > +            AE algorithm. If AnalogueGain is set while this mode is<br>> > > > > active, it<br>> > > > > +            will be ignored, and it will also not be retained.<br>> > > > > +        - name: AnalogueGainModeDisabled<br>> > > > > +          value: 1<br>> > > > > +          description: |<br>> > > > > +            The analogue gain will not be updated by the AE<br>> > algorithm. It<br>> > > > > will<br>> > > > > +            come from the last calculated value when the mode was<br>> > Auto,<br>> > > > > or from<br>> > > > > +            the value specified in AnalogueGain.<br>> > > > ><br>> > > > > -        \todo Document the interactions between AeEnable and setting<br>> > a<br>> > > > > fixed<br>> > > > > -        value for this control. Consider interactions with other AE<br>> > > > > features,<br>> > > > > -        such as aperture and aperture/shutter priority mode, and<br>> > decide if<br>> > > > > -        control of which features should be automatically adjusted<br>> > > > > shouldn't<br>> > > > > -        better be handled through a separate AE mode control.<br>> > > > > +            When transitioning from Auto to Disabled mode the last<br>> > > > > computed<br>> > > > > +            gain value is used until a new value is specified<br>> > through the<br>> > > > > +            AnalogueGain control. If an AnalogueGain value is<br>> > specified<br>> > > > > in the<br>> > > > > +            same request where the AnalogueGainMode is set to<br>> > Disabled,<br>> > > > > the<br>> > > > > +            provided AnalogueGain is applied.<br>> > > > ><br>> > > > >    - Brightness:<br>> > > > >        type: float<br>> > > > > @@ -477,36 +645,6 @@ controls:<br>> > > > >              High quality aberration correction which might reduce the<br>> > > > > frame<br>> > > > >              rate.<br>> > > > ><br>> > > > > -  - AeState:<br>> > > > > -      type: int32_t<br>> > > > > -      draft: true<br>> > > > > -      description: |<br>> > > > > -       Control to report the current AE algorithm state. Currently<br>> > > > > identical to<br>> > > > > -       ANDROID_CONTROL_AE_STATE.<br>> > > > > -<br>> > > > > -        Current state of the AE algorithm.<br>> > > > > -      enum:<br>> > > > > -        - name: AeStateInactive<br>> > > > > -          value: 0<br>> > > > > -          description: The AE algorithm is inactive.<br>> > > > > -        - name: AeStateSearching<br>> > > > > -          value: 1<br>> > > > > -          description: The AE algorithm has not converged yet.<br>> > > > > -        - name: AeStateConverged<br>> > > > > -          value: 2<br>> > > > > -          description: The AE algorithm has converged.<br>> > > > > -        - name: AeStateLocked<br>> > > > > -          value: 3<br>> > > > > -          description: The AE algorithm is locked.<br>> > > > > -        - name: AeStateFlashRequired<br>> > > > > -          value: 4<br>> > > > > -          description: The AE algorithm would need a flash for good<br>> > > > > results<br>> > > > > -        - name: AeStatePrecapture<br>> > > > > -          value: 5<br>> > > > > -          description: |<br>> > > > > -            The AE algorithm has started a pre-capture metering<br>> > session.<br>> > > > > -            \sa AePrecaptureTrigger<br>> > > > > -<br>> > > > >    - AfState:<br>> > > > >        type: int32_t<br>> > > > >        draft: true<br>> > > > > --<br>> > > > > 2.30.2<br>> > > > ><br>> > > > ></div>