Based on kernel version 3.0.4. Page generated on 2011-10-03 22:07 EST.
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 > 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. 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(&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;, &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 < 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 < 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 203 for (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 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(&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;, &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 237 if (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 243 buffers = calloc(reqbuf.count, sizeof(*buffers)); 244 assert(buffers != NULL); 245 246 for (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 284 for (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 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 (&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;, &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. 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, ⪚ 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. 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 -->
