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