Documentation/DocBook/media/v4l/vidioc-dqevent.xml

   1 <refentry id="vidioc-dqevent">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_DQEVENT</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_DQEVENT</refname>
   9     <refpurpose>Dequeue event</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcprototype>
  15         <funcdef>int <function>ioctl</function></funcdef>
  16         <paramdef>int <parameter>fd</parameter></paramdef>
  17         <paramdef>int <parameter>request</parameter></paramdef>
  18         <paramdef>struct v4l2_event
  19 *<parameter>argp</parameter></paramdef>
  20       </funcprototype>
  21     </funcsynopsis>
  22   </refsynopsisdiv>
  23
  24   <refsect1>
  25     <title>Arguments</title>
  26
  27     <variablelist>
  28       <varlistentry>
  29         <term><parameter>fd</parameter></term>
  30         <listitem>
  31           <para>&fd;</para>
  32         </listitem>
  33       </varlistentry>
  34       <varlistentry>
  35         <term><parameter>request</parameter></term>
  36         <listitem>
  37           <para>VIDIOC_DQEVENT</para>
  38         </listitem>
  39       </varlistentry>
  40       <varlistentry>
  41         <term><parameter>argp</parameter></term>
  42         <listitem>
  43           <para></para>
  44         </listitem>
  45       </varlistentry>
  46     </variablelist>
  47   </refsect1>
  48
  49   <refsect1>
  50     <title>Description</title>
  51
  52     <para>Dequeue an event from a video device. No input is required
  53     for this ioctl. All the fields of the &v4l2-event; structure are
  54     filled by the driver. The file handle will also receive exceptions
  55     which the application may get by e.g. using the select system
  56     call.</para>
  57
  58     <table frame="none" pgwide="1" id="v4l2-event">
  59       <title>struct <structname>v4l2_event</structname></title>
  60       <tgroup cols="4">
  61         &cs-str;
  62         <tbody valign="top">
  63           <row>
  64             <entry>__u32</entry>
  65             <entry><structfield>type</structfield></entry>
  66             <entry></entry>
  67             <entry>Type of the event.</entry>
  68           </row>
  69           <row>
  70             <entry>union</entry>
  71             <entry><structfield>u</structfield></entry>
  72             <entry></entry>
  73             <entry></entry>
  74           </row>
  75           <row>
  76             <entry></entry>
  77             <entry>&v4l2-event-vsync;</entry>
  78             <entry><structfield>vsync</structfield></entry>
  79             <entry>Event data for event V4L2_EVENT_VSYNC.
  80             </entry>
  81           </row>
  82           <row>
  83             <entry></entry>
  84             <entry>&v4l2-event-ctrl;</entry>
  85             <entry><structfield>ctrl</structfield></entry>
  86             <entry>Event data for event V4L2_EVENT_CTRL.
  87             </entry>
  88           </row>
  89           <row>
  90             <entry></entry>
  91             <entry>&v4l2-event-frame-sync;</entry>
  92             <entry><structfield>frame_sync</structfield></entry>
  93             <entry>Event data for event V4L2_EVENT_FRAME_SYNC.</entry>
  94           </row>
  95           <row>
  96             <entry></entry>
  97             <entry>&v4l2-event-motion-det;</entry>
  98             <entry><structfield>motion_det</structfield></entry>
  99             <entry>Event data for event V4L2_EVENT_MOTION_DET.</entry>
 100           </row>
 101           <row>
 102             <entry></entry>
 103             <entry>&v4l2-event-src-change;</entry>
 104             <entry><structfield>src_change</structfield></entry>
 105             <entry>Event data for event V4L2_EVENT_SOURCE_CHANGE.</entry>
 106           </row>
 107           <row>
 108             <entry></entry>
 109             <entry>__u8</entry>
 110             <entry><structfield>data</structfield>[64]</entry>
 111             <entry>Event data. Defined by the event type. The union
 112             should be used to define easily accessible type for
 113             events.</entry>
 114           </row>
 115           <row>
 116             <entry>__u32</entry>
 117             <entry><structfield>pending</structfield></entry>
 118             <entry></entry>
 119             <entry>Number of pending events excluding this one.</entry>
 120           </row>
 121           <row>
 122             <entry>__u32</entry>
 123             <entry><structfield>sequence</structfield></entry>
 124             <entry></entry>
 125             <entry>Event sequence number. The sequence number is
 126             incremented for every subscribed event that takes place.
 127             If sequence numbers are not contiguous it means that
 128             events have been lost.
 129             </entry>
 130           </row>
 131           <row>
 132             <entry>struct timespec</entry>
 133             <entry><structfield>timestamp</structfield></entry>
 134             <entry></entry>
 135             <entry>Event timestamp.</entry>
 136           </row>
 137           <row>
 138             <entry>u32</entry>
 139             <entry><structfield>id</structfield></entry>
 140             <entry></entry>
 141             <entry>The ID associated with the event source. If the event does not
 142                 have an associated ID (this depends on the event type), then this
 143                 is 0.</entry>
 144           </row>
 145           <row>
 146             <entry>__u32</entry>
 147             <entry><structfield>reserved</structfield>[8]</entry>
 148             <entry></entry>
 149             <entry>Reserved for future extensions. Drivers must set
 150             the array to zero.</entry>
 151           </row>
 152         </tbody>
 153       </tgroup>
 154     </table>
 155
 156     <table frame="none" pgwide="1" id="v4l2-event-vsync">
 157       <title>struct <structname>v4l2_event_vsync</structname></title>
 158       <tgroup cols="3">
 159         &cs-str;
 160         <tbody valign="top">
 161           <row>
 162             <entry>__u8</entry>
 163             <entry><structfield>field</structfield></entry>
 164             <entry>The upcoming field. See &v4l2-field;.</entry>
 165           </row>
 166         </tbody>
 167       </tgroup>
 168     </table>
 169
 170     <table frame="none" pgwide="1" id="v4l2-event-ctrl">
 171       <title>struct <structname>v4l2_event_ctrl</structname></title>
 172       <tgroup cols="4">
 173         &cs-str;
 174         <tbody valign="top">
 175           <row>
 176             <entry>__u32</entry>
 177             <entry><structfield>changes</structfield></entry>
 178             <entry></entry>
 179             <entry>A bitmask that tells what has changed. See <xref linkend="changes-flags" />.</entry>
 180           </row>
 181           <row>
 182             <entry>__u32</entry>
 183             <entry><structfield>type</structfield></entry>
 184             <entry></entry>
 185             <entry>The type of the control. See &v4l2-ctrl-type;.</entry>
 186           </row>
 187           <row>
 188             <entry>union (anonymous)</entry>
 189             <entry></entry>
 190             <entry></entry>
 191             <entry></entry>
 192           </row>
 193           <row>
 194             <entry></entry>
 195             <entry>__s32</entry>
 196             <entry><structfield>value</structfield></entry>
 197             <entry>The 32-bit value of the control for 32-bit control types.
 198                 This is 0 for string controls since the value of a string
 199                 cannot be passed using &VIDIOC-DQEVENT;.</entry>
 200           </row>
 201           <row>
 202             <entry></entry>
 203             <entry>__s64</entry>
 204             <entry><structfield>value64</structfield></entry>
 205             <entry>The 64-bit value of the control for 64-bit control types.</entry>
 206           </row>
 207           <row>
 208             <entry>__u32</entry>
 209             <entry><structfield>flags</structfield></entry>
 210             <entry></entry>
 211             <entry>The control flags. See <xref linkend="control-flags" />.</entry>
 212           </row>
 213           <row>
 214             <entry>__s32</entry>
 215             <entry><structfield>minimum</structfield></entry>
 216             <entry></entry>
 217             <entry>The minimum value of the control. See &v4l2-queryctrl;.</entry>
 218           </row>
 219           <row>
 220             <entry>__s32</entry>
 221             <entry><structfield>maximum</structfield></entry>
 222             <entry></entry>
 223             <entry>The maximum value of the control. See &v4l2-queryctrl;.</entry>
 224           </row>
 225           <row>
 226             <entry>__s32</entry>
 227             <entry><structfield>step</structfield></entry>
 228             <entry></entry>
 229             <entry>The step value of the control. See &v4l2-queryctrl;.</entry>
 230           </row>
 231           <row>
 232             <entry>__s32</entry>
 233             <entry><structfield>default_value</structfield></entry>
 234             <entry></entry>
 235             <entry>The default value value of the control. See &v4l2-queryctrl;.</entry>
 236           </row>
 237         </tbody>
 238       </tgroup>
 239     </table>
 240
 241     <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
 242       <title>struct <structname>v4l2_event_frame_sync</structname></title>
 243       <tgroup cols="3">
 244         &cs-str;
 245         <tbody valign="top">
 246           <row>
 247             <entry>__u32</entry>
 248             <entry><structfield>frame_sequence</structfield></entry>
 249             <entry>
 250               The sequence number of the frame being received.
 251             </entry>
 252           </row>
 253         </tbody>
 254       </tgroup>
 255     </table>
 256
 257     <table frame="none" pgwide="1" id="v4l2-event-src-change">
 258       <title>struct <structname>v4l2_event_src_change</structname></title>
 259       <tgroup cols="3">
 260         &cs-str;
 261         <tbody valign="top">
 262           <row>
 263             <entry>__u32</entry>
 264             <entry><structfield>changes</structfield></entry>
 265             <entry>
 266               A bitmask that tells what has changed. See <xref linkend="src-changes-flags" />.
 267             </entry>
 268           </row>
 269         </tbody>
 270       </tgroup>
 271     </table>
 272
 273     <table frame="none" pgwide="1" id="v4l2-event-motion-det">
 274       <title>struct <structname>v4l2_event_motion_det</structname></title>
 275       <tgroup cols="3">
 276         &cs-str;
 277         <tbody valign="top">
 278           <row>
 279             <entry>__u32</entry>
 280             <entry><structfield>flags</structfield></entry>
 281             <entry>
 282               Currently only one flag is available: if <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant>
 283               is set, then the <structfield>frame_sequence</structfield> field is valid,
 284               otherwise that field should be ignored.
 285             </entry>
 286           </row>
 287           <row>
 288             <entry>__u32</entry>
 289             <entry><structfield>frame_sequence</structfield></entry>
 290             <entry>
 291               The sequence number of the frame being received. Only valid if the
 292               <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant> flag was set.
 293             </entry>
 294           </row>
 295           <row>
 296             <entry>__u32</entry>
 297             <entry><structfield>region_mask</structfield></entry>
 298             <entry>
 299               The bitmask of the regions that reported motion. There is at least one
 300               region. If this field is 0, then no motion was detected at all.
 301               If there is no <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> control
 302               (see <xref linkend="detect-controls" />) to assign a different region
 303               to each cell in the motion detection grid, then that all cells
 304               are automatically assigned to the default region 0.
 305             </entry>
 306           </row>
 307         </tbody>
 308       </tgroup>
 309     </table>
 310
 311     <table pgwide="1" frame="none" id="changes-flags">
 312       <title>Changes</title>
 313       <tgroup cols="3">
 314         &cs-def;
 315         <tbody valign="top">
 316           <row>
 317             <entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry>
 318             <entry>0x0001</entry>
 319             <entry>This control event was triggered because the value of the control
 320                 changed. Special case: if a button control is pressed, then this
 321                 event is sent as well, even though there is not explicit value
 322                 associated with a button control.</entry>
 323           </row>
 324           <row>
 325             <entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry>
 326             <entry>0x0002</entry>
 327             <entry>This control event was triggered because the control flags
 328                 changed.</entry>
 329           </row>
 330           <row>
 331             <entry><constant>V4L2_EVENT_CTRL_CH_RANGE</constant></entry>
 332             <entry>0x0004</entry>
 333             <entry>This control event was triggered because the minimum,
 334             maximum, step or the default value of the control changed.</entry>
 335           </row>
 336         </tbody>
 337       </tgroup>
 338     </table>
 339
 340     <table pgwide="1" frame="none" id="src-changes-flags">
 341       <title>Source Changes</title>
 342       <tgroup cols="3">
 343         &cs-def;
 344         <tbody valign="top">
 345           <row>
 346             <entry><constant>V4L2_EVENT_SRC_CH_RESOLUTION</constant></entry>
 347             <entry>0x0001</entry>
 348             <entry>This event gets triggered when a resolution change is
 349             detected at an input. This can come from an input connector or
 350             from a video decoder.
 351             </entry>
 352           </row>
 353         </tbody>
 354       </tgroup>
 355     </table>
 356   </refsect1>
 357   <refsect1>
 358     &return-value;
 359   </refsect1>
 360 </refentry>