drivers: video: controls: add the BASE and CAMERA controls

Add all the base controls present like they are in Linux into Zephyr,
limited to those that can apply in the current system:
- Buttons are left as integer for now.
- Some description is modified to fit the Zephyr situation.
- For the minimum number of buffer, Zephyr uses a different mechanism.
- No audio support through the video subsystem.
- Homogenize the wording

Signed-off-by: Josuah Demangeon <me@josuah.net>

Author: josuah

drivers/video/video_ctrls.c

@@ -17,17 +17,33 @@ LOG_MODULE_REGISTER(video_ctrls, CONFIG_VIDEO_LOG_LEVEL);
 
 static inline const char *const *video_get_std_menu_ctrl(uint32_t id)
 {
-	static const char *const camera_power_line_frequency[] = {"Disabled", "50 Hz", "60 Hz",
-								  "Auto", NULL};
-	static const char *const camera_exposure_auto[] = {"Auto Mode", "Manual Mode",
-							   "Shutter Priority Mode",
-							   "Aperture Priority Mode", NULL};
+	static char const *const power_line_frequency[] = {
+		"Disabled", "50 Hz", "60 Hz", "Auto", NULL,
+	};
+	static char const *const exposure_auto[] = {
+		"Auto Mode", "Manual Mode", "Shutter Priority Mode", "Aperture Priority Mode", NULL,
+	};
+	static char const *const colorfx[] = {
+		"None", "Black & White", "Sepia", "Negative", "Emboss", "Sketch", "Sky Blue",
+		"Grass Green", "Skin Whiten", "Vivid", "Aqua", "Art Freeze", "Silhouette",
+		"Solarization", "Antique", "Set Cb/Cr", NULL,
+	};
+	static char const *const camera_orientation[] = {
+		"Front", "Back", "External", NULL,
+	};
 
 	switch (id) {
+	/* User control menus */
 	case VIDEO_CID_POWER_LINE_FREQUENCY:
-		return camera_power_line_frequency;
+		return power_line_frequency;
+
+	/* Camera control menus */
 	case VIDEO_CID_EXPOSURE_AUTO:
-		return camera_exposure_auto;
+		return exposure_auto;
+	case VIDEO_CID_COLORFX:
+		return colorfx;
+	case VIDEO_CID_CAMERA_ORIENTATION:
+		return camera_orientation;
 	default:
 		return NULL;
 	}
@@ -69,12 +85,22 @@ static inline void set_type_flag(uint32_t id, enum video_ctrl_type *type, uint32
 	*flags = 0;
 
 	switch (id) {
+	case VIDEO_CID_AUTO_WHITE_BALANCE:
+	case VIDEO_CID_AUTOGAIN:
 	case VIDEO_CID_HFLIP:
 	case VIDEO_CID_VFLIP:
+	case VIDEO_CID_HUE_AUTO:
+	case VIDEO_CID_AUTOBRIGHTNESS:
+	case VIDEO_CID_EXPOSURE_AUTO_PRIORITY:
+	case VIDEO_CID_FOCUS_AUTO:
+	case VIDEO_CID_WIDE_DYNAMIC_RANGE:
 		*type = VIDEO_CTRL_TYPE_BOOLEAN;
 		break;
 	case VIDEO_CID_POWER_LINE_FREQUENCY:
+	case VIDEO_CID_EXPOSURE_AUTO:
+	case VIDEO_CID_COLORFX:
 	case VIDEO_CID_TEST_PATTERN:
+	case VIDEO_CID_CAMERA_ORIENTATION:
 		*type = VIDEO_CTRL_TYPE_MENU;
 		break;
 	case VIDEO_CID_PIXEL_RATE:
@@ -388,6 +414,14 @@ static inline const char *video_get_ctrl_name(uint32_t id)
 		return "Saturation";
 	case VIDEO_CID_HUE:
 		return "Hue";
+	case VIDEO_CID_AUTO_WHITE_BALANCE:
+		return "White Balance, Automatic";
+	case VIDEO_CID_RED_BALANCE:
+		return "Red Balance";
+	case VIDEO_CID_BLUE_BALANCE:
+		return "Blue Balance";
+	case VIDEO_CID_GAMMA:
+		return "Gamma";
 	case VIDEO_CID_EXPOSURE:
 		return "Exposure";
 	case VIDEO_CID_AUTOGAIN:
@@ -402,10 +436,64 @@ static inline const char *video_get_ctrl_name(uint32_t id)
 		return "Vertical Flip";
 	case VIDEO_CID_POWER_LINE_FREQUENCY:
 		return "Power Line Frequency";
+	case VIDEO_CID_HUE_AUTO:
+		return "Hue, Automatic";
+	case VIDEO_CID_WHITE_BALANCE_TEMPERATURE:
+		return "White Balance Temperature";
+	case VIDEO_CID_SHARPNESS:
+		return "Sharpness";
+	case VIDEO_CID_BACKLIGHT_COMPENSATION:
+		return "Backlight Compensation";
+	case VIDEO_CID_COLORFX:
+		return "Color Effects";
+	case VIDEO_CID_AUTOBRIGHTNESS:
+		return "Brightness, Automatic";
+	case VIDEO_CID_BAND_STOP_FILTER:
+		return "Band-Stop Filter";
+	case VIDEO_CID_ALPHA_COMPONENT:
+		return "Alpha Component";
 
 	/* Camera controls */
+	case VIDEO_CID_EXPOSURE_AUTO:
+		return "Auto Exposure";
+	case VIDEO_CID_EXPOSURE_ABSOLUTE:
+		return "Exposure Time, Absolute";
+	case VIDEO_CID_EXPOSURE_AUTO_PRIORITY:
+		return "Exposure, Dynamic Framerate";
+	case VIDEO_CID_PAN_RELATIVE:
+		return "Pan, Relative";
+	case VIDEO_CID_TILT_RELATIVE:
+		return "Tilt, Reset";
+	case VIDEO_CID_PAN_ABSOLUTE:
+		return "Pan, Absolute";
+	case VIDEO_CID_TILT_ABSOLUTE:
+		return "Tilt, Absolute";
+	case VIDEO_CID_FOCUS_ABSOLUTE:
+		return "Focus, Absolute";
+	case VIDEO_CID_FOCUS_RELATIVE:
+		return "Focus, Relative";
+	case VIDEO_CID_FOCUS_AUTO:
+		return "Focus, Automatic Continuous";
 	case VIDEO_CID_ZOOM_ABSOLUTE:
 		return "Zoom, Absolute";
+	case VIDEO_CID_ZOOM_RELATIVE:
+		return "Zoom, Relative";
+	case VIDEO_CID_ZOOM_CONTINUOUS:
+		return "Zoom, Continuous";
+	case VIDEO_CID_IRIS_ABSOLUTE:
+		return "Iris, Absolute";
+	case VIDEO_CID_IRIS_RELATIVE:
+		return "Iris, Relative";
+	case VIDEO_CID_WIDE_DYNAMIC_RANGE:
+		return "Wide Dynamic Range";
+	case VIDEO_CID_PAN_SPEED:
+		return "Pan, Speed";
+	case VIDEO_CID_TILT_SPEED:
+		return "Tilt, Speed";
+	case VIDEO_CID_CAMERA_ORIENTATION:
+		return "Camera Orientation";
+	case VIDEO_CID_CAMERA_SENSOR_ROTATION:
+		return "Camera Sensor Rotation";
 
 	/* JPEG encoder controls */
 	case VIDEO_CID_JPEG_COMPRESSION_QUALITY:

include/zephyr/drivers/video-controls.h

@@ -42,19 +42,31 @@ extern "C" {
  */
 #define VIDEO_CID_BASE 0x00980900
 
-/** Amount of perceived light of the image, the luma (Y') value. */
+/** Picture brightness, or more precisely, the black level. */
 #define VIDEO_CID_BRIGHTNESS (VIDEO_CID_BASE + 0)
 
-/** Amount of difference between the bright colors and dark colors. */
+/** Picture contrast or luma gain. */
 #define VIDEO_CID_CONTRAST (VIDEO_CID_BASE + 1)
 
-/** Colorfulness of the image while preserving its brightness */
+/** Picture color saturation or chroma gain. */
 #define VIDEO_CID_SATURATION (VIDEO_CID_BASE + 2)
 
-/** Shift in the tint of every colors, clockwise in a RGB color wheel */
+/** Hue or color balance. */
 #define VIDEO_CID_HUE (VIDEO_CID_BASE + 3)
 
-/** Amount of time an image sensor is exposed to light, affecting the brightness */
+/** Automatic white balance (cameras). */
+#define VIDEO_CID_AUTO_WHITE_BALANCE (VIDEO_CID_BASE + 12)
+
+/** Red chroma balance, as a ratio to the green channel. */
+#define VIDEO_CID_RED_BALANCE (VIDEO_CID_BASE + 14)
+
+/** Blue chroma balance, as a ratio to the green channel. */
+#define VIDEO_CID_BLUE_BALANCE (VIDEO_CID_BASE + 15)
+
+/** Gamma adjust. */
+#define VIDEO_CID_GAMMA (VIDEO_CID_BASE + 16)
+
+/** Image sensor exposure time. */
 #define VIDEO_CID_EXPOSURE (VIDEO_CID_BASE + 17)
 
 /** Automatic gain control */
@@ -81,9 +93,61 @@ enum video_power_line_frequency {
 	VIDEO_CID_POWER_LINE_FREQUENCY_AUTO = 3,
 };
 
-/** Balance of colors in direction of blue (cold) or red (warm) */
+/** Enables automatic hue control by the device.
+ * Setting @ref VIDEO_CID_HUE while automatic hue control is enabled is undefined.
+ * Drivers should ignore such request.
+ */
+#define VIDEO_CID_HUE_AUTO (VIDEO_CID_BASE + 25)
+
+/** White balance settings as a color temperature in Kelvin.
+ * A driver should have a minimum range of 2800 (incandescent) to 6500 (daylight).
+ */
 #define VIDEO_CID_WHITE_BALANCE_TEMPERATURE (VIDEO_CID_BASE + 26)
 
+/** Adjusts the sharpness filters in a camera.
+ * The minimum value disables the filters, higher values give a sharper picture.
+ */
+#define VIDEO_CID_SHARPNESS (VIDEO_CID_BASE + 27)
+
+/** Adjusts the backlight compensation in a camera.
+ * The minimum value disables backlight compensation.
+ */
+#define VIDEO_CID_BACKLIGHT_COMPENSATION (VIDEO_CID_BASE + 28)
+
+/** Selects a color effect. */
+#define VIDEO_CID_COLORFX (VIDEO_CID_BASE + 31)
+enum video_colorfx {
+	VIDEO_COLORFX_NONE = 0,
+	VIDEO_COLORFX_BW = 1,
+	VIDEO_COLORFX_SEPIA = 2,
+	VIDEO_COLORFX_NEGATIVE = 3,
+	VIDEO_COLORFX_EMBOSS = 4,
+	VIDEO_COLORFX_SKETCH = 5,
+	VIDEO_COLORFX_SKY_BLUE = 6,
+	VIDEO_COLORFX_GRASS_GREEN = 7,
+	VIDEO_COLORFX_SKIN_WHITEN = 8,
+	VIDEO_COLORFX_VIVID = 9,
+	VIDEO_COLORFX_AQUA = 10,
+	VIDEO_COLORFX_ART_FREEZE = 11,
+	VIDEO_COLORFX_SILHOUETTE = 12,
+	VIDEO_COLORFX_SOLARIZATION = 13,
+	VIDEO_COLORFX_ANTIQUE = 14,
+};
+
+/* Enable Automatic Brightness. */
+#define VIDEO_CID_AUTOBRIGHTNESS (VIDEO_CID_BASE + 32)
+
+/** Switch the band-stop filter of a camera sensor on or off, or specify its strength.
+ * Such band-stop filters can be used, for example, to filter out the fluorescent light component.
+ */
+#define VIDEO_CID_BAND_STOP_FILTER (VIDEO_CID_BASE + 33)
+
+/** Sets the alpha color component.
+ * Some devices produce data with a user-controllable alpha component. Set the value applied to
+ * the alpha channel of every pixel produced.
+ */
+#define VIDEO_CID_ALPHA_COMPONENT (VIDEO_CID_BASE + 41)
+
 /** Last base CID + 1 */
 #define VIDEO_CID_LASTP1 (VIDEO_CID_BASE + 44)
 
@@ -107,18 +171,151 @@ enum video_power_line_frequency {
  */
 #define VIDEO_CID_CAMERA_CLASS_BASE 0x009a0900
 
-/** Adjustments of exposure time and/or iris aperture. */
+/** Enables automatic adjustments of the exposure time and/or iris aperture.
+ * Manual exposure or iris changes when it is not @ref VIDEO_EXPOSURE_MANUAL is undefined.
+ * Drivers should ignore such requests.
+ */
 #define VIDEO_CID_EXPOSURE_AUTO (VIDEO_CID_CAMERA_CLASS_BASE + 1)
-enum video_exposure_auto_type {
+enum video_exposure_type {
 	VIDEO_EXPOSURE_AUTO = 0,
 	VIDEO_EXPOSURE_MANUAL = 1,
 	VIDEO_EXPOSURE_SHUTTER_PRIORITY = 2,
 	VIDEO_EXPOSURE_APERTURE_PRIORITY = 3
 };
 
-/** Amount of optical zoom applied through to the camera optics */
+/** Determines the exposure time of the camera sensor.
+ * The exposure time is limited by the frame in terval. Drivers should interpret the values as
+ * 100 µs units, where the value 1 stands for 1/10000th of a second, 10000 for 1 second and 100000
+ * for 10 seconds.
+ */
+#define VIDEO_CID_EXPOSURE_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 2)
+
+/** Whether the device may dynamically vary the frame rate under the effect of auto-exposure
+ * Applicable when @ref VIDEO_CID_EXPOSURE_AUTO is set to @ref VIDEO_EXPOSURE_AUTO or
+ * @ref VIDEO_EXPOSURE_APERTURE_PRIORITY. Disabled by default: the frame rate must remain constant.
+ */
+#define VIDEO_CID_EXPOSURE_AUTO_PRIORITY (VIDEO_CID_CAMERA_CLASS_BASE + 3)
+
+/** This write-only control turns the camera horizontally by the specified amount.
+ * The unit is undefined. A positive value moves the camera to the right (clockwise when viewed
+ * from above), a negative value to the left. A value of zero does not cause motion.
+ */
+#define VIDEO_CID_PAN_RELATIVE (VIDEO_CID_CAMERA_CLASS_BASE + 4)
+
+/** This write-only control turns the camera vertically by the specified amount.
+ * The unit is undefined. A positive value moves the camera up, a negative value down.
+ * A value of zero does not cause motion.
+ */
+#define VIDEO_CID_TILT_RELATIVE (VIDEO_CID_CAMERA_CLASS_BASE + 5)
+
+/** This control turns the camera horizontally to the specified position.
+ * Positive values move the camera to the right (clockwise when viewed from above), negative
+ * values to the left. Drivers should interpret the values as arc seconds, with valid values
+ * between -180 * 3600 and +180 * 3600 inclusive.
+ */
+#define VIDEO_CID_PAN_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 8)
+
+/** This control turns the camera vertically to the specified position.
+ * Positive values move the camera up, negative values down. Drivers should interpret the values as
+ * arc seconds, with valid values between -180 * 3600 and +180 * 3600 inclusive.
+ */
+#define VIDEO_CID_TILT_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 9)
+
+/** This control sets the focal point of the camera to the specified position.
+ * The unit is undefined. Positive values set the focus closer to the camera, negative values
+ * towards infinity.
+ */
+#define VIDEO_CID_FOCUS_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 10)
+
+/** This write-only control moves the focal point of the camera by the specified amount.
+ * The unit is undefined. Positive values move the focus closer to the camera, negative values
+ * towards infinity.
+ */
+#define VIDEO_CID_FOCUS_RELATIVE (VIDEO_CID_CAMERA_CLASS_BASE + 11)
+
+/** Enables continuous automatic focus adjustments.
+ * Manual focus adjustments while this control is on (set to 1) is undefined.
+ * Drivers should ignore such requests.
+ */
+#define VIDEO_CID_FOCUS_AUTO (VIDEO_CID_CAMERA_CLASS_BASE + 12)
+
+/** Specify the objective lens focal length as an absolute value.
+ * The zoom unit is driver-specific and its value should be a positive integer.
+ */
 #define VIDEO_CID_ZOOM_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 13)
 
+/** This write-only control sets the objective lens focal length relatively to the current value.
+ * Positive values move the zoom lens group towards the telephoto direction, negative values
+ * towards the wide-angle direction. The zoom unit is driver-specific.
+ */
+#define VIDEO_CID_ZOOM_RELATIVE (VIDEO_CID_CAMERA_CLASS_BASE + 14)
+
+/** Start a continuous zoom movement.
+ * Move the objective lens group at the specified speed until it reaches physical device limits or
+ * until an explicit request to stop the movement. A positive value moves the zoom lens group
+ * towards the telephoto direction. A value of zero stops the zoom lens group movement.
+ * A negative value moves the zoom lens group towards the wide-angle direction.
+ * The zoom speed unit is driver-specific.
+ */
+#define VIDEO_CID_ZOOM_CONTINUOUS (VIDEO_CID_CAMERA_CLASS_BASE + 15)
+
+/** This control sets the camera's aperture to the specified value.
+ * The unit is undefined. Larger values open the iris wider, smaller values close it.
+ */
+#define VIDEO_CID_IRIS_ABSOLUTE (VIDEO_CID_CAMERA_CLASS_BASE + 17)
+
+/** This write-only control modifies the camera's aperture by the specified amount.
+ * The unit is undefined. Positive values open the iris one step further, negative values close
+ * it one step further.
+ */
+#define VIDEO_CID_IRIS_RELATIVE (VIDEO_CID_CAMERA_CLASS_BASE + 18)
+
+/** Enables or disables the camera's wide dynamic range feature.
+ * This feature allows to obtain clear images in situations where intensity of the illumination
+ * varies significantly throughout the scene, i.e. there are simultaneously very dark and very
+ * bright areas. It is most commonly realized in cameras by combining two subsequent frames with
+ * different exposure times.
+ */
+#define VIDEO_CID_WIDE_DYNAMIC_RANGE (VIDEO_CID_CAMERA_CLASS_BASE + 21)
+
+/**This control turns the camera horizontally at the specific speed.
+ * The unit is undefined. A positive value moves the camera to the right (clockwise when viewed
+ * from above), a negative value to the left. A value of zero stops the motion if one is in
+ * progress and has no effect otherwise.
+ */
+#define VIDEO_CID_PAN_SPEED (VIDEO_CID_CAMERA_CLASS_BASE + 32)
+
+/** This control turns the camera vertically at the specified speed.
+ * The unit is undefined. A positive value moves the camera up, a negative value down.
+ * A value of zero stops the motion if one is in progress and has no effect otherwise.
+ */
+#define VIDEO_CID_TILT_SPEED (VIDEO_CID_CAMERA_CLASS_BASE + 33)
+
+/** This read-only control describes the camera position on the device
+ * It by reports where the camera camera is installed, its mounting position on the device.
+ * This control is particularly meaningful for devices which have a well defined orientation,
+ * such as phones, laptops and portable devices since the control is expressed as a position
+ * relative to the device's intended usage orientation.
+ * , or , are said to have the
+ * @ref VIDEO_CAMERA_ORIENTATION_EXTERNAL orientation.
+ */
+#define VIDEO_CID_CAMERA_ORIENTATION (VIDEO_CID_CAMERA_CLASS_BASE + 34)
+enum video_camera_orientation {
+	/** Camera installed on the user-facing side of a phone/tablet/laptop device */
+	VIDEO_CAMERA_ORIENTATION_FRONT = 0,
+	/** Camera installed on the opposite side of the user */
+	VIDEO_CAMERA_ORIENTATION_BACK = 1,
+	/** Camera sensors not directly attached to the device or that can move freely */
+	VIDEO_CAMERA_ORIENTATION_EXTERNAL = 2,
+};
+
+/** This read-only control describes the orientation of the sensor in the device.
+ * The value is the rotation correction in degrees in the counter-clockwise direction to be
+ * applied to the captured images once captured to memory to compensate for the camera sensor
+ * mounting rotation.
+ */
+#define VIDEO_CID_CAMERA_SENSOR_ROTATION (VIDEO_CID_CAMERA_CLASS_BASE + 35)
+
 /**
  * @}
  */