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