From ab35f973a040ef7e07fdf664682893c62ed46d34 Mon Sep 17 00:00:00 2001 From: Josuah Demangeon Date: Tue, 22 Apr 2025 20:31:37 +0000 Subject: [PATCH] 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 --- drivers/video/video_ctrls.c | 102 ++++++++++- include/zephyr/drivers/video-controls.h | 215 +++++++++++++++++++++++- 2 files changed, 301 insertions(+), 16 deletions(-) diff --git a/drivers/video/video_ctrls.c b/drivers/video/video_ctrls.c index 25906f13c31c6..e24fff6b45e0b 100644 --- a/drivers/video/video_ctrls.c +++ b/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: diff --git a/include/zephyr/drivers/video-controls.h b/include/zephyr/drivers/video-controls.h index 4304316c18189..79141eb430d8a 100644 --- a/include/zephyr/drivers/video-controls.h +++ b/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) + /** * @} */