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