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變數。通用錯誤程式碼在通用錯誤程式碼章節中描述。