# SPDX-License-Identifier: LGPL-2.1-or-later
#
# Copyright (C) 2019, Google Inc.
#
%YAML 1.2
---
# Unless otherwise stated, all controls are bi-directional, i.e. they can be
# set through Request::controls() and returned out through Request::metadata().
controls:
  - AeEnable:
      type: bool
      description: |
        Enable or disable the AE.

        \sa ExposureTime AnalogueGain

  - AeLocked:
      type: bool
      description: |
        Report the lock status of a running AE algorithm.

        If the AE algorithm is locked the value shall be set to true, if it's
        converging it shall be set to false. If the AE algorithm is not
        running the control shall not be present in the metadata control list.

        \sa AeEnable

  # AeMeteringMode needs further attention:
  # - Auto-generate max enum value.
  # - Better handling of custom types.
  - AeMeteringMode:
      type: int32_t
      description: |
        Specify a metering mode for the AE algorithm to use. The metering
        modes determine which parts of the image are used to determine the
        scene brightness. Metering modes may be platform specific and not
        all metering modes may be supported.
      enum:
        - name: MeteringCentreWeighted
          value: 0
          description: Centre-weighted metering mode.
        - name: MeteringSpot
          value: 1
          description: Spot metering mode.
        - name: MeteringMatrix
          value: 2
          description: Matrix metering mode.
        - name: MeteringCustom
          value: 3
          description: Custom metering mode.

  # AeConstraintMode needs further attention:
  # - Auto-generate max enum value.
  # - Better handling of custom types.
  - AeConstraintMode:
      type: int32_t
      description: |
        Specify a constraint mode for the AE algorithm to use. These determine
        how the measured scene brightness is adjusted to reach the desired
        target exposure. Constraint modes may be platform specific, and not
        all constraint modes may be supported.
      enum:
        - name: ConstraintNormal
          value: 0
          description: Default constraint mode.
            This mode aims to balance the exposure of different parts of the
            image so as to reach a reasonable average level. However, highlights
            in the image may appear over-exposed and lowlights may appear
            under-exposed.
        - name: ConstraintHighlight
          value: 1
          description: Highlight constraint mode.
            This mode adjusts the exposure levels in order to try and avoid
            over-exposing the brightest parts (highlights) of an image.
            Other non-highlight parts of the image may appear under-exposed.
        - name: ConstraintShadows
          value: 2
          description: Shadows constraint mode.
            This mode adjusts the exposure levels in order to try and avoid
            under-exposing the dark parts (shadows) of an image. Other normally
            exposed parts of the image may appear over-exposed.
        - name: ConstraintCustom
          value: 3
          description: Custom constraint mode.

  # AeExposureMode needs further attention:
  # - Auto-generate max enum value.
  # - Better handling of custom types.
  - AeExposureMode:
      type: int32_t
      description: |
        Specify an exposure mode for the AE algorithm to use. These specify
        how the desired total exposure is divided between the shutter time
        and the sensor's analogue gain. The exposure modes are platform
        specific, and not all exposure modes may be supported.
      enum:
        - name: ExposureNormal
          value: 0
          description: Default exposure mode.
        - name: ExposureShort
          value: 1
          description: Exposure mode allowing only short exposure times.
        - name: ExposureLong
          value: 2
          description: Exposure mode allowing long exposure times.
        - name: ExposureCustom
          value: 3
          description: Custom exposure mode.

  - ExposureValue:
      type: float
      description: |
        Specify an Exposure Value (EV) parameter. The EV parameter will only be
        applied if the AE algorithm is currently enabled.