7.49. ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL 和 VIDIOC_QUERYMENU

7.49.1. 名称

VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - 枚举控件和菜单控件项

7.49.2. 概要

int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)

VIDIOC_QUERY_EXT_CTRL

int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)

VIDIOC_QUERYMENU

int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)

7.49.3. 参数

fd

由 open() 返回的文件描述符。

argp

指向 struct v4l2_queryctrl、v4l2_query_ext_ctrl 或 v4l2_querymenu 的指针（取决于 ioctl）。

7.49.4. 描述

要查询控件的属性，应用程序需要设置 struct v4l2_queryctrl 的 id 字段，并使用指向此结构的指针调用 VIDIOC_QUERYCTRL ioctl。驱动程序会填充结构的其余部分，或者当 id 无效时返回 EINVAL 错误代码。

可以通过从 V4L2_CID_BASE 开始，直到但不包括 V4L2_CID_LASTP1，连续调用 VIDIOC_QUERYCTRL 并使用递增的 id 值来枚举控件。如果不支持此范围内的控件，驱动程序可能会返回 EINVAL。此外，应用程序可以通过从 V4L2_CID_PRIVATE_BASE 开始并递增 id，直到驱动程序返回 EINVAL，来枚举此规范中未定义的私有控件。

在这两种情况下，当驱动程序在 flags 字段中设置 V4L2_CTRL_FLAG_DISABLED 标志时，此控件将被永久禁用，应用程序应忽略它。[1]

当应用程序将 id 与 V4L2_CTRL_FLAG_NEXT_CTRL 进行 OR 运算时，驱动程序将返回下一个支持的非复合控件，如果没有，则返回 EINVAL。此外，可以指定 V4L2_CTRL_FLAG_NEXT_COMPOUND 标志来枚举所有复合控件（即类型 ≥ V4L2_CTRL_COMPOUND_TYPES 和/或数组控件的控件，换句话说，包含多个值的控件）。同时指定 V4L2_CTRL_FLAG_NEXT_CTRL 和 V4L2_CTRL_FLAG_NEXT_COMPOUND 以枚举所有控件，无论是否为复合控件。尚不支持这些标志的驱动程序始终返回 EINVAL。

引入 VIDIOC_QUERY_EXT_CTRL ioctl 是为了更好地支持可以使用复合类型的控件，并公开无法在 struct v4l2_queryctrl 中返回的其他控件信息，因为该结构已满。

VIDIOC_QUERY_EXT_CTRL 的使用方式与 VIDIOC_QUERYCTRL 相同，只是 reserved 数组也必须清零。

菜单控件需要额外的信息：菜单项的名称。要查询它们，应用程序需要设置 struct v4l2_querymenu 的 id 和 index 字段，并使用指向此结构的指针调用 VIDIOC_QUERYMENU ioctl。驱动程序会填充结构的其余部分，或者当 id 或 index 无效时返回 EINVAL 错误代码。通过调用 VIDIOC_QUERYMENU 并使用从 struct v4l2_queryctrl 的 minimum 到 maximum（包括两者）的递增的 index 值来枚举菜单项。

注意

VIDIOC_QUERYMENU 可能会为 minimum 和 maximum 之间的一些索引返回 EINVAL 错误代码。在这种情况下，该特定菜单项不受此驱动程序的支持。另请注意，minimum 值不一定为 0。

另请参阅 用户控件 中的示例。

struct v4l2_queryctrl

