1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _planar-apis:
4
5*****************************
6Single- and multi-planar APIs
7*****************************
8
9Some devices require data for each input or output video frame to be
10placed in discontiguous memory buffers. In such cases, one video frame
11has to be addressed using more than one memory address, i.e. one pointer
12per "plane". A plane is a sub-buffer of the current frame. For examples
13of such formats see :ref:`pixfmt`.
14
15Initially, V4L2 API did not support multi-planar buffers and a set of
16extensions has been introduced to handle them. Those extensions
17constitute what is being referred to as the "multi-planar API".
18
19Some of the V4L2 API calls and structures are interpreted differently,
20depending on whether single- or multi-planar API is being used. An
21application can choose whether to use one or the other by passing a
22corresponding buffer type to its ioctl calls. Multi-planar versions of
23buffer types are suffixed with an ``_MPLANE`` string. For a list of
24available multi-planar buffer types see enum
25:c:type:`v4l2_buf_type`.
26
27
28Multi-planar formats
29====================
30
31Multi-planar API introduces new multi-planar formats. Those formats use
32a separate set of FourCC codes. It is important to distinguish between
33the multi-planar API and a multi-planar format. Multi-planar API calls
34can handle all single-planar formats as well (as long as they are passed
35in multi-planar API structures), while the single-planar API cannot
36handle multi-planar formats.
37
38
39Calls that distinguish between single and multi-planar APIs
40===========================================================
41
42:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
43    Two additional multi-planar capabilities are added. They can be set
44    together with non-multi-planar ones for devices that handle both
45    single- and multi-planar formats.
46
47:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`
48    New structures for describing multi-planar formats are added: struct
49    :c:type:`v4l2_pix_format_mplane` and
50    struct :c:type:`v4l2_plane_pix_format`.
51    Drivers may define new multi-planar formats, which have distinct
52    FourCC codes from the existing single-planar ones.
53
54:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`
55    A new struct :c:type:`v4l2_plane` structure for
56    describing planes is added. Arrays of this structure are passed in
57    the new ``m.planes`` field of struct
58    :c:type:`v4l2_buffer`.
59
60:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
61    Will allocate multi-planar buffers as requested.
62