0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _buffer:
0005
0006 *******
0007 Buffers
0008 *******
0009
0010 A buffer contains data exchanged by application and driver using one of
0011 the Streaming I/O methods. In the multi-planar API, the data is held in
0012 planes, while the buffer structure acts as a container for the planes.
0013 Only pointers to buffers (planes) are exchanged, the data itself is not
0014 copied. These pointers, together with meta-information like timestamps
0015 or field parity, are stored in a struct :c:type:`v4l2_buffer`,
0016 argument to the :ref:`VIDIOC_QUERYBUF`,
0017 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and
0018 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API,
0019 some plane-specific members of struct :c:type:`v4l2_buffer`,
0020 such as pointers and sizes for each plane, are stored in
0021 struct :c:type:`v4l2_plane` instead. In that case,
0022 struct :c:type:`v4l2_buffer` contains an array of plane structures.
0023
0024 Dequeued video buffers come with timestamps. The driver decides at which
0025 part of the frame and with which clock the timestamp is taken. Please
0026 see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and
0027 ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags
0028 are always valid and constant across all buffers during the whole video
0029 stream. Changes in these flags may take place as a side effect of
0030 :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or
0031 :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The
0032 ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on
0033 mem-to-mem devices is an exception to the rule: the timestamp source
0034 flags are copied from the OUTPUT video buffer to the CAPTURE video
0035 buffer.
0036
0037 Interactions between formats, controls and buffers
0038 ==================================================
0039
0040 V4L2 exposes parameters that influence the buffer size, or the way data is
0041 laid out in the buffer. Those parameters are exposed through both formats and
0042 controls. One example of such a control is the ``V4L2_CID_ROTATE`` control
0043 that modifies the direction in which pixels are stored in the buffer, as well
0044 as the buffer size when the selected format includes padding at the end of
0045 lines.
0046
0047 The set of information needed to interpret the content of a buffer (e.g. the
0048 pixel format, the line stride, the tiling orientation or the rotation) is
0049 collectively referred to in the rest of this section as the buffer layout.
0050
0051 Controls that can modify the buffer layout shall set the
0052 ``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag.
0053
0054 Modifying formats or controls that influence the buffer size or layout require
0055 the stream to be stopped. Any attempt at such a modification while the stream
0056 is active shall cause the ioctl setting the format or the control to return
0057 the ``EBUSY`` error code. In that case drivers shall also set the
0058 ``V4L2_CTRL_FLAG_GRABBED`` flag when calling
0059 :c:func:`VIDIOC_QUERYCTRL` or :c:func:`VIDIOC_QUERY_EXT_CTRL` for such a
0060 control while the stream is active.
0061
0062 .. note::
0063
0064 The :c:func:`VIDIOC_S_SELECTION` ioctl can, depending on the hardware (for
0065 instance if the device doesn't include a scaler), modify the format in
0066 addition to the selection rectangle. Similarly, the
0067 :c:func:`VIDIOC_S_INPUT`, :c:func:`VIDIOC_S_OUTPUT`, :c:func:`VIDIOC_S_STD`
0068 and :c:func:`VIDIOC_S_DV_TIMINGS` ioctls can also modify the format and
0069 selection rectangles. When those ioctls result in a buffer size or layout
0070 change, drivers shall handle that condition as they would handle it in the
0071 :c:func:`VIDIOC_S_FMT` ioctl in all cases described in this section.
0072
0073 Controls that only influence the buffer layout can be modified at any time
0074 when the stream is stopped. As they don't influence the buffer size, no
0075 special handling is needed to synchronize those controls with buffer
0076 allocation and the ``V4L2_CTRL_FLAG_GRABBED`` flag is cleared once the
0077 stream is stopped.
0078
0079 Formats and controls that influence the buffer size interact with buffer
0080 allocation. The simplest way to handle this is for drivers to always require
0081 buffers to be reallocated in order to change those formats or controls. In
0082 that case, to perform such changes, userspace applications shall first stop
0083 the video stream with the :c:func:`VIDIOC_STREAMOFF` ioctl if it is running
0084 and free all buffers with the :c:func:`VIDIOC_REQBUFS` ioctl if they are
0085 allocated. After freeing all buffers the ``V4L2_CTRL_FLAG_GRABBED`` flag
0086 for controls is cleared. The format or controls can then be modified, and
0087 buffers shall then be reallocated and the stream restarted. A typical ioctl
0088 sequence is
0089
0090 #. VIDIOC_STREAMOFF
0091 #. VIDIOC_REQBUFS(0)
0092 #. VIDIOC_S_EXT_CTRLS
0093 #. VIDIOC_S_FMT
0094 #. VIDIOC_REQBUFS(n)
0095 #. VIDIOC_QBUF
0096 #. VIDIOC_STREAMON
0097
0098 The second :c:func:`VIDIOC_REQBUFS` call will take the new format and control
0099 value into account to compute the buffer size to allocate. Applications can
0100 also retrieve the size by calling the :c:func:`VIDIOC_G_FMT` ioctl if needed.
0101
0102 .. note::
0103
0104 The API doesn't mandate the above order for control (3.) and format (4.)
0105 changes. Format and controls can be set in a different order, or even
0106 interleaved, depending on the device and use case. For instance some
0107 controls might behave differently for different pixel formats, in which
0108 case the format might need to be set first.
0109
0110 When reallocation is required, any attempt to modify format or controls that
0111 influences the buffer size while buffers are allocated shall cause the format
0112 or control set ioctl to return the ``EBUSY`` error. Any attempt to queue a
0113 buffer too small for the current format or controls shall cause the
0114 :c:func:`VIDIOC_QBUF` ioctl to return a ``EINVAL`` error.
0115
0116 Buffer reallocation is an expensive operation. To avoid that cost, drivers can
0117 (and are encouraged to) allow format or controls that influence the buffer
0118 size to be changed with buffers allocated. In that case, a typical ioctl
0119 sequence to modify format and controls is
0120
0121 #. VIDIOC_STREAMOFF
0122 #. VIDIOC_S_EXT_CTRLS
0123 #. VIDIOC_S_FMT
0124 #. VIDIOC_QBUF
0125 #. VIDIOC_STREAMON
0126
0127 For this sequence to operate correctly, queued buffers need to be large enough
0128 for the new format or controls. Drivers shall return a ``ENOSPC`` error in
0129 response to format change (:c:func:`VIDIOC_S_FMT`) or control changes
0130 (:c:func:`VIDIOC_S_CTRL` or :c:func:`VIDIOC_S_EXT_CTRLS`) if buffers too small
0131 for the new format are currently queued. As a simplification, drivers are
0132 allowed to return a ``EBUSY`` error from these ioctls if any buffer is
0133 currently queued, without checking the queued buffers sizes.
0134
0135 Additionally, drivers shall return a ``EINVAL`` error from the
0136 :c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the
0137 current format or controls. Together, these requirements ensure that queued
0138 buffers will always be large enough for the configured format and controls.
0139
0140 Userspace applications can query the buffer size required for a given format
0141 and controls by first setting the desired control values and then trying the
0142 desired format. The :c:func:`VIDIOC_TRY_FMT` ioctl will return the required
0143 buffer size.
0144
0145 #. VIDIOC_S_EXT_CTRLS(x)
0146 #. VIDIOC_TRY_FMT()
0147 #. VIDIOC_S_EXT_CTRLS(y)
0148 #. VIDIOC_TRY_FMT()
0149
0150 The :c:func:`VIDIOC_CREATE_BUFS` ioctl can then be used to allocate buffers
0151 based on the queried sizes (for instance by allocating a set of buffers large
0152 enough for all the desired formats and controls, or by allocating separate set
0153 of appropriately sized buffers for each use case).
0154
0155 .. c:type:: v4l2_buffer
0156
0157 struct v4l2_buffer
0158 ==================
0159
0160 .. tabularcolumns:: |p{2.9cm}|p{2.4cm}|p{12.0cm}|
0161
0162 .. cssclass:: longtable
0163
0164 .. flat-table:: struct v4l2_buffer
0165 :header-rows: 0
0166 :stub-columns: 0
0167 :widths: 1 2 10
0168
0169 * - __u32
0170 - ``index``
0171 - Number of the buffer, set by the application except when calling
0172 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the
0173 driver. This field can range from zero to the number of buffers
0174 allocated with the :ref:`VIDIOC_REQBUFS` ioctl
0175 (struct :c:type:`v4l2_requestbuffers`
0176 ``count``), plus any buffers allocated with
0177 :ref:`VIDIOC_CREATE_BUFS` minus one.
0178 * - __u32
0179 - ``type``
0180 - Type of the buffer, same as struct
0181 :c:type:`v4l2_format` ``type`` or struct
0182 :c:type:`v4l2_requestbuffers` ``type``, set
0183 by the application. See :c:type:`v4l2_buf_type`
0184 * - __u32
0185 - ``bytesused``
0186 - The number of bytes occupied by the data in the buffer. It depends
0187 on the negotiated data format and may change with each buffer for
0188 compressed variable size data like JPEG images. Drivers must set
0189 this field when ``type`` refers to a capture stream, applications
0190 when it refers to an output stream. If the application sets this
0191 to 0 for an output stream, then ``bytesused`` will be set to the
0192 size of the buffer (see the ``length`` field of this struct) by
0193 the driver. For multiplanar formats this field is ignored and the
0194 ``planes`` pointer is used instead.
0195 * - __u32
0196 - ``flags``
0197 - Flags set by the application or driver, see :ref:`buffer-flags`.
0198 * - __u32
0199 - ``field``
0200 - Indicates the field order of the image in the buffer, see
0201 :c:type:`v4l2_field`. This field is not used when the buffer
0202 contains VBI data. Drivers must set it when ``type`` refers to a
0203 capture stream, applications when it refers to an output stream.
0204 * - struct timeval
0205 - ``timestamp``
0206 - For capture streams this is time when the first data byte was
0207 captured, as returned by the :c:func:`clock_gettime()` function
0208 for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in
0209 :ref:`buffer-flags`. For output streams the driver stores the
0210 time at which the last data byte was actually sent out in the
0211 ``timestamp`` field. This permits applications to monitor the
0212 drift between the video and system clock. For output streams that
0213 use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill
0214 in the timestamp which will be copied by the driver to the capture
0215 stream.
0216 * - struct :c:type:`v4l2_timecode`
0217 - ``timecode``
0218 - When the ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
0219 structure contains a frame timecode. In
0220 :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and
0221 bottom field contain the same timecode. Timecodes are intended to
0222 help video editing and are typically recorded on video tapes, but
0223 also embedded in compressed formats like MPEG. This field is
0224 independent of the ``timestamp`` and ``sequence`` fields.
0225 * - __u32
0226 - ``sequence``
0227 - Set by the driver, counting the frames (not fields!) in sequence.
0228 This field is set for both input and output devices.
0229 * - :cspan:`2`
0230
0231 In :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and
0232 bottom field have the same sequence number. The count starts at
0233 zero and includes dropped or repeated frames. A dropped frame was
0234 received by an input device but could not be stored due to lack of
0235 free buffer space. A repeated frame was displayed again by an
0236 output device because the application did not pass new data in
0237 time.
0238
0239 .. note::
0240
0241 This may count the frames received e.g. over USB, without
0242 taking into account the frames dropped by the remote hardware due
0243 to limited compression throughput or bus bandwidth. These devices
0244 identify by not enumerating any video standards, see
0245 :ref:`standard`.
0246
0247 * - __u32
0248 - ``memory``
0249 - This field must be set by applications and/or drivers in
0250 accordance with the selected I/O method. See :c:type:`v4l2_memory`
0251 * - union {
0252 - ``m``
0253 * - __u32
0254 - ``offset``
0255 - For the single-planar API and when ``memory`` is
0256 ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
0257 start of the device memory. The value is returned by the driver
0258 and apart of serving as parameter to the
0259 :c:func:`mmap()` function not useful for applications.
0260 See :ref:`mmap` for details
0261 * - unsigned long
0262 - ``userptr``
0263 - For the single-planar API and when ``memory`` is
0264 ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
0265 unsigned long type) in virtual memory, set by the application. See
0266 :ref:`userp` for details.
0267 * - struct v4l2_plane
0268 - ``*planes``
0269 - When using the multi-planar API, contains a userspace pointer to
0270 an array of struct :c:type:`v4l2_plane`. The size of
0271 the array should be put in the ``length`` field of this
0272 struct :c:type:`v4l2_buffer` structure.
0273 * - int
0274 - ``fd``
0275 - For the single-plane API and when ``memory`` is
0276 ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with
0277 a DMABUF buffer.
0278 * - }
0279 -
0280 * - __u32
0281 - ``length``
0282 - Size of the buffer (not the payload) in bytes for the
0283 single-planar API. This is set by the driver based on the calls to
0284 :ref:`VIDIOC_REQBUFS` and/or
0285 :ref:`VIDIOC_CREATE_BUFS`. For the
0286 multi-planar API the application sets this to the number of
0287 elements in the ``planes`` array. The driver will fill in the
0288 actual number of valid elements in that array.
0289 * - __u32
0290 - ``reserved2``
0291 - A place holder for future extensions. Drivers and applications
0292 must set this to 0.
0293 * - __u32
0294 - ``request_fd``
0295 - The file descriptor of the request to queue the buffer to. If the flag
0296 ``V4L2_BUF_FLAG_REQUEST_FD`` is set, then the buffer will be
0297 queued to this request. If the flag is not set, then this field will
0298 be ignored.
0299
0300 The ``V4L2_BUF_FLAG_REQUEST_FD`` flag and this field are only used by
0301 :ref:`ioctl VIDIOC_QBUF <VIDIOC_QBUF>` and ignored by other ioctls that
0302 take a :c:type:`v4l2_buffer` as argument.
0303
0304 Applications should not set ``V4L2_BUF_FLAG_REQUEST_FD`` for any ioctls
0305 other than :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`.
0306
0307 If the device does not support requests, then ``EBADR`` will be returned.
0308 If requests are supported but an invalid request file descriptor is
0309 given, then ``EINVAL`` will be returned.
0310
0311
0312 .. c:type:: v4l2_plane
0313
0314 struct v4l2_plane
0315 =================
0316
0317 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{10.3cm}|
0318
0319 .. cssclass:: longtable
0320
0321 .. flat-table::
0322 :header-rows: 0
0323 :stub-columns: 0
0324 :widths: 1 1 2
0325
0326 * - __u32
0327 - ``bytesused``
0328 - The number of bytes occupied by data in the plane (its payload).
0329 Drivers must set this field when ``type`` refers to a capture
0330 stream, applications when it refers to an output stream. If the
0331 application sets this to 0 for an output stream, then
0332 ``bytesused`` will be set to the size of the plane (see the
0333 ``length`` field of this struct) by the driver.
0334
0335 .. note::
0336
0337 Note that the actual image data starts at ``data_offset``
0338 which may not be 0.
0339 * - __u32
0340 - ``length``
0341 - Size in bytes of the plane (not its payload). This is set by the
0342 driver based on the calls to
0343 :ref:`VIDIOC_REQBUFS` and/or
0344 :ref:`VIDIOC_CREATE_BUFS`.
0345 * - union {
0346 - ``m``
0347 * - __u32
0348 - ``mem_offset``
0349 - When the memory type in the containing struct
0350 :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this
0351 is the value that should be passed to :c:func:`mmap()`,
0352 similar to the ``offset`` field in struct
0353 :c:type:`v4l2_buffer`.
0354 * - unsigned long
0355 - ``userptr``
0356 - When the memory type in the containing struct
0357 :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``,
0358 this is a userspace pointer to the memory allocated for this plane
0359 by an application.
0360 * - int
0361 - ``fd``
0362 - When the memory type in the containing struct
0363 :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``,
0364 this is a file descriptor associated with a DMABUF buffer, similar
0365 to the ``fd`` field in struct :c:type:`v4l2_buffer`.
0366 * - }
0367 -
0368 * - __u32
0369 - ``data_offset``
0370 - Offset in bytes to video data in the plane. Drivers must set this
0371 field when ``type`` refers to a capture stream, applications when
0372 it refers to an output stream.
0373
0374 .. note::
0375
0376 That data_offset is included in ``bytesused``. So the
0377 size of the image in the plane is ``bytesused``-``data_offset``
0378 at offset ``data_offset`` from the start of the plane.
0379 * - __u32
0380 - ``reserved[11]``
0381 - Reserved for future use. Should be zeroed by drivers and
0382 applications.
0383
0384
0385 .. c:type:: v4l2_buf_type
0386
0387 enum v4l2_buf_type
0388 ==================
0389
0390 .. cssclass:: longtable
0391
0392 .. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{8.9cm}|
0393
0394 .. flat-table::
0395 :header-rows: 0
0396 :stub-columns: 0
0397 :widths: 4 1 9
0398
0399 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
0400 - 1
0401 - Buffer of a single-planar video capture stream, see
0402 :ref:`capture`.
0403 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
0404 - 9
0405 - Buffer of a multi-planar video capture stream, see
0406 :ref:`capture`.
0407 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
0408 - 2
0409 - Buffer of a single-planar video output stream, see
0410 :ref:`output`.
0411 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
0412 - 10
0413 - Buffer of a multi-planar video output stream, see :ref:`output`.
0414 * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
0415 - 3
0416 - Buffer for video overlay, see :ref:`overlay`.
0417 * - ``V4L2_BUF_TYPE_VBI_CAPTURE``
0418 - 4
0419 - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
0420 * - ``V4L2_BUF_TYPE_VBI_OUTPUT``
0421 - 5
0422 - Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
0423 * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
0424 - 6
0425 - Buffer of a sliced VBI capture stream, see :ref:`sliced`.
0426 * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
0427 - 7
0428 - Buffer of a sliced VBI output stream, see :ref:`sliced`.
0429 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
0430 - 8
0431 - Buffer for video output overlay (OSD), see :ref:`osd`.
0432 * - ``V4L2_BUF_TYPE_SDR_CAPTURE``
0433 - 11
0434 - Buffer for Software Defined Radio (SDR) capture stream, see
0435 :ref:`sdr`.
0436 * - ``V4L2_BUF_TYPE_SDR_OUTPUT``
0437 - 12
0438 - Buffer for Software Defined Radio (SDR) output stream, see
0439 :ref:`sdr`.
0440 * - ``V4L2_BUF_TYPE_META_CAPTURE``
0441 - 13
0442 - Buffer for metadata capture, see :ref:`metadata`.
0443 * - ``V4L2_BUF_TYPE_META_OUTPUT``
0444 - 14
0445 - Buffer for metadata output, see :ref:`metadata`.
0446
0447
0448 .. _buffer-flags:
0449
0450 Buffer Flags
0451 ============
0452
0453 .. raw:: latex
0454
0455 \footnotesize
0456
0457 .. tabularcolumns:: |p{6.5cm}|p{1.8cm}|p{9.0cm}|
0458
0459 .. cssclass:: longtable
0460
0461 .. flat-table::
0462 :header-rows: 0
0463 :stub-columns: 0
0464 :widths: 65 18 70
0465
0466 * .. _`V4L2-BUF-FLAG-MAPPED`:
0467
0468 - ``V4L2_BUF_FLAG_MAPPED``
0469 - 0x00000001
0470 - The buffer resides in device memory and has been mapped into the
0471 application's address space, see :ref:`mmap` for details.
0472 Drivers set or clear this flag when the
0473 :ref:`VIDIOC_QUERYBUF`,
0474 :ref:`VIDIOC_QBUF` or
0475 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the
0476 driver.
0477 * .. _`V4L2-BUF-FLAG-QUEUED`:
0478
0479 - ``V4L2_BUF_FLAG_QUEUED``
0480 - 0x00000002
0481 - Internally drivers maintain two buffer queues, an incoming and
0482 outgoing queue. When this flag is set, the buffer is currently on
0483 the incoming queue. It automatically moves to the outgoing queue
0484 after the buffer has been filled (capture devices) or displayed
0485 (output devices). Drivers set or clear this flag when the
0486 ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling
0487 the ``VIDIOC_QBUF``\ ioctl it is always set and after
0488 ``VIDIOC_DQBUF`` always cleared.
0489 * .. _`V4L2-BUF-FLAG-DONE`:
0490
0491 - ``V4L2_BUF_FLAG_DONE``
0492 - 0x00000004
0493 - When this flag is set, the buffer is currently on the outgoing
0494 queue, ready to be dequeued from the driver. Drivers set or clear
0495 this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After
0496 calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always
0497 cleared. Of course a buffer cannot be on both queues at the same
0498 time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag
0499 are mutually exclusive. They can be both cleared however, then the
0500 buffer is in "dequeued" state, in the application domain so to
0501 say.
0502 * .. _`V4L2-BUF-FLAG-ERROR`:
0503
0504 - ``V4L2_BUF_FLAG_ERROR``
0505 - 0x00000040
0506 - When this flag is set, the buffer has been dequeued successfully,
0507 although the data might have been corrupted. This is recoverable,
0508 streaming may continue as normal and the buffer may be reused
0509 normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is
0510 called.
0511 * .. _`V4L2-BUF-FLAG-IN-REQUEST`:
0512
0513 - ``V4L2_BUF_FLAG_IN_REQUEST``
0514 - 0x00000080
0515 - This buffer is part of a request that hasn't been queued yet.
0516 * .. _`V4L2-BUF-FLAG-KEYFRAME`:
0517
0518 - ``V4L2_BUF_FLAG_KEYFRAME``
0519 - 0x00000008
0520 - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
0521 ioctl. It may be set by video capture devices when the buffer
0522 contains a compressed image which is a key frame (or field), i. e.
0523 can be decompressed on its own. Also known as an I-frame.
0524 Applications can set this bit when ``type`` refers to an output
0525 stream.
0526 * .. _`V4L2-BUF-FLAG-PFRAME`:
0527
0528 - ``V4L2_BUF_FLAG_PFRAME``
0529 - 0x00000010
0530 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
0531 or fields which contain only differences to a previous key frame.
0532 Applications can set this bit when ``type`` refers to an output
0533 stream.
0534 * .. _`V4L2-BUF-FLAG-BFRAME`:
0535
0536 - ``V4L2_BUF_FLAG_BFRAME``
0537 - 0x00000020
0538 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
0539 predicted frame or field which contains only the differences
0540 between the current frame and both the preceding and following key
0541 frames to specify its content. Applications can set this bit when
0542 ``type`` refers to an output stream.
0543 * .. _`V4L2-BUF-FLAG-TIMECODE`:
0544
0545 - ``V4L2_BUF_FLAG_TIMECODE``
0546 - 0x00000100
0547 - The ``timecode`` field is valid. Drivers set or clear this flag
0548 when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set
0549 this bit and the corresponding ``timecode`` structure when
0550 ``type`` refers to an output stream.
0551 * .. _`V4L2-BUF-FLAG-PREPARED`:
0552
0553 - ``V4L2_BUF_FLAG_PREPARED``
0554 - 0x00000400
0555 - The buffer has been prepared for I/O and can be queued by the
0556 application. Drivers set or clear this flag when the
0557 :ref:`VIDIOC_QUERYBUF`,
0558 :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`,
0559 :ref:`VIDIOC_QBUF` or
0560 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called.
0561 * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`:
0562
0563 - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
0564 - 0x00000800
0565 - Caches do not have to be invalidated for this buffer. Typically
0566 applications shall use this flag if the data captured in the
0567 buffer is not going to be touched by the CPU, instead the buffer
0568 will, probably, be passed on to a DMA-capable hardware unit for
0569 further processing or output. This flag is ignored unless the
0570 queue is used for :ref:`memory mapping <mmap>` streaming I/O and
0571 reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS
0572 <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
0573 * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`:
0574
0575 - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
0576 - 0x00001000
0577 - Caches do not have to be cleaned for this buffer. Typically
0578 applications shall use this flag for output buffers if the data in
0579 this buffer has not been created by the CPU but by some
0580 DMA-capable unit, in which case caches have not been used. This flag
0581 is ignored unless the queue is used for :ref:`memory mapping <mmap>`
0582 streaming I/O and reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS
0583 <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
0584 * .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`:
0585
0586 - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF``
0587 - 0x00000200
0588 - Only valid if struct :c:type:`v4l2_requestbuffers` flag ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is
0589 set. It is typically used with stateless decoders where multiple
0590 output buffers each decode to a slice of the decoded frame.
0591 Applications can set this flag when queueing the output buffer
0592 to prevent the driver from dequeueing the capture buffer after
0593 the output buffer has been decoded (i.e. the capture buffer is
0594 'held'). If the timestamp of this output buffer differs from that
0595 of the previous output buffer, then that indicates the start of a
0596 new frame and the previously held capture buffer is dequeued.
0597 * .. _`V4L2-BUF-FLAG-LAST`:
0598
0599 - ``V4L2_BUF_FLAG_LAST``
0600 - 0x00100000
0601 - Last buffer produced by the hardware. mem2mem codec drivers set
0602 this flag on the capture queue for the last buffer when the
0603 :ref:`VIDIOC_QUERYBUF` or
0604 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to
0605 hardware limitations, the last buffer may be empty. In this case
0606 the driver will set the ``bytesused`` field to 0, regardless of
0607 the format. Any subsequent call to the
0608 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
0609 but return an ``EPIPE`` error code.
0610 * .. _`V4L2-BUF-FLAG-REQUEST-FD`:
0611
0612 - ``V4L2_BUF_FLAG_REQUEST_FD``
0613 - 0x00800000
0614 - The ``request_fd`` field contains a valid file descriptor.
0615 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`:
0616
0617 - ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
0618 - 0x0000e000
0619 - Mask for timestamp types below. To test the timestamp type, mask
0620 out bits not belonging to timestamp type by performing a logical
0621 and operation with buffer flags and timestamp mask.
0622 * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`:
0623
0624 - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
0625 - 0x00000000
0626 - Unknown timestamp type. This type is used by drivers before Linux
0627 3.9 and may be either monotonic (see below) or realtime (wall
0628 clock). Monotonic clock has been favoured in embedded systems
0629 whereas most of the drivers use the realtime clock. Either kinds
0630 of timestamps are available in user space via
0631 :c:func:`clock_gettime` using clock IDs ``CLOCK_MONOTONIC``
0632 and ``CLOCK_REALTIME``, respectively.
0633 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`:
0634
0635 - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
0636 - 0x00002000
0637 - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
0638 clock. To access the same clock outside V4L2, use
0639 :c:func:`clock_gettime`.
0640 * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`:
0641
0642 - ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
0643 - 0x00004000
0644 - The CAPTURE buffer timestamp has been taken from the corresponding
0645 OUTPUT buffer. This flag applies only to mem2mem devices.
0646 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`:
0647
0648 - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
0649 - 0x00070000
0650 - Mask for timestamp sources below. The timestamp source defines the
0651 point of time the timestamp is taken in relation to the frame.
0652 Logical 'and' operation between the ``flags`` field and
0653 ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the
0654 timestamp source. Applications must set the timestamp source when
0655 ``type`` refers to an output stream and
0656 ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set.
0657 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`:
0658
0659 - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
0660 - 0x00000000
0661 - End Of Frame. The buffer timestamp has been taken when the last
0662 pixel of the frame has been received or the last pixel of the
0663 frame has been transmitted. In practice, software generated
0664 timestamps will typically be read from the clock a small amount of
0665 time after the last pixel has been received or transmitten,
0666 depending on the system and other activity in it.
0667 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`:
0668
0669 - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
0670 - 0x00010000
0671 - Start Of Exposure. The buffer timestamp has been taken when the
0672 exposure of the frame has begun. This is only valid for the
0673 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
0674
0675 .. raw:: latex
0676
0677 \normalsize
0678
0679 enum v4l2_memory
0680 ================
0681
0682 .. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.5cm}|
0683
0684 .. flat-table::
0685 :header-rows: 0
0686 :stub-columns: 0
0687 :widths: 3 1 4
0688
0689 * - ``V4L2_MEMORY_MMAP``
0690 - 1
0691 - The buffer is used for :ref:`memory mapping <mmap>` I/O.
0692 * - ``V4L2_MEMORY_USERPTR``
0693 - 2
0694 - The buffer is used for :ref:`user pointer <userp>` I/O.
0695 * - ``V4L2_MEMORY_OVERLAY``
0696 - 3
0697 - [to do]
0698 * - ``V4L2_MEMORY_DMABUF``
0699 - 4
0700 - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
0701
0702 .. _memory-flags:
0703
0704 Memory Consistency Flags
0705 ------------------------
0706
0707 .. raw:: latex
0708
0709 \small
0710
0711 .. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}|
0712
0713 .. cssclass:: longtable
0714
0715 .. flat-table::
0716 :header-rows: 0
0717 :stub-columns: 0
0718 :widths: 3 1 4
0719
0720 * .. _`V4L2-MEMORY-FLAG-NON-COHERENT`:
0721
0722 - ``V4L2_MEMORY_FLAG_NON_COHERENT``
0723 - 0x00000001
0724 - A buffer is allocated either in coherent (it will be automatically
0725 coherent between the CPU and the bus) or non-coherent memory. The
0726 latter can provide performance gains, for instance the CPU cache
0727 sync/flush operations can be avoided if the buffer is accessed by the
0728 corresponding device only and the CPU does not read/write to/from that
0729 buffer. However, this requires extra care from the driver -- it must
0730 guarantee memory consistency by issuing a cache flush/sync when
0731 consistency is needed. If this flag is set V4L2 will attempt to
0732 allocate the buffer in non-coherent memory. The flag takes effect
0733 only if the buffer is used for :ref:`memory mapping <mmap>` I/O and the
0734 queue reports the :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS
0735 <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
0736
0737 .. raw:: latex
0738
0739 \normalsize
0740
0741 Timecodes
0742 =========
0743
0744 The :c:type:`v4l2_buffer_timecode` structure is designed to hold a
0745 :ref:`smpte12m` or similar timecode.
0746 (struct :c:type:`timeval` timestamps are stored in the struct
0747 :c:type:`v4l2_buffer` ``timestamp`` field.)
0748
0749 .. c:type:: v4l2_timecode
0750
0751 struct v4l2_timecode
0752 --------------------
0753
0754 .. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}|
0755
0756 .. flat-table::
0757 :header-rows: 0
0758 :stub-columns: 0
0759 :widths: 1 1 2
0760
0761 * - __u32
0762 - ``type``
0763 - Frame rate the timecodes are based on, see :ref:`timecode-type`.
0764 * - __u32
0765 - ``flags``
0766 - Timecode flags, see :ref:`timecode-flags`.
0767 * - __u8
0768 - ``frames``
0769 - Frame count, 0 ... 23/24/29/49/59, depending on the type of
0770 timecode.
0771 * - __u8
0772 - ``seconds``
0773 - Seconds count, 0 ... 59. This is a binary, not BCD number.
0774 * - __u8
0775 - ``minutes``
0776 - Minutes count, 0 ... 59. This is a binary, not BCD number.
0777 * - __u8
0778 - ``hours``
0779 - Hours count, 0 ... 29. This is a binary, not BCD number.
0780 * - __u8
0781 - ``userbits``\ [4]
0782 - The "user group" bits from the timecode.
0783
0784
0785 .. _timecode-type:
0786
0787 Timecode Types
0788 --------------
0789
0790 .. flat-table::
0791 :header-rows: 0
0792 :stub-columns: 0
0793 :widths: 3 1 4
0794
0795 * - ``V4L2_TC_TYPE_24FPS``
0796 - 1
0797 - 24 frames per second, i. e. film.
0798 * - ``V4L2_TC_TYPE_25FPS``
0799 - 2
0800 - 25 frames per second, i. e. PAL or SECAM video.
0801 * - ``V4L2_TC_TYPE_30FPS``
0802 - 3
0803 - 30 frames per second, i. e. NTSC video.
0804 * - ``V4L2_TC_TYPE_50FPS``
0805 - 4
0806 -
0807 * - ``V4L2_TC_TYPE_60FPS``
0808 - 5
0809 -
0810
0811
0812 .. _timecode-flags:
0813
0814 Timecode Flags
0815 --------------
0816
0817 .. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.3cm}|
0818
0819 .. flat-table::
0820 :header-rows: 0
0821 :stub-columns: 0
0822 :widths: 3 1 4
0823
0824 * - ``V4L2_TC_FLAG_DROPFRAME``
0825 - 0x0001
0826 - Indicates "drop frame" semantics for counting frames in 29.97 fps
0827 material. When set, frame numbers 0 and 1 at the start of each
0828 minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
0829 count.
0830 * - ``V4L2_TC_FLAG_COLORFRAME``
0831 - 0x0002
0832 - The "color frame" flag.
0833 * - ``V4L2_TC_USERBITS_field``
0834 - 0x000C
0835 - Field mask for the "binary group flags".
0836 * - ``V4L2_TC_USERBITS_USERDEFINED``
0837 - 0x0000
0838 - Unspecified format.
0839 * - ``V4L2_TC_USERBITS_8BITCHARS``
0840 - 0x0008
0841 - 8-bit ISO characters.
