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

Commit 269da402 authored by Sylwester Nawrocki's avatar Sylwester Nawrocki Committed by Mauro Carvalho Chehab
Browse files

[media] v4l: Add DocBook documentation for YU12M, NV12M image formats 



Signed-off-by: default avatarSylwester Nawrocki <s.nawrocki@samsung.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 4a3c9b4f

Documentation/DocBook/media-entities.tmpl

+4 −0
Original line number Diff line number Diff line
@@ -237,6 +237,7 @@ 
<!ENTITY sub-io SYSTEM "v4l/io.xml">

<!ENTITY sub-grey SYSTEM "v4l/pixfmt-grey.xml">

<!ENTITY sub-nv12 SYSTEM "v4l/pixfmt-nv12.xml">

<!ENTITY sub-nv12m SYSTEM "v4l/pixfmt-nv12m.xml">

<!ENTITY sub-nv16 SYSTEM "v4l/pixfmt-nv16.xml">

<!ENTITY sub-packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml">

<!ENTITY sub-packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml">
@@ -251,6 +252,7 @@ 
<!ENTITY sub-yuv410 SYSTEM "v4l/pixfmt-yuv410.xml">

<!ENTITY sub-yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml">

<!ENTITY sub-yuv420 SYSTEM "v4l/pixfmt-yuv420.xml">

<!ENTITY sub-yuv420m SYSTEM "v4l/pixfmt-yuv420m.xml">

<!ENTITY sub-yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml">

<!ENTITY sub-yuyv SYSTEM "v4l/pixfmt-yuyv.xml">

<!ENTITY sub-yvyu SYSTEM "v4l/pixfmt-yvyu.xml">
@@ -337,6 +339,7 @@ 
<!ENTITY write SYSTEM "v4l/func-write.xml">

<!ENTITY grey SYSTEM "v4l/pixfmt-grey.xml">

<!ENTITY nv12 SYSTEM "v4l/pixfmt-nv12.xml">

<!ENTITY nv12m SYSTEM "v4l/pixfmt-nv12m.xml">

<!ENTITY nv16 SYSTEM "v4l/pixfmt-nv16.xml">

<!ENTITY packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml">

<!ENTITY packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml">
@@ -351,6 +354,7 @@ 
<!ENTITY yuv410 SYSTEM "v4l/pixfmt-yuv410.xml">

<!ENTITY yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml">

<!ENTITY yuv420 SYSTEM "v4l/pixfmt-yuv420.xml">

<!ENTITY yuv420m SYSTEM "v4l/pixfmt-yuv420m.xml">

<!ENTITY yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml">

<!ENTITY yuyv SYSTEM "v4l/pixfmt-yuyv.xml">

<!ENTITY yvyu SYSTEM "v4l/pixfmt-yvyu.xml">

Documentation/DocBook/v4l/pixfmt-nv12m.xml

0 → 100644
+154 −0
Original line number Diff line number Diff line 
    <refentry id="V4L2-PIX-FMT-NV12M">

      <refmeta>

	<refentrytitle>V4L2_PIX_FMT_NV12M ('NV12M')</refentrytitle>

	&manvol;

      </refmeta>

      <refnamediv>

	<refname> <constant>V4L2_PIX_FMT_NV12M</constant></refname>

	<refpurpose>Variation of <constant>V4L2_PIX_FMT_NV12</constant> with planes

	  non contiguous in memory. </refpurpose>

      </refnamediv>

      <refsect1>

	<title>Description</title>



	<para>This is a multi-planar, two-plane version of the YUV 4:2:0 format.

The three components are separated into two sub-images or planes.

<constant>V4L2_PIX_FMT_NV12M</constant> differs from <constant>V4L2_PIX_FMT_NV12

</constant> in that the two planes are non-contiguous in memory, i.e. the chroma

plane do not necessarily immediately follows the luma plane.

The luminance data occupies the first plane. The Y plane has one byte per pixel.

In the second plane there is a chrominance data with alternating chroma samples.

The CbCr plane is the same width, in bytes, as the Y plane (and of the image),

but is half as tall in pixels. Each CbCr pair belongs to four pixels. For example,

Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to

Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,

Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. </para>



	<para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be

used only in drivers and applications that support the multi-planar API,

described in <xref linkend="planar-apis"/>. </para>



	<para>If the Y plane has pad bytes after each row, then the