__u32	id	标识控件，由应用程序设置。有关预定义的 ID，请参阅 控件 ID。当 ID 与 V4L2_CTRL_FLAG_NEXT_CTRL 进行 OR 运算时，驱动程序会清除该标志并返回第一个 ID 较高的控件。尚不支持此标志的驱动程序始终返回 EINVAL 错误代码。
__u32	type	控件类型，请参阅 v4l2_ctrl_type。
__u8	name[32]	控件的名称，以 NUL 结尾的 ASCII 字符串。此信息供用户使用。
__s32	minimum	最小值，包括。此字段给出了控件的下限。有关最小值如何用于每种可能的控件类型，请参阅 enum v4l2_ctrl_type。请注意，这是一个有符号的 32 位值。
__s32	maximum	最大值，包括。此字段给出了控件的上限。有关最大值如何用于每种可能的控件类型，请参阅 enum v4l2_ctrl_type。请注意，这是一个有符号的 32 位值。
__s32	step	此字段给出了控件的步长。有关步长值如何用于每种可能的控件类型，请参阅 enum v4l2_ctrl_type。请注意，这是一个无符号的 32 位值。 通常，驱动程序不应缩放硬件控件值。例如，当 name 或 id 暗示特定单位，而硬件实际上只接受该单位的倍数时，这可能是必要的。如果是这样，驱动程序必须注意在缩放时正确舍入值，这样错误才不会在重复的读写周期中累积。 此字段给出了整数控件的最小更改，该更改实际影响硬件。通常，当用户可以通过键盘或 GUI 按钮而不是滑块来更改控件时，需要此信息。例如，当硬件寄存器接受 0-511 的值，而驱动程序报告 0-65535 时，步长应为 128。 请注意，尽管已签名，但步长值应始终为正值。
__s32	default_value	V4L2_CTRL_TYPE_INTEGER、_BOOLEAN、_BITMASK、_MENU 或 _INTEGER_MENU 控件的默认值。对其他类型的控件无效。 注意 驱动程序仅在首次加载驱动程序时将控件重置为其默认值，之后不再重置。
__u32	flags	控件标志，请参阅 控件标志。
__u32	reserved[2]	为将来的扩展保留。驱动程序必须将数组设置为零。

struct v4l2_query_ext_ctrl

__u32	id	标识控件，由应用程序设置。有关预定义的 ID，请参阅 控件 ID。当 ID 与 V4L2_CTRL_FLAG_NEXT_CTRL 进行 OR 运算时，驱动程序会清除该标志并返回第一个 ID 较高的非复合控件。当 ID 与 V4L2_CTRL_FLAG_NEXT_COMPOUND 进行 OR 运算时，驱动程序会清除该标志并返回第一个 ID 较高的复合控件。同时设置两者以获取第一个 ID 较高的控件（无论是否为复合控件）。
__u32	type	控件类型，请参阅 v4l2_ctrl_type。
char	name[32]	控件的名称，以 NUL 结尾的 ASCII 字符串。此信息供用户使用。
__s64	minimum	最小值，包括。此字段给出了控件的下限。有关最小值如何用于每种可能的控件类型，请参阅 enum v4l2_ctrl_type。请注意，这是一个有符号的 64 位值。
__s64	maximum	最大值，包括。此字段给出了控件的上限。有关最大值如何用于每种可能的控件类型，请参阅 enum v4l2_ctrl_type。请注意，这是一个有符号的 64 位值。
__u64	step	此字段给出了控件的步长。有关步长值如何用于每种可能的控件类型，请参阅 enum v4l2_ctrl_type。请注意，这是一个无符号的 64 位值。 通常，驱动程序不应缩放硬件控件值。例如，当 name 或 id 暗示特定单位，而硬件实际上只接受该单位的倍数时，这可能是必要的。如果是这样，驱动程序必须注意在缩放时正确舍入值，这样错误才不会在重复的读写周期中累积。 此字段给出了整数控件的最小更改，该更改实际影响硬件。通常，当用户可以通过键盘或 GUI 按钮而不是滑块来更改控件时，需要此信息。例如，当硬件寄存器接受 0-511 的值，而驱动程序报告 0-65535 时，步长应为 128。
__s64	default_value	V4L2_CTRL_TYPE_INTEGER、_INTEGER64、_BOOLEAN、_BITMASK、_MENU、_INTEGER_MENU、_U8 或 _U16 控件的默认值。对其他类型的控件无效。 注意 驱动程序仅在首次加载驱动程序时将控件重置为其默认值，之后不再重置。
__u32	flags	控件标志，请参阅 控件标志。
__u32	elem_size	数组单个元素的大小（以字节为单位）。给定一个指向 3 维数组的 char 指针 p，您可以找到单元格 (z, y, x) 的位置，如下所示：p + ((z * dims[1] + y) * dims[0] + x) * elem_size。elem_size 始终有效，即使控件不是数组也是如此。对于字符串控件，elem_size 等于 maximum + 1。
__u32	elems	N 维数组中的元素数。如果此控件不是数组，则 elems 为 1。elems 字段永远不能为 0。
__u32	nr_of_dims	N 维数组中的维数。如果此控件不是数组，则此字段为 0。
__u32	dims[V4L2_CTRL_MAX_DIMS]	每个维度的大小。此数组的前 nr_of_dims 个元素必须为非零，所有剩余元素必须为零。
__u32	reserved[32]	为将来的扩展保留。应用程序和驱动程序必须将数组设置为零。

struct v4l2_querymenu

