Documentation/DocBook/media/v4l/io.xml

   1   <title>Input/Output</title>
   2
   3   <para>The V4L2 API defines several different methods to read from or
   4 write to a device. All drivers exchanging data with applications must
   5 support at least one of them.</para>
   6
   7   <para>The classic I/O method using the <function>read()</function>
   8 and <function>write()</function> function is automatically selected
   9 after opening a V4L2 device. When the driver does not support this
  10 method attempts to read or write will fail at any time.</para>
  11
  12   <para>Other methods must be negotiated. To select the streaming I/O
  13 method with memory mapped or user buffers applications call the
  14 &VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined
  15 yet.</para>
  16
  17   <para>Video overlay can be considered another I/O method, although
  18 the application does not directly receive the image data. It is
  19 selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl.
  20 For more information see <xref linkend="overlay" />.</para>
  21
  22   <para>Generally exactly one I/O method, including overlay, is
  23 associated with each file descriptor. The only exceptions are
  24 applications not exchanging data with a driver ("panel applications",
  25 see <xref linkend="open" />) and drivers permitting simultaneous video capturing
  26 and overlay using the same file descriptor, for compatibility with V4L
  27 and earlier versions of V4L2.</para>
  28
  29   <para><constant>VIDIOC_S_FMT</constant> and
  30 <constant>VIDIOC_REQBUFS</constant> would permit this to some degree,
  31 but for simplicity drivers need not support switching the I/O method
  32 (after first switching away from read/write) other than by closing
  33 and reopening the device.</para>
  34
  35   <para>The following sections describe the various I/O methods in
  36 more detail.</para>
  37
  38   <section id="rw">
  39     <title>Read/Write</title>
  40
  41     <para>Input and output devices support the
  42 <function>read()</function> and <function>write()</function> function,
  43 respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in
  44 the <structfield>capabilities</structfield> field of &v4l2-capability;
  45 returned by the &VIDIOC-QUERYCAP; ioctl is set.</para>
  46
  47     <para>Drivers may need the CPU to copy the data, but they may also
  48 support DMA to or from user memory, so this I/O method is not
  49 necessarily less efficient than other methods merely exchanging buffer
  50 pointers. It is considered inferior though because no meta-information
  51 like frame counters or timestamps are passed. This information is
  52 necessary to recognize frame dropping and to synchronize with other
  53 data streams. However this is also the simplest I/O method, requiring
  54 little or no setup to exchange data. It permits command line stunts
  55 like this (the <application>vidctrl</application> tool is
  56 fictitious):</para>
  57
  58     <informalexample>
  59       <screen>
  60 &gt; vidctrl /dev/video --input=0 --format=YUYV --size=352x288
  61 &gt; dd if=/dev/video of=myimage.422 bs=202752 count=1
  62 </screen>
  63     </informalexample>
  64
  65     <para>To read from the device applications use the
  66 &func-read; function, to write the &func-write; function.
  67 Drivers must implement one I/O method if they
  68 exchange data with applications, but it need not be this.<footnote>
  69         <para>It would be desirable if applications could depend on
  70 drivers supporting all I/O interfaces, but as much as the complex
  71 memory mapping I/O can be inadequate for some devices we have no
  72 reason to require this interface, which is most useful for simple
  73 applications capturing still images.</para>
  74       </footnote> When reading or writing is supported, the driver
  75 must also support the &func-select; and &func-poll;
  76 function.<footnote>
  77         <para>At the driver level <function>select()</function> and
  78 <function>poll()</function> are the same, and
  79 <function>select()</function> is too important to be optional.</para>
  80       </footnote></para>
  81   </section>
  82
  83   <section id="mmap">
  84     <title>Streaming I/O (Memory Mapping)</title>
  85
  86     <para>Input and output devices support this I/O method when the
  87 <constant>V4L2_CAP_STREAMING</constant> flag in the
  88 <structfield>capabilities</structfield> field of &v4l2-capability;
  89 returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two
  90 streaming methods, to determine if the memory mapping flavor is
  91 supported applications must call the &VIDIOC-REQBUFS; ioctl.</para>
  92
  93     <para>Streaming is an I/O method where only pointers to buffers
  94 are exchanged between application and driver, the data itself is not
  95 copied. Memory mapping is primarily intended to map buffers in device
  96 memory into the application's address space. Device memory can be for
  97 example the video memory on a graphics card with a video capture
  98 add-on. However, being the most efficient I/O method available for a
  99 long time, many other drivers support streaming as well, allocating
 100 buffers in DMA-able main memory.</para>
 101
 102     <para>A driver can support many sets of buffers. Each set is
 103 identified by a unique buffer type value. The sets are independent and
 104 each set can hold a different type of data. To access different sets
 105 at the same time different file descriptors must be used.<footnote>
 106         <para>One could use one file descriptor and set the buffer
 107 type field accordingly when calling &VIDIOC-QBUF; etc., but it makes
 108 the <function>select()</function> function ambiguous. We also like the
 109 clean approach of one file descriptor per logical stream. Video
 110 overlay for example is also a logical stream, although the CPU is not
 111 needed for continuous operation.</para>
 112       </footnote></para>
 113
 114     <para>To allocate device buffers applications call the
 115 &VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer
 116 type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.
 117 This ioctl can also be used to change the number of buffers or to free
 118 the allocated memory, provided none of the buffers are still
 119 mapped.</para>
 120
 121     <para>Before applications can access the buffers they must map
 122 them into their address space with the &func-mmap; function. The
 123 location of the buffers in device memory can be determined with the
 124 &VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the
 125 <structfield>m.offset</structfield> and <structfield>length</structfield>
 126 returned in a &v4l2-buffer; are passed as sixth and second parameter to the
 127 <function>mmap()</function> function. When using the multi-planar API,
 128 struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each
 129 containing its own <structfield>m.offset</structfield> and
 130 <structfield>length</structfield>. When using the multi-planar API, every
 131 plane of every buffer has to be mapped separately, so the number of
 132 calls to &func-mmap; should be equal to number of buffers times number of
 133 planes in each buffer. The offset and length values must not be modified.
 134 Remember, the buffers are allocated in physical memory, as opposed to virtual
 135 memory, which can be swapped out to disk. Applications should free the buffers
 136 as soon as possible with the &func-munmap; function.</para>
 137
 138     <example>
 139       <title>Mapping buffers in the single-planar API</title>
 140       <programlisting>
 141 &v4l2-requestbuffers; reqbuf;
 142 struct {
 143         void *start;
 144         size_t length;
 145 } *buffers;
 146 unsigned int i;
 147
 148 memset(&amp;reqbuf, 0, sizeof(reqbuf));
 149 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 150 reqbuf.memory = V4L2_MEMORY_MMAP;
 151 reqbuf.count = 20;
 152
 153 if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf)) {
 154         if (errno == EINVAL)
 155                 printf("Video capturing or mmap-streaming is not supported\n");
 156         else
 157                 perror("VIDIOC_REQBUFS");
 158
 159         exit(EXIT_FAILURE);
 160 }
 161
 162 /* We want at least five buffers. */
 163
 164 if (reqbuf.count &lt; 5) {
 165         /* You may need to free the buffers here. */
 166         printf("Not enough buffer memory\n");
 167         exit(EXIT_FAILURE);
 168 }
 169
 170 buffers = calloc(reqbuf.count, sizeof(*buffers));
 171 assert(buffers != NULL);
 172
 173 for (i = 0; i &lt; reqbuf.count; i++) {
 174         &v4l2-buffer; buffer;
 175
 176         memset(&amp;buffer, 0, sizeof(buffer));
 177         buffer.type = reqbuf.type;
 178         buffer.memory = V4L2_MEMORY_MMAP;
 179         buffer.index = i;
 180
 181         if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &amp;buffer)) {
 182                 perror("VIDIOC_QUERYBUF");
 183                 exit(EXIT_FAILURE);
 184         }
 185
 186         buffers[i].length = buffer.length; /* remember for munmap() */
 187
 188         buffers[i].start = mmap(NULL, buffer.length,
 189                                 PROT_READ | PROT_WRITE, /* recommended */
 190                                 MAP_SHARED,             /* recommended */
 191                                 fd, buffer.m.offset);
 192
 193         if (MAP_FAILED == buffers[i].start) {
 194                 /* If you do not exit here you should unmap() and free()
 195                    the buffers mapped so far. */
 196                 perror("mmap");
 197                 exit(EXIT_FAILURE);
 198         }
 199 }
 200
 201 /* Cleanup. */
 202
 203 for (i = 0; i &lt; reqbuf.count; i++)
 204         munmap(buffers[i].start, buffers[i].length);
 205       </programlisting>
 206     </example>
 207
 208     <example>
 209       <title>Mapping buffers in the multi-planar API</title>
 210       <programlisting>
 211 &v4l2-requestbuffers; reqbuf;
 212 /* Our current format uses 3 planes per buffer */
 213 #define FMT_NUM_PLANES = 3
 214
 215 struct {
 216         void *start[FMT_NUM_PLANES];
 217         size_t length[FMT_NUM_PLANES];
 218 } *buffers;
 219 unsigned int i, j;
 220
 221 memset(&amp;reqbuf, 0, sizeof(reqbuf));
 222 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
 223 reqbuf.memory = V4L2_MEMORY_MMAP;
 224 reqbuf.count = 20;
 225
 226 if (ioctl(fd, &VIDIOC-REQBUFS;, &amp;reqbuf) &lt; 0) {
 227         if (errno == EINVAL)
 228                 printf("Video capturing or mmap-streaming is not supported\n");
 229         else
 230                 perror("VIDIOC_REQBUFS");
 231
 232         exit(EXIT_FAILURE);
 233 }
 234
 235 /* We want at least five buffers. */
 236
 237 if (reqbuf.count &lt; 5) {
 238         /* You may need to free the buffers here. */
 239         printf("Not enough buffer memory\n");
 240         exit(EXIT_FAILURE);
 241 }
 242
 243 buffers = calloc(reqbuf.count, sizeof(*buffers));
 244 assert(buffers != NULL);
 245
 246 for (i = 0; i &lt; reqbuf.count; i++) {
 247         &v4l2-buffer; buffer;
 248         &v4l2-plane; planes[FMT_NUM_PLANES];
 249
 250         memset(&amp;buffer, 0, sizeof(buffer));
 251         buffer.type = reqbuf.type;
 252         buffer.memory = V4L2_MEMORY_MMAP;
 253         buffer.index = i;
 254         /* length in struct v4l2_buffer in multi-planar API stores the size
 255          * of planes array. */
 256         buffer.length = FMT_NUM_PLANES;
 257         buffer.m.planes = planes;
 258
 259         if (ioctl(fd, &VIDIOC-QUERYBUF;, &amp;buffer) &lt; 0) {
 260                 perror("VIDIOC_QUERYBUF");
 261                 exit(EXIT_FAILURE);
 262         }
 263
 264         /* Every plane has to be mapped separately */
 265         for (j = 0; j &lt; FMT_NUM_PLANES; j++) {
 266                 buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
 267
 268                 buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
 269                                  PROT_READ | PROT_WRITE, /* recommended */
 270                                  MAP_SHARED,             /* recommended */
 271                                  fd, buffer.m.planes[j].m.offset);
 272
 273                 if (MAP_FAILED == buffers[i].start[j]) {
 274                         /* If you do not exit here you should unmap() and free()
 275                            the buffers and planes mapped so far. */
 276                         perror("mmap");
 277                         exit(EXIT_FAILURE);
 278                 }
 279         }
 280 }
 281
 282 /* Cleanup. */
 283
 284 for (i = 0; i &lt; reqbuf.count; i++)
 285         for (j = 0; j &lt; FMT_NUM_PLANES; j++)
 286                 munmap(buffers[i].start[j], buffers[i].length[j]);
 287       </programlisting>
 288     </example>
 289
 290     <para>Conceptually streaming drivers maintain two buffer queues, an incoming
 291 and an outgoing queue. They separate the synchronous capture or output
 292 operation locked to a video clock from the application which is
 293 subject to random disk or network delays and preemption by
 294 other processes, thereby reducing the probability of data loss.
 295 The queues are organized as FIFOs, buffers will be
 296 output in the order enqueued in the incoming FIFO, and were
 297 captured in the order dequeued from the outgoing FIFO.</para>
 298
 299     <para>The driver may require a minimum number of buffers enqueued
 300 at all times to function, apart of this no limit exists on the number
 301 of buffers applications can enqueue in advance, or dequeue and
 302 process. They can also enqueue in a different order than buffers have
 303 been dequeued, and the driver can <emphasis>fill</emphasis> enqueued
 304 <emphasis>empty</emphasis> buffers in any order. <footnote>
 305         <para>Random enqueue order permits applications processing
 306 images out of order (such as video codecs) to return buffers earlier,
 307 reducing the probability of data loss. Random fill order allows
 308 drivers to reuse buffers on a LIFO-basis, taking advantage of caches
 309 holding scatter-gather lists and the like.</para>
 310       </footnote> The index number of a buffer (&v4l2-buffer;
 311 <structfield>index</structfield>) plays no role here, it only
 312 identifies the buffer.</para>
 313
 314     <para>Initially all mapped buffers are in dequeued state,
 315 inaccessible by the driver. For capturing applications it is customary
 316 to first enqueue all mapped buffers, then to start capturing and enter
 317 the read loop. Here the application waits until a filled buffer can be
 318 dequeued, and re-enqueues the buffer when the data is no longer
 319 needed. Output applications fill and enqueue buffers, when enough
 320 buffers are stacked up the output is started with
 321 <constant>VIDIOC_STREAMON</constant>. In the write loop, when
 322 the application runs out of free buffers, it must wait until an empty
 323 buffer can be dequeued and reused.</para>
 324
 325     <para>To enqueue and dequeue a buffer applications use the
 326 &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being
 327 mapped, enqueued, full or empty can be determined at any time using the
 328 &VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the
 329 application until one or more buffers can be dequeued. By default
 330 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
 331 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
 332 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
 333 returns immediately with an &EAGAIN; when no buffer is available. The
 334 &func-select; or &func-poll; function are always available.</para>
 335
 336     <para>To start and stop capturing or output applications call the
 337 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
 338 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
 339 queues as a side effect. Since there is no notion of doing anything
 340 "now" on a multitasking system, if an application needs to synchronize
 341 with another event it should examine the &v4l2-buffer;
 342 <structfield>timestamp</structfield> of captured buffers, or set the
 343 field before enqueuing buffers for output.</para>
 344
 345     <para>Drivers implementing memory mapping I/O must
 346 support the <constant>VIDIOC_REQBUFS</constant>,
 347 <constant>VIDIOC_QUERYBUF</constant>,
 348 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
 349 <constant>VIDIOC_STREAMON</constant> and
 350 <constant>VIDIOC_STREAMOFF</constant> ioctl, the
 351 <function>mmap()</function>, <function>munmap()</function>,
 352 <function>select()</function> and <function>poll()</function>
 353 function.<footnote>
 354         <para>At the driver level <function>select()</function> and
 355 <function>poll()</function> are the same, and
 356 <function>select()</function> is too important to be optional. The
 357 rest should be evident.</para>
 358       </footnote></para>
 359
 360     <para>[capture example]</para>
 361
 362   </section>
 363
 364   <section id="userp">
 365     <title>Streaming I/O (User Pointers)</title>
 366
 367     <para>Input and output devices support this I/O method when the
 368 <constant>V4L2_CAP_STREAMING</constant> flag in the
 369 <structfield>capabilities</structfield> field of &v4l2-capability;
 370 returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user
 371 pointer method (not only memory mapping) is supported must be
 372 determined by calling the &VIDIOC-REQBUFS; ioctl.</para>
 373
 374     <para>This I/O method combines advantages of the read/write and
 375 memory mapping methods. Buffers (planes) are allocated by the application
 376 itself, and can reside for example in virtual or shared memory. Only
 377 pointers to data are exchanged, these pointers and meta-information
 378 are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case).
 379 The driver must be switched into user pointer I/O mode by calling the
 380 &VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated
 381 beforehand, consequently they are not indexed and cannot be queried like mapped
 382 buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para>
 383
 384     <example>
 385       <title>Initiating streaming I/O with user pointers</title>
 386
 387       <programlisting>
 388 &v4l2-requestbuffers; reqbuf;
 389
 390 memset (&amp;reqbuf, 0, sizeof (reqbuf));
 391 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 392 reqbuf.memory = V4L2_MEMORY_USERPTR;
 393
 394 if (ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
 395         if (errno == EINVAL)
 396                 printf ("Video capturing or user pointer streaming is not supported\n");
 397         else
 398                 perror ("VIDIOC_REQBUFS");
 399
 400         exit (EXIT_FAILURE);
 401 }
 402       </programlisting>
 403     </example>
 404
 405     <para>Buffer (plane) addresses and sizes are passed on the fly with the
 406 &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
 407 applications can pass different addresses and sizes at each
 408 <constant>VIDIOC_QBUF</constant> call. If required by the hardware the
 409 driver swaps memory pages within physical memory to create a
 410 continuous area of memory. This happens transparently to the
 411 application in the virtual memory subsystem of the kernel. When buffer
 412 pages have been swapped out to disk they are brought back and finally
 413 locked in physical memory for DMA.<footnote>
 414         <para>We expect that frequently used buffers are typically not
 415 swapped out. Anyway, the process of swapping, locking or generating
 416 scatter-gather lists may be time consuming. The delay can be masked by
 417 the depth of the incoming buffer queue, and perhaps by maintaining
 418 caches assuming a buffer will be soon enqueued again. On the other
 419 hand, to optimize memory usage drivers can limit the number of buffers
 420 locked in advance and recycle the most recently used buffers first. Of
 421 course, the pages of empty buffers in the incoming queue need not be
 422 saved to disk. Output buffers must be saved on the incoming and
 423 outgoing queue because an application may share them with other
 424 processes.</para>
 425       </footnote></para>
 426
 427     <para>Filled or displayed buffers are dequeued with the
 428 &VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any
 429 time between the completion of the DMA and this ioctl. The memory is
 430 also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
 431 when the device is closed. Applications must take care not to free
 432 buffers without dequeuing. For once, the buffers remain locked until
 433 further, wasting physical memory. Second the driver will not be
 434 notified when the memory is returned to the application's free list
 435 and subsequently reused for other purposes, possibly completing the
 436 requested DMA and overwriting valuable data.</para>
 437
 438     <para>For capturing applications it is customary to enqueue a
 439 number of empty buffers, to start capturing and enter the read loop.
 440 Here the application waits until a filled buffer can be dequeued, and
 441 re-enqueues the buffer when the data is no longer needed. Output
 442 applications fill and enqueue buffers, when enough buffers are stacked
 443 up output is started. In the write loop, when the application
 444 runs out of free buffers it must wait until an empty buffer can be
 445 dequeued and reused. Two methods exist to suspend execution of the
 446 application until one or more buffers can be dequeued. By default
 447 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
 448 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
 449 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
 450 returns immediately with an &EAGAIN; when no buffer is available. The
 451 &func-select; or &func-poll; function are always available.</para>
 452
 453     <para>To start and stop capturing or output applications call the
 454 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
 455 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
 456 queues and unlocks all buffers as a side effect. Since there is no
 457 notion of doing anything "now" on a multitasking system, if an
 458 application needs to synchronize with another event it should examine
 459 the &v4l2-buffer; <structfield>timestamp</structfield> of captured
 460 buffers, or set the field before enqueuing buffers for output.</para>
 461
 462     <para>Drivers implementing user pointer I/O must
 463 support the <constant>VIDIOC_REQBUFS</constant>,
 464 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
 465 <constant>VIDIOC_STREAMON</constant> and
 466 <constant>VIDIOC_STREAMOFF</constant> ioctl, the
 467 <function>select()</function> and <function>poll()</function> function.<footnote>
 468         <para>At the driver level <function>select()</function> and
 469 <function>poll()</function> are the same, and
 470 <function>select()</function> is too important to be optional. The
 471 rest should be evident.</para>
 472       </footnote></para>
 473   </section>
 474
 475   <section id="async">
 476     <title>Asynchronous I/O</title>
 477
 478     <para>This method is not defined yet.</para>
 479   </section>
 480
 481   <section id="buffer">
 482     <title>Buffers</title>
 483
 484     <para>A buffer contains data exchanged by application and
 485 driver using one of the Streaming I/O methods. In the multi-planar API, the
 486 data is held in planes, while the buffer structure acts as a container
 487 for the planes. Only pointers to buffers (planes) are exchanged, the data
 488 itself is not copied. These pointers, together with meta-information like
 489 timestamps or field parity, are stored in a struct
 490 <structname>v4l2_buffer</structname>, argument to
 491 the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.
 492 In the multi-planar API, some plane-specific members of struct
 493 <structname>v4l2_buffer</structname>, such as pointers and sizes for each
 494 plane, are stored in struct <structname>v4l2_plane</structname> instead.
 495 In that case, struct <structname>v4l2_buffer</structname> contains an array of
 496 plane structures.</para>
 497
 498       <para>Nominally timestamps refer to the first data byte transmitted.
 499 In practice however the wide range of hardware covered by the V4L2 API
 500 limits timestamp accuracy. Often an interrupt routine will
 501 sample the system clock shortly after the field or frame was stored
 502 completely in memory. So applications must expect a constant
 503 difference up to one field or frame period plus a small (few scan
 504 lines) random error. The delay and error can be much
 505 larger due to compression or transmission over an external bus when
 506 the frames are not properly stamped by the sender. This is frequently
 507 the case with USB cameras. Here timestamps refer to the instant the
 508 field or frame was received by the driver, not the capture time. These
 509 devices identify by not enumerating any video standards, see <xref
 510 linkend="standard" />.</para>
 511
 512       <para>Similar limitations apply to output timestamps. Typically
 513 the video hardware locks to a clock controlling the video timing, the
 514 horizontal and vertical synchronization pulses. At some point in the
 515 line sequence, possibly the vertical blanking, an interrupt routine
 516 samples the system clock, compares against the timestamp and programs
 517 the hardware to repeat the previous field or frame, or to display the
 518 buffer contents.</para>
 519
 520       <para>Apart of limitations of the video device and natural
 521 inaccuracies of all clocks, it should be noted system time itself is
 522 not perfectly stable. It can be affected by power saving cycles,
 523 warped to insert leap seconds, or even turned back or forth by the
 524 system administrator affecting long term measurements. <footnote>
 525           <para>Since no other Linux multimedia
 526 API supports unadjusted time it would be foolish to introduce here. We
 527 must use a universally supported clock to synchronize different media,
 528 hence time of day.</para>
 529         </footnote></para>
 530
 531     <table frame="none" pgwide="1" id="v4l2-buffer">
 532       <title>struct <structname>v4l2_buffer</structname></title>
 533       <tgroup cols="4">
 534         &cs-ustr;
 535         <tbody valign="top">
 536           <row>
 537             <entry>__u32</entry>
 538             <entry><structfield>index</structfield></entry>
 539             <entry></entry>
 540             <entry>Number of the buffer, set by the application. This
 541 field is only used for <link linkend="mmap">memory mapping</link> I/O
 542 and can range from zero to the number of buffers allocated
 543 with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry>
 544           </row>
 545           <row>
 546             <entry>&v4l2-buf-type;</entry>
 547             <entry><structfield>type</structfield></entry>
 548             <entry></entry>
 549             <entry>Type of the buffer, same as &v4l2-format;
 550 <structfield>type</structfield> or &v4l2-requestbuffers;
 551 <structfield>type</structfield>, set by the application.</entry>
 552           </row>
 553           <row>
 554             <entry>__u32</entry>
 555             <entry><structfield>bytesused</structfield></entry>
 556             <entry></entry>
 557             <entry>The number of bytes occupied by the data in the
 558 buffer. It depends on the negotiated data format and may change with
 559 each buffer for compressed variable size data like JPEG images.
 560 Drivers must set this field when <structfield>type</structfield>
 561 refers to an input stream, applications when an output stream.</entry>
 562           </row>
 563           <row>
 564             <entry>__u32</entry>
 565             <entry><structfield>flags</structfield></entry>
 566             <entry></entry>
 567             <entry>Flags set by the application or driver, see <xref
 568 linkend="buffer-flags" />.</entry>
 569           </row>
 570           <row>
 571             <entry>&v4l2-field;</entry>
 572             <entry><structfield>field</structfield></entry>
 573             <entry></entry>
 574             <entry>Indicates the field order of the image in the
 575 buffer, see <xref linkend="v4l2-field" />. This field is not used when
 576 the buffer contains VBI data. Drivers must set it when
 577 <structfield>type</structfield> refers to an input stream,
 578 applications when an output stream.</entry>
 579           </row>
 580           <row>
 581             <entry>struct timeval</entry>
 582             <entry><structfield>timestamp</structfield></entry>
 583             <entry></entry>
 584             <entry><para>For input streams this is the
 585 system time (as returned by the <function>gettimeofday()</function>
 586 function) when the first data byte was captured. For output streams
 587 the data will not be displayed before this time, secondary to the
 588 nominal frame rate determined by the current video standard in
 589 enqueued order. Applications can for example zero this field to
 590 display frames as soon as possible. The driver stores the time at
 591 which the first data byte was actually sent out in the
 592 <structfield>timestamp</structfield> field. This permits
 593 applications to monitor the drift between the video and system
 594 clock.</para></entry>
 595           </row>
 596           <row>
 597             <entry>&v4l2-timecode;</entry>
 598             <entry><structfield>timecode</structfield></entry>
 599             <entry></entry>
 600             <entry>When <structfield>type</structfield> is
 601 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the
 602 <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in
 603 <structfield>flags</structfield>, this structure contains a frame
 604 timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
 605 mode the top and bottom field contain the same timecode.
 606 Timecodes are intended to help video editing and are typically recorded on
 607 video tapes, but also embedded in compressed formats like MPEG. This
 608 field is independent of the <structfield>timestamp</structfield> and
 609 <structfield>sequence</structfield> fields.</entry>
 610           </row>
 611           <row>
 612             <entry>__u32</entry>
 613             <entry><structfield>sequence</structfield></entry>
 614             <entry></entry>
 615             <entry>Set by the driver, counting the frames in the
 616 sequence.</entry>
 617           </row>
 618           <row>
 619             <entry spanname="hspan"><para>In <link
 620 linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and
 621 bottom field have the same sequence number. The count starts at zero
 622 and includes dropped or repeated frames. A dropped frame was received
 623 by an input device but could not be stored due to lack of free buffer
 624 space. A repeated frame was displayed again by an output device
 625 because the application did not pass new data in
 626 time.</para><para>Note this may count the frames received
 627 e.g. over USB, without taking into account the frames dropped by the
 628 remote hardware due to limited compression throughput or bus
 629 bandwidth. These devices identify by not enumerating any video
 630 standards, see <xref linkend="standard" />.</para></entry>
 631           </row>
 632           <row>
 633             <entry>&v4l2-memory;</entry>
 634             <entry><structfield>memory</structfield></entry>
 635             <entry></entry>
 636             <entry>This field must be set by applications and/or drivers
 637 in accordance with the selected I/O method.</entry>
 638           </row>
 639           <row>
 640             <entry>union</entry>
 641             <entry><structfield>m</structfield></entry>
 642           </row>
 643           <row>
 644             <entry></entry>
 645             <entry>__u32</entry>
 646             <entry><structfield>offset</structfield></entry>
 647             <entry>For the single-planar API and when
 648 <structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this
 649 is the offset of the buffer from the start of the device memory. The value is
 650 returned by the driver and apart of serving as parameter to the &func-mmap;
 651 function not useful for applications. See <xref linkend="mmap" /> for details
 652           </entry>
 653           </row>
 654           <row>
 655             <entry></entry>
 656             <entry>unsigned long</entry>
 657             <entry><structfield>userptr</structfield></entry>
 658             <entry>For the single-planar API and when
 659 <structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant>
 660 this is a pointer to the buffer (casted to unsigned long type) in virtual
 661 memory, set by the application. See <xref linkend="userp" /> for details.
 662             </entry>
 663           </row>
 664           <row>
 665             <entry></entry>
 666             <entry>struct v4l2_plane</entry>
 667             <entry><structfield>*planes</structfield></entry>
 668             <entry>When using the multi-planar API, contains a userspace pointer
 669             to an array of &v4l2-plane;. The size of the array should be put
 670             in the <structfield>length</structfield> field of this
 671             <structname>v4l2_buffer</structname> structure.</entry>
 672           </row>
 673           <row>
 674             <entry>__u32</entry>
 675             <entry><structfield>length</structfield></entry>
 676             <entry></entry>
 677             <entry>Size of the buffer (not the payload) in bytes for the
 678             single-planar API. For the multi-planar API should contain the
 679             number of elements in the <structfield>planes</structfield> array.
 680             </entry>
 681           </row>
 682           <row>
 683             <entry>__u32</entry>
 684             <entry><structfield>input</structfield></entry>
 685             <entry></entry>
 686             <entry>Some video capture drivers support rapid and
 687 synchronous video input changes, a function useful for example in
 688 video surveillance applications. For this purpose applications set the
 689 <constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the
 690 number of a video input as in &v4l2-input; field
 691 <structfield>index</structfield>.</entry>
 692           </row>
 693           <row>
 694             <entry>__u32</entry>
 695             <entry><structfield>reserved</structfield></entry>
 696             <entry></entry>
 697             <entry>A place holder for future extensions and custom
 698 (driver defined) buffer types
 699 <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications
 700 should set this to 0.</entry>
 701           </row>
 702         </tbody>
 703       </tgroup>
 704     </table>
 705
 706     <table frame="none" pgwide="1" id="v4l2-plane">
 707       <title>struct <structname>v4l2_plane</structname></title>
 708       <tgroup cols="4">
 709         &cs-ustr;
 710         <tbody valign="top">
 711           <row>
 712             <entry>__u32</entry>
 713             <entry><structfield>bytesused</structfield></entry>
 714             <entry></entry>
 715             <entry>The number of bytes occupied by data in the plane
 716             (its payload).</entry>
 717           </row>
 718           <row>
 719             <entry>__u32</entry>
 720             <entry><structfield>length</structfield></entry>
 721             <entry></entry>
 722             <entry>Size in bytes of the plane (not its payload).</entry>
 723           </row>
 724           <row>
 725             <entry>union</entry>
 726             <entry><structfield>m</structfield></entry>
 727             <entry></entry>
 728             <entry></entry>
 729           </row>
 730           <row>
 731             <entry></entry>
 732             <entry>__u32</entry>
 733             <entry><structfield>mem_offset</structfield></entry>
 734             <entry>When the memory type in the containing &v4l2-buffer; is
 735               <constant>V4L2_MEMORY_MMAP</constant>, this is the value that
 736               should be passed to &func-mmap;, similar to the
 737               <structfield>offset</structfield> field in &v4l2-buffer;.</entry>
 738           </row>
 739           <row>
 740             <entry></entry>
 741             <entry>__unsigned long</entry>
 742             <entry><structfield>userptr</structfield></entry>
 743             <entry>When the memory type in the containing &v4l2-buffer; is
 744               <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace
 745               pointer to the memory allocated for this plane by an application.
 746               </entry>
 747           </row>
 748           <row>
 749             <entry>__u32</entry>
 750             <entry><structfield>data_offset</structfield></entry>
 751             <entry></entry>
 752             <entry>Offset in bytes to video data in the plane, if applicable.
 753             </entry>
 754           </row>
 755           <row>
 756             <entry>__u32</entry>
 757             <entry><structfield>reserved[11]</structfield></entry>
 758             <entry></entry>
 759             <entry>Reserved for future use. Should be zeroed by an
 760             application.</entry>
 761           </row>
 762         </tbody>
 763       </tgroup>
 764     </table>
 765
 766     <table frame="none" pgwide="1" id="v4l2-buf-type">
 767       <title>enum v4l2_buf_type</title>
 768       <tgroup cols="3">
 769         &cs-def;
 770         <tbody valign="top">
 771           <row>
 772             <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
 773             <entry>1</entry>
 774             <entry>Buffer of a single-planar video capture stream, see <xref
 775                 linkend="capture" />.</entry>
 776           </row>
 777           <row>
 778             <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
 779             </entry>
 780             <entry>9</entry>
 781             <entry>Buffer of a multi-planar video capture stream, see <xref
 782                 linkend="capture" />.</entry>
 783           </row>
 784           <row>
 785             <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
 786             <entry>2</entry>
 787             <entry>Buffer of a single-planar video output stream, see <xref
 788                 linkend="output" />.</entry>
 789           </row>
 790           <row>
 791             <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>
 792             </entry>
 793             <entry>10</entry>
 794             <entry>Buffer of a multi-planar video output stream, see <xref
 795                 linkend="output" />.</entry>
 796           </row>
 797           <row>
 798             <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
 799             <entry>3</entry>
 800             <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry>
 801           </row>
 802           <row>
 803             <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
 804             <entry>4</entry>
 805             <entry>Buffer of a raw VBI capture stream, see <xref
 806                 linkend="raw-vbi" />.</entry>
 807           </row>
 808           <row>
 809             <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
 810             <entry>5</entry>
 811             <entry>Buffer of a raw VBI output stream, see <xref
 812                 linkend="raw-vbi" />.</entry>
 813           </row>
 814           <row>
 815             <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
 816             <entry>6</entry>
 817             <entry>Buffer of a sliced VBI capture stream, see <xref
 818                 linkend="sliced" />.</entry>
 819           </row>
 820           <row>
 821             <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
 822             <entry>7</entry>
 823             <entry>Buffer of a sliced VBI output stream, see <xref
 824                 linkend="sliced" />.</entry>
 825           </row>
 826           <row>
 827             <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry>
 828             <entry>8</entry>
 829             <entry>Buffer for video output overlay (OSD), see <xref
 830                 linkend="osd" />. Status: <link
 831 linkend="experimental">Experimental</link>.</entry>
 832           </row>
 833           <row>
 834             <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry>
 835             <entry>0x80</entry>
 836           <entry>This and higher values are reserved for custom
 837 (driver defined) buffer types.</entry>
 838           </row>
 839         </tbody>
 840       </tgroup>
 841     </table>
 842
 843     <table frame="none" pgwide="1" id="buffer-flags">
 844       <title>Buffer Flags</title>
 845       <tgroup cols="3">
 846         &cs-def;
 847         <tbody valign="top">
 848           <row>
 849             <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
 850             <entry>0x0001</entry>
 851             <entry>The buffer resides in device memory and has been mapped
 852 into the application's address space, see <xref linkend="mmap" /> for details.
 853 Drivers set or clear this flag when the
 854 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
 855           linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
 856           linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
 857           </row>
 858           <row>
 859             <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
 860             <entry>0x0002</entry>
 861           <entry>Internally drivers maintain two buffer queues, an
 862 incoming and outgoing queue. When this flag is set, the buffer is
 863 currently on the incoming queue. It automatically moves to the
 864 outgoing queue after the buffer has been filled (capture devices) or
 865 displayed (output devices). Drivers set or clear this flag when the
 866 <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
 867 (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
 868 always set and after <constant>VIDIOC_DQBUF</constant> always
 869 cleared.</entry>
 870           </row>
 871           <row>
 872             <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
 873             <entry>0x0004</entry>
 874             <entry>When this flag is set, the buffer is currently on
 875 the outgoing queue, ready to be dequeued from the driver. Drivers set
 876 or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
 877 is called. After calling the <constant>VIDIOC_QBUF</constant> or
 878 <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
 879 buffer cannot be on both queues at the same time, the
 880 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
 881 <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
 882 They can be both cleared however, then the buffer is in "dequeued"
 883 state, in the application domain to say so.</entry>
 884           </row>
 885           <row>
 886             <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
 887             <entry>0x0040</entry>
 888             <entry>When this flag is set, the buffer has been dequeued
 889             successfully, although the data might have been corrupted.
 890             This is recoverable, streaming may continue as normal and
 891             the buffer may be reused normally.
 892             Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
 893             ioctl is called.</entry>
 894           </row>
 895           <row>
 896             <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
 897             <entry>0x0008</entry>
 898           <entry>Drivers set or clear this flag when calling the
 899 <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
 900 capture devices when the buffer contains a compressed image which is a
 901 key frame (or field), &ie; can be decompressed on its own.</entry>
 902           </row>
 903           <row>
 904             <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
 905             <entry>0x0010</entry>
 906             <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
 907 this flags predicted frames or fields which contain only differences to a
 908 previous key frame.</entry>
 909           </row>
 910           <row>
 911             <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
 912             <entry>0x0020</entry>
 913             <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant>
 914         this is a bidirectional predicted frame or field. [ooc tbd]</entry>
 915           </row>
 916           <row>
 917             <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
 918             <entry>0x0100</entry>
 919             <entry>The <structfield>timecode</structfield> field is valid.
 920 Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
 921 ioctl is called.</entry>
 922           </row>
 923           <row>
 924             <entry><constant>V4L2_BUF_FLAG_INPUT</constant></entry>
 925             <entry>0x0200</entry>
 926             <entry>The <structfield>input</structfield> field is valid.
 927 Applications set or clear this flag before calling the
 928 <constant>VIDIOC_QBUF</constant> ioctl.</entry>
 929           </row>
 930         </tbody>
 931       </tgroup>
 932     </table>
 933
 934     <table pgwide="1" frame="none" id="v4l2-memory">
 935       <title>enum v4l2_memory</title>
 936       <tgroup cols="3">
 937         &cs-def;
 938         <tbody valign="top">
 939           <row>
 940             <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
 941             <entry>1</entry>
 942             <entry>The buffer is used for <link linkend="mmap">memory
 943 mapping</link> I/O.</entry>
 944           </row>
 945           <row>
 946             <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
 947             <entry>2</entry>
 948             <entry>The buffer is used for <link linkend="userp">user
 949 pointer</link> I/O.</entry>
 950           </row>
 951           <row>
 952             <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
 953             <entry>3</entry>
 954             <entry>[to do]</entry>
 955           </row>
 956         </tbody>
 957       </tgroup>
 958     </table>
 959
 960     <section>
 961       <title>Timecodes</title>
 962
 963       <para>The <structname>v4l2_timecode</structname> structure is
 964 designed to hold a <xref linkend="smpte12m" /> or similar timecode.
 965 (struct <structname>timeval</structname> timestamps are stored in
 966 &v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
 967
 968       <table frame="none" pgwide="1" id="v4l2-timecode">
 969         <title>struct <structname>v4l2_timecode</structname></title>
 970         <tgroup cols="3">
 971           &cs-str;
 972           <tbody valign="top">
 973             <row>
 974               <entry>__u32</entry>
 975               <entry><structfield>type</structfield></entry>
 976               <entry>Frame rate the timecodes are based on, see <xref
 977                   linkend="timecode-type" />.</entry>
 978             </row>
 979             <row>
 980               <entry>__u32</entry>
 981               <entry><structfield>flags</structfield></entry>
 982               <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
 983             </row>
 984             <row>
 985               <entry>__u8</entry>
 986               <entry><structfield>frames</structfield></entry>
 987               <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
 988             type of timecode.</entry>
 989             </row>
 990             <row>
 991               <entry>__u8</entry>
 992               <entry><structfield>seconds</structfield></entry>
 993               <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
 994             </row>
 995             <row>
 996               <entry>__u8</entry>
 997               <entry><structfield>minutes</structfield></entry>
 998               <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
 999             </row>
1000             <row>
1001               <entry>__u8</entry>
1002               <entry><structfield>hours</structfield></entry>
1003               <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
1004             </row>
1005             <row>
1006               <entry>__u8</entry>
1007               <entry><structfield>userbits</structfield>[4]</entry>
1008               <entry>The "user group" bits from the timecode.</entry>
1009             </row>
1010           </tbody>
1011         </tgroup>
1012       </table>
1013
1014       <table frame="none" pgwide="1" id="timecode-type">
1015         <title>Timecode Types</title>
1016         <tgroup cols="3">
1017         &cs-def;
1018           <tbody valign="top">
1019             <row>
1020               <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
1021               <entry>1</entry>
1022               <entry>24 frames per second, i.&nbsp;e. film.</entry>
1023             </row>
1024             <row>
1025               <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
1026               <entry>2</entry>
1027               <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
1028             </row>
1029             <row>
1030               <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
1031               <entry>3</entry>
1032               <entry>30 frames per second, &ie; NTSC video.</entry>
1033             </row>
1034             <row>
1035               <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
1036               <entry>4</entry>
1037               <entry></entry>
1038             </row>
1039             <row>
1040               <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
1041               <entry>5</entry>
1042               <entry></entry>
1043             </row>
1044           </tbody>
1045         </tgroup>
1046       </table>
1047
1048       <table frame="none" pgwide="1" id="timecode-flags">
1049         <title>Timecode Flags</title>
1050         <tgroup cols="3">
1051         &cs-def;
1052           <tbody valign="top">
1053             <row>
1054               <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
1055               <entry>0x0001</entry>
1056               <entry>Indicates "drop frame" semantics for counting frames
1057 in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
1058 each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
1059 count.</entry>
1060             </row>
1061             <row>
1062               <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
1063               <entry>0x0002</entry>
1064               <entry>The "color frame" flag.</entry>
1065             </row>
1066             <row>
1067               <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
1068               <entry>0x000C</entry>
1069               <entry>Field mask for the "binary group flags".</entry>
1070             </row>
1071             <row>
1072               <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
1073               <entry>0x0000</entry>
1074               <entry>Unspecified format.</entry>
1075             </row>
1076             <row>
1077               <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
1078               <entry>0x0008</entry>
1079               <entry>8-bit ISO characters.</entry>
1080             </row>
1081           </tbody>
1082         </tgroup>
1083       </table>
1084     </section>
1085   </section>
1086
1087   <section id="field-order">
1088     <title>Field Order</title>
1089
1090     <para>We have to distinguish between progressive and interlaced
1091 video. Progressive video transmits all lines of a video image
1092 sequentially. Interlaced video divides an image into two fields,
1093 containing only the odd and even lines of the image, respectively.
1094 Alternating the so called odd and even field are transmitted, and due
1095 to a small delay between fields a cathode ray TV displays the lines
1096 interleaved, yielding the original frame. This curious technique was
1097 invented because at refresh rates similar to film the image would
1098 fade out too quickly. Transmitting fields reduces the flicker without
1099 the necessity of doubling the frame rate and with it the bandwidth
1100 required for each channel.</para>
1101
1102     <para>It is important to understand a video camera does not expose
1103 one frame at a time, merely transmitting the frames separated into
1104 fields. The fields are in fact captured at two different instances in
1105 time. An object on screen may well move between one field and the
1106 next. For applications analysing motion it is of paramount importance
1107 to recognize which field of a frame is older, the <emphasis>temporal
1108 order</emphasis>.</para>
1109
1110     <para>When the driver provides or accepts images field by field
1111 rather than interleaved, it is also important applications understand
1112 how the fields combine to frames. We distinguish between top (aka odd) and
1113 bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line
1114 of the top field is the first line of an interlaced frame, the first
1115 line of the bottom field is the second line of that frame.</para>
1116
1117     <para>However because fields were captured one after the other,
1118 arguing whether a frame commences with the top or bottom field is
1119 pointless. Any two successive top and bottom, or bottom and top fields
1120 yield a valid frame. Only when the source was progressive to begin
1121 with, &eg; when transferring film to video, two fields may come from
1122 the same frame, creating a natural order.</para>
1123
1124     <para>Counter to intuition the top field is not necessarily the
1125 older field. Whether the older field contains the top or bottom lines
1126 is a convention determined by the video standard. Hence the
1127 distinction between temporal and spatial order of fields. The diagrams
1128 below should make this clearer.</para>
1129
1130     <para>All video capture and output devices must report the current
1131 field order. Some drivers may permit the selection of a different
1132 order, to this end applications initialize the
1133 <structfield>field</structfield> field of &v4l2-pix-format; before
1134 calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
1135 have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
1136
1137     <table frame="none" pgwide="1" id="v4l2-field">
1138       <title>enum v4l2_field</title>
1139       <tgroup cols="3">
1140         &cs-def;
1141         <tbody valign="top">
1142           <row>
1143             <entry><constant>V4L2_FIELD_ANY</constant></entry>
1144             <entry>0</entry>
1145             <entry>Applications request this field order when any
1146 one of the <constant>V4L2_FIELD_NONE</constant>,
1147 <constant>V4L2_FIELD_TOP</constant>,
1148 <constant>V4L2_FIELD_BOTTOM</constant>, or
1149 <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
1150 Drivers choose depending on hardware capabilities or e.&nbsp;g. the
1151 requested image size, and return the actual field order. &v4l2-buffer;
1152 <structfield>field</structfield> can never be
1153 <constant>V4L2_FIELD_ANY</constant>.</entry>
1154           </row>
1155           <row>
1156             <entry><constant>V4L2_FIELD_NONE</constant></entry>
1157             <entry>1</entry>
1158             <entry>Images are in progressive format, not interlaced.
1159 The driver may also indicate this order when it cannot distinguish
1160 between <constant>V4L2_FIELD_TOP</constant> and
1161 <constant>V4L2_FIELD_BOTTOM</constant>.</entry>
1162           </row>
1163           <row>
1164             <entry><constant>V4L2_FIELD_TOP</constant></entry>
1165             <entry>2</entry>
1166             <entry>Images consist of the top (aka odd) field only.</entry>
1167           </row>
1168           <row>
1169             <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
1170             <entry>3</entry>
1171             <entry>Images consist of the bottom (aka even) field only.
1172 Applications may wish to prevent a device from capturing interlaced
1173 images because they will have "comb" or "feathering" artefacts around
1174 moving objects.</entry>
1175           </row>
1176           <row>
1177             <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
1178             <entry>4</entry>
1179             <entry>Images contain both fields, interleaved line by
1180 line. The temporal order of the fields (whether the top or bottom
1181 field is first transmitted) depends on the current video standard.
1182 M/NTSC transmits the bottom field first, all other standards the top
1183 field first.</entry>
1184           </row>
1185           <row>
1186             <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
1187             <entry>5</entry>
1188             <entry>Images contain both fields, the top field lines
1189 are stored first in memory, immediately followed by the bottom field
1190 lines. Fields are always stored in temporal order, the older one first
1191 in memory. Image sizes refer to the frame, not fields.</entry>
1192           </row>
1193           <row>
1194             <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1195             <entry>6</entry>
1196             <entry>Images contain both fields, the bottom field
1197 lines are stored first in memory, immediately followed by the top
1198 field lines. Fields are always stored in temporal order, the older one
1199 first in memory. Image sizes refer to the frame, not fields.</entry>
1200           </row>
1201           <row>
1202             <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1203             <entry>7</entry>
1204             <entry>The two fields of a frame are passed in separate
1205 buffers, in temporal order, &ie; the older one first. To indicate the field
1206 parity (whether the current field is a top or bottom field) the driver
1207 or application, depending on data direction, must set &v4l2-buffer;
1208 <structfield>field</structfield> to
1209 <constant>V4L2_FIELD_TOP</constant> or
1210 <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
1211 to build a frame. If fields are successive, without any dropped fields
1212 between them (fields can drop individually), can be determined from
1213 the &v4l2-buffer; <structfield>sequence</structfield> field. Image
1214 sizes refer to the frame, not fields. This format cannot be selected
1215 when using the read/write I/O method.<!-- Where it's indistinguishable
1216 from V4L2_FIELD_SEQ_*. --></entry>
1217           </row>
1218           <row>
1219             <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
1220             <entry>8</entry>
1221             <entry>Images contain both fields, interleaved line by
1222 line, top field first. The top field is transmitted first.</entry>
1223           </row>
1224           <row>
1225             <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
1226             <entry>9</entry>
1227             <entry>Images contain both fields, interleaved line by
1228 line, top field first. The bottom field is transmitted first.</entry>
1229           </row>
1230         </tbody>
1231       </tgroup>
1232     </table>
1233
1234     <figure id="fieldseq-tb">
1235         <title>Field Order, Top Field First Transmitted</title>
1236         <mediaobject>
1237           <imageobject>
1238             <imagedata fileref="fieldseq_tb.pdf" format="PS" />
1239           </imageobject>
1240           <imageobject>
1241             <imagedata fileref="fieldseq_tb.gif" format="GIF" />
1242           </imageobject>
1243         </mediaobject>
1244     </figure>
1245
1246     <figure id="fieldseq-bt">
1247         <title>Field Order, Bottom Field First Transmitted</title>
1248         <mediaobject>
1249           <imageobject>
1250             <imagedata fileref="fieldseq_bt.pdf" format="PS" />
1251           </imageobject>
1252           <imageobject>
1253             <imagedata fileref="fieldseq_bt.gif" format="GIF" />
1254           </imageobject>
1255         </mediaobject>
1256     </figure>
1257   </section>
1258
1259   <!--
1260 Local Variables:
1261 mode: sgml
1262 sgml-parent-document: "v4l2.sgml"
1263 indent-tabs-mode: nil
1264 End:
1265   -->