0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _planar-apis:
0004
0005 *****************************
0006 Single- and multi-planar APIs
0007 *****************************
0008
0009 Some devices require data for each input or output video frame to be
0010 placed in discontiguous memory buffers. In such cases, one video frame
0011 has to be addressed using more than one memory address, i.e. one pointer
0012 per "plane". A plane is a sub-buffer of the current frame. For examples
0013 of such formats see :ref:`pixfmt`.
0014
0015 Initially, V4L2 API did not support multi-planar buffers and a set of
0016 extensions has been introduced to handle them. Those extensions
0017 constitute what is being referred to as the "multi-planar API".
0018
0019 Some of the V4L2 API calls and structures are interpreted differently,
0020 depending on whether single- or multi-planar API is being used. An
0021 application can choose whether to use one or the other by passing a
0022 corresponding buffer type to its ioctl calls. Multi-planar versions of
0023 buffer types are suffixed with an ``_MPLANE`` string. For a list of
0024 available multi-planar buffer types see enum
0025 :c:type:`v4l2_buf_type`.
0026
0027
0028 Multi-planar formats
0029 ====================
0030
0031 Multi-planar API introduces new multi-planar formats. Those formats use
0032 a separate set of FourCC codes. It is important to distinguish between
0033 the multi-planar API and a multi-planar format. Multi-planar API calls
0034 can handle all single-planar formats as well (as long as they are passed
0035 in multi-planar API structures), while the single-planar API cannot
0036 handle multi-planar formats.
0037
0038
0039 Calls that distinguish between single and multi-planar APIs
0040 ===========================================================
0041
0042 :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
0043 Two additional multi-planar capabilities are added. They can be set
0044 together with non-multi-planar ones for devices that handle both
0045 single- and multi-planar formats.
0046
0047 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`
0048 New structures for describing multi-planar formats are added: struct
0049 :c:type:`v4l2_pix_format_mplane` and
0050 struct :c:type:`v4l2_plane_pix_format`.
0051 Drivers may define new multi-planar formats, which have distinct
0052 FourCC codes from the existing single-planar ones.
0053
0054 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`
0055 A new struct :c:type:`v4l2_plane` structure for
0056 describing planes is added. Arrays of this structure are passed in
0057 the new ``m.planes`` field of struct
0058 :c:type:`v4l2_buffer`.
0059
0060 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
0061 Will allocate multi-planar buffers as requested.
