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 | ||
41d80465 MCC |
18 | .. c:function:: int ioctl( int fd, VIDIOC_DQEVENT, struct v4l2_event *argp ) |
19 | :name: VIDIOC_DQEVENT | |
5377d91f | 20 | |
586027ce | 21 | |
15e7d615 | 22 | Arguments |
5377d91f MH |
23 | ========= |
24 | ||
25 | ``fd`` | |
26 | File descriptor returned by :ref:`open() <func-open>`. | |
27 | ||
5377d91f MH |
28 | ``argp`` |
29 | ||
30 | ||
15e7d615 | 31 | Description |
5377d91f MH |
32 | =========== |
33 | ||
34 | Dequeue an event from a video device. No input is required for this | |
e8be7e97 | 35 | ioctl. All the fields of the struct :c:type:`v4l2_event` |
5377d91f MH |
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 | ||
0e9411ac MCC |
41 | .. tabularcolumns:: |p{3.0cm}|p{4.3cm}|p{2.5cm}|p{7.7cm}| |
42 | ||
e8be7e97 | 43 | .. c:type:: v4l2_event |
fa92b04d | 44 | |
0e9411ac | 45 | .. cssclass: longtable |
5bd4bb78 | 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 | - |
e8be7e97 | 74 | - struct :c:type:`v4l2_event_vsync` |
5377d91f MH |
75 | |
76 | - ``vsync`` | |
77 | ||
78 | - Event data for event ``V4L2_EVENT_VSYNC``. | |
79 | ||
80 | - .. row 4 | |
81 | ||
0579e6e3 | 82 | - |
e8be7e97 | 83 | - struct :c:type:`v4l2_event_ctrl` |
5377d91f MH |
84 | |
85 | - ``ctrl`` | |
86 | ||
87 | - Event data for event ``V4L2_EVENT_CTRL``. | |
88 | ||
89 | - .. row 5 | |
90 | ||
0579e6e3 | 91 | - |
e8be7e97 | 92 | - struct :c:type:`v4l2_event_frame_sync` |
5377d91f MH |
93 | |
94 | - ``frame_sync`` | |
95 | ||
96 | - Event data for event ``V4L2_EVENT_FRAME_SYNC``. | |
97 | ||
98 | - .. row 6 | |
99 | ||
0579e6e3 | 100 | - |
e8be7e97 | 101 | - struct :c:type:`v4l2_event_motion_det` |
5377d91f MH |
102 | |
103 | - ``motion_det`` | |
104 | ||
105 | - Event data for event V4L2_EVENT_MOTION_DET. | |
106 | ||
107 | - .. row 7 | |
108 | ||
0579e6e3 | 109 | - |
e8be7e97 | 110 | - struct :c:type:`v4l2_event_src_change` |
5377d91f MH |
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 | 154 | ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2, |
39b6b900 | 155 | use :c:func:`clock_gettime`. |
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 | ||
5bd4bb78 MCC |
180 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
181 | ||
ef76c068 MCC |
182 | .. cssclass:: longtable |
183 | ||
fa92b04d MCC |
184 | .. _event-type: |
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 | |
e8be7e97 | 208 | struct :c:type:`v4l2_event_vsync` associated |
0579e6e3 | 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 | |
e8be7e97 | 231 | :c:type:`v4l2_event_ctrl` associated with it. |
0579e6e3 MCC |
232 | This struct contains much of the same information as struct |
233 | :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct | |
e8be7e97 | 234 | :c:type:`v4l2_control`. |
0579e6e3 MCC |
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 | |
e8be7e97 | 246 | struct :c:type:`v4l2_event_ctrl` of the |
0579e6e3 MCC |
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 | 258 | This event has a struct |
e8be7e97 | 259 | :c:type:`v4l2_event_frame_sync` |
0579e6e3 | 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 | |
e8be7e97 | 265 | :c:type:`v4l2_event_frame_sync` will not |
0579e6e3 MCC |
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 | |
e8be7e97 | 284 | :c:type:`v4l2_event_src_change` |
0579e6e3 MCC |
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 | 297 | the regions changes. This event has a struct |
e8be7e97 | 298 | :c:type:`v4l2_event_motion_det` |
0579e6e3 | 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 | ||
5bd4bb78 MCC |
311 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
312 | ||
e8be7e97 | 313 | .. c:type:: v4l2_event_vsync |
fa92b04d | 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 | ||
56683d7d | 327 | - The upcoming field. See enum :c:type:`v4l2_field`. |
5377d91f MH |
328 | |
329 | ||
330 | ||
0e9411ac | 331 | .. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}| |
5bd4bb78 | 332 | |
e8be7e97 | 333 | .. c:type:: v4l2_event_ctrl |
fa92b04d | 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 |
ffa0441e | 359 | :c: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 | ||
5bd4bb78 MCC |
440 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
441 | ||
e8be7e97 | 442 | .. c:type:: v4l2_event_frame_sync |
fa92b04d | 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 | ||
5bd4bb78 MCC |
460 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
461 | ||
e8be7e97 | 462 | .. c:type:: v4l2_event_src_change |
fa92b04d | 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 | ||
5bd4bb78 MCC |
481 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
482 | ||
e8be7e97 | 483 | .. c:type:: v4l2_event_motion_det |
fa92b04d | 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 | ||
5bd4bb78 MCC |
526 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
527 | ||
fa92b04d MCC |
528 | .. _ctrl-changes-flags: |
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 | ||
5bd4bb78 MCC |
567 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
568 | ||
fa92b04d MCC |
569 | .. _src-changes-flags: |
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. |