Documentation/media/uapi/v4l/ext-ctrls-flash.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _flash-controls:
  11
  12 ***********************
  13 Flash Control Reference
  14 ***********************
  15
  16 The V4L2 flash controls are intended to provide generic access to flash
  17 controller devices. Flash controller devices are typically used in
  18 digital cameras.
  19
  20 The interface can support both LED and xenon flash devices. As of
  21 writing this, there is no xenon flash driver using this interface.
  22
  23
  24 .. _flash-controls-use-cases:
  25
  26 Supported use cases
  27 ===================
  28
  29
  30 Unsynchronised LED flash (software strobe)
  31 ------------------------------------------
  32
  33 Unsynchronised LED flash is controlled directly by the host as the
  34 sensor. The flash must be enabled by the host before the exposure of the
  35 image starts and disabled once it ends. The host is fully responsible
  36 for the timing of the flash.
  37
  38 Example of such device: Nokia N900.
  39
  40
  41 Synchronised LED flash (hardware strobe)
  42 ----------------------------------------
  43
  44 The synchronised LED flash is pre-programmed by the host (power and
  45 timeout) but controlled by the sensor through a strobe signal from the
  46 sensor to the flash.
  47
  48 The sensor controls the flash duration and timing. This information
  49 typically must be made available to the sensor.
  50
  51
  52 LED flash as torch
  53 ------------------
  54
  55 LED flash may be used as torch in conjunction with another use case
  56 involving camera or individually.
  57
  58
  59 .. _flash-control-id:
  60
  61 Flash Control IDs
  62 -----------------
  63
  64 ``V4L2_CID_FLASH_CLASS (class)``
  65     The FLASH class descriptor.
  66
  67 ``V4L2_CID_FLASH_LED_MODE (menu)``
  68     Defines the mode of the flash LED, the high-power white LED attached
  69     to the flash controller. Setting this control may not be possible in
  70     presence of some faults. See V4L2_CID_FLASH_FAULT.
  71
  72
  73
  74 .. flat-table::
  75     :header-rows:  0
  76     :stub-columns: 0
  77
  78     * - ``V4L2_FLASH_LED_MODE_NONE``
  79       - Off.
  80     * - ``V4L2_FLASH_LED_MODE_FLASH``
  81       - Flash mode.
  82     * - ``V4L2_FLASH_LED_MODE_TORCH``
  83       - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
  84
  85
  86
  87 ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
  88     Defines the source of the flash LED strobe.
  89
  90 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
  91
  92 .. flat-table::
  93     :header-rows:  0
  94     :stub-columns: 0
  95
  96     * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
  97       - The flash strobe is triggered by using the
  98         V4L2_CID_FLASH_STROBE control.
  99     * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
 100       - The flash strobe is triggered by an external source. Typically
 101         this is a sensor, which makes it possible to synchronises the
 102         flash strobe start to exposure start.
 103
 104
 105
 106 ``V4L2_CID_FLASH_STROBE (button)``
 107     Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
 108     V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
 109     is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
 110     control may not be possible in presence of some faults. See
 111     V4L2_CID_FLASH_FAULT.
 112
 113 ``V4L2_CID_FLASH_STROBE_STOP (button)``
 114     Stop flash strobe immediately.
 115
 116 ``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
 117     Strobe status: whether the flash is strobing at the moment or not.
 118     This is a read-only control.
 119
 120 ``V4L2_CID_FLASH_TIMEOUT (integer)``
 121     Hardware timeout for flash. The flash strobe is stopped after this
 122     period of time has passed from the start of the strobe.
 123
 124 ``V4L2_CID_FLASH_INTENSITY (integer)``
 125     Intensity of the flash strobe when the flash LED is in flash mode
 126     (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
 127     if possible.
 128
 129 ``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
 130     Intensity of the flash LED in torch mode
 131     (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
 132     if possible. Setting this control may not be possible in presence of
 133     some faults. See V4L2_CID_FLASH_FAULT.
 134
 135 ``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
 136     Intensity of the indicator LED. The indicator LED may be fully
 137     independent of the flash LED. The unit should be microamps (uA) if
 138     possible.
 139
 140 ``V4L2_CID_FLASH_FAULT (bitmask)``
 141     Faults related to the flash. The faults tell about specific problems
 142     in the flash chip itself or the LEDs attached to it. Faults may
 143     prevent further use of some of the flash controls. In particular,
 144     V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
 145     if the fault affects the flash LED. Exactly which faults have such
 146     an effect is chip dependent. Reading the faults resets the control
 147     and returns the chip to a usable state if possible.
 148
 149 .. tabularcolumns:: |p{8.0cm}|p{9.5cm}|
 150
 151 .. flat-table::
 152     :header-rows:  0
 153     :stub-columns: 0
 154
 155     * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
 156       - Flash controller voltage to the flash LED has exceeded the limit
 157         specific to the flash controller.
 158     * - ``V4L2_FLASH_FAULT_TIMEOUT``
 159       - The flash strobe was still on when the timeout set by the user ---
 160         V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
 161         controllers may set this in all such conditions.
 162     * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
 163       - The flash controller has overheated.
 164     * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
 165       - The short circuit protection of the flash controller has been
 166         triggered.
 167     * - ``V4L2_FLASH_FAULT_OVER_CURRENT``
 168       - Current in the LED power supply has exceeded the limit specific to
 169         the flash controller.
 170     * - ``V4L2_FLASH_FAULT_INDICATOR``
 171       - The flash controller has detected a short or open circuit
 172         condition on the indicator LED.
 173     * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
 174       - Flash controller voltage to the flash LED has been below the
 175         minimum limit specific to the flash controller.
 176     * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
 177       - The input voltage of the flash controller is below the limit under
 178         which strobing the flash at full current will not be possible.The
 179         condition persists until this flag is no longer set.
 180     * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
 181       - The temperature of the LED has exceeded its allowed upper limit.
 182
 183
 184
 185 ``V4L2_CID_FLASH_CHARGE (boolean)``
 186     Enable or disable charging of the xenon flash capacitor.
 187
 188 ``V4L2_CID_FLASH_READY (boolean)``
 189     Is the flash ready to strobe? Xenon flashes require their capacitors
 190     charged before strobing. LED flashes often require a cooldown period
 191     after strobe during which another strobe will not be possible. This
 192     is a read-only control.