1.11. 摄像头控制参考¶
摄像头类别包含用于设备机械（或等效数字）功能的控制，例如可控镜头或传感器。
1.11.1. 摄像头控制ID¶
V4L2_CID_CAMERA_CLASS (类)摄像头类描述符。为此控制调用 ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL 和 VIDIOC_QUERYMENU 将返回此控制类的描述。
V4L2_CID_EXPOSURE_AUTO(枚举)
- enum v4l2_exposure_auto_type -
启用曝光时间及/或光圈的自动调整。当这些功能启用时，手动更改曝光时间或光圈的效果是未定义的，驱动应忽略此类请求。可能的值有：
|
自动曝光时间，自动光圈。 |
|
手动曝光时间，手动光圈。 |
|
手动曝光时间，自动光圈。 |
|
自动曝光时间，手动光圈。 |
V4L2_CID_EXPOSURE_ABSOLUTE (整数)确定摄像头传感器的曝光时间。曝光时间受帧间隔限制。驱动应将值解释为 100 微秒单位，其中值 1 代表 1/10000 秒，10000 代表 1 秒，100000 代表 10 秒。
V4L2_CID_EXPOSURE_AUTO_PRIORITY (布尔)当
V4L2_CID_EXPOSURE_AUTO设置为AUTO或APERTURE_PRIORITY时，此控制决定设备是否可以动态改变帧率。默认情况下，此功能是禁用 (0) 的，帧率必须保持恒定。V4L2_CID_AUTO_EXPOSURE_BIAS (整数 菜单)确定自动曝光补偿，仅当
V4L2_CID_EXPOSURE_AUTO控制设置为AUTO、SHUTTER_PRIORITY或APERTURE_PRIORITY时才有效。它以 EV 表示，驱动应将值解释为 0.001 EV 单位，其中值 1000 代表 +1 EV。增加曝光补偿值等同于减少曝光值 (EV)，并将增加图像传感器接收到的光量。摄像头通过调整绝对曝光时间及/或光圈来执行曝光补偿。
V4L2_CID_EXPOSURE_METERING(枚举)
- enum v4l2_exposure_metering -
确定摄像头如何测量帧曝光可用光量。可能的值有：
|
使用来自整个帧的光信息并平均，不给计量区域的任何特定部分加权。 |
|
平均来自整个帧的光信息，优先考虑计量区域的中心。 |
|
仅测量帧中心非常小的区域。 |
|
多区域测光。在帧的多个点测量光强度并组合结果。区域选择及其在计算最终值中的重要性算法取决于设备。 |
V4L2_CID_PAN_RELATIVE (整数)此控制将摄像头水平转动指定量。单位未定义。正值使摄像头向右移动（从上方看是顺时针），负值向左移动。值为零不引起运动。这是一个只写控制。
V4L2_CID_TILT_RELATIVE (整数)此控制将摄像头垂直转动指定量。单位未定义。正值使摄像头向上移动，负值向下移动。值为零不引起运动。这是一个只写控制。
V4L2_CID_PAN_RESET (按钮)当此控制设置时，摄像头水平移动到默认位置。
V4L2_CID_TILT_RESET (按钮)当此控制设置时，摄像头垂直移动到默认位置。
V4L2_CID_PAN_ABSOLUTE (整数)此控制将摄像头水平转动到指定位置。正值使摄像头向右移动（从上方看是顺时针），负值向左移动。驱动应将值解释为弧秒，有效值介于 -180 * 3600 和 +180 * 3600（含）之间。
V4L2_CID_TILT_ABSOLUTE (整数)此控制将摄像头垂直转动到指定位置。正值使摄像头向上移动，负值向下移动。驱动应将值解释为弧秒，有效值介于 -180 * 3600 和 +180 * 3600（含）之间。
V4L2_CID_FOCUS_ABSOLUTE (整数)此控制将摄像头的焦点设置为指定位置。单位未定义。正值使焦点更靠近摄像头，负值使焦点移向无穷远。
V4L2_CID_FOCUS_RELATIVE (整数)此控制将摄像头的焦点移动指定量。单位未定义。正值使焦点更靠近摄像头，负值使焦点移向无穷远。这是一个只写控制。
V4L2_CID_FOCUS_AUTO (布尔)启用连续自动对焦调整。当此功能启用时，手动对焦调整的效果是未定义的，驱动应忽略此类请求。
V4L2_CID_AUTO_FOCUS_START (按钮)启动单次自动对焦过程。当
V4L2_CID_FOCUS_AUTO设置为TRUE(1) 时设置此控制的效果是未定义的，驱动应忽略此类请求。V4L2_CID_AUTO_FOCUS_STOP (按钮)中止由
V4L2_CID_AUTO_FOCUS_START控制启动的自动对焦。仅当连续自动对焦被禁用时才有效，即当V4L2_CID_FOCUS_AUTO控制设置为FALSE(0) 时。
V4L2_CID_AUTO_FOCUS_STATUS (位掩码)自动对焦状态。这是一个只读控制。
设置
V4L2_CID_3A_LOCK控制的V4L2_LOCK_FOCUS锁定位可能会停止V4L2_CID_AUTO_FOCUS_STATUS控制值的更新。
|
自动对焦未激活。 |
|
自动对焦正在进行中。 |
|
已达到焦点。 |
|
自动对焦失败，驱动将不会从此状态转换，直到应用程序执行另一个操作。 |
V4L2_CID_AUTO_FOCUS_RANGE(枚举)
- enum v4l2_auto_focus_range -
确定镜头可以调整的自动对焦距离范围。
|
摄像头自动选择对焦范围。 |
|
正常距离范围，为获得最佳自动对焦性能而受限。 |
|
微距（特写）自动对焦。摄像头将使用其可能的最小距离进行自动对焦。 |
|
镜头设置为对焦无限远处的物体。 |
V4L2_CID_ZOOM_ABSOLUTE (整数)将物镜焦距指定为绝对值。变焦单位是驱动特定的，其值应为正整数。
V4L2_CID_ZOOM_RELATIVE (整数)相对于当前值指定物镜焦距。正值使变焦镜头组向长焦方向移动，负值向广角方向移动。变焦单位是驱动特定的。这是一个只写控制。
V4L2_CID_ZOOM_CONTINUOUS (整数)以指定速度移动物镜组，直到达到物理设备限制或直到有明确请求停止移动。正值使变焦镜头组向长焦方向移动。零值停止变焦镜头组的移动。负值使变焦镜头组向广角方向移动。变焦速度单位是驱动特定的。
V4L2_CID_IRIS_ABSOLUTE (整数)此控制将摄像头的孔径设置为指定值。单位未定义。值越大光圈开得越宽，值越小光圈关得越小。
V4L2_CID_IRIS_RELATIVE (整数)此控制按指定量修改摄像头的孔径。单位未定义。正值使光圈再开一步，负值使光圈再关一步。这是一个只写控制。
V4L2_CID_PRIVACY (布尔)阻止摄像头获取视频。当此控制设置为
TRUE(1) 时，摄像头无法捕获任何图像。实现隐私的常见手段是传感器的机械遮挡和固件图像处理，但设备不限于这些方法。实现隐私控制的设备必须支持读访问，并可能支持写访问。V4L2_CID_BAND_STOP_FILTER (整数)开启或关闭摄像头传感器的带阻滤波器，或指定其强度。例如，此类带阻滤波器可用于滤除荧光灯分量。
V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE(枚举)
- enum v4l2_auto_n_preset_white_balance -
将白平衡设置为自动、手动或预设。预设确定光的色温，作为摄像头调整白平衡的提示，以实现最准确的色彩表示。以下白平衡预设按色温递增顺序列出。
|
手动白平衡。 |
|
自动白平衡调整。 |
|
用于白炽灯（钨丝灯）照明的白平衡设置。它通常会使颜色变冷，大致对应 2500...3500 K 的色温范围。 |
|
用于荧光灯照明的白平衡预设。它大致对应 4000...5000 K 的色温。 |
|
通过此设置，摄像头将补偿荧光 H 照明。 |
|
用于地平线日光照明的白平衡设置。它大致对应 5000 K 的色温。 |
|
用于日光（晴空）的白平衡预设。它大致对应 5000...6500 K 的色温。 |
|
通过此设置，摄像头将补偿闪光灯。它会使颜色略微变暖，大致对应 5000...5500 K 的色温。 |
|
用于中度阴天的白平衡预设。此选项大致对应 6500...8000 K 的色温范围。 |
|
用于阴影或重度阴天的白平衡预设。它大致对应 9000...10000 K 的色温。 |
V4L2_CID_WIDE_DYNAMIC_RANGE (布尔)启用或禁用摄像头的宽动态范围功能。此功能允许在场景中光照强度显著变化的场景中获得清晰图像，即同时存在非常暗和非常亮的区域。它在摄像头中最常见的实现方式是结合两个具有不同曝光时间的连续帧。[1]
V4L2_CID_IMAGE_STABILIZATION (布尔)启用或禁用图像稳定功能。
V4L2_CID_ISO_SENSITIVITY (整数 菜单)确定图像传感器的 ISO 等效值，表示传感器对光的敏感度。这些数字以算术刻度表示，符合 ISO 12232:2006 标准，其中传感器灵敏度加倍表示为 ISO 数值加倍。应用程序应将这些值解释为标准 ISO 值乘以 1000，例如控制值 800 代表 ISO 0.8。驱动通常只支持标准 ISO 值的一个子集。当
V4L2_CID_ISO_SENSITIVITY_AUTO控制设置为非V4L2_CID_ISO_SENSITIVITY_MANUAL值时，设置此控制的效果是未定义的，驱动应忽略此类请求。
V4L2_CID_ISO_SENSITIVITY_AUTO(枚举)
- enum v4l2_iso_sensitivity_type -
启用或禁用自动 ISO 敏感度调整。
|
手动 ISO 敏感度。 |
|
自动 ISO 敏感度调整。 |
V4L2_CID_SCENE_MODE(枚举)
- enum v4l2_scene_mode -
此控制允许选择场景程序作为针对常见拍摄场景优化的摄像头自动模式。在这些模式下，摄像头会确定最佳曝光、光圈、对焦、测光、白平衡和等效敏感度。这些参数的控制受场景模式控制的影响。每种模式下的确切行为取决于摄像头规格。
当不使用场景模式功能时，此控制应设置为
V4L2_SCENE_MODE_NONE，以确保其他可能相关的控制可访问。定义了以下场景程序：
|
场景模式功能已禁用。 |
|
逆光。当光线从主体后方射来时，补偿暗影，也会自动开启闪光灯。 |
|
沙滩和雪景。当摄像头的自动曝光基于平均场景亮度时，此模式补偿全白或明亮场景（这些场景往往看起来灰色且对比度低）。为补偿这一点，此模式会自动轻微过度曝光帧。白平衡也可能被调整，以补偿反光雪景看起来偏蓝而不是白色的事实。 |
|
烛光。摄像头通常会提高 ISO 敏感度并降低快门速度。此模式补偿场景中相对较近的主体。为保持光线氛围，闪光灯被禁用。 |
|
黎明和黄昏。保留黄昏前和黎明后低自然光下看到的颜色。摄像头可能会关闭闪光灯，并自动对焦无限远。它通常会提高饱和度并降低快门速度。 |
|
秋色。增加饱和度并调整白平衡以增强色彩。秋叶照片会获得饱和的红色和黄色。 |
|
烟花。使用长曝光时间捕获烟花扩散的光爆。摄像头可能会启用图像稳定。 |
|
风景。摄像头可能会选择小光圈以提供深景深和长曝光时间，以帮助在昏暗光线条件下捕捉细节。焦点固定在无限远。适用于远距离和广阔的风景。 |
|
夜晚，也称为夜景。专为低光条件设计，可在不使亮物体曝光过度的情况下保留暗区细节。摄像头通常会设置为中高 ISO 敏感度，曝光时间相对较长，并关闭闪光灯。因此，图像噪点会增加，并可能出现图像模糊。 |
|
派对和室内。旨在捕捉室内背景光和闪光灯照明的室内场景。摄像头通常会提高 ISO 敏感度，并调整曝光以适应低光条件。 |
|
肖像。摄像头调整光圈，以减少景深，这有助于将主体从平滑背景中分离出来。大多数摄像头会识别场景中人脸的存在并对其对焦。调整色调以增强肤色。闪光灯的强度通常会降低。 |
|
运动。显著提高 ISO 并使用高速快门以冻结快速移动主体的运动。在此模式下可能会看到增加的图像噪点。 |
|
日落。保留日落和日出中看到的深色调。它会提高饱和度。 |
|
文本。它应用额外的对比度和锐度，通常是为可读性优化的黑白模式。自动对焦可能会切换到特写模式，此设置也可能涉及一些镜头畸变校正。 |
V4L2_CID_3A_LOCK (位掩码)此控制锁定或解锁自动对焦、曝光和白平衡。通过将相应的锁定位设置为 1，可以独立暂停自动调整。然后，摄像头会保留这些设置，直到锁定位被清除。定义了以下锁定位：
当给定算法未启用时，驱动应忽略锁定它的请求，并且不应返回错误。例如，当
V4L2_CID_AUTO_WHITE_BALANCE控制设置为FALSE时，应用程序设置V4L2_LOCK_WHITE_BALANCE位。此控制的值可能会被曝光、白平衡或对焦控制更改。
|
自动曝光调整锁定。 |
|
自动白平衡调整锁定。 |
|
自动对焦锁定。 |
V4L2_CID_PAN_SPEED (整数)此控制以特定速度水平转动摄像头。单位未定义。正值使摄像头向右移动（从上方看是顺时针），负值向左移动。值为零停止正在进行的运动，否则无效果。
V4L2_CID_TILT_SPEED (整数)此控制以指定速度垂直转动摄像头。单位未定义。正值使摄像头向上移动，负值向下移动。值为零停止正在进行的运动，否则无效果。
V4L2_CID_CAMERA_ORIENTATION (菜单)此只读控制通过报告摄像头在安装设备上的安装位置来描述摄像头方向。控制值是常量，不能由软件修改。此控制对于具有明确方向的设备（例如手机、笔记本电脑和便携式设备）特别有意义，因为该控制表示为相对于设备预期使用方向的位置。例如，安装在手机、平板电脑或笔记本电脑设备用户侧的摄像头被认为是
V4L2_CAMERA_ORIENTATION_FRONT方向，而安装在正面相反侧的摄像头被认为是V4L2_CAMERA_ORIENTATION_BACK方向。未直接连接到设备或以允许其自由移动的方式连接的摄像头传感器（例如网络摄像头和数码相机）被认为是V4L2_CAMERA_ORIENTATION_EXTERNAL方向。
|
摄像头朝向设备的用户侧。 |
|
摄像头朝向设备的背面。 |
|
摄像头未直接连接到设备，可自由移动。 |
V4L2_CID_CAMERA_SENSOR_ROTATION (整数)此只读控制描述了为补偿摄像头传感器安装旋转，在捕获图像到内存后需要对捕获图像应用的逆时针方向的旋转校正度数。
有关传感器安装旋转的精确定义，请参阅设备树绑定文件“video-interfaces.txt”中对“rotation”属性的详细描述。
下面报告了一些示例，使用一条鲨鱼在用户面前从左向右游动作为要捕获的示例场景。
0 X-axis 0 +-------------------------------------> ! ! ! ! |\____)\___ ! ) _____ __`< ! |/ )/ ! ! ! V Y-axis
示例一 - 网络摄像头
假设您可以带着笔记本电脑与鲨鱼一起游泳，笔记本电脑的摄像头模块安装在笔记本电脑屏幕外壳的用户侧部分，通常用于视频通话。捕获的图像旨在以横向模式（宽度 > 高度）在笔记本电脑屏幕上显示。
摄像头通常倒置安装，以补偿镜头光学反转效应。在这种情况下，V4L2_CID_CAMERA_SENSOR_ROTATION 控制的值为 0，不需要旋转即可向用户正确显示图像。
如果摄像头传感器未倒置安装，则需要补偿镜头光学反转效应，并且 V4L2_CID_CAMERA_SENSOR_ROTATION 控制的值为 180 度，因为图像在捕获到内存时会旋转。
+--------------------------------------+ ! ! ! ! ! ! ! __/(_____/| ! ! >.___ ____ ( ! ! \( \| ! ! ! ! ! ! ! +--------------------------------------+
必须应用 180 度的软件旋转校正才能在用户屏幕上正确显示图像。
+--------------------------------------+ ! ! ! ! ! ! ! |\____)\___ ! ! ) _____ __`< ! ! |/ )/ ! ! ! ! ! ! ! +--------------------------------------+
示例二 - 手机摄像头
随身携带手机与鲨鱼一起游泳并使用安装在设备背面、远离用户的摄像头拍照会更方便。捕获的图像旨在以纵向模式（高度 > 宽度）显示，以匹配设备屏幕方向和拍照时使用的设备使用方向。
摄像头传感器通常以其像素阵列长边与设备长边对齐的方式安装，并倒置安装以补偿镜头光学反转效应。
图像一旦捕获到内存，将发生旋转，并且 V4L2_CID_CAMERA_SENSOR_ROTATION 的值将报告 90 度旋转。
+-------------------------------------+ | _ _ | | \ / | | | | | | | | | | | > | | < | | | | | | | . | | V | +-------------------------------------+
必须应用 90 度逆时针方向的校正才能在设备屏幕上正确显示纵向模式的图像。
+--------------------+ | | | | | | | | | | | | | |\____)\___ | | ) _____ __`< | | |/ )/ | | | | | | | | | | | +--------------------+
V4L2_CID_HDR_SENSOR_MODE (菜单)更改传感器 HDR 模式。HDR 图像是通过合并同一场景的两次不同曝光时间的捕获获得的。HDR 模式描述了这两种捕获在传感器中合并的方式。
由于模式因每个传感器而异，此控制不标准化菜单项，并留给程序员自行决定。