1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3 .. _planar-apis: 4 5 ***************************** 6 Single- and multi-planar APIs 7 ***************************** 8 9 Some devices require data for each input or output video frame to be 10 placed in discontiguous memory buffers. In such cases, one video frame 11 has to be addressed using more than one memory address, i.e. one pointer 12 per "plane". A plane is a sub-buffer of the current frame. For examples 13 of such formats see :ref:`pixfmt`. 14 15 Initially, V4L2 API did not support multi-planar buffers and a set of 16 extensions has been introduced to handle them. Those extensions 17 constitute what is being referred to as the "multi-planar API". 18 19 Some of the V4L2 API calls and structures are interpreted differently, 20 depending on whether single- or multi-planar API is being used. An 21 application can choose whether to use one or the other by passing a 22 corresponding buffer type to its ioctl calls. Multi-planar versions of 23 buffer types are suffixed with an ``_MPLANE`` string. For a list of 24 available multi-planar buffer types see enum 25 :c:type:`v4l2_buf_type`. 26 27 28 Multi-planar formats 29 ==================== 30 31 Multi-planar API introduces new multi-planar formats. Those formats use 32 a separate set of FourCC codes. It is important to distinguish between 33 the multi-planar API and a multi-planar format. Multi-planar API calls 34 can handle all single-planar formats as well (as long as they are passed 35 in multi-planar API structures), while the single-planar API cannot 36 handle multi-planar formats. 37 38 39 Calls 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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.