diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/planar-apis.xml')
-rw-r--r-- | Documentation/DocBook/media/v4l/planar-apis.xml | 62 |
1 files changed, 62 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/v4l/planar-apis.xml b/Documentation/DocBook/media/v4l/planar-apis.xml new file mode 100644 index 00000000000..878ce204048 --- /dev/null +++ b/Documentation/DocBook/media/v4l/planar-apis.xml @@ -0,0 +1,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> |