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