Debian Codegraph @

Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst

raw
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L
3
4 .. _flash-controls:
5
6 ***********************
7 Flash Control Reference
8 ***********************
9
10 The V4L2 flash controls are intended to provide generic access to flash
11 controller devices. Flash controller devices are typically used in
12 digital cameras.
13
14 The interface can support both LED and xenon flash devices. As of
15 writing this, there is no xenon flash driver using this interface.
16
17
18 .. _flash-controls-use-cases:
19
20 Supported use cases
21 ===================
22
23
24 Unsynchronised LED flash (software strobe)
25 ------------------------------------------
26
27 Unsynchronised LED flash is controlled directly by the host as the
28 sensor. The flash must be enabled by the host before the exposure of the
29 image starts and disabled once it ends. The host is fully responsible
30 for the timing of the flash.
31
32 Example of such device: Nokia N900.
33
34
35 Synchronised LED flash (hardware strobe)
36 ----------------------------------------
37
38 The synchronised LED flash is pre-programmed by the host (power and
39 timeout) but controlled by the sensor through a strobe signal from the
40 sensor to the flash.
41
42 The sensor controls the flash duration and timing. This information
43 typically must be made available to the sensor.
44
45
46 LED flash as torch
47 ------------------
48
49 LED flash may be used as torch in conjunction with another use case
50 involving camera or individually.
51
52
53 .. _flash-control-id:
54
55 Flash Control IDs
56 -----------------
57
58 ``V4L2_CID_FLASH_CLASS (class)``
59 The FLASH class descriptor.
60
61 .. _v4l2-cid-flash-led-mode:
62
63 ``V4L2_CID_FLASH_LED_MODE (menu)``
64 Defines the mode of the flash LED, the high-power white LED attached
65 to the flash controller. Setting this control may not be possible in
66 presence of some faults. See V4L2_CID_FLASH_FAULT.
67
68
69 .. tabularcolumns:: |p{5.7cm}|p{11.8cm}|
70
71 .. flat-table::
72 :header-rows: 0
73 :stub-columns: 0
74
75 * - ``V4L2_FLASH_LED_MODE_NONE``
76 - Off.
77 * - ``V4L2_FLASH_LED_MODE_FLASH``
78 - Flash mode.
79 * - ``V4L2_FLASH_LED_MODE_TORCH``
80 - Torch mode.
81
82 See V4L2_CID_FLASH_TORCH_INTENSITY.
83
84
85
86 .. _v4l2-cid-flash-strobe-source:
87
88 ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
89 Defines the source of the flash LED strobe.
90
91 .. tabularcolumns:: |p{7.5cm}|p{7.5cm}|
92
93 .. flat-table::
94 :header-rows: 0
95 :stub-columns: 0
96
97 * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
98 - The flash strobe is triggered by using the
99 V4L2_CID_FLASH_STROBE control.
100 * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
101 - The flash strobe is triggered by an external source. Typically
102 this is a sensor, which makes it possible to synchronise the
103 flash strobe start to exposure start.
104 This method of controlling flash LED strobe has two additional
105 prerequisites: the strobe source's :ref:`strobe output
106 <v4l2-cid-flash-strobe-oe>` must be enabled (if available)
107 and the flash controller's :ref:`flash LED mode
108 <v4l2-cid-flash-led-mode>` must be set to
109 ``V4L2_FLASH_LED_MODE_FLASH``.
110
111
112
113 ``V4L2_CID_FLASH_STROBE (button)``
114 Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
115 V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
116 is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
117 control may not be possible in presence of some faults. See
118 V4L2_CID_FLASH_FAULT.
119
120 ``V4L2_CID_FLASH_STROBE_STOP (button)``
121 Stop flash strobe immediately.
122
123 ``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
124 Strobe status: whether the flash is strobing at the moment or not.
125 This is a read-only control.
126
127 ``V4L2_CID_FLASH_TIMEOUT (integer)``
128 Hardware timeout for flash. The flash strobe is stopped after this
129 period of time has passed from the start of the strobe.
130
131 ``V4L2_CID_FLASH_INTENSITY (integer)``
132 Intensity of the flash strobe when the flash LED is in flash mode
133 (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
134 if possible.
135
136 ``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
137 Intensity of the flash LED in torch mode
138 (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
139 if possible. Setting this control may not be possible in presence of
140 some faults. See V4L2_CID_FLASH_FAULT.
141
142 ``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
143 Intensity of the indicator LED. The indicator LED may be fully
144 independent of the flash LED. The unit should be microamps (uA) if
145 possible.
146
147 ``V4L2_CID_FLASH_FAULT (bitmask)``
148 Faults related to the flash. The faults tell about specific problems
149 in the flash chip itself or the LEDs attached to it. Faults may
150 prevent further use of some of the flash controls. In particular,
151 V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
152 if the fault affects the flash LED. Exactly which faults have such
153 an effect is chip dependent. Reading the faults resets the control
154 and returns the chip to a usable state if possible.
155
156 .. tabularcolumns:: |p{8.4cm}|p{9.1cm}|
157
158 .. flat-table::
159 :header-rows: 0
160 :stub-columns: 0
161
162 * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
163 - Flash controller voltage to the flash LED has exceeded the limit
164 specific to the flash controller.
165 * - ``V4L2_FLASH_FAULT_TIMEOUT``
166 - The flash strobe was still on when the timeout set by the user ---
167 V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
168 controllers may set this in all such conditions.
169 * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
170 - The flash controller has overheated.
171 * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
172 - The short circuit protection of the flash controller has been
173 triggered.
174 * - ``V4L2_FLASH_FAULT_OVER_CURRENT``
175 - Current in the LED power supply has exceeded the limit specific to
176 the flash controller.
177 * - ``V4L2_FLASH_FAULT_INDICATOR``
178 - The flash controller has detected a short or open circuit
179 condition on the indicator LED.
180 * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
181 - Flash controller voltage to the flash LED has been below the
182 minimum limit specific to the flash controller.
183 * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
184 - The input voltage of the flash controller is below the limit under
185 which strobing the flash at full current will not be possible.The
186 condition persists until this flag is no longer set.
187 * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
188 - The temperature of the LED has exceeded its allowed upper limit.
189
190
191
192 ``V4L2_CID_FLASH_CHARGE (boolean)``
193 Enable or disable charging of the xenon flash capacitor.
194
195 ``V4L2_CID_FLASH_READY (boolean)``
196 Is the flash ready to strobe? Xenon flashes require their capacitors
197 charged before strobing. LED flashes often require a cooldown period
198 after strobe during which another strobe will not be possible. This
199 is a read-only control.
200
201 .. _v4l2-cid-flash-duration:
202
203 ``V4L2_CID_FLASH_DURATION (integer)``
204 Duration of the flash strobe pulse generated by the strobe source, when
205 using external strobe. This control shall be implemented by the device
206 generating the hardware flash strobe signal, typically a camera sensor,
207 connected to a flash controller.
208
209 The flash controllers :ref:`strobe source <v4l2-cid-flash-strobe-source>`
210 must be configured to ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL`` for this
211 mode of operation. For more details please also take a look at the
212 documentation there.
213
214 The unit should be microseconds (µs) if possible.
215
216 .. _v4l2-cid-flash-strobe-oe:
217
218 ``V4L2_CID_FLASH_STROBE_OE (boolean)``
219 Enables the output of a hardware strobe signal from the strobe source,
220 when using external strobe. This control shall be implemented by the device
221 generating the hardware flash strobe signal, typically a camera sensor,
222 connected to a flash controller.
223
224 Provided the signal generating device driver supports it, the length of the
225 strobe signal can be configured by adjusting its
226 :ref:`flash duration <v4l2-cid-flash-duration>`.
227
228 The flash controllers :ref:`strobe source <v4l2-cid-flash-strobe-source>`
229 must be configured to ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL`` for this
230 mode of operation. For more details please also take a look at the
231 documentation there.