[deliverable/linux.git] / Documentation / linux_tv / media / v4l / vidioc-dqevent.rst

.. -*- coding: utf-8; mode: rst -*-

.. _VIDIOC_DQEVENT:

********************
ioctl VIDIOC_DQEVENT
********************

*man VIDIOC_DQEVENT(2)*

Dequeue event


Synopsis
========

.. c:function:: int ioctl( int fd, int request, struct v4l2_event *argp )

Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_DQEVENT

``argp``


Description
===========

Dequeue an event from a video device. No input is required for this
ioctl. All the fields of the struct :ref:`v4l2_event <v4l2-event>`
structure are filled by the driver. The file handle will also receive
exceptions which the application may get by e.g. using the select system
call.


.. _v4l2-event:

.. flat-table:: struct v4l2_event
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2 1


    -  .. row 1

       -  __u32

       -  ``type``

       -  
       -  Type of the event, see :ref:`event-type`.

    -  .. row 2

       -  union

       -  ``u``

       -  
       -  

    -  .. row 3

       -  
       -  struct :ref:`v4l2_event_vsync <v4l2-event-vsync>`

       -  ``vsync``

       -  Event data for event ``V4L2_EVENT_VSYNC``.

    -  .. row 4

       -  
       -  struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>`

       -  ``ctrl``

       -  Event data for event ``V4L2_EVENT_CTRL``.

    -  .. row 5

       -  
       -  struct :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`

       -  ``frame_sync``

       -  Event data for event ``V4L2_EVENT_FRAME_SYNC``.

    -  .. row 6

       -  
       -  struct :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`

       -  ``motion_det``

       -  Event data for event V4L2_EVENT_MOTION_DET.

    -  .. row 7

       -  
       -  struct :ref:`v4l2_event_src_change <v4l2-event-src-change>`

       -  ``src_change``

       -  Event data for event V4L2_EVENT_SOURCE_CHANGE.

    -  .. row 8

       -  
       -  __u8

       -  ``data``\ [64]

       -  Event data. Defined by the event type. The union should be used to
          define easily accessible type for events.

    -  .. row 9

       -  __u32

       -  ``pending``

       -  
       -  Number of pending events excluding this one.

    -  .. row 10

       -  __u32

       -  ``sequence``

       -  
       -  Event sequence number. The sequence number is incremented for
          every subscribed event that takes place. If sequence numbers are
          not contiguous it means that events have been lost.

    -  .. row 11

       -  struct timespec

       -  ``timestamp``

       -  
       -  Event timestamp. The timestamp has been taken from the
          ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2,
          use :c:func:`clock_gettime(2)`.

    -  .. row 12

       -  u32

       -  ``id``

       -  
       -  The ID associated with the event source. If the event does not
          have an associated ID (this depends on the event type), then this
          is 0.

    -  .. row 13

       -  __u32

       -  ``reserved``\ [8]

       -  
       -  Reserved for future extensions. Drivers must set the array to
          zero.


.. _event-type:

.. flat-table:: Event Types
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_EVENT_ALL``

       -  0

       -  All events. V4L2_EVENT_ALL is valid only for
          VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.

    -  .. row 2

       -  ``V4L2_EVENT_VSYNC``

       -  1

       -  This event is triggered on the vertical sync. This event has a
          struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` associated
          with it.

    -  .. row 3

       -  ``V4L2_EVENT_EOS``

       -  2

       -  This event is triggered when the end of a stream is reached. This
          is typically used with MPEG decoders to report to the application
          when the last of the MPEG stream has been decoded.

    -  .. row 4

       -  ``V4L2_EVENT_CTRL``

       -  3

       -  This event requires that the ``id`` matches the control ID from
          which you want to receive events. This event is triggered if the
          control's value changes, if a button control is pressed or if the
          control's flags change. This event has a struct
          :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` associated with it.
          This struct contains much of the same information as struct
          :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct
          :ref:`v4l2_control <v4l2-control>`.

          If the event is generated due to a call to
          :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or
          :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the
          event will *not* be sent to the file handle that called the ioctl
          function. This prevents nasty feedback loops. If you *do* want to
          get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
          flag.

          This event type will ensure that no information is lost when more
          events are raised than there is room internally. In that case the
          struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` of the
          second-oldest event is kept, but the ``changes`` field of the
          second-oldest event is ORed with the ``changes`` field of the
          oldest event.

    -  .. row 5

       -  ``V4L2_EVENT_FRAME_SYNC``

       -  4

       -  Triggered immediately when the reception of a frame has begun.
          This event has a struct
          :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
          associated with it.

          If the hardware needs to be stopped in the case of a buffer
          underrun it might not be able to generate this event. In such
          cases the ``frame_sequence`` field in struct
          :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` will not
          be incremented. This causes two consecutive frame sequence numbers
          to have n times frame interval in between them.

    -  .. row 6

       -  ``V4L2_EVENT_SOURCE_CHANGE``

       -  5

       -  This event is triggered when a source parameter change is detected
          during runtime by the video device. It can be a runtime resolution
          change triggered by a video decoder or the format change happening
          on an input connector. This event requires that the ``id`` matches
          the input index (when used with a video device node) or the pad
          index (when used with a subdevice node) from which you want to
          receive events.

          This event has a struct
          :ref:`v4l2_event_src_change <v4l2-event-src-change>`
          associated with it. The ``changes`` bitfield denotes what has
          changed for the subscribed pad. If multiple events occurred before
          application could dequeue them, then the changes will have the
          ORed value of all the events generated.

    -  .. row 7

       -  ``V4L2_EVENT_MOTION_DET``

       -  6

       -  Triggered whenever the motion detection state for one or more of
          the regions changes. This event has a struct
          :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
          associated with it.

    -  .. row 8

       -  ``V4L2_EVENT_PRIVATE_START``

       -  0x08000000

       -  Base event number for driver-private events.


.. _v4l2-event-vsync:

.. flat-table:: struct v4l2_event_vsync
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u8

       -  ``field``

       -  The upcoming field. See enum :ref:`v4l2_field <v4l2-field>`.


.. _v4l2-event-ctrl:

.. flat-table:: struct v4l2_event_ctrl
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2 1


    -  .. row 1

       -  __u32

       -  ``changes``

       -  
       -  A bitmask that tells what has changed. See
          :ref:`ctrl-changes-flags`.

    -  .. row 2

       -  __u32

       -  ``type``

       -  
       -  The type of the control. See enum
          :ref:`v4l2_ctrl_type <v4l2-ctrl-type>`.

    -  .. row 3

       -  union (anonymous)

       -  
       -  
       -  

    -  .. row 4

       -  
       -  __s32

       -  ``value``

       -  The 32-bit value of the control for 32-bit control types. This is
          0 for string controls since the value of a string cannot be passed
          using :ref:`VIDIOC_DQEVENT`.

    -  .. row 5

       -  
       -  __s64

       -  ``value64``

       -  The 64-bit value of the control for 64-bit control types.

    -  .. row 6

       -  __u32

       -  ``flags``

       -  
       -  The control flags. See :ref:`control-flags`.

    -  .. row 7

       -  __s32

       -  ``minimum``

       -  
       -  The minimum value of the control. See struct
          :ref:`v4l2_queryctrl <v4l2-queryctrl>`.

    -  .. row 8

       -  __s32

       -  ``maximum``

       -  
       -  The maximum value of the control. See struct
          :ref:`v4l2_queryctrl <v4l2-queryctrl>`.

    -  .. row 9

       -  __s32

       -  ``step``

       -  
       -  The step value of the control. See struct
          :ref:`v4l2_queryctrl <v4l2-queryctrl>`.

    -  .. row 10

       -  __s32

       -  ``default_value``

       -  
       -  The default value value of the control. See struct
          :ref:`v4l2_queryctrl <v4l2-queryctrl>`.


.. _v4l2-event-frame-sync:

.. flat-table:: struct v4l2_event_frame_sync
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u32

       -  ``frame_sequence``

       -  The sequence number of the frame being received.


.. _v4l2-event-src-change:

.. flat-table:: struct v4l2_event_src_change
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u32

       -  ``changes``

       -  A bitmask that tells what has changed. See
          :ref:`src-changes-flags`.


.. _v4l2-event-motion-det:

.. flat-table:: struct v4l2_event_motion_det
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u32

       -  ``flags``

       -  Currently only one flag is available: if
          ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the
          ``frame_sequence`` field is valid, otherwise that field should be
          ignored.

    -  .. row 2

       -  __u32

       -  ``frame_sequence``

       -  The sequence number of the frame being received. Only valid if the
          ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set.

    -  .. row 3

       -  __u32

       -  ``region_mask``

       -  The bitmask of the regions that reported motion. There is at least
          one region. If this field is 0, then no motion was detected at
          all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control
          (see :ref:`detect-controls`) to assign a different region to
          each cell in the motion detection grid, then that all cells are
          automatically assigned to the default region 0.


.. _ctrl-changes-flags:

.. flat-table:: Control Changes
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_EVENT_CTRL_CH_VALUE``

       -  0x0001

       -  This control event was triggered because the value of the control
          changed. Special cases: Volatile controls do no generate this
          event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
          flag set, then this event is sent as well, regardless its value.

    -  .. row 2

       -  ``V4L2_EVENT_CTRL_CH_FLAGS``

       -  0x0002

       -  This control event was triggered because the control flags
          changed.

    -  .. row 3

       -  ``V4L2_EVENT_CTRL_CH_RANGE``

       -  0x0004

       -  This control event was triggered because the minimum, maximum,
          step or the default value of the control changed.


.. _src-changes-flags:

.. flat-table:: Source Changes
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_EVENT_SRC_CH_RESOLUTION``

       -  0x0001

       -  This event gets triggered when a resolution change is detected at
          an input. This can come from an input connector or from a video
          decoder.


Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


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