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

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