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