__u32	id	标识控件，由应用程序从相应的 struct v4l2_queryctrl id 设置。
__u32	index	菜单项的索引，从零开始，由应用程序设置。
union {	(anonymous)
__u8	name[32]	菜单项的名称，以 NUL 结尾的 ASCII 字符串。此信息供用户使用。此字段对 V4L2_CTRL_TYPE_MENU 类型的控件有效。
__s64	value	整数菜单项的值。此字段对 V4L2_CTRL_TYPE_INTEGER_MENU 类型的控件有效。
}
__u32	reserved	为将来的扩展保留。驱动程序必须将数组设置为零。

type v4l2_ctrl_type

enum v4l2_ctrl_type

类型	minimum	step	maximum	描述
V4L2_CTRL_TYPE_INTEGER	任意	任意	任意	一个整数值控件，范围从最小值到最大值（包括）。步长值表示值之间的增量。
V4L2_CTRL_TYPE_BOOLEAN	0	1	1	一个布尔值控件。零对应于“已禁用”，一表示“已启用”。
V4L2_CTRL_TYPE_MENU	≥ 0	1	N-1	控件具有 N 个选项的菜单。可以使用 VIDIOC_QUERYMENU ioctl 枚举菜单项的名称。
V4L2_CTRL_TYPE_INTEGER_MENU	≥ 0	1	N-1	控件具有 N 个选项的菜单。可以使用 VIDIOC_QUERYMENU ioctl 枚举菜单项的值。这与 V4L2_CTRL_TYPE_MENU 类似，只是菜单项是有符号的 64 位整数而不是字符串。
V4L2_CTRL_TYPE_BITMASK	0	n/a	任意	一个位掩码字段。最大值是可以使用的位集，所有其他位都应为 0。最大值被解释为 __u32，允许在位掩码中使用位 31。
V4L2_CTRL_TYPE_BUTTON	0	0	0	一个在设置时执行操作的控件。驱动程序必须忽略使用 VIDIOC_S_CTRL 传递的值，并在 VIDIOC_G_CTRL 尝试时返回 EACCES 错误代码。
V4L2_CTRL_TYPE_INTEGER64	任意	任意	任意	一个 64 位整数值控件。无法使用 VIDIOC_QUERYCTRL 查询最小值、最大值和步长。只有 VIDIOC_QUERY_EXT_CTRL 可以检索 64 位 min/max/step 值，在使用 VIDIOC_QUERYCTRL 时应将其解释为 n/a。
V4L2_CTRL_TYPE_STRING	≥ 0	≥ 1	≥ 0	最小和最大字符串长度。步长表示字符串的长度必须为（最小值 + N * 步长），其中 N ≥ 0。这些长度不包括终止零，因此为了将长度为 8 的字符串传递给 VIDIOC_S_EXT_CTRLS，需要将 struct v4l2_ext_control 的 size 字段设置为 9。对于 VIDIOC_G_EXT_CTRLS，可以将 size 字段设置为 maximum + 1。使用的字符编码将取决于字符串控件本身，并且应该是控件文档的一部分。
V4L2_CTRL_TYPE_CTRL_CLASS	n/a	n/a	n/a	这不是控件。当使用等于控件类代码（请参阅 控件类）+ 1 的控件 ID 调用 VIDIOC_QUERYCTRL 时，ioctl 返回控件类的名称和此控件类型。不支持此功能的旧驱动程序返回 EINVAL 错误代码。
V4L2_CTRL_TYPE_U8	任意	任意	任意	一个无符号的 8 位值控件，范围从最小值到最大值（包括）。步长值表示值之间的增量。
V4L2_CTRL_TYPE_U16	任意	任意	任意	一个无符号的 16 位值控件，范围从最小值到最大值（包括）。步长值表示值之间的增量。
V4L2_CTRL_TYPE_U32	任意	任意	任意	一个无符号的 32 位值控件，范围从最小值到最大值（包括）。步长值表示值之间的增量。
V4L2_CTRL_TYPE_MPEG2_QUANTISATION	n/a	n/a	n/a	一个 struct v4l2_ctrl_mpeg2_quantisation，包含用于无状态视频解码器的 MPEG-2 量化矩阵。
V4L2_CTRL_TYPE_MPEG2_SEQUENCE	n/a	n/a	n/a	一个 struct v4l2_ctrl_mpeg2_sequence，包含用于无状态视频解码器的 MPEG-2 序列参数。
V4L2_CTRL_TYPE_MPEG2_PICTURE	n/a	n/a	n/a	一个 struct v4l2_ctrl_mpeg2_picture，包含用于无状态视频解码器的 MPEG-2 图片参数。
V4L2_CTRL_TYPE_AREA	n/a	n/a	n/a	一个 struct v4l2_area，包含矩形区域的宽度和高度。单位取决于用例。
V4L2_CTRL_TYPE_RECT	n/a	n/a	n/a	一个 struct v4l2_rect，包含由其左上角的位置、宽度和高度描述的矩形。单位取决于用例。对 V4L2_CTRL_WHICH_MIN_VAL 和 V4L2_CTRL_WHICH_MAX_VAL 的支持是可选的，并且取决于 V4L2_CTRL_FLAG_HAS_WHICH_MIN_MAX 标志。有关如何解释最小值和最大值的文档，请参阅特定控件的文档。
V4L2_CTRL_TYPE_H264_SPS	n/a	n/a	n/a	一个 struct v4l2_ctrl_h264_sps，包含用于无状态视频解码器的 H264 序列参数。
V4L2_CTRL_TYPE_H264_PPS	n/a	n/a	n/a	一个 struct v4l2_ctrl_h264_pps，包含用于无状态视频解码器的 H264 图片参数。
V4L2_CTRL_TYPE_H264_SCALING_MATRIX	n/a	n/a	n/a	一个 struct v4l2_ctrl_h264_scaling_matrix，包含用于无状态视频解码器的 H264 缩放矩阵。
V4L2_CTRL_TYPE_H264_SLICE_PARAMS	n/a	n/a	n/a	一个 struct v4l2_ctrl_h264_slice_params，包含用于无状态视频解码器的 H264 片段参数。
V4L2_CTRL_TYPE_H264_DECODE_PARAMS	n/a	n/a	n/a	一个 struct v4l2_ctrl_h264_decode_params，包含用于无状态视频解码器的 H264 解码参数。
V4L2_CTRL_TYPE_FWHT_PARAMS	n/a	n/a	n/a	一个 struct v4l2_ctrl_fwht_params，包含用于无状态视频解码器的 FWHT 参数。
V4L2_CTRL_TYPE_HEVC_SPS	n/a	n/a	n/a	一个 struct v4l2_ctrl_hevc_sps，包含用于无状态视频解码器的 HEVC 序列参数集。
V4L2_CTRL_TYPE_HEVC_PPS	n/a	n/a	n/a	一个 struct v4l2_ctrl_hevc_pps，包含用于无状态视频解码器的 HEVC 图片参数集。
V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS	n/a	n/a	n/a	一个 struct v4l2_ctrl_hevc_slice_params，包含用于无状态视频解码器的 HEVC 片段参数。
V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX	n/a	n/a	n/a	一个 struct v4l2_ctrl_hevc_scaling_matrix，包含用于无状态视频解码器的 HEVC 缩放矩阵。
V4L2_CTRL_TYPE_VP8_FRAME	n/a	n/a	n/a	一个 struct v4l2_ctrl_vp8_frame，包含用于无状态视频解码器的 VP8 帧参数。
V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS	n/a	n/a	n/a	一个 struct v4l2_ctrl_hevc_decode_params，包含用于无状态视频解码器的 HEVC 解码参数。
V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR	n/a	n/a	n/a	一个 struct v4l2_ctrl_vp9_compressed_hdr，包含用于无状态视频解码器的 VP9 概率更新。
V4L2_CTRL_TYPE_VP9_FRAME	n/a	n/a	n/a	一个 struct v4l2_ctrl_vp9_frame，包含用于无状态视频解码器的 VP9 帧解码参数。
V4L2_CTRL_TYPE_AV1_SEQUENCE	n/a	n/a	n/a	一个 struct v4l2_ctrl_av1_sequence，包含用于无状态视频解码器的 AV1 序列 OBU 解码参数。
V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY	n/a	n/a	n/a	一个 struct v4l2_ctrl_av1_tile_group_entry，包含用于无状态视频解码器的 AV1 图块组 OBU 解码参数。
V4L2_CTRL_TYPE_AV1_FRAME	n/a	n/a	n/a	一个 struct v4l2_ctrl_av1_frame，包含用于无状态视频解码器的 AV1 帧/帧头 OBU 解码参数。
V4L2_CTRL_TYPE_AV1_FILM_GRAIN	n/a	n/a	n/a	一个 struct v4l2_ctrl_av1_film_grain，包含用于无状态视频解码器的 AV1 胶片颗粒参数。

