Line data Source code
1 1 : /*
2 : * Copyright (c) 2019 Linaro Limited.
3 : * Copyright (c) 2024 tinyVision.ai Inc.
4 : * Copyright 2025 NXP
5 : *
6 : * SPDX-License-Identifier: Apache-2.0
7 : */
8 : #ifndef ZEPHYR_INCLUDE_VIDEO_CONTROLS_H_
9 : #define ZEPHYR_INCLUDE_VIDEO_CONTROLS_H_
10 :
11 : /**
12 : * @file
13 : *
14 : * @brief Public APIs for Video.
15 : */
16 :
17 : /**
18 : * @brief Video controls
19 : * @defgroup video_controls Video Controls
20 : * @ingroup video_interface
21 : *
22 : * The Video control IDs (CIDs) are introduced with the same name as
23 : * Linux V4L2 subsystem and under the same class. This facilitates
24 : * inter-operability and debugging devices end-to-end across Linux and
25 : * Zephyr.
26 : *
27 : * This list is maintained compatible to the Linux kernel definitions in
28 : * @c linux/include/uapi/linux/v4l2-controls.h
29 : *
30 : * @{
31 : */
32 :
33 : #include <stdint.h>
34 :
35 : #ifdef __cplusplus
36 : extern "C" {
37 : #endif
38 :
39 : /**
40 : * @name Base class control IDs
41 : * @{
42 : */
43 0 : #define VIDEO_CID_BASE 0x00980900
44 :
45 : /** Picture brightness, or more precisely, the black level. */
46 1 : #define VIDEO_CID_BRIGHTNESS (VIDEO_CID_BASE + 0)
47 :
48 : /** Picture contrast or luma gain. */
49 1 : #define VIDEO_CID_CONTRAST (VIDEO_CID_BASE + 1)
50 :
51 : /** Picture color saturation or chroma gain. */
52 1 : #define VIDEO_CID_SATURATION (VIDEO_CID_BASE + 2)
53 :
54 : /** Hue or color balance. */
55 1 : #define VIDEO_CID_HUE (VIDEO_CID_BASE + 3)
56 :
57 : /** Automatic white balance (cameras). */
58 1 : #define VIDEO_CID_AUTO_WHITE_BALANCE (VIDEO_CID_BASE + 12)
59 :
60 : /** Red chroma balance, as a ratio to the green channel. */
61 1 : #define VIDEO_CID_RED_BALANCE (VIDEO_CID_BASE + 14)
62 :
63 : /** Blue chroma balance, as a ratio to the green channel. */
64 1 : #define VIDEO_CID_BLUE_BALANCE (VIDEO_CID_BASE + 15)
65 :
66 : /** Gamma adjust. */
67 1 : #define VIDEO_CID_GAMMA (VIDEO_CID_BASE + 16)
68 :
69 : /** Image sensor exposure time. */
70 1 : #define VIDEO_CID_EXPOSURE (VIDEO_CID_BASE + 17)
71 :
72 : /** Automatic gain control */
73 1 : #define VIDEO_CID_AUTOGAIN (VIDEO_CID_BASE + 18)
74 :
75 : /** Gain control. Most devices control only digital gain with this control.
76 : * Devices that recognise the difference between digital and analogue gain use
77 : * VIDEO_CID_DIGITAL_GAIN and VIDEO_CID_ANALOGUE_GAIN.
78 : */
79 1 : #define VIDEO_CID_GAIN (VIDEO_CID_BASE + 19)
80 :
81 : /** Flip the image horizontally: the left side becomes the right side */
82 1 : #define VIDEO_CID_HFLIP (VIDEO_CID_BASE + 20)
83 :
84 : /** Flip the image vertically: the top side becomes the bottom side */
85 1 : #define VIDEO_CID_VFLIP (VIDEO_CID_BASE + 21)
86 :
87 : /** Frequency of the power line to compensate for.
88 : * Avoids flicker due to artificial lighting.
89 : */
90 1 : #define VIDEO_CID_POWER_LINE_FREQUENCY (VIDEO_CID_BASE + 24)
91 :
92 : /**
93 : * @brief Video power line frequency
94 : */
95 1 : enum video_power_line_frequency {
96 : VIDEO_CID_POWER_LINE_FREQUENCY_DISABLED = 0, /**< Power line frequency disabled. */
97 : VIDEO_CID_POWER_LINE_FREQUENCY_50HZ = 1, /**< 50 Hz power line frequency. */
98 : VIDEO_CID_POWER_LINE_FREQUENCY_60HZ = 2, /**< 60 Hz power line frequency. */
99 : VIDEO_CID_POWER_LINE_FREQUENCY_AUTO = 3, /**< Automatic power line frequency. */
100 : };
101 :
102 : /** Enables automatic hue control by the device.
103 : * Setting @ref VIDEO_CID_HUE while automatic hue control is enabled is undefined.
104 : * Drivers should ignore such request.
105 : */
106 1 : #define VIDEO_CID_HUE_AUTO (VIDEO_CID_BASE + 25)
107 :
108 : /** White balance settings as a color temperature in Kelvin.
109 : * A driver should have a minimum range of 2800 (incandescent) to 6500 (daylight).
110 : */
111 1 : #define VIDEO_CID_WHITE_BALANCE_TEMPERATURE (VIDEO_CID_BASE + 26)
112 :
113 : /** Adjusts the sharpness filters in a camera.
114 : * The minimum value disables the filters, higher values give a sharper picture.
115 : */
116 1 : #define VIDEO_CID_SHARPNESS (VIDEO_CID_BASE + 27)
117 :
118 : /** Adjusts the backlight compensation in a camera.
119 : * The minimum value disables backlight compensation.
120 : */
121 1 : #define VIDEO_CID_BACKLIGHT_COMPENSATION (VIDEO_CID_BASE + 28)
122 :
123 : /** Selects a color effect. */
124 1 : #define VIDEO_CID_COLORFX (VIDEO_CID_BASE + 31)
125 :
126 : /**
127 : * @brief Video color effects
128 : */
129 1 : enum video_colorfx {
130 : VIDEO_COLORFX_NONE = 0, /**< No color effect. */
131 : VIDEO_COLORFX_BW = 1, /**< Black and white effect. */
132 : VIDEO_COLORFX_SEPIA = 2, /**< Sepia tone effect. */
133 : VIDEO_COLORFX_NEGATIVE = 3, /**< Negative image effect. */
134 : VIDEO_COLORFX_EMBOSS = 4, /**< Emboss effect. */
135 : VIDEO_COLORFX_SKETCH = 5, /**< Sketch/drawing effect. */
136 : VIDEO_COLORFX_SKY_BLUE = 6, /**< Sky blue tint effect. */
137 : VIDEO_COLORFX_GRASS_GREEN = 7, /**< Grass green tint effect. */
138 : VIDEO_COLORFX_SKIN_WHITEN = 8, /**< Skin whitening effect. */
139 : VIDEO_COLORFX_VIVID = 9, /**< Vivid/bright color effect. */
140 : VIDEO_COLORFX_AQUA = 10, /**< Aqua (blue-green) effect. */
141 : VIDEO_COLORFX_ART_FREEZE = 11, /**< Art freeze/stylized effect. */
142 : VIDEO_COLORFX_SILHOUETTE = 12, /**< Silhouette effect. */
143 : VIDEO_COLORFX_SOLARIZATION = 13, /**< Solarization effect. */
144 : VIDEO_COLORFX_ANTIQUE = 14, /**< Antique/vintage effect. */
145 : };
146 :
147 : /** Enables automatic brightness. */
148 1 : #define VIDEO_CID_AUTOBRIGHTNESS (VIDEO_CID_BASE + 32)
149 :
150 : /** Switch the band-stop filter of a camera sensor on or off, or specify its strength.
151 : * Such band-stop filters can be used, for example, to filter out the fluorescent light component.
152 : */
153 1 : #define VIDEO_CID_BAND_STOP_FILTER (VIDEO_CID_BASE + 33)
154 :
155 : /** Sets the alpha color component.
156 : * Some devices produce data with a user-controllable alpha component. Set the value applied to
157 : * the alpha channel of every pixel produced.
158 : */
159 1 : #define VIDEO_CID_ALPHA_COMPONENT (VIDEO_CID_BASE + 41)
160 :
161 : /** Last base CID + 1 */
162 1 : #define VIDEO_CID_LASTP1 (VIDEO_CID_BASE + 44)
163 :
164 : /**
165 : * @}
166 : */
167 :
168 : /**
169 : * @name Stateful codec controls IDs
170 : * @{
171 : */
172 0 : #define VIDEO_CID_CODEC_CLASS_BASE 0x00990900
173 :
174 : /**
175 : * @}
176 : */
177 :
178 : /**
179 : * @name Camera class controls IDs
180 : * @{
181 : */
182 0 : #define VIDEO_CID_CAMERA_CLASS_BASE 0x009a0900
183 :
184 : /** Enables automatic adjustments of the exposure time and/or iris aperture.
185 : * Manual exposure or iris changes when it is not @ref VIDEO_EXPOSURE_MANUAL is undefined.
186 : * Drivers should ignore such requests.
187 : */
188 1 : #define VIDEO_CID_EXPOSURE_AUTO (VIDEO_CID_CAMERA_CLASS_BASE + 1)
189 :
190 : /**
191 : * @brief Video exposure type
192 : */
193 1 : enum video_exposure_type {
194 : VIDEO_EXPOSURE_AUTO = 0, /**< Automatic exposure. */
195 : VIDEO_EXPOSURE_MANUAL = 1, /**< Manual exposure. */
196 : VIDEO_EXPOSURE_SHUTTER_PRIORITY = 2, /**< Shutter priority. */
197 : VIDEO_EXPOSURE_APERTURE_PRIORITY = 3 /**< Aperture priority. */
198 : };
199 :
200 : /** Determines the exposure time of the camera sensor.
201 : * The exposure time is limited by the frame in terval. Drivers should interpret the values as
202 : * 100 µs units, where the value 1 stands for 1/10000th of a second, 10000 for 1 second and 100000
203 : * for 10 seconds.
204 : */
205 1 : #define VIDEO_CID_EXPOSURE_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 2)
206 :
207 : /** Whether the device may dynamically vary the frame rate under the effect of auto-exposure
208 : * Applicable when @ref VIDEO_CID_EXPOSURE_AUTO is set to @ref VIDEO_EXPOSURE_AUTO or
209 : * @ref VIDEO_EXPOSURE_APERTURE_PRIORITY. Disabled by default: the frame rate must remain constant.
210 : */
211 1 : #define VIDEO_CID_EXPOSURE_AUTO_PRIORITY (VIDEO_CID_CAMERA_CLASS_BASE + 3)
212 :
213 : /** This write-only control turns the camera horizontally by the specified amount.
214 : * The unit is undefined. A positive value moves the camera to the right (clockwise when viewed
215 : * from above), a negative value to the left. A value of zero does not cause motion.
216 : */
217 1 : #define VIDEO_CID_PAN_RELATIVE (VIDEO_CID_CAMERA_CLASS_BASE + 4)
218 :
219 : /** This write-only control turns the camera vertically by the specified amount.
220 : * The unit is undefined. A positive value moves the camera up, a negative value down.
221 : * A value of zero does not cause motion.
222 : */
223 1 : #define VIDEO_CID_TILT_RELATIVE (VIDEO_CID_CAMERA_CLASS_BASE + 5)
224 :
225 : /** This control turns the camera horizontally to the specified position.
226 : * Positive values move the camera to the right (clockwise when viewed from above), negative
227 : * values to the left. Drivers should interpret the values as arc seconds, with valid values
228 : * between -180 * 3600 and +180 * 3600 inclusive.
229 : */
230 1 : #define VIDEO_CID_PAN_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 8)
231 :
232 : /** This control turns the camera vertically to the specified position.
233 : * Positive values move the camera up, negative values down. Drivers should interpret the values as
234 : * arc seconds, with valid values between -180 * 3600 and +180 * 3600 inclusive.
235 : */
236 1 : #define VIDEO_CID_TILT_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 9)
237 :
238 : /** This control sets the focal point of the camera to the specified position.
239 : * The unit is undefined. Positive values set the focus closer to the camera, negative values
240 : * towards infinity.
241 : */
242 1 : #define VIDEO_CID_FOCUS_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 10)
243 :
244 : /** This write-only control moves the focal point of the camera by the specified amount.
245 : * The unit is undefined. Positive values move the focus closer to the camera, negative values
246 : * towards infinity.
247 : */
248 1 : #define VIDEO_CID_FOCUS_RELATIVE (VIDEO_CID_CAMERA_CLASS_BASE + 11)
249 :
250 : /** Enables continuous automatic focus adjustments.
251 : * Manual focus adjustments while this control is on (set to 1) is undefined.
252 : * Drivers should ignore such requests.
253 : */
254 1 : #define VIDEO_CID_FOCUS_AUTO (VIDEO_CID_CAMERA_CLASS_BASE + 12)
255 :
256 : /** Specify the objective lens focal length as an absolute value.
257 : * The zoom unit is driver-specific and its value should be a positive integer.
258 : */
259 1 : #define VIDEO_CID_ZOOM_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 13)
260 :
261 : /** This write-only control sets the objective lens focal length relatively to the current value.
262 : * Positive values move the zoom lens group towards the telephoto direction, negative values
263 : * towards the wide-angle direction. The zoom unit is driver-specific.
264 : */
265 1 : #define VIDEO_CID_ZOOM_RELATIVE (VIDEO_CID_CAMERA_CLASS_BASE + 14)
266 :
267 : /** Start a continuous zoom movement.
268 : * Move the objective lens group at the specified speed until it reaches physical device limits or
269 : * until an explicit request to stop the movement. A positive value moves the zoom lens group
270 : * towards the telephoto direction. A value of zero stops the zoom lens group movement.
271 : * A negative value moves the zoom lens group towards the wide-angle direction.
272 : * The zoom speed unit is driver-specific.
273 : */
274 1 : #define VIDEO_CID_ZOOM_CONTINUOUS (VIDEO_CID_CAMERA_CLASS_BASE + 15)
275 :
276 : /** This control sets the camera's aperture to the specified value.
277 : * The unit is undefined. Larger values open the iris wider, smaller values close it.
278 : */
279 1 : #define VIDEO_CID_IRIS_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 17)
280 :
281 : /** This write-only control modifies the camera's aperture by the specified amount.
282 : * The unit is undefined. Positive values open the iris one step further, negative values close
283 : * it one step further.
284 : */
285 1 : #define VIDEO_CID_IRIS_RELATIVE (VIDEO_CID_CAMERA_CLASS_BASE + 18)
286 :
287 : /** Enables or disables the camera's wide dynamic range feature.
288 : * This feature allows to obtain clear images in situations where intensity of the illumination
289 : * varies significantly throughout the scene, i.e. there are simultaneously very dark and very
290 : * bright areas. It is most commonly realized in cameras by combining two subsequent frames with
291 : * different exposure times.
292 : */
293 1 : #define VIDEO_CID_WIDE_DYNAMIC_RANGE (VIDEO_CID_CAMERA_CLASS_BASE + 21)
294 :
295 : /**This control turns the camera horizontally at the specific speed.
296 : * The unit is undefined. A positive value moves the camera to the right (clockwise when viewed
297 : * from above), a negative value to the left. A value of zero stops the motion if one is in
298 : * progress and has no effect otherwise.
299 : */
300 1 : #define VIDEO_CID_PAN_SPEED (VIDEO_CID_CAMERA_CLASS_BASE + 32)
301 :
302 : /** This control turns the camera vertically at the specified speed.
303 : * The unit is undefined. A positive value moves the camera up, a negative value down.
304 : * A value of zero stops the motion if one is in progress and has no effect otherwise.
305 : */
306 1 : #define VIDEO_CID_TILT_SPEED (VIDEO_CID_CAMERA_CLASS_BASE + 33)
307 :
308 : /** This read-only control describes the camera position on the device
309 : * It by reports where the camera camera is installed, its mounting position on the device.
310 : * This control is particularly meaningful for devices which have a well defined orientation,
311 : * such as phones, laptops and portable devices since the control is expressed as a position
312 : * relative to the device's intended usage orientation.
313 : * , or , are said to have the
314 : * @ref VIDEO_CAMERA_ORIENTATION_EXTERNAL orientation.
315 : */
316 1 : #define VIDEO_CID_CAMERA_ORIENTATION (VIDEO_CID_CAMERA_CLASS_BASE + 34)
317 :
318 : /**
319 : * @brief Video camera orientation
320 : */
321 1 : enum video_camera_orientation {
322 : /** Camera installed on the user-facing side of a phone/tablet/laptop device */
323 : VIDEO_CAMERA_ORIENTATION_FRONT = 0,
324 : /** Camera installed on the opposite side of the user */
325 : VIDEO_CAMERA_ORIENTATION_BACK = 1,
326 : /** Camera sensors not directly attached to the device or that can move freely */
327 : VIDEO_CAMERA_ORIENTATION_EXTERNAL = 2,
328 : };
329 :
330 : /** This read-only control describes the orientation of the sensor in the device.
331 : * The value is the rotation correction in degrees in the counter-clockwise direction to be
332 : * applied to the captured images once captured to memory to compensate for the camera sensor
333 : * mounting rotation.
334 : */
335 1 : #define VIDEO_CID_CAMERA_SENSOR_ROTATION (VIDEO_CID_CAMERA_CLASS_BASE + 35)
336 :
337 : /**
338 : * @}
339 : */
340 :
341 : /**
342 : * @name Camera Flash class control IDs
343 : * @{
344 : */
345 0 : #define VIDEO_CID_FLASH_CLASS_BASE 0x009c0900
346 :
347 : /**
348 : * @}
349 : */
350 :
351 : /**
352 : * @name JPEG class control IDs
353 : * @{
354 : */
355 0 : #define VIDEO_CID_JPEG_CLASS_BASE 0x009d0900
356 :
357 : /** Quality (Q) factor of the JPEG algorithm, also increasing the data size */
358 1 : #define VIDEO_CID_JPEG_COMPRESSION_QUALITY (VIDEO_CID_JPEG_CLASS_BASE + 3)
359 :
360 : /**
361 : * @}
362 : */
363 :
364 : /**
365 : * @name Image Source class control IDs
366 : * @{
367 : */
368 0 : #define VIDEO_CID_IMAGE_SOURCE_CLASS_BASE 0x009e0900
369 :
370 : /** Analogue gain control. */
371 1 : #define VIDEO_CID_ANALOGUE_GAIN (VIDEO_CID_IMAGE_SOURCE_CLASS_BASE + 3)
372 :
373 : /**
374 : * @}
375 : */
376 :
377 : /**
378 : * @name Image Processing class control IDs
379 : * @{
380 : */
381 0 : #define VIDEO_CID_IMAGE_PROC_CLASS_BASE 0x009f0900
382 :
383 : /** Link frequency, applicable for the CSI2 based devices */
384 1 : #define VIDEO_CID_LINK_FREQ (VIDEO_CID_IMAGE_PROC_CLASS_BASE + 1)
385 :
386 : /** Pixel rate (pixels/second) in the device's pixel array. This control is read-only. */
387 1 : #define VIDEO_CID_PIXEL_RATE (VIDEO_CID_IMAGE_PROC_CLASS_BASE + 2)
388 :
389 : /** Selection of the type of test pattern to represent */
390 1 : #define VIDEO_CID_TEST_PATTERN (VIDEO_CID_IMAGE_PROC_CLASS_BASE + 3)
391 :
392 : /**
393 : * @}
394 : */
395 :
396 : /**
397 : * @name Vendor-specific class control IDs
398 : * @{
399 : */
400 0 : #define VIDEO_CID_PRIVATE_BASE 0x08000000
401 :
402 : /**
403 : * @}
404 : */
405 :
406 : /**
407 : * @name Query flags, to be ORed with the control ID
408 : * @{
409 : */
410 0 : #define VIDEO_CTRL_FLAG_NEXT_CTRL 0x80000000
411 :
412 : /**
413 : * @}
414 : */
415 :
416 : /**
417 : * @name Public video control structures
418 : * @{
419 : */
420 :
421 : /**
422 : * @struct video_control
423 : * @brief Video control structure
424 : *
425 : * Used to get/set a video control.
426 : * @see video_ctrl for the struct used in the driver implementation
427 : */
428 1 : struct video_control {
429 : /** control id */
430 1 : uint32_t id;
431 : /** control value */
432 : union {
433 0 : int32_t val;
434 0 : int64_t val64;
435 1 : };
436 : };
437 :
438 : /**
439 1 : * @struct video_control_range
440 : * @brief Video control range structure
441 : *
442 : * Describe range of a control including min, max, step and default values
443 : */
444 0 : struct video_ctrl_range {
445 : /** control minimum value, inclusive */
446 : union {
447 0 : int32_t min;
448 0 : int64_t min64;
449 1 : };
450 : /** control maximum value, inclusive */
451 : union {
452 0 : int32_t max;
453 0 : int64_t max64;
454 1 : };
455 : /** control value step */
456 : union {
457 0 : int32_t step;
458 0 : int64_t step64;
459 1 : };
460 : /** control default value for VIDEO_CTRL_TYPE_INTEGER, _BOOLEAN, _MENU or
461 : * _INTEGER_MENU, not valid for other types
462 : */
463 : union {
464 0 : int32_t def;
465 0 : int64_t def64;
466 1 : };
467 : };
468 :
469 : /**
470 1 : * @struct video_control_query
471 : * @brief Video control query structure
472 : *
473 : * Used to query information about a control.
474 : */
475 0 : struct video_ctrl_query {
476 : /** device being queried, application needs to set this field */
477 1 : const struct device *dev;
478 : /** control id, application needs to set this field */
479 1 : uint32_t id;
480 : /** control type */
481 1 : uint32_t type;
482 : /** control name */
483 1 : const char *name;
484 : /** control flags */
485 1 : uint32_t flags;
486 : /** control range */
487 1 : struct video_ctrl_range range;
488 : /** menu if control is of menu type */
489 : union {
490 0 : const char *const *menu;
491 0 : const int64_t *int_menu;
492 1 : };
493 : };
494 :
495 : /**
496 : * @}
497 : */
498 :
499 : #ifdef __cplusplus
500 : }
501 : #endif
502 :
503 : /**
504 : * @}
505 : */
506 :
507 : #endif /* ZEPHYR_INCLUDE_VIDEO_H_ */
|
