Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit d39155d9 authored by Pawel Osciak's avatar Pawel Osciak Committed by Mauro Carvalho Chehab
Browse files

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



This feature will probably be moved to libv4l2.

Signed-off-by: default avatarPawel Osciak <pawel@osciak.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 87a0c94c

Documentation/DocBook/v4l/planar-apis.xml

+8 −27
Original line number Diff line number Diff line
@@ -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>

Documentation/DocBook/v4l/vidioc-querycap.xml

+10 −12
Original line number Diff line number Diff line
@@ -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>