7.8. ioctl VIDIOC_DQEVENT

7.8.1. 名称

VIDIOC_DQEVENT - 队列事件

7.8.2. 概要

VIDIOC_DQEVENT

int ioctl(int fd, VIDIOC_DQEVENT, struct v4l2_event *argp)

7.8.3. 参数

fd

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

argp

指向 struct v4l2_event的指针。

7.8.4. 描述

从视频设备中队列事件。此 ioctl 不需要输入。struct v4l2_event结构的所有字段都由驱动程序填充。文件句柄也会收到应用程序可能通过例如使用 select 系统调用获得的异常。

type v4l2_event

struct v4l2_event

__u32	type	事件的类型，请参见事件类型。
union {	u
struct v4l2_event_vsync	vsync	事件V4L2_EVENT_VSYNC的事件数据。
struct v4l2_event_ctrl	ctrl	事件V4L2_EVENT_CTRL的事件数据。
struct v4l2_event_frame_sync	frame_sync	事件V4L2_EVENT_FRAME_SYNC的事件数据。
struct v4l2_event_motion_det	motion_det	事件 V4L2_EVENT_MOTION_DET 的事件数据。
struct v4l2_event_src_change	src_change	事件 V4L2_EVENT_SOURCE_CHANGE 的事件数据。
__u8	data[64]	事件数据。由事件类型定义。union 应该用于为事件定义易于访问的类型。
}
__u32	pending	不包括此事件的待处理事件数。
__u32	sequence	事件序列号。对于发生的每个订阅事件，序列号都会递增。如果序列号不连续，则表示事件已丢失。
struct timespec	timestamp	事件时间戳。时间戳已从CLOCK_MONOTONIC时钟获取。要在 V4L2 之外访问同一时钟，请使用clock_gettime()。
u32	id	与事件源关联的 ID。如果事件没有关联的 ID（这取决于事件类型），则为 0。
__u32	reserved[8]	保留供将来扩展使用。驱动程序必须将数组设置为零。

事件类型

V4L2_EVENT_ALL	0	所有事件。V4L2_EVENT_ALL 仅对 VIDIOC_UNSUBSCRIBE_EVENT 有效，用于一次取消订阅所有事件。
V4L2_EVENT_VSYNC	1	此事件在垂直同步时触发。此事件具有与之关联的 struct v4l2_event_vsync。
V4L2_EVENT_EOS	2	当到达流的末尾时，将触发此事件。这通常与 MPEG 解码器一起使用，以向应用程序报告何时已解码 MPEG 流的最后一个。
V4L2_EVENT_CTRL	3	此事件要求id与您要接收事件的控件 ID 匹配。如果控件的值更改，如果按下按钮控件或控件的标志更改，则会触发此事件。此事件具有与之关联的 struct v4l2_event_ctrl。此结构包含与 struct v4l2_queryctrl 和 struct v4l2_control 大致相同的信息。 如果由于调用VIDIOC_S_CTRL或VIDIOC_S_EXT_CTRLS而生成了事件，则该事件不会发送到调用 ioctl 函数的文件句柄。这可以防止讨厌的反馈循环。如果您确实想获取该事件，请设置V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK标志。 此事件类型将确保当引发的事件多于内部空间时，不会丢失任何信息。在这种情况下，将保留第二个最旧事件的 struct v4l2_event_ctrl，但是第二个最旧事件的changes字段将与最旧事件的changes字段进行 OR 运算。
V4L2_EVENT_FRAME_SYNC	4	在帧接收开始时立即触发。此事件具有与之关联的 struct v4l2_event_frame_sync。 如果在缓冲区欠载的情况下需要停止硬件，则可能无法生成此事件。在这种情况下，struct v4l2_event_frame_sync中的frame_sequence字段将不会递增。这会导致两个连续的帧序列号之间有 n 倍的帧间隔。
V4L2_EVENT_SOURCE_CHANGE	5	当视频设备在运行时检测到源参数更改时，将触发此事件。它可以是由视频解码器触发的运行时分辨率更改，也可以是发生在输入连接器上的格式更改。此事件要求id与您要从中接收事件的输入索引（与视频设备节点一起使用时）或 pad 索引（与子设备节点一起使用时）匹配。 此事件具有与之关联的 struct v4l2_event_src_change。 changes位字段表示已订阅的 pad 发生了什么变化。如果在应用程序可以对事件进行队列之前发生多个事件，则更改将具有生成的所有事件的 ORed 值。
V4L2_EVENT_MOTION_DET	6	只要一个或多个区域的运动检测状态发生变化，就会触发此事件。此事件具有与之关联的 struct v4l2_event_motion_det。
V4L2_EVENT_PRIVATE_START	0x08000000	驱动程序私有事件的基本事件编号。

