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。
另请参阅 用户控件 中的示例。
__u32 |
|
标识控件,由应用程序设置。有关预定义的 ID,请参阅 控件 ID。当 ID 与 V4L2_CTRL_FLAG_NEXT_CTRL 进行 OR 运算时,驱动程序会清除该标志并返回第一个 ID 较高的控件。尚不支持此标志的驱动程序始终返回 |
__u32 |
|
控件类型,请参阅 |
__u8 |
|
控件的名称,以 NUL 结尾的 ASCII 字符串。此信息供用户使用。 |
__s32 |
|
最小值,包括。此字段给出了控件的下限。有关最小值如何用于每种可能的控件类型,请参阅 enum |
__s32 |
|
最大值,包括。此字段给出了控件的上限。有关最大值如何用于每种可能的控件类型,请参阅 enum |
__s32 |
|
此字段给出了控件的步长。有关步长值如何用于每种可能的控件类型,请参阅 enum 通常,驱动程序不应缩放硬件控件值。例如,当 此字段给出了整数控件的最小更改,该更改实际影响硬件。通常,当用户可以通过键盘或 GUI 按钮而不是滑块来更改控件时,需要此信息。例如,当硬件寄存器接受 0-511 的值,而驱动程序报告 0-65535 时,步长应为 128。 请注意,尽管已签名,但步长值应始终为正值。 |
__s32 |
|
注意 驱动程序仅在首次加载驱动程序时将控件重置为其默认值,之后不再重置。 |
__u32 |
|
控件标志,请参阅 控件标志。 |
__u32 |
|
为将来的扩展保留。驱动程序必须将数组设置为零。 |
__u32 |
|
标识控件,由应用程序设置。有关预定义的 ID,请参阅 控件 ID。当 ID 与 |
__u32 |
|
控件类型,请参阅 |
char |
|
控件的名称,以 NUL 结尾的 ASCII 字符串。此信息供用户使用。 |
__s64 |
|
最小值,包括。此字段给出了控件的下限。有关最小值如何用于每种可能的控件类型,请参阅 enum |
__s64 |
|
最大值,包括。此字段给出了控件的上限。有关最大值如何用于每种可能的控件类型,请参阅 enum |
__u64 |
|
此字段给出了控件的步长。有关步长值如何用于每种可能的控件类型,请参阅 enum 通常,驱动程序不应缩放硬件控件值。例如,当 此字段给出了整数控件的最小更改,该更改实际影响硬件。通常,当用户可以通过键盘或 GUI 按钮而不是滑块来更改控件时,需要此信息。例如,当硬件寄存器接受 0-511 的值,而驱动程序报告 0-65535 时,步长应为 128。 |
__s64 |
|
注意 驱动程序仅在首次加载驱动程序时将控件重置为其默认值,之后不再重置。 |
__u32 |
|
控件标志,请参阅 控件标志。 |
__u32 |
|
数组单个元素的大小(以字节为单位)。给定一个指向 3 维数组的 char 指针 |
__u32 |
|
N 维数组中的元素数。如果此控件不是数组,则 |
__u32 |
|
N 维数组中的维数。如果此控件不是数组,则此字段为 0。 |
__u32 |
|
每个维度的大小。此数组的前 |
__u32 |
|
为将来的扩展保留。应用程序和驱动程序必须将数组设置为零。 |
__u32 |
|
标识控件,由应用程序从相应的 struct v4l2_queryctrl |
__u32 |
|
菜单项的索引,从零开始,由应用程序设置。 |
union { |
(anonymous) |
|
__u8 |
|
菜单项的名称,以 NUL 结尾的 ASCII 字符串。此信息供用户使用。此字段对 |
__s64 |
|
整数菜单项的值。此字段对 |
} |
||
__u32 |
|
为将来的扩展保留。驱动程序必须将数组设置为零。 |
-
type v4l2_ctrl_type¶
类型 |
|
|
|
描述 |
---|---|---|---|---|
|
任意 |
任意 |
任意 |
一个整数值控件,范围从最小值到最大值(包括)。步长值表示值之间的增量。 |
|
0 |
1 |
1 |
一个布尔值控件。零对应于“已禁用”,一表示“已启用”。 |
|
≥ 0 |
1 |
N-1 |
控件具有 N 个选项的菜单。可以使用 |
|
≥ 0 |
1 |
N-1 |
控件具有 N 个选项的菜单。可以使用 |
|
0 |
n/a |
任意 |
一个位掩码字段。最大值是可以使用的位集,所有其他位都应为 0。最大值被解释为 __u32,允许在位掩码中使用位 31。 |
|
0 |
0 |
0 |
一个在设置时执行操作的控件。驱动程序必须忽略使用 |
|
任意 |
任意 |
任意 |
一个 64 位整数值控件。无法使用 |
|
≥ 0 |
≥ 1 |
≥ 0 |
最小和最大字符串长度。步长表示字符串的长度必须为(最小值 + N * 步长),其中 N ≥ 0。这些长度不包括终止零,因此为了将长度为 8 的字符串传递给 VIDIOC_S_EXT_CTRLS,需要将 struct |
|
n/a |
n/a |
n/a |
这不是控件。当使用等于控件类代码(请参阅 控件类)+ 1 的控件 ID 调用 |
|
任意 |
任意 |
任意 |
一个无符号的 8 位值控件,范围从最小值到最大值(包括)。步长值表示值之间的增量。 |
|
任意 |
任意 |
任意 |
一个无符号的 16 位值控件,范围从最小值到最大值(包括)。步长值表示值之间的增量。 |
|
任意 |
任意 |
任意 |
一个无符号的 32 位值控件,范围从最小值到最大值(包括)。步长值表示值之间的增量。 |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
n/a |
n/a |
n/a |
一个 struct |
|
0x0001 |
此控件已永久禁用,应被应用程序忽略。任何更改控件的尝试都将导致 |
|
0x0002 |
此控件暂时无法更改,例如因为另一个应用程序控制了相应的资源。此类控件可能会在用户界面中以特殊方式显示。 尝试更改控件可能会导致 |
|
0x0004 |
此控件永久只读。 任何更改控件的尝试都会导致 |
|
0x0008 |
提示:更改此控件可能会影响同一控件类中其他控件的值。 应用程序应相应地更新其用户界面。 |
|
0x0010 |
此控件不适用于当前配置,应在用户界面中相应地显示。 例如,当使用另一个控件选择 MPEG 音频编码级别 1 时,可以在 MPEG 音频级别 2 比特率控件上设置此标志。 |
|
0x0020 |
提示:此控件最好在用户界面中表示为类似滑块的元素。 |
|
0x0040 |
此控件永久只写。 任何读取控件的尝试都会导致 |
|
0x0080 |
此控件是可变的,这意味着控件的值会持续变化。 一个典型的例子是如果设备处于自动增益模式,则为当前增益值。 在这种情况下,硬件会根据光照条件计算增益值,而光照条件可能会随着时间的推移而变化。 注意 除非同时设置了 V4L2_CTRL_FLAG_EXECUTE_ON_WRITE,否则设置可变控件的新值将被忽略。 设置可变控件的新值永远不会触发 V4L2_EVENT_CTRL_CH_VALUE 事件。 |
|
0x0100 |
此控件具有指针类型,因此必须使用结构体 |
|
0x0200 |
即使提供给控件的值保持不变,也会将其传播到驱动程序。 当控件表示硬件上的操作时,这是必需的。 例如:清除错误标志或触发闪光灯。 所有 |
|
0x0400 |
更改此控件值可能会修改缓冲区(对于视频设备)或媒体总线格式(对于子设备)的布局。 一个典型的例子是 请注意,通常,当缓冲区分配或流传输正在进行时,具有此标志的控件也将设置 |
|
0x0800 |
此控件是动态大小的一维数组。 它的行为与常规数组相同,只是 |
|
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
尝试读取只写控件。