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