Documentation/media/uapi/v4l/pixfmt-006.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 ****************************
   4 Defining Colorspaces in V4L2
   5 ****************************
   6
   7 In V4L2 colorspaces are defined by four values. The first is the
   8 colorspace identifier (enum :ref:`v4l2_colorspace <v4l2-colorspace>`)
   9 which defines the chromaticities, the default transfer function, the
  10 default Y'CbCr encoding and the default quantization method. The second
  11 is the transfer function identifier (enum
  12 :ref:`v4l2_xfer_func <v4l2-xfer-func>`) to specify non-standard
  13 transfer functions. The third is the Y'CbCr encoding identifier (enum
  14 :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`) to specify
  15 non-standard Y'CbCr encodings and the fourth is the quantization
  16 identifier (enum :ref:`v4l2_quantization <v4l2-quantization>`) to
  17 specify non-standard quantization methods. Most of the time only the
  18 colorspace field of struct :ref:`v4l2_pix_format <v4l2-pix-format>`
  19 or struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>`
  20 needs to be filled in.
  21
  22 .. note:: The default R'G'B' quantization is full range for all
  23    colorspaces except for BT.2020 which uses limited range R'G'B'
  24    quantization.
  25
  26
  27 .. _v4l2-colorspace:
  28
  29 .. flat-table:: V4L2 Colorspaces
  30     :header-rows:  1
  31     :stub-columns: 0
  32
  33
  34     -  .. row 1
  35
  36        -  Identifier
  37
  38        -  Details
  39
  40     -  .. row 2
  41
  42        -  ``V4L2_COLORSPACE_DEFAULT``
  43
  44        -  The default colorspace. This can be used by applications to let
  45           the driver fill in the colorspace.
  46
  47     -  .. row 3
  48
  49        -  ``V4L2_COLORSPACE_SMPTE170M``
  50
  51        -  See :ref:`col-smpte-170m`.
  52
  53     -  .. row 4
  54
  55        -  ``V4L2_COLORSPACE_REC709``
  56
  57        -  See :ref:`col-rec709`.
  58
  59     -  .. row 5
  60
  61        -  ``V4L2_COLORSPACE_SRGB``
  62
  63        -  See :ref:`col-srgb`.
  64
  65     -  .. row 6
  66
  67        -  ``V4L2_COLORSPACE_ADOBERGB``
  68
  69        -  See :ref:`col-adobergb`.
  70
  71     -  .. row 7
  72
  73        -  ``V4L2_COLORSPACE_BT2020``
  74
  75        -  See :ref:`col-bt2020`.
  76
  77     -  .. row 8
  78
  79        -  ``V4L2_COLORSPACE_DCI_P3``
  80
  81        -  See :ref:`col-dcip3`.
  82
  83     -  .. row 9
  84
  85        -  ``V4L2_COLORSPACE_SMPTE240M``
  86
  87        -  See :ref:`col-smpte-240m`.
  88
  89     -  .. row 10
  90
  91        -  ``V4L2_COLORSPACE_470_SYSTEM_M``
  92
  93        -  See :ref:`col-sysm`.
  94
  95     -  .. row 11
  96
  97        -  ``V4L2_COLORSPACE_470_SYSTEM_BG``
  98
  99        -  See :ref:`col-sysbg`.
 100
 101     -  .. row 12
 102
 103        -  ``V4L2_COLORSPACE_JPEG``
 104
 105        -  See :ref:`col-jpeg`.
 106
 107     -  .. row 13
 108
 109        -  ``V4L2_COLORSPACE_RAW``
 110
 111        -  The raw colorspace. This is used for raw image capture where the
 112           image is minimally processed and is using the internal colorspace
 113           of the device. The software that processes an image using this
 114           'colorspace' will have to know the internals of the capture
 115           device.
 116
 117
 118
 119 .. _v4l2-xfer-func:
 120
 121 .. flat-table:: V4L2 Transfer Function
 122     :header-rows:  1
 123     :stub-columns: 0
 124
 125
 126     -  .. row 1
 127
 128        -  Identifier
 129
 130        -  Details
 131
 132     -  .. row 2
 133
 134        -  ``V4L2_XFER_FUNC_DEFAULT``
 135
 136        -  Use the default transfer function as defined by the colorspace.
 137
 138     -  .. row 3
 139
 140        -  ``V4L2_XFER_FUNC_709``
 141
 142        -  Use the Rec. 709 transfer function.
 143
 144     -  .. row 4
 145
 146        -  ``V4L2_XFER_FUNC_SRGB``
 147
 148        -  Use the sRGB transfer function.
 149
 150     -  .. row 5
 151
 152        -  ``V4L2_XFER_FUNC_ADOBERGB``
 153
 154        -  Use the AdobeRGB transfer function.
 155
 156     -  .. row 6
 157
 158        -  ``V4L2_XFER_FUNC_SMPTE240M``
 159
 160        -  Use the SMPTE 240M transfer function.
 161
 162     -  .. row 7
 163
 164        -  ``V4L2_XFER_FUNC_NONE``
 165
 166        -  Do not use a transfer function (i.e. use linear RGB values).
 167
 168     -  .. row 8
 169
 170        -  ``V4L2_XFER_FUNC_DCI_P3``
 171
 172        -  Use the DCI-P3 transfer function.
 173
 174     -  .. row 9
 175
 176        -  ``V4L2_XFER_FUNC_SMPTE2084``
 177
 178        -  Use the SMPTE 2084 transfer function.
 179
 180
 181
 182 .. _v4l2-ycbcr-encoding:
 183
 184 .. flat-table:: V4L2 Y'CbCr Encodings
 185     :header-rows:  1
 186     :stub-columns: 0
 187
 188
 189     -  .. row 1
 190
 191        -  Identifier
 192
 193        -  Details
 194
 195     -  .. row 2
 196
 197        -  ``V4L2_YCBCR_ENC_DEFAULT``
 198
 199        -  Use the default Y'CbCr encoding as defined by the colorspace.
 200
 201     -  .. row 3
 202
 203        -  ``V4L2_YCBCR_ENC_601``
 204
 205        -  Use the BT.601 Y'CbCr encoding.
 206
 207     -  .. row 4
 208
 209        -  ``V4L2_YCBCR_ENC_709``
 210
 211        -  Use the Rec. 709 Y'CbCr encoding.
 212
 213     -  .. row 5
 214
 215        -  ``V4L2_YCBCR_ENC_XV601``
 216
 217        -  Use the extended gamut xvYCC BT.601 encoding.
 218
 219     -  .. row 6
 220
 221        -  ``V4L2_YCBCR_ENC_XV709``
 222
 223        -  Use the extended gamut xvYCC Rec. 709 encoding.
 224
 225     -  .. row 7
 226
 227        -  ``V4L2_YCBCR_ENC_SYCC``
 228
 229        -  Use the extended gamut sYCC encoding.
 230
 231     -  .. row 8
 232
 233        -  ``V4L2_YCBCR_ENC_BT2020``
 234
 235        -  Use the default non-constant luminance BT.2020 Y'CbCr encoding.
 236
 237     -  .. row 9
 238
 239        -  ``V4L2_YCBCR_ENC_BT2020_CONST_LUM``
 240
 241        -  Use the constant luminance BT.2020 Yc'CbcCrc encoding.
 242
 243     -  .. row 10
 244
 245        -  ``V4L2_YCBCR_ENC_SMPTE_240M``
 246
 247        -  Use the SMPTE 240M Y'CbCr encoding.
 248
 249
 250
 251 .. _v4l2-quantization:
 252
 253 .. flat-table:: V4L2 Quantization Methods
 254     :header-rows:  1
 255     :stub-columns: 0
 256
 257
 258     -  .. row 1
 259
 260        -  Identifier
 261
 262        -  Details
 263
 264     -  .. row 2
 265
 266        -  ``V4L2_QUANTIZATION_DEFAULT``
 267
 268        -  Use the default quantization encoding as defined by the
 269           colorspace. This is always full range for R'G'B' (except for the
 270           BT.2020 colorspace) and usually limited range for Y'CbCr.
 271
 272     -  .. row 3
 273
 274        -  ``V4L2_QUANTIZATION_FULL_RANGE``
 275
 276        -  Use the full range quantization encoding. I.e. the range [0…1] is
 277           mapped to [0…255] (with possible clipping to [1…254] to avoid the
 278           0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to
 279           [0…255] (with possible clipping to [1…254] to avoid the 0x00 and
 280           0xff values).
 281
 282     -  .. row 4
 283
 284        -  ``V4L2_QUANTIZATION_LIM_RANGE``
 285
 286        -  Use the limited range quantization encoding. I.e. the range [0…1]
 287           is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to
 288           [16…240].