Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 16, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 95 additions & 7 deletions drivers/video/video_ctrls.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand All @@ -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:
Expand Down
215 changes: 206 additions & 9 deletions include/zephyr/drivers/video-controls.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Expand All @@ -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)

Expand All @@ -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)

/**
* @}
*/
Expand Down