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_CTRLVIDIOC_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_changechanges位字段表示已订阅的 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_TIMINGSVIDIOC_QUERYSTD查询新时序。

重要:即使新的视频时序看起来与旧的时序相同,接收此事件也表示视频信号存在问题,您必须停止并重新启动流式传输(VIDIOC_STREAMOFF,然后是VIDIOC_STREAMON)。原因是许多视频捕获设备无法从临时信号丢失中恢复,因此需要重新启动流式传输 I/O 才能使硬件与视频信号同步。

7.8.5. 返回值

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