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