Documentation/media/uapi/v4l/vidioc-dqevent.rst

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