1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>ioctl VIDIOC_DQEVENT</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="user-func.html" title="Appendix A. Function Reference"><link rel="prev" href="vidioc-decoder-cmd.html" title="ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD"><link rel="next" href="vidioc-dv-timings-cap.html" title="ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ioctl VIDIOC_DQEVENT</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="vidioc-decoder-cmd.html">Prev</a> </td><th width="60%" align="center">Appendix A. Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="vidioc-dv-timings-cap.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="vidioc-dqevent"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>VIDIOC_DQEVENT — Dequeue event</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">ioctl</b>(</code></td><td>int <var class="pdparam">fd</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">request</var>, </td></tr><tr><td> </td><td>struct v4l2_event 2*<var class="pdparam">argp</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp1112335092"></a><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>fd</code></em></span></dt><dd><p>File descriptor returned by <a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a>.</p></dd><dt><span class="term"><em class="parameter"><code>request</code></em></span></dt><dd><p>VIDIOC_DQEVENT</p></dd><dt><span class="term"><em class="parameter"><code>argp</code></em></span></dt><dd><p></p></dd></dl></div></div><div class="refsect1"><a name="idp1112339140"></a><h2>Description</h2><p>Dequeue an event from a video device. No input is required 3 for this ioctl. All the fields of the struct <a class="link" href="vidioc-dqevent.html#v4l2-event" title="Table A.12. struct v4l2_event">v4l2_event</a> structure are 4 filled by the driver. The file handle will also receive exceptions 5 which the application may get by e.g. using the select system 6 call.</p><div class="table"><a name="v4l2-event"></a><p class="title"><b>Table A.12. struct <span class="structname">v4l2_event</span></b></p><div class="table-contents"><table summary="struct v4l2_event" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"><col></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>type</code></em></td><td valign="top"> </td><td valign="top">Type of the event, see <a class="xref" href="vidioc-dqevent.html#event-type" title="Table A.13. Event Types">Table A.13, “Event Types”</a>.</td></tr><tr><td valign="top">union</td><td valign="top"><em class="structfield"><code>u</code></em></td><td valign="top"> </td><td valign="top"> </td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="vidioc-dqevent.html#v4l2-event-vsync" title="Table A.14. struct v4l2_event_vsync">v4l2_event_vsync</a></td><td valign="top"><em class="structfield"><code>vsync</code></em></td><td valign="top">Event data for event <code class="constant">V4L2_EVENT_VSYNC</code>. 7 </td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="vidioc-dqevent.html#v4l2-event-ctrl" title="Table A.15. struct v4l2_event_ctrl">v4l2_event_ctrl</a></td><td valign="top"><em class="structfield"><code>ctrl</code></em></td><td valign="top">Event data for event <code class="constant">V4L2_EVENT_CTRL</code>. 8 </td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="vidioc-dqevent.html#v4l2-event-frame-sync" title="Table A.16. struct v4l2_event_frame_sync">v4l2_event_frame_sync</a></td><td valign="top"><em class="structfield"><code>frame_sync</code></em></td><td valign="top">Event data for event 9 <code class="constant">V4L2_EVENT_FRAME_SYNC</code>.</td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="vidioc-dqevent.html#v4l2-event-motion-det" title="Table A.18. struct v4l2_event_motion_det">v4l2_event_motion_det</a></td><td valign="top"><em class="structfield"><code>motion_det</code></em></td><td valign="top">Event data for event V4L2_EVENT_MOTION_DET.</td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="vidioc-dqevent.html#v4l2-event-src-change" title="Table A.17. struct v4l2_event_src_change">v4l2_event_src_change</a></td><td valign="top"><em class="structfield"><code>src_change</code></em></td><td valign="top">Event data for event V4L2_EVENT_SOURCE_CHANGE.</td></tr><tr><td valign="top"> </td><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>data</code></em>[64]</td><td valign="top">Event data. Defined by the event type. The union 10 should be used to define easily accessible type for 11 events.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>pending</code></em></td><td valign="top"> </td><td valign="top">Number of pending events excluding this one.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>sequence</code></em></td><td valign="top"> </td><td valign="top">Event sequence number. The sequence number is 12 incremented for every subscribed event that takes place. 13 If sequence numbers are not contiguous it means that 14 events have been lost. 15 </td></tr><tr><td valign="top">struct timespec</td><td valign="top"><em class="structfield"><code>timestamp</code></em></td><td valign="top"> </td><td valign="top">Event timestamp.</td></tr><tr><td valign="top">u32</td><td valign="top"><em class="structfield"><code>id</code></em></td><td valign="top"> </td><td valign="top">The ID associated with the event source. If the event does not 16 have an associated ID (this depends on the event type), then this 17 is 0.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>reserved</code></em>[8]</td><td valign="top"> </td><td valign="top">Reserved for future extensions. Drivers must set 18 the array to zero.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="event-type"></a><p class="title"><b>Table A.13. Event Types</b></p><div class="table-contents"><table summary="Event Types" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_EVENT_ALL</code></td><td valign="top">0</td><td valign="top">All events. V4L2_EVENT_ALL is valid only for 19 VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. 20 </td></tr><tr><td valign="top"><code class="constant">V4L2_EVENT_VSYNC</code></td><td valign="top">1</td><td valign="top">This event is triggered on the vertical sync. 21 This event has a struct <a class="link" href="vidioc-dqevent.html#v4l2-event-vsync" title="Table A.14. struct v4l2_event_vsync">v4l2_event_vsync</a> associated with it. 22 </td></tr><tr><td valign="top"><code class="constant">V4L2_EVENT_EOS</code></td><td valign="top">2</td><td valign="top">This event is triggered when the end of a stream is reached. 23 This is typically used with MPEG decoders to report to the application 24 when the last of the MPEG stream has been decoded. 25 </td></tr><tr><td valign="top"><code class="constant">V4L2_EVENT_CTRL</code></td><td valign="top">3</td><td valign="top"><p>This event requires that the <em class="structfield"><code>id</code></em> 26 matches the control ID from which you want to receive events. 27 This event is triggered if the control's value changes, if a 28 button control is pressed or if the control's flags change. 29 This event has a struct <a class="link" href="vidioc-dqevent.html#v4l2-event-ctrl" title="Table A.15. struct v4l2_event_ctrl">v4l2_event_ctrl</a> associated with it. This struct 30 contains much of the same information as struct <a class="link" href="vidioc-queryctrl.html#v4l2-queryctrl" title="Table A.95. struct v4l2_queryctrl">v4l2_queryctrl</a> and 31 struct <a class="link" href="vidioc-g-ctrl.html#v4l2-control" title="Table A.56. struct v4l2_control">v4l2_control</a>.</p> 32 33 <p>If the event is generated due to a call to <a class="link" href="vidioc-g-ctrl.html" title="ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL"><code class="constant">VIDIOC_S_CTRL</code></a> or 34 <a class="link" href="vidioc-g-ext-ctrls.html" title="ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS"><code class="constant">VIDIOC_S_EXT_CTRLS</code></a>, then the event will <span class="emphasis"><em>not</em></span> be sent to 35 the file handle that called the ioctl function. This prevents 36 nasty feedback loops. If you <span class="emphasis"><em>do</em></span> want to get the 37 event, then set the <code class="constant">V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK</code> 38 flag. 39 </p> 40 41 <p>This event type will ensure that no information is lost when 42 more events are raised than there is room internally. In that 43 case the struct <a class="link" href="vidioc-dqevent.html#v4l2-event-ctrl" title="Table A.15. struct v4l2_event_ctrl">v4l2_event_ctrl</a> of the second-oldest event is kept, 44 but the <em class="structfield"><code>changes</code></em> field of the 45 second-oldest event is ORed with the <em class="structfield"><code>changes</code></em> 46 field of the oldest event.</p> 47 </td></tr><tr><td valign="top"><code class="constant">V4L2_EVENT_FRAME_SYNC</code></td><td valign="top">4</td><td valign="top"> 48 <p>Triggered immediately when the reception of a 49 frame has begun. This event has a 50 struct <a class="link" href="vidioc-dqevent.html#v4l2-event-frame-sync" title="Table A.16. struct v4l2_event_frame_sync">v4l2_event_frame_sync</a> associated with it.</p> 51 52 <p>If the hardware needs to be stopped in the case of a 53 buffer underrun it might not be able to generate this event. 54 In such cases the <em class="structfield"><code>frame_sequence</code></em> 55 field in struct <a class="link" href="vidioc-dqevent.html#v4l2-event-frame-sync" title="Table A.16. struct v4l2_event_frame_sync">v4l2_event_frame_sync</a> will not be incremented. This 56 causes two consecutive frame sequence numbers to have n times 57 frame interval in between them.</p> 58 </td></tr><tr><td valign="top"><code class="constant">V4L2_EVENT_SOURCE_CHANGE</code></td><td valign="top">5</td><td valign="top"> 59 <p>This event is triggered when a source parameter change is 60 detected during runtime by the video device. It can be a 61 runtime resolution change triggered by a video decoder or the 62 format change happening on an input connector. 63 This event requires that the <em class="structfield"><code>id</code></em> 64 matches the input index (when used with a video device node) 65 or the pad index (when used with a subdevice node) from which 66 you want to receive events.</p> 67 68 <p>This event has a struct <a class="link" href="vidioc-dqevent.html#v4l2-event-src-change" title="Table A.17. struct v4l2_event_src_change">v4l2_event_src_change</a> associated 69 with it. The <em class="structfield"><code>changes</code></em> bitfield denotes 70 what has changed for the subscribed pad. If multiple events 71 occurred before application could dequeue them, then the changes 72 will have the ORed value of all the events generated.</p> 73 </td></tr><tr><td valign="top"><code class="constant">V4L2_EVENT_MOTION_DET</code></td><td valign="top">6</td><td valign="top"> 74 <p>Triggered whenever the motion detection state for one or more of the regions 75 changes. This event has a struct <a class="link" href="vidioc-dqevent.html#v4l2-event-motion-det" title="Table A.18. struct v4l2_event_motion_det">v4l2_event_motion_det</a> associated with it.</p> 76 </td></tr><tr><td valign="top"><code class="constant">V4L2_EVENT_PRIVATE_START</code></td><td valign="top">0x08000000</td><td valign="top">Base event number for driver-private events.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-event-vsync"></a><p class="title"><b>Table A.14. struct <span class="structname">v4l2_event_vsync</span></b></p><div class="table-contents"><table summary="struct v4l2_event_vsync" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>field</code></em></td><td valign="top">The upcoming field. See enum <a class="link" href="field-order.html#v4l2-field" title="Table 3.9. enum v4l2_field">v4l2_field</a>.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-event-ctrl"></a><p class="title"><b>Table A.15. struct <span class="structname">v4l2_event_ctrl</span></b></p><div class="table-contents"><table summary="struct v4l2_event_ctrl" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"><col></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>changes</code></em></td><td valign="top"> </td><td valign="top">A bitmask that tells what has changed. See <a class="xref" href="vidioc-dqevent.html#ctrl-changes-flags" title="Table A.19. Control Changes">Table A.19, “Control Changes”</a>.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>type</code></em></td><td valign="top"> </td><td valign="top">The type of the control. See enum <a class="link" href="vidioc-queryctrl.html#v4l2-ctrl-type" title="Table A.98. enum v4l2_ctrl_type">v4l2_ctrl_type</a>.</td></tr><tr><td valign="top">union (anonymous)</td><td valign="top"> </td><td valign="top"> </td><td valign="top"> </td></tr><tr><td valign="top"> </td><td valign="top">__s32</td><td valign="top"><em class="structfield"><code>value</code></em></td><td valign="top">The 32-bit value of the control for 32-bit control types. 77 This is 0 for string controls since the value of a string 78 cannot be passed using <a class="link" href="vidioc-dqevent.html" title="ioctl VIDIOC_DQEVENT"><code class="constant">VIDIOC_DQEVENT</code></a>.</td></tr><tr><td valign="top"> </td><td valign="top">__s64</td><td valign="top"><em class="structfield"><code>value64</code></em></td><td valign="top">The 64-bit value of the control for 64-bit control types.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>flags</code></em></td><td valign="top"> </td><td valign="top">The control flags. See <a class="xref" href="vidioc-queryctrl.html#control-flags" title="Table A.99. Control Flags">Table A.99, “Control Flags”</a>.</td></tr><tr><td valign="top">__s32</td><td valign="top"><em class="structfield"><code>minimum</code></em></td><td valign="top"> </td><td valign="top">The minimum value of the control. See struct <a class="link" href="vidioc-queryctrl.html#v4l2-queryctrl" title="Table A.95. struct v4l2_queryctrl">v4l2_queryctrl</a>.</td></tr><tr><td valign="top">__s32</td><td valign="top"><em class="structfield"><code>maximum</code></em></td><td valign="top"> </td><td valign="top">The maximum value of the control. See struct <a class="link" href="vidioc-queryctrl.html#v4l2-queryctrl" title="Table A.95. struct v4l2_queryctrl">v4l2_queryctrl</a>.</td></tr><tr><td valign="top">__s32</td><td valign="top"><em class="structfield"><code>step</code></em></td><td valign="top"> </td><td valign="top">The step value of the control. See struct <a class="link" href="vidioc-queryctrl.html#v4l2-queryctrl" title="Table A.95. struct v4l2_queryctrl">v4l2_queryctrl</a>.</td></tr><tr><td valign="top">__s32</td><td valign="top"><em class="structfield"><code>default_value</code></em></td><td valign="top"> </td><td valign="top">The default value value of the control. See struct <a class="link" href="vidioc-queryctrl.html#v4l2-queryctrl" title="Table A.95. struct v4l2_queryctrl">v4l2_queryctrl</a>.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-event-frame-sync"></a><p class="title"><b>Table A.16. struct <span class="structname">v4l2_event_frame_sync</span></b></p><div class="table-contents"><table summary="struct v4l2_event_frame_sync" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>frame_sequence</code></em></td><td valign="top"> 79 The sequence number of the frame being received. 80 </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-event-src-change"></a><p class="title"><b>Table A.17. struct <span class="structname">v4l2_event_src_change</span></b></p><div class="table-contents"><table summary="struct v4l2_event_src_change" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>changes</code></em></td><td valign="top"> 81 A bitmask that tells what has changed. See <a class="xref" href="vidioc-dqevent.html#src-changes-flags" title="Table A.20. Source Changes">Table A.20, “Source Changes”</a>. 82 </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-event-motion-det"></a><p class="title"><b>Table A.18. struct <span class="structname">v4l2_event_motion_det</span></b></p><div class="table-contents"><table summary="struct v4l2_event_motion_det" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>flags</code></em></td><td valign="top"> 83 Currently only one flag is available: if <code class="constant">V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</code> 84 is set, then the <em class="structfield"><code>frame_sequence</code></em> field is valid, 85 otherwise that field should be ignored. 86 </td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>frame_sequence</code></em></td><td valign="top"> 87 The sequence number of the frame being received. Only valid if the 88 <code class="constant">V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</code> flag was set. 89 </td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>region_mask</code></em></td><td valign="top"> 90 The bitmask of the regions that reported motion. There is at least one 91 region. If this field is 0, then no motion was detected at all. 92 If there is no <code class="constant">V4L2_CID_DETECT_MD_REGION_GRID</code> control 93 (see <a class="xref" href="extended-controls.html#detect-controls" title="Detect Control Reference">the section called “Detect Control Reference”</a>) to assign a different region 94 to each cell in the motion detection grid, then that all cells 95 are automatically assigned to the default region 0. 96 </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="ctrl-changes-flags"></a><p class="title"><b>Table A.19. Control Changes</b></p><div class="table-contents"><table summary="Control Changes" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_EVENT_CTRL_CH_VALUE</code></td><td valign="top">0x0001</td><td valign="top">This control event was triggered because the value of the control 97 changed. Special cases: Volatile controls do no generate this event; 98 If a control has the <code class="constant">V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</code> 99 flag set, then this event is sent as well, regardless its value.</td></tr><tr><td valign="top"><code class="constant">V4L2_EVENT_CTRL_CH_FLAGS</code></td><td valign="top">0x0002</td><td valign="top">This control event was triggered because the control flags 100 changed.</td></tr><tr><td valign="top"><code class="constant">V4L2_EVENT_CTRL_CH_RANGE</code></td><td valign="top">0x0004</td><td valign="top">This control event was triggered because the minimum, 101 maximum, step or the default value of the control changed.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="src-changes-flags"></a><p class="title"><b>Table A.20. Source Changes</b></p><div class="table-contents"><table summary="Source Changes" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_EVENT_SRC_CH_RESOLUTION</code></td><td valign="top">0x0001</td><td valign="top">This event gets triggered when a resolution change is 102 detected at an input. This can come from an input connector or 103 from a video decoder. 104 </td></tr></tbody></table></div></div><br class="table-break"></div><div class="refsect1"><a name="idp1112431236"></a><h2>Return Value</h2><p>On success <span class="returnvalue">0</span> is returned, on error <span class="returnvalue">-1</span> and the <code class="varname">errno</code> variable is set appropriately. The generic error codes are described at the <a class="link" href="gen_errors.html#gen-errors" title="Table 19.1. Generic error codes">Generic Error Codes</a> chapter.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="vidioc-decoder-cmd.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-func.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="vidioc-dv-timings-cap.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</td></tr></table></div></body></html> 105