blob: 878ce204048831d8e70662ff8331288ac9e621dd (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
|
<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>
|
