michaelh/zephyr
1
0
Fork 0
Code Releases Activity
zephyr/include/zephyr/drivers/video-controls.h
Phi Bang Nguyen 10deca2ef6 drivers: video: Fix skipped CIDs when enumerating controls 
When enumerating controls with VIDEO_CTRL_FLAG_NEXT_CTRL, if child devices
have controls with IDs lower or equal to the ones in the parent devices,
those controls will be accidentally skipped.

Fix this by resetting the query's ID and tracking of the queried device in
the query when moving to the next device in the pipeline.

Signed-off-by: Phi Bang Nguyen <phibang.nguyen@nxp.com>
Signed-off-by: Josuah Demangeon <me@josuah.net>
2025-06-19 22:37:54 -07:00

489 lines
15 KiB
C
Raw Permalink Blame History

/*
* Copyright (c) 2019 Linaro Limited.
* Copyright (c) 2024 tinyVision.ai Inc.
* Copyright 2025 NXP
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ZEPHYR_INCLUDE_VIDEO_CONTROLS_H_
#define ZEPHYR_INCLUDE_VIDEO_CONTROLS_H_
/**
* @file
*
* @brief Public APIs for Video.
*/
/**
* @brief Video controls
* @defgroup video_controls Video Controls
* @ingroup io_interfaces
*
* The Video control IDs (CIDs) are introduced with the same name as
* Linux V4L2 subsystem and under the same class. This facilitates
* 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
*
* @{
*/
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @name Base class control IDs
* @{
*/
#define VIDEO_CID_BASE 0x00980900
/** Picture brightness, or more precisely, the black level. */
#define VIDEO_CID_BRIGHTNESS (VIDEO_CID_BASE + 0)
/** Picture contrast or luma gain. */
#define VIDEO_CID_CONTRAST (VIDEO_CID_BASE + 1)
/** Picture color saturation or chroma gain. */
#define VIDEO_CID_SATURATION (VIDEO_CID_BASE + 2)
/** Hue or color balance. */
#define VIDEO_CID_HUE (VIDEO_CID_BASE + 3)
/** 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 */
#define VIDEO_CID_AUTOGAIN (VIDEO_CID_BASE + 18)
/** Gain control. Most devices control only digital gain with this control.
* Devices that recognise the difference between digital and analogue gain use
* VIDEO_CID_DIGITAL_GAIN and VIDEO_CID_ANALOGUE_GAIN.
*/
#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,
};
/** 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)
/**
* @}
*/
/**
* @name Stateful codec controls IDs
* @{
*/
#define VIDEO_CID_CODEC_CLASS_BASE 0x00990900
/**
* @}
*/
/**
* @name Camera class controls IDs
* @{
*/
#define VIDEO_CID_CAMERA_CLASS_BASE 0x009a0900
/** 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_type {
VIDEO_EXPOSURE_AUTO = 0,
VIDEO_EXPOSURE_MANUAL = 1,
VIDEO_EXPOSURE_SHUTTER_PRIORITY = 2,
VIDEO_EXPOSURE_APERTURE_PRIORITY = 3
};
/** 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)
/**
* @}
*/
/**
* @name Camera Flash class control IDs
* @{
*/
#define VIDEO_CID_FLASH_CLASS_BASE 0x009c0900
/**
* @}
*/
/**
* @name JPEG class control IDs
* @{
*/
#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
/** Analogue gain control. */
#define VIDEO_CID_ANALOGUE_GAIN (VIDEO_CID_IMAGE_SOURCE_CLASS_BASE + 3)
/**
* @}
*/
/**
* @name Image Processing class control IDs
* @{
*/
#define VIDEO_CID_IMAGE_PROC_CLASS_BASE 0x009f0900
/** Link frequency, applicable for the CSI2 based devices */
#define VIDEO_CID_LINK_FREQ (VIDEO_CID_IMAGE_PROC_CLASS_BASE + 1)
/** 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)
/** 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
/**
* @}
*/
/**
* @name Query flags, to be ORed with the control ID
* @{
*/
#define VIDEO_CTRL_FLAG_NEXT_CTRL 0x80000000
/**
* @}
*/
/**
* @name Public video control structures
* @{
*/
/**
* @struct video_control
* @brief Video control structure
*
* Used to get/set a video control.
* @see video_ctrl for the struct used in the driver implementation
*/
struct video_control {
/** control id */
uint32_t id;
/** control value */
union {
int32_t val;
int64_t val64;
};
};
/**
* @struct video_control_range
* @brief Video control range structure
*
* Describe range of a control including min, max, step and default values
*/
struct video_ctrl_range {
/** control minimum value, inclusive */
union {
int32_t min;
int64_t min64;
};
/** control maximum value, inclusive */
union {
int32_t max;
int64_t max64;
};
/** control value step */
union {
int32_t step;
int64_t step64;
};
/** control default value for VIDEO_CTRL_TYPE_INTEGER, _BOOLEAN, _MENU or
* _INTEGER_MENU, not valid for other types
*/
union {
int32_t def;
int64_t def64;
};
};
/**
* @struct video_control_query
* @brief Video control query structure
*
* Used to query information about a control.
*/
struct video_ctrl_query {
/** device being queried, application needs to set this field */
const struct device *dev;
/** control id, application needs to set this field */
uint32_t id;
/** control type */
uint32_t type;
/** control name */
const char *name;
/** control flags */
uint32_t flags;
/** control range */
struct video_ctrl_range range;
/** menu if control is of menu type */
union {
const char *const *menu;
const int64_t *int_menu;
};
};
/**
* @}
*/
#ifdef __cplusplus
}
#endif
/**
* @}
*/
#endif /* ZEPHYR_INCLUDE_VIDEO_H_ */
View git blame Copy permalink