drivers: video: controls: document each control and move classes

Make controls more readable and intuitive to extend, with definition
of each control value to help disambiguate between similar controls,
such as BRIGHTNESS vs GAIN.

Move the class definition to the top of each relevant class, like it
is on Linux for the V4L2_CID_..._CLASS_BASE variables.

Signed-off-by: Josuah Demangeon <[email protected]>

Author: josuah

include/zephyr/drivers/video-controls.h

@@ -23,55 +23,68 @@
  * inter-operability and debugging devices end-to-end across Linux and
  * Zephyr.
  *
+ * This list is maintained compatible to the Linux kernel definitions in
+ * @c linux/include/uapi/linux/v4l2-controls.h
+ *
  * @{
  */
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/**
- * @name Control classes
- *
- * List of control classes, to group related controls together in blocks.
- *
- * This list is kept identical to the Linux kernel definitions.
- *
- * @{
- */
-#define VIDEO_CID_BASE				0x00980900 /**< Base class controls */
-#define VIDEO_CID_CODEC_CLASS_BASE		0x00990900 /**< Stateful codec controls */
-#define VIDEO_CID_CAMERA_CLASS_BASE		0x009a0900 /**< Camera class controls */
-#define VIDEO_CID_FLASH_CLASS_BASE		0x009c0900 /**< Camera flash controls */
-#define VIDEO_CID_JPEG_CLASS_BASE		0x009d0900 /**< JPEG-compression controls */
-#define VIDEO_CID_IMAGE_SOURCE_CLASS_BASE	0x009e0900 /**< Image source controls */
-#define VIDEO_CID_IMAGE_PROC_CLASS_BASE		0x009f0900 /**< Image processing controls */
-#define VIDEO_CID_PRIVATE_BASE			0x08000000 /**< Vendor-specific class controls */
-/**
- * @}
- */
-
 /**
  * @name Base class control IDs
  * @{
  */
-#define VIDEO_CID_BRIGHTNESS			(VIDEO_CID_BASE + 0)
-#define VIDEO_CID_CONTRAST			(VIDEO_CID_BASE + 1)
-#define VIDEO_CID_SATURATION			(VIDEO_CID_BASE + 2)
-#define VIDEO_CID_HUE				(VIDEO_CID_BASE + 3)
-#define VIDEO_CID_EXPOSURE			(VIDEO_CID_BASE + 17)
-#define VIDEO_CID_GAIN				(VIDEO_CID_BASE + 19)
-#define VIDEO_CID_HFLIP				(VIDEO_CID_BASE + 20)
-#define VIDEO_CID_VFLIP				(VIDEO_CID_BASE + 21)
-/** Power line frequency (enum) filter to avoid flicker */
-#define VIDEO_CID_POWER_LINE_FREQUENCY		(VIDEO_CID_BASE + 24)
+#define VIDEO_CID_BASE 0x00980900
+
+/** Amount of perceived light of the image, the luma (Y') value. */
+#define VIDEO_CID_BRIGHTNESS (VIDEO_CID_BASE + 0)
+
+/** Amount of difference between the bright colors and dark colors. */
+#define VIDEO_CID_CONTRAST (VIDEO_CID_BASE + 1)
+
+/** Colorfulness of the image while preserving its brightness */
+#define VIDEO_CID_SATURATION (VIDEO_CID_BASE + 2)
+
+/** Shift in the tint of every colors, clockwise in a RGB color wheel */
+#define VIDEO_CID_HUE (VIDEO_CID_BASE + 3)
+
+/** Amount of time an image sensor is exposed to light, affecting the brightness */
+#define VIDEO_CID_EXPOSURE (VIDEO_CID_BASE + 17)
+
+/** Amount of amplification performed to each pixel electrical signal, affecting the brightness */
+#define VIDEO_CID_GAIN (VIDEO_CID_BASE + 19)
+
+/** Flip the image horizontally: the left side becomes the right side */
+#define VIDEO_CID_HFLIP (VIDEO_CID_BASE + 20)
+
+/** Flip the image vertically: the top side becomes the bottom side */
+#define VIDEO_CID_VFLIP (VIDEO_CID_BASE + 21)
+
+/** Frequency of the power line to compensate for, avoiding flicker due to artificial lighting */
+#define VIDEO_CID_POWER_LINE_FREQUENCY (VIDEO_CID_BASE + 24)
 enum video_power_line_frequency {
 	VIDEO_CID_POWER_LINE_FREQUENCY_DISABLED = 0,
 	VIDEO_CID_POWER_LINE_FREQUENCY_50HZ = 1,
 	VIDEO_CID_POWER_LINE_FREQUENCY_60HZ = 2,
 	VIDEO_CID_POWER_LINE_FREQUENCY_AUTO = 3,
 };
-#define VIDEO_CID_WHITE_BALANCE_TEMPERATURE	(VIDEO_CID_BASE + 26)
+
+/** Balance of colors in direction of blue (cold) or red (warm) */
+#define VIDEO_CID_WHITE_BALANCE_TEMPERATURE (VIDEO_CID_BASE + 26)
+
+/**
+ * @}
+ */
+
+/**
+ * @name Stateful codec controls IDs
+ * @{
+ */
+#define VIDEO_CID_CODEC_CLASS_BASE 0x00990900
+
 /**
  * @}
  */
@@ -80,7 +93,21 @@ enum video_power_line_frequency {
  * @name Camera class controls IDs
  * @{
  */
-#define VIDEO_CID_ZOOM_ABSOLUTE			(VIDEO_CID_CAMERA_CLASS_BASE + 13)
+#define VIDEO_CID_CAMERA_CLASS_BASE 0x009a0900
+
+/** Amount of optical zoom applied through to the camera optics */
+#define VIDEO_CID_ZOOM_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 13)
+
+/**
+ * @}
+ */
+
+/**
+ * @name Camera Flash class control IDs
+ * @{
+ */
+#define VIDEO_CID_FLASH_CLASS_BASE 0x009c0900
+
 /**
  * @}
  */
@@ -89,7 +116,21 @@ enum video_power_line_frequency {
  * @name JPEG class control IDs
  * @{
  */
-#define VIDEO_CID_JPEG_COMPRESSION_QUALITY	(VIDEO_CID_JPEG_CLASS_BASE + 3)
+#define VIDEO_CID_JPEG_CLASS_BASE 0x009d0900
+
+/** Quality (Q) factor of the JPEG algorithm, also increasing the data size */
+#define VIDEO_CID_JPEG_COMPRESSION_QUALITY (VIDEO_CID_JPEG_CLASS_BASE + 3)
+
+/**
+ * @}
+ */
+
+/**
+ * @name Image Source class control IDs
+ * @{
+ */
+#define VIDEO_CID_IMAGE_SOURCE_CLASS_BASE 0x009e0900
+
 /**
  * @}
  */
@@ -98,9 +139,24 @@ enum video_power_line_frequency {
  * @name Image Processing class control IDs
  * @{
  */
+#define VIDEO_CID_IMAGE_PROC_CLASS_BASE 0x009f0900
+
 /** Pixel rate (pixels/second) in the device's pixel array. This control is read-only. */
-#define VIDEO_CID_PIXEL_RATE			(VIDEO_CID_IMAGE_PROC_CLASS_BASE + 2)
-#define VIDEO_CID_TEST_PATTERN			(VIDEO_CID_IMAGE_PROC_CLASS_BASE + 3)
+#define VIDEO_CID_PIXEL_RATE (VIDEO_CID_IMAGE_PROC_CLASS_BASE + 2)
+
+/** Selection of the type of test pattern to represent */
+#define VIDEO_CID_TEST_PATTERN (VIDEO_CID_IMAGE_PROC_CLASS_BASE + 3)
+
+/**
+ * @}
+ */
+
+/**
+ * @name Vendor-specific class control IDs
+ * @{
+ */
+#define VIDEO_CID_PRIVATE_BASE 0x08000000
+
 /**
  * @}
  */