1 <title>Input/Output</title> 2 3 <para>The V4L2 API defines several different methods to read from or 4write to a device. All drivers exchanging data with applications must 5support at least one of them.</para> 6 7 <para>The classic I/O method using the <function>read()</function> 8and <function>write()</function> function is automatically selected 9after opening a V4L2 device. When the driver does not support this 10method 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 13method with memory mapped or user buffers applications call the 14&VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined 15yet.</para> 16 17 <para>Video overlay can be considered another I/O method, although 18the application does not directly receive the image data. It is 19selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl. 20For more information see <xref linkend="overlay" />.</para> 21 22 <para>Generally exactly one I/O method, including overlay, is 23associated with each file descriptor. The only exceptions are 24applications not exchanging data with a driver ("panel applications", 25see <xref linkend="open" />) and drivers permitting simultaneous video capturing 26and overlay using the same file descriptor, for compatibility with V4L 27and 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, 31but for simplicity drivers need not support switching the I/O method 32(after first switching away from read/write) other than by closing 33and reopening the device.</para> 34 35 <para>The following sections describe the various I/O methods in 36more 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, 43respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in 44the <structfield>capabilities</structfield> field of &v4l2-capability; 45returned by the &VIDIOC-QUERYCAP; ioctl is set.</para> 46 47 <para>Drivers may need the CPU to copy the data, but they may also 48support DMA to or from user memory, so this I/O method is not 49necessarily less efficient than other methods merely exchanging buffer 50pointers. It is considered inferior though because no meta-information 51like frame counters or timestamps are passed. This information is 52necessary to recognize frame dropping and to synchronize with other 53data streams. However this is also the simplest I/O method, requiring 54little or no setup to exchange data. It permits command line stunts 55like this (the <application>vidctrl</application> tool is 56fictitious):</para> 57 58 <informalexample> 59 <screen> 60> vidctrl /dev/video --input=0 --format=YUYV --size=352x288 61> 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. 67Drivers must implement one I/O method if they 68exchange data with applications, but it need not be this.<footnote> 69 <para>It would be desirable if applications could depend on 70drivers supporting all I/O interfaces, but as much as the complex 71memory mapping I/O can be inadequate for some devices we have no 72reason to require this interface, which is most useful for simple 73applications capturing still images.</para> 74 </footnote> When reading or writing is supported, the driver 75must also support the &func-select; and &func-poll; 76function.<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; 89returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two 90streaming methods, to determine if the memory mapping flavor is 91supported applications must call the &VIDIOC-REQBUFS; ioctl.</para> 92 93 <para>Streaming is an I/O method where only pointers to buffers 94are exchanged between application and driver, the data itself is not 95copied. Memory mapping is primarily intended to map buffers in device 96memory into the application's address space. Device memory can be for 97example the video memory on a graphics card with a video capture 98add-on. However, being the most efficient I/O method available for a 99long time, many other drivers support streaming as well, allocating 100buffers in DMA-able main memory.</para> 101 102 <para>A driver can support many sets of buffers. Each set is 103identified by a unique buffer type value. The sets are independent and 104each set can hold a different type of data. To access different sets 105at the same time different file descriptors must be used.<footnote> 106 <para>One could use one file descriptor and set the buffer 107type field accordingly when calling &VIDIOC-QBUF; etc., but it makes 108the <function>select()</function> function ambiguous. We also like the 109clean approach of one file descriptor per logical stream. Video 110overlay for example is also a logical stream, although the CPU is not 111needed 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 116type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. 117This ioctl can also be used to change the number of buffers or to free 118the allocated memory, provided none of the buffers are still 119mapped.</para> 120 121 <para>Before applications can access the buffers they must map 122them into their address space with the &func-mmap; function. The 123location 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> 126returned in a &v4l2-buffer; are passed as sixth and second parameter to the 127<function>mmap()</function> function. When using the multi-planar API, 128struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each 129containing its own <structfield>m.offset</structfield> and 130<structfield>length</structfield>. When using the multi-planar API, every 131plane of every buffer has to be mapped separately, so the number of 132calls to &func-mmap; should be equal to number of buffers times number of 133planes in each buffer. The offset and length values must not be modified. 134Remember, the buffers are allocated in physical memory, as opposed to virtual 135memory, which can be swapped out to disk. Applications should free the buffers 136as 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; 142struct { 143 void *start; 144 size_t length; 145} *buffers; 146unsigned int i; 147 148memset(&reqbuf, 0, sizeof(reqbuf)); 149reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 150reqbuf.memory = V4L2_MEMORY_MMAP; 151reqbuf.count = 20; 152 153if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &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 164if (reqbuf.count < 5) { 165 /* You may need to free the buffers here. */ 166 printf("Not enough buffer memory\n"); 167 exit(EXIT_FAILURE); 168} 169 170buffers = calloc(reqbuf.count, sizeof(*buffers)); 171assert(buffers != NULL); 172 173for (i = 0; i < reqbuf.count; i++) { 174 &v4l2-buffer; buffer; 175 176 memset(&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;, &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 203for (i = 0; i < 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 215struct { 216 void *start[FMT_NUM_PLANES]; 217 size_t length[FMT_NUM_PLANES]; 218} *buffers; 219unsigned int i, j; 220 221memset(&reqbuf, 0, sizeof(reqbuf)); 222reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; 223reqbuf.memory = V4L2_MEMORY_MMAP; 224reqbuf.count = 20; 225 226if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 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 237if (reqbuf.count < 5) { 238 /* You may need to free the buffers here. */ 239 printf("Not enough buffer memory\n"); 240 exit(EXIT_FAILURE); 241} 242 243buffers = calloc(reqbuf.count, sizeof(*buffers)); 244assert(buffers != NULL); 245 246for (i = 0; i < reqbuf.count; i++) { 247 &v4l2-buffer; buffer; 248 &v4l2-plane; planes[FMT_NUM_PLANES]; 249 250 memset(&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;, &buffer) < 0) { 260 perror("VIDIOC_QUERYBUF"); 261 exit(EXIT_FAILURE); 262 } 263 264 /* Every plane has to be mapped separately */ 265 for (j = 0; j < 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 284for (i = 0; i < reqbuf.count; i++) 285 for (j = 0; j < 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 291and an outgoing queue. They separate the synchronous capture or output 292operation locked to a video clock from the application which is 293subject to random disk or network delays and preemption by 294other processes, thereby reducing the probability of data loss. 295The queues are organized as FIFOs, buffers will be 296output in the order enqueued in the incoming FIFO, and were 297captured in the order dequeued from the outgoing FIFO.</para> 298 299 <para>The driver may require a minimum number of buffers enqueued 300at all times to function, apart of this no limit exists on the number 301of buffers applications can enqueue in advance, or dequeue and 302process. They can also enqueue in a different order than buffers have 303been 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 306images out of order (such as video codecs) to return buffers earlier, 307reducing the probability of data loss. Random fill order allows 308drivers to reuse buffers on a LIFO-basis, taking advantage of caches 309holding 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 312identifies the buffer.</para> 313 314 <para>Initially all mapped buffers are in dequeued state, 315inaccessible by the driver. For capturing applications it is customary 316to first enqueue all mapped buffers, then to start capturing and enter 317the read loop. Here the application waits until a filled buffer can be 318dequeued, and re-enqueues the buffer when the data is no longer 319needed. Output applications fill and enqueue buffers, when enough 320buffers are stacked up the output is started with 321<constant>VIDIOC_STREAMON</constant>. In the write loop, when 322the application runs out of free buffers, it must wait until an empty 323buffer 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 327mapped, enqueued, full or empty can be determined at any time using the 328&VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the 329application until one or more buffers can be dequeued. By default 330<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the 331outgoing queue. When the <constant>O_NONBLOCK</constant> flag was 332given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> 333returns 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 339queues as a side effect. Since there is no notion of doing anything 340"now" on a multitasking system, if an application needs to synchronize 341with another event it should examine the &v4l2-buffer; 342<structfield>timestamp</structfield> of captured buffers, or set the 343field before enqueuing buffers for output.</para> 344 345 <para>Drivers implementing memory mapping I/O must 346support 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> 353function.<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 357rest 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; 370returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user 371pointer method (not only memory mapping) is supported must be 372determined by calling the &VIDIOC-REQBUFS; ioctl.</para> 373 374 <para>This I/O method combines advantages of the read/write and 375memory mapping methods. Buffers (planes) are allocated by the application 376itself, and can reside for example in virtual or shared memory. Only 377pointers to data are exchanged, these pointers and meta-information 378are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case). 379The 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 381beforehand, consequently they are not indexed and cannot be queried like mapped 382buffers 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 390memset (&reqbuf, 0, sizeof (reqbuf)); 391reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 392reqbuf.memory = V4L2_MEMORY_USERPTR; 393 394if (ioctl (fd, &VIDIOC-REQBUFS;, &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, 407applications can pass different addresses and sizes at each 408<constant>VIDIOC_QBUF</constant> call. If required by the hardware the 409driver swaps memory pages within physical memory to create a 410continuous area of memory. This happens transparently to the 411application in the virtual memory subsystem of the kernel. When buffer 412pages have been swapped out to disk they are brought back and finally 413locked in physical memory for DMA.<footnote> 414 <para>We expect that frequently used buffers are typically not 415swapped out. Anyway, the process of swapping, locking or generating 416scatter-gather lists may be time consuming. The delay can be masked by 417the depth of the incoming buffer queue, and perhaps by maintaining 418caches assuming a buffer will be soon enqueued again. On the other 419hand, to optimize memory usage drivers can limit the number of buffers 420locked in advance and recycle the most recently used buffers first. Of 421course, the pages of empty buffers in the incoming queue need not be 422saved to disk. Output buffers must be saved on the incoming and 423outgoing queue because an application may share them with other 424processes.</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 429time between the completion of the DMA and this ioctl. The memory is 430also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or 431when the device is closed. Applications must take care not to free 432buffers without dequeuing. For once, the buffers remain locked until 433further, wasting physical memory. Second the driver will not be 434notified when the memory is returned to the application's free list 435and subsequently reused for other purposes, possibly completing the 436requested DMA and overwriting valuable data.</para> 437 438 <para>For capturing applications it is customary to enqueue a 439number of empty buffers, to start capturing and enter the read loop. 440Here the application waits until a filled buffer can be dequeued, and 441re-enqueues the buffer when the data is no longer needed. Output 442applications fill and enqueue buffers, when enough buffers are stacked 443up output is started. In the write loop, when the application 444runs out of free buffers it must wait until an empty buffer can be 445dequeued and reused. Two methods exist to suspend execution of the 446application until one or more buffers can be dequeued. By default 447<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the 448outgoing queue. When the <constant>O_NONBLOCK</constant> flag was 449given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> 450returns 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 456queues and unlocks all buffers as a side effect. Since there is no 457notion of doing anything "now" on a multitasking system, if an 458application needs to synchronize with another event it should examine 459the &v4l2-buffer; <structfield>timestamp</structfield> of captured 460buffers, or set the field before enqueuing buffers for output.</para> 461 462 <para>Drivers implementing user pointer I/O must 463support 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 471rest 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 485driver using one of the Streaming I/O methods. In the multi-planar API, the 486data is held in planes, while the buffer structure acts as a container 487for the planes. Only pointers to buffers (planes) are exchanged, the data 488itself is not copied. These pointers, together with meta-information like 489timestamps or field parity, are stored in a struct 490<structname>v4l2_buffer</structname>, argument to 491the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. 492In the multi-planar API, some plane-specific members of struct 493<structname>v4l2_buffer</structname>, such as pointers and sizes for each 494plane, are stored in struct <structname>v4l2_plane</structname> instead. 495In that case, struct <structname>v4l2_buffer</structname> contains an array of 496plane structures.</para> 497 498 <para>Nominally timestamps refer to the first data byte transmitted. 499In practice however the wide range of hardware covered by the V4L2 API 500limits timestamp accuracy. Often an interrupt routine will 501sample the system clock shortly after the field or frame was stored 502completely in memory. So applications must expect a constant 503difference up to one field or frame period plus a small (few scan 504lines) random error. The delay and error can be much 505larger due to compression or transmission over an external bus when 506the frames are not properly stamped by the sender. This is frequently 507the case with USB cameras. Here timestamps refer to the instant the 508field or frame was received by the driver, not the capture time. These 509devices identify by not enumerating any video standards, see <xref 510linkend="standard" />.</para> 511 512 <para>Similar limitations apply to output timestamps. Typically 513the video hardware locks to a clock controlling the video timing, the 514horizontal and vertical synchronization pulses. At some point in the 515line sequence, possibly the vertical blanking, an interrupt routine 516samples the system clock, compares against the timestamp and programs 517the hardware to repeat the previous field or frame, or to display the 518buffer contents.</para> 519 520 <para>Apart of limitations of the video device and natural 521inaccuracies of all clocks, it should be noted system time itself is 522not perfectly stable. It can be affected by power saving cycles, 523warped to insert leap seconds, or even turned back or forth by the 524system administrator affecting long term measurements. <footnote> 525 <para>Since no other Linux multimedia 526API supports unadjusted time it would be foolish to introduce here. We 527must use a universally supported clock to synchronize different media, 528hence 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 541field is only used for <link linkend="mmap">memory mapping</link> I/O 542and can range from zero to the number of buffers allocated 543with 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 558buffer. It depends on the negotiated data format and may change with 559each buffer for compressed variable size data like JPEG images. 560Drivers must set this field when <structfield>type</structfield> 561refers 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 568linkend="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 575buffer, see <xref linkend="v4l2-field" />. This field is not used when 576the buffer contains VBI data. Drivers must set it when 577<structfield>type</structfield> refers to an input stream, 578applications 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 585system time (as returned by the <function>gettimeofday()</function> 586function) when the first data byte was captured. For output streams 587the data will not be displayed before this time, secondary to the 588nominal frame rate determined by the current video standard in 589enqueued order. Applications can for example zero this field to 590display frames as soon as possible. The driver stores the time at 591which the first data byte was actually sent out in the 592<structfield>timestamp</structfield> field. This permits 593applications to monitor the drift between the video and system 594clock.</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 604timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> 605mode the top and bottom field contain the same timecode. 606Timecodes are intended to help video editing and are typically recorded on 607video tapes, but also embedded in compressed formats like MPEG. This 608field 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 616sequence.</entry> 617 </row> 618 <row> 619 <entry spanname="hspan"><para>In <link 620linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and 621bottom field have the same sequence number. The count starts at zero 622and includes dropped or repeated frames. A dropped frame was received 623by an input device but could not be stored due to lack of free buffer 624space. A repeated frame was displayed again by an output device 625because the application did not pass new data in 626time.</para><para>Note this may count the frames received 627e.g. over USB, without taking into account the frames dropped by the 628remote hardware due to limited compression throughput or bus 629bandwidth. These devices identify by not enumerating any video 630standards, 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 637in 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 649is the offset of the buffer from the start of the device memory. The value is 650returned by the driver and apart of serving as parameter to the &func-mmap; 651function 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> 660this is a pointer to the buffer (casted to unsigned long type) in virtual 661memory, 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 687synchronous video input changes, a function useful for example in 688video surveillance applications. For this purpose applications set the 689<constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the 690number 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 700should 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 831linkend="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 852into the application's address space, see <xref linkend="mmap" /> for details. 853Drivers 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 862incoming and outgoing queue. When this flag is set, the buffer is 863currently on the incoming queue. It automatically moves to the 864outgoing queue after the buffer has been filled (capture devices) or 865displayed (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 868always set and after <constant>VIDIOC_DQBUF</constant> always 869cleared.</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 875the outgoing queue, ready to be dequeued from the driver. Drivers set 876or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl 877is called. After calling the <constant>VIDIOC_QBUF</constant> or 878<constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a 879buffer 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. 882They can be both cleared however, then the buffer is in "dequeued" 883state, 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 900capture devices when the buffer contains a compressed image which is a 901key 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> 907this flags predicted frames or fields which contain only differences to a 908previous 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. 920Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> 921ioctl 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. 927Applications set or clear this flag before calling the 928<constant>VIDIOC_QBUF</constant> ioctl.</entry> 929 </row> 930 <row> 931 <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry> 932 <entry>0x0400</entry> 933 <entry>The buffer has been prepared for I/O and can be queued by the 934application. Drivers set or clear this flag when the 935<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link 936 linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link 937 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link 938 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry> 939 </row> 940 <row> 941 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry> 942 <entry>0x0400</entry> 943 <entry>Caches do not have to be invalidated for this buffer. 944Typically applications shall use this flag if the data captured in the buffer 945is not going to be touched by the CPU, instead the buffer will, probably, be 946passed on to a DMA-capable hardware unit for further processing or output. 947</entry> 948 </row> 949 <row> 950 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry> 951 <entry>0x0800</entry> 952 <entry>Caches do not have to be cleaned for this buffer. 953Typically applications shall use this flag for output buffers if the data 954in this buffer has not been created by the CPU but by some DMA-capable unit, 955in which case caches have not been used.</entry> 956 </row> 957 </tbody> 958 </tgroup> 959 </table> 960 961 <table pgwide="1" frame="none" id="v4l2-memory"> 962 <title>enum v4l2_memory</title> 963 <tgroup cols="3"> 964 &cs-def; 965 <tbody valign="top"> 966 <row> 967 <entry><constant>V4L2_MEMORY_MMAP</constant></entry> 968 <entry>1</entry> 969 <entry>The buffer is used for <link linkend="mmap">memory 970mapping</link> I/O.</entry> 971 </row> 972 <row> 973 <entry><constant>V4L2_MEMORY_USERPTR</constant></entry> 974 <entry>2</entry> 975 <entry>The buffer is used for <link linkend="userp">user 976pointer</link> I/O.</entry> 977 </row> 978 <row> 979 <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry> 980 <entry>3</entry> 981 <entry>[to do]</entry> 982 </row> 983 </tbody> 984 </tgroup> 985 </table> 986 987 <section> 988 <title>Timecodes</title> 989 990 <para>The <structname>v4l2_timecode</structname> structure is 991designed to hold a <xref linkend="smpte12m" /> or similar timecode. 992(struct <structname>timeval</structname> timestamps are stored in 993&v4l2-buffer; field <structfield>timestamp</structfield>.)</para> 994 995 <table frame="none" pgwide="1" id="v4l2-timecode"> 996 <title>struct <structname>v4l2_timecode</structname></title> 997 <tgroup cols="3"> 998 &cs-str; 999 <tbody valign="top"> 1000 <row> 1001 <entry>__u32</entry> 1002 <entry><structfield>type</structfield></entry> 1003 <entry>Frame rate the timecodes are based on, see <xref 1004 linkend="timecode-type" />.</entry> 1005 </row> 1006 <row> 1007 <entry>__u32</entry> 1008 <entry><structfield>flags</structfield></entry> 1009 <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry> 1010 </row> 1011 <row> 1012 <entry>__u8</entry> 1013 <entry><structfield>frames</structfield></entry> 1014 <entry>Frame count, 0 ... 23/24/29/49/59, depending on the 1015 type of timecode.</entry> 1016 </row> 1017 <row> 1018 <entry>__u8</entry> 1019 <entry><structfield>seconds</structfield></entry> 1020 <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry> 1021 </row> 1022 <row> 1023 <entry>__u8</entry> 1024 <entry><structfield>minutes</structfield></entry> 1025 <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry> 1026 </row> 1027 <row> 1028 <entry>__u8</entry> 1029 <entry><structfield>hours</structfield></entry> 1030 <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry> 1031 </row> 1032 <row> 1033 <entry>__u8</entry> 1034 <entry><structfield>userbits</structfield>[4]</entry> 1035 <entry>The "user group" bits from the timecode.</entry> 1036 </row> 1037 </tbody> 1038 </tgroup> 1039 </table> 1040 1041 <table frame="none" pgwide="1" id="timecode-type"> 1042 <title>Timecode Types</title> 1043 <tgroup cols="3"> 1044 &cs-def; 1045 <tbody valign="top"> 1046 <row> 1047 <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry> 1048 <entry>1</entry> 1049 <entry>24 frames per second, i. e. film.</entry> 1050 </row> 1051 <row> 1052 <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry> 1053 <entry>2</entry> 1054 <entry>25 frames per second, &ie; PAL or SECAM video.</entry> 1055 </row> 1056 <row> 1057 <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry> 1058 <entry>3</entry> 1059 <entry>30 frames per second, &ie; NTSC video.</entry> 1060 </row> 1061 <row> 1062 <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry> 1063 <entry>4</entry> 1064 <entry></entry> 1065 </row> 1066 <row> 1067 <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry> 1068 <entry>5</entry> 1069 <entry></entry> 1070 </row> 1071 </tbody> 1072 </tgroup> 1073 </table> 1074 1075 <table frame="none" pgwide="1" id="timecode-flags"> 1076 <title>Timecode Flags</title> 1077 <tgroup cols="3"> 1078 &cs-def; 1079 <tbody valign="top"> 1080 <row> 1081 <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry> 1082 <entry>0x0001</entry> 1083 <entry>Indicates "drop frame" semantics for counting frames 1084in 29.97 fps material. When set, frame numbers 0 and 1 at the start of 1085each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the 1086count.</entry> 1087 </row> 1088 <row> 1089 <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry> 1090 <entry>0x0002</entry> 1091 <entry>The "color frame" flag.</entry> 1092 </row> 1093 <row> 1094 <entry><constant>V4L2_TC_USERBITS_field</constant></entry> 1095 <entry>0x000C</entry> 1096 <entry>Field mask for the "binary group flags".</entry> 1097 </row> 1098 <row> 1099 <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry> 1100 <entry>0x0000</entry> 1101 <entry>Unspecified format.</entry> 1102 </row> 1103 <row> 1104 <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry> 1105 <entry>0x0008</entry> 1106 <entry>8-bit ISO characters.</entry> 1107 </row> 1108 </tbody> 1109 </tgroup> 1110 </table> 1111 </section> 1112 </section> 1113 1114 <section id="field-order"> 1115 <title>Field Order</title> 1116 1117 <para>We have to distinguish between progressive and interlaced 1118video. Progressive video transmits all lines of a video image 1119sequentially. Interlaced video divides an image into two fields, 1120containing only the odd and even lines of the image, respectively. 1121Alternating the so called odd and even field are transmitted, and due 1122to a small delay between fields a cathode ray TV displays the lines 1123interleaved, yielding the original frame. This curious technique was 1124invented because at refresh rates similar to film the image would 1125fade out too quickly. Transmitting fields reduces the flicker without 1126the necessity of doubling the frame rate and with it the bandwidth 1127required for each channel.</para> 1128 1129 <para>It is important to understand a video camera does not expose 1130one frame at a time, merely transmitting the frames separated into 1131fields. The fields are in fact captured at two different instances in 1132time. An object on screen may well move between one field and the 1133next. For applications analysing motion it is of paramount importance 1134to recognize which field of a frame is older, the <emphasis>temporal 1135order</emphasis>.</para> 1136 1137 <para>When the driver provides or accepts images field by field 1138rather than interleaved, it is also important applications understand 1139how the fields combine to frames. We distinguish between top (aka odd) and 1140bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line 1141of the top field is the first line of an interlaced frame, the first 1142line of the bottom field is the second line of that frame.</para> 1143 1144 <para>However because fields were captured one after the other, 1145arguing whether a frame commences with the top or bottom field is 1146pointless. Any two successive top and bottom, or bottom and top fields 1147yield a valid frame. Only when the source was progressive to begin 1148with, ⪚ when transferring film to video, two fields may come from 1149the same frame, creating a natural order.</para> 1150 1151 <para>Counter to intuition the top field is not necessarily the 1152older field. Whether the older field contains the top or bottom lines 1153is a convention determined by the video standard. Hence the 1154distinction between temporal and spatial order of fields. The diagrams 1155below should make this clearer.</para> 1156 1157 <para>All video capture and output devices must report the current 1158field order. Some drivers may permit the selection of a different 1159order, to this end applications initialize the 1160<structfield>field</structfield> field of &v4l2-pix-format; before 1161calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should 1162have the value <constant>V4L2_FIELD_ANY</constant> (0).</para> 1163 1164 <table frame="none" pgwide="1" id="v4l2-field"> 1165 <title>enum v4l2_field</title> 1166 <tgroup cols="3"> 1167 &cs-def; 1168 <tbody valign="top"> 1169 <row> 1170 <entry><constant>V4L2_FIELD_ANY</constant></entry> 1171 <entry>0</entry> 1172 <entry>Applications request this field order when any 1173one of the <constant>V4L2_FIELD_NONE</constant>, 1174<constant>V4L2_FIELD_TOP</constant>, 1175<constant>V4L2_FIELD_BOTTOM</constant>, or 1176<constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. 1177Drivers choose depending on hardware capabilities or e. g. the 1178requested image size, and return the actual field order. &v4l2-buffer; 1179<structfield>field</structfield> can never be 1180<constant>V4L2_FIELD_ANY</constant>.</entry> 1181 </row> 1182 <row> 1183 <entry><constant>V4L2_FIELD_NONE</constant></entry> 1184 <entry>1</entry> 1185 <entry>Images are in progressive format, not interlaced. 1186The driver may also indicate this order when it cannot distinguish 1187between <constant>V4L2_FIELD_TOP</constant> and 1188<constant>V4L2_FIELD_BOTTOM</constant>.</entry> 1189 </row> 1190 <row> 1191 <entry><constant>V4L2_FIELD_TOP</constant></entry> 1192 <entry>2</entry> 1193 <entry>Images consist of the top (aka odd) field only.</entry> 1194 </row> 1195 <row> 1196 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> 1197 <entry>3</entry> 1198 <entry>Images consist of the bottom (aka even) field only. 1199Applications may wish to prevent a device from capturing interlaced 1200images because they will have "comb" or "feathering" artefacts around 1201moving objects.</entry> 1202 </row> 1203 <row> 1204 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> 1205 <entry>4</entry> 1206 <entry>Images contain both fields, interleaved line by 1207line. The temporal order of the fields (whether the top or bottom 1208field is first transmitted) depends on the current video standard. 1209M/NTSC transmits the bottom field first, all other standards the top 1210field first.</entry> 1211 </row> 1212 <row> 1213 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> 1214 <entry>5</entry> 1215 <entry>Images contain both fields, the top field lines 1216are stored first in memory, immediately followed by the bottom field 1217lines. Fields are always stored in temporal order, the older one first 1218in memory. Image sizes refer to the frame, not fields.</entry> 1219 </row> 1220 <row> 1221 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> 1222 <entry>6</entry> 1223 <entry>Images contain both fields, the bottom field 1224lines are stored first in memory, immediately followed by the top 1225field lines. Fields are always stored in temporal order, the older one 1226first in memory. Image sizes refer to the frame, not fields.</entry> 1227 </row> 1228 <row> 1229 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> 1230 <entry>7</entry> 1231 <entry>The two fields of a frame are passed in separate 1232buffers, in temporal order, &ie; the older one first. To indicate the field 1233parity (whether the current field is a top or bottom field) the driver 1234or application, depending on data direction, must set &v4l2-buffer; 1235<structfield>field</structfield> to 1236<constant>V4L2_FIELD_TOP</constant> or 1237<constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair 1238to build a frame. If fields are successive, without any dropped fields 1239between them (fields can drop individually), can be determined from 1240the &v4l2-buffer; <structfield>sequence</structfield> field. Image 1241sizes refer to the frame, not fields. This format cannot be selected 1242when using the read/write I/O method.<!-- Where it's indistinguishable 1243from V4L2_FIELD_SEQ_*. --></entry> 1244 </row> 1245 <row> 1246 <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry> 1247 <entry>8</entry> 1248 <entry>Images contain both fields, interleaved line by 1249line, top field first. The top field is transmitted first.</entry> 1250 </row> 1251 <row> 1252 <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry> 1253 <entry>9</entry> 1254 <entry>Images contain both fields, interleaved line by 1255line, top field first. The bottom field is transmitted first.</entry> 1256 </row> 1257 </tbody> 1258 </tgroup> 1259 </table> 1260 1261 <figure id="fieldseq-tb"> 1262 <title>Field Order, Top Field First Transmitted</title> 1263 <mediaobject> 1264 <imageobject> 1265 <imagedata fileref="fieldseq_tb.pdf" format="PS" /> 1266 </imageobject> 1267 <imageobject> 1268 <imagedata fileref="fieldseq_tb.gif" format="GIF" /> 1269 </imageobject> 1270 </mediaobject> 1271 </figure> 1272 1273 <figure id="fieldseq-bt"> 1274 <title>Field Order, Bottom Field First Transmitted</title> 1275 <mediaobject> 1276 <imageobject> 1277 <imagedata fileref="fieldseq_bt.pdf" format="PS" /> 1278 </imageobject> 1279 <imageobject> 1280 <imagedata fileref="fieldseq_bt.gif" format="GIF" /> 1281 </imageobject> 1282 </mediaobject> 1283 </figure> 1284 </section> 1285
