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