Commit | Line | Data |
---|---|---|
8e080c2e MCC |
1 | <title>Input/Output</title> |
2 | ||
3 | <para>The V4L2 API defines several different methods to read from or | |
4 | write to a device. All drivers exchanging data with applications must | |
5 | support at least one of them.</para> | |
6 | ||
7 | <para>The classic I/O method using the <function>read()</function> | |
8 | and <function>write()</function> function is automatically selected | |
9 | after opening a V4L2 device. When the driver does not support this | |
10 | method attempts to read or write will fail at any time.</para> | |
11 | ||
12 | <para>Other methods must be negotiated. To select the streaming I/O | |
13 | method with memory mapped or user buffers applications call the | |
14 | &VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined | |
15 | yet.</para> | |
16 | ||
17 | <para>Video overlay can be considered another I/O method, although | |
18 | the application does not directly receive the image data. It is | |
19 | selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl. | |
20 | For more information see <xref linkend="overlay" />.</para> | |
21 | ||
22 | <para>Generally exactly one I/O method, including overlay, is | |
23 | associated with each file descriptor. The only exceptions are | |
24 | applications not exchanging data with a driver ("panel applications", | |
25 | see <xref linkend="open" />) and drivers permitting simultaneous video capturing | |
26 | and overlay using the same file descriptor, for compatibility with V4L | |
27 | and earlier versions of V4L2.</para> | |
28 | ||
29 | <para><constant>VIDIOC_S_FMT</constant> and | |
30 | <constant>VIDIOC_REQBUFS</constant> would permit this to some degree, | |
31 | but for simplicity drivers need not support switching the I/O method | |
32 | (after first switching away from read/write) other than by closing | |
33 | and reopening the device.</para> | |
34 | ||
35 | <para>The following sections describe the various I/O methods in | |
36 | more detail.</para> | |
37 | ||
38 | <section id="rw"> | |
39 | <title>Read/Write</title> | |
40 | ||
41 | <para>Input and output devices support the | |
42 | <function>read()</function> and <function>write()</function> function, | |
43 | respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in | |
44 | the <structfield>capabilities</structfield> field of &v4l2-capability; | |
45 | returned by the &VIDIOC-QUERYCAP; ioctl is set.</para> | |
46 | ||
47 | <para>Drivers may need the CPU to copy the data, but they may also | |
48 | support DMA to or from user memory, so this I/O method is not | |
49 | necessarily less efficient than other methods merely exchanging buffer | |
50 | pointers. It is considered inferior though because no meta-information | |
51 | like frame counters or timestamps are passed. This information is | |
52 | necessary to recognize frame dropping and to synchronize with other | |
53 | data streams. However this is also the simplest I/O method, requiring | |
54 | little or no setup to exchange data. It permits command line stunts | |
55 | like this (the <application>vidctrl</application> tool is | |
56 | fictitious):</para> | |
57 | ||
58 | <informalexample> | |
59 | <screen> | |
60 | > vidctrl /dev/video --input=0 --format=YUYV --size=352x288 | |
61 | > dd if=/dev/video of=myimage.422 bs=202752 count=1 | |
62 | </screen> | |
63 | </informalexample> | |
64 | ||
65 | <para>To read from the device applications use the | |
66 | &func-read; function, to write the &func-write; function. | |
67 | Drivers must implement one I/O method if they | |
68 | exchange data with applications, but it need not be this.<footnote> | |
69 | <para>It would be desirable if applications could depend on | |
70 | drivers supporting all I/O interfaces, but as much as the complex | |
71 | memory mapping I/O can be inadequate for some devices we have no | |
72 | reason to require this interface, which is most useful for simple | |
73 | applications capturing still images.</para> | |
74 | </footnote> When reading or writing is supported, the driver | |
75 | must also support the &func-select; and &func-poll; | |
76 | function.<footnote> | |
77 | <para>At the driver level <function>select()</function> and | |
78 | <function>poll()</function> are the same, and | |
79 | <function>select()</function> is too important to be optional.</para> | |
80 | </footnote></para> | |
81 | </section> | |
82 | ||
83 | <section id="mmap"> | |
84 | <title>Streaming I/O (Memory Mapping)</title> | |
85 | ||
86 | <para>Input and output devices support this I/O method when the | |
87 | <constant>V4L2_CAP_STREAMING</constant> flag in the | |
88 | <structfield>capabilities</structfield> field of &v4l2-capability; | |
89 | returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two | |
90 | streaming methods, to determine if the memory mapping flavor is | |
91 | supported applications must call the &VIDIOC-REQBUFS; ioctl.</para> | |
92 | ||
93 | <para>Streaming is an I/O method where only pointers to buffers | |
94 | are exchanged between application and driver, the data itself is not | |
95 | copied. Memory mapping is primarily intended to map buffers in device | |
96 | memory into the application's address space. Device memory can be for | |
97 | example the video memory on a graphics card with a video capture | |
98 | add-on. However, being the most efficient I/O method available for a | |
99 | long time, many other drivers support streaming as well, allocating | |
100 | buffers in DMA-able main memory.</para> | |
101 | ||
102 | <para>A driver can support many sets of buffers. Each set is | |
103 | identified by a unique buffer type value. The sets are independent and | |
104 | each set can hold a different type of data. To access different sets | |
105 | at the same time different file descriptors must be used.<footnote> | |
106 | <para>One could use one file descriptor and set the buffer | |
107 | type field accordingly when calling &VIDIOC-QBUF; etc., but it makes | |
108 | the <function>select()</function> function ambiguous. We also like the | |
109 | clean approach of one file descriptor per logical stream. Video | |
110 | overlay for example is also a logical stream, although the CPU is not | |
111 | needed for continuous operation.</para> | |
112 | </footnote></para> | |
113 | ||
114 | <para>To allocate device buffers applications call the | |
115 | &VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer | |
116 | type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. | |
117 | This ioctl can also be used to change the number of buffers or to free | |
118 | the allocated memory, provided none of the buffers are still | |
119 | mapped.</para> | |
120 | ||
121 | <para>Before applications can access the buffers they must map | |
122 | them into their address space with the &func-mmap; function. The | |
123 | location of the buffers in device memory can be determined with the | |
53b5d574 PO |
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> | |
8e080c2e MCC |
137 | |
138 | <example> | |
53b5d574 | 139 | <title>Mapping buffers in the single-planar API</title> |
8e080c2e MCC |
140 | <programlisting> |
141 | &v4l2-requestbuffers; reqbuf; | |
142 | struct { | |
143 | void *start; | |
144 | size_t length; | |
145 | } *buffers; | |
146 | unsigned int i; | |
147 | ||
c4c0a78d | 148 | memset(&reqbuf, 0, sizeof(reqbuf)); |
8e080c2e MCC |
149 | reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; |
150 | reqbuf.memory = V4L2_MEMORY_MMAP; | |
151 | reqbuf.count = 20; | |
152 | ||
153 | if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) { | |
154 | if (errno == EINVAL) | |
c4c0a78d | 155 | printf("Video capturing or mmap-streaming is not supported\n"); |
8e080c2e | 156 | else |
c4c0a78d | 157 | perror("VIDIOC_REQBUFS"); |
8e080c2e | 158 | |
c4c0a78d | 159 | exit(EXIT_FAILURE); |
8e080c2e MCC |
160 | } |
161 | ||
162 | /* We want at least five buffers. */ | |
163 | ||
164 | if (reqbuf.count < 5) { | |
165 | /* You may need to free the buffers here. */ | |
c4c0a78d PO |
166 | printf("Not enough buffer memory\n"); |
167 | exit(EXIT_FAILURE); | |
8e080c2e MCC |
168 | } |
169 | ||
c4c0a78d PO |
170 | buffers = calloc(reqbuf.count, sizeof(*buffers)); |
171 | assert(buffers != NULL); | |
8e080c2e MCC |
172 | |
173 | for (i = 0; i < reqbuf.count; i++) { | |
174 | &v4l2-buffer; buffer; | |
175 | ||
c4c0a78d | 176 | memset(&buffer, 0, sizeof(buffer)); |
8e080c2e MCC |
177 | buffer.type = reqbuf.type; |
178 | buffer.memory = V4L2_MEMORY_MMAP; | |
179 | buffer.index = i; | |
180 | ||
181 | if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &buffer)) { | |
c4c0a78d PO |
182 | perror("VIDIOC_QUERYBUF"); |
183 | exit(EXIT_FAILURE); | |
8e080c2e MCC |
184 | } |
185 | ||
186 | buffers[i].length = buffer.length; /* remember for munmap() */ | |
187 | ||
c4c0a78d PO |
188 | buffers[i].start = mmap(NULL, buffer.length, |
189 | PROT_READ | PROT_WRITE, /* recommended */ | |
190 | MAP_SHARED, /* recommended */ | |
191 | fd, buffer.m.offset); | |
8e080c2e MCC |
192 | |
193 | if (MAP_FAILED == buffers[i].start) { | |
194 | /* If you do not exit here you should unmap() and free() | |
195 | the buffers mapped so far. */ | |
c4c0a78d PO |
196 | perror("mmap"); |
197 | exit(EXIT_FAILURE); | |
8e080c2e MCC |
198 | } |
199 | } | |
200 | ||
201 | /* Cleanup. */ | |
202 | ||
203 | for (i = 0; i < reqbuf.count; i++) | |
c4c0a78d | 204 | munmap(buffers[i].start, buffers[i].length); |
8e080c2e MCC |
205 | </programlisting> |
206 | </example> | |
207 | ||
53b5d574 PO |
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 */ | |
497888cf | 213 | #define FMT_NUM_PLANES = 3 |
53b5d574 PO |
214 | |
215 | struct { | |
216 | void *start[FMT_NUM_PLANES]; | |
217 | size_t length[FMT_NUM_PLANES]; | |
218 | } *buffers; | |
219 | unsigned int i, j; | |
220 | ||
221 | memset(&reqbuf, 0, sizeof(reqbuf)); | |
222 | reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; | |
223 | reqbuf.memory = V4L2_MEMORY_MMAP; | |
224 | reqbuf.count = 20; | |
225 | ||
226 | if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 0) { | |
227 | if (errno == EINVAL) | |
228 | printf("Video capturing or mmap-streaming is not supported\n"); | |
229 | else | |
230 | perror("VIDIOC_REQBUFS"); | |
231 | ||
232 | exit(EXIT_FAILURE); | |
233 | } | |
234 | ||
235 | /* We want at least five buffers. */ | |
236 | ||
237 | if (reqbuf.count < 5) { | |
238 | /* You may need to free the buffers here. */ | |
239 | printf("Not enough buffer memory\n"); | |
240 | exit(EXIT_FAILURE); | |
241 | } | |
242 | ||
243 | buffers = calloc(reqbuf.count, sizeof(*buffers)); | |
244 | assert(buffers != NULL); | |
245 | ||
246 | for (i = 0; i < reqbuf.count; i++) { | |
247 | &v4l2-buffer; buffer; | |
248 | &v4l2-plane; planes[FMT_NUM_PLANES]; | |
249 | ||
250 | memset(&buffer, 0, sizeof(buffer)); | |
251 | buffer.type = reqbuf.type; | |
252 | buffer.memory = V4L2_MEMORY_MMAP; | |
253 | buffer.index = i; | |
254 | /* length in struct v4l2_buffer in multi-planar API stores the size | |
255 | * of planes array. */ | |
256 | buffer.length = FMT_NUM_PLANES; | |
257 | buffer.m.planes = planes; | |
258 | ||
259 | if (ioctl(fd, &VIDIOC-QUERYBUF;, &buffer) < 0) { | |
260 | perror("VIDIOC_QUERYBUF"); | |
261 | exit(EXIT_FAILURE); | |
262 | } | |
263 | ||
264 | /* Every plane has to be mapped separately */ | |
265 | for (j = 0; j < FMT_NUM_PLANES; j++) { | |
266 | buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */ | |
267 | ||
268 | buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length, | |
269 | PROT_READ | PROT_WRITE, /* recommended */ | |
270 | MAP_SHARED, /* recommended */ | |
271 | fd, buffer.m.planes[j].m.offset); | |
272 | ||
273 | if (MAP_FAILED == buffers[i].start[j]) { | |
274 | /* If you do not exit here you should unmap() and free() | |
275 | the buffers and planes mapped so far. */ | |
276 | perror("mmap"); | |
277 | exit(EXIT_FAILURE); | |
278 | } | |
279 | } | |
280 | } | |
281 | ||
282 | /* Cleanup. */ | |
283 | ||
284 | for (i = 0; i < reqbuf.count; i++) | |
285 | for (j = 0; j < FMT_NUM_PLANES; j++) | |
286 | munmap(buffers[i].start[j], buffers[i].length[j]); | |
287 | </programlisting> | |
288 | </example> | |
289 | ||
8e080c2e MCC |
290 | <para>Conceptually streaming drivers maintain two buffer queues, an incoming |
291 | and an outgoing queue. They separate the synchronous capture or output | |
292 | operation locked to a video clock from the application which is | |
293 | subject to random disk or network delays and preemption by | |
294 | other processes, thereby reducing the probability of data loss. | |
295 | The queues are organized as FIFOs, buffers will be | |
296 | output in the order enqueued in the incoming FIFO, and were | |
297 | captured in the order dequeued from the outgoing FIFO.</para> | |
298 | ||
299 | <para>The driver may require a minimum number of buffers enqueued | |
300 | at all times to function, apart of this no limit exists on the number | |
301 | of buffers applications can enqueue in advance, or dequeue and | |
302 | process. They can also enqueue in a different order than buffers have | |
303 | been dequeued, and the driver can <emphasis>fill</emphasis> enqueued | |
304 | <emphasis>empty</emphasis> buffers in any order. <footnote> | |
305 | <para>Random enqueue order permits applications processing | |
306 | images out of order (such as video codecs) to return buffers earlier, | |
307 | reducing the probability of data loss. Random fill order allows | |
308 | drivers to reuse buffers on a LIFO-basis, taking advantage of caches | |
309 | holding scatter-gather lists and the like.</para> | |
310 | </footnote> The index number of a buffer (&v4l2-buffer; | |
311 | <structfield>index</structfield>) plays no role here, it only | |
312 | identifies the buffer.</para> | |
313 | ||
314 | <para>Initially all mapped buffers are in dequeued state, | |
315 | inaccessible by the driver. For capturing applications it is customary | |
316 | to first enqueue all mapped buffers, then to start capturing and enter | |
317 | the read loop. Here the application waits until a filled buffer can be | |
318 | dequeued, and re-enqueues the buffer when the data is no longer | |
319 | needed. Output applications fill and enqueue buffers, when enough | |
320 | buffers are stacked up the output is started with | |
321 | <constant>VIDIOC_STREAMON</constant>. In the write loop, when | |
322 | the application runs out of free buffers, it must wait until an empty | |
323 | buffer can be dequeued and reused.</para> | |
324 | ||
325 | <para>To enqueue and dequeue a buffer applications use the | |
326 | &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being | |
327 | mapped, enqueued, full or empty can be determined at any time using the | |
328 | &VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the | |
329 | application until one or more buffers can be dequeued. By default | |
330 | <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the | |
331 | outgoing queue. When the <constant>O_NONBLOCK</constant> flag was | |
332 | given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> | |
333 | returns immediately with an &EAGAIN; when no buffer is available. The | |
334 | &func-select; or &func-poll; function are always available.</para> | |
335 | ||
336 | <para>To start and stop capturing or output applications call the | |
337 | &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note | |
338 | <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both | |
339 | queues as a side effect. Since there is no notion of doing anything | |
340 | "now" on a multitasking system, if an application needs to synchronize | |
341 | with another event it should examine the &v4l2-buffer; | |
342 | <structfield>timestamp</structfield> of captured buffers, or set the | |
343 | field before enqueuing buffers for output.</para> | |
344 | ||
345 | <para>Drivers implementing memory mapping I/O must | |
346 | support the <constant>VIDIOC_REQBUFS</constant>, | |
347 | <constant>VIDIOC_QUERYBUF</constant>, | |
348 | <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, | |
349 | <constant>VIDIOC_STREAMON</constant> and | |
350 | <constant>VIDIOC_STREAMOFF</constant> ioctl, the | |
351 | <function>mmap()</function>, <function>munmap()</function>, | |
352 | <function>select()</function> and <function>poll()</function> | |
353 | function.<footnote> | |
354 | <para>At the driver level <function>select()</function> and | |
355 | <function>poll()</function> are the same, and | |
356 | <function>select()</function> is too important to be optional. The | |
357 | rest should be evident.</para> | |
358 | </footnote></para> | |
359 | ||
360 | <para>[capture example]</para> | |
361 | ||
362 | </section> | |
363 | ||
364 | <section id="userp"> | |
365 | <title>Streaming I/O (User Pointers)</title> | |
366 | ||
367 | <para>Input and output devices support this I/O method when the | |
368 | <constant>V4L2_CAP_STREAMING</constant> flag in the | |
369 | <structfield>capabilities</structfield> field of &v4l2-capability; | |
370 | returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user | |
371 | pointer method (not only memory mapping) is supported must be | |
372 | determined by calling the &VIDIOC-REQBUFS; ioctl.</para> | |
373 | ||
374 | <para>This I/O method combines advantages of the read/write and | |
53b5d574 | 375 | memory mapping methods. Buffers (planes) are allocated by the application |
8e080c2e MCC |
376 | itself, and can reside for example in virtual or shared memory. Only |
377 | pointers to data are exchanged, these pointers and meta-information | |
53b5d574 PO |
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 | |
8e080c2e MCC |
382 | buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para> |
383 | ||
384 | <example> | |
385 | <title>Initiating streaming I/O with user pointers</title> | |
386 | ||
387 | <programlisting> | |
388 | &v4l2-requestbuffers; reqbuf; | |
389 | ||
390 | memset (&reqbuf, 0, sizeof (reqbuf)); | |
391 | reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | |
392 | reqbuf.memory = V4L2_MEMORY_USERPTR; | |
393 | ||
394 | if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { | |
395 | if (errno == EINVAL) | |
396 | printf ("Video capturing or user pointer streaming is not supported\n"); | |
397 | else | |
398 | perror ("VIDIOC_REQBUFS"); | |
399 | ||
400 | exit (EXIT_FAILURE); | |
401 | } | |
402 | </programlisting> | |
403 | </example> | |
404 | ||
53b5d574 | 405 | <para>Buffer (plane) addresses and sizes are passed on the fly with the |
8e080c2e MCC |
406 | &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled, |
407 | applications can pass different addresses and sizes at each | |
408 | <constant>VIDIOC_QBUF</constant> call. If required by the hardware the | |
409 | driver swaps memory pages within physical memory to create a | |
410 | continuous area of memory. This happens transparently to the | |
411 | application in the virtual memory subsystem of the kernel. When buffer | |
412 | pages have been swapped out to disk they are brought back and finally | |
413 | locked in physical memory for DMA.<footnote> | |
414 | <para>We expect that frequently used buffers are typically not | |
415 | swapped out. Anyway, the process of swapping, locking or generating | |
416 | scatter-gather lists may be time consuming. The delay can be masked by | |
417 | the depth of the incoming buffer queue, and perhaps by maintaining | |
418 | caches assuming a buffer will be soon enqueued again. On the other | |
419 | hand, to optimize memory usage drivers can limit the number of buffers | |
420 | locked in advance and recycle the most recently used buffers first. Of | |
421 | course, the pages of empty buffers in the incoming queue need not be | |
422 | saved to disk. Output buffers must be saved on the incoming and | |
423 | outgoing queue because an application may share them with other | |
424 | processes.</para> | |
425 | </footnote></para> | |
426 | ||
427 | <para>Filled or displayed buffers are dequeued with the | |
428 | &VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any | |
429 | time between the completion of the DMA and this ioctl. The memory is | |
430 | also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or | |
431 | when the device is closed. Applications must take care not to free | |
432 | buffers without dequeuing. For once, the buffers remain locked until | |
433 | further, wasting physical memory. Second the driver will not be | |
434 | notified when the memory is returned to the application's free list | |
435 | and subsequently reused for other purposes, possibly completing the | |
436 | requested DMA and overwriting valuable data.</para> | |
437 | ||
438 | <para>For capturing applications it is customary to enqueue a | |
439 | number of empty buffers, to start capturing and enter the read loop. | |
440 | Here the application waits until a filled buffer can be dequeued, and | |
441 | re-enqueues the buffer when the data is no longer needed. Output | |
442 | applications fill and enqueue buffers, when enough buffers are stacked | |
443 | up output is started. In the write loop, when the application | |
444 | runs out of free buffers it must wait until an empty buffer can be | |
445 | dequeued and reused. Two methods exist to suspend execution of the | |
446 | application until one or more buffers can be dequeued. By default | |
447 | <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the | |
448 | outgoing queue. When the <constant>O_NONBLOCK</constant> flag was | |
449 | given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> | |
450 | returns immediately with an &EAGAIN; when no buffer is available. The | |
451 | &func-select; or &func-poll; function are always available.</para> | |
452 | ||
453 | <para>To start and stop capturing or output applications call the | |
454 | &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note | |
455 | <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both | |
456 | queues and unlocks all buffers as a side effect. Since there is no | |
457 | notion of doing anything "now" on a multitasking system, if an | |
458 | application needs to synchronize with another event it should examine | |
459 | the &v4l2-buffer; <structfield>timestamp</structfield> of captured | |
460 | buffers, or set the field before enqueuing buffers for output.</para> | |
461 | ||
462 | <para>Drivers implementing user pointer I/O must | |
463 | support the <constant>VIDIOC_REQBUFS</constant>, | |
464 | <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, | |
465 | <constant>VIDIOC_STREAMON</constant> and | |
466 | <constant>VIDIOC_STREAMOFF</constant> ioctl, the | |
467 | <function>select()</function> and <function>poll()</function> function.<footnote> | |
468 | <para>At the driver level <function>select()</function> and | |
469 | <function>poll()</function> are the same, and | |
470 | <function>select()</function> is too important to be optional. The | |
471 | rest should be evident.</para> | |
472 | </footnote></para> | |
473 | </section> | |
474 | ||
475 | <section id="async"> | |
476 | <title>Asynchronous I/O</title> | |
477 | ||
478 | <para>This method is not defined yet.</para> | |
479 | </section> | |
480 | ||
481 | <section id="buffer"> | |
482 | <title>Buffers</title> | |
483 | ||
484 | <para>A buffer contains data exchanged by application and | |
53b5d574 PO |
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> | |
8e080c2e MCC |
497 | |
498 | <para>Nominally timestamps refer to the first data byte transmitted. | |
499 | In practice however the wide range of hardware covered by the V4L2 API | |
500 | limits timestamp accuracy. Often an interrupt routine will | |
501 | sample the system clock shortly after the field or frame was stored | |
502 | completely in memory. So applications must expect a constant | |
503 | difference up to one field or frame period plus a small (few scan | |
504 | lines) random error. The delay and error can be much | |
505 | larger due to compression or transmission over an external bus when | |
506 | the frames are not properly stamped by the sender. This is frequently | |
507 | the case with USB cameras. Here timestamps refer to the instant the | |
508 | field or frame was received by the driver, not the capture time. These | |
509 | devices identify by not enumerating any video standards, see <xref | |
510 | linkend="standard" />.</para> | |
511 | ||
512 | <para>Similar limitations apply to output timestamps. Typically | |
513 | the video hardware locks to a clock controlling the video timing, the | |
514 | horizontal and vertical synchronization pulses. At some point in the | |
515 | line sequence, possibly the vertical blanking, an interrupt routine | |
516 | samples the system clock, compares against the timestamp and programs | |
517 | the hardware to repeat the previous field or frame, or to display the | |
518 | buffer contents.</para> | |
519 | ||
520 | <para>Apart of limitations of the video device and natural | |
521 | inaccuracies of all clocks, it should be noted system time itself is | |
522 | not perfectly stable. It can be affected by power saving cycles, | |
523 | warped to insert leap seconds, or even turned back or forth by the | |
524 | system administrator affecting long term measurements. <footnote> | |
525 | <para>Since no other Linux multimedia | |
526 | API supports unadjusted time it would be foolish to introduce here. We | |
527 | must use a universally supported clock to synchronize different media, | |
528 | hence time of day.</para> | |
529 | </footnote></para> | |
530 | ||
531 | <table frame="none" pgwide="1" id="v4l2-buffer"> | |
532 | <title>struct <structname>v4l2_buffer</structname></title> | |
533 | <tgroup cols="4"> | |
534 | &cs-ustr; | |
535 | <tbody valign="top"> | |
536 | <row> | |
537 | <entry>__u32</entry> | |
538 | <entry><structfield>index</structfield></entry> | |
539 | <entry></entry> | |
540 | <entry>Number of the buffer, set by the application. This | |
541 | field is only used for <link linkend="mmap">memory mapping</link> I/O | |
542 | and can range from zero to the number of buffers allocated | |
543 | with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry> | |
544 | </row> | |
545 | <row> | |
546 | <entry>&v4l2-buf-type;</entry> | |
547 | <entry><structfield>type</structfield></entry> | |
548 | <entry></entry> | |
549 | <entry>Type of the buffer, same as &v4l2-format; | |
550 | <structfield>type</structfield> or &v4l2-requestbuffers; | |
551 | <structfield>type</structfield>, set by the application.</entry> | |
552 | </row> | |
553 | <row> | |
554 | <entry>__u32</entry> | |
555 | <entry><structfield>bytesused</structfield></entry> | |
556 | <entry></entry> | |
557 | <entry>The number of bytes occupied by the data in the | |
558 | buffer. It depends on the negotiated data format and may change with | |
559 | each buffer for compressed variable size data like JPEG images. | |
560 | Drivers must set this field when <structfield>type</structfield> | |
561 | refers to an input stream, applications when an output stream.</entry> | |
562 | </row> | |
563 | <row> | |
564 | <entry>__u32</entry> | |
565 | <entry><structfield>flags</structfield></entry> | |
566 | <entry></entry> | |
567 | <entry>Flags set by the application or driver, see <xref | |
568 | linkend="buffer-flags" />.</entry> | |
569 | </row> | |
570 | <row> | |
571 | <entry>&v4l2-field;</entry> | |
572 | <entry><structfield>field</structfield></entry> | |
573 | <entry></entry> | |
574 | <entry>Indicates the field order of the image in the | |
575 | buffer, see <xref linkend="v4l2-field" />. This field is not used when | |
576 | the buffer contains VBI data. Drivers must set it when | |
577 | <structfield>type</structfield> refers to an input stream, | |
578 | applications when an output stream.</entry> | |
579 | </row> | |
580 | <row> | |
581 | <entry>struct timeval</entry> | |
582 | <entry><structfield>timestamp</structfield></entry> | |
583 | <entry></entry> | |
584 | <entry><para>For input streams this is the | |
585 | system time (as returned by the <function>gettimeofday()</function> | |
586 | function) when the first data byte was captured. For output streams | |
587 | the data will not be displayed before this time, secondary to the | |
588 | nominal frame rate determined by the current video standard in | |
589 | enqueued order. Applications can for example zero this field to | |
590 | display frames as soon as possible. The driver stores the time at | |
591 | which the first data byte was actually sent out in the | |
592 | <structfield>timestamp</structfield> field. This permits | |
593 | applications to monitor the drift between the video and system | |
594 | clock.</para></entry> | |
595 | </row> | |
596 | <row> | |
597 | <entry>&v4l2-timecode;</entry> | |
598 | <entry><structfield>timecode</structfield></entry> | |
599 | <entry></entry> | |
600 | <entry>When <structfield>type</structfield> is | |
601 | <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the | |
602 | <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in | |
603 | <structfield>flags</structfield>, this structure contains a frame | |
604 | timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> | |
605 | mode the top and bottom field contain the same timecode. | |
606 | Timecodes are intended to help video editing and are typically recorded on | |
607 | video tapes, but also embedded in compressed formats like MPEG. This | |
608 | field is independent of the <structfield>timestamp</structfield> and | |
609 | <structfield>sequence</structfield> fields.</entry> | |
610 | </row> | |
611 | <row> | |
612 | <entry>__u32</entry> | |
613 | <entry><structfield>sequence</structfield></entry> | |
614 | <entry></entry> | |
615 | <entry>Set by the driver, counting the frames in the | |
616 | sequence.</entry> | |
617 | </row> | |
618 | <row> | |
619 | <entry spanname="hspan"><para>In <link | |
620 | linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and | |
621 | bottom field have the same sequence number. The count starts at zero | |
622 | and includes dropped or repeated frames. A dropped frame was received | |
623 | by an input device but could not be stored due to lack of free buffer | |
624 | space. A repeated frame was displayed again by an output device | |
625 | because the application did not pass new data in | |
626 | time.</para><para>Note this may count the frames received | |
627 | e.g. over USB, without taking into account the frames dropped by the | |
628 | remote hardware due to limited compression throughput or bus | |
629 | bandwidth. These devices identify by not enumerating any video | |
630 | standards, see <xref linkend="standard" />.</para></entry> | |
631 | </row> | |
632 | <row> | |
633 | <entry>&v4l2-memory;</entry> | |
634 | <entry><structfield>memory</structfield></entry> | |
635 | <entry></entry> | |
636 | <entry>This field must be set by applications and/or drivers | |
637 | in accordance with the selected I/O method.</entry> | |
638 | </row> | |
639 | <row> | |
640 | <entry>union</entry> | |
641 | <entry><structfield>m</structfield></entry> | |
642 | </row> | |
643 | <row> | |
644 | <entry></entry> | |
645 | <entry>__u32</entry> | |
646 | <entry><structfield>offset</structfield></entry> | |
53b5d574 PO |
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> | |
8e080c2e MCC |
653 | </row> |
654 | <row> | |
655 | <entry></entry> | |
656 | <entry>unsigned long</entry> | |
657 | <entry><structfield>userptr</structfield></entry> | |
53b5d574 PO |
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> | |
8e080c2e MCC |
672 | </row> |
673 | <row> | |
674 | <entry>__u32</entry> | |
675 | <entry><structfield>length</structfield></entry> | |
676 | <entry></entry> | |
53b5d574 PO |
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> | |
8e080c2e MCC |
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 | |
995f5fef HV |
699 | <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications |
700 | should set this to 0.</entry> | |
8e080c2e MCC |
701 | </row> |
702 | </tbody> | |
703 | </tgroup> | |
704 | </table> | |
705 | ||
53b5d574 PO |
706 | <table frame="none" pgwide="1" id="v4l2-plane"> |
707 | <title>struct <structname>v4l2_plane</structname></title> | |
708 | <tgroup cols="4"> | |
709 | &cs-ustr; | |
710 | <tbody valign="top"> | |
711 | <row> | |
712 | <entry>__u32</entry> | |
713 | <entry><structfield>bytesused</structfield></entry> | |
714 | <entry></entry> | |
715 | <entry>The number of bytes occupied by data in the plane | |
716 | (its payload).</entry> | |
717 | </row> | |
718 | <row> | |
719 | <entry>__u32</entry> | |
720 | <entry><structfield>length</structfield></entry> | |
721 | <entry></entry> | |
722 | <entry>Size in bytes of the plane (not its payload).</entry> | |
723 | </row> | |
724 | <row> | |
725 | <entry>union</entry> | |
726 | <entry><structfield>m</structfield></entry> | |
727 | <entry></entry> | |
728 | <entry></entry> | |
729 | </row> | |
730 | <row> | |
731 | <entry></entry> | |
732 | <entry>__u32</entry> | |
733 | <entry><structfield>mem_offset</structfield></entry> | |
734 | <entry>When the memory type in the containing &v4l2-buffer; is | |
735 | <constant>V4L2_MEMORY_MMAP</constant>, this is the value that | |
736 | should be passed to &func-mmap;, similar to the | |
737 | <structfield>offset</structfield> field in &v4l2-buffer;.</entry> | |
738 | </row> | |
739 | <row> | |
740 | <entry></entry> | |
741 | <entry>__unsigned long</entry> | |
742 | <entry><structfield>userptr</structfield></entry> | |
743 | <entry>When the memory type in the containing &v4l2-buffer; is | |
744 | <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace | |
745 | pointer to the memory allocated for this plane by an application. | |
746 | </entry> | |
747 | </row> | |
748 | <row> | |
749 | <entry>__u32</entry> | |
750 | <entry><structfield>data_offset</structfield></entry> | |
751 | <entry></entry> | |
752 | <entry>Offset in bytes to video data in the plane, if applicable. | |
753 | </entry> | |
754 | </row> | |
755 | <row> | |
756 | <entry>__u32</entry> | |
757 | <entry><structfield>reserved[11]</structfield></entry> | |
758 | <entry></entry> | |
759 | <entry>Reserved for future use. Should be zeroed by an | |
760 | application.</entry> | |
761 | </row> | |
762 | </tbody> | |
763 | </tgroup> | |
764 | </table> | |
765 | ||
8e080c2e MCC |
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> | |
53b5d574 PO |
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 | |
8e080c2e MCC |
782 | linkend="capture" />.</entry> |
783 | </row> | |
784 | <row> | |
785 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> | |
786 | <entry>2</entry> | |
53b5d574 PO |
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 | |
8e080c2e MCC |
795 | linkend="output" />.</entry> |
796 | </row> | |
797 | <row> | |
798 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> | |
799 | <entry>3</entry> | |
800 | <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry> | |
801 | </row> | |
802 | <row> | |
803 | <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> | |
804 | <entry>4</entry> | |
805 | <entry>Buffer of a raw VBI capture stream, see <xref | |
806 | linkend="raw-vbi" />.</entry> | |
807 | </row> | |
808 | <row> | |
809 | <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> | |
810 | <entry>5</entry> | |
811 | <entry>Buffer of a raw VBI output stream, see <xref | |
812 | linkend="raw-vbi" />.</entry> | |
813 | </row> | |
814 | <row> | |
815 | <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> | |
816 | <entry>6</entry> | |
817 | <entry>Buffer of a sliced VBI capture stream, see <xref | |
818 | linkend="sliced" />.</entry> | |
819 | </row> | |
820 | <row> | |
821 | <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> | |
822 | <entry>7</entry> | |
823 | <entry>Buffer of a sliced VBI output stream, see <xref | |
824 | linkend="sliced" />.</entry> | |
825 | </row> | |
826 | <row> | |
827 | <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry> | |
828 | <entry>8</entry> | |
829 | <entry>Buffer for video output overlay (OSD), see <xref | |
830 | linkend="osd" />. Status: <link | |
831 | linkend="experimental">Experimental</link>.</entry> | |
832 | </row> | |
833 | <row> | |
834 | <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry> | |
835 | <entry>0x80</entry> | |
836 | <entry>This and higher values are reserved for custom | |
837 | (driver defined) buffer types.</entry> | |
838 | </row> | |
839 | </tbody> | |
840 | </tgroup> | |
841 | </table> | |
842 | ||
843 | <table frame="none" pgwide="1" id="buffer-flags"> | |
844 | <title>Buffer Flags</title> | |
845 | <tgroup cols="3"> | |
846 | &cs-def; | |
847 | <tbody valign="top"> | |
848 | <row> | |
849 | <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry> | |
850 | <entry>0x0001</entry> | |
851 | <entry>The buffer resides in device memory and has been mapped | |
852 | into the application's address space, see <xref linkend="mmap" /> for details. | |
853 | Drivers set or clear this flag when the | |
854 | <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link | |
855 | linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link | |
856 | linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry> | |
857 | </row> | |
858 | <row> | |
859 | <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry> | |
860 | <entry>0x0002</entry> | |
861 | <entry>Internally drivers maintain two buffer queues, an | |
862 | incoming and outgoing queue. When this flag is set, the buffer is | |
863 | currently on the incoming queue. It automatically moves to the | |
864 | outgoing queue after the buffer has been filled (capture devices) or | |
865 | displayed (output devices). Drivers set or clear this flag when the | |
866 | <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After | |
867 | (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is | |
868 | always set and after <constant>VIDIOC_DQBUF</constant> always | |
869 | cleared.</entry> | |
870 | </row> | |
871 | <row> | |
872 | <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry> | |
873 | <entry>0x0004</entry> | |
874 | <entry>When this flag is set, the buffer is currently on | |
875 | the outgoing queue, ready to be dequeued from the driver. Drivers set | |
876 | or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl | |
877 | is called. After calling the <constant>VIDIOC_QBUF</constant> or | |
878 | <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a | |
879 | buffer cannot be on both queues at the same time, the | |
880 | <constant>V4L2_BUF_FLAG_QUEUED</constant> and | |
881 | <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive. | |
882 | They can be both cleared however, then the buffer is in "dequeued" | |
883 | state, in the application domain to say so.</entry> | |
884 | </row> | |
21636363 PO |
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> | |
8e080c2e MCC |
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> | |
55093284 GL |
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> | |
8e080c2e MCC |
957 | </tbody> |
958 | </tgroup> | |
959 | </table> | |
960 | ||
961 | <table pgwide="1" frame="none" id="v4l2-memory"> | |
962 | <title>enum v4l2_memory</title> | |
963 | <tgroup cols="3"> | |
964 | &cs-def; | |
965 | <tbody valign="top"> | |
966 | <row> | |
967 | <entry><constant>V4L2_MEMORY_MMAP</constant></entry> | |
968 | <entry>1</entry> | |
969 | <entry>The buffer is used for <link linkend="mmap">memory | |
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> | |
986 | ||
987 | <section> | |
988 | <title>Timecodes</title> | |
989 | ||
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> | |
994 | ||
995 | <table frame="none" pgwide="1" id="v4l2-timecode"> | |
996 | <title>struct <structname>v4l2_timecode</structname></title> | |
997 | <tgroup cols="3"> | |
998 | &cs-str; | |
999 | <tbody valign="top"> | |
1000 | <row> | |
1001 | <entry>__u32</entry> | |
1002 | <entry><structfield>type</structfield></entry> | |
1003 | <entry>Frame rate the timecodes are based on, see <xref | |
1004 | linkend="timecode-type" />.</entry> | |
1005 | </row> | |
1006 | <row> | |
1007 | <entry>__u32</entry> | |
1008 | <entry><structfield>flags</structfield></entry> | |
1009 | <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry> | |
1010 | </row> | |
1011 | <row> | |
1012 | <entry>__u8</entry> | |
1013 | <entry><structfield>frames</structfield></entry> | |
1014 | <entry>Frame count, 0 ... 23/24/29/49/59, depending on the | |
1015 | type of timecode.</entry> | |
1016 | </row> | |
1017 | <row> | |
1018 | <entry>__u8</entry> | |
1019 | <entry><structfield>seconds</structfield></entry> | |
1020 | <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry> | |
1021 | </row> | |
1022 | <row> | |
1023 | <entry>__u8</entry> | |
1024 | <entry><structfield>minutes</structfield></entry> | |
1025 | <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry> | |
1026 | </row> | |
1027 | <row> | |
1028 | <entry>__u8</entry> | |
1029 | <entry><structfield>hours</structfield></entry> | |
1030 | <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry> | |
1031 | </row> | |
1032 | <row> | |
1033 | <entry>__u8</entry> | |
1034 | <entry><structfield>userbits</structfield>[4]</entry> | |
1035 | <entry>The "user group" bits from the timecode.</entry> | |
1036 | </row> | |
1037 | </tbody> | |
1038 | </tgroup> | |
1039 | </table> | |
1040 | ||
1041 | <table frame="none" pgwide="1" id="timecode-type"> | |
1042 | <title>Timecode Types</title> | |
1043 | <tgroup cols="3"> | |
1044 | &cs-def; | |
1045 | <tbody valign="top"> | |
1046 | <row> | |
1047 | <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry> | |
1048 | <entry>1</entry> | |
1049 | <entry>24 frames per second, i. e. film.</entry> | |
1050 | </row> | |
1051 | <row> | |
1052 | <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry> | |
1053 | <entry>2</entry> | |
1054 | <entry>25 frames per second, &ie; PAL or SECAM video.</entry> | |
1055 | </row> | |
1056 | <row> | |
1057 | <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry> | |
1058 | <entry>3</entry> | |
1059 | <entry>30 frames per second, &ie; NTSC video.</entry> | |
1060 | </row> | |
1061 | <row> | |
1062 | <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry> | |
1063 | <entry>4</entry> | |
1064 | <entry></entry> | |
1065 | </row> | |
1066 | <row> | |
1067 | <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry> | |
1068 | <entry>5</entry> | |
1069 | <entry></entry> | |
1070 | </row> | |
1071 | </tbody> | |
1072 | </tgroup> | |
1073 | </table> | |
1074 | ||
1075 | <table frame="none" pgwide="1" id="timecode-flags"> | |
1076 | <title>Timecode Flags</title> | |
1077 | <tgroup cols="3"> | |
1078 | &cs-def; | |
1079 | <tbody valign="top"> | |
1080 | <row> | |
1081 | <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry> | |
1082 | <entry>0x0001</entry> | |
1083 | <entry>Indicates "drop frame" semantics for counting frames | |
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> | |
1113 | ||
1114 | <section id="field-order"> | |
1115 | <title>Field Order</title> | |
1116 | ||
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> | |
1128 | ||
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> | |
1136 | ||
1137 | <para>When the driver provides or accepts images field by field | |
1138 | rather than interleaved, it is also important applications understand | |
37089368 HV |
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 | |
8e080c2e MCC |
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> | |
1143 | ||
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> | |
1150 | ||
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> | |
1156 | ||
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> | |
1163 | ||
1164 | <table frame="none" pgwide="1" id="v4l2-field"> | |
1165 | <title>enum v4l2_field</title> | |
1166 | <tgroup cols="3"> | |
1167 | &cs-def; | |
1168 | <tbody valign="top"> | |
1169 | <row> | |
1170 | <entry><constant>V4L2_FIELD_ANY</constant></entry> | |
1171 | <entry>0</entry> | |
1172 | <entry>Applications request this field order when any | |
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> | |
37089368 | 1193 | <entry>Images consist of the top (aka odd) field only.</entry> |
8e080c2e MCC |
1194 | </row> |
1195 | <row> | |
1196 | <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> | |
1197 | <entry>3</entry> | |
37089368 | 1198 | <entry>Images consist of the bottom (aka even) field only. |
8e080c2e MCC |
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> | |
1260 | ||
1261 | <figure id="fieldseq-tb"> | |
1262 | <title>Field Order, Top Field First Transmitted</title> | |
1263 | <mediaobject> | |
1264 | <imageobject> | |
1265 | <imagedata fileref="fieldseq_tb.pdf" format="PS" /> | |
1266 | </imageobject> | |
1267 | <imageobject> | |
1268 | <imagedata fileref="fieldseq_tb.gif" format="GIF" /> | |
1269 | </imageobject> | |
1270 | </mediaobject> | |
1271 | </figure> | |
1272 | ||
1273 | <figure id="fieldseq-bt"> | |
1274 | <title>Field Order, Bottom Field First Transmitted</title> | |
1275 | <mediaobject> | |
1276 | <imageobject> | |
1277 | <imagedata fileref="fieldseq_bt.pdf" format="PS" /> | |
1278 | </imageobject> | |
1279 | <imageobject> | |
1280 | <imagedata fileref="fieldseq_bt.gif" format="GIF" /> | |
1281 | </imageobject> | |
1282 | </mediaobject> | |
1283 | </figure> | |
1284 | </section> |