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