Documentation/DocBook/v4l/pixfmt.xml

   1   <title>Image Formats</title>
   2
   3   <para>The V4L2 API was primarily designed for devices exchanging
   4 image data with applications. The
   5 <structname>v4l2_pix_format</structname> structure defines the format
   6 and layout of an image in memory. Image formats are negotiated with
   7 the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
   8 capturing and output, for overlay frame buffer formats see also
   9 &VIDIOC-G-FBUF;.)</para>
  10
  11   <table pgwide="1" frame="none" id="v4l2-pix-format">
  12     <title>struct <structname>v4l2_pix_format</structname></title>
  13     <tgroup cols="3">
  14       &cs-str;
  15       <tbody valign="top">
  16         <row>
  17           <entry>__u32</entry>
  18           <entry><structfield>width</structfield></entry>
  19           <entry>Image width in pixels.</entry>
  20         </row>
  21         <row>
  22           <entry>__u32</entry>
  23           <entry><structfield>height</structfield></entry>
  24           <entry>Image height in pixels.</entry>
  25         </row>
  26         <row>
  27           <entry spanname="hspan">Applications set these fields to
  28 request an image size, drivers return the closest possible values. In
  29 case of planar formats the <structfield>width</structfield> and
  30 <structfield>height</structfield> applies to the largest plane. To
  31 avoid ambiguities drivers must return values rounded up to a multiple
  32 of the scale factor of any smaller planes. For example when the image
  33 format is YUV 4:2:0, <structfield>width</structfield> and
  34 <structfield>height</structfield> must be multiples of two.</entry>
  35         </row>
  36         <row>
  37           <entry>__u32</entry>
  38           <entry><structfield>pixelformat</structfield></entry>
  39           <entry>The pixel format or type of compression, set by the
  40 application. This is a little endian <link
  41 linkend="v4l2-fourcc">four character code</link>. V4L2 defines
  42 standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref
  43 linkend="yuv-formats" />, and reserved codes in <xref
  44 linkend="reserved-formats" /></entry>
  45         </row>
  46         <row>
  47           <entry>&v4l2-field;</entry>
  48           <entry><structfield>field</structfield></entry>
  49           <entry>Video images are typically interlaced. Applications
  50 can request to capture or output only the top or bottom field, or both
  51 fields interlaced or sequentially stored in one buffer or alternating
  52 in separate buffers. Drivers return the actual field order selected.
  53 For details see <xref linkend="field-order" />.</entry>
  54         </row>
  55         <row>
  56           <entry>__u32</entry>
  57           <entry><structfield>bytesperline</structfield></entry>
  58           <entry>Distance in bytes between the leftmost pixels in two
  59 adjacent lines.</entry>
  60         </row>
  61         <row>
  62           <entry spanname="hspan"><para>Both applications and drivers
  63 can set this field to request padding bytes at the end of each line.
  64 Drivers however may ignore the value requested by the application,
  65 returning <structfield>width</structfield> times bytes per pixel or a
  66 larger value required by the hardware. That implies applications can
  67 just set this field to zero to get a reasonable
  68 default.</para><para>Video hardware may access padding bytes,
  69 therefore they must reside in accessible memory. Consider cases where
  70 padding bytes after the last line of an image cross a system page
  71 boundary. Input devices may write padding bytes, the value is
  72 undefined. Output devices ignore the contents of padding
  73 bytes.</para><para>When the image format is planar the
  74 <structfield>bytesperline</structfield> value applies to the largest
  75 plane and is divided by the same factor as the
  76 <structfield>width</structfield> field for any smaller planes. For
  77 example the Cb and Cr planes of a YUV 4:2:0 image have half as many
  78 padding bytes following each line as the Y plane. To avoid ambiguities
  79 drivers must return a <structfield>bytesperline</structfield> value
  80 rounded up to a multiple of the scale factor.</para></entry>
  81         </row>
  82         <row>
  83           <entry>__u32</entry>
  84           <entry><structfield>sizeimage</structfield></entry>
  85           <entry>Size in bytes of the buffer to hold a complete image,
  86 set by the driver. Usually this is
  87 <structfield>bytesperline</structfield> times
  88 <structfield>height</structfield>. When the image consists of variable
  89 length compressed data this is the maximum number of bytes required to
  90 hold an image.</entry>
  91         </row>
  92         <row>
  93           <entry>&v4l2-colorspace;</entry>
  94           <entry><structfield>colorspace</structfield></entry>
  95           <entry>This information supplements the
  96 <structfield>pixelformat</structfield> and must be set by the driver,
  97 see <xref linkend="colorspaces" />.</entry>
  98         </row>
  99         <row>
 100           <entry>__u32</entry>
 101           <entry><structfield>priv</structfield></entry>
 102           <entry>Reserved for custom (driver defined) additional
 103 information about formats. When not used drivers and applications must
 104 set this field to zero.</entry>
 105         </row>
 106       </tbody>
 107     </tgroup>
 108   </table>
 109
 110   <section>
 111     <title>Standard Image Formats</title>
 112
 113     <para>In order to exchange images between drivers and
 114 applications, it is necessary to have standard image data formats
 115 which both sides will interpret the same way. V4L2 includes several
 116 such formats, and this section is intended to be an unambiguous
 117 specification of the standard image data formats in V4L2.</para>
 118
 119     <para>V4L2 drivers are not limited to these formats, however.
 120 Driver-specific formats are possible. In that case the application may
 121 depend on a codec to convert images to one of the standard formats
 122 when needed. But the data can still be stored and retrieved in the
 123 proprietary format. For example, a device may support a proprietary
 124 compressed format. Applications can still capture and save the data in
 125 the compressed format, saving much disk space, and later use a codec
 126 to convert the images to the X Windows screen format when the video is
 127 to be displayed.</para>
 128
 129     <para>Even so, ultimately, some standard formats are needed, so
 130 the V4L2 specification would not be complete without well-defined
 131 standard formats.</para>
 132
 133     <para>The V4L2 standard formats are mainly uncompressed formats. The
 134 pixels are always arranged in memory from left to right, and from top
 135 to bottom. The first byte of data in the image buffer is always for
 136 the leftmost pixel of the topmost row. Following that is the pixel
 137 immediately to its right, and so on until the end of the top row of
 138 pixels. Following the rightmost pixel of the row there may be zero or
 139 more bytes of padding to guarantee that each row of pixel data has a
 140 certain alignment. Following the pad bytes, if any, is data for the
 141 leftmost pixel of the second row from the top, and so on. The last row
 142 has just as many pad bytes after it as the other rows.</para>
 143
 144     <para>In V4L2 each format has an identifier which looks like
 145 <constant>PIX_FMT_XXX</constant>, defined in the <link
 146 linkend="videodev">videodev.h</link> header file. These identifiers
 147 represent <link linkend="v4l2-fourcc">four character codes</link>
 148 which are also listed below, however they are not the same as those
 149 used in the Windows world.</para>
 150   </section>
 151
 152   <section id="colorspaces">
 153     <title>Colorspaces</title>
 154
 155     <para>[intro]</para>
 156
 157     <!-- See proposal by Billy Biggs, video4linux-list@redhat.com
 158 on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and
 159 http://vektor.theorem.ca/graphics/ycbcr/ and
 160 http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html -->
 161
 162     <para>
 163       <variablelist>
 164         <varlistentry>
 165           <term>Gamma Correction</term>
 166           <listitem>
 167             <para>[to do]</para>
 168             <para>E'<subscript>R</subscript> = f(R)</para>
 169             <para>E'<subscript>G</subscript> = f(G)</para>
 170             <para>E'<subscript>B</subscript> = f(B)</para>
 171           </listitem>
 172         </varlistentry>
 173         <varlistentry>
 174           <term>Construction of luminance and color-difference
 175 signals</term>
 176           <listitem>
 177             <para>[to do]</para>
 178             <para>E'<subscript>Y</subscript> =
 179 Coeff<subscript>R</subscript> E'<subscript>R</subscript>
 180 + Coeff<subscript>G</subscript> E'<subscript>G</subscript>
 181 + Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
 182             <para>(E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = E'<subscript>R</subscript>
 183 - Coeff<subscript>R</subscript> E'<subscript>R</subscript>
 184 - Coeff<subscript>G</subscript> E'<subscript>G</subscript>
 185 - Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
 186             <para>(E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = E'<subscript>B</subscript>
 187 - Coeff<subscript>R</subscript> E'<subscript>R</subscript>
 188 - Coeff<subscript>G</subscript> E'<subscript>G</subscript>
 189 - Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
 190           </listitem>
 191         </varlistentry>
 192         <varlistentry>
 193           <term>Re-normalized color-difference signals</term>
 194           <listitem>
 195             <para>The color-difference signals are scaled back to unity
 196 range [-0.5;+0.5]:</para>
 197             <para>K<subscript>B</subscript> = 0.5 / (1 - Coeff<subscript>B</subscript>)</para>
 198             <para>K<subscript>R</subscript> = 0.5 / (1 - Coeff<subscript>R</subscript>)</para>
 199             <para>P<subscript>B</subscript> =
 200 K<subscript>B</subscript> (E'<subscript>B</subscript> - E'<subscript>Y</subscript>) =
 201   0.5 (Coeff<subscript>R</subscript> / Coeff<subscript>B</subscript>) E'<subscript>R</subscript>
 202 + 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>B</subscript>) E'<subscript>G</subscript>
 203 + 0.5 E'<subscript>B</subscript></para>
 204             <para>P<subscript>R</subscript> =
 205 K<subscript>R</subscript> (E'<subscript>R</subscript> - E'<subscript>Y</subscript>) =
 206   0.5 E'<subscript>R</subscript>
 207 + 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>R</subscript>) E'<subscript>G</subscript>
 208 + 0.5 (Coeff<subscript>B</subscript> / Coeff<subscript>R</subscript>) E'<subscript>B</subscript></para>
 209           </listitem>
 210         </varlistentry>
 211         <varlistentry>
 212           <term>Quantization</term>
 213           <listitem>
 214             <para>[to do]</para>
 215             <para>Y' = (Lum. Levels - 1) &middot; E'<subscript>Y</subscript> + Lum. Offset</para>
 216             <para>C<subscript>B</subscript> = (Chrom. Levels - 1)
 217 &middot; P<subscript>B</subscript> + Chrom. Offset</para>
 218             <para>C<subscript>R</subscript> = (Chrom. Levels - 1)
 219 &middot; P<subscript>R</subscript> + Chrom. Offset</para>
 220             <para>Rounding to the nearest integer and clamping to the range
 221 [0;255] finally yields the digital color components Y'CbCr
 222 stored in YUV images.</para>
 223           </listitem>
 224         </varlistentry>
 225       </variablelist>
 226     </para>
 227
 228     <example>
 229       <title>ITU-R Rec. BT.601 color conversion</title>
 230
 231       <para>Forward Transformation</para>
 232
 233       <programlisting>
 234 int ER, EG, EB;         /* gamma corrected RGB input [0;255] */
 235 int Y1, Cb, Cr;         /* output [0;255] */
 236
 237 double r, g, b;         /* temporaries */
 238 double y1, pb, pr;
 239
 240 int
 241 clamp (double x)
 242 {
 243         int r = x;      /* round to nearest */
 244
 245         if (r &lt; 0)         return 0;
 246         else if (r &gt; 255)  return 255;
 247         else               return r;
 248 }
 249
 250 r = ER / 255.0;
 251 g = EG / 255.0;
 252 b = EB / 255.0;
 253
 254 y1  =  0.299  * r + 0.587 * g + 0.114  * b;
 255 pb  = -0.169  * r - 0.331 * g + 0.5    * b;
 256 pr  =  0.5    * r - 0.419 * g - 0.081  * b;
 257
 258 Y1 = clamp (219 * y1 + 16);
 259 Cb = clamp (224 * pb + 128);
 260 Cr = clamp (224 * pr + 128);
 261
 262 /* or shorter */
 263
 264 y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB;
 265
 266 Y1 = clamp ( (219 / 255.0)                    *       y1  + 16);
 267 Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128);
 268 Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128);
 269       </programlisting>
 270
 271       <para>Inverse Transformation</para>
 272
 273       <programlisting>
 274 int Y1, Cb, Cr;         /* gamma pre-corrected input [0;255] */
 275 int ER, EG, EB;         /* output [0;255] */
 276
 277 double r, g, b;         /* temporaries */
 278 double y1, pb, pr;
 279
 280 int
 281 clamp (double x)
 282 {
 283         int r = x;      /* round to nearest */
 284
 285         if (r &lt; 0)         return 0;
 286         else if (r &gt; 255)  return 255;
 287         else               return r;
 288 }
 289
 290 y1 = (255 / 219.0) * (Y1 - 16);
 291 pb = (255 / 224.0) * (Cb - 128);
 292 pr = (255 / 224.0) * (Cr - 128);
 293
 294 r = 1.0 * y1 + 0     * pb + 1.402 * pr;
 295 g = 1.0 * y1 - 0.344 * pb - 0.714 * pr;
 296 b = 1.0 * y1 + 1.772 * pb + 0     * pr;
 297
 298 ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */
 299 EG = clamp (g * 255);
 300 EB = clamp (b * 255);
 301       </programlisting>
 302     </example>
 303
 304     <table pgwide="1" id="v4l2-colorspace" orient="land">
 305       <title>enum v4l2_colorspace</title>
 306       <tgroup cols="11" align="center">
 307         <colspec align="left" />
 308         <colspec align="center" />
 309         <colspec align="left" />
 310         <colspec colname="cr" />
 311         <colspec colname="cg" />
 312         <colspec colname="cb" />
 313         <colspec colname="wp" />
 314         <colspec colname="gc" />
 315         <colspec colname="lum" />
 316         <colspec colname="qy" />
 317         <colspec colname="qc" />
 318         <spanspec namest="cr" nameend="cb" spanname="chrom" />
 319         <spanspec namest="qy" nameend="qc" spanname="quant" />
 320         <spanspec namest="lum" nameend="qc" spanname="spam" />
 321         <thead>
 322           <row>
 323             <entry morerows="1">Identifier</entry>
 324             <entry morerows="1">Value</entry>
 325             <entry morerows="1">Description</entry>
 326             <entry spanname="chrom">Chromaticities<footnote>
 327                 <para>The coordinates of the color primaries are
 328 given in the CIE system (1931)</para>
 329               </footnote></entry>
 330             <entry morerows="1">White Point</entry>
 331             <entry morerows="1">Gamma Correction</entry>
 332             <entry morerows="1">Luminance E'<subscript>Y</subscript></entry>
 333             <entry spanname="quant">Quantization</entry>
 334           </row>
 335           <row>
 336             <entry>Red</entry>
 337             <entry>Green</entry>
 338             <entry>Blue</entry>
 339             <entry>Y'</entry>
 340             <entry>Cb, Cr</entry>
 341           </row>
 342         </thead>
 343         <tbody valign="top">
 344           <row>
 345             <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry>
 346             <entry>1</entry>
 347             <entry>NTSC/PAL according to <xref linkend="smpte170m" />,
 348 <xref linkend="itu601" /></entry>
 349             <entry>x&nbsp;=&nbsp;0.630, y&nbsp;=&nbsp;0.340</entry>
 350             <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.595</entry>
 351             <entry>x&nbsp;=&nbsp;0.155, y&nbsp;=&nbsp;0.070</entry>
 352             <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
 353             Illuminant D<subscript>65</subscript></entry>
 354             <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
 355 1.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
 356             <entry>0.299&nbsp;E'<subscript>R</subscript>
 357 +&nbsp;0.587&nbsp;E'<subscript>G</subscript>
 358 +&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
 359             <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
 360             <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
 361           </row>
 362           <row>
 363             <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry>
 364             <entry>2</entry>
 365             <entry>1125-Line (US) HDTV, see <xref
 366 linkend="smpte240m" /></entry>
 367             <entry>x&nbsp;=&nbsp;0.630, y&nbsp;=&nbsp;0.340</entry>
 368             <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.595</entry>
 369             <entry>x&nbsp;=&nbsp;0.155, y&nbsp;=&nbsp;0.070</entry>
 370             <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
 371             Illuminant D<subscript>65</subscript></entry>
 372             <entry>E' = 4&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.0228,
 373 1.1115&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.1115&nbsp;for&nbsp;0.0228&nbsp;&lt;&nbsp;I</entry>
 374             <entry>0.212&nbsp;E'<subscript>R</subscript>
 375 +&nbsp;0.701&nbsp;E'<subscript>G</subscript>
 376 +&nbsp;0.087&nbsp;E'<subscript>B</subscript></entry>
 377             <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
 378             <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
 379           </row>
 380           <row>
 381             <entry><constant>V4L2_COLORSPACE_REC709</constant></entry>
 382             <entry>3</entry>
 383             <entry>HDTV and modern devices, see <xref
 384 linkend="itu709" /></entry>
 385             <entry>x&nbsp;=&nbsp;0.640, y&nbsp;=&nbsp;0.330</entry>
 386             <entry>x&nbsp;=&nbsp;0.300, y&nbsp;=&nbsp;0.600</entry>
 387             <entry>x&nbsp;=&nbsp;0.150, y&nbsp;=&nbsp;0.060</entry>
 388             <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
 389             Illuminant D<subscript>65</subscript></entry>
 390             <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
 391 1.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
 392             <entry>0.2125&nbsp;E'<subscript>R</subscript>
 393 +&nbsp;0.7154&nbsp;E'<subscript>G</subscript>
 394 +&nbsp;0.0721&nbsp;E'<subscript>B</subscript></entry>
 395             <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
 396             <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
 397           </row>
 398           <row>
 399             <entry><constant>V4L2_COLORSPACE_BT878</constant></entry>
 400             <entry>4</entry>
 401             <entry>Broken Bt878 extents<footnote>
 402                 <para>The ubiquitous Bt878 video capture chip
 403 quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range
 404 of Y' = 16 &hellip; 253, unlike Rec. 601 Y' = 16 &hellip;
 405 235. This is not a typo in the Bt878 documentation, it has been
 406 implemented in silicon. The chroma extents are unclear.</para>
 407               </footnote>, <xref linkend="itu601" /></entry>
 408             <entry>?</entry>
 409             <entry>?</entry>
 410             <entry>?</entry>
 411             <entry>?</entry>
 412             <entry>?</entry>
 413             <entry>0.299&nbsp;E'<subscript>R</subscript>
 414 +&nbsp;0.587&nbsp;E'<subscript>G</subscript>
 415 +&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
 416             <entry><emphasis>237</emphasis>&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
 417             <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128 (probably)</entry>
 418           </row>
 419           <row>
 420             <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry>
 421             <entry>5</entry>
 422             <entry>M/NTSC<footnote>
 423                 <para>No identifier exists for M/PAL which uses
 424 the chromaticities of M/NTSC, the remaining parameters are equal to B and
 425 G/PAL.</para>
 426               </footnote> according to <xref linkend="itu470" />, <xref
 427                 linkend="itu601" /></entry>
 428             <entry>x&nbsp;=&nbsp;0.67, y&nbsp;=&nbsp;0.33</entry>
 429             <entry>x&nbsp;=&nbsp;0.21, y&nbsp;=&nbsp;0.71</entry>
 430             <entry>x&nbsp;=&nbsp;0.14, y&nbsp;=&nbsp;0.08</entry>
 431             <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.316, Illuminant C</entry>
 432             <entry>?</entry>
 433             <entry>0.299&nbsp;E'<subscript>R</subscript>
 434 +&nbsp;0.587&nbsp;E'<subscript>G</subscript>
 435 +&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
 436             <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
 437             <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
 438           </row>
 439           <row>
 440             <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry>
 441             <entry>6</entry>
 442             <entry>625-line PAL and SECAM systems according to <xref
 443 linkend="itu470" />, <xref linkend="itu601" /></entry>
 444             <entry>x&nbsp;=&nbsp;0.64, y&nbsp;=&nbsp;0.33</entry>
 445             <entry>x&nbsp;=&nbsp;0.29, y&nbsp;=&nbsp;0.60</entry>
 446             <entry>x&nbsp;=&nbsp;0.15, y&nbsp;=&nbsp;0.06</entry>
 447             <entry>x&nbsp;=&nbsp;0.313, y&nbsp;=&nbsp;0.329,
 448 Illuminant D<subscript>65</subscript></entry>
 449             <entry>?</entry>
 450             <entry>0.299&nbsp;E'<subscript>R</subscript>
 451 +&nbsp;0.587&nbsp;E'<subscript>G</subscript>
 452 +&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
 453             <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
 454             <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
 455           </row>
 456           <row>
 457             <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry>
 458             <entry>7</entry>
 459             <entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry>
 460             <entry>?</entry>
 461             <entry>?</entry>
 462             <entry>?</entry>
 463             <entry>?</entry>
 464             <entry>?</entry>
 465             <entry>0.299&nbsp;E'<subscript>R</subscript>
 466 +&nbsp;0.587&nbsp;E'<subscript>G</subscript>
 467 +&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
 468             <entry>256&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16<footnote>
 469                 <para>Note JFIF quantizes
 470 Y'P<subscript>B</subscript>P<subscript>R</subscript> in range [0;+1] and
 471 [-0.5;+0.5] to <emphasis>257</emphasis> levels, however Y'CbCr signals
 472 are still clamped to [0;255].</para>
 473               </footnote></entry>
 474             <entry>256&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
 475           </row>
 476           <row>
 477             <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry>
 478             <entry>8</entry>
 479             <entry>[?]</entry>
 480             <entry>x&nbsp;=&nbsp;0.640, y&nbsp;=&nbsp;0.330</entry>
 481             <entry>x&nbsp;=&nbsp;0.300, y&nbsp;=&nbsp;0.600</entry>
 482             <entry>x&nbsp;=&nbsp;0.150, y&nbsp;=&nbsp;0.060</entry>
 483             <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
 484             Illuminant D<subscript>65</subscript></entry>
 485             <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
 486 1.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
 487             <entry spanname="spam">n/a</entry>
 488           </row>
 489         </tbody>
 490       </tgroup>
 491     </table>
 492   </section>
 493
 494   <section id="pixfmt-indexed">
 495     <title>Indexed Format</title>
 496
 497     <para>In this format each pixel is represented by an 8 bit index
 498 into a 256 entry ARGB palette. It is intended for <link
 499 linkend="osd">Video Output Overlays</link> only. There are no ioctls to
 500 access the palette, this must be done with ioctls of the Linux framebuffer API.</para>
 501
 502     <table pgwide="0" frame="none">
 503       <title>Indexed Image Format</title>
 504       <tgroup cols="37" align="center">
 505         <colspec colname="id" align="left" />
 506         <colspec colname="fourcc" />
 507         <colspec colname="bit" />
 508
 509         <colspec colnum="4" colname="b07" align="center" />
 510         <colspec colnum="5" colname="b06" align="center" />
 511         <colspec colnum="6" colname="b05" align="center" />
 512         <colspec colnum="7" colname="b04" align="center" />
 513         <colspec colnum="8" colname="b03" align="center" />
 514         <colspec colnum="9" colname="b02" align="center" />
 515         <colspec colnum="10" colname="b01" align="center" />
 516         <colspec colnum="11" colname="b00" align="center" />
 517
 518         <spanspec namest="b07" nameend="b00" spanname="b0" />
 519         <spanspec namest="b17" nameend="b10" spanname="b1" />
 520         <spanspec namest="b27" nameend="b20" spanname="b2" />
 521         <spanspec namest="b37" nameend="b30" spanname="b3" />
 522         <thead>
 523           <row>
 524             <entry>Identifier</entry>
 525             <entry>Code</entry>
 526             <entry>&nbsp;</entry>
 527             <entry spanname="b0">Byte&nbsp;0</entry>
 528           </row>
 529           <row>
 530             <entry>&nbsp;</entry>
 531             <entry>&nbsp;</entry>
 532             <entry>Bit</entry>
 533             <entry>7</entry>
 534             <entry>6</entry>
 535             <entry>5</entry>
 536             <entry>4</entry>
 537             <entry>3</entry>
 538             <entry>2</entry>
 539             <entry>1</entry>
 540             <entry>0</entry>
 541           </row>
 542         </thead>
 543         <tbody valign="top">
 544           <row id="V4L2-PIX-FMT-PAL8">
 545             <entry><constant>V4L2_PIX_FMT_PAL8</constant></entry>
 546             <entry>'PAL8'</entry>
 547             <entry></entry>
 548             <entry>i<subscript>7</subscript></entry>
 549             <entry>i<subscript>6</subscript></entry>
 550             <entry>i<subscript>5</subscript></entry>
 551             <entry>i<subscript>4</subscript></entry>
 552             <entry>i<subscript>3</subscript></entry>
 553             <entry>i<subscript>2</subscript></entry>
 554             <entry>i<subscript>1</subscript></entry>
 555             <entry>i<subscript>0</subscript></entry>
 556           </row>
 557         </tbody>
 558       </tgroup>
 559     </table>
 560   </section>
 561
 562   <section id="pixfmt-rgb">
 563     <title>RGB Formats</title>
 564
 565     &sub-packed-rgb;
 566     &sub-sbggr8;
 567     &sub-sgbrg8;
 568     &sub-sgrbg8;
 569     &sub-sbggr16;
 570   </section>
 571
 572   <section id="yuv-formats">
 573     <title>YUV Formats</title>
 574
 575     <para>YUV is the format native to TV broadcast and composite video
 576 signals. It separates the brightness information (Y) from the color
 577 information (U and V or Cb and Cr). The color information consists of
 578 red and blue <emphasis>color difference</emphasis> signals, this way
 579 the green component can be reconstructed by subtracting from the
 580 brightness component. See <xref linkend="colorspaces" /> for conversion
 581 examples. YUV was chosen because early television would only transmit
 582 brightness information. To add color in a way compatible with existing
 583 receivers a new signal carrier was added to transmit the color
 584 difference signals. Secondary in the YUV format the U and V components
 585 usually have lower resolution than the Y component. This is an analog
 586 video compression technique taking advantage of a property of the
 587 human visual system, being more sensitive to brightness
 588 information.</para>
 589
 590     &sub-packed-yuv;
 591     &sub-grey;
 592     &sub-y16;
 593     &sub-yuyv;
 594     &sub-uyvy;
 595     &sub-yvyu;
 596     &sub-vyuy;
 597     &sub-y41p;
 598     &sub-yuv420;
 599     &sub-yuv410;
 600     &sub-yuv422p;
 601     &sub-yuv411p;
 602     &sub-nv12;
 603     &sub-nv16;
 604   </section>
 605
 606   <section>
 607     <title>Compressed Formats</title>
 608
 609     <table pgwide="1" frame="none" id="compressed-formats">
 610       <title>Compressed Image Formats</title>
 611       <tgroup cols="3" align="left">
 612         &cs-def;
 613         <thead>
 614           <row>
 615             <entry>Identifier</entry>
 616             <entry>Code</entry>
 617             <entry>Details</entry>
 618           </row>
 619         </thead>
 620         <tbody valign="top">
 621          <row id="V4L2-PIX-FMT-JPEG">
 622             <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry>
 623             <entry>'JPEG'</entry>
 624             <entry>TBD. See also &VIDIOC-G-JPEGCOMP;,
 625             &VIDIOC-S-JPEGCOMP;.</entry>
 626           </row>
 627           <row id="V4L2-PIX-FMT-MPEG">
 628             <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry>
 629             <entry>'MPEG'</entry>
 630             <entry>MPEG stream. The actual format is determined by
 631 extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
 632 <xref linkend="mpeg-control-id" />.</entry>
 633           </row>
 634         </tbody>
 635       </tgroup>
 636     </table>
 637   </section>
 638
 639   <section id="pixfmt-reserved">
 640     <title>Reserved Format Identifiers</title>
 641
 642     <para>These formats are not defined by this specification, they
 643 are just listed for reference and to avoid naming conflicts. If you
 644 want to register your own format, send an e-mail to the linux-media mailing
 645 list &v4l-ml; for inclusion in the <filename>videodev2.h</filename>
 646 file. If you want to share your format with other developers add a
 647 link to your documentation and send a copy to the linux-media mailing list
 648 for inclusion in this section. If you think your format should be listed
 649 in a standard format section please make a proposal on the linux-media mailing
 650 list.</para>
 651
 652     <table pgwide="1" frame="none" id="reserved-formats">
 653       <title>Reserved Image Formats</title>
 654       <tgroup cols="3" align="left">
 655         &cs-def;
 656         <thead>
 657           <row>
 658             <entry>Identifier</entry>
 659             <entry>Code</entry>
 660             <entry>Details</entry>
 661           </row>
 662         </thead>
 663         <tbody valign="top">
 664           <row id="V4L2-PIX-FMT-DV">
 665             <entry><constant>V4L2_PIX_FMT_DV</constant></entry>
 666             <entry>'dvsd'</entry>
 667             <entry>unknown</entry>
 668           </row>
 669           <row id="V4L2-PIX-FMT-ET61X251">
 670             <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry>
 671             <entry>'E625'</entry>
 672             <entry>Compressed format of the ET61X251 driver.</entry>
 673           </row>
 674           <row id="V4L2-PIX-FMT-HI240">
 675             <entry><constant>V4L2_PIX_FMT_HI240</constant></entry>
 676             <entry>'HI24'</entry>
 677             <entry><para>8 bit RGB format used by the BTTV driver.</para></entry>
 678           </row>
 679           <row id="V4L2-PIX-FMT-HM12">
 680             <entry><constant>V4L2_PIX_FMT_HM12</constant></entry>
 681             <entry>'HM12'</entry>
 682             <entry><para>YUV 4:2:0 format used by the
 683 IVTV driver, <ulink url="http://www.ivtvdriver.org/">
 684 http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the
 685 kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename>
 686 </para></entry>
 687           </row>
 688           <row id="V4L2-PIX-FMT-SPCA501">
 689             <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry>
 690             <entry>'S501'</entry>
 691             <entry>YUYV per line used by the gspca driver.</entry>
 692           </row>
 693           <row id="V4L2-PIX-FMT-SPCA505">
 694             <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry>
 695             <entry>'S505'</entry>
 696             <entry>YYUV per line used by the gspca driver.</entry>
 697           </row>
 698           <row id="V4L2-PIX-FMT-SPCA508">
 699             <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry>
 700             <entry>'S508'</entry>
 701             <entry>YUVY per line used by the gspca driver.</entry>
 702           </row>
 703           <row id="V4L2-PIX-FMT-SPCA561">
 704             <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry>
 705             <entry>'S561'</entry>
 706             <entry>Compressed GBRG Bayer format used by the gspca driver.</entry>
 707           </row>
 708           <row id="V4L2-PIX-FMT-SGRBG10">
 709             <entry><constant>V4L2_PIX_FMT_SGRBG10</constant></entry>
 710             <entry>'DA10'</entry>
 711             <entry>10 bit raw Bayer, expanded to 16 bits.</entry>
 712           </row>
 713           <row id="V4L2-PIX-FMT-SGRBG10DPCM8">
 714             <entry><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></entry>
 715             <entry>'DB10'</entry>
 716             <entry>10 bit raw Bayer DPCM compressed to 8 bits.</entry>
 717           </row>
 718           <row id="V4L2-PIX-FMT-PAC207">
 719             <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry>
 720             <entry>'P207'</entry>
 721             <entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
 722           </row>
 723           <row id="V4L2-PIX-FMT-MR97310A">
 724             <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry>
 725             <entry>'M310'</entry>
 726             <entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
 727           </row>
 728           <row id="V4L2-PIX-FMT-OV511">
 729             <entry><constant>V4L2_PIX_FMT_OV511</constant></entry>
 730             <entry>'O511'</entry>
 731             <entry>OV511 JPEG format used by the gspca driver.</entry>
 732           </row>
 733           <row id="V4L2-PIX-FMT-OV518">
 734             <entry><constant>V4L2_PIX_FMT_OV518</constant></entry>
 735             <entry>'O518'</entry>
 736             <entry>OV518 JPEG format used by the gspca driver.</entry>
 737           </row>
 738           <row id="V4L2-PIX-FMT-PJPG">
 739             <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry>
 740             <entry>'PJPG'</entry>
 741             <entry>Pixart 73xx JPEG format used by the gspca driver.</entry>
 742           </row>
 743           <row id="V4L2-PIX-FMT-SQ905C">
 744             <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry>
 745             <entry>'905C'</entry>
 746             <entry>Compressed RGGB bayer format used by the gspca driver.</entry>
 747           </row>
 748           <row id="V4L2-PIX-FMT-MJPEG">
 749             <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry>
 750             <entry>'MJPG'</entry>
 751             <entry>Compressed format used by the Zoran driver</entry>
 752           </row>
 753           <row id="V4L2-PIX-FMT-PWC1">
 754             <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry>
 755             <entry>'PWC1'</entry>
 756             <entry>Compressed format of the PWC driver.</entry>
 757           </row>
 758           <row id="V4L2-PIX-FMT-PWC2">
 759             <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry>
 760             <entry>'PWC2'</entry>
 761             <entry>Compressed format of the PWC driver.</entry>
 762           </row>
 763           <row id="V4L2-PIX-FMT-SN9C10X">
 764             <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry>
 765             <entry>'S910'</entry>
 766             <entry>Compressed format of the SN9C102 driver.</entry>
 767           </row>
 768           <row id="V4L2-PIX-FMT-SN9C20X-I420">
 769             <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry>
 770             <entry>'S920'</entry>
 771             <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry>
 772           </row>
 773           <row id="V4L2-PIX-FMT-STV0680">
 774             <entry><constant>V4L2_PIX_FMT_STV0680</constant></entry>
 775             <entry>'S680'</entry>
 776             <entry>Bayer format of the gspca stv0680 driver.</entry>
 777           </row>
 778           <row id="V4L2-PIX-FMT-WNVA">
 779             <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry>
 780             <entry>'WNVA'</entry>
 781             <entry><para>Used by the Winnov Videum driver, <ulink
 782 url="http://www.thedirks.org/winnov/">
 783 http://www.thedirks.org/winnov/</ulink></para></entry>
 784           </row>
 785           <row id="V4L2-PIX-FMT-TM6000">
 786             <entry><constant>V4L2_PIX_FMT_TM6000</constant></entry>
 787             <entry>'TM60'</entry>
 788             <entry><para>Used by Trident tm6000</para></entry>
 789           </row>
 790           <row id="V4L2-PIX-FMT-YYUV">
 791             <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry>
 792             <entry>'YYUV'</entry>
 793             <entry>unknown</entry>
 794           </row>
 795         </tbody>
 796       </tgroup>
 797     </table>
 798   </section>
 799
 800   <!--
 801 Local Variables:
 802 mode: sgml
 803 sgml-parent-document: "v4l2.sgml"
 804 indent-tabs-mode: nil
 805 End:
 806   -->