1.. -*- coding: utf-8; mode: rst -*- 2 3.. _VIDIOC_DQEVENT: 4 5******************** 6ioctl VIDIOC_DQEVENT 7******************** 8 9Name 10==== 11 12VIDIOC_DQEVENT - Dequeue event 13 14 15Synopsis 16======== 17 18.. c:function:: int ioctl( int fd, VIDIOC_DQEVENT, struct v4l2_event *argp ) 19 :name: VIDIOC_DQEVENT 20 21 22Arguments 23========= 24 25``fd`` 26 File descriptor returned by :ref:`open() <func-open>`. 27 28``argp`` 29 Pointer to struct :c:type:`v4l2_event`. 30 31 32Description 33=========== 34 35Dequeue an event from a video device. No input is required for this 36ioctl. All the fields of the struct :c:type:`v4l2_event` 37structure are filled by the driver. The file handle will also receive 38exceptions which the application may get by e.g. using the select system 39call. 40 41 42.. tabularcolumns:: |p{3.0cm}|p{4.4cm}|p{2.4cm}|p{7.7cm}| 43 44.. c:type:: v4l2_event 45 46.. cssclass: longtable 47 48.. flat-table:: struct v4l2_event 49 :header-rows: 0 50 :stub-columns: 0 51 :widths: 1 1 2 1 52 53 * - __u32 54 - ``type`` 55 - 56 - Type of the event, see :ref:`event-type`. 57 * - union 58 - ``u`` 59 - 60 - 61 * - 62 - struct :c:type:`v4l2_event_vsync` 63 - ``vsync`` 64 - Event data for event ``V4L2_EVENT_VSYNC``. 65 * - 66 - struct :c:type:`v4l2_event_ctrl` 67 - ``ctrl`` 68 - Event data for event ``V4L2_EVENT_CTRL``. 69 * - 70 - struct :c:type:`v4l2_event_frame_sync` 71 - ``frame_sync`` 72 - Event data for event ``V4L2_EVENT_FRAME_SYNC``. 73 * - 74 - struct :c:type:`v4l2_event_motion_det` 75 - ``motion_det`` 76 - Event data for event V4L2_EVENT_MOTION_DET. 77 * - 78 - struct :c:type:`v4l2_event_src_change` 79 - ``src_change`` 80 - Event data for event V4L2_EVENT_SOURCE_CHANGE. 81 * - 82 - __u8 83 - ``data``\ [64] 84 - Event data. Defined by the event type. The union should be used to 85 define easily accessible type for events. 86 * - __u32 87 - ``pending`` 88 - 89 - Number of pending events excluding this one. 90 * - __u32 91 - ``sequence`` 92 - 93 - Event sequence number. The sequence number is incremented for 94 every subscribed event that takes place. If sequence numbers are 95 not contiguous it means that events have been lost. 96 * - struct timespec 97 - ``timestamp`` 98 - 99 - Event timestamp. The timestamp has been taken from the 100 ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2, 101 use :c:func:`clock_gettime`. 102 * - u32 103 - ``id`` 104 - 105 - The ID associated with the event source. If the event does not 106 have an associated ID (this depends on the event type), then this 107 is 0. 108 * - __u32 109 - ``reserved``\ [8] 110 - 111 - Reserved for future extensions. Drivers must set the array to 112 zero. 113 114 115 116.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 117 118.. cssclass:: longtable 119 120.. _event-type: 121 122.. flat-table:: Event Types 123 :header-rows: 0 124 :stub-columns: 0 125 :widths: 3 1 4 126 127 * - ``V4L2_EVENT_ALL`` 128 - 0 129 - All events. V4L2_EVENT_ALL is valid only for 130 VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. 131 * - ``V4L2_EVENT_VSYNC`` 132 - 1 133 - This event is triggered on the vertical sync. This event has a 134 struct :c:type:`v4l2_event_vsync` associated 135 with it. 136 * - ``V4L2_EVENT_EOS`` 137 - 2 138 - This event is triggered when the end of a stream is reached. This 139 is typically used with MPEG decoders to report to the application 140 when the last of the MPEG stream has been decoded. 141 * - ``V4L2_EVENT_CTRL`` 142 - 3 143 - This event requires that the ``id`` matches the control ID from 144 which you want to receive events. This event is triggered if the 145 control's value changes, if a button control is pressed or if the 146 control's flags change. This event has a struct 147 :c:type:`v4l2_event_ctrl` associated with it. 148 This struct contains much of the same information as struct 149 :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct 150 :c:type:`v4l2_control`. 151 152 If the event is generated due to a call to 153 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or 154 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the 155 event will *not* be sent to the file handle that called the ioctl 156 function. This prevents nasty feedback loops. If you *do* want to 157 get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK`` 158 flag. 159 160 This event type will ensure that no information is lost when more 161 events are raised than there is room internally. In that case the 162 struct :c:type:`v4l2_event_ctrl` of the 163 second-oldest event is kept, but the ``changes`` field of the 164 second-oldest event is ORed with the ``changes`` field of the 165 oldest event. 166 * - ``V4L2_EVENT_FRAME_SYNC`` 167 - 4 168 - Triggered immediately when the reception of a frame has begun. 169 This event has a struct 170 :c:type:`v4l2_event_frame_sync` 171 associated with it. 172 173 If the hardware needs to be stopped in the case of a buffer 174 underrun it might not be able to generate this event. In such 175 cases the ``frame_sequence`` field in struct 176 :c:type:`v4l2_event_frame_sync` will not 177 be incremented. This causes two consecutive frame sequence numbers 178 to have n times frame interval in between them. 179 * - ``V4L2_EVENT_SOURCE_CHANGE`` 180 - 5 181 - This event is triggered when a source parameter change is detected 182 during runtime by the video device. It can be a runtime resolution 183 change triggered by a video decoder or the format change happening 184 on an input connector. This event requires that the ``id`` matches 185 the input index (when used with a video device node) or the pad 186 index (when used with a subdevice node) from which you want to 187 receive events. 188 189 This event has a struct 190 :c:type:`v4l2_event_src_change` 191 associated with it. The ``changes`` bitfield denotes what has 192 changed for the subscribed pad. If multiple events occurred before 193 application could dequeue them, then the changes will have the 194 ORed value of all the events generated. 195 * - ``V4L2_EVENT_MOTION_DET`` 196 - 6 197 - Triggered whenever the motion detection state for one or more of 198 the regions changes. This event has a struct 199 :c:type:`v4l2_event_motion_det` 200 associated with it. 201 * - ``V4L2_EVENT_PRIVATE_START`` 202 - 0x08000000 203 - Base event number for driver-private events. 204 205 206 207.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 208 209.. c:type:: v4l2_event_vsync 210 211.. flat-table:: struct v4l2_event_vsync 212 :header-rows: 0 213 :stub-columns: 0 214 :widths: 1 1 2 215 216 * - __u8 217 - ``field`` 218 - The upcoming field. See enum :c:type:`v4l2_field`. 219 220 221 222.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}| 223 224.. c:type:: v4l2_event_ctrl 225 226.. flat-table:: struct v4l2_event_ctrl 227 :header-rows: 0 228 :stub-columns: 0 229 :widths: 1 1 2 1 230 231 * - __u32 232 - ``changes`` 233 - 234 - A bitmask that tells what has changed. See 235 :ref:`ctrl-changes-flags`. 236 * - __u32 237 - ``type`` 238 - 239 - The type of the control. See enum 240 :c:type:`v4l2_ctrl_type`. 241 * - union (anonymous) 242 - 243 - 244 - 245 * - 246 - __s32 247 - ``value`` 248 - The 32-bit value of the control for 32-bit control types. This is 249 0 for string controls since the value of a string cannot be passed 250 using :ref:`VIDIOC_DQEVENT`. 251 * - 252 - __s64 253 - ``value64`` 254 - The 64-bit value of the control for 64-bit control types. 255 * - __u32 256 - ``flags`` 257 - 258 - The control flags. See :ref:`control-flags`. 259 * - __s32 260 - ``minimum`` 261 - 262 - The minimum value of the control. See struct 263 :ref:`v4l2_queryctrl <v4l2-queryctrl>`. 264 * - __s32 265 - ``maximum`` 266 - 267 - The maximum value of the control. See struct 268 :ref:`v4l2_queryctrl <v4l2-queryctrl>`. 269 * - __s32 270 - ``step`` 271 - 272 - The step value of the control. See struct 273 :ref:`v4l2_queryctrl <v4l2-queryctrl>`. 274 * - __s32 275 - ``default_value`` 276 - 277 - The default value value of the control. See struct 278 :ref:`v4l2_queryctrl <v4l2-queryctrl>`. 279 280 281 282.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 283 284.. c:type:: v4l2_event_frame_sync 285 286.. flat-table:: struct v4l2_event_frame_sync 287 :header-rows: 0 288 :stub-columns: 0 289 :widths: 1 1 2 290 291 * - __u32 292 - ``frame_sequence`` 293 - The sequence number of the frame being received. 294 295 296 297.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 298 299.. c:type:: v4l2_event_src_change 300 301.. flat-table:: struct v4l2_event_src_change 302 :header-rows: 0 303 :stub-columns: 0 304 :widths: 1 1 2 305 306 * - __u32 307 - ``changes`` 308 - A bitmask that tells what has changed. See 309 :ref:`src-changes-flags`. 310 311 312 313.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 314 315.. c:type:: v4l2_event_motion_det 316 317.. flat-table:: struct v4l2_event_motion_det 318 :header-rows: 0 319 :stub-columns: 0 320 :widths: 1 1 2 321 322 * - __u32 323 - ``flags`` 324 - Currently only one flag is available: if 325 ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the 326 ``frame_sequence`` field is valid, otherwise that field should be 327 ignored. 328 * - __u32 329 - ``frame_sequence`` 330 - The sequence number of the frame being received. Only valid if the 331 ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set. 332 * - __u32 333 - ``region_mask`` 334 - The bitmask of the regions that reported motion. There is at least 335 one region. If this field is 0, then no motion was detected at 336 all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control 337 (see :ref:`detect-controls`) to assign a different region to 338 each cell in the motion detection grid, then that all cells are 339 automatically assigned to the default region 0. 340 341 342 343.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 344 345.. _ctrl-changes-flags: 346 347.. flat-table:: Control Changes 348 :header-rows: 0 349 :stub-columns: 0 350 :widths: 3 1 4 351 352 * - ``V4L2_EVENT_CTRL_CH_VALUE`` 353 - 0x0001 354 - This control event was triggered because the value of the control 355 changed. Special cases: Volatile controls do no generate this 356 event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` 357 flag set, then this event is sent as well, regardless its value. 358 * - ``V4L2_EVENT_CTRL_CH_FLAGS`` 359 - 0x0002 360 - This control event was triggered because the control flags 361 changed. 362 * - ``V4L2_EVENT_CTRL_CH_RANGE`` 363 - 0x0004 364 - This control event was triggered because the minimum, maximum, 365 step or the default value of the control changed. 366 367 368 369.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 370 371.. _src-changes-flags: 372 373.. flat-table:: Source Changes 374 :header-rows: 0 375 :stub-columns: 0 376 :widths: 3 1 4 377 378 * - ``V4L2_EVENT_SRC_CH_RESOLUTION`` 379 - 0x0001 380 - This event gets triggered when a resolution change is detected at 381 an input. This can come from an input connector or from a video 382 decoder. 383 384 385Return Value 386============ 387 388On success 0 is returned, on error -1 and the ``errno`` variable is set 389appropriately. The generic error codes are described at the 390:ref:`Generic Error Codes <gen-errors>` chapter. 391