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 | ||
99bb078e LP |
37 | Interactions between formats, controls and buffers |
38 | ================================================== | |
39 | ||
40 | V4L2 exposes parameters that influence the buffer size, or the way data is | |
41 | laid out in the buffer. Those parameters are exposed through both formats and | |
42 | controls. One example of such a control is the ``V4L2_CID_ROTATE`` control | |
43 | that modifies the direction in which pixels are stored in the buffer, as well | |
44 | as the buffer size when the selected format includes padding at the end of | |
45 | lines. | |
46 | ||
47 | The set of information needed to interpret the content of a buffer (e.g. the | |
48 | pixel format, the line stride, the tiling orientation or the rotation) is | |
49 | collectively referred to in the rest of this section as the buffer layout. | |
50 | ||
51 | Modifying formats or controls that influence the buffer size or layout require | |
52 | the stream to be stopped. Any attempt at such a modification while the stream | |
53 | is active shall cause the ioctl setting the format or the control to return | |
54 | the ``EBUSY`` error code. | |
55 | ||
56 | .. note:: | |
57 | ||
58 | The :c:func:`VIDIOC_S_SELECTION` ioctl can, depending on the hardware (for | |
59 | instance if the device doesn't include a scaler), modify the format in | |
60 | addition to the selection rectangle. Similarly, the | |
61 | :c:func:`VIDIOC_S_INPUT`, :c:func:`VIDIOC_S_OUTPUT`, :c:func:`VIDIOC_S_STD` | |
62 | and :c:func:`VIDIOC_S_DV_TIMINGS` ioctls can also modify the format and | |
63 | selection rectangles. When those ioctls result in a buffer size or layout | |
64 | change, drivers shall handle that condition as they would handle it in the | |
65 | :c:func:`VIDIOC_S_FMT` ioctl in all cases described in this section. | |
66 | ||
67 | Controls that only influence the buffer layout can be modified at any time | |
68 | when the stream is stopped. As they don't influence the buffer size, no | |
69 | special handling is needed to synchronize those controls with buffer | |
70 | allocation. | |
71 | ||
72 | Formats and controls that influence the buffer size interact with buffer | |
73 | allocation. The simplest way to handle this is for drivers to always require | |
74 | buffers to be reallocated in order to change those formats or controls. In | |
75 | that case, to perform such changes, userspace applications shall first stop | |
76 | the video stream with the :c:func:`VIDIOC_STREAMOFF` ioctl if it is running | |
77 | and free all buffers with the :c:func:`VIDIOC_REQBUFS` ioctl if they are | |
78 | allocated. The format or controls can then be modified, and buffers shall then | |
79 | be reallocated and the stream restarted. A typical ioctl sequence is | |
80 | ||
81 | #. VIDIOC_STREAMOFF | |
82 | #. VIDIOC_REQBUFS(0) | |
83 | #. VIDIOC_S_EXT_CTRLS | |
84 | #. VIDIOC_S_FMT | |
85 | #. VIDIOC_REQBUFS(n) | |
86 | #. VIDIOC_QBUF | |
87 | #. VIDIOC_STREAMON | |
88 | ||
89 | The second :c:func:`VIDIOC_REQBUFS` call will take the new format and control | |
90 | value into account to compute the buffer size to allocate. Applications can | |
91 | also retrieve the size by calling the :c:func:`VIDIOC_G_FMT` ioctl if needed. | |
92 | ||
93 | .. note:: | |
94 | ||
95 | The API doesn't mandate the above order for control (3.) and format (4.) | |
96 | changes. Format and controls can be set in a different order, or even | |
97 | interleaved, depending on the device and use case. For instance some | |
98 | controls might behave differently for different pixel formats, in which | |
99 | case the format might need to be set first. | |
100 | ||
101 | When reallocation is required, any attempt to modify format or controls that | |
102 | influences the buffer size while buffers are allocated shall cause the format | |
103 | or control set ioctl to return the ``EBUSY`` error. Any attempt to queue a | |
104 | buffer too small for the current format or controls shall cause the | |
105 | :c:func:`VIDIOC_QBUF` ioctl to return a ``EINVAL`` error. | |
106 | ||
107 | Buffer reallocation is an expensive operation. To avoid that cost, drivers can | |
108 | (and are encouraged to) allow format or controls that influence the buffer | |
109 | size to be changed with buffers allocated. In that case, a typical ioctl | |
110 | sequence to modify format and controls is | |
111 | ||
112 | #. VIDIOC_STREAMOFF | |
113 | #. VIDIOC_S_EXT_CTRLS | |
114 | #. VIDIOC_S_FMT | |
115 | #. VIDIOC_QBUF | |
116 | #. VIDIOC_STREAMON | |
117 | ||
118 | For this sequence to operate correctly, queued buffers need to be large enough | |
119 | for the new format or controls. Drivers shall return a ``ENOSPC`` error in | |
120 | response to format change (:c:func:`VIDIOC_S_FMT`) or control changes | |
121 | (:c:func:`VIDIOC_S_CTRL` or :c:func:`VIDIOC_S_EXT_CTRLS`) if buffers too small | |
122 | for the new format are currently queued. As a simplification, drivers are | |
123 | allowed to return a ``EBUSY`` error from these ioctls if any buffer is | |
124 | currently queued, without checking the queued buffers sizes. | |
125 | ||
126 | Additionally, drivers shall return a ``EINVAL`` error from the | |
127 | :c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the | |
128 | current format or controls. Together, these requirements ensure that queued | |
129 | buffers will always be large enough for the configured format and controls. | |
130 | ||
131 | Userspace applications can query the buffer size required for a given format | |
132 | and controls by first setting the desired control values and then trying the | |
133 | desired format. The :c:func:`VIDIOC_TRY_FMT` ioctl will return the required | |
134 | buffer size. | |
135 | ||
136 | #. VIDIOC_S_EXT_CTRLS(x) | |
137 | #. VIDIOC_TRY_FMT() | |
138 | #. VIDIOC_S_EXT_CTRLS(y) | |
139 | #. VIDIOC_TRY_FMT() | |
140 | ||
141 | The :c:func:`VIDIOC_CREATE_BUFS` ioctl can then be used to allocate buffers | |
142 | based on the queried sizes (for instance by allocating a set of buffers large | |
143 | enough for all the desired formats and controls, or by allocating separate set | |
144 | of appropriately sized buffers for each use case). | |
145 | ||
146 | ||
e8be7e97 | 147 | .. c:type:: v4l2_buffer |
5377d91f | 148 | |
90865d29 MCC |
149 | struct v4l2_buffer |
150 | ================== | |
151 | ||
43e4138b | 152 | .. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.3cm}|p{10.5cm}| |
8b5efbeb MCC |
153 | |
154 | .. cssclass:: longtable | |
5bd4bb78 | 155 | |
5377d91f MH |
156 | .. flat-table:: struct v4l2_buffer |
157 | :header-rows: 0 | |
158 | :stub-columns: 0 | |
8b5efbeb | 159 | :widths: 1 2 1 10 |
5377d91f | 160 | |
c2b66caf LP |
161 | * - __u32 |
162 | - ``index`` | |
163 | - | |
164 | - Number of the buffer, set by the application except when calling | |
165 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the | |
166 | driver. This field can range from zero to the number of buffers | |
167 | allocated with the :ref:`VIDIOC_REQBUFS` ioctl | |
168 | (struct :c:type:`v4l2_requestbuffers` | |
169 | ``count``), plus any buffers allocated with | |
170 | :ref:`VIDIOC_CREATE_BUFS` minus one. | |
171 | * - __u32 | |
172 | - ``type`` | |
173 | - | |
174 | - Type of the buffer, same as struct | |
175 | :c:type:`v4l2_format` ``type`` or struct | |
176 | :c:type:`v4l2_requestbuffers` ``type``, set | |
177 | by the application. See :c:type:`v4l2_buf_type` | |
178 | * - __u32 | |
179 | - ``bytesused`` | |
180 | - | |
181 | - The number of bytes occupied by the data in the buffer. It depends | |
182 | on the negotiated data format and may change with each buffer for | |
183 | compressed variable size data like JPEG images. Drivers must set | |
184 | this field when ``type`` refers to a capture stream, applications | |
185 | when it refers to an output stream. If the application sets this | |
186 | to 0 for an output stream, then ``bytesused`` will be set to the | |
187 | size of the buffer (see the ``length`` field of this struct) by | |
188 | the driver. For multiplanar formats this field is ignored and the | |
189 | ``planes`` pointer is used instead. | |
190 | * - __u32 | |
191 | - ``flags`` | |
192 | - | |
193 | - Flags set by the application or driver, see :ref:`buffer-flags`. | |
194 | * - __u32 | |
195 | - ``field`` | |
196 | - | |
197 | - Indicates the field order of the image in the buffer, see | |
198 | :c:type:`v4l2_field`. This field is not used when the buffer | |
199 | contains VBI data. Drivers must set it when ``type`` refers to a | |
200 | capture stream, applications when it refers to an output stream. | |
201 | * - struct timeval | |
202 | - ``timestamp`` | |
203 | - | |
204 | - For capture streams this is time when the first data byte was | |
205 | captured, as returned by the :c:func:`clock_gettime()` function | |
206 | for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in | |
207 | :ref:`buffer-flags`. For output streams the driver stores the | |
208 | time at which the last data byte was actually sent out in the | |
209 | ``timestamp`` field. This permits applications to monitor the | |
210 | drift between the video and system clock. For output streams that | |
211 | use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill | |
212 | in the timestamp which will be copied by the driver to the capture | |
213 | stream. | |
214 | * - struct :c:type:`v4l2_timecode` | |
215 | - ``timecode`` | |
216 | - | |
217 | - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the | |
218 | ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this | |
219 | structure contains a frame timecode. In | |
220 | :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and | |
221 | bottom field contain the same timecode. Timecodes are intended to | |
222 | help video editing and are typically recorded on video tapes, but | |
223 | also embedded in compressed formats like MPEG. This field is | |
224 | independent of the ``timestamp`` and ``sequence`` fields. | |
225 | * - __u32 | |
226 | - ``sequence`` | |
227 | - | |
228 | - Set by the driver, counting the frames (not fields!) in sequence. | |
229 | This field is set for both input and output devices. | |
230 | * - :cspan:`3` | |
231 | ||
232 | In :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and | |
233 | bottom field have the same sequence number. The count starts at | |
234 | zero and includes dropped or repeated frames. A dropped frame was | |
235 | received by an input device but could not be stored due to lack of | |
236 | free buffer space. A repeated frame was displayed again by an | |
237 | output device because the application did not pass new data in | |
238 | time. | |
239 | ||
240 | .. note:: | |
241 | ||
242 | This may count the frames received e.g. over USB, without | |
243 | taking into account the frames dropped by the remote hardware due | |
244 | to limited compression throughput or bus bandwidth. These devices | |
245 | identify by not enumerating any video standards, see | |
246 | :ref:`standard`. | |
247 | ||
248 | * - __u32 | |
249 | - ``memory`` | |
250 | - | |
251 | - This field must be set by applications and/or drivers in | |
252 | accordance with the selected I/O method. See :c:type:`v4l2_memory` | |
253 | * - union | |
254 | - ``m`` | |
255 | * - | |
256 | - __u32 | |
257 | - ``offset`` | |
258 | - For the single-planar API and when ``memory`` is | |
259 | ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the | |
260 | start of the device memory. The value is returned by the driver | |
261 | and apart of serving as parameter to the | |
262 | :ref:`mmap() <func-mmap>` function not useful for applications. | |
263 | See :ref:`mmap` for details | |
264 | * - | |
265 | - unsigned long | |
266 | - ``userptr`` | |
267 | - For the single-planar API and when ``memory`` is | |
268 | ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to | |
269 | unsigned long type) in virtual memory, set by the application. See | |
270 | :ref:`userp` for details. | |
271 | * - | |
272 | - struct v4l2_plane | |
273 | - ``*planes`` | |
274 | - When using the multi-planar API, contains a userspace pointer to | |
275 | an array of struct :c:type:`v4l2_plane`. The size of | |
276 | the array should be put in the ``length`` field of this | |
277 | struct :c:type:`v4l2_buffer` structure. | |
278 | * - | |
279 | - int | |
280 | - ``fd`` | |
281 | - For the single-plane API and when ``memory`` is | |
282 | ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with | |
283 | a DMABUF buffer. | |
284 | * - __u32 | |
285 | - ``length`` | |
286 | - | |
287 | - Size of the buffer (not the payload) in bytes for the | |
288 | single-planar API. This is set by the driver based on the calls to | |
289 | :ref:`VIDIOC_REQBUFS` and/or | |
290 | :ref:`VIDIOC_CREATE_BUFS`. For the | |
291 | multi-planar API the application sets this to the number of | |
292 | elements in the ``planes`` array. The driver will fill in the | |
293 | actual number of valid elements in that array. | |
294 | * - __u32 | |
295 | - ``reserved2`` | |
296 | - | |
297 | - A place holder for future extensions. Drivers and applications | |
298 | must set this to 0. | |
299 | * - __u32 | |
300 | - ``reserved`` | |
301 | - | |
302 | - A place holder for future extensions. Drivers and applications | |
303 | must set this to 0. | |
5377d91f MH |
304 | |
305 | ||
306 | ||
e8be7e97 | 307 | .. c:type:: v4l2_plane |
5377d91f | 308 | |
90865d29 MCC |
309 | struct v4l2_plane |
310 | ================= | |
311 | ||
5bd4bb78 MCC |
312 | .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| |
313 | ||
8b5efbeb MCC |
314 | .. cssclass:: longtable |
315 | ||
90865d29 | 316 | .. flat-table:: |
5377d91f MH |
317 | :header-rows: 0 |
318 | :stub-columns: 0 | |
319 | :widths: 1 1 1 2 | |
320 | ||
c2b66caf LP |
321 | * - __u32 |
322 | - ``bytesused`` | |
323 | - | |
324 | - The number of bytes occupied by data in the plane (its payload). | |
325 | Drivers must set this field when ``type`` refers to a capture | |
326 | stream, applications when it refers to an output stream. If the | |
327 | application sets this to 0 for an output stream, then | |
328 | ``bytesused`` will be set to the size of the plane (see the | |
329 | ``length`` field of this struct) by the driver. | |
330 | ||
331 | .. note:: | |
332 | ||
333 | Note that the actual image data starts at ``data_offset`` | |
334 | which may not be 0. | |
335 | * - __u32 | |
336 | - ``length`` | |
337 | - | |
338 | - Size in bytes of the plane (not its payload). This is set by the | |
339 | driver based on the calls to | |
340 | :ref:`VIDIOC_REQBUFS` and/or | |
341 | :ref:`VIDIOC_CREATE_BUFS`. | |
342 | * - union | |
343 | - ``m`` | |
344 | - | |
345 | - | |
346 | * - | |
347 | - __u32 | |
348 | - ``mem_offset`` | |
349 | - When the memory type in the containing struct | |
350 | :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this | |
351 | is the value that should be passed to :ref:`mmap() <func-mmap>`, | |
352 | similar to the ``offset`` field in struct | |
353 | :c:type:`v4l2_buffer`. | |
354 | * - | |
355 | - unsigned long | |
356 | - ``userptr`` | |
357 | - When the memory type in the containing struct | |
358 | :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``, | |
359 | this is a userspace pointer to the memory allocated for this plane | |
360 | by an application. | |
361 | * - | |
362 | - int | |
363 | - ``fd`` | |
364 | - When the memory type in the containing struct | |
365 | :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``, | |
366 | this is a file descriptor associated with a DMABUF buffer, similar | |
367 | to the ``fd`` field in struct :c:type:`v4l2_buffer`. | |
368 | * - __u32 | |
369 | - ``data_offset`` | |
370 | - | |
371 | - Offset in bytes to video data in the plane. Drivers must set this | |
372 | field when ``type`` refers to a capture stream, applications when | |
373 | it refers to an output stream. | |
374 | ||
375 | .. note:: | |
376 | ||
377 | That data_offset is included in ``bytesused``. So the | |
378 | size of the image in the plane is ``bytesused``-``data_offset`` | |
379 | at offset ``data_offset`` from the start of the plane. | |
380 | * - __u32 | |
381 | - ``reserved[11]`` | |
382 | - | |
383 | - Reserved for future use. Should be zeroed by drivers and | |
384 | applications. | |
5377d91f MH |
385 | |
386 | ||
387 | ||
56683d7d | 388 | .. c:type:: v4l2_buf_type |
5377d91f | 389 | |
90865d29 MCC |
390 | enum v4l2_buf_type |
391 | ================== | |
392 | ||
8b5efbeb MCC |
393 | .. cssclass:: longtable |
394 | ||
395 | .. tabularcolumns:: |p{7.2cm}|p{0.6cm}|p{9.7cm}| | |
5bd4bb78 | 396 | |
90865d29 | 397 | .. flat-table:: |
5377d91f MH |
398 | :header-rows: 0 |
399 | :stub-columns: 0 | |
8b5efbeb | 400 | :widths: 4 1 9 |
5377d91f | 401 | |
c2b66caf LP |
402 | * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` |
403 | - 1 | |
404 | - Buffer of a single-planar video capture stream, see | |
405 | :ref:`capture`. | |
406 | * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` | |
407 | - 9 | |
408 | - Buffer of a multi-planar video capture stream, see | |
409 | :ref:`capture`. | |
410 | * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` | |
411 | - 2 | |
412 | - Buffer of a single-planar video output stream, see | |
413 | :ref:`output`. | |
414 | * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` | |
415 | - 10 | |
416 | - Buffer of a multi-planar video output stream, see :ref:`output`. | |
417 | * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` | |
418 | - 3 | |
419 | - Buffer for video overlay, see :ref:`overlay`. | |
420 | * - ``V4L2_BUF_TYPE_VBI_CAPTURE`` | |
421 | - 4 | |
422 | - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`. | |
423 | * - ``V4L2_BUF_TYPE_VBI_OUTPUT`` | |
424 | - 5 | |
425 | - Buffer of a raw VBI output stream, see :ref:`raw-vbi`. | |
426 | * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` | |
427 | - 6 | |
428 | - Buffer of a sliced VBI capture stream, see :ref:`sliced`. | |
429 | * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` | |
430 | - 7 | |
431 | - Buffer of a sliced VBI output stream, see :ref:`sliced`. | |
432 | * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` | |
433 | - 8 | |
434 | - Buffer for video output overlay (OSD), see :ref:`osd`. | |
435 | * - ``V4L2_BUF_TYPE_SDR_CAPTURE`` | |
436 | - 11 | |
437 | - Buffer for Software Defined Radio (SDR) capture stream, see | |
438 | :ref:`sdr`. | |
439 | * - ``V4L2_BUF_TYPE_SDR_OUTPUT`` | |
440 | - 12 | |
441 | - Buffer for Software Defined Radio (SDR) output stream, see | |
442 | :ref:`sdr`. | |
5377d91f MH |
443 | |
444 | ||
445 | ||
446 | .. _buffer-flags: | |
447 | ||
90865d29 MCC |
448 | Buffer Flags |
449 | ============ | |
450 | ||
8b5efbeb MCC |
451 | .. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}| |
452 | ||
453 | .. cssclass:: longtable | |
5bd4bb78 | 454 | |
90865d29 | 455 | .. flat-table:: |
5377d91f MH |
456 | :header-rows: 0 |
457 | :stub-columns: 0 | |
458 | :widths: 3 1 4 | |
459 | ||
c2b66caf LP |
460 | * .. _`V4L2-BUF-FLAG-MAPPED`: |
461 | ||
462 | - ``V4L2_BUF_FLAG_MAPPED`` | |
463 | - 0x00000001 | |
464 | - The buffer resides in device memory and has been mapped into the | |
465 | application's address space, see :ref:`mmap` for details. | |
466 | Drivers set or clear this flag when the | |
467 | :ref:`VIDIOC_QUERYBUF`, | |
468 | :ref:`VIDIOC_QBUF` or | |
469 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the | |
470 | driver. | |
471 | * .. _`V4L2-BUF-FLAG-QUEUED`: | |
472 | ||
473 | - ``V4L2_BUF_FLAG_QUEUED`` | |
474 | - 0x00000002 | |
475 | - Internally drivers maintain two buffer queues, an incoming and | |
476 | outgoing queue. When this flag is set, the buffer is currently on | |
477 | the incoming queue. It automatically moves to the outgoing queue | |
478 | after the buffer has been filled (capture devices) or displayed | |
479 | (output devices). Drivers set or clear this flag when the | |
480 | ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling | |
481 | the ``VIDIOC_QBUF``\ ioctl it is always set and after | |
482 | ``VIDIOC_DQBUF`` always cleared. | |
483 | * .. _`V4L2-BUF-FLAG-DONE`: | |
484 | ||
485 | - ``V4L2_BUF_FLAG_DONE`` | |
486 | - 0x00000004 | |
487 | - When this flag is set, the buffer is currently on the outgoing | |
488 | queue, ready to be dequeued from the driver. Drivers set or clear | |
489 | this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After | |
490 | calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always | |
491 | cleared. Of course a buffer cannot be on both queues at the same | |
492 | time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag | |
493 | are mutually exclusive. They can be both cleared however, then the | |
494 | buffer is in "dequeued" state, in the application domain so to | |
495 | say. | |
496 | * .. _`V4L2-BUF-FLAG-ERROR`: | |
497 | ||
498 | - ``V4L2_BUF_FLAG_ERROR`` | |
499 | - 0x00000040 | |
500 | - When this flag is set, the buffer has been dequeued successfully, | |
501 | although the data might have been corrupted. This is recoverable, | |
502 | streaming may continue as normal and the buffer may be reused | |
503 | normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is | |
504 | called. | |
505 | * .. _`V4L2-BUF-FLAG-KEYFRAME`: | |
506 | ||
507 | - ``V4L2_BUF_FLAG_KEYFRAME`` | |
508 | - 0x00000008 | |
509 | - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF`` | |
510 | ioctl. It may be set by video capture devices when the buffer | |
511 | contains a compressed image which is a key frame (or field), i. e. | |
512 | can be decompressed on its own. Also known as an I-frame. | |
513 | Applications can set this bit when ``type`` refers to an output | |
514 | stream. | |
515 | * .. _`V4L2-BUF-FLAG-PFRAME`: | |
516 | ||
517 | - ``V4L2_BUF_FLAG_PFRAME`` | |
518 | - 0x00000010 | |
519 | - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames | |
520 | or fields which contain only differences to a previous key frame. | |
521 | Applications can set this bit when ``type`` refers to an output | |
522 | stream. | |
523 | * .. _`V4L2-BUF-FLAG-BFRAME`: | |
524 | ||
525 | - ``V4L2_BUF_FLAG_BFRAME`` | |
526 | - 0x00000020 | |
527 | - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional | |
528 | predicted frame or field which contains only the differences | |
529 | between the current frame and both the preceding and following key | |
530 | frames to specify its content. Applications can set this bit when | |
531 | ``type`` refers to an output stream. | |
532 | * .. _`V4L2-BUF-FLAG-TIMECODE`: | |
533 | ||
534 | - ``V4L2_BUF_FLAG_TIMECODE`` | |
535 | - 0x00000100 | |
536 | - The ``timecode`` field is valid. Drivers set or clear this flag | |
537 | when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set | |
538 | this bit and the corresponding ``timecode`` structure when | |
539 | ``type`` refers to an output stream. | |
540 | * .. _`V4L2-BUF-FLAG-PREPARED`: | |
541 | ||
542 | - ``V4L2_BUF_FLAG_PREPARED`` | |
543 | - 0x00000400 | |
544 | - The buffer has been prepared for I/O and can be queued by the | |
545 | application. Drivers set or clear this flag when the | |
546 | :ref:`VIDIOC_QUERYBUF`, | |
547 | :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`, | |
548 | :ref:`VIDIOC_QBUF` or | |
549 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. | |
550 | * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: | |
551 | ||
552 | - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` | |
553 | - 0x00000800 | |
554 | - Caches do not have to be invalidated for this buffer. Typically | |
555 | applications shall use this flag if the data captured in the | |
556 | buffer is not going to be touched by the CPU, instead the buffer | |
557 | will, probably, be passed on to a DMA-capable hardware unit for | |
558 | further processing or output. | |
559 | * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`: | |
560 | ||
561 | - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` | |
562 | - 0x00001000 | |
563 | - Caches do not have to be cleaned for this buffer. Typically | |
564 | applications shall use this flag for output buffers if the data in | |
565 | this buffer has not been created by the CPU but by some | |
566 | DMA-capable unit, in which case caches have not been used. | |
567 | * .. _`V4L2-BUF-FLAG-LAST`: | |
568 | ||
569 | - ``V4L2_BUF_FLAG_LAST`` | |
570 | - 0x00100000 | |
571 | - Last buffer produced by the hardware. mem2mem codec drivers set | |
572 | this flag on the capture queue for the last buffer when the | |
573 | :ref:`VIDIOC_QUERYBUF` or | |
574 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to | |
575 | hardware limitations, the last buffer may be empty. In this case | |
576 | the driver will set the ``bytesused`` field to 0, regardless of | |
577 | the format. Any Any subsequent call to the | |
578 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, | |
579 | but return an ``EPIPE`` error code. | |
580 | * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`: | |
581 | ||
582 | - ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` | |
583 | - 0x0000e000 | |
584 | - Mask for timestamp types below. To test the timestamp type, mask | |
585 | out bits not belonging to timestamp type by performing a logical | |
586 | and operation with buffer flags and timestamp mask. | |
587 | * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`: | |
588 | ||
589 | - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN`` | |
590 | - 0x00000000 | |
591 | - Unknown timestamp type. This type is used by drivers before Linux | |
592 | 3.9 and may be either monotonic (see below) or realtime (wall | |
593 | clock). Monotonic clock has been favoured in embedded systems | |
594 | whereas most of the drivers use the realtime clock. Either kinds | |
595 | of timestamps are available in user space via | |
596 | :c:func:`clock_gettime` using clock IDs ``CLOCK_MONOTONIC`` | |
597 | and ``CLOCK_REALTIME``, respectively. | |
598 | * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`: | |
599 | ||
600 | - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC`` | |
601 | - 0x00002000 | |
602 | - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC`` | |
603 | clock. To access the same clock outside V4L2, use | |
604 | :c:func:`clock_gettime`. | |
605 | * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`: | |
606 | ||
607 | - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` | |
608 | - 0x00004000 | |
609 | - The CAPTURE buffer timestamp has been taken from the corresponding | |
610 | OUTPUT buffer. This flag applies only to mem2mem devices. | |
611 | * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`: | |
612 | ||
613 | - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` | |
614 | - 0x00070000 | |
615 | - Mask for timestamp sources below. The timestamp source defines the | |
616 | point of time the timestamp is taken in relation to the frame. | |
617 | Logical 'and' operation between the ``flags`` field and | |
618 | ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the | |
619 | timestamp source. Applications must set the timestamp source when | |
620 | ``type`` refers to an output stream and | |
621 | ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set. | |
622 | * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`: | |
623 | ||
624 | - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF`` | |
625 | - 0x00000000 | |
626 | - End Of Frame. The buffer timestamp has been taken when the last | |
627 | pixel of the frame has been received or the last pixel of the | |
628 | frame has been transmitted. In practice, software generated | |
629 | timestamps will typically be read from the clock a small amount of | |
630 | time after the last pixel has been received or transmitten, | |
631 | depending on the system and other activity in it. | |
632 | * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`: | |
633 | ||
634 | - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE`` | |
635 | - 0x00010000 | |
636 | - Start Of Exposure. The buffer timestamp has been taken when the | |
637 | exposure of the frame has begun. This is only valid for the | |
638 | ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. | |
5377d91f MH |
639 | |
640 | ||
641 | ||
56683d7d | 642 | .. c:type:: v4l2_memory |
5377d91f | 643 | |
90865d29 MCC |
644 | enum v4l2_memory |
645 | ================ | |
646 | ||
5bd4bb78 MCC |
647 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
648 | ||
90865d29 | 649 | .. flat-table:: |
5377d91f MH |
650 | :header-rows: 0 |
651 | :stub-columns: 0 | |
652 | :widths: 3 1 4 | |
653 | ||
c2b66caf LP |
654 | * - ``V4L2_MEMORY_MMAP`` |
655 | - 1 | |
656 | - The buffer is used for :ref:`memory mapping <mmap>` I/O. | |
657 | * - ``V4L2_MEMORY_USERPTR`` | |
658 | - 2 | |
659 | - The buffer is used for :ref:`user pointer <userp>` I/O. | |
660 | * - ``V4L2_MEMORY_OVERLAY`` | |
661 | - 3 | |
662 | - [to do] | |
663 | * - ``V4L2_MEMORY_DMABUF`` | |
664 | - 4 | |
665 | - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O. | |
5377d91f MH |
666 | |
667 | ||
668 | ||
669 | Timecodes | |
670 | ========= | |
671 | ||
fc78c7c7 | 672 | The struct :c:type:`v4l2_timecode` structure is designed to hold a |
5377d91f | 673 | :ref:`smpte12m` or similar timecode. (struct |
a17a954e | 674 | struct :c:type:`timeval` timestamps are stored in struct |
e8be7e97 | 675 | :c:type:`v4l2_buffer` field ``timestamp``.) |
5377d91f MH |
676 | |
677 | ||
e8be7e97 | 678 | .. c:type:: v4l2_timecode |
5377d91f | 679 | |
90865d29 MCC |
680 | struct v4l2_timecode |
681 | -------------------- | |
682 | ||
5bd4bb78 MCC |
683 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
684 | ||
90865d29 | 685 | .. flat-table:: |
5377d91f MH |
686 | :header-rows: 0 |
687 | :stub-columns: 0 | |
688 | :widths: 1 1 2 | |
689 | ||
c2b66caf LP |
690 | * - __u32 |
691 | - ``type`` | |
692 | - Frame rate the timecodes are based on, see :ref:`timecode-type`. | |
693 | * - __u32 | |
694 | - ``flags`` | |
695 | - Timecode flags, see :ref:`timecode-flags`. | |
696 | * - __u8 | |
697 | - ``frames`` | |
698 | - Frame count, 0 ... 23/24/29/49/59, depending on the type of | |
699 | timecode. | |
700 | * - __u8 | |
701 | - ``seconds`` | |
702 | - Seconds count, 0 ... 59. This is a binary, not BCD number. | |
703 | * - __u8 | |
704 | - ``minutes`` | |
705 | - Minutes count, 0 ... 59. This is a binary, not BCD number. | |
706 | * - __u8 | |
707 | - ``hours`` | |
708 | - Hours count, 0 ... 29. This is a binary, not BCD number. | |
709 | * - __u8 | |
710 | - ``userbits``\ [4] | |
711 | - The "user group" bits from the timecode. | |
5377d91f MH |
712 | |
713 | ||
714 | ||
715 | .. _timecode-type: | |
716 | ||
90865d29 MCC |
717 | Timecode Types |
718 | -------------- | |
719 | ||
5bd4bb78 MCC |
720 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
721 | ||
90865d29 | 722 | .. flat-table:: |
5377d91f MH |
723 | :header-rows: 0 |
724 | :stub-columns: 0 | |
725 | :widths: 3 1 4 | |
726 | ||
c2b66caf LP |
727 | * - ``V4L2_TC_TYPE_24FPS`` |
728 | - 1 | |
729 | - 24 frames per second, i. e. film. | |
730 | * - ``V4L2_TC_TYPE_25FPS`` | |
731 | - 2 | |
732 | - 25 frames per second, i. e. PAL or SECAM video. | |
733 | * - ``V4L2_TC_TYPE_30FPS`` | |
734 | - 3 | |
735 | - 30 frames per second, i. e. NTSC video. | |
736 | * - ``V4L2_TC_TYPE_50FPS`` | |
737 | - 4 | |
738 | - | |
739 | * - ``V4L2_TC_TYPE_60FPS`` | |
740 | - 5 | |
741 | - | |
5377d91f MH |
742 | |
743 | ||
744 | ||
745 | .. _timecode-flags: | |
746 | ||
90865d29 MCC |
747 | Timecode Flags |
748 | -------------- | |
749 | ||
8b5efbeb | 750 | .. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}| |
5bd4bb78 | 751 | |
90865d29 | 752 | .. flat-table:: |
5377d91f MH |
753 | :header-rows: 0 |
754 | :stub-columns: 0 | |
755 | :widths: 3 1 4 | |
756 | ||
c2b66caf LP |
757 | * - ``V4L2_TC_FLAG_DROPFRAME`` |
758 | - 0x0001 | |
759 | - Indicates "drop frame" semantics for counting frames in 29.97 fps | |
760 | material. When set, frame numbers 0 and 1 at the start of each | |
761 | minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the | |
762 | count. | |
763 | * - ``V4L2_TC_FLAG_COLORFRAME`` | |
764 | - 0x0002 | |
765 | - The "color frame" flag. | |
766 | * - ``V4L2_TC_USERBITS_field`` | |
767 | - 0x000C | |
768 | - Field mask for the "binary group flags". | |
769 | * - ``V4L2_TC_USERBITS_USERDEFINED`` | |
770 | - 0x0000 | |
771 | - Unspecified format. | |
772 | * - ``V4L2_TC_USERBITS_8BITCHARS`` | |
773 | - 0x0008 | |
774 | - 8-bit ISO characters. |