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