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