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