Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.
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>
