Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _buffer: | |
4 | ||
5 | ******* | |
6 | Buffers | |
7 | ******* | |
8 | ||
9 | A buffer contains data exchanged by application and driver using one of | |
10 | the Streaming I/O methods. In the multi-planar API, the data is held in | |
11 | planes, while the buffer structure acts as a container for the planes. | |
12 | Only pointers to buffers (planes) are exchanged, the data itself is not | |
13 | copied. These pointers, together with meta-information like timestamps | |
acf309a2 | 14 | or field parity, are stored in a struct :ref:`struct v4l2_buffer <v4l2-buffer>`, |
7347081e MCC |
15 | argument to the :ref:`VIDIOC_QUERYBUF`, |
16 | :ref:`VIDIOC_QBUF` and | |
af4a4d0d | 17 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API, |
acf309a2 | 18 | some plane-specific members of struct :ref:`struct v4l2_buffer <v4l2-buffer>`, |
5377d91f | 19 | such as pointers and sizes for each plane, are stored in struct |
acf309a2 MCC |
20 | :ref:`struct v4l2_plane <v4l2-plane>` instead. In that case, struct |
21 | :ref:`struct v4l2_buffer <v4l2-buffer>` contains an array of plane structures. | |
5377d91f MH |
22 | |
23 | Dequeued video buffers come with timestamps. The driver decides at which | |
24 | part of the frame and with which clock the timestamp is taken. Please | |
25 | see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and | |
26 | ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags | |
27 | are always valid and constant across all buffers during the whole video | |
28 | stream. Changes in these flags may take place as a side effect of | |
af4a4d0d MCC |
29 | :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or |
30 | :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The | |
5377d91f MH |
31 | ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on |
32 | mem-to-mem devices is an exception to the rule: the timestamp source | |
33 | flags are copied from the OUTPUT video buffer to the CAPTURE video | |
34 | buffer. | |
35 | ||
36 | ||
37 | .. _v4l2-buffer: | |
38 | ||
39 | .. flat-table:: struct v4l2_buffer | |
40 | :header-rows: 0 | |
41 | :stub-columns: 0 | |
42 | :widths: 1 1 1 2 | |
43 | ||
44 | ||
45 | - .. row 1 | |
46 | ||
47 | - __u32 | |
48 | ||
49 | - ``index`` | |
50 | ||
0579e6e3 | 51 | - |
5377d91f | 52 | - Number of the buffer, set by the application except when calling |
0579e6e3 MCC |
53 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the |
54 | driver. This field can range from zero to the number of buffers | |
55 | allocated with the :ref:`VIDIOC_REQBUFS` ioctl | |
56 | (struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` | |
57 | ``count``), plus any buffers allocated with | |
58 | :ref:`VIDIOC_CREATE_BUFS` minus one. | |
5377d91f MH |
59 | |
60 | - .. row 2 | |
61 | ||
62 | - __u32 | |
63 | ||
64 | - ``type`` | |
65 | ||
0579e6e3 | 66 | - |
5377d91f | 67 | - Type of the buffer, same as struct |
0579e6e3 MCC |
68 | :ref:`v4l2_format <v4l2-format>` ``type`` or struct |
69 | :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set | |
70 | by the application. See :ref:`v4l2-buf-type` | |
5377d91f MH |
71 | |
72 | - .. row 3 | |
73 | ||
74 | - __u32 | |
75 | ||
76 | - ``bytesused`` | |
77 | ||
0579e6e3 | 78 | - |
5377d91f | 79 | - The number of bytes occupied by the data in the buffer. It depends |
0579e6e3 MCC |
80 | on the negotiated data format and may change with each buffer for |
81 | compressed variable size data like JPEG images. Drivers must set | |
82 | this field when ``type`` refers to a capture stream, applications | |
83 | when it refers to an output stream. If the application sets this | |
84 | to 0 for an output stream, then ``bytesused`` will be set to the | |
85 | size of the buffer (see the ``length`` field of this struct) by | |
86 | the driver. For multiplanar formats this field is ignored and the | |
87 | ``planes`` pointer is used instead. | |
5377d91f MH |
88 | |
89 | - .. row 4 | |
90 | ||
91 | - __u32 | |
92 | ||
93 | - ``flags`` | |
94 | ||
0579e6e3 | 95 | - |
5377d91f MH |
96 | - Flags set by the application or driver, see :ref:`buffer-flags`. |
97 | ||
98 | - .. row 5 | |
99 | ||
100 | - __u32 | |
101 | ||
102 | - ``field`` | |
103 | ||
0579e6e3 | 104 | - |
5377d91f | 105 | - Indicates the field order of the image in the buffer, see |
0579e6e3 MCC |
106 | :ref:`v4l2-field`. This field is not used when the buffer |
107 | contains VBI data. Drivers must set it when ``type`` refers to a | |
108 | capture stream, applications when it refers to an output stream. | |
5377d91f MH |
109 | |
110 | - .. row 6 | |
111 | ||
112 | - struct timeval | |
113 | ||
114 | - ``timestamp`` | |
115 | ||
0579e6e3 | 116 | - |
5377d91f | 117 | - For capture streams this is time when the first data byte was |
0579e6e3 MCC |
118 | captured, as returned by the :c:func:`clock_gettime()` function |
119 | for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in | |
120 | :ref:`buffer-flags`. For output streams the driver stores the | |
121 | time at which the last data byte was actually sent out in the | |
122 | ``timestamp`` field. This permits applications to monitor the | |
123 | drift between the video and system clock. For output streams that | |
124 | use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill | |
125 | in the timestamp which will be copied by the driver to the capture | |
126 | stream. | |
5377d91f MH |
127 | |
128 | - .. row 7 | |
129 | ||
130 | - struct :ref:`v4l2_timecode <v4l2-timecode>` | |
131 | ||
132 | - ``timecode`` | |
133 | ||
0579e6e3 | 134 | - |
5377d91f | 135 | - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the |
0579e6e3 MCC |
136 | ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this |
137 | structure contains a frame timecode. In | |
138 | :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and | |
139 | bottom field contain the same timecode. Timecodes are intended to | |
140 | help video editing and are typically recorded on video tapes, but | |
141 | also embedded in compressed formats like MPEG. This field is | |
142 | independent of the ``timestamp`` and ``sequence`` fields. | |
5377d91f MH |
143 | |
144 | - .. row 8 | |
145 | ||
146 | - __u32 | |
147 | ||
148 | - ``sequence`` | |
149 | ||
0579e6e3 | 150 | - |
5377d91f | 151 | - Set by the driver, counting the frames (not fields!) in sequence. |
0579e6e3 | 152 | This field is set for both input and output devices. |
5377d91f MH |
153 | |
154 | - .. row 9 | |
155 | ||
156 | - :cspan:`3` | |
157 | ||
0579e6e3 MCC |
158 | In :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and |
159 | bottom field have the same sequence number. The count starts at | |
160 | zero and includes dropped or repeated frames. A dropped frame was | |
161 | received by an input device but could not be stored due to lack of | |
162 | free buffer space. A repeated frame was displayed again by an | |
163 | output device because the application did not pass new data in | |
164 | time. | |
5377d91f | 165 | |
0579e6e3 MCC |
166 | Note this may count the frames received e.g. over USB, without |
167 | taking into account the frames dropped by the remote hardware due | |
168 | to limited compression throughput or bus bandwidth. These devices | |
169 | identify by not enumerating any video standards, see | |
170 | :ref:`standard`. | |
5377d91f MH |
171 | |
172 | - .. row 10 | |
173 | ||
174 | - __u32 | |
175 | ||
176 | - ``memory`` | |
177 | ||
0579e6e3 | 178 | - |
5377d91f | 179 | - This field must be set by applications and/or drivers in |
0579e6e3 | 180 | accordance with the selected I/O method. See :ref:`v4l2-memory` |
5377d91f MH |
181 | |
182 | - .. row 11 | |
183 | ||
184 | - union | |
185 | ||
186 | - ``m`` | |
187 | ||
188 | - .. row 12 | |
189 | ||
0579e6e3 | 190 | - |
5377d91f MH |
191 | - __u32 |
192 | ||
193 | - ``offset`` | |
194 | ||
195 | - For the single-planar API and when ``memory`` is | |
0579e6e3 MCC |
196 | ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the |
197 | start of the device memory. The value is returned by the driver | |
198 | and apart of serving as parameter to the | |
199 | :ref:`mmap() <func-mmap>` function not useful for applications. | |
200 | See :ref:`mmap` for details | |
5377d91f MH |
201 | |
202 | - .. row 13 | |
203 | ||
0579e6e3 | 204 | - |
5377d91f MH |
205 | - unsigned long |
206 | ||
207 | - ``userptr`` | |
208 | ||
209 | - For the single-planar API and when ``memory`` is | |
0579e6e3 MCC |
210 | ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to |
211 | unsigned long type) in virtual memory, set by the application. See | |
212 | :ref:`userp` for details. | |
5377d91f MH |
213 | |
214 | - .. row 14 | |
215 | ||
0579e6e3 | 216 | - |
5377d91f MH |
217 | - struct v4l2_plane |
218 | ||
219 | - ``*planes`` | |
220 | ||
221 | - When using the multi-planar API, contains a userspace pointer to | |
0579e6e3 MCC |
222 | an array of struct :ref:`v4l2_plane <v4l2-plane>`. The size of |
223 | the array should be put in the ``length`` field of this | |
224 | :ref:`struct v4l2_buffer <v4l2-buffer>` structure. | |
5377d91f MH |
225 | |
226 | - .. row 15 | |
227 | ||
0579e6e3 | 228 | - |
5377d91f MH |
229 | - int |
230 | ||
231 | - ``fd`` | |
232 | ||
233 | - For the single-plane API and when ``memory`` is | |
0579e6e3 MCC |
234 | ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with |
235 | a DMABUF buffer. | |
5377d91f MH |
236 | |
237 | - .. row 16 | |
238 | ||
239 | - __u32 | |
240 | ||
241 | - ``length`` | |
242 | ||
0579e6e3 | 243 | - |
5377d91f | 244 | - Size of the buffer (not the payload) in bytes for the |
0579e6e3 MCC |
245 | single-planar API. This is set by the driver based on the calls to |
246 | :ref:`VIDIOC_REQBUFS` and/or | |
247 | :ref:`VIDIOC_CREATE_BUFS`. For the | |
248 | multi-planar API the application sets this to the number of | |
249 | elements in the ``planes`` array. The driver will fill in the | |
250 | actual number of valid elements in that array. | |
5377d91f MH |
251 | |
252 | - .. row 17 | |
253 | ||
254 | - __u32 | |
255 | ||
256 | - ``reserved2`` | |
257 | ||
0579e6e3 | 258 | - |
5377d91f | 259 | - A place holder for future extensions. Drivers and applications |
0579e6e3 | 260 | must set this to 0. |
5377d91f MH |
261 | |
262 | - .. row 18 | |
263 | ||
264 | - __u32 | |
265 | ||
266 | - ``reserved`` | |
267 | ||
0579e6e3 | 268 | - |
5377d91f | 269 | - A place holder for future extensions. Drivers and applications |
0579e6e3 | 270 | must set this to 0. |
5377d91f MH |
271 | |
272 | ||
273 | ||
274 | .. _v4l2-plane: | |
275 | ||
276 | .. flat-table:: struct v4l2_plane | |
277 | :header-rows: 0 | |
278 | :stub-columns: 0 | |
279 | :widths: 1 1 1 2 | |
280 | ||
281 | ||
282 | - .. row 1 | |
283 | ||
284 | - __u32 | |
285 | ||
286 | - ``bytesused`` | |
287 | ||
0579e6e3 | 288 | - |
5377d91f | 289 | - The number of bytes occupied by data in the plane (its payload). |
0579e6e3 MCC |
290 | Drivers must set this field when ``type`` refers to a capture |
291 | stream, applications when it refers to an output stream. If the | |
292 | application sets this to 0 for an output stream, then | |
293 | ``bytesused`` will be set to the size of the plane (see the | |
294 | ``length`` field of this struct) by the driver. Note that the | |
295 | actual image data starts at ``data_offset`` which may not be 0. | |
5377d91f MH |
296 | |
297 | - .. row 2 | |
298 | ||
299 | - __u32 | |
300 | ||
301 | - ``length`` | |
302 | ||
0579e6e3 | 303 | - |
5377d91f | 304 | - Size in bytes of the plane (not its payload). This is set by the |
0579e6e3 MCC |
305 | driver based on the calls to |
306 | :ref:`VIDIOC_REQBUFS` and/or | |
307 | :ref:`VIDIOC_CREATE_BUFS`. | |
5377d91f MH |
308 | |
309 | - .. row 3 | |
310 | ||
311 | - union | |
312 | ||
313 | - ``m`` | |
314 | ||
0579e6e3 MCC |
315 | - |
316 | - | |
5377d91f MH |
317 | |
318 | - .. row 4 | |
319 | ||
0579e6e3 | 320 | - |
5377d91f MH |
321 | - __u32 |
322 | ||
323 | - ``mem_offset`` | |
324 | ||
325 | - When the memory type in the containing struct | |
0579e6e3 MCC |
326 | :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_MMAP``, this |
327 | is the value that should be passed to :ref:`mmap() <func-mmap>`, | |
328 | similar to the ``offset`` field in struct | |
329 | :ref:`v4l2_buffer <v4l2-buffer>`. | |
5377d91f MH |
330 | |
331 | - .. row 5 | |
332 | ||
0579e6e3 | 333 | - |
5377d91f MH |
334 | - unsigned long |
335 | ||
336 | - ``userptr`` | |
337 | ||
338 | - When the memory type in the containing struct | |
0579e6e3 MCC |
339 | :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_USERPTR``, |
340 | this is a userspace pointer to the memory allocated for this plane | |
341 | by an application. | |
5377d91f MH |
342 | |
343 | - .. row 6 | |
344 | ||
0579e6e3 | 345 | - |
5377d91f MH |
346 | - int |
347 | ||
348 | - ``fd`` | |
349 | ||
350 | - When the memory type in the containing struct | |
0579e6e3 MCC |
351 | :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_DMABUF``, |
352 | this is a file descriptor associated with a DMABUF buffer, similar | |
353 | to the ``fd`` field in struct :ref:`v4l2_buffer <v4l2-buffer>`. | |
5377d91f MH |
354 | |
355 | - .. row 7 | |
356 | ||
357 | - __u32 | |
358 | ||
359 | - ``data_offset`` | |
360 | ||
0579e6e3 | 361 | - |
5377d91f | 362 | - Offset in bytes to video data in the plane. Drivers must set this |
0579e6e3 MCC |
363 | field when ``type`` refers to a capture stream, applications when |
364 | it refers to an output stream. Note that data_offset is included | |
365 | in ``bytesused``. So the size of the image in the plane is | |
366 | ``bytesused``-``data_offset`` at offset ``data_offset`` from the | |
367 | start of the plane. | |
5377d91f MH |
368 | |
369 | - .. row 8 | |
370 | ||
371 | - __u32 | |
372 | ||
373 | - ``reserved[11]`` | |
374 | ||
0579e6e3 | 375 | - |
5377d91f | 376 | - Reserved for future use. Should be zeroed by drivers and |
0579e6e3 | 377 | applications. |
5377d91f MH |
378 | |
379 | ||
380 | ||
381 | .. _v4l2-buf-type: | |
382 | ||
383 | .. flat-table:: enum v4l2_buf_type | |
384 | :header-rows: 0 | |
385 | :stub-columns: 0 | |
386 | :widths: 3 1 4 | |
387 | ||
388 | ||
389 | - .. row 1 | |
390 | ||
391 | - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` | |
392 | ||
393 | - 1 | |
394 | ||
395 | - Buffer of a single-planar video capture stream, see | |
0579e6e3 | 396 | :ref:`capture`. |
5377d91f MH |
397 | |
398 | - .. row 2 | |
399 | ||
400 | - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` | |
401 | ||
402 | - 9 | |
403 | ||
404 | - Buffer of a multi-planar video capture stream, see | |
0579e6e3 | 405 | :ref:`capture`. |
5377d91f MH |
406 | |
407 | - .. row 3 | |
408 | ||
409 | - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` | |
410 | ||
411 | - 2 | |
412 | ||
413 | - Buffer of a single-planar video output stream, see | |
0579e6e3 | 414 | :ref:`output`. |
5377d91f MH |
415 | |
416 | - .. row 4 | |
417 | ||
418 | - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` | |
419 | ||
420 | - 10 | |
421 | ||
422 | - Buffer of a multi-planar video output stream, see :ref:`output`. | |
423 | ||
424 | - .. row 5 | |
425 | ||
426 | - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` | |
427 | ||
428 | - 3 | |
429 | ||
430 | - Buffer for video overlay, see :ref:`overlay`. | |
431 | ||
432 | - .. row 6 | |
433 | ||
434 | - ``V4L2_BUF_TYPE_VBI_CAPTURE`` | |
435 | ||
436 | - 4 | |
437 | ||
438 | - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`. | |
439 | ||
440 | - .. row 7 | |
441 | ||
442 | - ``V4L2_BUF_TYPE_VBI_OUTPUT`` | |
443 | ||
444 | - 5 | |
445 | ||
446 | - Buffer of a raw VBI output stream, see :ref:`raw-vbi`. | |
447 | ||
448 | - .. row 8 | |
449 | ||
450 | - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` | |
451 | ||
452 | - 6 | |
453 | ||
454 | - Buffer of a sliced VBI capture stream, see :ref:`sliced`. | |
455 | ||
456 | - .. row 9 | |
457 | ||
458 | - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` | |
459 | ||
460 | - 7 | |
461 | ||
462 | - Buffer of a sliced VBI output stream, see :ref:`sliced`. | |
463 | ||
464 | - .. row 10 | |
465 | ||
466 | - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` | |
467 | ||
468 | - 8 | |
469 | ||
470 | - Buffer for video output overlay (OSD), see :ref:`osd`. | |
471 | ||
472 | - .. row 11 | |
473 | ||
474 | - ``V4L2_BUF_TYPE_SDR_CAPTURE`` | |
475 | ||
476 | - 11 | |
477 | ||
478 | - Buffer for Software Defined Radio (SDR) capture stream, see | |
0579e6e3 | 479 | :ref:`sdr`. |
5377d91f MH |
480 | |
481 | - .. row 12 | |
482 | ||
483 | - ``V4L2_BUF_TYPE_SDR_OUTPUT`` | |
484 | ||
485 | - 12 | |
486 | ||
487 | - Buffer for Software Defined Radio (SDR) output stream, see | |
0579e6e3 | 488 | :ref:`sdr`. |
5377d91f MH |
489 | |
490 | ||
491 | ||
492 | .. _buffer-flags: | |
493 | ||
494 | .. flat-table:: Buffer Flags | |
495 | :header-rows: 0 | |
496 | :stub-columns: 0 | |
497 | :widths: 3 1 4 | |
498 | ||
499 | ||
500 | - .. row 1 | |
501 | ||
502 | - ``V4L2_BUF_FLAG_MAPPED`` | |
503 | ||
504 | - 0x00000001 | |
505 | ||
506 | - The buffer resides in device memory and has been mapped into the | |
0579e6e3 MCC |
507 | application's address space, see :ref:`mmap` for details. |
508 | Drivers set or clear this flag when the | |
509 | :ref:`VIDIOC_QUERYBUF`, | |
510 | :ref:`VIDIOC_QBUF` or | |
511 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the | |
512 | driver. | |
5377d91f MH |
513 | |
514 | - .. row 2 | |
515 | ||
516 | - ``V4L2_BUF_FLAG_QUEUED`` | |
517 | ||
518 | - 0x00000002 | |
519 | ||
520 | - Internally drivers maintain two buffer queues, an incoming and | |
0579e6e3 MCC |
521 | outgoing queue. When this flag is set, the buffer is currently on |
522 | the incoming queue. It automatically moves to the outgoing queue | |
523 | after the buffer has been filled (capture devices) or displayed | |
524 | (output devices). Drivers set or clear this flag when the | |
525 | ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling | |
526 | the ``VIDIOC_QBUF``\ ioctl it is always set and after | |
527 | ``VIDIOC_DQBUF`` always cleared. | |
5377d91f MH |
528 | |
529 | - .. row 3 | |
530 | ||
531 | - ``V4L2_BUF_FLAG_DONE`` | |
532 | ||
533 | - 0x00000004 | |
534 | ||
535 | - When this flag is set, the buffer is currently on the outgoing | |
0579e6e3 MCC |
536 | queue, ready to be dequeued from the driver. Drivers set or clear |
537 | this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After | |
538 | calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always | |
539 | cleared. Of course a buffer cannot be on both queues at the same | |
540 | time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag | |
541 | are mutually exclusive. They can be both cleared however, then the | |
542 | buffer is in "dequeued" state, in the application domain so to | |
543 | say. | |
5377d91f MH |
544 | |
545 | - .. row 4 | |
546 | ||
547 | - ``V4L2_BUF_FLAG_ERROR`` | |
548 | ||
549 | - 0x00000040 | |
550 | ||
551 | - When this flag is set, the buffer has been dequeued successfully, | |
0579e6e3 MCC |
552 | although the data might have been corrupted. This is recoverable, |
553 | streaming may continue as normal and the buffer may be reused | |
554 | normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is | |
555 | called. | |
5377d91f MH |
556 | |
557 | - .. row 5 | |
558 | ||
559 | - ``V4L2_BUF_FLAG_KEYFRAME`` | |
560 | ||
561 | - 0x00000008 | |
562 | ||
563 | - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF`` | |
0579e6e3 MCC |
564 | ioctl. It may be set by video capture devices when the buffer |
565 | contains a compressed image which is a key frame (or field), i. e. | |
566 | can be decompressed on its own. Also known as an I-frame. | |
567 | Applications can set this bit when ``type`` refers to an output | |
568 | stream. | |
5377d91f MH |
569 | |
570 | - .. row 6 | |
571 | ||
572 | - ``V4L2_BUF_FLAG_PFRAME`` | |
573 | ||
574 | - 0x00000010 | |
575 | ||
576 | - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames | |
0579e6e3 MCC |
577 | or fields which contain only differences to a previous key frame. |
578 | Applications can set this bit when ``type`` refers to an output | |
579 | stream. | |
5377d91f MH |
580 | |
581 | - .. row 7 | |
582 | ||
583 | - ``V4L2_BUF_FLAG_BFRAME`` | |
584 | ||
585 | - 0x00000020 | |
586 | ||
587 | - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional | |
0579e6e3 MCC |
588 | predicted frame or field which contains only the differences |
589 | between the current frame and both the preceding and following key | |
590 | frames to specify its content. Applications can set this bit when | |
591 | ``type`` refers to an output stream. | |
5377d91f MH |
592 | |
593 | - .. row 8 | |
594 | ||
595 | - ``V4L2_BUF_FLAG_TIMECODE`` | |
596 | ||
597 | - 0x00000100 | |
598 | ||
599 | - The ``timecode`` field is valid. Drivers set or clear this flag | |
0579e6e3 MCC |
600 | when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set |
601 | this bit and the corresponding ``timecode`` structure when | |
602 | ``type`` refers to an output stream. | |
5377d91f MH |
603 | |
604 | - .. row 9 | |
605 | ||
606 | - ``V4L2_BUF_FLAG_PREPARED`` | |
607 | ||
608 | - 0x00000400 | |
609 | ||
610 | - The buffer has been prepared for I/O and can be queued by the | |
0579e6e3 MCC |
611 | application. Drivers set or clear this flag when the |
612 | :ref:`VIDIOC_QUERYBUF`, | |
613 | :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`, | |
614 | :ref:`VIDIOC_QBUF` or | |
615 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. | |
5377d91f MH |
616 | |
617 | - .. row 10 | |
618 | ||
619 | - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` | |
620 | ||
621 | - 0x00000800 | |
622 | ||
623 | - Caches do not have to be invalidated for this buffer. Typically | |
0579e6e3 MCC |
624 | applications shall use this flag if the data captured in the |
625 | buffer is not going to be touched by the CPU, instead the buffer | |
626 | will, probably, be passed on to a DMA-capable hardware unit for | |
627 | further processing or output. | |
5377d91f MH |
628 | |
629 | - .. row 11 | |
630 | ||
631 | - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` | |
632 | ||
633 | - 0x00001000 | |
634 | ||
635 | - Caches do not have to be cleaned for this buffer. Typically | |
0579e6e3 MCC |
636 | applications shall use this flag for output buffers if the data in |
637 | this buffer has not been created by the CPU but by some | |
638 | DMA-capable unit, in which case caches have not been used. | |
5377d91f MH |
639 | |
640 | - .. row 12 | |
641 | ||
642 | - ``V4L2_BUF_FLAG_LAST`` | |
643 | ||
644 | - 0x00100000 | |
645 | ||
646 | - Last buffer produced by the hardware. mem2mem codec drivers set | |
0579e6e3 MCC |
647 | this flag on the capture queue for the last buffer when the |
648 | :ref:`VIDIOC_QUERYBUF` or | |
649 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to | |
650 | hardware limitations, the last buffer may be empty. In this case | |
651 | the driver will set the ``bytesused`` field to 0, regardless of | |
652 | the format. Any Any subsequent call to the | |
653 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, | |
654 | but return an ``EPIPE`` error code. | |
5377d91f MH |
655 | |
656 | - .. row 13 | |
657 | ||
658 | - ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` | |
659 | ||
660 | - 0x0000e000 | |
661 | ||
662 | - Mask for timestamp types below. To test the timestamp type, mask | |
0579e6e3 MCC |
663 | out bits not belonging to timestamp type by performing a logical |
664 | and operation with buffer flags and timestamp mask. | |
5377d91f MH |
665 | |
666 | - .. row 14 | |
667 | ||
668 | - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN`` | |
669 | ||
670 | - 0x00000000 | |
671 | ||
672 | - Unknown timestamp type. This type is used by drivers before Linux | |
0579e6e3 MCC |
673 | 3.9 and may be either monotonic (see below) or realtime (wall |
674 | clock). Monotonic clock has been favoured in embedded systems | |
675 | whereas most of the drivers use the realtime clock. Either kinds | |
676 | of timestamps are available in user space via | |
677 | :c:func:`clock_gettime(2)` using clock IDs ``CLOCK_MONOTONIC`` | |
678 | and ``CLOCK_REALTIME``, respectively. | |
5377d91f MH |
679 | |
680 | - .. row 15 | |
681 | ||
682 | - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC`` | |
683 | ||
684 | - 0x00002000 | |
685 | ||
686 | - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC`` | |
0579e6e3 MCC |
687 | clock. To access the same clock outside V4L2, use |
688 | :c:func:`clock_gettime(2)`. | |
5377d91f MH |
689 | |
690 | - .. row 16 | |
691 | ||
692 | - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` | |
693 | ||
694 | - 0x00004000 | |
695 | ||
696 | - The CAPTURE buffer timestamp has been taken from the corresponding | |
0579e6e3 | 697 | OUTPUT buffer. This flag applies only to mem2mem devices. |
5377d91f MH |
698 | |
699 | - .. row 17 | |
700 | ||
701 | - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` | |
702 | ||
703 | - 0x00070000 | |
704 | ||
705 | - Mask for timestamp sources below. The timestamp source defines the | |
0579e6e3 MCC |
706 | point of time the timestamp is taken in relation to the frame. |
707 | Logical 'and' operation between the ``flags`` field and | |
708 | ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the | |
709 | timestamp source. Applications must set the timestamp source when | |
710 | ``type`` refers to an output stream and | |
711 | ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set. | |
5377d91f MH |
712 | |
713 | - .. row 18 | |
714 | ||
715 | - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF`` | |
716 | ||
717 | - 0x00000000 | |
718 | ||
719 | - End Of Frame. The buffer timestamp has been taken when the last | |
0579e6e3 MCC |
720 | pixel of the frame has been received or the last pixel of the |
721 | frame has been transmitted. In practice, software generated | |
722 | timestamps will typically be read from the clock a small amount of | |
723 | time after the last pixel has been received or transmitten, | |
724 | depending on the system and other activity in it. | |
5377d91f MH |
725 | |
726 | - .. row 19 | |
727 | ||
728 | - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE`` | |
729 | ||
730 | - 0x00010000 | |
731 | ||
732 | - Start Of Exposure. The buffer timestamp has been taken when the | |
0579e6e3 MCC |
733 | exposure of the frame has begun. This is only valid for the |
734 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. | |
5377d91f MH |
735 | |
736 | ||
737 | ||
738 | .. _v4l2-memory: | |
739 | ||
740 | .. flat-table:: enum v4l2_memory | |
741 | :header-rows: 0 | |
742 | :stub-columns: 0 | |
743 | :widths: 3 1 4 | |
744 | ||
745 | ||
746 | - .. row 1 | |
747 | ||
748 | - ``V4L2_MEMORY_MMAP`` | |
749 | ||
750 | - 1 | |
751 | ||
752 | - The buffer is used for :ref:`memory mapping <mmap>` I/O. | |
753 | ||
754 | - .. row 2 | |
755 | ||
756 | - ``V4L2_MEMORY_USERPTR`` | |
757 | ||
758 | - 2 | |
759 | ||
760 | - The buffer is used for :ref:`user pointer <userp>` I/O. | |
761 | ||
762 | - .. row 3 | |
763 | ||
764 | - ``V4L2_MEMORY_OVERLAY`` | |
765 | ||
766 | - 3 | |
767 | ||
768 | - [to do] | |
769 | ||
770 | - .. row 4 | |
771 | ||
772 | - ``V4L2_MEMORY_DMABUF`` | |
773 | ||
774 | - 4 | |
775 | ||
776 | - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O. | |
777 | ||
778 | ||
779 | ||
780 | Timecodes | |
781 | ========= | |
782 | ||
acf309a2 | 783 | The :ref:`struct v4l2_timecode <v4l2-timecode>` structure is designed to hold a |
5377d91f MH |
784 | :ref:`smpte12m` or similar timecode. (struct |
785 | :c:type:`struct timeval` timestamps are stored in struct | |
786 | :ref:`v4l2_buffer <v4l2-buffer>` field ``timestamp``.) | |
787 | ||
788 | ||
789 | .. _v4l2-timecode: | |
790 | ||
791 | .. flat-table:: struct v4l2_timecode | |
792 | :header-rows: 0 | |
793 | :stub-columns: 0 | |
794 | :widths: 1 1 2 | |
795 | ||
796 | ||
797 | - .. row 1 | |
798 | ||
799 | - __u32 | |
800 | ||
801 | - ``type`` | |
802 | ||
803 | - Frame rate the timecodes are based on, see :ref:`timecode-type`. | |
804 | ||
805 | - .. row 2 | |
806 | ||
807 | - __u32 | |
808 | ||
809 | - ``flags`` | |
810 | ||
811 | - Timecode flags, see :ref:`timecode-flags`. | |
812 | ||
813 | - .. row 3 | |
814 | ||
815 | - __u8 | |
816 | ||
817 | - ``frames`` | |
818 | ||
819 | - Frame count, 0 ... 23/24/29/49/59, depending on the type of | |
0579e6e3 | 820 | timecode. |
5377d91f MH |
821 | |
822 | - .. row 4 | |
823 | ||
824 | - __u8 | |
825 | ||
826 | - ``seconds`` | |
827 | ||
828 | - Seconds count, 0 ... 59. This is a binary, not BCD number. | |
829 | ||
830 | - .. row 5 | |
831 | ||
832 | - __u8 | |
833 | ||
834 | - ``minutes`` | |
835 | ||
836 | - Minutes count, 0 ... 59. This is a binary, not BCD number. | |
837 | ||
838 | - .. row 6 | |
839 | ||
840 | - __u8 | |
841 | ||
842 | - ``hours`` | |
843 | ||
844 | - Hours count, 0 ... 29. This is a binary, not BCD number. | |
845 | ||
846 | - .. row 7 | |
847 | ||
848 | - __u8 | |
849 | ||
850 | - ``userbits``\ [4] | |
851 | ||
852 | - The "user group" bits from the timecode. | |
853 | ||
854 | ||
855 | ||
856 | .. _timecode-type: | |
857 | ||
858 | .. flat-table:: Timecode Types | |
859 | :header-rows: 0 | |
860 | :stub-columns: 0 | |
861 | :widths: 3 1 4 | |
862 | ||
863 | ||
864 | - .. row 1 | |
865 | ||
866 | - ``V4L2_TC_TYPE_24FPS`` | |
867 | ||
868 | - 1 | |
869 | ||
870 | - 24 frames per second, i. e. film. | |
871 | ||
872 | - .. row 2 | |
873 | ||
874 | - ``V4L2_TC_TYPE_25FPS`` | |
875 | ||
876 | - 2 | |
877 | ||
878 | - 25 frames per second, i. e. PAL or SECAM video. | |
879 | ||
880 | - .. row 3 | |
881 | ||
882 | - ``V4L2_TC_TYPE_30FPS`` | |
883 | ||
884 | - 3 | |
885 | ||
886 | - 30 frames per second, i. e. NTSC video. | |
887 | ||
888 | - .. row 4 | |
889 | ||
890 | - ``V4L2_TC_TYPE_50FPS`` | |
891 | ||
892 | - 4 | |
893 | ||
0579e6e3 | 894 | - |
5377d91f MH |
895 | |
896 | - .. row 5 | |
897 | ||
898 | - ``V4L2_TC_TYPE_60FPS`` | |
899 | ||
900 | - 5 | |
901 | ||
0579e6e3 | 902 | - |
5377d91f MH |
903 | |
904 | ||
905 | ||
906 | .. _timecode-flags: | |
907 | ||
908 | .. flat-table:: Timecode Flags | |
909 | :header-rows: 0 | |
910 | :stub-columns: 0 | |
911 | :widths: 3 1 4 | |
912 | ||
913 | ||
914 | - .. row 1 | |
915 | ||
916 | - ``V4L2_TC_FLAG_DROPFRAME`` | |
917 | ||
918 | - 0x0001 | |
919 | ||
920 | - Indicates "drop frame" semantics for counting frames in 29.97 fps | |
0579e6e3 MCC |
921 | material. When set, frame numbers 0 and 1 at the start of each |
922 | minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the | |
923 | count. | |
5377d91f MH |
924 | |
925 | - .. row 2 | |
926 | ||
927 | - ``V4L2_TC_FLAG_COLORFRAME`` | |
928 | ||
929 | - 0x0002 | |
930 | ||
931 | - The "color frame" flag. | |
932 | ||
933 | - .. row 3 | |
934 | ||
935 | - ``V4L2_TC_USERBITS_field`` | |
936 | ||
937 | - 0x000C | |
938 | ||
939 | - Field mask for the "binary group flags". | |
940 | ||
941 | - .. row 4 | |
942 | ||
943 | - ``V4L2_TC_USERBITS_USERDEFINED`` | |
944 | ||
945 | - 0x0000 | |
946 | ||
947 | - Unspecified format. | |
948 | ||
949 | - .. row 5 | |
950 | ||
951 | - ``V4L2_TC_USERBITS_8BITCHARS`` | |
952 | ||
953 | - 0x0008 | |
954 | ||
955 | - 8-bit ISO characters. |