Documentation/userspace-api/media/v4l/vidioc-dqevent.rst

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