Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_DQEVENT: |
5377d91f MH |
4 | |
5 | ******************** | |
6 | ioctl VIDIOC_DQEVENT | |
7 | ******************** | |
8 | ||
9 | *man VIDIOC_DQEVENT(2)* | |
10 | ||
11 | Dequeue event | |
12 | ||
13 | ||
14 | Synopsis | |
15 | ======== | |
16 | ||
b7e67f6c | 17 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_event *argp ) |
5377d91f MH |
18 | |
19 | Arguments | |
20 | ========= | |
21 | ||
22 | ``fd`` | |
23 | File descriptor returned by :ref:`open() <func-open>`. | |
24 | ||
25 | ``request`` | |
26 | VIDIOC_DQEVENT | |
27 | ||
28 | ``argp`` | |
29 | ||
30 | ||
31 | Description | |
32 | =========== | |
33 | ||
34 | Dequeue an event from a video device. No input is required for this | |
35 | ioctl. All the fields of the struct :ref:`v4l2_event <v4l2-event>` | |
36 | structure are filled by the driver. The file handle will also receive | |
37 | exceptions which the application may get by e.g. using the select system | |
38 | call. | |
39 | ||
40 | ||
41 | .. _v4l2-event: | |
42 | ||
43 | .. flat-table:: struct v4l2_event | |
44 | :header-rows: 0 | |
45 | :stub-columns: 0 | |
46 | :widths: 1 1 2 1 | |
47 | ||
48 | ||
49 | - .. row 1 | |
50 | ||
51 | - __u32 | |
52 | ||
53 | - ``type`` | |
54 | ||
0579e6e3 | 55 | - |
5377d91f MH |
56 | - Type of the event, see :ref:`event-type`. |
57 | ||
58 | - .. row 2 | |
59 | ||
60 | - union | |
61 | ||
62 | - ``u`` | |
63 | ||
0579e6e3 MCC |
64 | - |
65 | - | |
5377d91f MH |
66 | |
67 | - .. row 3 | |
68 | ||
0579e6e3 | 69 | - |
5377d91f MH |
70 | - struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` |
71 | ||
72 | - ``vsync`` | |
73 | ||
74 | - Event data for event ``V4L2_EVENT_VSYNC``. | |
75 | ||
76 | - .. row 4 | |
77 | ||
0579e6e3 | 78 | - |
5377d91f MH |
79 | - struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` |
80 | ||
81 | - ``ctrl`` | |
82 | ||
83 | - Event data for event ``V4L2_EVENT_CTRL``. | |
84 | ||
85 | - .. row 5 | |
86 | ||
0579e6e3 | 87 | - |
5377d91f MH |
88 | - struct :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` |
89 | ||
90 | - ``frame_sync`` | |
91 | ||
92 | - Event data for event ``V4L2_EVENT_FRAME_SYNC``. | |
93 | ||
94 | - .. row 6 | |
95 | ||
0579e6e3 | 96 | - |
5377d91f MH |
97 | - struct :ref:`v4l2_event_motion_det <v4l2-event-motion-det>` |
98 | ||
99 | - ``motion_det`` | |
100 | ||
101 | - Event data for event V4L2_EVENT_MOTION_DET. | |
102 | ||
103 | - .. row 7 | |
104 | ||
0579e6e3 | 105 | - |
5377d91f MH |
106 | - struct :ref:`v4l2_event_src_change <v4l2-event-src-change>` |
107 | ||
108 | - ``src_change`` | |
109 | ||
110 | - Event data for event V4L2_EVENT_SOURCE_CHANGE. | |
111 | ||
112 | - .. row 8 | |
113 | ||
0579e6e3 | 114 | - |
5377d91f MH |
115 | - __u8 |
116 | ||
117 | - ``data``\ [64] | |
118 | ||
119 | - Event data. Defined by the event type. The union should be used to | |
0579e6e3 | 120 | define easily accessible type for events. |
5377d91f MH |
121 | |
122 | - .. row 9 | |
123 | ||
124 | - __u32 | |
125 | ||
126 | - ``pending`` | |
127 | ||
0579e6e3 | 128 | - |
5377d91f MH |
129 | - Number of pending events excluding this one. |
130 | ||
131 | - .. row 10 | |
132 | ||
133 | - __u32 | |
134 | ||
135 | - ``sequence`` | |
136 | ||
0579e6e3 | 137 | - |
5377d91f | 138 | - Event sequence number. The sequence number is incremented for |
0579e6e3 MCC |
139 | every subscribed event that takes place. If sequence numbers are |
140 | not contiguous it means that events have been lost. | |
5377d91f MH |
141 | |
142 | - .. row 11 | |
143 | ||
144 | - struct timespec | |
145 | ||
146 | - ``timestamp`` | |
147 | ||
0579e6e3 | 148 | - |
5377d91f | 149 | - Event timestamp. The timestamp has been taken from the |
0579e6e3 MCC |
150 | ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2, |
151 | use :c:func:`clock_gettime(2)`. | |
5377d91f MH |
152 | |
153 | - .. row 12 | |
154 | ||
155 | - u32 | |
156 | ||
157 | - ``id`` | |
158 | ||
0579e6e3 | 159 | - |
5377d91f | 160 | - The ID associated with the event source. If the event does not |
0579e6e3 MCC |
161 | have an associated ID (this depends on the event type), then this |
162 | is 0. | |
5377d91f MH |
163 | |
164 | - .. row 13 | |
165 | ||
166 | - __u32 | |
167 | ||
168 | - ``reserved``\ [8] | |
169 | ||
0579e6e3 | 170 | - |
5377d91f | 171 | - Reserved for future extensions. Drivers must set the array to |
0579e6e3 | 172 | zero. |
5377d91f MH |
173 | |
174 | ||
175 | ||
176 | .. _event-type: | |
177 | ||
178 | .. flat-table:: Event Types | |
179 | :header-rows: 0 | |
180 | :stub-columns: 0 | |
181 | :widths: 3 1 4 | |
182 | ||
183 | ||
184 | - .. row 1 | |
185 | ||
186 | - ``V4L2_EVENT_ALL`` | |
187 | ||
188 | - 0 | |
189 | ||
190 | - All events. V4L2_EVENT_ALL is valid only for | |
0579e6e3 | 191 | VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. |
5377d91f MH |
192 | |
193 | - .. row 2 | |
194 | ||
195 | - ``V4L2_EVENT_VSYNC`` | |
196 | ||
197 | - 1 | |
198 | ||
199 | - This event is triggered on the vertical sync. This event has a | |
0579e6e3 MCC |
200 | struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` associated |
201 | with it. | |
5377d91f MH |
202 | |
203 | - .. row 3 | |
204 | ||
205 | - ``V4L2_EVENT_EOS`` | |
206 | ||
207 | - 2 | |
208 | ||
209 | - This event is triggered when the end of a stream is reached. This | |
0579e6e3 MCC |
210 | is typically used with MPEG decoders to report to the application |
211 | when the last of the MPEG stream has been decoded. | |
5377d91f MH |
212 | |
213 | - .. row 4 | |
214 | ||
215 | - ``V4L2_EVENT_CTRL`` | |
216 | ||
217 | - 3 | |
218 | ||
219 | - This event requires that the ``id`` matches the control ID from | |
0579e6e3 MCC |
220 | which you want to receive events. This event is triggered if the |
221 | control's value changes, if a button control is pressed or if the | |
222 | control's flags change. This event has a struct | |
223 | :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` associated with it. | |
224 | This struct contains much of the same information as struct | |
225 | :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct | |
226 | :ref:`v4l2_control <v4l2-control>`. | |
227 | ||
228 | If the event is generated due to a call to | |
229 | :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or | |
230 | :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the | |
231 | event will *not* be sent to the file handle that called the ioctl | |
232 | function. This prevents nasty feedback loops. If you *do* want to | |
233 | get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK`` | |
234 | flag. | |
235 | ||
236 | This event type will ensure that no information is lost when more | |
237 | events are raised than there is room internally. In that case the | |
238 | struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` of the | |
239 | second-oldest event is kept, but the ``changes`` field of the | |
240 | second-oldest event is ORed with the ``changes`` field of the | |
241 | oldest event. | |
5377d91f MH |
242 | |
243 | - .. row 5 | |
244 | ||
245 | - ``V4L2_EVENT_FRAME_SYNC`` | |
246 | ||
247 | - 4 | |
248 | ||
249 | - Triggered immediately when the reception of a frame has begun. | |
0579e6e3 MCC |
250 | This event has a struct |
251 | :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` | |
252 | associated with it. | |
5377d91f | 253 | |
0579e6e3 MCC |
254 | If the hardware needs to be stopped in the case of a buffer |
255 | underrun it might not be able to generate this event. In such | |
256 | cases the ``frame_sequence`` field in struct | |
257 | :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` will not | |
258 | be incremented. This causes two consecutive frame sequence numbers | |
259 | to have n times frame interval in between them. | |
5377d91f MH |
260 | |
261 | - .. row 6 | |
262 | ||
263 | - ``V4L2_EVENT_SOURCE_CHANGE`` | |
264 | ||
265 | - 5 | |
266 | ||
267 | - This event is triggered when a source parameter change is detected | |
0579e6e3 MCC |
268 | during runtime by the video device. It can be a runtime resolution |
269 | change triggered by a video decoder or the format change happening | |
270 | on an input connector. This event requires that the ``id`` matches | |
271 | the input index (when used with a video device node) or the pad | |
272 | index (when used with a subdevice node) from which you want to | |
273 | receive events. | |
274 | ||
275 | This event has a struct | |
276 | :ref:`v4l2_event_src_change <v4l2-event-src-change>` | |
277 | associated with it. The ``changes`` bitfield denotes what has | |
278 | changed for the subscribed pad. If multiple events occurred before | |
279 | application could dequeue them, then the changes will have the | |
280 | ORed value of all the events generated. | |
5377d91f MH |
281 | |
282 | - .. row 7 | |
283 | ||
284 | - ``V4L2_EVENT_MOTION_DET`` | |
285 | ||
286 | - 6 | |
287 | ||
288 | - Triggered whenever the motion detection state for one or more of | |
0579e6e3 MCC |
289 | the regions changes. This event has a struct |
290 | :ref:`v4l2_event_motion_det <v4l2-event-motion-det>` | |
291 | associated with it. | |
5377d91f MH |
292 | |
293 | - .. row 8 | |
294 | ||
295 | - ``V4L2_EVENT_PRIVATE_START`` | |
296 | ||
297 | - 0x08000000 | |
298 | ||
299 | - Base event number for driver-private events. | |
300 | ||
301 | ||
302 | ||
303 | .. _v4l2-event-vsync: | |
304 | ||
305 | .. flat-table:: struct v4l2_event_vsync | |
306 | :header-rows: 0 | |
307 | :stub-columns: 0 | |
308 | :widths: 1 1 2 | |
309 | ||
310 | ||
311 | - .. row 1 | |
312 | ||
313 | - __u8 | |
314 | ||
315 | - ``field`` | |
316 | ||
317 | - The upcoming field. See enum :ref:`v4l2_field <v4l2-field>`. | |
318 | ||
319 | ||
320 | ||
321 | .. _v4l2-event-ctrl: | |
322 | ||
323 | .. flat-table:: struct v4l2_event_ctrl | |
324 | :header-rows: 0 | |
325 | :stub-columns: 0 | |
326 | :widths: 1 1 2 1 | |
327 | ||
328 | ||
329 | - .. row 1 | |
330 | ||
331 | - __u32 | |
332 | ||
333 | - ``changes`` | |
334 | ||
0579e6e3 | 335 | - |
5377d91f | 336 | - A bitmask that tells what has changed. See |
0579e6e3 | 337 | :ref:`ctrl-changes-flags`. |
5377d91f MH |
338 | |
339 | - .. row 2 | |
340 | ||
341 | - __u32 | |
342 | ||
343 | - ``type`` | |
344 | ||
0579e6e3 | 345 | - |
5377d91f | 346 | - The type of the control. See enum |
0579e6e3 | 347 | :ref:`v4l2_ctrl_type <v4l2-ctrl-type>`. |
5377d91f MH |
348 | |
349 | - .. row 3 | |
350 | ||
351 | - union (anonymous) | |
352 | ||
0579e6e3 MCC |
353 | - |
354 | - | |
355 | - | |
5377d91f MH |
356 | |
357 | - .. row 4 | |
358 | ||
0579e6e3 | 359 | - |
5377d91f MH |
360 | - __s32 |
361 | ||
362 | - ``value`` | |
363 | ||
364 | - The 32-bit value of the control for 32-bit control types. This is | |
0579e6e3 MCC |
365 | 0 for string controls since the value of a string cannot be passed |
366 | using :ref:`VIDIOC_DQEVENT`. | |
5377d91f MH |
367 | |
368 | - .. row 5 | |
369 | ||
0579e6e3 | 370 | - |
5377d91f MH |
371 | - __s64 |
372 | ||
373 | - ``value64`` | |
374 | ||
375 | - The 64-bit value of the control for 64-bit control types. | |
376 | ||
377 | - .. row 6 | |
378 | ||
379 | - __u32 | |
380 | ||
381 | - ``flags`` | |
382 | ||
0579e6e3 | 383 | - |
5377d91f MH |
384 | - The control flags. See :ref:`control-flags`. |
385 | ||
386 | - .. row 7 | |
387 | ||
388 | - __s32 | |
389 | ||
390 | - ``minimum`` | |
391 | ||
0579e6e3 | 392 | - |
5377d91f | 393 | - The minimum value of the control. See struct |
0579e6e3 | 394 | :ref:`v4l2_queryctrl <v4l2-queryctrl>`. |
5377d91f MH |
395 | |
396 | - .. row 8 | |
397 | ||
398 | - __s32 | |
399 | ||
400 | - ``maximum`` | |
401 | ||
0579e6e3 | 402 | - |
5377d91f | 403 | - The maximum value of the control. See struct |
0579e6e3 | 404 | :ref:`v4l2_queryctrl <v4l2-queryctrl>`. |
5377d91f MH |
405 | |
406 | - .. row 9 | |
407 | ||
408 | - __s32 | |
409 | ||
410 | - ``step`` | |
411 | ||
0579e6e3 | 412 | - |
5377d91f | 413 | - The step value of the control. See struct |
0579e6e3 | 414 | :ref:`v4l2_queryctrl <v4l2-queryctrl>`. |
5377d91f MH |
415 | |
416 | - .. row 10 | |
417 | ||
418 | - __s32 | |
419 | ||
420 | - ``default_value`` | |
421 | ||
0579e6e3 | 422 | - |
5377d91f | 423 | - The default value value of the control. See struct |
0579e6e3 | 424 | :ref:`v4l2_queryctrl <v4l2-queryctrl>`. |
5377d91f MH |
425 | |
426 | ||
427 | ||
428 | .. _v4l2-event-frame-sync: | |
429 | ||
430 | .. flat-table:: struct v4l2_event_frame_sync | |
431 | :header-rows: 0 | |
432 | :stub-columns: 0 | |
433 | :widths: 1 1 2 | |
434 | ||
435 | ||
436 | - .. row 1 | |
437 | ||
438 | - __u32 | |
439 | ||
440 | - ``frame_sequence`` | |
441 | ||
442 | - The sequence number of the frame being received. | |
443 | ||
444 | ||
445 | ||
446 | .. _v4l2-event-src-change: | |
447 | ||
448 | .. flat-table:: struct v4l2_event_src_change | |
449 | :header-rows: 0 | |
450 | :stub-columns: 0 | |
451 | :widths: 1 1 2 | |
452 | ||
453 | ||
454 | - .. row 1 | |
455 | ||
456 | - __u32 | |
457 | ||
458 | - ``changes`` | |
459 | ||
460 | - A bitmask that tells what has changed. See | |
0579e6e3 | 461 | :ref:`src-changes-flags`. |
5377d91f MH |
462 | |
463 | ||
464 | ||
465 | .. _v4l2-event-motion-det: | |
466 | ||
467 | .. flat-table:: struct v4l2_event_motion_det | |
468 | :header-rows: 0 | |
469 | :stub-columns: 0 | |
470 | :widths: 1 1 2 | |
471 | ||
472 | ||
473 | - .. row 1 | |
474 | ||
475 | - __u32 | |
476 | ||
477 | - ``flags`` | |
478 | ||
479 | - Currently only one flag is available: if | |
0579e6e3 MCC |
480 | ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the |
481 | ``frame_sequence`` field is valid, otherwise that field should be | |
482 | ignored. | |
5377d91f MH |
483 | |
484 | - .. row 2 | |
485 | ||
486 | - __u32 | |
487 | ||
488 | - ``frame_sequence`` | |
489 | ||
490 | - The sequence number of the frame being received. Only valid if the | |
0579e6e3 | 491 | ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set. |
5377d91f MH |
492 | |
493 | - .. row 3 | |
494 | ||
495 | - __u32 | |
496 | ||
497 | - ``region_mask`` | |
498 | ||
499 | - The bitmask of the regions that reported motion. There is at least | |
0579e6e3 MCC |
500 | one region. If this field is 0, then no motion was detected at |
501 | all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control | |
502 | (see :ref:`detect-controls`) to assign a different region to | |
503 | each cell in the motion detection grid, then that all cells are | |
504 | automatically assigned to the default region 0. | |
5377d91f MH |
505 | |
506 | ||
507 | ||
508 | .. _ctrl-changes-flags: | |
509 | ||
510 | .. flat-table:: Control Changes | |
511 | :header-rows: 0 | |
512 | :stub-columns: 0 | |
513 | :widths: 3 1 4 | |
514 | ||
515 | ||
516 | - .. row 1 | |
517 | ||
518 | - ``V4L2_EVENT_CTRL_CH_VALUE`` | |
519 | ||
520 | - 0x0001 | |
521 | ||
522 | - This control event was triggered because the value of the control | |
0579e6e3 MCC |
523 | changed. Special cases: Volatile controls do no generate this |
524 | event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` | |
525 | flag set, then this event is sent as well, regardless its value. | |
5377d91f MH |
526 | |
527 | - .. row 2 | |
528 | ||
529 | - ``V4L2_EVENT_CTRL_CH_FLAGS`` | |
530 | ||
531 | - 0x0002 | |
532 | ||
533 | - This control event was triggered because the control flags | |
0579e6e3 | 534 | changed. |
5377d91f MH |
535 | |
536 | - .. row 3 | |
537 | ||
538 | - ``V4L2_EVENT_CTRL_CH_RANGE`` | |
539 | ||
540 | - 0x0004 | |
541 | ||
542 | - This control event was triggered because the minimum, maximum, | |
0579e6e3 | 543 | step or the default value of the control changed. |
5377d91f MH |
544 | |
545 | ||
546 | ||
547 | .. _src-changes-flags: | |
548 | ||
549 | .. flat-table:: Source Changes | |
550 | :header-rows: 0 | |
551 | :stub-columns: 0 | |
552 | :widths: 3 1 4 | |
553 | ||
554 | ||
555 | - .. row 1 | |
556 | ||
557 | - ``V4L2_EVENT_SRC_CH_RESOLUTION`` | |
558 | ||
559 | - 0x0001 | |
560 | ||
561 | - This event gets triggered when a resolution change is detected at | |
0579e6e3 MCC |
562 | an input. This can come from an input connector or from a video |
563 | decoder. | |
5377d91f MH |
564 | |
565 | ||
566 | ||
567 | Return Value | |
568 | ============ | |
569 | ||
570 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
571 | appropriately. The generic error codes are described at the | |
572 | :ref:`Generic Error Codes <gen-errors>` chapter. |