type v4l2_event_vsync

struct v4l2_event_vsync

__u8

field

即将到来的字段。请参见枚举v4l2_field。

type v4l2_event_ctrl

struct v4l2_event_ctrl

__u32	changes	一个位掩码，用于告知发生了什么变化。请参见控件更改。
__u32	type	控件的类型。请参见枚举v4l2_ctrl_type。
union {	(匿名)
__s32	value	32 位控件类型的控件的 32 位值。对于字符串控件，这是 0，因为不能使用ioctl VIDIOC_DQEVENT传递字符串的值。
__s64	value64	64 位控件类型的控件的 64 位值。
}
__u32	flags	控件标志。请参见控件标志。
__s32	minimum	控件的最小值。请参见 struct v4l2_queryctrl。
__s32	maximum	控件的最大值。请参见 struct v4l2_queryctrl。
__s32	step	控件的步长值。请参见 struct v4l2_queryctrl。
__s32	default_value	控件的默认值。请参见 struct v4l2_queryctrl。

type v4l2_event_frame_sync

struct v4l2_event_frame_sync

__u32

frame_sequence

正在接收的帧的序列号。

type v4l2_event_src_change

struct v4l2_event_src_change

__u32

changes

一个位掩码，用于告知发生了什么变化。请参见源更改。

type v4l2_event_motion_det

struct v4l2_event_motion_det

__u32	flags	当前只有一个标志可用：如果设置了V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ，则frame_sequence字段有效，否则应忽略该字段。
__u32	frame_sequence	正在接收的帧的序列号。仅当设置了V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ标志时才有效。
__u32	region_mask	报告运动的区域的位掩码。至少有一个区域。如果此字段为 0，则根本没有检测到运动。如果没有V4L2_CID_DETECT_MD_REGION_GRID控件（请参见检测控件参考）向运动检测网格中的每个单元分配一个不同的区域，则会自动将所有单元分配给默认区域 0。

控件更改

V4L2_EVENT_CTRL_CH_VALUE	0x0001	由于控件的值已更改，因此触发了此控件事件。特殊情况：易失性控件不会生成此事件；如果控件设置了V4L2_CTRL_FLAG_EXECUTE_ON_WRITE标志，则也会发送此事件，而与其值无关。
V4L2_EVENT_CTRL_CH_FLAGS	0x0002	由于控件标志已更改，因此触发了此控件事件。
V4L2_EVENT_CTRL_CH_RANGE	0x0004	由于控件的最小值、最大值、步长值或默认值已更改，因此触发了此控件事件。
V4L2_EVENT_CTRL_CH_DIMENSIONS	0x0008	由于控件的尺寸已更改，因此触发了此控件事件。请注意，尺寸数量保持不变。

源更改

V4L2_EVENT_SRC_CH_RESOLUTION

0x0001

当在输入端检测到分辨率更改时，会触发此事件。这可能来自输入连接器或视频解码器。应用程序将必须查询新分辨率（如果有，信号也可能已丢失）。 对于有状态解码器，请遵循内存到内存有状态视频解码器接口中的准则。视频捕获设备必须使用ioctl VIDIOC_QUERY_DV_TIMINGS或VIDIOC_QUERYSTD查询新时序。 重要：即使新的视频时序看起来与旧的时序相同，接收此事件也表示视频信号存在问题，您必须停止并重新启动流式传输（VIDIOC_STREAMOFF，然后是VIDIOC_STREAMON）。原因是许多视频捕获设备无法从临时信号丢失中恢复，因此需要重新启动流式传输 I/O 才能使硬件与视频信号同步。

7.8.5. 返回值

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