dect
/
linux-2.6
Archived
13
0
Fork 0
Code Releases Activity

[media] Remove compatibility layer from multi-planar API documentation 

This feature will probably be moved to libv4l2.

Signed-off-by: Pawel Osciak <pawel@osciak.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
This commit is contained in:
Pawel Osciak 2011-01-16 13:53:31 -03:00 committed by Mauro Carvalho Chehab
parent 87a0c94ce6
commit d39155d91d
2 changed files with 18 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
Documentation/DocBook/v4l/planar-apis.xml
View File

@ -2,10 +2,10 @@
<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
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 current frame. For examples
of such formats see <xref linkend="pixfmt" />.</para>
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
@ -14,8 +14,8 @@
<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
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>
@ -24,28 +24,9 @@
<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, while the single-planar API cannot
handle multi-planar formats. Applications do not have to switch between APIs
when handling both single- and multi-planar devices and should use the
multi-planar API version for both single- and multi-planar formats.
Drivers that do not support multi-planar API can still be handled with it,
utilizing a compatibility layer built into standard V4L2 ioctl handling.
</para>
</section>
<section>
<title>Single and multi-planar API compatibility layer</title>
<para>In most cases<footnote><para>The compatibility layer does not cover
drivers that do not use video_ioctl2() call.</para></footnote>, applications
can use the multi-planar API with older drivers that support
only its single-planar version and vice versa. Appropriate conversion is
done seamlessly for both applications and drivers in the V4L2 core. The
general rule of thumb is: as long as an application uses formats that
a driver supports, it can use either API (although use of multi-planar
formats is only possible with the multi-planar API). The list of formats
supported by a driver can be obtained using the &VIDIOC-ENUM-FMT; call.
It is possible, but discouraged, for a driver or an application to support
and use both versions of the API.</para>
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>

22
Documentation/DocBook/v4l/vidioc-querycap.xml
View File

@ -142,30 +142,28 @@ this array to zero.</entry>
<row>
<entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
<entry>0x00000001</entry>
<entry>The device supports single-planar formats through the <link
linkend="capture">Video Capture</link> interface. An application can use either
<link linkend="planar-apis">the single or the multi-planar API</link>.</entry>
<entry>The device supports the single-planar API through the <link
linkend="capture">Video Capture</link> interface.</entry>
</row>
<row>
<entry><constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant></entry>
<entry>0x00001000</entry>
<entry>The device supports multi-planar formats through the <link
linkend="capture">Video Capture</link> interface. An application has to use the
<link linkend="planar-apis">multi-planar API</link>.</entry>
<entry>The device supports the
<link linkend="planar-apis">multi-planar API</link> through the
<link linkend="capture">Video Capture</link> interface.</entry>
</row>
<row>
<entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry>
<entry>0x00000002</entry>
<entry>The device supports single-planar formats through the <link
linkend="output">Video Output</link> interface. An application can use either
<link linkend="planar-apis">the single or the multi-planar API</link>.</entry>
<entry>The device supports the single-planar API through the <link
linkend="output">Video Output</link> interface.</entry>
</row>
<row>
<entry><constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant></entry>
<entry>0x00002000</entry>
<entry>The device supports multi-planar formats through the <link
linkend="output">Video Output</link> interface. An application has to use the
<link linkend="planar-apis">multi-planar API</link>.</entry>
<entry>The device supports the
<link linkend="planar-apis">multi-planar API</link> through the
<link linkend="output">Video Output</link> interface.</entry>
</row>
<row>
<entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>