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