1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Single- and multi-planar APIs</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="common.html" title="Chapter 1. Common API Elements"><link rel="prev" href="format.html" title="Data Formats"><link rel="next" href="crop.html" title="Image Cropping, Insertion and Scaling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Single- and multi-planar APIs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="format.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Common API Elements</th><td width="20%" align="right"> <a accesskey="n" href="crop.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="planar-apis"></a>Single- and multi-planar APIs</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="planar-apis.html#idp1098952028">Multi-planar formats</a></span></dt><dt><span class="section"><a href="planar-apis.html#idp1098952868">Calls that distinguish between single and multi-planar APIs</a></span></dt></dl></div><p>Some devices require data for each input or output video frame 2 to be placed in discontiguous memory buffers. In such cases, one 3 video frame has to be addressed using more than one memory address, i.e. one 4 pointer per "plane". A plane is a sub-buffer of the current frame. For 5 examples of such formats see <a class="xref" href="pixfmt.html" title="Chapter 2. Image Formats">Chapter 2, <i>Image Formats</i></a>.</p><p>Initially, V4L2 API did not support multi-planar buffers and a set of 6 extensions has been introduced to handle them. Those extensions constitute 7 what is being referred to as the "multi-planar API".</p><p>Some of the V4L2 API calls and structures are interpreted differently, 8 depending on whether single- or multi-planar API is being used. An application 9 can choose whether to use one or the other by passing a corresponding buffer 10 type to its ioctl calls. Multi-planar versions of buffer types are suffixed 11 with an `_MPLANE' string. For a list of available multi-planar buffer types 12 see enum <a class="link" href="buffer.html#v4l2-buf-type" title="Table 3.3. enum v4l2_buf_type">v4l2_buf_type</a>. 13 </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1098952028"></a>Multi-planar formats</h3></div></div></div><p>Multi-planar API introduces new multi-planar formats. Those formats 14 use a separate set of FourCC codes. It is important to distinguish between 15 the multi-planar API and a multi-planar format. Multi-planar API calls can 16 handle all single-planar formats as well (as long as they are passed in 17 multi-planar API structures), while the single-planar API cannot 18 handle multi-planar formats.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1098952868"></a>Calls that distinguish between single and multi-planar APIs</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a class="link" href="vidioc-querycap.html" title="ioctl VIDIOC_QUERYCAP"><code class="constant">VIDIOC_QUERYCAP</code></a></span></dt><dd><p>Two additional multi-planar capabilities are added. They can 19 be set together with non-multi-planar ones for devices that handle 20 both single- and multi-planar formats.</p></dd><dt><span class="term"><a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_G_FMT</code></a>, <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a>, <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_TRY_FMT</code></a></span></dt><dd><p>New structures for describing multi-planar formats are added: 21 struct <a class="link" href="ch02s02.html#v4l2-pix-format-mplane" title="Table 2.3. struct v4l2_pix_format_mplane">v4l2_pix_format_mplane</a> and struct <a class="link" href="ch02s02.html#v4l2-plane-pix-format" title="Table 2.2. struct v4l2_plane_pix_format">v4l2_plane_pix_format</a>. Drivers may 22 define new multi-planar formats, which have distinct FourCC codes from 23 the existing single-planar ones.</p></dd><dt><span class="term"><a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_QBUF</code></a>, <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_DQBUF</code></a>, <a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF"><code class="constant">VIDIOC_QUERYBUF</code></a></span></dt><dd><p>A new struct <a class="link" href="buffer.html#v4l2-plane" title="Table 3.2. struct v4l2_plane">v4l2_plane</a> structure for describing planes is added. 24 Arrays of this structure are passed in the new 25 <em class="structfield"><code>m.planes</code></em> field of struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a>.</p></dd><dt><span class="term"><a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a></span></dt><dd><p>Will allocate multi-planar buffers as requested.</p></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="format.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="common.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="crop.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Data Formats </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Image Cropping, Insertion and Scaling</td></tr></table></div></body></html> 26