| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _VIDIOC_DQEVENT: |
| 5 |
|
| 6 |
******************** |
| 7 |
ioctl VIDIOC_DQEVENT |
| 8 |
******************** |
| 9 |
|
| 10 |
Name |
| 11 |
==== |
| 12 |
|
| 13 |
VIDIOC_DQEVENT - Dequeue event |
| 14 |
|
| 15 |
Synopsis |
| 16 |
======== |
| 17 |
|
| 18 |
.. c:macro:: VIDIOC_DQEVENT |
| 19 |
|
| 20 |
``int ioctl(int fd, VIDIOC_DQEVENT, struct v4l2_event *argp)`` |
| 21 |
|
| 22 |
Arguments |
| 23 |
========= |
| 24 |
|
| 25 |
``fd`` |
| 26 |
File descriptor returned by :c:func:`open()`. |
| 27 |
|
| 28 |
``argp`` |
| 29 |
Pointer to struct :c:type:`v4l2_event`. |
| 30 |
|
| 31 |
Description |
| 32 |
=========== |
| 33 |
|
| 34 |
Dequeue an event from a video device. No input is required for this |
| 35 |
ioctl. All the fields of the struct :c:type:`v4l2_event` |
| 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 |
.. 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 |
* - ``V4L2_EVENT_CTRL_CH_DIMENSIONS`` |
| 336 |
- 0x0008 |
| 337 |
- This control event was triggered because the dimensions of the |
| 338 |
control changed. Note that the number of dimensions remains the |
| 339 |
same. |
| 340 |
|
| 341 |
|
| 342 |
.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| |
| 343 |
|
| 344 |
.. _src-changes-flags: |
| 345 |
|
| 346 |
.. flat-table:: Source Changes |
| 347 |
:header-rows: 0 |
| 348 |
:stub-columns: 0 |
| 349 |
:widths: 3 1 4 |
| 350 |
|
| 351 |
* - ``V4L2_EVENT_SRC_CH_RESOLUTION`` |
| 352 |
- 0x0001 |
| 353 |
- This event gets triggered when a resolution change is detected at |
| 354 |
an input. This can come from an input connector or from a video |
| 355 |
decoder. Applications will have to query the new resolution (if |
| 356 |
any, the signal may also have been lost). |
| 357 |
|
| 358 |
For stateful decoders follow the guidelines in :ref:`decoder`. |
| 359 |
Video Capture devices have to query the new timings using |
| 360 |
:ref:`VIDIOC_QUERY_DV_TIMINGS` or |
| 361 |
:ref:`VIDIOC_QUERYSTD <VIDIOC_QUERYSTD>`. |
| 362 |
|
| 363 |
*Important*: even if the new video timings appear identical to the old |
| 364 |
ones, receiving this event indicates that there was an issue with the |
| 365 |
video signal and you must stop and restart streaming |
| 366 |
(:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` |
| 367 |
followed by :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`). The reason is |
| 368 |
that many Video Capture devices are not able to recover from a temporary |
| 369 |
loss of signal and so restarting streaming I/O is required in order for |
| 370 |
the hardware to synchronize to the video signal. |
| 371 |
|
| 372 |
Return Value |
| 373 |
============ |
| 374 |
|
| 375 |
On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 376 |
appropriately. The generic error codes are described at the |
| 377 |
:ref:`Generic Error Codes <gen-errors>` chapter. |