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 系统调用获取的异常。

类型 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]	事件数据。由事件类型定义。该联合应该用于为事件定义易于访问的类型。
}
__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 字段进行或运算。
V4L2_EVENT_FRAME_SYNC	4	在开始接收帧时立即触发。此事件具有与之关联的 struct v4l2_event_frame_sync。 如果硬件需要在缓冲区欠载的情况下停止，它可能无法生成此事件。在这种情况下，struct v4l2_event_frame_sync 中的 frame_sequence 字段将不会递增。这会导致两个连续的帧序列号之间间隔 n 倍的帧间隔。
V4L2_EVENT_SOURCE_CHANGE	5	当视频设备在运行时检测到源参数更改时，将触发此事件。它可以是由视频解码器触发的运行时分辨率更改，或输入连接器上发生的格式更改。此事件要求 id 与您要接收事件的输入索引（当与视频设备节点一起使用时）或焊盘索引（当与子设备节点一起使用时）匹配。 此事件具有与之关联的 struct v4l2_event_src_change。changes 位域表示已订阅的焊盘发生了哪些更改。如果应用程序在可以将其出队之前发生多个事件，则更改将具有生成的所有事件的 OR 运算值。
V4L2_EVENT_MOTION_DET	6	每当一个或多个区域的运动检测状态更改时触发。此事件具有与之关联的 struct v4l2_event_motion_det。
V4L2_EVENT_PRIVATE_START	0x08000000	驱动程序专用事件的基本事件号。

类型 v4l2_event_vsync

struct v4l2_event_vsync

__u8

field

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

类型 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	控制的最大值。请参阅结构体 v4l2_queryctrl。
__s32	步长	控制的步长值。请参阅结构体 v4l2_queryctrl。
__s32	默认值	控制的默认值。请参阅结构体 v4l2_queryctrl。

类型 v4l2_event_frame_sync

结构体 v4l2_event_frame_sync

__u32

frame_sequence

正在接收的帧的序列号。

类型 v4l2_event_src_change

结构体 v4l2_event_src_change

__u32

changes

一个位掩码，指示发生了什么变化。请参阅 源更改。

类型 v4l2_event_motion_det

结构体 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 变量。通用错误代码在 通用错误代码 章节中描述。