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