projects / linux-2.6-block.git / blame
| Commit | Line | Data |
|---|---|---|
| 8e080c2e MCC |
1 | <title>Image Formats</title> |
| 2 | ||
| 3 | <para>The V4L2 API was primarily designed for devices exchanging | |
| 4 | image data with applications. The | |
| 53b5d574 PO |
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. | |
| 7 | The former is used with the single-planar API, while the latter is used with the | |
| 8 | multi-planar version (see <xref linkend="planar-apis"/>). Image formats are | |
| 9 | negotiated with the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video | |
| 8e080c2e MCC |
10 | capturing and output, for overlay frame buffer formats see also |
| 11 | &VIDIOC-G-FBUF;.)</para> | |
| 12 | ||
| 53b5d574 PO |
13 | <section> |
| 14 | <title>Single-planar format structure</title> | |
| 8e080c2e MCC |
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> | |
| 46609297 HV |
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> | |
| 8e080c2e MCC |
34 | </row> |
| 35 | <row> | |
| 36 | <entry spanname="hspan">Applications set these fields to | |
| 37 | request an image size, drivers return the closest possible values. In | |
| 38 | case of planar formats the <structfield>width</structfield> and | |
| 39 | <structfield>height</structfield> applies to the largest plane. To | |
| 40 | avoid ambiguities drivers must return values rounded up to a multiple | |
| 41 | of the scale factor of any smaller planes. For example when the image | |
| 42 | format 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 | |
| 49 | application. This is a little endian <link | |
| 50 | linkend="v4l2-fourcc">four character code</link>. V4L2 defines | |
| 51 | standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref | |
| 52 | linkend="yuv-formats" />, and reserved codes in <xref | |
| 53 | linkend="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 | |
| 59 | can request to capture or output only the top or bottom field, or both | |
| 60 | fields interlaced or sequentially stored in one buffer or alternating | |
| 61 | in separate buffers. Drivers return the actual field order selected. | |
| 46609297 | 62 | For more details on fields see <xref linkend="field-order" />.</entry> |
| 8e080c2e MCC |
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 | |
| 68 | adjacent lines.</entry> | |
| 69 | </row> | |
| 70 | <row> | |
| 71 | <entry spanname="hspan"><para>Both applications and drivers | |
| 72 | can set this field to request padding bytes at the end of each line. | |
| 73 | Drivers however may ignore the value requested by the application, | |
| 74 | returning <structfield>width</structfield> times bytes per pixel or a | |
| 75 | larger value required by the hardware. That implies applications can | |
| 76 | just set this field to zero to get a reasonable | |
| 77 | default.</para><para>Video hardware may access padding bytes, | |
| 78 | therefore they must reside in accessible memory. Consider cases where | |
| 79 | padding bytes after the last line of an image cross a system page | |
| 80 | boundary. Input devices may write padding bytes, the value is | |
| 81 | undefined. Output devices ignore the contents of padding | |
| 82 | bytes.</para><para>When the image format is planar the | |
| 2ddb77bb | 83 | <structfield>bytesperline</structfield> value applies to the first |
| 8e080c2e | 84 | plane and is divided by the same factor as the |
| 2ddb77bb | 85 | <structfield>width</structfield> field for the other planes. For |
| 8e080c2e MCC |
86 | example the Cb and Cr planes of a YUV 4:2:0 image have half as many |
| 87 | padding bytes following each line as the Y plane. To avoid ambiguities | |
| 88 | drivers must return a <structfield>bytesperline</structfield> value | |
| 46609297 HV |
89 | rounded up to a multiple of the scale factor.</para> |
| 90 | <para>For compressed formats the <structfield>bytesperline</structfield> | |
| 91 | value makes no sense. Applications and drivers must set this to 0 in | |
| 92 | that case.</para></entry> | |
| 8e080c2e MCC |
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, | |
| 98 | set by the driver. Usually this is | |
| 99 | <structfield>bytesperline</structfield> times | |
| 100 | <structfield>height</structfield>. When the image consists of variable | |
| 101 | length compressed data this is the maximum number of bytes required to | |
| 102 | hold an image.</entry> | |
| 103 | </row> | |
| 104 | <row> | |
| 105 | <entry>&v4l2-colorspace;</entry> | |
| 106 | <entry><structfield>colorspace</structfield></entry> | |
| 107 | <entry>This information supplements the | |
| 46609297 HV |
108 | <structfield>pixelformat</structfield> and must be set by the driver for |
| 109 | capture streams and by the application for output streams, | |
| 8e080c2e MCC |
110 | see <xref linkend="colorspaces" />.</entry> |
| 111 | </row> | |
| 112 | <row> | |
| 113 | <entry>__u32</entry> | |
| 114 | <entry><structfield>priv</structfield></entry> | |
| d52e2381 LP |
115 | <entry><para>This field indicates whether the remaining fields of the |
| 116 | <structname>v4l2_pix_format</structname> structure, also called the extended | |
| 117 | fields, are valid. When set to <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, it | |
| 118 | indicates that the extended fields have been correctly initialized. When set to | |
| 119 | any 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 | |
| 122 | ensure that the feature is supported by querying the device for the | |
| 123 | <link linkend="querycap"><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></link> | |
| 124 | capability. If the capability isn't set the pixel format extended fields are not | |
| 125 | supported 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 | |
| 129 | and 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 | |
| 133 | extended 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 | |
| 136 | applicable values.</para></entry> | |
| 8e080c2e | 137 | </row> |
| c96fd46a LP |
138 | <row> |
| 139 | <entry>__u32</entry> | |
| 140 | <entry><structfield>flags</structfield></entry> | |
| cc036312 | 141 | <entry>Flags set by the application or driver, see <xref |
| c96fd46a LP |
142 | linkend="format-flags" />.</entry> |
| 143 | </row> | |
| cc036312 HV |
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 | |
| 149 | capture streams and by the application for output streams, | |
| 150 | see <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 | |
| 157 | capture streams and by the application for output streams, | |
| 22b6ae48 HV |
158 | see <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 | |
| 165 | capture streams and by the application for output streams, | |
| cc036312 HV |
166 | see <xref linkend="colorspaces" />.</entry> |
| 167 | </row> | |
| 8e080c2e MCC |
168 | </tbody> |
| 169 | </tgroup> | |
| 170 | </table> | |
| 53b5d574 PO |
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"> | |
| ee490b46 | 182 | <title>struct <structname>v4l2_plane_pix_format</structname></title> |
| 53b5d574 PO |
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> | |
| cc7d2dfb | 193 | <entry>__u32</entry> |
| 53b5d574 PO |
194 | <entry><structfield>bytesperline</structfield></entry> |
| 195 | <entry>Distance in bytes between the leftmost pixels in two adjacent | |
| 46609297 | 196 | lines. See &v4l2-pix-format;.</entry> |
| 53b5d574 PO |
197 | </row> |
| 198 | <row> | |
| 199 | <entry>__u16</entry> | |
| cc7d2dfb | 200 | <entry><structfield>reserved[6]</structfield></entry> |
| dc8b1c0e HV |
201 | <entry>Reserved for future extensions. Should be zeroed by drivers and |
| 202 | applications.</entry> | |
| 53b5d574 PO |
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> | |
| 46609297 | 215 | <entry>Image width in pixels. See &v4l2-pix-format;.</entry> |
| 53b5d574 PO |
216 | </row> |
| 217 | <row> | |
| 218 | <entry>__u32</entry> | |
| 219 | <entry><structfield>height</structfield></entry> | |
| 46609297 | 220 | <entry>Image height in pixels. See &v4l2-pix-format;.</entry> |
| 53b5d574 PO |
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 | |
| 226 | codes 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> | |
| c96fd46a LP |
253 | <row> |
| 254 | <entry>__u8</entry> | |
| 255 | <entry><structfield>flags</structfield></entry> | |
| 256 | <entry>Flags set by the application or driver, see <xref | |
| 257 | linkend="format-flags" />.</entry> | |
| cc036312 HV |
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 | |
| 264 | capture streams and by the application for output streams, | |
| 265 | see <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 | |
| 272 | capture streams and by the application for output streams, | |
| 22b6ae48 HV |
273 | see <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 | |
| 280 | capture streams and by the application for output streams, | |
| cc036312 | 281 | see <xref linkend="colorspaces" />.</entry> |
| c96fd46a | 282 | </row> |
| 53b5d574 PO |
283 | <row> |
| 284 | <entry>__u8</entry> | |
| 22b6ae48 | 285 | <entry><structfield>reserved[7]</structfield></entry> |
| dc8b1c0e HV |
286 | <entry>Reserved for future extensions. Should be zeroed by drivers |
| 287 | and applications.</entry> | |
| 53b5d574 PO |
288 | </row> |
| 289 | </tbody> | |
| 290 | </tgroup> | |
| 291 | </table> | |
| 292 | </section> | |
| 8e080c2e MCC |
293 | |
| 294 | <section> | |
| 295 | <title>Standard Image Formats</title> | |
| 296 | ||
| 297 | <para>In order to exchange images between drivers and | |
| 298 | applications, it is necessary to have standard image data formats | |
| 299 | which both sides will interpret the same way. V4L2 includes several | |
| 300 | such formats, and this section is intended to be an unambiguous | |
| 301 | specification of the standard image data formats in V4L2.</para> | |
| 302 | ||
| 303 | <para>V4L2 drivers are not limited to these formats, however. | |
| 304 | Driver-specific formats are possible. In that case the application may | |
| 305 | depend on a codec to convert images to one of the standard formats | |
| 306 | when needed. But the data can still be stored and retrieved in the | |
| 307 | proprietary format. For example, a device may support a proprietary | |
| 308 | compressed format. Applications can still capture and save the data in | |
| 309 | the compressed format, saving much disk space, and later use a codec | |
| 310 | to convert the images to the X Windows screen format when the video is | |
| 311 | to be displayed.</para> | |
| 312 | ||
| 313 | <para>Even so, ultimately, some standard formats are needed, so | |
| 314 | the V4L2 specification would not be complete without well-defined | |
| 315 | standard formats.</para> | |
| 316 | ||
| 317 | <para>The V4L2 standard formats are mainly uncompressed formats. The | |
| 318 | pixels are always arranged in memory from left to right, and from top | |
| 319 | to bottom. The first byte of data in the image buffer is always for | |
| 320 | the leftmost pixel of the topmost row. Following that is the pixel | |
| 321 | immediately to its right, and so on until the end of the top row of | |
| 322 | pixels. Following the rightmost pixel of the row there may be zero or | |
| 323 | more bytes of padding to guarantee that each row of pixel data has a | |
| 324 | certain alignment. Following the pad bytes, if any, is data for the | |
| 325 | leftmost pixel of the second row from the top, and so on. The last row | |
| 326 | has 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 | |
| 53b5d574 | 329 | <constant>PIX_FMT_XXX</constant>, defined in the <link |
| d9cdebd0 | 330 | linkend="videodev">videodev2.h</link> header file. These identifiers |
| 53b5d574 | 331 | represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link> |
| 8e080c2e MCC |
332 | which are also listed below, however they are not the same as those |
| 333 | used in the Windows world.</para> | |
| 53b5d574 PO |
334 | |
| 335 | <para>For some formats, data is stored in separate, discontiguous | |
| 336 | memory buffers. Those formats are identified by a separate set of FourCC codes | |
| 337 | and are referred to as "multi-planar formats". For example, a YUV422 frame is | |
| 338 | normally stored in one memory buffer, but it can also be placed in two or three | |
| 339 | separate buffers, with Y component in one buffer and CbCr components in another | |
| 340 | in the 2-planar version or with each component in its own buffer in the | |
| 341 | 3-planar case. Those sub-buffers are referred to as "planes".</para> | |
| 8e080c2e MCC |
342 | </section> |
| 343 | ||
| 344 | <section id="colorspaces"> | |
| 345 | <title>Colorspaces</title> | |
| 346 | ||
| 1afed883 HV |
347 | <para>'Color' is a very complex concept and depends on physics, chemistry and |
| 348 | biology. Just because you have three numbers that describe the 'red', 'green' | |
| 349 | and 'blue' components of the color of a pixel does not mean that you can accurately | |
| 350 | display that color. A colorspace defines what it actually <emphasis>means</emphasis> | |
| 351 | to have an RGB value of e.g. (255, 0, 0). That is, which color should be | |
| 352 | reproduced on the screen in a perfectly calibrated environment.</para> | |
| 8e080c2e | 353 | |
| 1afed883 HV |
354 | <para>In order to do that we first need to have a good definition of |
| 355 | color, i.e. some way to uniquely and unambiguously define a color so that someone | |
| 356 | else can reproduce it. Human color vision is trichromatic since the human eye has | |
| 357 | color receptors that are sensitive to three different wavelengths of light. Hence | |
| 358 | the need to use three numbers to describe color. Be glad you are not a mantis shrimp | |
| 359 | as those are sensitive to 12 different wavelengths, so instead of RGB we would be | |
| 360 | using the ABCDEFGHIJKL colorspace...</para> | |
| 8e080c2e | 361 | |
| 1afed883 HV |
362 | <para>Color exists only in the eye and brain and is the result of how strongly |
| 363 | color receptors are stimulated. This is based on the Spectral | |
| 364 | Power Distribution (SPD) which is a graph showing the intensity (radiant power) | |
| 365 | of the light at wavelengths covering the visible spectrum as it enters the eye. | |
| 366 | The science of colorimetry is about the relationship between the SPD and color as | |
| 367 | perceived by the human brain.</para> | |
| 368 | ||
| 369 | <para>Since the human eye has only three color receptors it is perfectly | |
| 370 | possible that different SPDs will result in the same stimulation of those receptors | |
| 371 | and are perceived as the same color, even though the SPD of the light is | |
| 372 | different.</para> | |
| 373 | ||
| 374 | <para>In the 1920s experiments were devised to determine the relationship | |
| 375 | between SPDs and the perceived color and that resulted in the CIE 1931 standard | |
| 376 | that defines spectral weighting functions that model the perception of color. | |
| 377 | Specifically that standard defines functions that can take an SPD and calculate | |
| 378 | the stimulus for each color receptor. After some further mathematical transforms | |
| 379 | these stimuli are known as the <emphasis>CIE XYZ tristimulus</emphasis> values | |
| 380 | and these X, Y and Z values describe a color as perceived by a human unambiguously. | |
| 381 | These 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 | |
| 384 | the 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 | |
| 390 | define a color without the luminance component Y. It is very confusing to | |
| 391 | have such similar names for these colorspaces. Just be aware that if colors | |
| 392 | are specified with lower case 'x' and 'y', then the CIE xyY colorspace is | |
| 393 | used. Upper case 'X' and 'Y' refer to the CIE XYZ colorspace. Also, y has nothing | |
| 394 | to do with luminance. Together x and y specify a color, and Y the luminance. | |
| 395 | That is really all you need to remember from a practical point of view. At | |
| 396 | the end of this section you will find reading resources that go into much more | |
| 397 | detail if you are interested. | |
| 398 | </para> | |
| 399 | ||
| 400 | <para>A monitor or TV will reproduce colors by emitting light at three | |
| 401 | different wavelengths, the combination of which will stimulate the color receptors | |
| 402 | in the eye and thus cause the perception of color. Historically these wavelengths | |
| 403 | were 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 | |
| 407 | primaries are more suitable for some display technologies than others. This has | |
| 408 | resulted in a variety of colorspaces that are used for different display | |
| 409 | technologies or uses. To define a colorspace you need to define the three | |
| 410 | color primaries (these are typically defined as x, y chromaticity coordinates | |
| 411 | from the CIE xyY colorspace) but also the white reference: that is the color obtained | |
| 412 | when all three primaries are at maximum power. This determines the relative power | |
| 413 | or energy of the primaries. This is usually chosen to be close to daylight which has | |
| 414 | been defined as the CIE D65 Illuminant.</para> | |
| 415 | ||
| 416 | <para>To recapitulate: the CIE XYZ colorspace uniquely identifies colors. | |
| 417 | Other colorspaces are defined by three chromaticity coordinates defined in the | |
| 418 | CIE xyY colorspace. Based on those a 3x3 matrix can be constructed that | |
| 419 | transforms 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 | |
| 423 | specific chromaticity primaries are linear colorspaces. But neither the eye, | |
| 424 | nor display technology is linear. Doubling the values of all components in | |
| 425 | the linear colorspace will not be perceived as twice the intensity of the color. | |
| 426 | So each colorspace also defines a transfer function that takes a linear color | |
| 427 | component value and transforms it to the non-linear component value, which is a | |
| 428 | closer match to the non-linear performance of both the eye and displays. Linear | |
| 429 | component values are denoted RGB, non-linear are denoted as R'G'B'. In general | |
| 430 | colors used in graphics are all R'G'B', except in openGL which uses linear RGB. | |
| 431 | Special care should be taken when dealing with openGL to provide linear RGB colors | |
| 432 | or 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 | |
| 435 | transforms non-linear R'G'B' to non-linear Y'CbCr. This function is determined | |
| 436 | by the so-called luma coefficients. There may be multiple possible Y'CbCr | |
| 437 | encodings allowed for the same colorspace. Many encodings of color | |
| 438 | prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the human | |
| 439 | eye is more sensitive to differences in luminance than in color this encoding | |
| 440 | allows one to reduce the amount of color information compared to the luma | |
| 441 | data. Note that the luma (Y') is unrelated to the Y in the CIE XYZ colorspace. | |
| 442 | Also note that Y'CbCr is often called YCbCr or YUV even though these are | |
| 443 | strictly speaking wrong.</para> | |
| 444 | ||
| 445 | <para>Sometimes people confuse Y'CbCr as being a colorspace. This is not | |
| 446 | correct, it is just an encoding of an R'G'B' color into luma and chroma | |
| 447 | values. The underlying colorspace that is associated with the R'G'B' color | |
| 448 | is 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 | |
| 451 | quantized. 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 | |
| 453 | another colorspace will produce colors that are outside the [0…1] range. | |
| 454 | Once clamped to the [0…1] range those colors can no longer be reproduced | |
| 455 | in that colorspace. This clamping is what reduces the extent or gamut of the | |
| 456 | colorspace. How the range of [0…1] is translated to integer values in the | |
| 457 | range of [0…255] (or higher, depending on the color depth) is called the | |
| 458 | quantization. This is <emphasis>not</emphasis> part of the colorspace | |
| 459 | definition. In practice RGB or R'G'B' values are full range, i.e. they | |
| 460 | use the full [0…255] range. Y'CbCr values on the other hand are limited | |
| 461 | range 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 | |
| 464 | where the components use the range [16…235]. And full range Y'CbCr also exists | |
| 465 | using the [0…255] range.</para> | |
| 466 | ||
| 467 | <para>In order to correctly interpret a color you need to know the | |
| 468 | quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr encoding | |
| 469 | and the colorspace. | |
| 470 | From that information you can calculate the corresponding CIE XYZ color | |
| 471 | and map that again to whatever colorspace your display device uses.</para> | |
| 472 | ||
| 473 | <para>The colorspace definition itself consists of the three | |
| 474 | chromaticity primaries, the white reference chromaticity, a transfer | |
| 475 | function and the luma coefficients needed to transform R'G'B' to Y'CbCr. While | |
| 476 | some colorspace standards correctly define all four, quite often the colorspace | |
| 477 | standard only defines some, and you have to rely on other standards for | |
| 478 | the missing pieces. The fact that colorspaces are often a mix of different | |
| 479 | standards also led to very confusing naming conventions where the name of | |
| 480 | a standard was used to name a colorspace when in fact that standard was | |
| 481 | part of various other colorspaces as well.</para> | |
| 482 | ||
| 483 | <para>If you want to read more about colors and colorspaces, then the | |
| 484 | following resources are useful: <xref linkend="poynton" /> is a good practical | |
| 485 | book for video engineers, <xref linkend="colimg" /> has a much broader scope and | |
| 486 | describes many more aspects of color (physics, chemistry, biology, etc.). | |
| 487 | The <ulink url="http://www.brucelindbloom.com">http://www.brucelindbloom.com</ulink> | |
| 488 | website is an excellent resource, especially with respect to the mathematics behind | |
| 489 | colorspace 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 | |
| 490 | is also very useful.</para> | |
| 491 | </section> | |
| 492 | ||
| 493 | <section> | |
| 494 | <title>Defining Colorspaces in V4L2</title> | |
| 22b6ae48 HV |
495 | <para>In V4L2 colorspaces are defined by four values. The first is the colorspace |
| 496 | identifier (&v4l2-colorspace;) which defines the chromaticities, the default transfer | |
| 1afed883 | 497 | function, the default Y'CbCr encoding and the default quantization method. The second |
| 22b6ae48 HV |
498 | is the transfer function identifier (&v4l2-xfer-func;) to specify non-standard |
| 499 | transfer functions. The third is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;) | |
| 500 | to 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 | |
| 502 | only the colorspace field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to | |
| 503 | be filled in. Note that the default R'G'B' quantization is full range for all | |
| 504 | colorspaces except for BT.2020 which uses limited range R'G'B' quantization.</para> | |
| 1afed883 HV |
505 | |
| 506 | <table pgwide="1" frame="none" id="v4l2-colorspace"> | |
| 507 | <title>V4L2 Colorspaces</title> | |
| 508 | <tgroup cols="2" align="left"> | |
| 509 | &cs-def; | |
| 8e080c2e MCC |
510 | <thead> |
| 511 | <row> | |
| 1afed883 HV |
512 | <entry>Identifier</entry> |
| 513 | <entry>Details</entry> | |
| 8e080c2e MCC |
514 | </row> |
| 515 | </thead> | |
| 516 | <tbody valign="top"> | |
| da0c211b HV |
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> | |
| 8e080c2e MCC |
522 | <row> |
| 523 | <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> | |
| 1afed883 | 524 | <entry>See <xref linkend="col-smpte-170m" />.</entry> |
| 8e080c2e MCC |
525 | </row> |
| 526 | <row> | |
| 1afed883 HV |
527 | <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> |
| 528 | <entry>See <xref linkend="col-rec709" />.</entry> | |
| 8e080c2e MCC |
529 | </row> |
| 530 | <row> | |
| 1afed883 HV |
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> | |
| 8e080c2e MCC |
537 | </row> |
| 538 | <row> | |
| 1afed883 HV |
539 | <entry><constant>V4L2_COLORSPACE_BT2020</constant></entry> |
| 540 | <entry>See <xref linkend="col-bt2020" />.</entry> | |
| 541 | </row> | |
| 7146a9cf HV |
542 | <row> |
| 543 | <entry><constant>V4L2_COLORSPACE_DCI_P3</constant></entry> | |
| 544 | <entry>See <xref linkend="col-dcip3" />.</entry> | |
| 545 | </row> | |
| 1afed883 HV |
546 | <row> |
| 547 | <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> | |
| 548 | <entry>See <xref linkend="col-smpte-240m" />.</entry> | |
| 8e080c2e MCC |
549 | </row> |
| 550 | <row> | |
| 551 | <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry> | |
| 1afed883 | 552 | <entry>See <xref linkend="col-sysm" />.</entry> |
| 8e080c2e MCC |
553 | </row> |
| 554 | <row> | |
| 555 | <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry> | |
| 1afed883 | 556 | <entry>See <xref linkend="col-sysbg" />.</entry> |
| 8e080c2e MCC |
557 | </row> |
| 558 | <row> | |
| 559 | <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> | |
| 1afed883 HV |
560 | <entry>See <xref linkend="col-jpeg" />.</entry> |
| 561 | </row> | |
| ed9be0b1 HV |
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> | |
| 1afed883 HV |
569 | </tbody> |
| 570 | </tgroup> | |
| 571 | </table> | |
| 572 | ||
| 22b6ae48 HV |
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> | |
| 7146a9cf HV |
608 | <row> |
| 609 | <entry><constant>V4L2_XFER_FUNC_DCI_P3</constant></entry> | |
| 610 | <entry>Use the DCI-P3 transfer function.</entry> | |
| 611 | </row> | |
| 00507a8d HV |
612 | <row> |
| 613 | <entry><constant>V4L2_XFER_FUNC_SMPTE2084</constant></entry> | |
| 614 | <entry>Use the SMPTE 2084 transfer function.</entry> | |
| 615 | </row> | |
| 22b6ae48 HV |
616 | </tbody> |
| 617 | </tgroup> | |
| 618 | </table> | |
| 619 | ||
| 1afed883 HV |
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> | |
| 8e080c2e | 628 | </row> |
| 1afed883 HV |
629 | </thead> |
| 630 | <tbody valign="top"> | |
| 8e080c2e | 631 | <row> |
| 1afed883 HV |
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> | |
| 8e080c2e MCC |
662 | </row> |
| 663 | </tbody> | |
| 664 | </tgroup> | |
| 665 | </table> | |
| 1afed883 HV |
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. | |
| 1acb93ad HV |
681 | This is always full range for R'G'B' (except for the BT.2020 colorspace) and usually |
| 682 | limited range for Y'CbCr.</entry> | |
| 1afed883 HV |
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] | |
| 687 | is mapped to [0…255] (with possible clipping to [1…254] to avoid the | |
| 688 | 0x00 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] | |
| 694 | is 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> | |
| 073e24f5 HV |
704 | <section id="col-smpte-170m"> |
| 705 | <title>Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title> | |
| 1afed883 | 706 | <para>The <xref linkend="smpte170m" /> standard defines the colorspace used by NTSC and PAL and by SDTV |
| 22b6ae48 HV |
707 | in general. The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. |
| 708 | The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. | |
| 1afed883 HV |
709 | The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and |
| 710 | the 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 | |
| 747 | as 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 | |
| e6d72d20 | 751 | one defined in Rec. 709.</term> |
| 1afed883 HV |
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 | |
| 772 | the 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 | |
| 781 | clamped to the range [-0.5…0.5]. This conversion to Y'CbCr is identical to the one | |
| 782 | defined in the <xref linkend="itu601" /> standard and this colorspace is sometimes called BT.601 as well, even | |
| 783 | though BT.601 does not mention any color primaries.</para> | |
| 784 | <para>The default quantization is limited range, but full range is possible although | |
| 785 | rarely seen.</para> | |
| 1afed883 HV |
786 | </section> |
| 787 | ||
| 073e24f5 HV |
788 | <section id="col-rec709"> |
| 789 | <title>Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title> | |
| 22b6ae48 HV |
790 | <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general. |
| 791 | The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. The default | |
| 1afed883 HV |
792 | Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. The default Y'CbCr quantization is |
| 793 | limited 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 | |
| 833 | gamut 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 | |
| 863 | clamped to the range [-0.5…0.5].</para> | |
| 864 | <para>The default quantization is limited range, but full range is possible although | |
| 865 | rarely seen.</para> | |
| 866 | <para>The <constant>V4L2_YCBCR_ENC_709</constant> encoding described above is the default | |
| 867 | for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_601</constant>, in which | |
| 868 | case the BT.601 Y'CbCr encoding is used.</para> | |
| e6d72d20 | 869 | <para>Two additional extended gamut Y'CbCr encodings are also possible with this colorspace:</para> |
| 1afed883 HV |
870 | <variablelist> |
| 871 | <varlistentry> | |
| 872 | <term>The xvYCC 709 encoding (<constant>V4L2_YCBCR_ENC_XV709</constant>, <xref linkend="xvycc" />) | |
| 873 | is 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> | |
| f658d133 HV |
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> | |
| 1afed883 HV |
879 | </listitem> |
| 880 | </varlistentry> | |
| 881 | </variablelist> | |
| e6d72d20 HV |
882 | <variablelist> |
| 883 | <varlistentry> | |
| 884 | <term>The xvYCC 601 encoding (<constant>V4L2_YCBCR_ENC_XV601</constant>, <xref linkend="xvycc" />) is similar | |
| 885 | to 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> | |
| f658d133 HV |
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> | |
| e6d72d20 HV |
891 | </listitem> |
| 892 | </varlistentry> | |
| 893 | </variablelist> | |
| 1afed883 | 894 | <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped |
| e6d72d20 HV |
895 | to the range [-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be used by |
| 896 | selecting <constant>V4L2_YCBCR_ENC_XV709</constant> or <constant>V4L2_YCBCR_ENC_XV601</constant>. | |
| 897 | The xvYCC encodings always use full range quantization.</para> | |
| 1afed883 HV |
898 | </section> |
| 899 | ||
| 073e24f5 HV |
900 | <section id="col-srgb"> |
| 901 | <title>Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title> | |
| 22b6ae48 HV |
902 | <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams |
| 903 | and computer graphics. The default transfer function is <constant>V4L2_XFER_FUNC_SRGB</constant>. | |
| 904 | The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr | |
| 905 | quantization is full range. The chromaticities of the primary colors and the white | |
| 906 | reference are:</para> | |
| 1afed883 HV |
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 | |
| 973 | to the range [-0.5…0.5]. The <constant>V4L2_YCBCR_ENC_SYCC</constant> quantization is always | |
| 974 | full range. Although this Y'CbCr encoding looks very similar to the <constant>V4L2_YCBCR_ENC_XV601</constant> | |
| 975 | encoding, it is not. The <constant>V4L2_YCBCR_ENC_XV601</constant> scales and offsets the Y'CbCr | |
| 976 | values before quantization, but this encoding does not do that.</para> | |
| 977 | </section> | |
| 978 | ||
| 073e24f5 HV |
979 | <section id="col-adobergb"> |
| 980 | <title>Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title> | |
| 1afed883 HV |
981 | <para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics |
| 982 | that use the AdobeRGB colorspace. This is also known as the <xref linkend="oprgb" /> standard. | |
| 22b6ae48 | 983 | The default transfer function is <constant>V4L2_XFER_FUNC_ADOBERGB</constant>. |
| 1afed883 HV |
984 | The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr |
| 985 | quantization is limited range. The chromaticities of the primary colors and the white reference | |
| 986 | are:</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 | |
| 1039 | following <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 | |
| 1048 | clamped to the range [-0.5…0.5]. This transform is identical to one defined in | |
| 1049 | SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para> | |
| 1050 | </section> | |
| 1051 | ||
| 073e24f5 HV |
1052 | <section id="col-bt2020"> |
| 1053 | <title>Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title> | |
| 1afed883 | 1054 | <para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition |
| 22b6ae48 HV |
1055 | television (UHDTV). The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. |
| 1056 | The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>. | |
| 1acb93ad HV |
1057 | The default R'G'B' quantization is limited range (!), and so is the default Y'CbCr quantization. |
| 1058 | The chromaticities of the primary colors and the white reference are:</para> | |
| 1afed883 HV |
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 | |
| 1113 | following <constant>V4L2_YCBCR_ENC_BT2020</constant> encoding:</term> | |
| 1114 | <listitem> | |
| 486e56be | 1115 | <para>Y' = 0.2627R' + 0.6780G' + 0.0593B'</para> |
| 1afed883 HV |
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 | |
| 1122 | clamped 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> | |
| 486e56be | 1129 | <para>Yc' = (0.2627R + 0.6780G + 0.0593B)'</para> |
| 1afed883 HV |
1130 | </listitem> |
| 1131 | </varlistentry> | |
| 1132 | </variablelist> | |
| 1133 | <variablelist> | |
| 1134 | <varlistentry> | |
| 1135 | <term>B' - Yc' ≤ 0:</term> | |
| 1136 | <listitem> | |
| 486e56be | 1137 | <para>Cbc = (B' - Yc') / 1.9404</para> |
| 1afed883 HV |
1138 | </listitem> |
| 1139 | </varlistentry> | |
| 1140 | </variablelist> | |
| 1141 | <variablelist> | |
| 1142 | <varlistentry> | |
| 1143 | <term>B' - Yc' > 0:</term> | |
| 1144 | <listitem> | |
| 486e56be | 1145 | <para>Cbc = (B' - Yc') / 1.5816</para> |
| 1afed883 HV |
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 | |
| 1166 | clamped to the range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.</para> | |
| 1167 | </section> | |
| 1168 | ||
| 7146a9cf HV |
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 | |
| 1172 | projectors that use the DCI-P3 colorspace. | |
| 1173 | The default transfer function is <constant>V4L2_XFER_FUNC_DCI_P3</constant>. | |
| 1174 | The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. Note that this | |
| 1175 | colorspace does not specify a Y'CbCr encoding since it is not meant to be encoded | |
| 1176 | to Y'CbCr. So this default Y'CbCr encoding was picked because it is the HDTV | |
| 1177 | encoding. The default Y'CbCr quantization is limited range. The chromaticities of | |
| 1178 | the 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 | ||
| 073e24f5 HV |
1231 | <section id="col-smpte-240m"> |
| 1232 | <title>Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title> | |
| 22b6ae48 HV |
1233 | <para>The <xref linkend="smpte240m" /> standard was an interim standard used during |
| 1234 | the early days of HDTV (1988-1998). It has been superseded by Rec. 709. | |
| 1235 | The default transfer function is <constant>V4L2_XFER_FUNC_SMPTE240M</constant>. | |
| 1236 | The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>. | |
| 1afed883 HV |
1237 | The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the |
| 1238 | white 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 | |
| 1294 | following <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 | |
| 1303 | clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> | |
| 1304 | </section> | |
| 1305 | ||
| 073e24f5 HV |
1306 | <section id="col-sysm"> |
| 1307 | <title>Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title> | |
| 1afed883 | 1308 | <para>This standard defines the colorspace used by NTSC in 1953. In practice this |
| 22b6ae48 HV |
1309 | colorspace is obsolete and SMPTE 170M should be used instead. |
| 1310 | The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. | |
| 1311 | The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. | |
| 1312 | The default Y'CbCr quantization is limited range. | |
| 1afed883 HV |
1313 | The 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 | |
| 1350 | white reference. To correctly convert an image in this colorspace to another | |
| 1351 | that uses D65 you need to apply a chromatic adaptation algorithm such as the | |
| 1352 | Bradford method.</para> | |
| 1353 | <variablelist> | |
| 1354 | <varlistentry> | |
| 1355 | <term>The transfer function was never properly defined for NTSC 1953. The | |
| 1356 | Rec. 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 | |
| 1373 | following <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 | |
| 1382 | clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. | |
| 1383 | This transform is identical to one defined in SMPTE 170M/BT.601.</para> | |
| 1384 | </section> | |
| 1385 | ||
| 073e24f5 HV |
1386 | <section id="col-sysbg"> |
| 1387 | <title>Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title> | |
| 1afed883 | 1388 | <para>The <xref linkend="tech3213" /> standard defines the colorspace used by PAL/SECAM in 1975. In practice this |
| 22b6ae48 HV |
1389 | colorspace is obsolete and SMPTE 170M should be used instead. |
| 1390 | The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. | |
| 1391 | The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. | |
| 1392 | The default Y'CbCr quantization is limited range. | |
| 1afed883 HV |
1393 | The 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. | |
| 1432 | The 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 | |
| 1449 | following <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 | |
| 1458 | clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. | |
| 1459 | This transform is identical to one defined in SMPTE 170M/BT.601.</para> | |
| 1460 | </section> | |
| 1461 | ||
| 073e24f5 HV |
1462 | <section id="col-jpeg"> |
| 1463 | <title>Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title> | |
| 1afed883 | 1464 | <para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities |
| 22b6ae48 HV |
1465 | of the primary colors and the white reference are identical to sRGB. The transfer |
| 1466 | function use is <constant>V4L2_XFER_FUNC_SRGB</constant>. The Y'CbCr encoding is | |
| 1afed883 HV |
1467 | <constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where |
| 1468 | Y' is scaled to [0…255] and Cb/Cr are scaled to [-128…128] and | |
| 1469 | then clipped to [-128…127].</para> | |
| 1470 | <para>Note that the JPEG standard does not actually store colorspace information. | |
| 1471 | So if something other than sRGB is used, then the driver will have to set that information | |
| 1472 | explicitly. Effectively <constant>V4L2_COLORSPACE_JPEG</constant> can be considered to be | |
| 1473 | an abbreviation for <constant>V4L2_COLORSPACE_SRGB</constant>, <constant>V4L2_YCBCR_ENC_601</constant> | |
| 1474 | and <constant>V4L2_QUANTIZATION_FULL_RANGE</constant>.</para> | |
| 1475 | </section> | |
| 1476 | ||
| 8e080c2e MCC |
1477 | </section> |
| 1478 | ||
| 00507a8d HV |
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 | |
| 1484 | High 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 | ||
| 8e080c2e MCC |
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 | |
| 1518 | into a 256 entry ARGB palette. It is intended for <link | |
| 1519 | linkend="osd">Video Output Overlays</link> only. There are no ioctls to | |
| 1520 | access 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; | |
| 039aa702 | 1589 | &sub-srggb8; |
| 8e080c2e | 1590 | &sub-sbggr16; |
| 039aa702 | 1591 | &sub-srggb10; |
| 4353e36e | 1592 | &sub-srggb10p; |
| 05ad6fc1 | 1593 | &sub-srggb10alaw8; |
| 440f0fad | 1594 | &sub-srggb10dpcm8; |
| 115d2535 | 1595 | &sub-srggb12; |
| 8e080c2e MCC |
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 | |
| 1602 | signals. It separates the brightness information (Y) from the color | |
| 1603 | information (U and V or Cb and Cr). The color information consists of | |
| 1604 | red and blue <emphasis>color difference</emphasis> signals, this way | |
| 1605 | the green component can be reconstructed by subtracting from the | |
| 1606 | brightness component. See <xref linkend="colorspaces" /> for conversion | |
| 1607 | examples. YUV was chosen because early television would only transmit | |
| 1608 | brightness information. To add color in a way compatible with existing | |
| 1609 | receivers a new signal carrier was added to transmit the color | |
| 1610 | difference signals. Secondary in the YUV format the U and V components | |
| 1611 | usually have lower resolution than the Y component. This is an analog | |
| 1612 | video compression technique taking advantage of a property of the | |
| 1613 | human visual system, being more sensitive to brightness | |
| 1614 | information.</para> | |
| 1615 | ||
| 1616 | &sub-packed-yuv; | |
| 1617 | &sub-grey; | |
| 039aa702 | 1618 | &sub-y10; |
| d924de09 | 1619 | &sub-y12; |
| 8bb36c21 | 1620 | &sub-y10b; |
| 8e080c2e | 1621 | &sub-y16; |
| ddfa6c63 | 1622 | &sub-y16-be; |
| 0bec78a4 GL |
1623 | &sub-y8i; |
| 1624 | &sub-y12i; | |
| 05ad6fc1 | 1625 | &sub-uv8; |
| 8e080c2e MCC |
1626 | &sub-yuyv; |
| 1627 | &sub-uyvy; | |
| 1628 | &sub-yvyu; | |
| 1629 | &sub-vyuy; | |
| 1630 | &sub-y41p; | |
| 1631 | &sub-yuv420; | |
| 269da402 | 1632 | &sub-yuv420m; |
| d65fae92 LP |
1633 | &sub-yuv422m; |
| 1634 | &sub-yuv444m; | |
| 8e080c2e MCC |
1635 | &sub-yuv410; |
| 1636 | &sub-yuv422p; | |
| 1637 | &sub-yuv411p; | |
| 1638 | &sub-nv12; | |
| 269da402 | 1639 | &sub-nv12m; |
| bd08a0cd | 1640 | &sub-nv12mt; |
| 8e080c2e | 1641 | &sub-nv16; |
| 84930548 | 1642 | &sub-nv16m; |
| 0b9eabd7 | 1643 | &sub-nv24; |
| 0e59fd05 | 1644 | &sub-m420; |
| 8e080c2e MCC |
1645 | </section> |
| 1646 | ||
| 0bec78a4 GL |
1647 | <section id="depth-formats"> |
| 1648 | <title>Depth Formats</title> | |
| 1649 | <para>Depth data provides distance to points, mapped onto the image plane | |
| 1650 | </para> | |
| 1651 | ||
| 1652 | &sub-z16; | |
| 1653 | </section> | |
| 1654 | ||
| 8e080c2e MCC |
1655 | <section> |
| 1656 | <title>Compressed Formats</title> | |
| 1657 | ||
| 1658 | <table pgwide="1" frame="none" id="compressed-formats"> | |
| 1659 | <title>Compressed Image Formats</title> | |
| 1660 | <tgroup cols="3" align="left"> | |
| 1661 | &cs-def; | |
| 1662 | <thead> | |
| 1663 | <row> | |
| 1664 | <entry>Identifier</entry> | |
| 1665 | <entry>Code</entry> | |
| 1666 | <entry>Details</entry> | |
| 1667 | </row> | |
| 1668 | </thead> | |
| 1669 | <tbody valign="top"> | |
| 1670 | <row id="V4L2-PIX-FMT-JPEG"> | |
| 1671 | <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry> | |
| 1672 | <entry>'JPEG'</entry> | |
| 1673 | <entry>TBD. See also &VIDIOC-G-JPEGCOMP;, | |
| 1674 | &VIDIOC-S-JPEGCOMP;.</entry> | |
| 1675 | </row> | |
| 1676 | <row id="V4L2-PIX-FMT-MPEG"> | |
| 1677 | <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry> | |
| 1678 | <entry>'MPEG'</entry> | |
| 4fa64dae | 1679 | <entry>MPEG multiplexed stream. The actual format is determined by |
| 8e080c2e MCC |
1680 | extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see |
| 1681 | <xref linkend="mpeg-control-id" />.</entry> | |
| 1682 | </row> | |
| 4fa64dae KD |
1683 | <row id="V4L2-PIX-FMT-H264"> |
| 1684 | <entry><constant>V4L2_PIX_FMT_H264</constant></entry> | |
| 1685 | <entry>'H264'</entry> | |
| 1686 | <entry>H264 video elementary stream with start codes.</entry> | |
| 1687 | </row> | |
| 1688 | <row id="V4L2-PIX-FMT-H264-NO-SC"> | |
| 1689 | <entry><constant>V4L2_PIX_FMT_H264_NO_SC</constant></entry> | |
| 1690 | <entry>'AVC1'</entry> | |
| 1691 | <entry>H264 video elementary stream without start codes.</entry> | |
| 1692 | </row> | |
| 4d08f670 AK |
1693 | <row id="V4L2-PIX-FMT-H264-MVC"> |
| 1694 | <entry><constant>V4L2_PIX_FMT_H264_MVC</constant></entry> | |
| f5705194 | 1695 | <entry>'M264'</entry> |
| 4d08f670 AK |
1696 | <entry>H264 MVC video elementary stream.</entry> |
| 1697 | </row> | |
| 4fa64dae KD |
1698 | <row id="V4L2-PIX-FMT-H263"> |
| 1699 | <entry><constant>V4L2_PIX_FMT_H263</constant></entry> | |
| 1700 | <entry>'H263'</entry> | |
| 1701 | <entry>H263 video elementary stream.</entry> | |
| 1702 | </row> | |
| 1703 | <row id="V4L2-PIX-FMT-MPEG1"> | |
| 1704 | <entry><constant>V4L2_PIX_FMT_MPEG1</constant></entry> | |
| 1705 | <entry>'MPG1'</entry> | |
| 1706 | <entry>MPEG1 video elementary stream.</entry> | |
| 1707 | </row> | |
| 1708 | <row id="V4L2-PIX-FMT-MPEG2"> | |
| 1709 | <entry><constant>V4L2_PIX_FMT_MPEG2</constant></entry> | |
| 1710 | <entry>'MPG2'</entry> | |
| 1711 | <entry>MPEG2 video elementary stream.</entry> | |
| 1712 | </row> | |
| 1713 | <row id="V4L2-PIX-FMT-MPEG4"> | |
| 1714 | <entry><constant>V4L2_PIX_FMT_MPEG4</constant></entry> | |
| 1715 | <entry>'MPG4'</entry> | |
| 1716 | <entry>MPEG4 video elementary stream.</entry> | |
| 1717 | </row> | |
| 1718 | <row id="V4L2-PIX-FMT-XVID"> | |
| 1719 | <entry><constant>V4L2_PIX_FMT_XVID</constant></entry> | |
| 1720 | <entry>'XVID'</entry> | |
| 1721 | <entry>Xvid video elementary stream.</entry> | |
| 1722 | </row> | |
| 1723 | <row id="V4L2-PIX-FMT-VC1-ANNEX-G"> | |
| 1724 | <entry><constant>V4L2_PIX_FMT_VC1_ANNEX_G</constant></entry> | |
| 1725 | <entry>'VC1G'</entry> | |
| 1726 | <entry>VC1, SMPTE 421M Annex G compliant stream.</entry> | |
| 1727 | </row> | |
| 1728 | <row id="V4L2-PIX-FMT-VC1-ANNEX-L"> | |
| 1729 | <entry><constant>V4L2_PIX_FMT_VC1_ANNEX_L</constant></entry> | |
| 1730 | <entry>'VC1L'</entry> | |
| 1731 | <entry>VC1, SMPTE 421M Annex L compliant stream.</entry> | |
| 1732 | </row> | |
| 4d08f670 AK |
1733 | <row id="V4L2-PIX-FMT-VP8"> |
| 1734 | <entry><constant>V4L2_PIX_FMT_VP8</constant></entry> | |
| f5705194 | 1735 | <entry>'VP80'</entry> |
| 4d08f670 AK |
1736 | <entry>VP8 video elementary stream.</entry> |
| 1737 | </row> | |
| 8e080c2e MCC |
1738 | </tbody> |
| 1739 | </tgroup> | |
| 1740 | </table> | |
| 1741 | </section> | |
| 1742 | ||
| 559f40fe AP |
1743 | <section id="sdr-formats"> |
| 1744 | <title>SDR Formats</title> | |
| 1745 | ||
| be8ee526 | 1746 | <para>These formats are used for <link linkend="sdr">SDR</link> |
| 559f40fe AP |
1747 | interface only.</para> |
| 1748 | ||
| 0a670c42 | 1749 | &sub-sdr-cu08; |
| e6001abc | 1750 | &sub-sdr-cu16le; |
| fd1e70bf | 1751 | &sub-sdr-cs08; |
| 565092c6 | 1752 | &sub-sdr-cs14le; |
| dd6b66d0 | 1753 | &sub-sdr-ru12le; |
| 0a670c42 | 1754 | |
| 559f40fe AP |
1755 | </section> |
| 1756 | ||
| 8e080c2e MCC |
1757 | <section id="pixfmt-reserved"> |
| 1758 | <title>Reserved Format Identifiers</title> | |
| 1759 | ||
| 1760 | <para>These formats are not defined by this specification, they | |
| 1761 | are just listed for reference and to avoid naming conflicts. If you | |
| 1762 | want to register your own format, send an e-mail to the linux-media mailing | |
| 1763 | list &v4l-ml; for inclusion in the <filename>videodev2.h</filename> | |
| 1764 | file. If you want to share your format with other developers add a | |
| 1765 | link to your documentation and send a copy to the linux-media mailing list | |
| 1766 | for inclusion in this section. If you think your format should be listed | |
| 1767 | in a standard format section please make a proposal on the linux-media mailing | |
| 1768 | list.</para> | |
| 1769 | ||
| 1770 | <table pgwide="1" frame="none" id="reserved-formats"> | |
| 1771 | <title>Reserved Image Formats</title> | |
| 1772 | <tgroup cols="3" align="left"> | |
| 1773 | &cs-def; | |
| 1774 | <thead> | |
| 1775 | <row> | |
| 1776 | <entry>Identifier</entry> | |
| 1777 | <entry>Code</entry> | |
| 1778 | <entry>Details</entry> | |
| 1779 | </row> | |
| 1780 | </thead> | |
| 1781 | <tbody valign="top"> | |
| 1782 | <row id="V4L2-PIX-FMT-DV"> | |
| 1783 | <entry><constant>V4L2_PIX_FMT_DV</constant></entry> | |
| 1784 | <entry>'dvsd'</entry> | |
| 1785 | <entry>unknown</entry> | |
| 1786 | </row> | |
| 1787 | <row id="V4L2-PIX-FMT-ET61X251"> | |
| 1788 | <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry> | |
| 1789 | <entry>'E625'</entry> | |
| 1790 | <entry>Compressed format of the ET61X251 driver.</entry> | |
| 1791 | </row> | |
| 1792 | <row id="V4L2-PIX-FMT-HI240"> | |
| 1793 | <entry><constant>V4L2_PIX_FMT_HI240</constant></entry> | |
| 1794 | <entry>'HI24'</entry> | |
| 1795 | <entry><para>8 bit RGB format used by the BTTV driver.</para></entry> | |
| 1796 | </row> | |
| 1797 | <row id="V4L2-PIX-FMT-HM12"> | |
| 1798 | <entry><constant>V4L2_PIX_FMT_HM12</constant></entry> | |
| 1799 | <entry>'HM12'</entry> | |
| 1800 | <entry><para>YUV 4:2:0 format used by the | |
| 1801 | IVTV driver, <ulink url="http://www.ivtvdriver.org/"> | |
| 1802 | http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the | |
| 1803 | kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename> | |
| 1804 | </para></entry> | |
| 1805 | </row> | |
| a99e3c51 MCC |
1806 | <row id="V4L2-PIX-FMT-CPIA1"> |
| 1807 | <entry><constant>V4L2_PIX_FMT_CPIA1</constant></entry> | |
| 1808 | <entry>'CPIA'</entry> | |
| 1809 | <entry>YUV format used by the gspca cpia1 driver.</entry> | |
| 1810 | </row> | |
| 157e03f2 JFM |
1811 | <row id="V4L2-PIX-FMT-JPGL"> |
| 1812 | <entry><constant>V4L2_PIX_FMT_JPGL</constant></entry> | |
| 1813 | <entry>'JPGL'</entry> | |
| 1814 | <entry>JPEG-Light format (Pegasus Lossless JPEG) | |
| 1815 | used in Divio webcams NW 80x.</entry> | |
| 1816 | </row> | |
| 8e080c2e MCC |
1817 | <row id="V4L2-PIX-FMT-SPCA501"> |
| 1818 | <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry> | |
| 1819 | <entry>'S501'</entry> | |
| 1820 | <entry>YUYV per line used by the gspca driver.</entry> | |
| 1821 | </row> | |
| 1822 | <row id="V4L2-PIX-FMT-SPCA505"> | |
| 1823 | <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry> | |
| 1824 | <entry>'S505'</entry> | |
| 1825 | <entry>YYUV per line used by the gspca driver.</entry> | |
| 1826 | </row> | |
| 1827 | <row id="V4L2-PIX-FMT-SPCA508"> | |
| 1828 | <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry> | |
| 1829 | <entry>'S508'</entry> | |
| 1830 | <entry>YUVY per line used by the gspca driver.</entry> | |
| 1831 | </row> | |
| 1832 | <row id="V4L2-PIX-FMT-SPCA561"> | |
| 1833 | <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry> | |
| 1834 | <entry>'S561'</entry> | |
| 1835 | <entry>Compressed GBRG Bayer format used by the gspca driver.</entry> | |
| 1836 | </row> | |
| 8e080c2e MCC |
1837 | <row id="V4L2-PIX-FMT-PAC207"> |
| 1838 | <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry> | |
| 1839 | <entry>'P207'</entry> | |
| 1840 | <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> | |
| 1841 | </row> | |
| 1842 | <row id="V4L2-PIX-FMT-MR97310A"> | |
| 1843 | <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry> | |
| 1844 | <entry>'M310'</entry> | |
| 1845 | <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> | |
| 1846 | </row> | |
| fe3449a4 TK |
1847 | <row id="V4L2-PIX-FMT-JL2005BCD"> |
| 1848 | <entry><constant>V4L2_PIX_FMT_JL2005BCD</constant></entry> | |
| 1849 | <entry>'JL20'</entry> | |
| 1850 | <entry>JPEG compressed RGGB Bayer format used by the gspca driver.</entry> | |
| 1851 | </row> | |
| 8e080c2e MCC |
1852 | <row id="V4L2-PIX-FMT-OV511"> |
| 1853 | <entry><constant>V4L2_PIX_FMT_OV511</constant></entry> | |
| 1854 | <entry>'O511'</entry> | |
| 1855 | <entry>OV511 JPEG format used by the gspca driver.</entry> | |
| 1856 | </row> | |
| 1857 | <row id="V4L2-PIX-FMT-OV518"> | |
| 1858 | <entry><constant>V4L2_PIX_FMT_OV518</constant></entry> | |
| 1859 | <entry>'O518'</entry> | |
| 1860 | <entry>OV518 JPEG format used by the gspca driver.</entry> | |
| 1861 | </row> | |
| 1862 | <row id="V4L2-PIX-FMT-PJPG"> | |
| 1863 | <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry> | |
| 1864 | <entry>'PJPG'</entry> | |
| 1865 | <entry>Pixart 73xx JPEG format used by the gspca driver.</entry> | |
| 1866 | </row> | |
| 21144ea6 HG |
1867 | <row id="V4L2-PIX-FMT-SE401"> |
| 1868 | <entry><constant>V4L2_PIX_FMT_SE401</constant></entry> | |
| 1869 | <entry>'S401'</entry> | |
| 1870 | <entry>Compressed RGB format used by the gspca se401 driver</entry> | |
| 1871 | </row> | |
| 8e080c2e MCC |
1872 | <row id="V4L2-PIX-FMT-SQ905C"> |
| 1873 | <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry> | |
| 1874 | <entry>'905C'</entry> | |
| 1875 | <entry>Compressed RGGB bayer format used by the gspca driver.</entry> | |
| 1876 | </row> | |
| 1877 | <row id="V4L2-PIX-FMT-MJPEG"> | |
| 1878 | <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry> | |
| 1879 | <entry>'MJPG'</entry> | |
| 1880 | <entry>Compressed format used by the Zoran driver</entry> | |
| 1881 | </row> | |
| 1882 | <row id="V4L2-PIX-FMT-PWC1"> | |
| 1883 | <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry> | |
| 1884 | <entry>'PWC1'</entry> | |
| 1885 | <entry>Compressed format of the PWC driver.</entry> | |
| 1886 | </row> | |
| 1887 | <row id="V4L2-PIX-FMT-PWC2"> | |
| 1888 | <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry> | |
| 1889 | <entry>'PWC2'</entry> | |
| 1890 | <entry>Compressed format of the PWC driver.</entry> | |
| 1891 | </row> | |
| 1892 | <row id="V4L2-PIX-FMT-SN9C10X"> | |
| 1893 | <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry> | |
| 1894 | <entry>'S910'</entry> | |
| 1895 | <entry>Compressed format of the SN9C102 driver.</entry> | |
| 1896 | </row> | |
| 1897 | <row id="V4L2-PIX-FMT-SN9C20X-I420"> | |
| 1898 | <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry> | |
| 1899 | <entry>'S920'</entry> | |
| 1900 | <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry> | |
| 1901 | </row> | |
| a99e3c51 MCC |
1902 | <row id="V4L2-PIX-FMT-SN9C2028"> |
| 1903 | <entry><constant>V4L2_PIX_FMT_SN9C2028</constant></entry> | |
| 1904 | <entry>'SONX'</entry> | |
| 1905 | <entry>Compressed GBRG bayer format of the gspca sn9c2028 driver.</entry> | |
| 1906 | </row> | |
| 47a50307 HV |
1907 | <row id="V4L2-PIX-FMT-STV0680"> |
| 1908 | <entry><constant>V4L2_PIX_FMT_STV0680</constant></entry> | |
| 1909 | <entry>'S680'</entry> | |
| 1910 | <entry>Bayer format of the gspca stv0680 driver.</entry> | |
| 1911 | </row> | |
| 8e080c2e MCC |
1912 | <row id="V4L2-PIX-FMT-WNVA"> |
| 1913 | <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry> | |
| 1914 | <entry>'WNVA'</entry> | |
| 1915 | <entry><para>Used by the Winnov Videum driver, <ulink | |
| 1916 | url="http://www.thedirks.org/winnov/"> | |
| 1917 | http://www.thedirks.org/winnov/</ulink></para></entry> | |
| 1918 | </row> | |
| 4e5fee2b MCC |
1919 | <row id="V4L2-PIX-FMT-TM6000"> |
| 1920 | <entry><constant>V4L2_PIX_FMT_TM6000</constant></entry> | |
| 1921 | <entry>'TM60'</entry> | |
| 1922 | <entry><para>Used by Trident tm6000</para></entry> | |
| 1923 | </row> | |
| 5e765c6e | 1924 | <row id="V4L2-PIX-FMT-CIT-YYVYUY"> |
| 516c714c MCC |
1925 | <entry><constant>V4L2_PIX_FMT_CIT_YYVYUY</constant></entry> |
| 1926 | <entry>'CITV'</entry> | |
| 1927 | <entry><para>Used by xirlink CIT, found at IBM webcams.</para> | |
| 1928 | <para>Uses one line of Y then 1 line of VYUY</para> | |
| 1929 | </entry> | |
| 1930 | </row> | |
| 5e765c6e | 1931 | <row id="V4L2-PIX-FMT-KONICA420"> |
| 516c714c MCC |
1932 | <entry><constant>V4L2_PIX_FMT_KONICA420</constant></entry> |
| 1933 | <entry>'KONI'</entry> | |
| 1934 | <entry><para>Used by Konica webcams.</para> | |
| 1935 | <para>YUV420 planar in blocks of 256 pixels.</para> | |
| 1936 | </entry> | |
| 1937 | </row> | |
| 8e080c2e MCC |
1938 | <row id="V4L2-PIX-FMT-YYUV"> |
| 1939 | <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry> | |
| 1940 | <entry>'YYUV'</entry> | |
| 1941 | <entry>unknown</entry> | |
| 1942 | </row> | |
| b3e212dc HV |
1943 | <row id="V4L2-PIX-FMT-Y4"> |
| 1944 | <entry><constant>V4L2_PIX_FMT_Y4</constant></entry> | |
| 1945 | <entry>'Y04 '</entry> | |
| de87897a | 1946 | <entry>Old 4-bit greyscale format. Only the most significant 4 bits of each byte are used, |
| b3e212dc HV |
1947 | the other bits are set to 0.</entry> |
| 1948 | </row> | |
| 1949 | <row id="V4L2-PIX-FMT-Y6"> | |
| 1950 | <entry><constant>V4L2_PIX_FMT_Y6</constant></entry> | |
| 1951 | <entry>'Y06 '</entry> | |
| de87897a | 1952 | <entry>Old 6-bit greyscale format. Only the most significant 6 bits of each byte are used, |
| b3e212dc HV |
1953 | the other bits are set to 0.</entry> |
| 1954 | </row> | |
| c3010097 SN |
1955 | <row id="V4L2-PIX-FMT-S5C-UYVY-JPG"> |
| 1956 | <entry><constant>V4L2_PIX_FMT_S5C_UYVY_JPG</constant></entry> | |
| 1957 | <entry>'S5CI'</entry> | |
| 1958 | <entry>Two-planar format used by Samsung S5C73MX cameras. The | |
| 1959 | first plane contains interleaved JPEG and UYVY image data, followed by meta data | |
| 1960 | in form of an array of offsets to the UYVY data blocks. The actual pointer array | |
| 1961 | follows immediately the interleaved JPEG/UYVY data, the number of entries in | |
| 1962 | this array equals the height of the UYVY image. Each entry is a 4-byte unsigned | |
| 1963 | integer in big endian order and it's an offset to a single pixel line of the | |
| 1964 | UYVY image. The first plane can start either with JPEG or UYVY data chunk. The | |
| 1965 | size of a single UYVY block equals the UYVY image's width multiplied by 2. The | |
| 1966 | size of a JPEG chunk depends on the image and can vary with each line. | |
| 1967 | <para>The second plane, at an offset of 4084 bytes, contains a 4-byte offset to | |
| 1968 | the pointer array in the first plane. This offset is followed by a 4-byte value | |
| 1969 | indicating size of the pointer array. All numbers in the second plane are also | |
| 1970 | in big endian order. Remaining data in the second plane is undefined. The | |
| 1971 | information in the second plane allows to easily find location of the pointer | |
| 1972 | array, which can be different for each frame. The size of the pointer array is | |
| 1973 | constant for given UYVY image height.</para> | |
| 1974 | <para>In order to extract UYVY and JPEG frames an application can initially set | |
| 1975 | a data pointer to the start of first plane and then add an offset from the first | |
| 1976 | entry of the pointers table. Such a pointer indicates start of an UYVY image | |
| 1977 | pixel line. Whole UYVY line can be copied to a separate buffer. These steps | |
| 1978 | should be repeated for each line, i.e. the number of entries in the pointer | |
| 1979 | array. Anything what's in between the UYVY lines is JPEG data and should be | |
| 1980 | concatenated to form the JPEG stream. </para> | |
| 1981 | </entry> | |
| 1982 | </row> | |
| 8e080c2e MCC |
1983 | </tbody> |
| 1984 | </tgroup> | |
| 1985 | </table> | |
| c96fd46a LP |
1986 | |
| 1987 | <table frame="none" pgwide="1" id="format-flags"> | |
| 1988 | <title>Format Flags</title> | |
| 1989 | <tgroup cols="3"> | |
| 1990 | &cs-def; | |
| 1991 | <tbody valign="top"> | |
| 1992 | <row> | |
| 1993 | <entry><constant>V4L2_PIX_FMT_FLAG_PREMUL_ALPHA</constant></entry> | |
| 1994 | <entry>0x00000001</entry> | |
| 1995 | <entry>The color values are premultiplied by the alpha channel | |
| 1996 | value. For example, if a light blue pixel with 50% transparency was described by | |
| 1997 | RGBA values (128, 192, 255, 128), the same pixel described with premultiplied | |
| 1998 | colors would be described by RGBA values (64, 96, 128, 128) </entry> | |
| 1999 | </row> | |
| 2000 | </tbody> | |
| 2001 | </tgroup> | |
| 2002 | </table> | |
| 8e080c2e | 2003 | </section> |