About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / planar-apis.xml

Custom Search

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>
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>
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>
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>
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>
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>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.