控件标志

V4L2_CTRL_FLAG_DISABLED	0x0001	此控件已永久禁用，应被应用程序忽略。任何更改控件的尝试都将导致 EINVAL 错误代码。
V4L2_CTRL_FLAG_GRABBED	0x0002	此控件暂时无法更改，例如因为另一个应用程序控制了相应的资源。此类控件可能会在用户界面中以特殊方式显示。 尝试更改控件可能会导致 EBUSY 错误代码。
V4L2_CTRL_FLAG_READ_ONLY	0x0004	此控件永久只读。 任何更改控件的尝试都会导致 EINVAL 错误代码。
V4L2_CTRL_FLAG_UPDATE	0x0008	提示：更改此控件可能会影响同一控件类中其他控件的值。 应用程序应相应地更新其用户界面。
V4L2_CTRL_FLAG_INACTIVE	0x0010	此控件不适用于当前配置，应在用户界面中相应地显示。 例如，当使用另一个控件选择 MPEG 音频编码级别 1 时，可以在 MPEG 音频级别 2 比特率控件上设置此标志。
V4L2_CTRL_FLAG_SLIDER	0x0020	提示：此控件最好在用户界面中表示为类似滑块的元素。
V4L2_CTRL_FLAG_WRITE_ONLY	0x0040	此控件永久只写。 任何读取控件的尝试都会导致 EACCES 错误代码。 此标志通常用于相对控件或操作控件，写入值将导致设备执行给定的操作（例如电机控制），但无法返回有意义的值。
V4L2_CTRL_FLAG_VOLATILE	0x0080	此控件是可变的，这意味着控件的值会持续变化。 一个典型的例子是如果设备处于自动增益模式，则为当前增益值。 在这种情况下，硬件会根据光照条件计算增益值，而光照条件可能会随着时间的推移而变化。 注意 除非同时设置了 V4L2_CTRL_FLAG_EXECUTE_ON_WRITE，否则设置可变控件的新值将被忽略。 设置可变控件的新值永远不会触发 V4L2_EVENT_CTRL_CH_VALUE 事件。
V4L2_CTRL_FLAG_HAS_PAYLOAD	0x0100	此控件具有指针类型，因此必须使用结构体 v4l2_ext_control 的指针字段之一访问其值。 对于数组、字符串或具有复合类型的控件，将设置此标志。 在所有情况下，您都必须设置一个指针，指向包含控件有效负载的内存。
V4L2_CTRL_FLAG_EXECUTE_ON_WRITE	0x0200	即使提供给控件的值保持不变，也会将其传播到驱动程序。 当控件表示硬件上的操作时，这是必需的。 例如：清除错误标志或触发闪光灯。 所有 V4L2_CTRL_TYPE_BUTTON 类型的控件都设置了此标志。
V4L2_CTRL_FLAG_MODIFY_LAYOUT	0x0400	更改此控件值可能会修改缓冲区（对于视频设备）或媒体总线格式（对于子设备）的布局。 一个典型的例子是 V4L2_CID_ROTATE 控件。 请注意，通常，当缓冲区分配或流传输正在进行时，具有此标志的控件也将设置 V4L2_CTRL_FLAG_GRABBED 标志，因为大多数驱动程序在这种情况下不支持更改格式。
V4L2_CTRL_FLAG_DYNAMIC_ARRAY	0x0800	此控件是动态大小的一维数组。 它的行为与常规数组相同，只是 elems 字段报告的元素数量介于 1 和 dims[0] 之间。 因此，使用大小不同的数组设置控件将更改之后查询控件时的 elems 字段。
V4L2_CTRL_FLAG_HAS_WHICH_MIN_MAX	0x1000	此控件支持使用 vidioc_g_ext_ctrls 和 V4L2_CTRL_WHICH_MIN/MAX_VAL 获取最小值和最大值。

7.49.5. 返回值

成功时返回 0，出错时返回 -1，并相应地设置 errno 变量。 通用错误代码在 通用错误代码 章节中描述。

EINVAL

结构体 v4l2_queryctrl 的 id 无效。 结构体 v4l2_querymenu 的 id 无效，或者 index 超出范围（小于 minimum 或大于 maximum），或者驱动程序不支持此特定菜单项。

EACCES

尝试读取只写控件。

[1]

V4L2_CTRL_FLAG_DISABLED 旨在用于两个目的：驱动程序可以跳过硬件不支持的预定义控件（虽然返回 EINVAL 也可以），或者在硬件检测后禁用预定义和私有控件，而无需重新排序控件数组和索引的麻烦（EINVAL 不能用于跳过私有控件，因为它会过早结束枚举）。