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