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