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