1 <title>Input/Output</title>
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>
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>
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
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>
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>
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>
35 <para>The following sections describe the various I/O methods in
39 <title>Read/Write</title>
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>
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
60 > vidctrl /dev/video --input=0 --format=YUYV --size=352x288
61 > dd if=/dev/video of=myimage.422 bs=202752 count=1
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;
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>
84 <title>Streaming I/O (Memory Mapping)</title>
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>
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>
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>
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
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>
139 <title>Mapping buffers in the single-planar API</title>
141 &v4l2-requestbuffers; reqbuf;
148 memset(&reqbuf, 0, sizeof(reqbuf));
149 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
150 reqbuf.memory = V4L2_MEMORY_MMAP;
153 if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) {
155 printf("Video capturing or mmap-streaming is not supported\n");
157 perror("VIDIOC_REQBUFS");
162 /* We want at least five buffers. */
164 if (reqbuf.count < 5) {
165 /* You may need to free the buffers here. */
166 printf("Not enough buffer memory\n");
170 buffers = calloc(reqbuf.count, sizeof(*buffers));
171 assert(buffers != NULL);
173 for (i = 0; i < reqbuf.count; i++) {
174 &v4l2-buffer; buffer;
176 memset(&buffer, 0, sizeof(buffer));
177 buffer.type = reqbuf.type;
178 buffer.memory = V4L2_MEMORY_MMAP;
181 if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &buffer)) {
182 perror("VIDIOC_QUERYBUF");
186 buffers[i].length = buffer.length; /* remember for munmap() */
188 buffers[i].start = mmap(NULL, buffer.length,
189 PROT_READ | PROT_WRITE, /* recommended */
190 MAP_SHARED, /* recommended */
191 fd, buffer.m.offset);
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. */
203 for (i = 0; i < reqbuf.count; i++)
204 munmap(buffers[i].start, buffers[i].length);
209 <title>Mapping buffers in the multi-planar API</title>
211 &v4l2-requestbuffers; reqbuf;
212 /* Our current format uses 3 planes per buffer */
213 #define FMT_NUM_PLANES = 3
216 void *start[FMT_NUM_PLANES];
217 size_t length[FMT_NUM_PLANES];
221 memset(&reqbuf, 0, sizeof(reqbuf));
222 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
223 reqbuf.memory = V4L2_MEMORY_MMAP;
226 if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 0) {
228 printf("Video capturing or mmap-streaming is not supported\n");
230 perror("VIDIOC_REQBUFS");
235 /* We want at least five buffers. */
237 if (reqbuf.count < 5) {
238 /* You may need to free the buffers here. */
239 printf("Not enough buffer memory\n");
243 buffers = calloc(reqbuf.count, sizeof(*buffers));
244 assert(buffers != NULL);
246 for (i = 0; i < reqbuf.count; i++) {
247 &v4l2-buffer; buffer;
248 &v4l2-plane; planes[FMT_NUM_PLANES];
250 memset(&buffer, 0, sizeof(buffer));
251 buffer.type = reqbuf.type;
252 buffer.memory = V4L2_MEMORY_MMAP;
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;
259 if (ioctl(fd, &VIDIOC-QUERYBUF;, &buffer) < 0) {
260 perror("VIDIOC_QUERYBUF");
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() */
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);
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. */
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]);
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>
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>
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>
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; functions are always available.</para>
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 or outputted buffers.
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>
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>
360 <para>[capture example]</para>
365 <title>Streaming I/O (User Pointers)</title>
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>
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>
385 <title>Initiating streaming I/O with user pointers</title>
388 &v4l2-requestbuffers; reqbuf;
390 memset (&reqbuf, 0, sizeof (reqbuf));
391 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
392 reqbuf.memory = V4L2_MEMORY_USERPTR;
394 if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) {
396 printf ("Video capturing or user pointer streaming is not supported\n");
398 perror ("VIDIOC_REQBUFS");
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
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>
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>
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 or outputted buffers.</para>
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>
475 <section id="dmabuf">
476 <title>Streaming I/O (DMA buffer importing)</title>
479 <title>Experimental</title>
480 <para>This is an <link linkend="experimental">experimental</link>
481 interface and may change in the future.</para>
484 <para>The DMABUF framework provides a generic method for sharing buffers
485 between multiple devices. Device drivers that support DMABUF can export a DMA
486 buffer to userspace as a file descriptor (known as the exporter role), import a
487 DMA buffer from userspace using a file descriptor previously exported for a
488 different or the same device (known as the importer role), or both. This
489 section describes the DMABUF importer role API in V4L2.</para>
491 <para>Refer to <link linkend="vidioc-expbuf">DMABUF exporting</link> for
492 details about exporting V4L2 buffers as DMABUF file descriptors.</para>
494 <para>Input and output devices support the streaming I/O method when the
495 <constant>V4L2_CAP_STREAMING</constant> flag in the
496 <structfield>capabilities</structfield> field of &v4l2-capability; returned by
497 the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through
498 DMABUF file descriptors is supported is determined by calling the
499 &VIDIOC-REQBUFS; ioctl with the memory type set to
500 <constant>V4L2_MEMORY_DMABUF</constant>.</para>
502 <para>This I/O method is dedicated to sharing DMA buffers between different
503 devices, which may be V4L devices or other video-related devices (e.g. DRM).
504 Buffers (planes) are allocated by a driver on behalf of an application. Next,
505 these buffers are exported to the application as file descriptors using an API
506 which is specific for an allocator driver. Only such file descriptor are
507 exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or
508 in &v4l2-plane; in the multi-planar API case). The driver must be switched
509 into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer
513 <title>Initiating streaming I/O with DMABUF file descriptors</title>
516 &v4l2-requestbuffers; reqbuf;
518 memset(&reqbuf, 0, sizeof (reqbuf));
519 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
520 reqbuf.memory = V4L2_MEMORY_DMABUF;
523 if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) {
525 printf("Video capturing or DMABUF streaming is not supported\n");
527 perror("VIDIOC_REQBUFS");
534 <para>The buffer (plane) file descriptor is passed on the fly with the
535 &VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be
536 associated with a different DMABUF descriptor. Although buffers are commonly
537 cycled, applications can pass a different DMABUF descriptor at each
538 <constant>VIDIOC_QBUF</constant> call.</para>
541 <title>Queueing DMABUF using single plane API</title>
544 int buffer_queue(int v4lfd, int index, int dmafd)
548 memset(&buf, 0, sizeof buf);
549 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
550 buf.memory = V4L2_MEMORY_DMABUF;
554 if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) {
555 perror("VIDIOC_QBUF");
565 <title>Queueing DMABUF using multi plane API</title>
568 int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
571 &v4l2-plane; planes[VIDEO_MAX_PLANES];
574 memset(&buf, 0, sizeof buf);
575 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
576 buf.memory = V4L2_MEMORY_DMABUF;
578 buf.m.planes = planes;
579 buf.length = n_planes;
581 memset(&planes, 0, sizeof planes);
583 for (i = 0; i < n_planes; ++i)
584 buf.m.planes[i].m.fd = dmafd[i];
586 if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) {
587 perror("VIDIOC_QBUF");
596 <para>Captured or displayed buffers are dequeued with the
597 &VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any
598 time between the completion of the DMA and this ioctl. The memory is
599 also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
600 when the device is closed.</para>
602 <para>For capturing applications it is customary to enqueue a
603 number of empty buffers, to start capturing and enter the read loop.
604 Here the application waits until a filled buffer can be dequeued, and
605 re-enqueues the buffer when the data is no longer needed. Output
606 applications fill and enqueue buffers, when enough buffers are stacked
607 up output is started. In the write loop, when the application
608 runs out of free buffers it must wait until an empty buffer can be
609 dequeued and reused. Two methods exist to suspend execution of the
610 application until one or more buffers can be dequeued. By default
611 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
612 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
613 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
614 returns immediately with an &EAGAIN; when no buffer is available. The
615 &func-select; and &func-poll; functions are always available.</para>
617 <para>To start and stop capturing or displaying applications call the
618 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that
619 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both queues and
620 unlocks all buffers as a side effect. Since there is no notion of doing
621 anything "now" on a multitasking system, if an application needs to synchronize
622 with another event it should examine the &v4l2-buffer;
623 <structfield>timestamp</structfield> of captured or outputted buffers.</para>
625 <para>Drivers implementing DMABUF importing I/O must support the
626 <constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>,
627 <constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and
628 <constant>VIDIOC_STREAMOFF</constant> ioctls, and the
629 <function>select()</function> and <function>poll()</function> functions.</para>
634 <title>Asynchronous I/O</title>
636 <para>This method is not defined yet.</para>
639 <section id="buffer">
640 <title>Buffers</title>
642 <para>A buffer contains data exchanged by application and
643 driver using one of the Streaming I/O methods. In the multi-planar API, the
644 data is held in planes, while the buffer structure acts as a container
645 for the planes. Only pointers to buffers (planes) are exchanged, the data
646 itself is not copied. These pointers, together with meta-information like
647 timestamps or field parity, are stored in a struct
648 <structname>v4l2_buffer</structname>, argument to
649 the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.
650 In the multi-planar API, some plane-specific members of struct
651 <structname>v4l2_buffer</structname>, such as pointers and sizes for each
652 plane, are stored in struct <structname>v4l2_plane</structname> instead.
653 In that case, struct <structname>v4l2_buffer</structname> contains an array of
654 plane structures.</para>
656 <para>Dequeued video buffers come with timestamps. The driver
657 decides at which part of the frame and with which clock the
658 timestamp is taken. Please see flags in the masks
659 <constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant> and
660 <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> in <xref
661 linkend="buffer-flags" />. These flags are always valid and constant
662 across all buffers during the whole video stream. Changes in these
663 flags may take place as a side effect of &VIDIOC-S-INPUT; or
664 &VIDIOC-S-OUTPUT; however. The
665 <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> timestamp type
666 which is used by e.g. on mem-to-mem devices is an exception to the
667 rule: the timestamp source flags are copied from the OUTPUT video
668 buffer to the CAPTURE video buffer.</para>
670 <table frame="none" pgwide="1" id="v4l2-buffer">
671 <title>struct <structname>v4l2_buffer</structname></title>
677 <entry><structfield>index</structfield></entry>
679 <entry>Number of the buffer, set by the application except
680 when calling &VIDIOC-DQBUF;, then it is set by the driver.
681 This field can range from zero to the number of buffers allocated
682 with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>),
683 plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry>
687 <entry><structfield>type</structfield></entry>
689 <entry>Type of the buffer, same as &v4l2-format;
690 <structfield>type</structfield> or &v4l2-requestbuffers;
691 <structfield>type</structfield>, set by the application. See <xref
692 linkend="v4l2-buf-type" /></entry>
696 <entry><structfield>bytesused</structfield></entry>
698 <entry>The number of bytes occupied by the data in the
699 buffer. It depends on the negotiated data format and may change with
700 each buffer for compressed variable size data like JPEG images.
701 Drivers must set this field when <structfield>type</structfield>
702 refers to an input stream, applications when it refers to an output stream.</entry>
706 <entry><structfield>flags</structfield></entry>
708 <entry>Flags set by the application or driver, see <xref
709 linkend="buffer-flags" />.</entry>
713 <entry><structfield>field</structfield></entry>
715 <entry>Indicates the field order of the image in the
716 buffer, see <xref linkend="v4l2-field" />. This field is not used when
717 the buffer contains VBI data. Drivers must set it when
718 <structfield>type</structfield> refers to an input stream,
719 applications when it refers to an output stream.</entry>
722 <entry>struct timeval</entry>
723 <entry><structfield>timestamp</structfield></entry>
725 <entry><para>For input streams this is time when the first data
726 byte was captured, as returned by the
727 <function>clock_gettime()</function> function for the relevant
728 clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in
729 <xref linkend="buffer-flags" />. For output streams the driver
730 stores the time at which the last data byte was actually sent out
731 in the <structfield>timestamp</structfield> field. This permits
732 applications to monitor the drift between the video and system
733 clock. For output streams that use <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant>
734 the application has to fill in the timestamp which will be copied
735 by the driver to the capture stream.</para></entry>
738 <entry>&v4l2-timecode;</entry>
739 <entry><structfield>timecode</structfield></entry>
741 <entry>When <structfield>type</structfield> is
742 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the
743 <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in
744 <structfield>flags</structfield>, this structure contains a frame
745 timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
746 mode the top and bottom field contain the same timecode.
747 Timecodes are intended to help video editing and are typically recorded on
748 video tapes, but also embedded in compressed formats like MPEG. This
749 field is independent of the <structfield>timestamp</structfield> and
750 <structfield>sequence</structfield> fields.</entry>
754 <entry><structfield>sequence</structfield></entry>
756 <entry>Set by the driver, counting the frames (not fields!) in
757 sequence. This field is set for both input and output devices.</entry>
760 <entry spanname="hspan"><para>In <link
761 linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and
762 bottom field have the same sequence number. The count starts at zero
763 and includes dropped or repeated frames. A dropped frame was received
764 by an input device but could not be stored due to lack of free buffer
765 space. A repeated frame was displayed again by an output device
766 because the application did not pass new data in
767 time.</para><para>Note this may count the frames received
768 e.g. over USB, without taking into account the frames dropped by the
769 remote hardware due to limited compression throughput or bus
770 bandwidth. These devices identify by not enumerating any video
771 standards, see <xref linkend="standard" />.</para></entry>
775 <entry><structfield>memory</structfield></entry>
777 <entry>This field must be set by applications and/or drivers
778 in accordance with the selected I/O method. See <xref linkend="v4l2-memory"
783 <entry><structfield>m</structfield></entry>
788 <entry><structfield>offset</structfield></entry>
789 <entry>For the single-planar API and when
790 <structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this
791 is the offset of the buffer from the start of the device memory. The value is
792 returned by the driver and apart of serving as parameter to the &func-mmap;
793 function not useful for applications. See <xref linkend="mmap" /> for details
798 <entry>unsigned long</entry>
799 <entry><structfield>userptr</structfield></entry>
800 <entry>For the single-planar API and when
801 <structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant>
802 this is a pointer to the buffer (casted to unsigned long type) in virtual
803 memory, set by the application. See <xref linkend="userp" /> for details.
808 <entry>struct v4l2_plane</entry>
809 <entry><structfield>*planes</structfield></entry>
810 <entry>When using the multi-planar API, contains a userspace pointer
811 to an array of &v4l2-plane;. The size of the array should be put
812 in the <structfield>length</structfield> field of this
813 <structname>v4l2_buffer</structname> structure.</entry>
818 <entry><structfield>fd</structfield></entry>
819 <entry>For the single-plane API and when
820 <structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this
821 is the file descriptor associated with a DMABUF buffer.</entry>
825 <entry><structfield>length</structfield></entry>
827 <entry>Size of the buffer (not the payload) in bytes for the
828 single-planar API. This is set by the driver based on the calls to
829 &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. For the multi-planar API the application sets
830 this to the number of elements in the <structfield>planes</structfield>
831 array. The driver will fill in the actual number of valid elements in
837 <entry><structfield>reserved2</structfield></entry>
839 <entry>A place holder for future extensions. Applications
840 should set this to 0.</entry>
844 <entry><structfield>reserved</structfield></entry>
846 <entry>A place holder for future extensions. Applications
847 should set this to 0.</entry>
853 <table frame="none" pgwide="1" id="v4l2-plane">
854 <title>struct <structname>v4l2_plane</structname></title>
860 <entry><structfield>bytesused</structfield></entry>
862 <entry>The number of bytes occupied by data in the plane
863 (its payload). Drivers must set this field when <structfield>type</structfield>
864 refers to an input stream, applications when it refers to an output stream.</entry>
868 <entry><structfield>length</structfield></entry>
870 <entry>Size in bytes of the plane (not its payload). This is set by the driver
871 based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;.</entry>
875 <entry><structfield>m</structfield></entry>
882 <entry><structfield>mem_offset</structfield></entry>
883 <entry>When the memory type in the containing &v4l2-buffer; is
884 <constant>V4L2_MEMORY_MMAP</constant>, this is the value that
885 should be passed to &func-mmap;, similar to the
886 <structfield>offset</structfield> field in &v4l2-buffer;.</entry>
890 <entry>unsigned long</entry>
891 <entry><structfield>userptr</structfield></entry>
892 <entry>When the memory type in the containing &v4l2-buffer; is
893 <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace
894 pointer to the memory allocated for this plane by an application.
900 <entry><structfield>fd</structfield></entry>
901 <entry>When the memory type in the containing &v4l2-buffer; is
902 <constant>V4L2_MEMORY_DMABUF</constant>, this is a file
903 descriptor associated with a DMABUF buffer, similar to the
904 <structfield>fd</structfield> field in &v4l2-buffer;.</entry>
908 <entry><structfield>data_offset</structfield></entry>
910 <entry>Offset in bytes to video data in the plane.
911 Drivers must set this field when <structfield>type</structfield>
912 refers to an input stream, applications when it refers to an output stream.
917 <entry><structfield>reserved[11]</structfield></entry>
919 <entry>Reserved for future use. Should be zeroed by an
926 <table frame="none" pgwide="1" id="v4l2-buf-type">
927 <title>enum v4l2_buf_type</title>
932 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
934 <entry>Buffer of a single-planar video capture stream, see <xref
935 linkend="capture" />.</entry>
938 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
941 <entry>Buffer of a multi-planar video capture stream, see <xref
942 linkend="capture" />.</entry>
945 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
947 <entry>Buffer of a single-planar video output stream, see <xref
948 linkend="output" />.</entry>
951 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>
954 <entry>Buffer of a multi-planar video output stream, see <xref
955 linkend="output" />.</entry>
958 <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
960 <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry>
963 <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
965 <entry>Buffer of a raw VBI capture stream, see <xref
966 linkend="raw-vbi" />.</entry>
969 <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
971 <entry>Buffer of a raw VBI output stream, see <xref
972 linkend="raw-vbi" />.</entry>
975 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
977 <entry>Buffer of a sliced VBI capture stream, see <xref
978 linkend="sliced" />.</entry>
981 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
983 <entry>Buffer of a sliced VBI output stream, see <xref
984 linkend="sliced" />.</entry>
987 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry>
989 <entry>Buffer for video output overlay (OSD), see <xref
990 linkend="osd" />.</entry>
993 <entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry>
995 <entry>Buffer for Software Defined Radio (SDR), see <xref
996 linkend="sdr" />.</entry>
1002 <table frame="none" pgwide="1" id="buffer-flags">
1003 <title>Buffer Flags</title>
1006 <tbody valign="top">
1008 <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
1009 <entry>0x00000001</entry>
1010 <entry>The buffer resides in device memory and has been mapped
1011 into the application's address space, see <xref linkend="mmap" /> for details.
1012 Drivers set or clear this flag when the
1013 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
1014 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
1015 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
1018 <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
1019 <entry>0x00000002</entry>
1020 <entry>Internally drivers maintain two buffer queues, an
1021 incoming and outgoing queue. When this flag is set, the buffer is
1022 currently on the incoming queue. It automatically moves to the
1023 outgoing queue after the buffer has been filled (capture devices) or
1024 displayed (output devices). Drivers set or clear this flag when the
1025 <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
1026 (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
1027 always set and after <constant>VIDIOC_DQBUF</constant> always
1031 <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
1032 <entry>0x00000004</entry>
1033 <entry>When this flag is set, the buffer is currently on
1034 the outgoing queue, ready to be dequeued from the driver. Drivers set
1035 or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
1036 is called. After calling the <constant>VIDIOC_QBUF</constant> or
1037 <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
1038 buffer cannot be on both queues at the same time, the
1039 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
1040 <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
1041 They can be both cleared however, then the buffer is in "dequeued"
1042 state, in the application domain so to say.</entry>
1045 <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
1046 <entry>0x00000040</entry>
1047 <entry>When this flag is set, the buffer has been dequeued
1048 successfully, although the data might have been corrupted.
1049 This is recoverable, streaming may continue as normal and
1050 the buffer may be reused normally.
1051 Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
1052 ioctl is called.</entry>
1055 <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
1056 <entry>0x00000008</entry>
1057 <entry>Drivers set or clear this flag when calling the
1058 <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
1059 capture devices when the buffer contains a compressed image which is a
1060 key frame (or field), &ie; can be decompressed on its own. Also know as
1061 an I-frame. Applications can set this bit when <structfield>type</structfield>
1062 refers to an output stream.</entry>
1065 <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
1066 <entry>0x00000010</entry>
1067 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
1068 this flags predicted frames or fields which contain only differences to a
1069 previous key frame. Applications can set this bit when <structfield>type</structfield>
1070 refers to an output stream.</entry>
1073 <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
1074 <entry>0x00000020</entry>
1075 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
1076 this flags a bi-directional predicted frame or field which contains only
1077 the differences between the current frame and both the preceding and following
1078 key frames to specify its content. Applications can set this bit when
1079 <structfield>type</structfield> refers to an output stream.</entry>
1082 <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
1083 <entry>0x00000100</entry>
1084 <entry>The <structfield>timecode</structfield> field is valid.
1085 Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
1086 ioctl is called. Applications can set this bit and the corresponding
1087 <structfield>timecode</structfield> structure when <structfield>type</structfield>
1088 refers to an output stream.</entry>
1091 <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>
1092 <entry>0x00000400</entry>
1093 <entry>The buffer has been prepared for I/O and can be queued by the
1094 application. Drivers set or clear this flag when the
1095 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
1096 linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link
1097 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
1098 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry>
1101 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry>
1102 <entry>0x00000800</entry>
1103 <entry>Caches do not have to be invalidated for this buffer.
1104 Typically applications shall use this flag if the data captured in the buffer
1105 is not going to be touched by the CPU, instead the buffer will, probably, be
1106 passed on to a DMA-capable hardware unit for further processing or output.
1110 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry>
1111 <entry>0x00001000</entry>
1112 <entry>Caches do not have to be cleaned for this buffer.
1113 Typically applications shall use this flag for output buffers if the data
1114 in this buffer has not been created by the CPU but by some DMA-capable unit,
1115 in which case caches have not been used.</entry>
1118 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry>
1119 <entry>0x0000e000</entry>
1120 <entry>Mask for timestamp types below. To test the
1121 timestamp type, mask out bits not belonging to timestamp
1122 type by performing a logical and operation with buffer
1123 flags and timestamp mask.</entry>
1126 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry>
1127 <entry>0x00000000</entry>
1128 <entry>Unknown timestamp type. This type is used by
1129 drivers before Linux 3.9 and may be either monotonic (see
1130 below) or realtime (wall clock). Monotonic clock has been
1131 favoured in embedded systems whereas most of the drivers
1132 use the realtime clock. Either kinds of timestamps are
1133 available in user space via
1134 <function>clock_gettime(2)</function> using clock IDs
1135 <constant>CLOCK_MONOTONIC</constant> and
1136 <constant>CLOCK_REALTIME</constant>, respectively.</entry>
1139 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry>
1140 <entry>0x00002000</entry>
1141 <entry>The buffer timestamp has been taken from the
1142 <constant>CLOCK_MONOTONIC</constant> clock. To access the
1143 same clock outside V4L2, use
1144 <function>clock_gettime(2)</function> .</entry>
1147 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry>
1148 <entry>0x00004000</entry>
1149 <entry>The CAPTURE buffer timestamp has been taken from the
1150 corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry>
1153 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry>
1154 <entry>0x00070000</entry>
1155 <entry>Mask for timestamp sources below. The timestamp source
1156 defines the point of time the timestamp is taken in relation to
1157 the frame. Logical 'and' operation between the
1158 <structfield>flags</structfield> field and
1159 <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the
1160 value of the timestamp source. Applications must set the timestamp
1161 source when <structfield>type</structfield> refers to an output stream
1162 and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry>
1165 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry>
1166 <entry>0x00000000</entry>
1167 <entry>End Of Frame. The buffer timestamp has been taken
1168 when the last pixel of the frame has been received or the
1169 last pixel of the frame has been transmitted. In practice,
1170 software generated timestamps will typically be read from
1171 the clock a small amount of time after the last pixel has
1172 been received or transmitten, depending on the system and
1173 other activity in it.</entry>
1176 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry>
1177 <entry>0x00010000</entry>
1178 <entry>Start Of Exposure. The buffer timestamp has been
1179 taken when the exposure of the frame has begun. This is
1181 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer
1188 <table pgwide="1" frame="none" id="v4l2-memory">
1189 <title>enum v4l2_memory</title>
1192 <tbody valign="top">
1194 <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
1196 <entry>The buffer is used for <link linkend="mmap">memory
1197 mapping</link> I/O.</entry>
1200 <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
1202 <entry>The buffer is used for <link linkend="userp">user
1203 pointer</link> I/O.</entry>
1206 <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
1208 <entry>[to do]</entry>
1211 <entry><constant>V4L2_MEMORY_DMABUF</constant></entry>
1213 <entry>The buffer is used for <link linkend="dmabuf">DMA shared
1214 buffer</link> I/O.</entry>
1221 <title>Timecodes</title>
1223 <para>The <structname>v4l2_timecode</structname> structure is
1224 designed to hold a <xref linkend="smpte12m" /> or similar timecode.
1225 (struct <structname>timeval</structname> timestamps are stored in
1226 &v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
1228 <table frame="none" pgwide="1" id="v4l2-timecode">
1229 <title>struct <structname>v4l2_timecode</structname></title>
1232 <tbody valign="top">
1234 <entry>__u32</entry>
1235 <entry><structfield>type</structfield></entry>
1236 <entry>Frame rate the timecodes are based on, see <xref
1237 linkend="timecode-type" />.</entry>
1240 <entry>__u32</entry>
1241 <entry><structfield>flags</structfield></entry>
1242 <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
1246 <entry><structfield>frames</structfield></entry>
1247 <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
1248 type of timecode.</entry>
1252 <entry><structfield>seconds</structfield></entry>
1253 <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
1257 <entry><structfield>minutes</structfield></entry>
1258 <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
1262 <entry><structfield>hours</structfield></entry>
1263 <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
1267 <entry><structfield>userbits</structfield>[4]</entry>
1268 <entry>The "user group" bits from the timecode.</entry>
1274 <table frame="none" pgwide="1" id="timecode-type">
1275 <title>Timecode Types</title>
1278 <tbody valign="top">
1280 <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
1282 <entry>24 frames per second, i. e. film.</entry>
1285 <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
1287 <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
1290 <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
1292 <entry>30 frames per second, &ie; NTSC video.</entry>
1295 <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
1300 <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
1308 <table frame="none" pgwide="1" id="timecode-flags">
1309 <title>Timecode Flags</title>
1312 <tbody valign="top">
1314 <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
1315 <entry>0x0001</entry>
1316 <entry>Indicates "drop frame" semantics for counting frames
1317 in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
1318 each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
1322 <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
1323 <entry>0x0002</entry>
1324 <entry>The "color frame" flag.</entry>
1327 <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
1328 <entry>0x000C</entry>
1329 <entry>Field mask for the "binary group flags".</entry>
1332 <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
1333 <entry>0x0000</entry>
1334 <entry>Unspecified format.</entry>
1337 <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
1338 <entry>0x0008</entry>
1339 <entry>8-bit ISO characters.</entry>
1347 <section id="field-order">
1348 <title>Field Order</title>
1350 <para>We have to distinguish between progressive and interlaced
1351 video. Progressive video transmits all lines of a video image
1352 sequentially. Interlaced video divides an image into two fields,
1353 containing only the odd and even lines of the image, respectively.
1354 Alternating the so called odd and even field are transmitted, and due
1355 to a small delay between fields a cathode ray TV displays the lines
1356 interleaved, yielding the original frame. This curious technique was
1357 invented because at refresh rates similar to film the image would
1358 fade out too quickly. Transmitting fields reduces the flicker without
1359 the necessity of doubling the frame rate and with it the bandwidth
1360 required for each channel.</para>
1362 <para>It is important to understand a video camera does not expose
1363 one frame at a time, merely transmitting the frames separated into
1364 fields. The fields are in fact captured at two different instances in
1365 time. An object on screen may well move between one field and the
1366 next. For applications analysing motion it is of paramount importance
1367 to recognize which field of a frame is older, the <emphasis>temporal
1368 order</emphasis>.</para>
1370 <para>When the driver provides or accepts images field by field
1371 rather than interleaved, it is also important applications understand
1372 how the fields combine to frames. We distinguish between top (aka odd) and
1373 bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line
1374 of the top field is the first line of an interlaced frame, the first
1375 line of the bottom field is the second line of that frame.</para>
1377 <para>However because fields were captured one after the other,
1378 arguing whether a frame commences with the top or bottom field is
1379 pointless. Any two successive top and bottom, or bottom and top fields
1380 yield a valid frame. Only when the source was progressive to begin
1381 with, ⪚ when transferring film to video, two fields may come from
1382 the same frame, creating a natural order.</para>
1384 <para>Counter to intuition the top field is not necessarily the
1385 older field. Whether the older field contains the top or bottom lines
1386 is a convention determined by the video standard. Hence the
1387 distinction between temporal and spatial order of fields. The diagrams
1388 below should make this clearer.</para>
1390 <para>All video capture and output devices must report the current
1391 field order. Some drivers may permit the selection of a different
1392 order, to this end applications initialize the
1393 <structfield>field</structfield> field of &v4l2-pix-format; before
1394 calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
1395 have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
1397 <table frame="none" pgwide="1" id="v4l2-field">
1398 <title>enum v4l2_field</title>
1401 <tbody valign="top">
1403 <entry><constant>V4L2_FIELD_ANY</constant></entry>
1405 <entry>Applications request this field order when any
1406 one of the <constant>V4L2_FIELD_NONE</constant>,
1407 <constant>V4L2_FIELD_TOP</constant>,
1408 <constant>V4L2_FIELD_BOTTOM</constant>, or
1409 <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
1410 Drivers choose depending on hardware capabilities or e. g. the
1411 requested image size, and return the actual field order. &v4l2-buffer;
1412 <structfield>field</structfield> can never be
1413 <constant>V4L2_FIELD_ANY</constant>.</entry>
1416 <entry><constant>V4L2_FIELD_NONE</constant></entry>
1418 <entry>Images are in progressive format, not interlaced.
1419 The driver may also indicate this order when it cannot distinguish
1420 between <constant>V4L2_FIELD_TOP</constant> and
1421 <constant>V4L2_FIELD_BOTTOM</constant>.</entry>
1424 <entry><constant>V4L2_FIELD_TOP</constant></entry>
1426 <entry>Images consist of the top (aka odd) field only.</entry>
1429 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
1431 <entry>Images consist of the bottom (aka even) field only.
1432 Applications may wish to prevent a device from capturing interlaced
1433 images because they will have "comb" or "feathering" artefacts around
1434 moving objects.</entry>
1437 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
1439 <entry>Images contain both fields, interleaved line by
1440 line. The temporal order of the fields (whether the top or bottom
1441 field is first transmitted) depends on the current video standard.
1442 M/NTSC transmits the bottom field first, all other standards the top
1443 field first.</entry>
1446 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
1448 <entry>Images contain both fields, the top field lines
1449 are stored first in memory, immediately followed by the bottom field
1450 lines. Fields are always stored in temporal order, the older one first
1451 in memory. Image sizes refer to the frame, not fields.</entry>
1454 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1456 <entry>Images contain both fields, the bottom field
1457 lines are stored first in memory, immediately followed by the top
1458 field lines. Fields are always stored in temporal order, the older one
1459 first in memory. Image sizes refer to the frame, not fields.</entry>
1462 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1464 <entry>The two fields of a frame are passed in separate
1465 buffers, in temporal order, &ie; the older one first. To indicate the field
1466 parity (whether the current field is a top or bottom field) the driver
1467 or application, depending on data direction, must set &v4l2-buffer;
1468 <structfield>field</structfield> to
1469 <constant>V4L2_FIELD_TOP</constant> or
1470 <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
1471 to build a frame. If fields are successive, without any dropped fields
1472 between them (fields can drop individually), can be determined from
1473 the &v4l2-buffer; <structfield>sequence</structfield> field. This format
1474 cannot be selected when using the read/write I/O method since there
1475 is no way to communicate if a field was a top or bottom field.</entry>
1478 <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
1480 <entry>Images contain both fields, interleaved line by
1481 line, top field first. The top field is transmitted first.</entry>
1484 <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
1486 <entry>Images contain both fields, interleaved line by
1487 line, top field first. The bottom field is transmitted first.</entry>
1493 <figure id="fieldseq-tb">
1494 <title>Field Order, Top Field First Transmitted</title>
1497 <imagedata fileref="fieldseq_tb.pdf" format="PS" />
1500 <imagedata fileref="fieldseq_tb.gif" format="GIF" />
1505 <figure id="fieldseq-bt">
1506 <title>Field Order, Bottom Field First Transmitted</title>
1509 <imagedata fileref="fieldseq_bt.pdf" format="PS" />
1512 <imagedata fileref="fieldseq_bt.gif" format="GIF" />