Documentation/media/uapi/v4l/planar-apis.rst

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