1 <title>Image Formats</title> 2 3 <para>The V4L2 API was primarily designed for devices exchanging 4image data with applications. The 5<structname>v4l2_pix_format</structname> and <structname>v4l2_pix_format_mplane 6</structname> structures define the format and layout of an image in memory. 7The former is used with the single-planar API, while the latter is used with the 8multi-planar version (see <xref linkend="planar-apis"/>). Image formats are 9negotiated with the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video 10capturing and output, for overlay frame buffer formats see also 11&VIDIOC-G-FBUF;.)</para> 12 13<section> 14 <title>Single-planar format structure</title> 15 <table pgwide="1" frame="none" id="v4l2-pix-format"> 16 <title>struct <structname>v4l2_pix_format</structname></title> 17 <tgroup cols="3"> 18 &cs-str; 19 <tbody valign="top"> 20 <row> 21 <entry>__u32</entry> 22 <entry><structfield>width</structfield></entry> 23 <entry>Image width in pixels.</entry> 24 </row> 25 <row> 26 <entry>__u32</entry> 27 <entry><structfield>height</structfield></entry> 28 <entry>Image height in pixels. If <structfield>field</structfield> is 29 one of <constant>V4L2_FIELD_TOP</constant>, <constant>V4L2_FIELD_BOTTOM</constant> 30 or <constant>V4L2_FIELD_ALTERNATE</constant> then height refers to the 31 number of lines in the field, otherwise it refers to the number of 32 lines in the frame (which is twice the field height for interlaced 33 formats).</entry> 34 </row> 35 <row> 36 <entry spanname="hspan">Applications set these fields to 37request an image size, drivers return the closest possible values. In 38case of planar formats the <structfield>width</structfield> and 39<structfield>height</structfield> applies to the largest plane. To 40avoid ambiguities drivers must return values rounded up to a multiple 41of the scale factor of any smaller planes. For example when the image 42format is YUV 4:2:0, <structfield>width</structfield> and 43<structfield>height</structfield> must be multiples of two.</entry> 44 </row> 45 <row> 46 <entry>__u32</entry> 47 <entry><structfield>pixelformat</structfield></entry> 48 <entry>The pixel format or type of compression, set by the 49application. This is a little endian <link 50linkend="v4l2-fourcc">four character code</link>. V4L2 defines 51standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref 52linkend="yuv-formats" />, and reserved codes in <xref 53linkend="reserved-formats" /></entry> 54 </row> 55 <row> 56 <entry>&v4l2-field;</entry> 57 <entry><structfield>field</structfield></entry> 58 <entry>Video images are typically interlaced. Applications 59can request to capture or output only the top or bottom field, or both 60fields interlaced or sequentially stored in one buffer or alternating 61in separate buffers. Drivers return the actual field order selected. 62For more details on fields see <xref linkend="field-order" />.</entry> 63 </row> 64 <row> 65 <entry>__u32</entry> 66 <entry><structfield>bytesperline</structfield></entry> 67 <entry>Distance in bytes between the leftmost pixels in two 68adjacent lines.</entry> 69 </row> 70 <row> 71 <entry spanname="hspan"><para>Both applications and drivers 72can set this field to request padding bytes at the end of each line. 73Drivers however may ignore the value requested by the application, 74returning <structfield>width</structfield> times bytes per pixel or a 75larger value required by the hardware. That implies applications can 76just set this field to zero to get a reasonable 77default.</para><para>Video hardware may access padding bytes, 78therefore they must reside in accessible memory. Consider cases where 79padding bytes after the last line of an image cross a system page 80boundary. Input devices may write padding bytes, the value is 81undefined. Output devices ignore the contents of padding 82bytes.</para><para>When the image format is planar the 83<structfield>bytesperline</structfield> value applies to the first 84plane and is divided by the same factor as the 85<structfield>width</structfield> field for the other planes. For 86example the Cb and Cr planes of a YUV 4:2:0 image have half as many 87padding bytes following each line as the Y plane. To avoid ambiguities 88drivers must return a <structfield>bytesperline</structfield> value 89rounded up to a multiple of the scale factor.</para> 90<para>For compressed formats the <structfield>bytesperline</structfield> 91value makes no sense. Applications and drivers must set this to 0 in 92that case.</para></entry> 93 </row> 94 <row> 95 <entry>__u32</entry> 96 <entry><structfield>sizeimage</structfield></entry> 97 <entry>Size in bytes of the buffer to hold a complete image, 98set by the driver. Usually this is 99<structfield>bytesperline</structfield> times 100<structfield>height</structfield>. When the image consists of variable 101length compressed data this is the maximum number of bytes required to 102hold an image.</entry> 103 </row> 104 <row> 105 <entry>&v4l2-colorspace;</entry> 106 <entry><structfield>colorspace</structfield></entry> 107 <entry>This information supplements the 108<structfield>pixelformat</structfield> and must be set by the driver for 109capture streams and by the application for output streams, 110see <xref linkend="colorspaces" />.</entry> 111 </row> 112 <row> 113 <entry>__u32</entry> 114 <entry><structfield>priv</structfield></entry> 115 <entry><para>This field indicates whether the remaining fields of the 116<structname>v4l2_pix_format</structname> structure, also called the extended 117fields, are valid. When set to <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, it 118indicates that the extended fields have been correctly initialized. When set to 119any other value it indicates that the extended fields contain undefined values. 120</para> 121<para>Applications that wish to use the pixel format extended fields must first 122ensure that the feature is supported by querying the device for the 123<link linkend="querycap"><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></link> 124capability. If the capability isn't set the pixel format extended fields are not 125supported and using the extended fields will lead to undefined results.</para> 126<para>To use the extended fields, applications must set the 127<structfield>priv</structfield> field to 128<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, initialize all the extended fields 129and zero the unused bytes of the <structname>v4l2_format</structname> 130<structfield>raw_data</structfield> field.</para> 131<para>When the <structfield>priv</structfield> field isn't set to 132<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> drivers must act as if all the 133extended fields were set to zero. On return drivers must set the 134<structfield>priv</structfield> field to 135<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> and all the extended fields to 136applicable values.</para></entry> 137 </row> 138 <row> 139 <entry>__u32</entry> 140 <entry><structfield>flags</structfield></entry> 141 <entry>Flags set by the application or driver, see <xref 142linkend="format-flags" />.</entry> 143 </row> 144 <row> 145 <entry>&v4l2-ycbcr-encoding;</entry> 146 <entry><structfield>ycbcr_enc</structfield></entry> 147 <entry>This information supplements the 148<structfield>colorspace</structfield> and must be set by the driver for 149capture streams and by the application for output streams, 150see <xref linkend="colorspaces" />.</entry> 151 </row> 152 <row> 153 <entry>&v4l2-quantization;</entry> 154 <entry><structfield>quantization</structfield></entry> 155 <entry>This information supplements the 156<structfield>colorspace</structfield> and must be set by the driver for 157capture streams and by the application for output streams, 158see <xref linkend="colorspaces" />.</entry> 159 </row> 160 </tbody> 161 </tgroup> 162 </table> 163</section> 164 165<section> 166 <title>Multi-planar format structures</title> 167 <para>The <structname>v4l2_plane_pix_format</structname> structures define 168 size and layout for each of the planes in a multi-planar format. 169 The <structname>v4l2_pix_format_mplane</structname> structure contains 170 information common to all planes (such as image width and height) and 171 an array of <structname>v4l2_plane_pix_format</structname> structures, 172 describing all planes of that format.</para> 173 <table pgwide="1" frame="none" id="v4l2-plane-pix-format"> 174 <title>struct <structname>v4l2_plane_pix_format</structname></title> 175 <tgroup cols="3"> 176 &cs-str; 177 <tbody valign="top"> 178 <row> 179 <entry>__u32</entry> 180 <entry><structfield>sizeimage</structfield></entry> 181 <entry>Maximum size in bytes required for image data in this plane. 182 </entry> 183 </row> 184 <row> 185 <entry>__u32</entry> 186 <entry><structfield>bytesperline</structfield></entry> 187 <entry>Distance in bytes between the leftmost pixels in two adjacent 188 lines. See &v4l2-pix-format;.</entry> 189 </row> 190 <row> 191 <entry>__u16</entry> 192 <entry><structfield>reserved[6]</structfield></entry> 193 <entry>Reserved for future extensions. Should be zeroed by the 194 application.</entry> 195 </row> 196 </tbody> 197 </tgroup> 198 </table> 199 <table pgwide="1" frame="none" id="v4l2-pix-format-mplane"> 200 <title>struct <structname>v4l2_pix_format_mplane</structname></title> 201 <tgroup cols="3"> 202 &cs-str; 203 <tbody valign="top"> 204 <row> 205 <entry>__u32</entry> 206 <entry><structfield>width</structfield></entry> 207 <entry>Image width in pixels. See &v4l2-pix-format;.</entry> 208 </row> 209 <row> 210 <entry>__u32</entry> 211 <entry><structfield>height</structfield></entry> 212 <entry>Image height in pixels. See &v4l2-pix-format;.</entry> 213 </row> 214 <row> 215 <entry>__u32</entry> 216 <entry><structfield>pixelformat</structfield></entry> 217 <entry>The pixel format. Both single- and multi-planar four character 218codes can be used.</entry> 219 </row> 220 <row> 221 <entry>&v4l2-field;</entry> 222 <entry><structfield>field</structfield></entry> 223 <entry>See &v4l2-pix-format;.</entry> 224 </row> 225 <row> 226 <entry>&v4l2-colorspace;</entry> 227 <entry><structfield>colorspace</structfield></entry> 228 <entry>See &v4l2-pix-format;.</entry> 229 </row> 230 <row> 231 <entry>&v4l2-plane-pix-format;</entry> 232 <entry><structfield>plane_fmt[VIDEO_MAX_PLANES]</structfield></entry> 233 <entry>An array of structures describing format of each plane this 234 pixel format consists of. The number of valid entries in this array 235 has to be put in the <structfield>num_planes</structfield> 236 field.</entry> 237 </row> 238 <row> 239 <entry>__u8</entry> 240 <entry><structfield>num_planes</structfield></entry> 241 <entry>Number of planes (i.e. separate memory buffers) for this format 242 and the number of valid entries in the 243 <structfield>plane_fmt</structfield> array.</entry> 244 </row> 245 <row> 246 <entry>__u8</entry> 247 <entry><structfield>flags</structfield></entry> 248 <entry>Flags set by the application or driver, see <xref 249linkend="format-flags" />.</entry> 250 </row> 251 <row> 252 <entry>&v4l2-ycbcr-encoding;</entry> 253 <entry><structfield>ycbcr_enc</structfield></entry> 254 <entry>This information supplements the 255<structfield>colorspace</structfield> and must be set by the driver for 256capture streams and by the application for output streams, 257see <xref linkend="colorspaces" />.</entry> 258 </row> 259 <row> 260 <entry>&v4l2-quantization;</entry> 261 <entry><structfield>quantization</structfield></entry> 262 <entry>This information supplements the 263<structfield>colorspace</structfield> and must be set by the driver for 264capture streams and by the application for output streams, 265see <xref linkend="colorspaces" />.</entry> 266 </row> 267 <row> 268 <entry>__u8</entry> 269 <entry><structfield>reserved[8]</structfield></entry> 270 <entry>Reserved for future extensions. Should be zeroed by the 271 application.</entry> 272 </row> 273 </tbody> 274 </tgroup> 275 </table> 276</section> 277 278 <section> 279 <title>Standard Image Formats</title> 280 281 <para>In order to exchange images between drivers and 282applications, it is necessary to have standard image data formats 283which both sides will interpret the same way. V4L2 includes several 284such formats, and this section is intended to be an unambiguous 285specification of the standard image data formats in V4L2.</para> 286 287 <para>V4L2 drivers are not limited to these formats, however. 288Driver-specific formats are possible. In that case the application may 289depend on a codec to convert images to one of the standard formats 290when needed. But the data can still be stored and retrieved in the 291proprietary format. For example, a device may support a proprietary 292compressed format. Applications can still capture and save the data in 293the compressed format, saving much disk space, and later use a codec 294to convert the images to the X Windows screen format when the video is 295to be displayed.</para> 296 297 <para>Even so, ultimately, some standard formats are needed, so 298the V4L2 specification would not be complete without well-defined 299standard formats.</para> 300 301 <para>The V4L2 standard formats are mainly uncompressed formats. The 302pixels are always arranged in memory from left to right, and from top 303to bottom. The first byte of data in the image buffer is always for 304the leftmost pixel of the topmost row. Following that is the pixel 305immediately to its right, and so on until the end of the top row of 306pixels. Following the rightmost pixel of the row there may be zero or 307more bytes of padding to guarantee that each row of pixel data has a 308certain alignment. Following the pad bytes, if any, is data for the 309leftmost pixel of the second row from the top, and so on. The last row 310has just as many pad bytes after it as the other rows.</para> 311 312 <para>In V4L2 each format has an identifier which looks like 313<constant>PIX_FMT_XXX</constant>, defined in the <link 314linkend="videodev">videodev2.h</link> header file. These identifiers 315represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link> 316which are also listed below, however they are not the same as those 317used in the Windows world.</para> 318 319 <para>For some formats, data is stored in separate, discontiguous 320memory buffers. Those formats are identified by a separate set of FourCC codes 321and are referred to as "multi-planar formats". For example, a YUV422 frame is 322normally stored in one memory buffer, but it can also be placed in two or three 323separate buffers, with Y component in one buffer and CbCr components in another 324in the 2-planar version or with each component in its own buffer in the 3253-planar case. Those sub-buffers are referred to as "planes".</para> 326 </section> 327 328 <section id="colorspaces"> 329 <title>Colorspaces</title> 330 331 <para>'Color' is a very complex concept and depends on physics, chemistry and 332biology. Just because you have three numbers that describe the 'red', 'green' 333and 'blue' components of the color of a pixel does not mean that you can accurately 334display that color. A colorspace defines what it actually <emphasis>means</emphasis> 335to have an RGB value of e.g. (255, 0, 0). That is, which color should be 336reproduced on the screen in a perfectly calibrated environment.</para> 337 338 <para>In order to do that we first need to have a good definition of 339color, i.e. some way to uniquely and unambiguously define a color so that someone 340else can reproduce it. Human color vision is trichromatic since the human eye has 341color receptors that are sensitive to three different wavelengths of light. Hence 342the need to use three numbers to describe color. Be glad you are not a mantis shrimp 343as those are sensitive to 12 different wavelengths, so instead of RGB we would be 344using the ABCDEFGHIJKL colorspace...</para> 345 346 <para>Color exists only in the eye and brain and is the result of how strongly 347color receptors are stimulated. This is based on the Spectral 348Power Distribution (SPD) which is a graph showing the intensity (radiant power) 349of the light at wavelengths covering the visible spectrum as it enters the eye. 350The science of colorimetry is about the relationship between the SPD and color as 351perceived by the human brain.</para> 352 353 <para>Since the human eye has only three color receptors it is perfectly 354possible that different SPDs will result in the same stimulation of those receptors 355and are perceived as the same color, even though the SPD of the light is 356different.</para> 357 358 <para>In the 1920s experiments were devised to determine the relationship 359between SPDs and the perceived color and that resulted in the CIE 1931 standard 360that defines spectral weighting functions that model the perception of color. 361Specifically that standard defines functions that can take an SPD and calculate 362the stimulus for each color receptor. After some further mathematical transforms 363these stimuli are known as the <emphasis>CIE XYZ tristimulus</emphasis> values 364and these X, Y and Z values describe a color as perceived by a human unambiguously. 365These X, Y and Z values are all in the range [0…1].</para> 366 367 <para>The Y value in the CIE XYZ colorspace corresponds to luminance. Often 368the CIE XYZ colorspace is transformed to the normalized CIE xyY colorspace:</para> 369 370 <para>x = X / (X + Y + Z)</para> 371 <para>y = Y / (X + Y + Z)</para> 372 373 <para>The x and y values are the chromaticity coordinates and can be used to 374define a color without the luminance component Y. It is very confusing to 375have such similar names for these colorspaces. Just be aware that if colors 376are specified with lower case 'x' and 'y', then the CIE xyY colorspace is 377used. Upper case 'X' and 'Y' refer to the CIE XYZ colorspace. Also, y has nothing 378to do with luminance. Together x and y specify a color, and Y the luminance. 379That is really all you need to remember from a practical point of view. At 380the end of this section you will find reading resources that go into much more 381detail if you are interested. 382</para> 383 384 <para>A monitor or TV will reproduce colors by emitting light at three 385different wavelengths, the combination of which will stimulate the color receptors 386in the eye and thus cause the perception of color. Historically these wavelengths 387were defined by the red, green and blue phosphors used in the displays. These 388<emphasis>color primaries</emphasis> are part of what defines a colorspace.</para> 389 390 <para>Different display devices will have different primaries and some 391primaries are more suitable for some display technologies than others. This has 392resulted in a variety of colorspaces that are used for different display 393technologies or uses. To define a colorspace you need to define the three 394color primaries (these are typically defined as x, y chromaticity coordinates 395from the CIE xyY colorspace) but also the white reference: that is the color obtained 396when all three primaries are at maximum power. This determines the relative power 397or energy of the primaries. This is usually chosen to be close to daylight which has 398been defined as the CIE D65 Illuminant.</para> 399 400 <para>To recapitulate: the CIE XYZ colorspace uniquely identifies colors. 401Other colorspaces are defined by three chromaticity coordinates defined in the 402CIE xyY colorspace. Based on those a 3x3 matrix can be constructed that 403transforms CIE XYZ colors to colors in the new colorspace. 404</para> 405 406 <para>Both the CIE XYZ and the RGB colorspace that are derived from the 407specific chromaticity primaries are linear colorspaces. But neither the eye, 408nor display technology is linear. Doubling the values of all components in 409the linear colorspace will not be perceived as twice the intensity of the color. 410So each colorspace also defines a transfer function that takes a linear color 411component value and transforms it to the non-linear component value, which is a 412closer match to the non-linear performance of both the eye and displays. Linear 413component values are denoted RGB, non-linear are denoted as R'G'B'. In general 414colors used in graphics are all R'G'B', except in openGL which uses linear RGB. 415Special care should be taken when dealing with openGL to provide linear RGB colors 416or to use the built-in openGL support to apply the inverse transfer function.</para> 417 418 <para>The final piece that defines a colorspace is a function that 419transforms non-linear R'G'B' to non-linear Y'CbCr. This function is determined 420by the so-called luma coefficients. There may be multiple possible Y'CbCr 421encodings allowed for the same colorspace. Many encodings of color 422prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the human 423eye is more sensitive to differences in luminance than in color this encoding 424allows one to reduce the amount of color information compared to the luma 425data. Note that the luma (Y') is unrelated to the Y in the CIE XYZ colorspace. 426Also note that Y'CbCr is often called YCbCr or YUV even though these are 427strictly speaking wrong.</para> 428 429 <para>Sometimes people confuse Y'CbCr as being a colorspace. This is not 430correct, it is just an encoding of an R'G'B' color into luma and chroma 431values. The underlying colorspace that is associated with the R'G'B' color 432is also associated with the Y'CbCr color.</para> 433 434 <para>The final step is how the RGB, R'G'B' or Y'CbCr values are 435quantized. The CIE XYZ colorspace where X, Y and Z are in the range 436[0…1] describes all colors that humans can perceive, but the transform to 437another colorspace will produce colors that are outside the [0…1] range. 438Once clamped to the [0…1] range those colors can no longer be reproduced 439in that colorspace. This clamping is what reduces the extent or gamut of the 440colorspace. How the range of [0…1] is translated to integer values in the 441range of [0…255] (or higher, depending on the color depth) is called the 442quantization. This is <emphasis>not</emphasis> part of the colorspace 443definition. In practice RGB or R'G'B' values are full range, i.e. they 444use the full [0…255] range. Y'CbCr values on the other hand are limited 445range with Y' using [16…235] and Cb and Cr using [16…240].</para> 446 447 <para>Unfortunately, in some cases limited range RGB is also used 448where the components use the range [16…235]. And full range Y'CbCr also exists 449using the [0…255] range.</para> 450 451 <para>In order to correctly interpret a color you need to know the 452quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr encoding 453and the colorspace. 454From that information you can calculate the corresponding CIE XYZ color 455and map that again to whatever colorspace your display device uses.</para> 456 457 <para>The colorspace definition itself consists of the three 458chromaticity primaries, the white reference chromaticity, a transfer 459function and the luma coefficients needed to transform R'G'B' to Y'CbCr. While 460some colorspace standards correctly define all four, quite often the colorspace 461standard only defines some, and you have to rely on other standards for 462the missing pieces. The fact that colorspaces are often a mix of different 463standards also led to very confusing naming conventions where the name of 464a standard was used to name a colorspace when in fact that standard was 465part of various other colorspaces as well.</para> 466 467 <para>If you want to read more about colors and colorspaces, then the 468following resources are useful: <xref linkend="poynton" /> is a good practical 469book for video engineers, <xref linkend="colimg" /> has a much broader scope and 470describes many more aspects of color (physics, chemistry, biology, etc.). 471The <ulink url="http://www.brucelindbloom.com">http://www.brucelindbloom.com</ulink> 472website is an excellent resource, especially with respect to the mathematics behind 473colorspace conversions. The wikipedia <ulink url="http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space">CIE 1931 colorspace</ulink> article 474is also very useful.</para> 475 </section> 476 477 <section> 478 <title>Defining Colorspaces in V4L2</title> 479 <para>In V4L2 colorspaces are defined by three values. The first is the colorspace 480identifier (&v4l2-colorspace;) which defines the chromaticities, the transfer 481function, the default Y'CbCr encoding and the default quantization method. The second 482is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;) to specify non-standard 483Y'CbCr encodings and the third is the quantization identifier (&v4l2-quantization;) 484to specify non-standard quantization methods. Most of the time only the colorspace 485field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to be filled in. Note 486that the default R'G'B' quantization is full range for all colorspaces except for 487BT.2020 which uses limited range R'G'B' quantization.</para> 488 489 <table pgwide="1" frame="none" id="v4l2-colorspace"> 490 <title>V4L2 Colorspaces</title> 491 <tgroup cols="2" align="left"> 492 &cs-def; 493 <thead> 494 <row> 495 <entry>Identifier</entry> 496 <entry>Details</entry> 497 </row> 498 </thead> 499 <tbody valign="top"> 500 <row> 501 <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> 502 <entry>See <xref linkend="col-smpte-170m" />.</entry> 503 </row> 504 <row> 505 <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> 506 <entry>See <xref linkend="col-rec709" />.</entry> 507 </row> 508 <row> 509 <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> 510 <entry>See <xref linkend="col-srgb" />.</entry> 511 </row> 512 <row> 513 <entry><constant>V4L2_COLORSPACE_ADOBERGB</constant></entry> 514 <entry>See <xref linkend="col-adobergb" />.</entry> 515 </row> 516 <row> 517 <entry><constant>V4L2_COLORSPACE_BT2020</constant></entry> 518 <entry>See <xref linkend="col-bt2020" />.</entry> 519 </row> 520 <row> 521 <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> 522 <entry>See <xref linkend="col-smpte-240m" />.</entry> 523 </row> 524 <row> 525 <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry> 526 <entry>See <xref linkend="col-sysm" />.</entry> 527 </row> 528 <row> 529 <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry> 530 <entry>See <xref linkend="col-sysbg" />.</entry> 531 </row> 532 <row> 533 <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> 534 <entry>See <xref linkend="col-jpeg" />.</entry> 535 </row> 536 </tbody> 537 </tgroup> 538 </table> 539 540 <table pgwide="1" frame="none" id="v4l2-ycbcr-encoding"> 541 <title>V4L2 Y'CbCr Encodings</title> 542 <tgroup cols="2" align="left"> 543 &cs-def; 544 <thead> 545 <row> 546 <entry>Identifier</entry> 547 <entry>Details</entry> 548 </row> 549 </thead> 550 <tbody valign="top"> 551 <row> 552 <entry><constant>V4L2_YCBCR_ENC_DEFAULT</constant></entry> 553 <entry>Use the default Y'CbCr encoding as defined by the colorspace.</entry> 554 </row> 555 <row> 556 <entry><constant>V4L2_YCBCR_ENC_601</constant></entry> 557 <entry>Use the BT.601 Y'CbCr encoding.</entry> 558 </row> 559 <row> 560 <entry><constant>V4L2_YCBCR_ENC_709</constant></entry> 561 <entry>Use the Rec. 709 Y'CbCr encoding.</entry> 562 </row> 563 <row> 564 <entry><constant>V4L2_YCBCR_ENC_XV601</constant></entry> 565 <entry>Use the extended gamut xvYCC BT.601 encoding.</entry> 566 </row> 567 <row> 568 <entry><constant>V4L2_YCBCR_ENC_XV709</constant></entry> 569 <entry>Use the extended gamut xvYCC Rec. 709 encoding.</entry> 570 </row> 571 <row> 572 <entry><constant>V4L2_YCBCR_ENC_SYCC</constant></entry> 573 <entry>Use the extended gamut sYCC encoding.</entry> 574 </row> 575 <row> 576 <entry><constant>V4L2_YCBCR_ENC_BT2020</constant></entry> 577 <entry>Use the default non-constant luminance BT.2020 Y'CbCr encoding.</entry> 578 </row> 579 <row> 580 <entry><constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant></entry> 581 <entry>Use the constant luminance BT.2020 Yc'CbcCrc encoding.</entry> 582 </row> 583 </tbody> 584 </tgroup> 585 </table> 586 587 <table pgwide="1" frame="none" id="v4l2-quantization"> 588 <title>V4L2 Quantization Methods</title> 589 <tgroup cols="2" align="left"> 590 &cs-def; 591 <thead> 592 <row> 593 <entry>Identifier</entry> 594 <entry>Details</entry> 595 </row> 596 </thead> 597 <tbody valign="top"> 598 <row> 599 <entry><constant>V4L2_QUANTIZATION_DEFAULT</constant></entry> 600 <entry>Use the default quantization encoding as defined by the colorspace. 601This is always full range for R'G'B' (except for the BT.2020 colorspace) and usually 602limited range for Y'CbCr.</entry> 603 </row> 604 <row> 605 <entry><constant>V4L2_QUANTIZATION_FULL_RANGE</constant></entry> 606 <entry>Use the full range quantization encoding. I.e. the range [0…1] 607is mapped to [0…255] (with possible clipping to [1…254] to avoid the 6080x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to [0…255] 609(with possible clipping to [1…254] to avoid the 0x00 and 0xff values).</entry> 610 </row> 611 <row> 612 <entry><constant>V4L2_QUANTIZATION_LIM_RANGE</constant></entry> 613 <entry>Use the limited range quantization encoding. I.e. the range [0…1] 614is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to [16…240]. 615</entry> 616 </row> 617 </tbody> 618 </tgroup> 619 </table> 620 </section> 621 622 <section> 623 <title>Detailed Colorspace Descriptions</title> 624 <section id="col-smpte-170m"> 625 <title>Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title> 626 <para>The <xref linkend="smpte170m" /> standard defines the colorspace used by NTSC and PAL and by SDTV 627in general. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. 628The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and 629the white reference are:</para> 630 <table frame="none"> 631 <title>SMPTE 170M Chromaticities</title> 632 <tgroup cols="3" align="left"> 633 &cs-str; 634 <thead> 635 <row> 636 <entry>Color</entry> 637 <entry>x</entry> 638 <entry>y</entry> 639 </row> 640 </thead> 641 <tbody valign="top"> 642 <row> 643 <entry>Red</entry> 644 <entry>0.630</entry> 645 <entry>0.340</entry> 646 </row> 647 <row> 648 <entry>Green</entry> 649 <entry>0.310</entry> 650 <entry>0.595</entry> 651 </row> 652 <row> 653 <entry>Blue</entry> 654 <entry>0.155</entry> 655 <entry>0.070</entry> 656 </row> 657 <row> 658 <entry>White Reference (D65)</entry> 659 <entry>0.3127</entry> 660 <entry>0.3290</entry> 661 </row> 662 </tbody> 663 </tgroup> 664 </table> 665 <para>The red, green and blue chromaticities are also often referred to 666as the SMPTE C set, so this colorspace is sometimes called SMPTE C as well.</para> 667 <variablelist> 668 <varlistentry> 669 <term>The transfer function defined for SMPTE 170M is the same as the 670one defined in Rec. 709.</term> 671 <listitem> 672 <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para> 673 <para>L' = 4.5L for -0.018 < L < 0.018</para> 674 <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para> 675 </listitem> 676 </varlistentry> 677 </variablelist> 678 <variablelist> 679 <varlistentry> 680 <term>Inverse Transfer function:</term> 681 <listitem> 682 <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para> 683 <para>L = L' / 4.5 for -0.081 < L' < 0.081</para> 684 <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> 685 </listitem> 686 </varlistentry> 687 </variablelist> 688 <variablelist> 689 <varlistentry> 690 <term>The luminance (Y') and color difference (Cb and Cr) are obtained with 691the following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> 692 <listitem> 693 <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> 694 <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> 695 <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> 696 </listitem> 697 </varlistentry> 698 </variablelist> 699 <para>Y' is clamped to the range [0…1] and Cb and Cr are 700clamped to the range [-0.5…0.5]. This conversion to Y'CbCr is identical to the one 701defined in the <xref linkend="itu601" /> standard and this colorspace is sometimes called BT.601 as well, even 702though BT.601 does not mention any color primaries.</para> 703 <para>The default quantization is limited range, but full range is possible although 704rarely seen.</para> 705 </section> 706 707 <section id="col-rec709"> 708 <title>Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title> 709 <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general. The default 710Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. The default Y'CbCr quantization is 711limited range. The chromaticities of the primary colors and the white reference are:</para> 712 <table frame="none"> 713 <title>Rec. 709 Chromaticities</title> 714 <tgroup cols="3" align="left"> 715 &cs-str; 716 <thead> 717 <row> 718 <entry>Color</entry> 719 <entry>x</entry> 720 <entry>y</entry> 721 </row> 722 </thead> 723 <tbody valign="top"> 724 <row> 725 <entry>Red</entry> 726 <entry>0.640</entry> 727 <entry>0.330</entry> 728 </row> 729 <row> 730 <entry>Green</entry> 731 <entry>0.300</entry> 732 <entry>0.600</entry> 733 </row> 734 <row> 735 <entry>Blue</entry> 736 <entry>0.150</entry> 737 <entry>0.060</entry> 738 </row> 739 <row> 740 <entry>White Reference (D65)</entry> 741 <entry>0.3127</entry> 742 <entry>0.3290</entry> 743 </row> 744 </tbody> 745 </tgroup> 746 </table> 747 <para>The full name of this standard is Rec. ITU-R BT.709-5.</para> 748 <variablelist> 749 <varlistentry> 750 <term>Transfer function. Normally L is in the range [0…1], but for the extended 751gamut xvYCC encoding values outside that range are allowed.</term> 752 <listitem> 753 <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para> 754 <para>L' = 4.5L for -0.018 < L < 0.018</para> 755 <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para> 756 </listitem> 757 </varlistentry> 758 </variablelist> 759 <variablelist> 760 <varlistentry> 761 <term>Inverse Transfer function:</term> 762 <listitem> 763 <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para> 764 <para>L = L' / 4.5 for -0.081 < L' < 0.081</para> 765 <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> 766 </listitem> 767 </varlistentry> 768 </variablelist> 769 <variablelist> 770 <varlistentry> 771 <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following 772<constant>V4L2_YCBCR_ENC_709</constant> encoding:</term> 773 <listitem> 774 <para>Y' = 0.2126R' + 0.7152G' + 0.0722B'</para> 775 <para>Cb = -0.1146R' - 0.3854G' + 0.5B'</para> 776 <para>Cr = 0.5R' - 0.4542G' - 0.0458B'</para> 777 </listitem> 778 </varlistentry> 779 </variablelist> 780 <para>Y' is clamped to the range [0…1] and Cb and Cr are 781clamped to the range [-0.5…0.5].</para> 782 <para>The default quantization is limited range, but full range is possible although 783rarely seen.</para> 784 <para>The <constant>V4L2_YCBCR_ENC_709</constant> encoding described above is the default 785for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_601</constant>, in which 786case the BT.601 Y'CbCr encoding is used.</para> 787 <para>Two additional extended gamut Y'CbCr encodings are also possible with this colorspace:</para> 788 <variablelist> 789 <varlistentry> 790 <term>The xvYCC 709 encoding (<constant>V4L2_YCBCR_ENC_XV709</constant>, <xref linkend="xvycc" />) 791is similar to the Rec. 709 encoding, but it allows for R', G' and B' values that are outside the range 792[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term> 793 <listitem> 794 <para>Y' = (219 / 256) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 256)</para> 795 <para>Cb = (224 / 256) * (-0.1146R' - 0.3854G' + 0.5B')</para> 796 <para>Cr = (224 / 256) * (0.5R' - 0.4542G' - 0.0458B')</para> 797 </listitem> 798 </varlistentry> 799 </variablelist> 800 <variablelist> 801 <varlistentry> 802 <term>The xvYCC 601 encoding (<constant>V4L2_YCBCR_ENC_XV601</constant>, <xref linkend="xvycc" />) is similar 803to the BT.601 encoding, but it allows for R', G' and B' values that are outside the range 804[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term> 805 <listitem> 806 <para>Y' = (219 / 256) * (0.299R' + 0.587G' + 0.114B') + (16 / 256)</para> 807 <para>Cb = (224 / 256) * (-0.169R' - 0.331G' + 0.5B')</para> 808 <para>Cr = (224 / 256) * (0.5R' - 0.419G' - 0.081B')</para> 809 </listitem> 810 </varlistentry> 811 </variablelist> 812 <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped 813to the range [-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be used by 814selecting <constant>V4L2_YCBCR_ENC_XV709</constant> or <constant>V4L2_YCBCR_ENC_XV601</constant>. 815The xvYCC encodings always use full range quantization.</para> 816 </section> 817 818 <section id="col-srgb"> 819 <title>Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title> 820 <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams and computer graphics. The 821default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr quantization 822is full range. The chromaticities of the primary colors and the white reference are:</para> 823 <table frame="none"> 824 <title>sRGB Chromaticities</title> 825 <tgroup cols="3" align="left"> 826 &cs-str; 827 <thead> 828 <row> 829 <entry>Color</entry> 830 <entry>x</entry> 831 <entry>y</entry> 832 </row> 833 </thead> 834 <tbody valign="top"> 835 <row> 836 <entry>Red</entry> 837 <entry>0.640</entry> 838 <entry>0.330</entry> 839 </row> 840 <row> 841 <entry>Green</entry> 842 <entry>0.300</entry> 843 <entry>0.600</entry> 844 </row> 845 <row> 846 <entry>Blue</entry> 847 <entry>0.150</entry> 848 <entry>0.060</entry> 849 </row> 850 <row> 851 <entry>White Reference (D65)</entry> 852 <entry>0.3127</entry> 853 <entry>0.3290</entry> 854 </row> 855 </tbody> 856 </tgroup> 857 </table> 858 <para>These chromaticities are identical to the Rec. 709 colorspace.</para> 859 <variablelist> 860 <varlistentry> 861 <term>Transfer function. Note that negative values for L are only used by the Y'CbCr conversion.</term> 862 <listitem> 863 <para>L' = -1.055(-L)<superscript>1/2.4</superscript> + 0.055 for L < -0.0031308</para> 864 <para>L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308</para> 865 <para>L' = 1.055L<superscript>1/2.4</superscript> - 0.055 for 0.0031308 < L ≤ 1</para> 866 </listitem> 867 </varlistentry> 868 <varlistentry> 869 <term>Inverse Transfer function:</term> 870 <listitem> 871 <para>L = -((-L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' < -0.04045</para> 872 <para>L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045</para> 873 <para>L = ((L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' > 0.04045</para> 874 </listitem> 875 </varlistentry> 876 </variablelist> 877 <variablelist> 878 <varlistentry> 879 <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following 880<constant>V4L2_YCBCR_ENC_SYCC</constant> encoding as defined by <xref linkend="sycc" />:</term> 881 <listitem> 882 <para>Y' = 0.2990R' + 0.5870G' + 0.1140B'</para> 883 <para>Cb = -0.1687R' - 0.3313G' + 0.5B'</para> 884 <para>Cr = 0.5R' - 0.4187G' - 0.0813B'</para> 885 </listitem> 886 </varlistentry> 887 </variablelist> 888 <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped 889to the range [-0.5…0.5]. The <constant>V4L2_YCBCR_ENC_SYCC</constant> quantization is always 890full range. Although this Y'CbCr encoding looks very similar to the <constant>V4L2_YCBCR_ENC_XV601</constant> 891encoding, it is not. The <constant>V4L2_YCBCR_ENC_XV601</constant> scales and offsets the Y'CbCr 892values before quantization, but this encoding does not do that.</para> 893 </section> 894 895 <section id="col-adobergb"> 896 <title>Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title> 897 <para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics 898that use the AdobeRGB colorspace. This is also known as the <xref linkend="oprgb" /> standard. 899The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr 900quantization is limited range. The chromaticities of the primary colors and the white reference 901are:</para> 902 <table frame="none"> 903 <title>Adobe RGB Chromaticities</title> 904 <tgroup cols="3" align="left"> 905 &cs-str; 906 <thead> 907 <row> 908 <entry>Color</entry> 909 <entry>x</entry> 910 <entry>y</entry> 911 </row> 912 </thead> 913 <tbody valign="top"> 914 <row> 915 <entry>Red</entry> 916 <entry>0.6400</entry> 917 <entry>0.3300</entry> 918 </row> 919 <row> 920 <entry>Green</entry> 921 <entry>0.2100</entry> 922 <entry>0.7100</entry> 923 </row> 924 <row> 925 <entry>Blue</entry> 926 <entry>0.1500</entry> 927 <entry>0.0600</entry> 928 </row> 929 <row> 930 <entry>White Reference (D65)</entry> 931 <entry>0.3127</entry> 932 <entry>0.3290</entry> 933 </row> 934 </tbody> 935 </tgroup> 936 </table> 937 <variablelist> 938 <varlistentry> 939 <term>Transfer function:</term> 940 <listitem> 941 <para>L' = L<superscript>1/2.19921875</superscript></para> 942 </listitem> 943 </varlistentry> 944 <varlistentry> 945 <term>Inverse Transfer function:</term> 946 <listitem> 947 <para>L = L'<superscript>2.19921875</superscript></para> 948 </listitem> 949 </varlistentry> 950 </variablelist> 951 <variablelist> 952 <varlistentry> 953 <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the 954following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> 955 <listitem> 956 <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> 957 <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> 958 <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> 959 </listitem> 960 </varlistentry> 961 </variablelist> 962 <para>Y' is clamped to the range [0…1] and Cb and Cr are 963clamped to the range [-0.5…0.5]. This transform is identical to one defined in 964SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para> 965 </section> 966 967 <section id="col-bt2020"> 968 <title>Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title> 969 <para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition 970television (UHDTV). The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>. 971The default R'G'B' quantization is limited range (!), and so is the default Y'CbCr quantization. 972The chromaticities of the primary colors and the white reference are:</para> 973 <table frame="none"> 974 <title>BT.2020 Chromaticities</title> 975 <tgroup cols="3" align="left"> 976 &cs-str; 977 <thead> 978 <row> 979 <entry>Color</entry> 980 <entry>x</entry> 981 <entry>y</entry> 982 </row> 983 </thead> 984 <tbody valign="top"> 985 <row> 986 <entry>Red</entry> 987 <entry>0.708</entry> 988 <entry>0.292</entry> 989 </row> 990 <row> 991 <entry>Green</entry> 992 <entry>0.170</entry> 993 <entry>0.797</entry> 994 </row> 995 <row> 996 <entry>Blue</entry> 997 <entry>0.131</entry> 998 <entry>0.046</entry> 999 </row> 1000 <row> 1001 <entry>White Reference (D65)</entry> 1002 <entry>0.3127</entry> 1003 <entry>0.3290</entry> 1004 </row> 1005 </tbody> 1006 </tgroup> 1007 </table> 1008 <variablelist> 1009 <varlistentry> 1010 <term>Transfer function (same as Rec. 709):</term> 1011 <listitem> 1012 <para>L' = 4.5L for 0 ≤ L < 0.018</para> 1013 <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> 1014 </listitem> 1015 </varlistentry> 1016 <varlistentry> 1017 <term>Inverse Transfer function:</term> 1018 <listitem> 1019 <para>L = L' / 4.5 for L' < 0.081</para> 1020 <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> 1021 </listitem> 1022 </varlistentry> 1023 </variablelist> 1024 <variablelist> 1025 <varlistentry> 1026 <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the 1027following <constant>V4L2_YCBCR_ENC_BT2020</constant> encoding:</term> 1028 <listitem> 1029 <para>Y' = 0.2627R' + 0.6780G' + 0.0593B'</para> 1030 <para>Cb = -0.1396R' - 0.3604G' + 0.5B'</para> 1031 <para>Cr = 0.5R' - 0.4598G' - 0.0402B'</para> 1032 </listitem> 1033 </varlistentry> 1034 </variablelist> 1035 <para>Y' is clamped to the range [0…1] and Cb and Cr are 1036clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> 1037 <para>There is also an alternate constant luminance R'G'B' to Yc'CbcCrc 1038(<constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant>) encoding:</para> 1039 <variablelist> 1040 <varlistentry> 1041 <term>Luma:</term> 1042 <listitem> 1043 <para>Yc' = (0.2627R + 0.6780G + 0.0593B)'</para> 1044 </listitem> 1045 </varlistentry> 1046 </variablelist> 1047 <variablelist> 1048 <varlistentry> 1049 <term>B' - Yc' ≤ 0:</term> 1050 <listitem> 1051 <para>Cbc = (B' - Yc') / 1.9404</para> 1052 </listitem> 1053 </varlistentry> 1054 </variablelist> 1055 <variablelist> 1056 <varlistentry> 1057 <term>B' - Yc' > 0:</term> 1058 <listitem> 1059 <para>Cbc = (B' - Yc') / 1.5816</para> 1060 </listitem> 1061 </varlistentry> 1062 </variablelist> 1063 <variablelist> 1064 <varlistentry> 1065 <term>R' - Yc' ≤ 0:</term> 1066 <listitem> 1067 <para>Crc = (R' - Y') / 1.7184</para> 1068 </listitem> 1069 </varlistentry> 1070 </variablelist> 1071 <variablelist> 1072 <varlistentry> 1073 <term>R' - Yc' > 0:</term> 1074 <listitem> 1075 <para>Crc = (R' - Y') / 0.9936</para> 1076 </listitem> 1077 </varlistentry> 1078 </variablelist> 1079 <para>Yc' is clamped to the range [0…1] and Cbc and Crc are 1080clamped to the range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.</para> 1081 </section> 1082 1083 <section id="col-smpte-240m"> 1084 <title>Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title> 1085 <para>The <xref linkend="smpte240m" /> standard was an interim standard used during the early days of HDTV (1988-1998). 1086It has been superseded by Rec. 709. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>. 1087The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the 1088white reference are:</para> 1089 <table frame="none"> 1090 <title>SMPTE 240M Chromaticities</title> 1091 <tgroup cols="3" align="left"> 1092 &cs-str; 1093 <thead> 1094 <row> 1095 <entry>Color</entry> 1096 <entry>x</entry> 1097 <entry>y</entry> 1098 </row> 1099 </thead> 1100 <tbody valign="top"> 1101 <row> 1102 <entry>Red</entry> 1103 <entry>0.630</entry> 1104 <entry>0.340</entry> 1105 </row> 1106 <row> 1107 <entry>Green</entry> 1108 <entry>0.310</entry> 1109 <entry>0.595</entry> 1110 </row> 1111 <row> 1112 <entry>Blue</entry> 1113 <entry>0.155</entry> 1114 <entry>0.070</entry> 1115 </row> 1116 <row> 1117 <entry>White Reference (D65)</entry> 1118 <entry>0.3127</entry> 1119 <entry>0.3290</entry> 1120 </row> 1121 </tbody> 1122 </tgroup> 1123 </table> 1124 <para>These chromaticities are identical to the SMPTE 170M colorspace.</para> 1125 <variablelist> 1126 <varlistentry> 1127 <term>Transfer function:</term> 1128 <listitem> 1129 <para>L' = 4L for 0 ≤ L < 0.0228</para> 1130 <para>L' = 1.1115L<superscript>0.45</superscript> - 0.1115 for 0.0228 ≤ L ≤ 1</para> 1131 </listitem> 1132 </varlistentry> 1133 <varlistentry> 1134 <term>Inverse Transfer function:</term> 1135 <listitem> 1136 <para>L = L' / 4 for 0 ≤ L' < 0.0913</para> 1137 <para>L = ((L' + 0.1115) / 1.1115)<superscript>1/0.45</superscript> for L' ≥ 0.0913</para> 1138 </listitem> 1139 </varlistentry> 1140 </variablelist> 1141 <variablelist> 1142 <varlistentry> 1143 <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the 1144following <constant>V4L2_YCBCR_ENC_SMPTE240M</constant> encoding:</term> 1145 <listitem> 1146 <para>Y' = 0.2122R' + 0.7013G' + 0.0865B'</para> 1147 <para>Cb = -0.1161R' - 0.3839G' + 0.5B'</para> 1148 <para>Cr = 0.5R' - 0.4451G' - 0.0549B'</para> 1149 </listitem> 1150 </varlistentry> 1151 </variablelist> 1152 <para>Yc' is clamped to the range [0…1] and Cbc and Crc are 1153clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> 1154 </section> 1155 1156 <section id="col-sysm"> 1157 <title>Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title> 1158 <para>This standard defines the colorspace used by NTSC in 1953. In practice this 1159colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding 1160is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range. 1161The chromaticities of the primary colors and the white reference are:</para> 1162 <table frame="none"> 1163 <title>NTSC 1953 Chromaticities</title> 1164 <tgroup cols="3" align="left"> 1165 &cs-str; 1166 <thead> 1167 <row> 1168 <entry>Color</entry> 1169 <entry>x</entry> 1170 <entry>y</entry> 1171 </row> 1172 </thead> 1173 <tbody valign="top"> 1174 <row> 1175 <entry>Red</entry> 1176 <entry>0.67</entry> 1177 <entry>0.33</entry> 1178 </row> 1179 <row> 1180 <entry>Green</entry> 1181 <entry>0.21</entry> 1182 <entry>0.71</entry> 1183 </row> 1184 <row> 1185 <entry>Blue</entry> 1186 <entry>0.14</entry> 1187 <entry>0.08</entry> 1188 </row> 1189 <row> 1190 <entry>White Reference (C)</entry> 1191 <entry>0.310</entry> 1192 <entry>0.316</entry> 1193 </row> 1194 </tbody> 1195 </tgroup> 1196 </table> 1197 <para>Note that this colorspace uses Illuminant C instead of D65 as the 1198white reference. To correctly convert an image in this colorspace to another 1199that uses D65 you need to apply a chromatic adaptation algorithm such as the 1200Bradford method.</para> 1201 <variablelist> 1202 <varlistentry> 1203 <term>The transfer function was never properly defined for NTSC 1953. The 1204Rec. 709 transfer function is recommended in the literature:</term> 1205 <listitem> 1206 <para>L' = 4.5L for 0 ≤ L < 0.018</para> 1207 <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> 1208 </listitem> 1209 </varlistentry> 1210 <varlistentry> 1211 <term>Inverse Transfer function:</term> 1212 <listitem> 1213 <para>L = L' / 4.5 for L' < 0.081</para> 1214 <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> 1215 </listitem> 1216 </varlistentry> 1217 </variablelist> 1218 <variablelist> 1219 <varlistentry> 1220 <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the 1221following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> 1222 <listitem> 1223 <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> 1224 <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> 1225 <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> 1226 </listitem> 1227 </varlistentry> 1228 </variablelist> 1229 <para>Y' is clamped to the range [0…1] and Cb and Cr are 1230clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. 1231This transform is identical to one defined in SMPTE 170M/BT.601.</para> 1232 </section> 1233 1234 <section id="col-sysbg"> 1235 <title>Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title> 1236 <para>The <xref linkend="tech3213" /> standard defines the colorspace used by PAL/SECAM in 1975. In practice this 1237colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding 1238is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range. 1239The chromaticities of the primary colors and the white reference are:</para> 1240 <table frame="none"> 1241 <title>EBU Tech. 3213 Chromaticities</title> 1242 <tgroup cols="3" align="left"> 1243 &cs-str; 1244 <thead> 1245 <row> 1246 <entry>Color</entry> 1247 <entry>x</entry> 1248 <entry>y</entry> 1249 </row> 1250 </thead> 1251 <tbody valign="top"> 1252 <row> 1253 <entry>Red</entry> 1254 <entry>0.64</entry> 1255 <entry>0.33</entry> 1256 </row> 1257 <row> 1258 <entry>Green</entry> 1259 <entry>0.29</entry> 1260 <entry>0.60</entry> 1261 </row> 1262 <row> 1263 <entry>Blue</entry> 1264 <entry>0.15</entry> 1265 <entry>0.06</entry> 1266 </row> 1267 <row> 1268 <entry>White Reference (D65)</entry> 1269 <entry>0.3127</entry> 1270 <entry>0.3290</entry> 1271 </row> 1272 </tbody> 1273 </tgroup> 1274 </table> 1275 <variablelist> 1276 <varlistentry> 1277 <term>The transfer function was never properly defined for this colorspace. 1278The Rec. 709 transfer function is recommended in the literature:</term> 1279 <listitem> 1280 <para>L' = 4.5L for 0 ≤ L < 0.018</para> 1281 <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> 1282 </listitem> 1283 </varlistentry> 1284 <varlistentry> 1285 <term>Inverse Transfer function:</term> 1286 <listitem> 1287 <para>L = L' / 4.5 for L' < 0.081</para> 1288 <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> 1289 </listitem> 1290 </varlistentry> 1291 </variablelist> 1292 <variablelist> 1293 <varlistentry> 1294 <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the 1295following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> 1296 <listitem> 1297 <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> 1298 <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> 1299 <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> 1300 </listitem> 1301 </varlistentry> 1302 </variablelist> 1303 <para>Y' is clamped to the range [0…1] and Cb and Cr are 1304clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. 1305This transform is identical to one defined in SMPTE 170M/BT.601.</para> 1306 </section> 1307 1308 <section id="col-jpeg"> 1309 <title>Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title> 1310 <para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities 1311of the primary colors and the white reference are identical to sRGB. The Y'CbCr encoding is 1312<constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where 1313Y' is scaled to [0…255] and Cb/Cr are scaled to [-128…128] and 1314then clipped to [-128…127].</para> 1315 <para>Note that the JPEG standard does not actually store colorspace information. 1316So if something other than sRGB is used, then the driver will have to set that information 1317explicitly. Effectively <constant>V4L2_COLORSPACE_JPEG</constant> can be considered to be 1318an abbreviation for <constant>V4L2_COLORSPACE_SRGB</constant>, <constant>V4L2_YCBCR_ENC_601</constant> 1319and <constant>V4L2_QUANTIZATION_FULL_RANGE</constant>.</para> 1320 </section> 1321 1322 </section> 1323 1324 <section id="pixfmt-indexed"> 1325 <title>Indexed Format</title> 1326 1327 <para>In this format each pixel is represented by an 8 bit index 1328into a 256 entry ARGB palette. It is intended for <link 1329linkend="osd">Video Output Overlays</link> only. There are no ioctls to 1330access the palette, this must be done with ioctls of the Linux framebuffer API.</para> 1331 1332 <table pgwide="0" frame="none"> 1333 <title>Indexed Image Format</title> 1334 <tgroup cols="37" align="center"> 1335 <colspec colname="id" align="left" /> 1336 <colspec colname="fourcc" /> 1337 <colspec colname="bit" /> 1338 1339 <colspec colnum="4" colname="b07" align="center" /> 1340 <colspec colnum="5" colname="b06" align="center" /> 1341 <colspec colnum="6" colname="b05" align="center" /> 1342 <colspec colnum="7" colname="b04" align="center" /> 1343 <colspec colnum="8" colname="b03" align="center" /> 1344 <colspec colnum="9" colname="b02" align="center" /> 1345 <colspec colnum="10" colname="b01" align="center" /> 1346 <colspec colnum="11" colname="b00" align="center" /> 1347 1348 <spanspec namest="b07" nameend="b00" spanname="b0" /> 1349 <spanspec namest="b17" nameend="b10" spanname="b1" /> 1350 <spanspec namest="b27" nameend="b20" spanname="b2" /> 1351 <spanspec namest="b37" nameend="b30" spanname="b3" /> 1352 <thead> 1353 <row> 1354 <entry>Identifier</entry> 1355 <entry>Code</entry> 1356 <entry> </entry> 1357 <entry spanname="b0">Byte 0</entry> 1358 </row> 1359 <row> 1360 <entry> </entry> 1361 <entry> </entry> 1362 <entry>Bit</entry> 1363 <entry>7</entry> 1364 <entry>6</entry> 1365 <entry>5</entry> 1366 <entry>4</entry> 1367 <entry>3</entry> 1368 <entry>2</entry> 1369 <entry>1</entry> 1370 <entry>0</entry> 1371 </row> 1372 </thead> 1373 <tbody valign="top"> 1374 <row id="V4L2-PIX-FMT-PAL8"> 1375 <entry><constant>V4L2_PIX_FMT_PAL8</constant></entry> 1376 <entry>'PAL8'</entry> 1377 <entry></entry> 1378 <entry>i<subscript>7</subscript></entry> 1379 <entry>i<subscript>6</subscript></entry> 1380 <entry>i<subscript>5</subscript></entry> 1381 <entry>i<subscript>4</subscript></entry> 1382 <entry>i<subscript>3</subscript></entry> 1383 <entry>i<subscript>2</subscript></entry> 1384 <entry>i<subscript>1</subscript></entry> 1385 <entry>i<subscript>0</subscript></entry> 1386 </row> 1387 </tbody> 1388 </tgroup> 1389 </table> 1390 </section> 1391 1392 <section id="pixfmt-rgb"> 1393 <title>RGB Formats</title> 1394 1395 &sub-packed-rgb; 1396 &sub-sbggr8; 1397 &sub-sgbrg8; 1398 &sub-sgrbg8; 1399 &sub-srggb8; 1400 &sub-sbggr16; 1401 &sub-srggb10; 1402 &sub-srggb10p; 1403 &sub-srggb10alaw8; 1404 &sub-srggb10dpcm8; 1405 &sub-srggb12; 1406 </section> 1407 1408 <section id="yuv-formats"> 1409 <title>YUV Formats</title> 1410 1411 <para>YUV is the format native to TV broadcast and composite video 1412signals. It separates the brightness information (Y) from the color 1413information (U and V or Cb and Cr). The color information consists of 1414red and blue <emphasis>color difference</emphasis> signals, this way 1415the green component can be reconstructed by subtracting from the 1416brightness component. See <xref linkend="colorspaces" /> for conversion 1417examples. YUV was chosen because early television would only transmit 1418brightness information. To add color in a way compatible with existing 1419receivers a new signal carrier was added to transmit the color 1420difference signals. Secondary in the YUV format the U and V components 1421usually have lower resolution than the Y component. This is an analog 1422video compression technique taking advantage of a property of the 1423human visual system, being more sensitive to brightness 1424information.</para> 1425 1426 &sub-packed-yuv; 1427 &sub-grey; 1428 &sub-y10; 1429 &sub-y12; 1430 &sub-y10b; 1431 &sub-y16; 1432 &sub-uv8; 1433 &sub-yuyv; 1434 &sub-uyvy; 1435 &sub-yvyu; 1436 &sub-vyuy; 1437 &sub-y41p; 1438 &sub-yuv420; 1439 &sub-yuv420m; 1440 &sub-yvu420m; 1441 &sub-yuv410; 1442 &sub-yuv422p; 1443 &sub-yuv411p; 1444 &sub-nv12; 1445 &sub-nv12m; 1446 &sub-nv12mt; 1447 &sub-nv16; 1448 &sub-nv16m; 1449 &sub-nv24; 1450 &sub-m420; 1451 </section> 1452 1453 <section> 1454 <title>Compressed Formats</title> 1455 1456 <table pgwide="1" frame="none" id="compressed-formats"> 1457 <title>Compressed Image Formats</title> 1458 <tgroup cols="3" align="left"> 1459 &cs-def; 1460 <thead> 1461 <row> 1462 <entry>Identifier</entry> 1463 <entry>Code</entry> 1464 <entry>Details</entry> 1465 </row> 1466 </thead> 1467 <tbody valign="top"> 1468 <row id="V4L2-PIX-FMT-JPEG"> 1469 <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry> 1470 <entry>'JPEG'</entry> 1471 <entry>TBD. See also &VIDIOC-G-JPEGCOMP;, 1472 &VIDIOC-S-JPEGCOMP;.</entry> 1473 </row> 1474 <row id="V4L2-PIX-FMT-MPEG"> 1475 <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry> 1476 <entry>'MPEG'</entry> 1477 <entry>MPEG multiplexed stream. The actual format is determined by 1478extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see 1479<xref linkend="mpeg-control-id" />.</entry> 1480 </row> 1481 <row id="V4L2-PIX-FMT-H264"> 1482 <entry><constant>V4L2_PIX_FMT_H264</constant></entry> 1483 <entry>'H264'</entry> 1484 <entry>H264 video elementary stream with start codes.</entry> 1485 </row> 1486 <row id="V4L2-PIX-FMT-H264-NO-SC"> 1487 <entry><constant>V4L2_PIX_FMT_H264_NO_SC</constant></entry> 1488 <entry>'AVC1'</entry> 1489 <entry>H264 video elementary stream without start codes.</entry> 1490 </row> 1491 <row id="V4L2-PIX-FMT-H264-MVC"> 1492 <entry><constant>V4L2_PIX_FMT_H264_MVC</constant></entry> 1493 <entry>'M264'</entry> 1494 <entry>H264 MVC video elementary stream.</entry> 1495 </row> 1496 <row id="V4L2-PIX-FMT-H263"> 1497 <entry><constant>V4L2_PIX_FMT_H263</constant></entry> 1498 <entry>'H263'</entry> 1499 <entry>H263 video elementary stream.</entry> 1500 </row> 1501 <row id="V4L2-PIX-FMT-MPEG1"> 1502 <entry><constant>V4L2_PIX_FMT_MPEG1</constant></entry> 1503 <entry>'MPG1'</entry> 1504 <entry>MPEG1 video elementary stream.</entry> 1505 </row> 1506 <row id="V4L2-PIX-FMT-MPEG2"> 1507 <entry><constant>V4L2_PIX_FMT_MPEG2</constant></entry> 1508 <entry>'MPG2'</entry> 1509 <entry>MPEG2 video elementary stream.</entry> 1510 </row> 1511 <row id="V4L2-PIX-FMT-MPEG4"> 1512 <entry><constant>V4L2_PIX_FMT_MPEG4</constant></entry> 1513 <entry>'MPG4'</entry> 1514 <entry>MPEG4 video elementary stream.</entry> 1515 </row> 1516 <row id="V4L2-PIX-FMT-XVID"> 1517 <entry><constant>V4L2_PIX_FMT_XVID</constant></entry> 1518 <entry>'XVID'</entry> 1519 <entry>Xvid video elementary stream.</entry> 1520 </row> 1521 <row id="V4L2-PIX-FMT-VC1-ANNEX-G"> 1522 <entry><constant>V4L2_PIX_FMT_VC1_ANNEX_G</constant></entry> 1523 <entry>'VC1G'</entry> 1524 <entry>VC1, SMPTE 421M Annex G compliant stream.</entry> 1525 </row> 1526 <row id="V4L2-PIX-FMT-VC1-ANNEX-L"> 1527 <entry><constant>V4L2_PIX_FMT_VC1_ANNEX_L</constant></entry> 1528 <entry>'VC1L'</entry> 1529 <entry>VC1, SMPTE 421M Annex L compliant stream.</entry> 1530 </row> 1531 <row id="V4L2-PIX-FMT-VP8"> 1532 <entry><constant>V4L2_PIX_FMT_VP8</constant></entry> 1533 <entry>'VP80'</entry> 1534 <entry>VP8 video elementary stream.</entry> 1535 </row> 1536 </tbody> 1537 </tgroup> 1538 </table> 1539 </section> 1540 1541 <section id="sdr-formats"> 1542 <title>SDR Formats</title> 1543 1544 <para>These formats are used for <link linkend="sdr">SDR Capture</link> 1545interface only.</para> 1546 1547 &sub-sdr-cu08; 1548 &sub-sdr-cu16le; 1549 &sub-sdr-cs08; 1550 &sub-sdr-cs14le; 1551 &sub-sdr-ru12le; 1552 1553 </section> 1554 1555 <section id="pixfmt-reserved"> 1556 <title>Reserved Format Identifiers</title> 1557 1558 <para>These formats are not defined by this specification, they 1559are just listed for reference and to avoid naming conflicts. If you 1560want to register your own format, send an e-mail to the linux-media mailing 1561list &v4l-ml; for inclusion in the <filename>videodev2.h</filename> 1562file. If you want to share your format with other developers add a 1563link to your documentation and send a copy to the linux-media mailing list 1564for inclusion in this section. If you think your format should be listed 1565in a standard format section please make a proposal on the linux-media mailing 1566list.</para> 1567 1568 <table pgwide="1" frame="none" id="reserved-formats"> 1569 <title>Reserved Image Formats</title> 1570 <tgroup cols="3" align="left"> 1571 &cs-def; 1572 <thead> 1573 <row> 1574 <entry>Identifier</entry> 1575 <entry>Code</entry> 1576 <entry>Details</entry> 1577 </row> 1578 </thead> 1579 <tbody valign="top"> 1580 <row id="V4L2-PIX-FMT-DV"> 1581 <entry><constant>V4L2_PIX_FMT_DV</constant></entry> 1582 <entry>'dvsd'</entry> 1583 <entry>unknown</entry> 1584 </row> 1585 <row id="V4L2-PIX-FMT-ET61X251"> 1586 <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry> 1587 <entry>'E625'</entry> 1588 <entry>Compressed format of the ET61X251 driver.</entry> 1589 </row> 1590 <row id="V4L2-PIX-FMT-HI240"> 1591 <entry><constant>V4L2_PIX_FMT_HI240</constant></entry> 1592 <entry>'HI24'</entry> 1593 <entry><para>8 bit RGB format used by the BTTV driver.</para></entry> 1594 </row> 1595 <row id="V4L2-PIX-FMT-HM12"> 1596 <entry><constant>V4L2_PIX_FMT_HM12</constant></entry> 1597 <entry>'HM12'</entry> 1598 <entry><para>YUV 4:2:0 format used by the 1599IVTV driver, <ulink url="http://www.ivtvdriver.org/"> 1600http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the 1601kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename> 1602</para></entry> 1603 </row> 1604 <row id="V4L2-PIX-FMT-CPIA1"> 1605 <entry><constant>V4L2_PIX_FMT_CPIA1</constant></entry> 1606 <entry>'CPIA'</entry> 1607 <entry>YUV format used by the gspca cpia1 driver.</entry> 1608 </row> 1609 <row id="V4L2-PIX-FMT-JPGL"> 1610 <entry><constant>V4L2_PIX_FMT_JPGL</constant></entry> 1611 <entry>'JPGL'</entry> 1612 <entry>JPEG-Light format (Pegasus Lossless JPEG) 1613 used in Divio webcams NW 80x.</entry> 1614 </row> 1615 <row id="V4L2-PIX-FMT-SPCA501"> 1616 <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry> 1617 <entry>'S501'</entry> 1618 <entry>YUYV per line used by the gspca driver.</entry> 1619 </row> 1620 <row id="V4L2-PIX-FMT-SPCA505"> 1621 <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry> 1622 <entry>'S505'</entry> 1623 <entry>YYUV per line used by the gspca driver.</entry> 1624 </row> 1625 <row id="V4L2-PIX-FMT-SPCA508"> 1626 <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry> 1627 <entry>'S508'</entry> 1628 <entry>YUVY per line used by the gspca driver.</entry> 1629 </row> 1630 <row id="V4L2-PIX-FMT-SPCA561"> 1631 <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry> 1632 <entry>'S561'</entry> 1633 <entry>Compressed GBRG Bayer format used by the gspca driver.</entry> 1634 </row> 1635 <row id="V4L2-PIX-FMT-PAC207"> 1636 <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry> 1637 <entry>'P207'</entry> 1638 <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> 1639 </row> 1640 <row id="V4L2-PIX-FMT-MR97310A"> 1641 <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry> 1642 <entry>'M310'</entry> 1643 <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> 1644 </row> 1645 <row id="V4L2-PIX-FMT-JL2005BCD"> 1646 <entry><constant>V4L2_PIX_FMT_JL2005BCD</constant></entry> 1647 <entry>'JL20'</entry> 1648 <entry>JPEG compressed RGGB Bayer format used by the gspca driver.</entry> 1649 </row> 1650 <row id="V4L2-PIX-FMT-OV511"> 1651 <entry><constant>V4L2_PIX_FMT_OV511</constant></entry> 1652 <entry>'O511'</entry> 1653 <entry>OV511 JPEG format used by the gspca driver.</entry> 1654 </row> 1655 <row id="V4L2-PIX-FMT-OV518"> 1656 <entry><constant>V4L2_PIX_FMT_OV518</constant></entry> 1657 <entry>'O518'</entry> 1658 <entry>OV518 JPEG format used by the gspca driver.</entry> 1659 </row> 1660 <row id="V4L2-PIX-FMT-PJPG"> 1661 <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry> 1662 <entry>'PJPG'</entry> 1663 <entry>Pixart 73xx JPEG format used by the gspca driver.</entry> 1664 </row> 1665 <row id="V4L2-PIX-FMT-SE401"> 1666 <entry><constant>V4L2_PIX_FMT_SE401</constant></entry> 1667 <entry>'S401'</entry> 1668 <entry>Compressed RGB format used by the gspca se401 driver</entry> 1669 </row> 1670 <row id="V4L2-PIX-FMT-SQ905C"> 1671 <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry> 1672 <entry>'905C'</entry> 1673 <entry>Compressed RGGB bayer format used by the gspca driver.</entry> 1674 </row> 1675 <row id="V4L2-PIX-FMT-MJPEG"> 1676 <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry> 1677 <entry>'MJPG'</entry> 1678 <entry>Compressed format used by the Zoran driver</entry> 1679 </row> 1680 <row id="V4L2-PIX-FMT-PWC1"> 1681 <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry> 1682 <entry>'PWC1'</entry> 1683 <entry>Compressed format of the PWC driver.</entry> 1684 </row> 1685 <row id="V4L2-PIX-FMT-PWC2"> 1686 <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry> 1687 <entry>'PWC2'</entry> 1688 <entry>Compressed format of the PWC driver.</entry> 1689 </row> 1690 <row id="V4L2-PIX-FMT-SN9C10X"> 1691 <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry> 1692 <entry>'S910'</entry> 1693 <entry>Compressed format of the SN9C102 driver.</entry> 1694 </row> 1695 <row id="V4L2-PIX-FMT-SN9C20X-I420"> 1696 <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry> 1697 <entry>'S920'</entry> 1698 <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry> 1699 </row> 1700 <row id="V4L2-PIX-FMT-SN9C2028"> 1701 <entry><constant>V4L2_PIX_FMT_SN9C2028</constant></entry> 1702 <entry>'SONX'</entry> 1703 <entry>Compressed GBRG bayer format of the gspca sn9c2028 driver.</entry> 1704 </row> 1705 <row id="V4L2-PIX-FMT-STV0680"> 1706 <entry><constant>V4L2_PIX_FMT_STV0680</constant></entry> 1707 <entry>'S680'</entry> 1708 <entry>Bayer format of the gspca stv0680 driver.</entry> 1709 </row> 1710 <row id="V4L2-PIX-FMT-WNVA"> 1711 <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry> 1712 <entry>'WNVA'</entry> 1713 <entry><para>Used by the Winnov Videum driver, <ulink 1714url="http://www.thedirks.org/winnov/"> 1715http://www.thedirks.org/winnov/</ulink></para></entry> 1716 </row> 1717 <row id="V4L2-PIX-FMT-TM6000"> 1718 <entry><constant>V4L2_PIX_FMT_TM6000</constant></entry> 1719 <entry>'TM60'</entry> 1720 <entry><para>Used by Trident tm6000</para></entry> 1721 </row> 1722 <row id="V4L2-PIX-FMT-CIT-YYVYUY"> 1723 <entry><constant>V4L2_PIX_FMT_CIT_YYVYUY</constant></entry> 1724 <entry>'CITV'</entry> 1725 <entry><para>Used by xirlink CIT, found at IBM webcams.</para> 1726 <para>Uses one line of Y then 1 line of VYUY</para> 1727 </entry> 1728 </row> 1729 <row id="V4L2-PIX-FMT-KONICA420"> 1730 <entry><constant>V4L2_PIX_FMT_KONICA420</constant></entry> 1731 <entry>'KONI'</entry> 1732 <entry><para>Used by Konica webcams.</para> 1733 <para>YUV420 planar in blocks of 256 pixels.</para> 1734 </entry> 1735 </row> 1736 <row id="V4L2-PIX-FMT-YYUV"> 1737 <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry> 1738 <entry>'YYUV'</entry> 1739 <entry>unknown</entry> 1740 </row> 1741 <row id="V4L2-PIX-FMT-Y4"> 1742 <entry><constant>V4L2_PIX_FMT_Y4</constant></entry> 1743 <entry>'Y04 '</entry> 1744 <entry>Old 4-bit greyscale format. Only the most significant 4 bits of each byte are used, 1745the other bits are set to 0.</entry> 1746 </row> 1747 <row id="V4L2-PIX-FMT-Y6"> 1748 <entry><constant>V4L2_PIX_FMT_Y6</constant></entry> 1749 <entry>'Y06 '</entry> 1750 <entry>Old 6-bit greyscale format. Only the most significant 6 bits of each byte are used, 1751the other bits are set to 0.</entry> 1752 </row> 1753 <row id="V4L2-PIX-FMT-S5C-UYVY-JPG"> 1754 <entry><constant>V4L2_PIX_FMT_S5C_UYVY_JPG</constant></entry> 1755 <entry>'S5CI'</entry> 1756 <entry>Two-planar format used by Samsung S5C73MX cameras. The 1757first plane contains interleaved JPEG and UYVY image data, followed by meta data 1758in form of an array of offsets to the UYVY data blocks. The actual pointer array 1759follows immediately the interleaved JPEG/UYVY data, the number of entries in 1760this array equals the height of the UYVY image. Each entry is a 4-byte unsigned 1761integer in big endian order and it's an offset to a single pixel line of the 1762UYVY image. The first plane can start either with JPEG or UYVY data chunk. The 1763size of a single UYVY block equals the UYVY image's width multiplied by 2. The 1764size of a JPEG chunk depends on the image and can vary with each line. 1765<para>The second plane, at an offset of 4084 bytes, contains a 4-byte offset to 1766the pointer array in the first plane. This offset is followed by a 4-byte value 1767indicating size of the pointer array. All numbers in the second plane are also 1768in big endian order. Remaining data in the second plane is undefined. The 1769information in the second plane allows to easily find location of the pointer 1770array, which can be different for each frame. The size of the pointer array is 1771constant for given UYVY image height.</para> 1772<para>In order to extract UYVY and JPEG frames an application can initially set 1773a data pointer to the start of first plane and then add an offset from the first 1774entry of the pointers table. Such a pointer indicates start of an UYVY image 1775pixel line. Whole UYVY line can be copied to a separate buffer. These steps 1776should be repeated for each line, i.e. the number of entries in the pointer 1777array. Anything what's in between the UYVY lines is JPEG data and should be 1778concatenated to form the JPEG stream. </para> 1779</entry> 1780 </row> 1781 </tbody> 1782 </tgroup> 1783 </table> 1784 1785 <table frame="none" pgwide="1" id="format-flags"> 1786 <title>Format Flags</title> 1787 <tgroup cols="3"> 1788 &cs-def; 1789 <tbody valign="top"> 1790 <row> 1791 <entry><constant>V4L2_PIX_FMT_FLAG_PREMUL_ALPHA</constant></entry> 1792 <entry>0x00000001</entry> 1793 <entry>The color values are premultiplied by the alpha channel 1794value. For example, if a light blue pixel with 50% transparency was described by 1795RGBA values (128, 192, 255, 128), the same pixel described with premultiplied 1796colors would be described by RGBA values (64, 96, 128, 128) </entry> 1797 </row> 1798 </tbody> 1799 </tgroup> 1800 </table> 1801 </section> 1802