63 lines
2.9 KiB
XML
63 lines
2.9 KiB
XML
<section id="planar-apis">
|
|
<title>Single- and multi-planar APIs</title>
|
|
|
|
<para>Some devices require data for each input or output video frame
|
|
to be placed in discontiguous memory buffers. In such cases, one
|
|
video frame has to be addressed using more than one memory address, i.e. one
|
|
pointer per "plane". A plane is a sub-buffer of the current frame. For
|
|
examples of such formats see <xref linkend="pixfmt" />.</para>
|
|
|
|
<para>Initially, V4L2 API did not support multi-planar buffers and a set of
|
|
extensions has been introduced to handle them. Those extensions constitute
|
|
what is being referred to as the "multi-planar API".</para>
|
|
|
|
<para>Some of the V4L2 API calls and structures are interpreted differently,
|
|
depending on whether single- or multi-planar API is being used. An application
|
|
can choose whether to use one or the other by passing a corresponding buffer
|
|
type to its ioctl calls. Multi-planar versions of buffer types are suffixed
|
|
with an `_MPLANE' string. For a list of available multi-planar buffer types
|
|
see &v4l2-buf-type;.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Multi-planar formats</title>
|
|
<para>Multi-planar API introduces new multi-planar formats. Those formats
|
|
use a separate set of FourCC codes. It is important to distinguish between
|
|
the multi-planar API and a multi-planar format. Multi-planar API calls can
|
|
handle all single-planar formats as well (as long as they are passed in
|
|
multi-planar API structures), while the single-planar API cannot
|
|
handle multi-planar formats.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Calls that distinguish between single and multi-planar APIs</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>&VIDIOC-QUERYCAP;</term>
|
|
<listitem><para>Two additional multi-planar capabilities are added. They can
|
|
be set together with non-multi-planar ones for devices that handle
|
|
both single- and multi-planar formats.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>&VIDIOC-G-FMT;, &VIDIOC-S-FMT;, &VIDIOC-TRY-FMT;</term>
|
|
<listitem><para>New structures for describing multi-planar formats are added:
|
|
&v4l2-pix-format-mplane; and &v4l2-plane-pix-format;. Drivers may
|
|
define new multi-planar formats, which have distinct FourCC codes from
|
|
the existing single-planar ones.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>&VIDIOC-QBUF;, &VIDIOC-DQBUF;, &VIDIOC-QUERYBUF;</term>
|
|
<listitem><para>A new &v4l2-plane; structure for describing planes is added.
|
|
Arrays of this structure are passed in the new
|
|
<structfield>m.planes</structfield> field of &v4l2-buffer;.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>&VIDIOC-REQBUFS;</term>
|
|
<listitem><para>Will allocate multi-planar buffers as requested.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
</section>
|