Documentation/userspace-api/media/v4l/vidioc-dqevent.rst

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