Merge branch 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab...
[linux-2.6.git] / Documentation / DocBook / media / v4l / pixfmt-nv12m.xml
1     <refentry id="V4L2-PIX-FMT-NV12M">
2       <refmeta>
3         <refentrytitle>V4L2_PIX_FMT_NV12M ('NV12M')</refentrytitle>
4         &manvol;
5       </refmeta>
6       <refnamediv>
7         <refname> <constant>V4L2_PIX_FMT_NV12M</constant></refname>
8         <refpurpose>Variation of <constant>V4L2_PIX_FMT_NV12</constant> with planes
9           non contiguous in memory. </refpurpose>
10       </refnamediv>
11       <refsect1>
12         <title>Description</title>
13
14         <para>This is a multi-planar, two-plane version of the YUV 4:2:0 format.
15 The three components are separated into two sub-images or planes.
16 <constant>V4L2_PIX_FMT_NV12M</constant> differs from <constant>V4L2_PIX_FMT_NV12
17 </constant> in that the two planes are non-contiguous in memory, i.e. the chroma
18 plane do not necessarily immediately follows the luma plane.
19 The luminance data occupies the first plane. The Y plane has one byte per pixel.
20 In the second plane there is a chrominance data with alternating chroma samples.
21 The CbCr plane is the same width, in bytes, as the Y plane (and of the image),
22 but is half as tall in pixels. Each CbCr pair belongs to four pixels. For example,
23 Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
24 Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
25 Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. </para>
26
27         <para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be
28 used only in drivers and applications that support the multi-planar API,
29 described in <xref linkend="planar-apis"/>. </para>
30
31         <para>If the Y plane has pad bytes after each row, then the
32 CbCr plane has as many pad bytes after its rows.</para>
33
34         <example>
35           <title><constant>V4L2_PIX_FMT_NV12M</constant> 4 &times; 4 pixel image</title>
36
37           <formalpara>
38             <title>Byte Order.</title>
39             <para>Each cell is one byte.
40                 <informaltable frame="none">
41                 <tgroup cols="5" align="center">
42                   <colspec align="left" colwidth="2*" />
43                   <tbody valign="top">
44                     <row>
45                       <entry>start0&nbsp;+&nbsp;0:</entry>
46                       <entry>Y'<subscript>00</subscript></entry>
47                       <entry>Y'<subscript>01</subscript></entry>
48                       <entry>Y'<subscript>02</subscript></entry>
49                       <entry>Y'<subscript>03</subscript></entry>
50                     </row>
51                     <row>
52                       <entry>start0&nbsp;+&nbsp;4:</entry>
53                       <entry>Y'<subscript>10</subscript></entry>
54                       <entry>Y'<subscript>11</subscript></entry>
55                       <entry>Y'<subscript>12</subscript></entry>
56                       <entry>Y'<subscript>13</subscript></entry>
57                     </row>
58                     <row>
59                       <entry>start0&nbsp;+&nbsp;8:</entry>
60                       <entry>Y'<subscript>20</subscript></entry>
61                       <entry>Y'<subscript>21</subscript></entry>
62                       <entry>Y'<subscript>22</subscript></entry>
63                       <entry>Y'<subscript>23</subscript></entry>
64                     </row>
65                     <row>
66                       <entry>start0&nbsp;+&nbsp;12:</entry>
67                       <entry>Y'<subscript>30</subscript></entry>
68                       <entry>Y'<subscript>31</subscript></entry>
69                       <entry>Y'<subscript>32</subscript></entry>
70                       <entry>Y'<subscript>33</subscript></entry>
71                     </row>
72                     <row>
73                       <entry></entry>
74                     </row>
75                     <row>
76                       <entry>start1&nbsp;+&nbsp;0:</entry>
77                       <entry>Cb<subscript>00</subscript></entry>
78                       <entry>Cr<subscript>00</subscript></entry>
79                       <entry>Cb<subscript>01</subscript></entry>
80                       <entry>Cr<subscript>01</subscript></entry>
81                     </row>
82                     <row>
83                       <entry>start1&nbsp;+&nbsp;4:</entry>
84                       <entry>Cb<subscript>10</subscript></entry>
85                       <entry>Cr<subscript>10</subscript></entry>
86                       <entry>Cb<subscript>11</subscript></entry>
87                       <entry>Cr<subscript>11</subscript></entry>
88                     </row>
89                   </tbody>
90                 </tgroup>
91                 </informaltable>
92               </para>
93           </formalpara>
94
95           <formalpara>
96             <title>Color Sample Location.</title>
97             <para>
98                 <informaltable frame="none">
99                 <tgroup cols="7" align="center">
100                   <tbody valign="top">
101                     <row>
102                       <entry></entry>
103                       <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
104                       <entry>2</entry><entry></entry><entry>3</entry>
105                     </row>
106                     <row>
107                       <entry>0</entry>
108                       <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
109                       <entry>Y</entry><entry></entry><entry>Y</entry>
110                     </row>
111                     <row>
112                       <entry></entry>
113                       <entry></entry><entry>C</entry><entry></entry><entry></entry>
114                       <entry></entry><entry>C</entry><entry></entry>
115                     </row>
116                     <row>
117                       <entry>1</entry>
118                       <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
119                       <entry>Y</entry><entry></entry><entry>Y</entry>
120                     </row>
121                     <row>
122                       <entry></entry>
123                     </row>
124                     <row>
125                       <entry>2</entry>
126                       <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
127                       <entry>Y</entry><entry></entry><entry>Y</entry>
128                     </row>
129                     <row>
130                       <entry></entry>
131                       <entry></entry><entry>C</entry><entry></entry><entry></entry>
132                       <entry></entry><entry>C</entry><entry></entry>
133                     </row>
134                     <row>
135                       <entry>3</entry>
136                       <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
137                       <entry>Y</entry><entry></entry><entry>Y</entry>
138                     </row>
139                   </tbody>
140                 </tgroup>
141                 </informaltable>
142               </para>
143           </formalpara>
144         </example>
145       </refsect1>
146     </refentry>