| blob | 3f47df1aa54aba5d9c46ab57533a2ddfe9fe3461 |
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
15 yet.</para>
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
36 more detail.</para>
38 <section id="rw">
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
56 fictitious):</para>
58 <informalexample>
59 <screen>
60 > vidctrl /dev/video --input=0 --format=YUYV --size=352x288
61 > dd if=/dev/video of=myimage.422 bs=202752 count=1
62 </screen>
63 </informalexample>
65 <para>To read from the device applications use the
66 &func-read; function, to write the &func-write; function.
67 Drivers must implement one I/O method if they
68 exchange data with applications, but it need not be this.<footnote>
69 <para>It would be desirable if applications could depend on
70 drivers supporting all I/O interfaces, but as much as the complex
71 memory mapping I/O can be inadequate for some devices we have no
72 reason to require this interface, which is most useful for simple
73 applications capturing still images.</para>
74 </footnote> When reading or writing is supported, the driver
75 must also support the &func-select; and &func-poll;
76 function.<footnote>
77 <para>At the driver level <function>select()</function> and
78 <function>poll()</function> are the same, and
79 <function>select()</function> is too important to be optional.</para>
80 </footnote></para>
81 </section>
83 <section id="mmap">
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>
112 </footnote></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
119 mapped.</para>
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>
138 <example>
139 <title>Mapping buffers in the single-planar API</title>
140 <programlisting>
141 &v4l2-requestbuffers; reqbuf;
142 struct {
143 void *start;
144 size_t length;
145 } *buffers;
146 unsigned int i;
148 memset(&reqbuf, 0, sizeof(reqbuf));
149 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
150 reqbuf.memory = V4L2_MEMORY_MMAP;
151 reqbuf.count = 20;
153 if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) {
154 if (errno == EINVAL)
155 printf("Video capturing or mmap-streaming is not supported\n");
156 else
157 perror("VIDIOC_REQBUFS");
159 exit(EXIT_FAILURE);
160 }
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");
167 exit(EXIT_FAILURE);
168 }
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;
179 buffer.index = i;
181 if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &buffer)) {
182 perror("VIDIOC_QUERYBUF");
183 exit(EXIT_FAILURE);
184 }
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. */
196 perror("mmap");
197 exit(EXIT_FAILURE);
198 }
199 }
201 /* Cleanup. */
203 for (i = 0; i < reqbuf.count; i++)
204 munmap(buffers[i].start, buffers[i].length);
205 </programlisting>
206 </example>
208 <example>
209 <title>Mapping buffers in the multi-planar API</title>
210 <programlisting>
211 &v4l2-requestbuffers; reqbuf;
212 /* Our current format uses 3 planes per buffer */
213 #define FMT_NUM_PLANES = 3
215 struct {
216 void *start[FMT_NUM_PLANES];
217 size_t length[FMT_NUM_PLANES];
218 } *buffers;
219 unsigned int i, j;
221 memset(&reqbuf, 0, sizeof(reqbuf));
222 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
223 reqbuf.memory = V4L2_MEMORY_MMAP;
224 reqbuf.count = 20;
226 if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 0) {
227 if (errno == EINVAL)
228 printf("Video capturing or mmap-streaming is not supported\n");
229 else
230 perror("VIDIOC_REQBUFS");
232 exit(EXIT_FAILURE);
233 }
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");
240 exit(EXIT_FAILURE);
241 }
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;
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;
259 if (ioctl(fd, &VIDIOC-QUERYBUF;, &buffer) < 0) {
260 perror("VIDIOC_QUERYBUF");
261 exit(EXIT_FAILURE);
262 }
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. */
276 perror("mmap");
277 exit(EXIT_FAILURE);
278 }
279 }
280 }
282 /* Cleanup. */
284 for (i = 0; i < reqbuf.count; i++)
285 for (j = 0; j < FMT_NUM_PLANES; j++)
286 munmap(buffers[i].start[j], buffers[i].length[j]);
287 </programlisting>
288 </example>
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; function 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 buffers, or set the
343 field before enqueuing buffers for output.</para>
345 <para>Drivers implementing memory mapping I/O must
346 support the <constant>VIDIOC_REQBUFS</constant>,
347 <constant>VIDIOC_QUERYBUF</constant>,
348 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
349 <constant>VIDIOC_STREAMON</constant> and
350 <constant>VIDIOC_STREAMOFF</constant> ioctl, the
351 <function>mmap()</function>, <function>munmap()</function>,
352 <function>select()</function> and <function>poll()</function>
353 function.<footnote>
354 <para>At the driver level <function>select()</function> and
355 <function>poll()</function> are the same, and
356 <function>select()</function> is too important to be optional. The
357 rest should be evident.</para>
358 </footnote></para>
360 <para>[capture example]</para>
362 </section>
364 <section id="userp">
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>
384 <example>
385 <title>Initiating streaming I/O with user pointers</title>
387 <programlisting>
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) {
395 if (errno == EINVAL)
396 printf ("Video capturing or user pointer streaming is not supported\n");
397 else
398 perror ("VIDIOC_REQBUFS");
400 exit (EXIT_FAILURE);
401 }
402 </programlisting>
403 </example>
405 <para>Buffer (plane) addresses and sizes are passed on the fly with the
406 &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
407 applications can pass different addresses and sizes at each
408 <constant>VIDIOC_QBUF</constant> call. If required by the hardware the
409 driver swaps memory pages within physical memory to create a
410 continuous area of memory. This happens transparently to the
411 application in the virtual memory subsystem of the kernel. When buffer
412 pages have been swapped out to disk they are brought back and finally
413 locked in physical memory for DMA.<footnote>
414 <para>We expect that frequently used buffers are typically not
415 swapped out. Anyway, the process of swapping, locking or generating
416 scatter-gather lists may be time consuming. The delay can be masked by
417 the depth of the incoming buffer queue, and perhaps by maintaining
418 caches assuming a buffer will be soon enqueued again. On the other
419 hand, to optimize memory usage drivers can limit the number of buffers
420 locked in advance and recycle the most recently used buffers first. Of
421 course, the pages of empty buffers in the incoming queue need not be
422 saved to disk. Output buffers must be saved on the incoming and
423 outgoing queue because an application may share them with other
424 processes.</para>
425 </footnote></para>
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 buffers, or set the field before enqueuing buffers for output.</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>
472 </footnote></para>
473 </section>
475 <section id="async">
476 <title>Asynchronous I/O</title>
478 <para>This method is not defined yet.</para>
479 </section>
481 <section id="buffer">
482 <title>Buffers</title>
484 <para>A buffer contains data exchanged by application and
485 driver using one of the Streaming I/O methods. In the multi-planar API, the
486 data is held in planes, while the buffer structure acts as a container
487 for the planes. Only pointers to buffers (planes) are exchanged, the data
488 itself is not copied. These pointers, together with meta-information like
489 timestamps or field parity, are stored in a struct
490 <structname>v4l2_buffer</structname>, argument to
491 the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.
492 In the multi-planar API, some plane-specific members of struct
493 <structname>v4l2_buffer</structname>, such as pointers and sizes for each
494 plane, are stored in struct <structname>v4l2_plane</structname> instead.
495 In that case, struct <structname>v4l2_buffer</structname> contains an array of
496 plane structures.</para>
498 <para>Nominally timestamps refer to the first data byte transmitted.
499 In practice however the wide range of hardware covered by the V4L2 API
500 limits timestamp accuracy. Often an interrupt routine will
501 sample the system clock shortly after the field or frame was stored
502 completely in memory. So applications must expect a constant
503 difference up to one field or frame period plus a small (few scan
504 lines) random error. The delay and error can be much
505 larger due to compression or transmission over an external bus when
506 the frames are not properly stamped by the sender. This is frequently
507 the case with USB cameras. Here timestamps refer to the instant the
508 field or frame was received by the driver, not the capture time. These
509 devices identify by not enumerating any video standards, see <xref
510 linkend="standard" />.</para>
512 <para>Similar limitations apply to output timestamps. Typically
513 the video hardware locks to a clock controlling the video timing, the
514 horizontal and vertical synchronization pulses. At some point in the
515 line sequence, possibly the vertical blanking, an interrupt routine
516 samples the system clock, compares against the timestamp and programs
517 the hardware to repeat the previous field or frame, or to display the
518 buffer contents.</para>
520 <para>Apart of limitations of the video device and natural
521 inaccuracies of all clocks, it should be noted system time itself is
522 not perfectly stable. It can be affected by power saving cycles,
523 warped to insert leap seconds, or even turned back or forth by the
524 system administrator affecting long term measurements. <footnote>
525 <para>Since no other Linux multimedia
526 API supports unadjusted time it would be foolish to introduce here. We
527 must use a universally supported clock to synchronize different media,
528 hence time of day.</para>
529 </footnote></para>
531 <table frame="none" pgwide="1" id="v4l2-buffer">
532 <title>struct <structname>v4l2_buffer</structname></title>
533 <tgroup cols="4">
534 &cs-ustr;
535 <tbody valign="top">
536 <row>
537 <entry>__u32</entry>
538 <entry><structfield>index</structfield></entry>
539 <entry></entry>
540 <entry>Number of the buffer, set by the application. This
541 field is only used for <link linkend="mmap">memory mapping</link> I/O
542 and can range from zero to the number of buffers allocated
543 with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry>
544 </row>
545 <row>
546 <entry>&v4l2-buf-type;</entry>
547 <entry><structfield>type</structfield></entry>
548 <entry></entry>
549 <entry>Type of the buffer, same as &v4l2-format;
550 <structfield>type</structfield> or &v4l2-requestbuffers;
551 <structfield>type</structfield>, set by the application.</entry>
552 </row>
553 <row>
554 <entry>__u32</entry>
555 <entry><structfield>bytesused</structfield></entry>
556 <entry></entry>
557 <entry>The number of bytes occupied by the data in the
558 buffer. It depends on the negotiated data format and may change with
559 each buffer for compressed variable size data like JPEG images.
560 Drivers must set this field when <structfield>type</structfield>
561 refers to an input stream, applications when an output stream.</entry>
562 </row>
563 <row>
564 <entry>__u32</entry>
565 <entry><structfield>flags</structfield></entry>
566 <entry></entry>
567 <entry>Flags set by the application or driver, see <xref
568 linkend="buffer-flags" />.</entry>
569 </row>
570 <row>
571 <entry>&v4l2-field;</entry>
572 <entry><structfield>field</structfield></entry>
573 <entry></entry>
574 <entry>Indicates the field order of the image in the
575 buffer, see <xref linkend="v4l2-field" />. This field is not used when
576 the buffer contains VBI data. Drivers must set it when
577 <structfield>type</structfield> refers to an input stream,
578 applications when an output stream.</entry>
579 </row>
580 <row>
581 <entry>struct timeval</entry>
582 <entry><structfield>timestamp</structfield></entry>
583 <entry></entry>
584 <entry><para>For input streams this is the
585 system time (as returned by the <function>gettimeofday()</function>
586 function) when the first data byte was captured. For output streams
587 the data will not be displayed before this time, secondary to the
588 nominal frame rate determined by the current video standard in
589 enqueued order. Applications can for example zero this field to
590 display frames as soon as possible. The driver stores the time at
591 which the first data byte was actually sent out in the
592 <structfield>timestamp</structfield> field. This permits
593 applications to monitor the drift between the video and system
594 clock.</para></entry>
595 </row>
596 <row>
597 <entry>&v4l2-timecode;</entry>
598 <entry><structfield>timecode</structfield></entry>
599 <entry></entry>
600 <entry>When <structfield>type</structfield> is
601 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the
602 <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in
603 <structfield>flags</structfield>, this structure contains a frame
604 timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
605 mode the top and bottom field contain the same timecode.
606 Timecodes are intended to help video editing and are typically recorded on
607 video tapes, but also embedded in compressed formats like MPEG. This
608 field is independent of the <structfield>timestamp</structfield> and
609 <structfield>sequence</structfield> fields.</entry>
610 </row>
611 <row>
612 <entry>__u32</entry>
613 <entry><structfield>sequence</structfield></entry>
614 <entry></entry>
615 <entry>Set by the driver, counting the frames in the
616 sequence.</entry>
617 </row>
618 <row>
619 <entry spanname="hspan"><para>In <link
620 linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and
621 bottom field have the same sequence number. The count starts at zero
622 and includes dropped or repeated frames. A dropped frame was received
623 by an input device but could not be stored due to lack of free buffer
624 space. A repeated frame was displayed again by an output device
625 because the application did not pass new data in
626 time.</para><para>Note this may count the frames received
627 e.g. over USB, without taking into account the frames dropped by the
628 remote hardware due to limited compression throughput or bus
629 bandwidth. These devices identify by not enumerating any video
630 standards, see <xref linkend="standard" />.</para></entry>
631 </row>
632 <row>
633 <entry>&v4l2-memory;</entry>
634 <entry><structfield>memory</structfield></entry>
635 <entry></entry>
636 <entry>This field must be set by applications and/or drivers
637 in accordance with the selected I/O method.</entry>
638 </row>
639 <row>
640 <entry>union</entry>
641 <entry><structfield>m</structfield></entry>
642 </row>
643 <row>
644 <entry></entry>
645 <entry>__u32</entry>
646 <entry><structfield>offset</structfield></entry>
647 <entry>For the single-planar API and when
648 <structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this
649 is the offset of the buffer from the start of the device memory. The value is
650 returned by the driver and apart of serving as parameter to the &func-mmap;
651 function not useful for applications. See <xref linkend="mmap" /> for details
652 </entry>
653 </row>
654 <row>
655 <entry></entry>
656 <entry>unsigned long</entry>
657 <entry><structfield>userptr</structfield></entry>
658 <entry>For the single-planar API and when
659 <structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant>
660 this is a pointer to the buffer (casted to unsigned long type) in virtual
661 memory, set by the application. See <xref linkend="userp" /> for details.
662 </entry>
663 </row>
664 <row>
665 <entry></entry>
666 <entry>struct v4l2_plane</entry>
667 <entry><structfield>*planes</structfield></entry>
668 <entry>When using the multi-planar API, contains a userspace pointer
669 to an array of &v4l2-plane;. The size of the array should be put
670 in the <structfield>length</structfield> field of this
671 <structname>v4l2_buffer</structname> structure.</entry>
672 </row>
673 <row>
674 <entry>__u32</entry>
675 <entry><structfield>length</structfield></entry>
676 <entry></entry>
677 <entry>Size of the buffer (not the payload) in bytes for the
678 single-planar API. For the multi-planar API should contain the
679 number of elements in the <structfield>planes</structfield> array.
680 </entry>
681 </row>
682 <row>
683 <entry>__u32</entry>
684 <entry><structfield>input</structfield></entry>
685 <entry></entry>
686 <entry>Some video capture drivers support rapid and
687 synchronous video input changes, a function useful for example in
688 video surveillance applications. For this purpose applications set the
689 <constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the
690 number of a video input as in &v4l2-input; field
691 <structfield>index</structfield>.</entry>
692 </row>
693 <row>
694 <entry>__u32</entry>
695 <entry><structfield>reserved</structfield></entry>
696 <entry></entry>
697 <entry>A place holder for future extensions and custom
698 (driver defined) buffer types
699 <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications
700 should set this to 0.</entry>
701 </row>
702 </tbody>
703 </tgroup>
704 </table>
706 <table frame="none" pgwide="1" id="v4l2-plane">
707 <title>struct <structname>v4l2_plane</structname></title>
708 <tgroup cols="4">
709 &cs-ustr;
710 <tbody valign="top">
711 <row>
712 <entry>__u32</entry>
713 <entry><structfield>bytesused</structfield></entry>
714 <entry></entry>
715 <entry>The number of bytes occupied by data in the plane
716 (its payload).</entry>
717 </row>
718 <row>
719 <entry>__u32</entry>
720 <entry><structfield>length</structfield></entry>
721 <entry></entry>
722 <entry>Size in bytes of the plane (not its payload).</entry>
723 </row>
724 <row>
725 <entry>union</entry>
726 <entry><structfield>m</structfield></entry>
727 <entry></entry>
728 <entry></entry>
729 </row>
730 <row>
731 <entry></entry>
732 <entry>__u32</entry>
733 <entry><structfield>mem_offset</structfield></entry>
734 <entry>When the memory type in the containing &v4l2-buffer; is
735 <constant>V4L2_MEMORY_MMAP</constant>, this is the value that
736 should be passed to &func-mmap;, similar to the
737 <structfield>offset</structfield> field in &v4l2-buffer;.</entry>
738 </row>
739 <row>
740 <entry></entry>
741 <entry>__unsigned long</entry>
742 <entry><structfield>userptr</structfield></entry>
743 <entry>When the memory type in the containing &v4l2-buffer; is
744 <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace
745 pointer to the memory allocated for this plane by an application.
746 </entry>
747 </row>
748 <row>
749 <entry>__u32</entry>
750 <entry><structfield>data_offset</structfield></entry>
751 <entry></entry>
752 <entry>Offset in bytes to video data in the plane, if applicable.
753 </entry>
754 </row>
755 <row>
756 <entry>__u32</entry>
757 <entry><structfield>reserved[11]</structfield></entry>
758 <entry></entry>
759 <entry>Reserved for future use. Should be zeroed by an
760 application.</entry>
761 </row>
762 </tbody>
763 </tgroup>
764 </table>
766 <table frame="none" pgwide="1" id="v4l2-buf-type">
767 <title>enum v4l2_buf_type</title>
768 <tgroup cols="3">
769 &cs-def;
770 <tbody valign="top">
771 <row>
772 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
773 <entry>1</entry>
774 <entry>Buffer of a single-planar video capture stream, see <xref
775 linkend="capture" />.</entry>
776 </row>
777 <row>
778 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
779 </entry>
780 <entry>9</entry>
781 <entry>Buffer of a multi-planar video capture stream, see <xref
782 linkend="capture" />.</entry>
783 </row>
784 <row>
785 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
786 <entry>2</entry>
787 <entry>Buffer of a single-planar video output stream, see <xref
788 linkend="output" />.</entry>
789 </row>
790 <row>
791 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>
792 </entry>
793 <entry>10</entry>
794 <entry>Buffer of a multi-planar video output stream, see <xref
795 linkend="output" />.</entry>
796 </row>
797 <row>
798 <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
799 <entry>3</entry>
800 <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry>
801 </row>
802 <row>
803 <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
804 <entry>4</entry>
805 <entry>Buffer of a raw VBI capture stream, see <xref
806 linkend="raw-vbi" />.</entry>
807 </row>
808 <row>
809 <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
810 <entry>5</entry>
811 <entry>Buffer of a raw VBI output stream, see <xref
812 linkend="raw-vbi" />.</entry>
813 </row>
814 <row>
815 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
816 <entry>6</entry>
817 <entry>Buffer of a sliced VBI capture stream, see <xref
818 linkend="sliced" />.</entry>
819 </row>
820 <row>
821 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
822 <entry>7</entry>
823 <entry>Buffer of a sliced VBI output stream, see <xref
824 linkend="sliced" />.</entry>
825 </row>
826 <row>
827 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry>
828 <entry>8</entry>
829 <entry>Buffer for video output overlay (OSD), see <xref
830 linkend="osd" />. Status: <link
831 linkend="experimental">Experimental</link>.</entry>
832 </row>
833 <row>
834 <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry>
835 <entry>0x80</entry>
836 <entry>This and higher values are reserved for custom
837 (driver defined) buffer types.</entry>
838 </row>
839 </tbody>
840 </tgroup>
841 </table>
843 <table frame="none" pgwide="1" id="buffer-flags">
844 <title>Buffer Flags</title>
845 <tgroup cols="3">
846 &cs-def;
847 <tbody valign="top">
848 <row>
849 <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
850 <entry>0x0001</entry>
851 <entry>The buffer resides in device memory and has been mapped
852 into the application's address space, see <xref linkend="mmap" /> for details.
853 Drivers set or clear this flag when the
854 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
855 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
856 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
857 </row>
858 <row>
859 <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
860 <entry>0x0002</entry>
861 <entry>Internally drivers maintain two buffer queues, an
862 incoming and outgoing queue. When this flag is set, the buffer is
863 currently on the incoming queue. It automatically moves to the
864 outgoing queue after the buffer has been filled (capture devices) or
865 displayed (output devices). Drivers set or clear this flag when the
866 <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
867 (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
868 always set and after <constant>VIDIOC_DQBUF</constant> always
869 cleared.</entry>
870 </row>
871 <row>
872 <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
873 <entry>0x0004</entry>
874 <entry>When this flag is set, the buffer is currently on
875 the outgoing queue, ready to be dequeued from the driver. Drivers set
876 or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
877 is called. After calling the <constant>VIDIOC_QBUF</constant> or
878 <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
879 buffer cannot be on both queues at the same time, the
880 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
881 <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
882 They can be both cleared however, then the buffer is in "dequeued"
883 state, in the application domain to say so.</entry>
884 </row>
885 <row>
886 <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
887 <entry>0x0040</entry>
888 <entry>When this flag is set, the buffer has been dequeued
889 successfully, although the data might have been corrupted.
890 This is recoverable, streaming may continue as normal and
891 the buffer may be reused normally.
892 Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
893 ioctl is called.</entry>
894 </row>
895 <row>
896 <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
897 <entry>0x0008</entry>
898 <entry>Drivers set or clear this flag when calling the
899 <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
900 capture devices when the buffer contains a compressed image which is a
901 key frame (or field), &ie; can be decompressed on its own.</entry>
902 </row>
903 <row>
904 <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
905 <entry>0x0010</entry>
906 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
907 this flags predicted frames or fields which contain only differences to a
908 previous key frame.</entry>
909 </row>
910 <row>
911 <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
912 <entry>0x0020</entry>
913 <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant>
914 this is a bidirectional predicted frame or field. [ooc tbd]</entry>
915 </row>
916 <row>
917 <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
918 <entry>0x0100</entry>
919 <entry>The <structfield>timecode</structfield> field is valid.
920 Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
921 ioctl is called.</entry>
922 </row>
923 <row>
924 <entry><constant>V4L2_BUF_FLAG_INPUT</constant></entry>
925 <entry>0x0200</entry>
926 <entry>The <structfield>input</structfield> field is valid.
927 Applications set or clear this flag before calling the
928 <constant>VIDIOC_QBUF</constant> ioctl.</entry>
929 </row>
930 <row>
931 <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>
932 <entry>0x0400</entry>
933 <entry>The buffer has been prepared for I/O and can be queued by the
934 application. Drivers set or clear this flag when the
935 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
936 linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link
937 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
938 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry>
939 </row>
940 <row>
941 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry>
942 <entry>0x0400</entry>
943 <entry>Caches do not have to be invalidated for this buffer.
944 Typically applications shall use this flag if the data captured in the buffer
945 is not going to be touched by the CPU, instead the buffer will, probably, be
946 passed on to a DMA-capable hardware unit for further processing or output.
947 </entry>
948 </row>
949 <row>
950 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry>
951 <entry>0x0800</entry>
952 <entry>Caches do not have to be cleaned for this buffer.
953 Typically applications shall use this flag for output buffers if the data
954 in this buffer has not been created by the CPU but by some DMA-capable unit,
955 in which case caches have not been used.</entry>
956 </row>
957 </tbody>
958 </tgroup>
959 </table>
961 <table pgwide="1" frame="none" id="v4l2-memory">
962 <title>enum v4l2_memory</title>
963 <tgroup cols="3">
964 &cs-def;
965 <tbody valign="top">
966 <row>
967 <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
968 <entry>1</entry>
969 <entry>The buffer is used for <link linkend="mmap">memory
970 mapping</link> I/O.</entry>
971 </row>
972 <row>
973 <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
974 <entry>2</entry>
975 <entry>The buffer is used for <link linkend="userp">user
976 pointer</link> I/O.</entry>
977 </row>
978 <row>
979 <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
980 <entry>3</entry>
981 <entry>[to do]</entry>
982 </row>
983 </tbody>
984 </tgroup>
985 </table>
987 <section>
988 <title>Timecodes</title>
990 <para>The <structname>v4l2_timecode</structname> structure is
991 designed to hold a <xref linkend="smpte12m" /> or similar timecode.
992 (struct <structname>timeval</structname> timestamps are stored in
993 &v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
995 <table frame="none" pgwide="1" id="v4l2-timecode">
996 <title>struct <structname>v4l2_timecode</structname></title>
997 <tgroup cols="3">
998 &cs-str;
999 <tbody valign="top">
1000 <row>
1001 <entry>__u32</entry>
1002 <entry><structfield>type</structfield></entry>
1003 <entry>Frame rate the timecodes are based on, see <xref
1004 linkend="timecode-type" />.</entry>
1005 </row>
1006 <row>
1007 <entry>__u32</entry>
1008 <entry><structfield>flags</structfield></entry>
1009 <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
1010 </row>
1011 <row>
1012 <entry>__u8</entry>
1013 <entry><structfield>frames</structfield></entry>
1014 <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
1015 type of timecode.</entry>
1016 </row>
1017 <row>
1018 <entry>__u8</entry>
1019 <entry><structfield>seconds</structfield></entry>
1020 <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
1021 </row>
1022 <row>
1023 <entry>__u8</entry>
1024 <entry><structfield>minutes</structfield></entry>
1025 <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
1026 </row>
1027 <row>
1028 <entry>__u8</entry>
1029 <entry><structfield>hours</structfield></entry>
1030 <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
1031 </row>
1032 <row>
1033 <entry>__u8</entry>
1034 <entry><structfield>userbits</structfield>[4]</entry>
1035 <entry>The "user group" bits from the timecode.</entry>
1036 </row>
1037 </tbody>
1038 </tgroup>
1039 </table>
1041 <table frame="none" pgwide="1" id="timecode-type">
1042 <title>Timecode Types</title>
1043 <tgroup cols="3">
1044 &cs-def;
1045 <tbody valign="top">
1046 <row>
1047 <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
1048 <entry>1</entry>
1049 <entry>24 frames per second, i. e. film.</entry>
1050 </row>
1051 <row>
1052 <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
1053 <entry>2</entry>
1054 <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
1055 </row>
1056 <row>
1057 <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
1058 <entry>3</entry>
1059 <entry>30 frames per second, &ie; NTSC video.</entry>
1060 </row>
1061 <row>
1062 <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
1063 <entry>4</entry>
1064 <entry></entry>
1065 </row>
1066 <row>
1067 <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
1068 <entry>5</entry>
1069 <entry></entry>
1070 </row>
1071 </tbody>
1072 </tgroup>
1073 </table>
1075 <table frame="none" pgwide="1" id="timecode-flags">
1076 <title>Timecode Flags</title>
1077 <tgroup cols="3">
1078 &cs-def;
1079 <tbody valign="top">
1080 <row>
1081 <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
1082 <entry>0x0001</entry>
1083 <entry>Indicates "drop frame" semantics for counting frames
1084 in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
1085 each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
1086 count.</entry>
1087 </row>
1088 <row>
1089 <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
1090 <entry>0x0002</entry>
1091 <entry>The "color frame" flag.</entry>
1092 </row>
1093 <row>
1094 <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
1095 <entry>0x000C</entry>
1096 <entry>Field mask for the "binary group flags".</entry>
1097 </row>
1098 <row>
1099 <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
1100 <entry>0x0000</entry>
1101 <entry>Unspecified format.</entry>
1102 </row>
1103 <row>
1104 <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
1105 <entry>0x0008</entry>
1106 <entry>8-bit ISO characters.</entry>
1107 </row>
1108 </tbody>
1109 </tgroup>
1110 </table>
1111 </section>
1112 </section>
1114 <section id="field-order">
1115 <title>Field Order</title>
1117 <para>We have to distinguish between progressive and interlaced
1118 video. Progressive video transmits all lines of a video image
1119 sequentially. Interlaced video divides an image into two fields,
1120 containing only the odd and even lines of the image, respectively.
1121 Alternating the so called odd and even field are transmitted, and due
1122 to a small delay between fields a cathode ray TV displays the lines
1123 interleaved, yielding the original frame. This curious technique was
1124 invented because at refresh rates similar to film the image would
1125 fade out too quickly. Transmitting fields reduces the flicker without
1126 the necessity of doubling the frame rate and with it the bandwidth
1127 required for each channel.</para>
1129 <para>It is important to understand a video camera does not expose
1130 one frame at a time, merely transmitting the frames separated into
1131 fields. The fields are in fact captured at two different instances in
1132 time. An object on screen may well move between one field and the
1133 next. For applications analysing motion it is of paramount importance
1134 to recognize which field of a frame is older, the <emphasis>temporal
1135 order</emphasis>.</para>
1137 <para>When the driver provides or accepts images field by field
1138 rather than interleaved, it is also important applications understand
1139 how the fields combine to frames. We distinguish between top (aka odd) and
1140 bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line
1141 of the top field is the first line of an interlaced frame, the first
1142 line of the bottom field is the second line of that frame.</para>
1144 <para>However because fields were captured one after the other,
1145 arguing whether a frame commences with the top or bottom field is
1146 pointless. Any two successive top and bottom, or bottom and top fields
1147 yield a valid frame. Only when the source was progressive to begin
1148 with, ⪚ when transferring film to video, two fields may come from
1149 the same frame, creating a natural order.</para>
1151 <para>Counter to intuition the top field is not necessarily the
1152 older field. Whether the older field contains the top or bottom lines
1153 is a convention determined by the video standard. Hence the
1154 distinction between temporal and spatial order of fields. The diagrams
1155 below should make this clearer.</para>
1157 <para>All video capture and output devices must report the current
1158 field order. Some drivers may permit the selection of a different
1159 order, to this end applications initialize the
1160 <structfield>field</structfield> field of &v4l2-pix-format; before
1161 calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
1162 have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
1164 <table frame="none" pgwide="1" id="v4l2-field">
1165 <title>enum v4l2_field</title>
1166 <tgroup cols="3">
1167 &cs-def;
1168 <tbody valign="top">
1169 <row>
1170 <entry><constant>V4L2_FIELD_ANY</constant></entry>
1171 <entry>0</entry>
1172 <entry>Applications request this field order when any
1173 one of the <constant>V4L2_FIELD_NONE</constant>,
1174 <constant>V4L2_FIELD_TOP</constant>,
1175 <constant>V4L2_FIELD_BOTTOM</constant>, or
1176 <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
1177 Drivers choose depending on hardware capabilities or e. g. the
1178 requested image size, and return the actual field order. &v4l2-buffer;
1179 <structfield>field</structfield> can never be
1180 <constant>V4L2_FIELD_ANY</constant>.</entry>
1181 </row>
1182 <row>
1183 <entry><constant>V4L2_FIELD_NONE</constant></entry>
1184 <entry>1</entry>
1185 <entry>Images are in progressive format, not interlaced.
1186 The driver may also indicate this order when it cannot distinguish
1187 between <constant>V4L2_FIELD_TOP</constant> and
1188 <constant>V4L2_FIELD_BOTTOM</constant>.</entry>
1189 </row>
1190 <row>
1191 <entry><constant>V4L2_FIELD_TOP</constant></entry>
1192 <entry>2</entry>
1193 <entry>Images consist of the top (aka odd) field only.</entry>
1194 </row>
1195 <row>
1196 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
1197 <entry>3</entry>
1198 <entry>Images consist of the bottom (aka even) field only.
1199 Applications may wish to prevent a device from capturing interlaced
1200 images because they will have "comb" or "feathering" artefacts around
1201 moving objects.</entry>
1202 </row>
1203 <row>
1204 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
1205 <entry>4</entry>
1206 <entry>Images contain both fields, interleaved line by
1207 line. The temporal order of the fields (whether the top or bottom
1208 field is first transmitted) depends on the current video standard.
1209 M/NTSC transmits the bottom field first, all other standards the top
1210 field first.</entry>
1211 </row>
1212 <row>
1213 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
1214 <entry>5</entry>
1215 <entry>Images contain both fields, the top field lines
1216 are stored first in memory, immediately followed by the bottom field
1217 lines. Fields are always stored in temporal order, the older one first
1218 in memory. Image sizes refer to the frame, not fields.</entry>
1219 </row>
1220 <row>
1221 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1222 <entry>6</entry>
1223 <entry>Images contain both fields, the bottom field
1224 lines are stored first in memory, immediately followed by the top
1225 field lines. Fields are always stored in temporal order, the older one
1226 first in memory. Image sizes refer to the frame, not fields.</entry>
1227 </row>
1228 <row>
1229 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1230 <entry>7</entry>
1231 <entry>The two fields of a frame are passed in separate
1232 buffers, in temporal order, &ie; the older one first. To indicate the field
1233 parity (whether the current field is a top or bottom field) the driver
1234 or application, depending on data direction, must set &v4l2-buffer;
1235 <structfield>field</structfield> to
1236 <constant>V4L2_FIELD_TOP</constant> or
1237 <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
1238 to build a frame. If fields are successive, without any dropped fields
1239 between them (fields can drop individually), can be determined from
1240 the &v4l2-buffer; <structfield>sequence</structfield> field. Image
1241 sizes refer to the frame, not fields. This format cannot be selected
1242 when using the read/write I/O method.<!-- Where it's indistinguishable
1243 from V4L2_FIELD_SEQ_*. --></entry>
1244 </row>
1245 <row>
1246 <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
1247 <entry>8</entry>
1248 <entry>Images contain both fields, interleaved line by
1249 line, top field first. The top field is transmitted first.</entry>
1250 </row>
1251 <row>
1252 <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
1253 <entry>9</entry>
1254 <entry>Images contain both fields, interleaved line by
1255 line, top field first. The bottom field is transmitted first.</entry>
1256 </row>
1257 </tbody>
1258 </tgroup>
1259 </table>
1261 <figure id="fieldseq-tb">
1262 <title>Field Order, Top Field First Transmitted</title>
1263 <mediaobject>
1264 <imageobject>
1265 <imagedata fileref="fieldseq_tb.pdf" format="PS" />
1266 </imageobject>
1267 <imageobject>
1268 <imagedata fileref="fieldseq_tb.gif" format="GIF" />
1269 </imageobject>
1270 </mediaobject>
1271 </figure>
1273 <figure id="fieldseq-bt">
1274 <title>Field Order, Bottom Field First Transmitted</title>
1275 <mediaobject>
1276 <imageobject>
1277 <imagedata fileref="fieldseq_bt.pdf" format="PS" />
1278 </imageobject>
1279 <imageobject>
1280 <imagedata fileref="fieldseq_bt.gif" format="GIF" />
1281 </imageobject>
1282 </mediaobject>
1283 </figure>
1284 </section>
1286 <!--
1287 Local Variables:
1288 mode: sgml
1289 sgml-parent-document: "v4l2.sgml"
1290 indent-tabs-mode: nil
1291 End:
1292 -->