Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2
   3 .. _packed-yuv:
   4
   5 ******************
   6 Packed YUV formats
   7 ******************
   8
   9 Similarly to the packed RGB formats, the packed YUV formats store the Y, Cb and
  10 Cr components consecutively in memory. They may apply subsampling to the chroma
  11 components and thus differ in how they interlave the three components.
  12
  13 .. note::
  14
  15    - In all the tables that follow, bit 7 is the most significant bit in a byte.
  16    - 'Y', 'Cb' and 'Cr' denote bits of the luma, blue chroma (also known as
  17      'U') and red chroma (also known as 'V') components respectively. 'A'
  18      denotes bits of the alpha component (if supported by the format), and 'X'
  19      denotes padding bits.
  20
  21
  22 4:4:4 Subsampling
  23 =================
  24
  25 These formats do not subsample the chroma components and store each pixels as a
  26 full triplet of Y, Cb and Cr values.
  27
  28 The next table lists the packed YUV 4:4:4 formats with less than 8 bits per
  29 component. They are named based on the order of the Y, Cb and Cr components as
  30 seen in a 16-bit word, which is then stored in memory in little endian byte
  31 order, and on the number of bits for each component. For instance the YUV565
  32 format stores a pixel in a 16-bit word [15:0] laid out at as [Y'\ :sub:`4-0`
  33 Cb\ :sub:`5-0` Cr\ :sub:`4-0`], and stored in memory in two bytes,
  34 [Cb\ :sub:`2-0` Cr\ :sub:`4-0`] followed by [Y'\ :sub:`4-0` Cb\ :sub:`5-3`].
  35
  36 .. raw:: latex
  37
  38     \begingroup
  39     \tiny
  40     \setlength{\tabcolsep}{2pt}
  41
  42 .. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|
  43
  44 .. flat-table:: Packed YUV 4:4:4 Image Formats (less than 8bpc)
  45     :header-rows:  2
  46     :stub-columns: 0
  47
  48     * - Identifier
  49       - Code
  50
  51       - :cspan:`7` Byte 0 in memory
  52
  53       - :cspan:`7` Byte 1
  54
  55     * -
  56       -
  57       - 7
  58       - 6
  59       - 5
  60       - 4
  61       - 3
  62       - 2
  63       - 1
  64       - 0
  65
  66       - 7
  67       - 6
  68       - 5
  69       - 4
  70       - 3
  71       - 2
  72       - 1
  73       - 0
  74
  75     * .. _V4L2-PIX-FMT-YUV444:
  76
  77       - ``V4L2_PIX_FMT_YUV444``
  78       - 'Y444'
  79
  80       - Cb\ :sub:`3`
  81       - Cb\ :sub:`2`
  82       - Cb\ :sub:`1`
  83       - Cb\ :sub:`0`
  84       - Cr\ :sub:`3`
  85       - Cr\ :sub:`2`
  86       - Cr\ :sub:`1`
  87       - Cr\ :sub:`0`
  88
  89       - a\ :sub:`3`
  90       - a\ :sub:`2`
  91       - a\ :sub:`1`
  92       - a\ :sub:`0`
  93       - Y'\ :sub:`3`
  94       - Y'\ :sub:`2`
  95       - Y'\ :sub:`1`
  96       - Y'\ :sub:`0`
  97
  98     * .. _V4L2-PIX-FMT-YUV555:
  99
 100       - ``V4L2_PIX_FMT_YUV555``
 101       - 'YUVO'
 102
 103       - Cb\ :sub:`2`
 104       - Cb\ :sub:`1`
 105       - Cb\ :sub:`0`
 106       - Cr\ :sub:`4`
 107       - Cr\ :sub:`3`
 108       - Cr\ :sub:`2`
 109       - Cr\ :sub:`1`
 110       - Cr\ :sub:`0`
 111
 112       - a
 113       - Y'\ :sub:`4`
 114       - Y'\ :sub:`3`
 115       - Y'\ :sub:`2`
 116       - Y'\ :sub:`1`
 117       - Y'\ :sub:`0`
 118       - Cb\ :sub:`4`
 119       - Cb\ :sub:`3`
 120
 121     * .. _V4L2-PIX-FMT-YUV565:
 122
 123       - ``V4L2_PIX_FMT_YUV565``
 124       - 'YUVP'
 125
 126       - Cb\ :sub:`2`
 127       - Cb\ :sub:`1`
 128       - Cb\ :sub:`0`
 129       - Cr\ :sub:`4`
 130       - Cr\ :sub:`3`
 131       - Cr\ :sub:`2`
 132       - Cr\ :sub:`1`
 133       - Cr\ :sub:`0`
 134
 135       - Y'\ :sub:`4`
 136       - Y'\ :sub:`3`
 137       - Y'\ :sub:`2`
 138       - Y'\ :sub:`1`
 139       - Y'\ :sub:`0`
 140       - Cb\ :sub:`5`
 141       - Cb\ :sub:`4`
 142       - Cb\ :sub:`3`
 143
 144 .. raw:: latex
 145
 146     \endgroup
 147
 148 .. note::
 149
 150     For the YUV444 and YUV555 formats, the value of alpha bits is undefined
 151     when reading from the driver, ignored when writing to the driver, except
 152     when alpha blending has been negotiated for a :ref:`Video Overlay
 153     <overlay>` or :ref:`Video Output Overlay <osd>`.
 154
 155
 156 The next table lists the packed YUV 4:4:4 formats with 8 bits per component.
 157 They are named based on the order of the Y, Cb and Cr components as stored in
 158 memory, and on the total number of bits per pixel. For instance, the VUYX32
 159 format stores a pixel with Cr\ :sub:`7-0` in the first byte, Cb\ :sub:`7-0` in
 160 the second byte and Y'\ :sub:`7-0` in the third byte.
 161
 162 .. flat-table:: Packed YUV Image Formats (8bpc)
 163     :header-rows: 1
 164     :stub-columns: 0
 165
 166     * - Identifier
 167       - Code
 168       - Byte 0
 169       - Byte 1
 170       - Byte 2
 171       - Byte 3
 172
 173     * .. _V4L2-PIX-FMT-YUV32:
 174
 175       - ``V4L2_PIX_FMT_YUV32``
 176       - 'YUV4'
 177
 178       - A\ :sub:`7-0`
 179       - Y'\ :sub:`7-0`
 180       - Cb\ :sub:`7-0`
 181       - Cr\ :sub:`7-0`
 182
 183     * .. _V4L2-PIX-FMT-AYUV32:
 184
 185       - ``V4L2_PIX_FMT_AYUV32``
 186       - 'AYUV'
 187
 188       - A\ :sub:`7-0`
 189       - Y'\ :sub:`7-0`
 190       - Cb\ :sub:`7-0`
 191       - Cr\ :sub:`7-0`
 192
 193     * .. _V4L2-PIX-FMT-XYUV32:
 194
 195       - ``V4L2_PIX_FMT_XYUV32``
 196       - 'XYUV'
 197
 198       - X\ :sub:`7-0`
 199       - Y'\ :sub:`7-0`
 200       - Cb\ :sub:`7-0`
 201       - Cr\ :sub:`7-0`
 202
 203     * .. _V4L2-PIX-FMT-VUYA32:
 204
 205       - ``V4L2_PIX_FMT_VUYA32``
 206       - 'VUYA'
 207
 208       - Cr\ :sub:`7-0`
 209       - Cb\ :sub:`7-0`
 210       - Y'\ :sub:`7-0`
 211       - A\ :sub:`7-0`
 212
 213     * .. _V4L2-PIX-FMT-VUYX32:
 214
 215       - ``V4L2_PIX_FMT_VUYX32``
 216       - 'VUYX'
 217
 218       - Cr\ :sub:`7-0`
 219       - Cb\ :sub:`7-0`
 220       - Y'\ :sub:`7-0`
 221       - X\ :sub:`7-0`
 222
 223 .. note::
 224
 225     - The alpha component is expected to contain a meaningful value that can be
 226       used by drivers and applications.
 227     - The padding bits contain undefined values that must be ignored by all
 228       applications and drivers.
 229
 230
 231 4:2:2 Subsampling
 232 =================
 233
 234 These formats, commonly referred to as YUYV or YUY2, subsample the chroma
 235 components horizontally by 2, storing 2 pixels in 4 bytes.
 236
 237 .. flat-table:: Packed YUV 4:2:2 Formats
 238     :header-rows: 1
 239     :stub-columns: 0
 240
 241     * - Identifier
 242       - Code
 243       - Byte 0
 244       - Byte 1
 245       - Byte 2
 246       - Byte 3
 247       - Byte 4
 248       - Byte 5
 249       - Byte 6
 250       - Byte 7
 251     * .. _V4L2-PIX-FMT-UYVY:
 252
 253       - ``V4L2_PIX_FMT_UYVY``
 254       - 'UYVY'
 255
 256       - Cb\ :sub:`0`
 257       - Y'\ :sub:`0`
 258       - Cr\ :sub:`0`
 259       - Y'\ :sub:`1`
 260       - Cb\ :sub:`2`
 261       - Y'\ :sub:`2`
 262       - Cr\ :sub:`2`
 263       - Y'\ :sub:`3`
 264     * .. _V4L2-PIX-FMT-VYUY:
 265
 266       - ``V4L2_PIX_FMT_VYUY``
 267       - 'VYUY'
 268
 269       - Cr\ :sub:`0`
 270       - Y'\ :sub:`0`
 271       - Cb\ :sub:`0`
 272       - Y'\ :sub:`1`
 273       - Cr\ :sub:`2`
 274       - Y'\ :sub:`2`
 275       - Cb\ :sub:`2`
 276       - Y'\ :sub:`3`
 277     * .. _V4L2-PIX-FMT-YUYV:
 278
 279       - ``V4L2_PIX_FMT_YUYV``
 280       - 'YUYV'
 281
 282       - Y'\ :sub:`0`
 283       - Cb\ :sub:`0`
 284       - Y'\ :sub:`1`
 285       - Cr\ :sub:`0`
 286       - Y'\ :sub:`2`
 287       - Cb\ :sub:`2`
 288       - Y'\ :sub:`3`
 289       - Cr\ :sub:`2`
 290     * .. _V4L2-PIX-FMT-YVYU:
 291
 292       - ``V4L2_PIX_FMT_YVYU``
 293       - 'YVYU'
 294
 295       - Y'\ :sub:`0`
 296       - Cr\ :sub:`0`
 297       - Y'\ :sub:`1`
 298       - Cb\ :sub:`0`
 299       - Y'\ :sub:`2`
 300       - Cr\ :sub:`2`
 301       - Y'\ :sub:`3`
 302       - Cb\ :sub:`2`
 303
 304 **Color Sample Location:**
 305 Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
 306 horizontally.
 307
 308
 309 4:1:1 Subsampling
 310 =================
 311
 312 This format subsamples the chroma components horizontally by 4, storing 8
 313 pixels in 12 bytes.
 314
 315 .. flat-table:: Packed YUV 4:1:1 Formats
 316     :header-rows: 1
 317     :stub-columns: 0
 318
 319     * - Identifier
 320       - Code
 321       - Byte 0
 322       - Byte 1
 323       - Byte 2
 324       - Byte 3
 325       - Byte 4
 326       - Byte 5
 327       - Byte 6
 328       - Byte 7
 329       - Byte 8
 330       - Byte 9
 331       - Byte 10
 332       - Byte 11
 333     * .. _V4L2-PIX-FMT-Y41P:
 334
 335       - ``V4L2_PIX_FMT_Y41P``
 336       - 'Y41P'
 337
 338       - Cb\ :sub:`0`
 339       - Y'\ :sub:`0`
 340       - Cr\ :sub:`0`
 341       - Y'\ :sub:`1`
 342       - Cb\ :sub:`4`
 343       - Y'\ :sub:`2`
 344       - Cr\ :sub:`4`
 345       - Y'\ :sub:`3`
 346       - Y'\ :sub:`4`
 347       - Y'\ :sub:`5`
 348       - Y'\ :sub:`6`
 349       - Y'\ :sub:`7`
 350
 351 .. note::
 352
 353     Do not confuse ``V4L2_PIX_FMT_Y41P`` with
 354     :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived from
 355     "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 *planar*".
 356
 357 **Color Sample Location:**
 358 Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
 359 horizontally.