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