Documentation/DocBook/v4l/planar-apis.xml

   1 <section id="planar-apis">
   2   <title>Single- and multi-planar APIs</title>
   3
   4   <para>Some devices require data for each input or output video frame
   5   to be placed in discontiguous memory buffers. In such cases, one
   6   video frame has to be addressed using more than one memory address, i.e. one
   7   pointer per "plane". A plane is a sub-buffer of the current frame. For
   8   examples of such formats see <xref linkend="pixfmt" />.</para>
   9
  10   <para>Initially, V4L2 API did not support multi-planar buffers and a set of
  11   extensions has been introduced to handle them. Those extensions constitute
  12   what is being referred to as the "multi-planar API".</para>
  13
  14   <para>Some of the V4L2 API calls and structures are interpreted differently,
  15   depending on whether single- or multi-planar API is being used. An application
  16   can choose whether to use one or the other by passing a corresponding buffer
  17   type to its ioctl calls. Multi-planar versions of buffer types are suffixed
  18   with an `_MPLANE' string. For a list of available multi-planar buffer types
  19   see &v4l2-buf-type;.
  20   </para>
  21
  22   <section>
  23     <title>Multi-planar formats</title>
  24     <para>Multi-planar API introduces new multi-planar formats. Those formats
  25     use a separate set of FourCC codes. It is important to distinguish between
  26     the multi-planar API and a multi-planar format. Multi-planar API calls can
  27     handle all single-planar formats as well (as long as they are passed in
  28     multi-planar API structures), while the single-planar API cannot
  29     handle multi-planar formats.</para>
  30   </section>
  31
  32   <section>
  33     <title>Calls that distinguish between single and multi-planar APIs</title>
  34     <variablelist>
  35       <varlistentry>
  36         <term>&VIDIOC-QUERYCAP;</term>
  37         <listitem><para>Two additional multi-planar capabilities are added. They can
  38         be set together with non-multi-planar ones for devices that handle
  39         both single- and multi-planar formats.</para></listitem>
  40       </varlistentry>
  41       <varlistentry>
  42         <term>&VIDIOC-G-FMT;, &VIDIOC-S-FMT;, &VIDIOC-TRY-FMT;</term>
  43         <listitem><para>New structures for describing multi-planar formats are added:
  44         &v4l2-pix-format-mplane; and &v4l2-plane-pix-format;. Drivers may
  45         define new multi-planar formats, which have distinct FourCC codes from
  46         the existing single-planar ones.</para>
  47         </listitem>
  48       </varlistentry>
  49       <varlistentry>
  50         <term>&VIDIOC-QBUF;, &VIDIOC-DQBUF;, &VIDIOC-QUERYBUF;</term>
  51         <listitem><para>A new &v4l2-plane; structure for describing planes is added.
  52         Arrays of this structure are passed in the new
  53         <structfield>m.planes</structfield> field of &v4l2-buffer;.</para>
  54         </listitem>
  55       </varlistentry>
  56       <varlistentry>
  57         <term>&VIDIOC-REQBUFS;</term>
  58         <listitem><para>Will allocate multi-planar buffers as requested.</para></listitem>
  59       </varlistentry>
  60     </variablelist>
  61   </section>
  62 </section>