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

   1 .. -*- coding: utf-8; mode: rst -*-
   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 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_event *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_DQEVENT
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 Dequeue an event from a video device. No input is required for this
  37 ioctl. All the fields of the struct :ref:`v4l2_event <v4l2-event>`
  38 structure are filled by the driver. The file handle will also receive
  39 exceptions which the application may get by e.g. using the select system
  40 call.
  41
  42
  43 .. _v4l2-event:
  44
  45 .. tabularcolumns:: |p{3.0cm}|p{4.3cm}|p{2.5cm}|p{7.7cm}|
  46
  47 .. cssclass: longtable
  48
  49 .. flat-table:: struct v4l2_event
  50     :header-rows:  0
  51     :stub-columns: 0
  52     :widths:       1 1 2 1
  53
  54
  55     -  .. row 1
  56
  57        -  __u32
  58
  59        -  ``type``
  60
  61        -
  62        -  Type of the event, see :ref:`event-type`.
  63
  64     -  .. row 2
  65
  66        -  union
  67
  68        -  ``u``
  69
  70        -
  71        -
  72
  73     -  .. row 3
  74
  75        -
  76        -  struct :ref:`v4l2_event_vsync <v4l2-event-vsync>`
  77
  78        -  ``vsync``
  79
  80        -  Event data for event ``V4L2_EVENT_VSYNC``.
  81
  82     -  .. row 4
  83
  84        -
  85        -  struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>`
  86
  87        -  ``ctrl``
  88
  89        -  Event data for event ``V4L2_EVENT_CTRL``.
  90
  91     -  .. row 5
  92
  93        -
  94        -  struct :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
  95
  96        -  ``frame_sync``
  97
  98        -  Event data for event ``V4L2_EVENT_FRAME_SYNC``.
  99
 100     -  .. row 6
 101
 102        -
 103        -  struct :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
 104
 105        -  ``motion_det``
 106
 107        -  Event data for event V4L2_EVENT_MOTION_DET.
 108
 109     -  .. row 7
 110
 111        -
 112        -  struct :ref:`v4l2_event_src_change <v4l2-event-src-change>`
 113
 114        -  ``src_change``
 115
 116        -  Event data for event V4L2_EVENT_SOURCE_CHANGE.
 117
 118     -  .. row 8
 119
 120        -
 121        -  __u8
 122
 123        -  ``data``\ [64]
 124
 125        -  Event data. Defined by the event type. The union should be used to
 126           define easily accessible type for events.
 127
 128     -  .. row 9
 129
 130        -  __u32
 131
 132        -  ``pending``
 133
 134        -
 135        -  Number of pending events excluding this one.
 136
 137     -  .. row 10
 138
 139        -  __u32
 140
 141        -  ``sequence``
 142
 143        -
 144        -  Event sequence number. The sequence number is incremented for
 145           every subscribed event that takes place. If sequence numbers are
 146           not contiguous it means that events have been lost.
 147
 148     -  .. row 11
 149
 150        -  struct timespec
 151
 152        -  ``timestamp``
 153
 154        -
 155        -  Event timestamp. The timestamp has been taken from the
 156           ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2,
 157           use :c:func:`clock_gettime(2)`.
 158
 159     -  .. row 12
 160
 161        -  u32
 162
 163        -  ``id``
 164
 165        -
 166        -  The ID associated with the event source. If the event does not
 167           have an associated ID (this depends on the event type), then this
 168           is 0.
 169
 170     -  .. row 13
 171
 172        -  __u32
 173
 174        -  ``reserved``\ [8]
 175
 176        -
 177        -  Reserved for future extensions. Drivers must set the array to
 178           zero.
 179
 180
 181
 182 .. _event-type:
 183
 184 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 185
 186 .. cssclass:: longtable
 187
 188 .. flat-table:: Event Types
 189     :header-rows:  0
 190     :stub-columns: 0
 191     :widths:       3 1 4
 192
 193
 194     -  .. row 1
 195
 196        -  ``V4L2_EVENT_ALL``
 197
 198        -  0
 199
 200        -  All events. V4L2_EVENT_ALL is valid only for
 201           VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.
 202
 203     -  .. row 2
 204
 205        -  ``V4L2_EVENT_VSYNC``
 206
 207        -  1
 208
 209        -  This event is triggered on the vertical sync. This event has a
 210           struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` associated
 211           with it.
 212
 213     -  .. row 3
 214
 215        -  ``V4L2_EVENT_EOS``
 216
 217        -  2
 218
 219        -  This event is triggered when the end of a stream is reached. This
 220           is typically used with MPEG decoders to report to the application
 221           when the last of the MPEG stream has been decoded.
 222
 223     -  .. row 4
 224
 225        -  ``V4L2_EVENT_CTRL``
 226
 227        -  3
 228
 229        -  This event requires that the ``id`` matches the control ID from
 230           which you want to receive events. This event is triggered if the
 231           control's value changes, if a button control is pressed or if the
 232           control's flags change. This event has a struct
 233           :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` associated with it.
 234           This struct contains much of the same information as struct
 235           :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct
 236           :ref:`v4l2_control <v4l2-control>`.
 237
 238           If the event is generated due to a call to
 239           :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or
 240           :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the
 241           event will *not* be sent to the file handle that called the ioctl
 242           function. This prevents nasty feedback loops. If you *do* want to
 243           get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
 244           flag.
 245
 246           This event type will ensure that no information is lost when more
 247           events are raised than there is room internally. In that case the
 248           struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` of the
 249           second-oldest event is kept, but the ``changes`` field of the
 250           second-oldest event is ORed with the ``changes`` field of the
 251           oldest event.
 252
 253     -  .. row 5
 254
 255        -  ``V4L2_EVENT_FRAME_SYNC``
 256
 257        -  4
 258
 259        -  Triggered immediately when the reception of a frame has begun.
 260           This event has a struct
 261           :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
 262           associated with it.
 263
 264           If the hardware needs to be stopped in the case of a buffer
 265           underrun it might not be able to generate this event. In such
 266           cases the ``frame_sequence`` field in struct
 267           :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` will not
 268           be incremented. This causes two consecutive frame sequence numbers
 269           to have n times frame interval in between them.
 270
 271     -  .. row 6
 272
 273        -  ``V4L2_EVENT_SOURCE_CHANGE``
 274
 275        -  5
 276
 277        -  This event is triggered when a source parameter change is detected
 278           during runtime by the video device. It can be a runtime resolution
 279           change triggered by a video decoder or the format change happening
 280           on an input connector. This event requires that the ``id`` matches
 281           the input index (when used with a video device node) or the pad
 282           index (when used with a subdevice node) from which you want to
 283           receive events.
 284
 285           This event has a struct
 286           :ref:`v4l2_event_src_change <v4l2-event-src-change>`
 287           associated with it. The ``changes`` bitfield denotes what has
 288           changed for the subscribed pad. If multiple events occurred before
 289           application could dequeue them, then the changes will have the
 290           ORed value of all the events generated.
 291
 292     -  .. row 7
 293
 294        -  ``V4L2_EVENT_MOTION_DET``
 295
 296        -  6
 297
 298        -  Triggered whenever the motion detection state for one or more of
 299           the regions changes. This event has a struct
 300           :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
 301           associated with it.
 302
 303     -  .. row 8
 304
 305        -  ``V4L2_EVENT_PRIVATE_START``
 306
 307        -  0x08000000
 308
 309        -  Base event number for driver-private events.
 310
 311
 312
 313 .. _v4l2-event-vsync:
 314
 315 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 316
 317 .. flat-table:: struct v4l2_event_vsync
 318     :header-rows:  0
 319     :stub-columns: 0
 320     :widths:       1 1 2
 321
 322
 323     -  .. row 1
 324
 325        -  __u8
 326
 327        -  ``field``
 328
 329        -  The upcoming field. See enum :ref:`v4l2_field <v4l2-field>`.
 330
 331
 332
 333 .. _v4l2-event-ctrl:
 334
 335 .. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}|
 336
 337 .. flat-table:: struct v4l2_event_ctrl
 338     :header-rows:  0
 339     :stub-columns: 0
 340     :widths:       1 1 2 1
 341
 342
 343     -  .. row 1
 344
 345        -  __u32
 346
 347        -  ``changes``
 348
 349        -
 350        -  A bitmask that tells what has changed. See
 351           :ref:`ctrl-changes-flags`.
 352
 353     -  .. row 2
 354
 355        -  __u32
 356
 357        -  ``type``
 358
 359        -
 360        -  The type of the control. See enum
 361           :ref:`v4l2_ctrl_type <v4l2-ctrl-type>`.
 362
 363     -  .. row 3
 364
 365        -  union (anonymous)
 366
 367        -
 368        -
 369        -
 370
 371     -  .. row 4
 372
 373        -
 374        -  __s32
 375
 376        -  ``value``
 377
 378        -  The 32-bit value of the control for 32-bit control types. This is
 379           0 for string controls since the value of a string cannot be passed
 380           using :ref:`VIDIOC_DQEVENT`.
 381
 382     -  .. row 5
 383
 384        -
 385        -  __s64
 386
 387        -  ``value64``
 388
 389        -  The 64-bit value of the control for 64-bit control types.
 390
 391     -  .. row 6
 392
 393        -  __u32
 394
 395        -  ``flags``
 396
 397        -
 398        -  The control flags. See :ref:`control-flags`.
 399
 400     -  .. row 7
 401
 402        -  __s32
 403
 404        -  ``minimum``
 405
 406        -
 407        -  The minimum value of the control. See struct
 408           :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
 409
 410     -  .. row 8
 411
 412        -  __s32
 413
 414        -  ``maximum``
 415
 416        -
 417        -  The maximum value of the control. See struct
 418           :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
 419
 420     -  .. row 9
 421
 422        -  __s32
 423
 424        -  ``step``
 425
 426        -
 427        -  The step value of the control. See struct
 428           :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
 429
 430     -  .. row 10
 431
 432        -  __s32
 433
 434        -  ``default_value``
 435
 436        -
 437        -  The default value value of the control. See struct
 438           :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
 439
 440
 441
 442 .. _v4l2-event-frame-sync:
 443
 444 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 445
 446 .. flat-table:: struct v4l2_event_frame_sync
 447     :header-rows:  0
 448     :stub-columns: 0
 449     :widths:       1 1 2
 450
 451
 452     -  .. row 1
 453
 454        -  __u32
 455
 456        -  ``frame_sequence``
 457
 458        -  The sequence number of the frame being received.
 459
 460
 461
 462 .. _v4l2-event-src-change:
 463
 464 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 465
 466 .. flat-table:: struct v4l2_event_src_change
 467     :header-rows:  0
 468     :stub-columns: 0
 469     :widths:       1 1 2
 470
 471
 472     -  .. row 1
 473
 474        -  __u32
 475
 476        -  ``changes``
 477
 478        -  A bitmask that tells what has changed. See
 479           :ref:`src-changes-flags`.
 480
 481
 482
 483 .. _v4l2-event-motion-det:
 484
 485 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 486
 487 .. flat-table:: struct v4l2_event_motion_det
 488     :header-rows:  0
 489     :stub-columns: 0
 490     :widths:       1 1 2
 491
 492
 493     -  .. row 1
 494
 495        -  __u32
 496
 497        -  ``flags``
 498
 499        -  Currently only one flag is available: if
 500           ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the
 501           ``frame_sequence`` field is valid, otherwise that field should be
 502           ignored.
 503
 504     -  .. row 2
 505
 506        -  __u32
 507
 508        -  ``frame_sequence``
 509
 510        -  The sequence number of the frame being received. Only valid if the
 511           ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set.
 512
 513     -  .. row 3
 514
 515        -  __u32
 516
 517        -  ``region_mask``
 518
 519        -  The bitmask of the regions that reported motion. There is at least
 520           one region. If this field is 0, then no motion was detected at
 521           all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control
 522           (see :ref:`detect-controls`) to assign a different region to
 523           each cell in the motion detection grid, then that all cells are
 524           automatically assigned to the default region 0.
 525
 526
 527
 528 .. _ctrl-changes-flags:
 529
 530 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 531
 532 .. flat-table:: Control Changes
 533     :header-rows:  0
 534     :stub-columns: 0
 535     :widths:       3 1 4
 536
 537
 538     -  .. row 1
 539
 540        -  ``V4L2_EVENT_CTRL_CH_VALUE``
 541
 542        -  0x0001
 543
 544        -  This control event was triggered because the value of the control
 545           changed. Special cases: Volatile controls do no generate this
 546           event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
 547           flag set, then this event is sent as well, regardless its value.
 548
 549     -  .. row 2
 550
 551        -  ``V4L2_EVENT_CTRL_CH_FLAGS``
 552
 553        -  0x0002
 554
 555        -  This control event was triggered because the control flags
 556           changed.
 557
 558     -  .. row 3
 559
 560        -  ``V4L2_EVENT_CTRL_CH_RANGE``
 561
 562        -  0x0004
 563
 564        -  This control event was triggered because the minimum, maximum,
 565           step or the default value of the control changed.
 566
 567
 568
 569 .. _src-changes-flags:
 570
 571 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 572
 573 .. flat-table:: Source Changes
 574     :header-rows:  0
 575     :stub-columns: 0
 576     :widths:       3 1 4
 577
 578
 579     -  .. row 1
 580
 581        -  ``V4L2_EVENT_SRC_CH_RESOLUTION``
 582
 583        -  0x0001
 584
 585        -  This event gets triggered when a resolution change is detected at
 586           an input. This can come from an input connector or from a video
 587           decoder.
 588
 589
 590 Return Value
 591 ============
 592
 593 On success 0 is returned, on error -1 and the ``errno`` variable is set
 594 appropriately. The generic error codes are described at the
 595 :ref:`Generic Error Codes <gen-errors>` chapter.