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