CbCr plane has as many pad bytes after its rows.</para>



	<example>

	  <title><constant>V4L2_PIX_FMT_NV12M</constant> 4 &times; 4 pixel image</title>



	  <formalpara>

	    <title>Byte Order.</title>

	    <para>Each cell is one byte.

		<informaltable frame="none">

		<tgroup cols="5" align="center">

		  <colspec align="left" colwidth="2*" />

		  <tbody valign="top">

		    <row>

		      <entry>start0&nbsp;+&nbsp;0:</entry>

		      <entry>Y'<subscript>00</subscript></entry>

		      <entry>Y'<subscript>01</subscript></entry>

		      <entry>Y'<subscript>02</subscript></entry>

		      <entry>Y'<subscript>03</subscript></entry>

		    </row>

		    <row>

		      <entry>start0&nbsp;+&nbsp;4:</entry>

		      <entry>Y'<subscript>10</subscript></entry>

		      <entry>Y'<subscript>11</subscript></entry>

		      <entry>Y'<subscript>12</subscript></entry>

		      <entry>Y'<subscript>13</subscript></entry>

		    </row>

		    <row>

		      <entry>start0&nbsp;+&nbsp;8:</entry>

		      <entry>Y'<subscript>20</subscript></entry>

		      <entry>Y'<subscript>21</subscript></entry>

		      <entry>Y'<subscript>22</subscript></entry>

		      <entry>Y'<subscript>23</subscript></entry>

		    </row>

		    <row>

		      <entry>start0&nbsp;+&nbsp;12:</entry>

		      <entry>Y'<subscript>30</subscript></entry>

		      <entry>Y'<subscript>31</subscript></entry>

		      <entry>Y'<subscript>32</subscript></entry>

		      <entry>Y'<subscript>33</subscript></entry>

		    </row>

		    <row>

		      <entry></entry>

		    </row>

		    <row>

		      <entry>start1&nbsp;+&nbsp;0:</entry>

		      <entry>Cb<subscript>00</subscript></entry>

		      <entry>Cr<subscript>00</subscript></entry>

		      <entry>Cb<subscript>01</subscript></entry>

		      <entry>Cr<subscript>01</subscript></entry>

		    </row>

		    <row>

		      <entry>start1&nbsp;+&nbsp;4:</entry>

		      <entry>Cb<subscript>10</subscript></entry>

		      <entry>Cr<subscript>10</subscript></entry>

		      <entry>Cb<subscript>11</subscript></entry>

		      <entry>Cr<subscript>11</subscript></entry>

		    </row>

		  </tbody>

		</tgroup>

		</informaltable>

	      </para>

	  </formalpara>



	  <formalpara>

	    <title>Color Sample Location.</title>

	    <para>

		<informaltable frame="none">

		<tgroup cols="7" align="center">

		  <tbody valign="top">

		    <row>

		      <entry></entry>

		      <entry>0</entry><entry></entry><entry>1</entry><entry></entry>

		      <entry>2</entry><entry></entry><entry>3</entry>

		    </row>

		    <row>

		      <entry>0</entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry>

		    </row>

		    <row>

		      <entry></entry>

		      <entry></entry><entry>C</entry><entry></entry><entry></entry>

		      <entry></entry><entry>C</entry><entry></entry>

		    </row>

		    <row>

		      <entry>1</entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry>

		    </row>

		    <row>

		      <entry></entry>

		    </row>

		    <row>

		      <entry>2</entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry>

		    </row>

		    <row>

		      <entry></entry>

		      <entry></entry><entry>C</entry><entry></entry><entry></entry>

		      <entry></entry><entry>C</entry><entry></entry>

		    </row>

		    <row>

		      <entry>3</entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry>

		    </row>

		  </tbody>

		</tgroup>

		</informaltable>

	      </para>

	  </formalpara>

	</example>

      </refsect1>

    </refentry>



  <!--

Local Variables:

mode: sgml

sgml-parent-document: "pixfmt.sgml"

indent-tabs-mode: nil

End:

  -->

Documentation/DocBook/v4l/pixfmt-yuv420m.xml

0 → 100644
+162 −0
Original line number Diff line number Diff line 
    <refentry id="V4L2-PIX-FMT-YUV420M">

      <refmeta>

	<refentrytitle>V4L2_PIX_FMT_YUV420M ('YU12M')</refentrytitle>

	&manvol;

      </refmeta>

      <refnamediv>

	<refname> <constant>V4L2_PIX_FMT_YUV420M</constant></refname>

	<refpurpose>Variation of <constant>V4L2_PIX_FMT_YUV420</constant>

	  with planes non contiguous in memory. </refpurpose>

      </refnamediv>



      <refsect1>

	<title>Description</title>



	<para>This is a multi-planar format, as opposed to a packed format.

The three components are separated into three sub- images or planes.



The Y plane is first. The Y plane has one byte per pixel. The Cb data

constitutes the second plane which is half the width and half

the height of the Y plane (and of the image). Each Cb belongs to four

pixels, a two-by-two square of the image. For example,

Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,

Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and

Y'<subscript>11</subscript>. The Cr data, just like the Cb plane, is

in the third plane. </para>



	<para>If the Y plane has pad bytes after each row, then the Cb

and Cr planes have half as many pad bytes after their rows. In other

words, two Cx rows (including padding) is exactly as long as one Y row

