1<refentry id="vidioc-dqevent"> 2 <refmeta> 3 <refentrytitle>ioctl VIDIOC_DQEVENT</refentrytitle> 4 &manvol; 5 </refmeta> 6 7 <refnamediv> 8 <refname>VIDIOC_DQEVENT</refname> 9 <refpurpose>Dequeue event</refpurpose> 10 </refnamediv> 11 12 <refsynopsisdiv> 13 <funcsynopsis> 14 <funcprototype> 15 <funcdef>int <function>ioctl</function></funcdef> 16 <paramdef>int <parameter>fd</parameter></paramdef> 17 <paramdef>int <parameter>request</parameter></paramdef> 18 <paramdef>struct v4l2_event 19*<parameter>argp</parameter></paramdef> 20 </funcprototype> 21 </funcsynopsis> 22 </refsynopsisdiv> 23 24 <refsect1> 25 <title>Arguments</title> 26 27 <variablelist> 28 <varlistentry> 29 <term><parameter>fd</parameter></term> 30 <listitem> 31 <para>&fd;</para> 32 </listitem> 33 </varlistentry> 34 <varlistentry> 35 <term><parameter>request</parameter></term> 36 <listitem> 37 <para>VIDIOC_DQEVENT</para> 38 </listitem> 39 </varlistentry> 40 <varlistentry> 41 <term><parameter>argp</parameter></term> 42 <listitem> 43 <para></para> 44 </listitem> 45 </varlistentry> 46 </variablelist> 47 </refsect1> 48 49 <refsect1> 50 <title>Description</title> 51 52 <para>Dequeue an event from a video device. No input is required 53 for this ioctl. All the fields of the &v4l2-event; structure are 54 filled by the driver. The file handle will also receive exceptions 55 which the application may get by e.g. using the select system 56 call.</para> 57 58 <table frame="none" pgwide="1" id="v4l2-event"> 59 <title>struct <structname>v4l2_event</structname></title> 60 <tgroup cols="4"> 61 &cs-str; 62 <tbody valign="top"> 63 <row> 64 <entry>__u32</entry> 65 <entry><structfield>type</structfield></entry> 66 <entry></entry> 67 <entry>Type of the event.</entry> 68 </row> 69 <row> 70 <entry>union</entry> 71 <entry><structfield>u</structfield></entry> 72 <entry></entry> 73 <entry></entry> 74 </row> 75 <row> 76 <entry></entry> 77 <entry>&v4l2-event-vsync;</entry> 78 <entry><structfield>vsync</structfield></entry> 79 <entry>Event data for event <constant>V4L2_EVENT_VSYNC</constant>. 80 </entry> 81 </row> 82 <row> 83 <entry></entry> 84 <entry>&v4l2-event-ctrl;</entry> 85 <entry><structfield>ctrl</structfield></entry> 86 <entry>Event data for event <constant>V4L2_EVENT_CTRL</constant>. 87 </entry> 88 </row> 89 <row> 90 <entry></entry> 91 <entry>&v4l2-event-frame-sync;</entry> 92 <entry><structfield>frame_sync</structfield></entry> 93 <entry>Event data for event 94 <constant>V4L2_EVENT_FRAME_SYNC</constant>.</entry> 95 </row> 96 <row> 97 <entry></entry> 98 <entry>&v4l2-event-motion-det;</entry> 99 <entry><structfield>motion_det</structfield></entry> 100 <entry>Event data for event V4L2_EVENT_MOTION_DET.</entry> 101 </row> 102 <row> 103 <entry></entry> 104 <entry>&v4l2-event-src-change;</entry> 105 <entry><structfield>src_change</structfield></entry> 106 <entry>Event data for event V4L2_EVENT_SOURCE_CHANGE.</entry> 107 </row> 108 <row> 109 <entry></entry> 110 <entry>__u8</entry> 111 <entry><structfield>data</structfield>[64]</entry> 112 <entry>Event data. Defined by the event type. The union 113 should be used to define easily accessible type for 114 events.</entry> 115 </row> 116 <row> 117 <entry>__u32</entry> 118 <entry><structfield>pending</structfield></entry> 119 <entry></entry> 120 <entry>Number of pending events excluding this one.</entry> 121 </row> 122 <row> 123 <entry>__u32</entry> 124 <entry><structfield>sequence</structfield></entry> 125 <entry></entry> 126 <entry>Event sequence number. The sequence number is 127 incremented for every subscribed event that takes place. 128 If sequence numbers are not contiguous it means that 129 events have been lost. 130 </entry> 131 </row> 132 <row> 133 <entry>struct timespec</entry> 134 <entry><structfield>timestamp</structfield></entry> 135 <entry></entry> 136 <entry>Event timestamp.</entry> 137 </row> 138 <row> 139 <entry>u32</entry> 140 <entry><structfield>id</structfield></entry> 141 <entry></entry> 142 <entry>The ID associated with the event source. If the event does not 143 have an associated ID (this depends on the event type), then this 144 is 0.</entry> 145 </row> 146 <row> 147 <entry>__u32</entry> 148 <entry><structfield>reserved</structfield>[8]</entry> 149 <entry></entry> 150 <entry>Reserved for future extensions. Drivers must set 151 the array to zero.</entry> 152 </row> 153 </tbody> 154 </tgroup> 155 </table> 156 157 <table frame="none" pgwide="1" id="v4l2-event-vsync"> 158 <title>struct <structname>v4l2_event_vsync</structname></title> 159 <tgroup cols="3"> 160 &cs-str; 161 <tbody valign="top"> 162 <row> 163 <entry>__u8</entry> 164 <entry><structfield>field</structfield></entry> 165 <entry>The upcoming field. See &v4l2-field;.</entry> 166 </row> 167 </tbody> 168 </tgroup> 169 </table> 170 171 <table frame="none" pgwide="1" id="v4l2-event-ctrl"> 172 <title>struct <structname>v4l2_event_ctrl</structname></title> 173 <tgroup cols="4"> 174 &cs-str; 175 <tbody valign="top"> 176 <row> 177 <entry>__u32</entry> 178 <entry><structfield>changes</structfield></entry> 179 <entry></entry> 180 <entry>A bitmask that tells what has changed. See <xref linkend="changes-flags" />.</entry> 181 </row> 182 <row> 183 <entry>__u32</entry> 184 <entry><structfield>type</structfield></entry> 185 <entry></entry> 186 <entry>The type of the control. See &v4l2-ctrl-type;.</entry> 187 </row> 188 <row> 189 <entry>union (anonymous)</entry> 190 <entry></entry> 191 <entry></entry> 192 <entry></entry> 193 </row> 194 <row> 195 <entry></entry> 196 <entry>__s32</entry> 197 <entry><structfield>value</structfield></entry> 198 <entry>The 32-bit value of the control for 32-bit control types. 199 This is 0 for string controls since the value of a string 200 cannot be passed using &VIDIOC-DQEVENT;.</entry> 201 </row> 202 <row> 203 <entry></entry> 204 <entry>__s64</entry> 205 <entry><structfield>value64</structfield></entry> 206 <entry>The 64-bit value of the control for 64-bit control types.</entry> 207 </row> 208 <row> 209 <entry>__u32</entry> 210 <entry><structfield>flags</structfield></entry> 211 <entry></entry> 212 <entry>The control flags. See <xref linkend="control-flags" />.</entry> 213 </row> 214 <row> 215 <entry>__s32</entry> 216 <entry><structfield>minimum</structfield></entry> 217 <entry></entry> 218 <entry>The minimum value of the control. See &v4l2-queryctrl;.</entry> 219 </row> 220 <row> 221 <entry>__s32</entry> 222 <entry><structfield>maximum</structfield></entry> 223 <entry></entry> 224 <entry>The maximum value of the control. See &v4l2-queryctrl;.</entry> 225 </row> 226 <row> 227 <entry>__s32</entry> 228 <entry><structfield>step</structfield></entry> 229 <entry></entry> 230 <entry>The step value of the control. See &v4l2-queryctrl;.</entry> 231 </row> 232 <row> 233 <entry>__s32</entry> 234 <entry><structfield>default_value</structfield></entry> 235 <entry></entry> 236 <entry>The default value value of the control. See &v4l2-queryctrl;.</entry> 237 </row> 238 </tbody> 239 </tgroup> 240 </table> 241 242 <table frame="none" pgwide="1" id="v4l2-event-frame-sync"> 243 <title>struct <structname>v4l2_event_frame_sync</structname></title> 244 <tgroup cols="3"> 245 &cs-str; 246 <tbody valign="top"> 247 <row> 248 <entry>__u32</entry> 249 <entry><structfield>frame_sequence</structfield></entry> 250 <entry> 251 The sequence number of the frame being received. 252 </entry> 253 </row> 254 </tbody> 255 </tgroup> 256 </table> 257 258 <table frame="none" pgwide="1" id="v4l2-event-src-change"> 259 <title>struct <structname>v4l2_event_src_change</structname></title> 260 <tgroup cols="3"> 261 &cs-str; 262 <tbody valign="top"> 263 <row> 264 <entry>__u32</entry> 265 <entry><structfield>changes</structfield></entry> 266 <entry> 267 A bitmask that tells what has changed. See <xref linkend="src-changes-flags" />. 268 </entry> 269 </row> 270 </tbody> 271 </tgroup> 272 </table> 273 274 <table frame="none" pgwide="1" id="v4l2-event-motion-det"> 275 <title>struct <structname>v4l2_event_motion_det</structname></title> 276 <tgroup cols="3"> 277 &cs-str; 278 <tbody valign="top"> 279 <row> 280 <entry>__u32</entry> 281 <entry><structfield>flags</structfield></entry> 282 <entry> 283 Currently only one flag is available: if <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant> 284 is set, then the <structfield>frame_sequence</structfield> field is valid, 285 otherwise that field should be ignored. 286 </entry> 287 </row> 288 <row> 289 <entry>__u32</entry> 290 <entry><structfield>frame_sequence</structfield></entry> 291 <entry> 292 The sequence number of the frame being received. Only valid if the 293 <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant> flag was set. 294 </entry> 295 </row> 296 <row> 297 <entry>__u32</entry> 298 <entry><structfield>region_mask</structfield></entry> 299 <entry> 300 The bitmask of the regions that reported motion. There is at least one 301 region. If this field is 0, then no motion was detected at all. 302 If there is no <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> control 303 (see <xref linkend="detect-controls" />) to assign a different region 304 to each cell in the motion detection grid, then that all cells 305 are automatically assigned to the default region 0. 306 </entry> 307 </row> 308 </tbody> 309 </tgroup> 310 </table> 311 312 <table pgwide="1" frame="none" id="changes-flags"> 313 <title>Changes</title> 314 <tgroup cols="3"> 315 &cs-def; 316 <tbody valign="top"> 317 <row> 318 <entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry> 319 <entry>0x0001</entry> 320 <entry>This control event was triggered because the value of the control 321 changed. Special case: if a button control is pressed, then this 322 event is sent as well, even though there is not explicit value 323 associated with a button control.</entry> 324 </row> 325 <row> 326 <entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry> 327 <entry>0x0002</entry> 328 <entry>This control event was triggered because the control flags 329 changed.</entry> 330 </row> 331 <row> 332 <entry><constant>V4L2_EVENT_CTRL_CH_RANGE</constant></entry> 333 <entry>0x0004</entry> 334 <entry>This control event was triggered because the minimum, 335 maximum, step or the default value of the control changed.</entry> 336 </row> 337 </tbody> 338 </tgroup> 339 </table> 340 341 <table pgwide="1" frame="none" id="src-changes-flags"> 342 <title>Source Changes</title> 343 <tgroup cols="3"> 344 &cs-def; 345 <tbody valign="top"> 346 <row> 347 <entry><constant>V4L2_EVENT_SRC_CH_RESOLUTION</constant></entry> 348 <entry>0x0001</entry> 349 <entry>This event gets triggered when a resolution change is 350 detected at an input. This can come from an input connector or 351 from a video decoder. 352 </entry> 353 </row> 354 </tbody> 355 </tgroup> 356 </table> 357 </refsect1> 358 <refsect1> 359 &return-value; 360 </refsect1> 361</refentry> 362