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