(including padding).</para>



	<para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be

used only in drivers and applications that support the multi-planar API,

described in <xref linkend="planar-apis"/>. </para>



	<example>

	  <title><constant>V4L2_PIX_FMT_YVU420M</constant> 4 &times; 4

pixel image</title>



	  <formalpara>

	    <title>Byte Order.</title>

	    <para>Each cell is one byte.

		<informaltable frame="none">

		<tgroup cols="5" align="center">

		  <colspec align="left" colwidth="2*" />

		  <tbody valign="top">

		    <row>

		      <entry>start0&nbsp;+&nbsp;0:</entry>

		      <entry>Y'<subscript>00</subscript></entry>

		      <entry>Y'<subscript>01</subscript></entry>

		      <entry>Y'<subscript>02</subscript></entry>

		      <entry>Y'<subscript>03</subscript></entry>

		    </row>

		    <row>

		      <entry>start0&nbsp;+&nbsp;4:</entry>

		      <entry>Y'<subscript>10</subscript></entry>

		      <entry>Y'<subscript>11</subscript></entry>

		      <entry>Y'<subscript>12</subscript></entry>

		      <entry>Y'<subscript>13</subscript></entry>

		    </row>

		    <row>

		      <entry>start0&nbsp;+&nbsp;8:</entry>

		      <entry>Y'<subscript>20</subscript></entry>

		      <entry>Y'<subscript>21</subscript></entry>

		      <entry>Y'<subscript>22</subscript></entry>

		      <entry>Y'<subscript>23</subscript></entry>

		    </row>

		    <row>

		      <entry>start0&nbsp;+&nbsp;12:</entry>

		      <entry>Y'<subscript>30</subscript></entry>

		      <entry>Y'<subscript>31</subscript></entry>

		      <entry>Y'<subscript>32</subscript></entry>

		      <entry>Y'<subscript>33</subscript></entry>

		    </row>

		    <row><entry></entry></row>

		    <row>

		      <entry>start1&nbsp;+&nbsp;0:</entry>

		      <entry>Cb<subscript>00</subscript></entry>

		      <entry>Cb<subscript>01</subscript></entry>

		    </row>

		    <row>

		      <entry>start1&nbsp;+&nbsp;2:</entry>

		      <entry>Cb<subscript>10</subscript></entry>

		      <entry>Cb<subscript>11</subscript></entry>

		    </row>

		    <row><entry></entry></row>

		    <row>

		      <entry>start2&nbsp;+&nbsp;0:</entry>

		      <entry>Cr<subscript>00</subscript></entry>

		      <entry>Cr<subscript>01</subscript></entry>

		    </row>

		    <row>

		      <entry>start2&nbsp;+&nbsp;2:</entry>

		      <entry>Cr<subscript>10</subscript></entry>

		      <entry>Cr<subscript>11</subscript></entry>

		    </row>

		  </tbody>

		</tgroup>

		</informaltable>

	      </para>

	  </formalpara>



	  <formalpara>

	    <title>Color Sample Location.</title>

	    <para>

		<informaltable frame="none">

		<tgroup cols="7" align="center">

		  <tbody valign="top">

		    <row>

		      <entry></entry>

		      <entry>0</entry><entry></entry><entry>1</entry><entry></entry>

		      <entry>2</entry><entry></entry><entry>3</entry>

		    </row>

		    <row>

		      <entry>0</entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry>

		    </row>

		    <row>

		      <entry></entry>

		      <entry></entry><entry>C</entry><entry></entry><entry></entry>

		      <entry></entry><entry>C</entry><entry></entry>

		    </row>

		    <row>

		      <entry>1</entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry>

		    </row>

		    <row>

		      <entry></entry>

		    </row>

		    <row>

		      <entry>2</entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry>

		    </row>

		    <row>

		      <entry></entry>

		      <entry></entry><entry>C</entry><entry></entry><entry></entry>

		      <entry></entry><entry>C</entry><entry></entry>

		    </row>

		    <row>

		      <entry>3</entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>

		      <entry>Y</entry><entry></entry><entry>Y</entry>

		    </row>

		  </tbody>

		</tgroup>

		</informaltable>

	      </para>

	  </formalpara>

	</example>

      </refsect1>

    </refentry>



  <!--

Local Variables:

mode: sgml

sgml-parent-document: "pixfmt.sgml"

indent-tabs-mode: nil

End:

  -->

Documentation/DocBook/v4l/pixfmt.xml

+2 −0
Original line number Diff line number Diff line
@@ -703,10 +703,12 @@ information.</para> 
    &sub-vyuy;

    &sub-y41p;

    &sub-yuv420;

    &sub-yuv420m;

    &sub-yuv410;

    &sub-yuv422p;

    &sub-yuv411p;

    &sub-nv12;

    &sub-nv12m;

    &sub-nv16;

  </section>