| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
**************************** |
| 5 |
Defining Colorspaces in V4L2 |
| 6 |
**************************** |
| 7 |
|
| 8 |
In V4L2 colorspaces are defined by four values. The first is the |
| 9 |
colorspace identifier (enum :c:type:`v4l2_colorspace`) |
| 10 |
which defines the chromaticities, the default transfer function, the |
| 11 |
default Y'CbCr encoding and the default quantization method. The second |
| 12 |
is the transfer function identifier (enum |
| 13 |
:c:type:`v4l2_xfer_func`) to specify non-standard |
| 14 |
transfer functions. The third is the Y'CbCr encoding identifier (enum |
| 15 |
:c:type:`v4l2_ycbcr_encoding`) to specify |
| 16 |
non-standard Y'CbCr encodings and the fourth is the quantization |
| 17 |
identifier (enum :c:type:`v4l2_quantization`) to |
| 18 |
specify non-standard quantization methods. Most of the time only the |
| 19 |
colorspace field of struct :c:type:`v4l2_pix_format` |
| 20 |
or struct :c:type:`v4l2_pix_format_mplane` |
| 21 |
needs to be filled in. |
| 22 |
|
| 23 |
.. _hsv-colorspace: |
| 24 |
|
| 25 |
On :ref:`HSV formats <hsv-formats>` the *Hue* is defined as the angle on |
| 26 |
the cylindrical color representation. Usually this angle is measured in |
| 27 |
degrees, i.e. 0-360. When we map this angle value into 8 bits, there are |
| 28 |
two basic ways to do it: Divide the angular value by 2 (0-179), or use the |
| 29 |
whole range, 0-255, dividing the angular value by 1.41. The enum |
| 30 |
:c:type:`v4l2_hsv_encoding` specifies which encoding is used. |
| 31 |
|
| 32 |
.. note:: The default R'G'B' quantization is full range for all |
| 33 |
colorspaces. HSV formats are always full range. |
| 34 |
|
| 35 |
.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| |
| 36 |
|
| 37 |
.. c:type:: v4l2_colorspace |
| 38 |
|
| 39 |
.. flat-table:: V4L2 Colorspaces |
| 40 |
:header-rows: 1 |
| 41 |
:stub-columns: 0 |
| 42 |
|
| 43 |
* - Identifier |
| 44 |
- Details |
| 45 |
* - ``V4L2_COLORSPACE_DEFAULT`` |
| 46 |
- The default colorspace. This can be used by applications to let |
| 47 |
the driver fill in the colorspace. |
| 48 |
* - ``V4L2_COLORSPACE_SMPTE170M`` |
| 49 |
- See :ref:`col-smpte-170m`. |
| 50 |
* - ``V4L2_COLORSPACE_REC709`` |
| 51 |
- See :ref:`col-rec709`. |
| 52 |
* - ``V4L2_COLORSPACE_SRGB`` |
| 53 |
- See :ref:`col-srgb`. |
| 54 |
* - ``V4L2_COLORSPACE_OPRGB`` |
| 55 |
- See :ref:`col-oprgb`. |
| 56 |
* - ``V4L2_COLORSPACE_BT2020`` |
| 57 |
- See :ref:`col-bt2020`. |
| 58 |
* - ``V4L2_COLORSPACE_DCI_P3`` |
| 59 |
- See :ref:`col-dcip3`. |
| 60 |
* - ``V4L2_COLORSPACE_SMPTE240M`` |
| 61 |
- See :ref:`col-smpte-240m`. |
| 62 |
* - ``V4L2_COLORSPACE_470_SYSTEM_M`` |
| 63 |
- See :ref:`col-sysm`. |
| 64 |
* - ``V4L2_COLORSPACE_470_SYSTEM_BG`` |
| 65 |
- See :ref:`col-sysbg`. |
| 66 |
* - ``V4L2_COLORSPACE_JPEG`` |
| 67 |
- See :ref:`col-jpeg`. |
| 68 |
* - ``V4L2_COLORSPACE_RAW`` |
| 69 |
- The raw colorspace. This is used for raw image capture where the |
| 70 |
image is minimally processed and is using the internal colorspace |
| 71 |
of the device. The software that processes an image using this |
| 72 |
'colorspace' will have to know the internals of the capture |
| 73 |
device. |
| 74 |
|
| 75 |
|
| 76 |
|
| 77 |
.. c:type:: v4l2_xfer_func |
| 78 |
|
| 79 |
.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| |
| 80 |
|
| 81 |
.. flat-table:: V4L2 Transfer Function |
| 82 |
:header-rows: 1 |
| 83 |
:stub-columns: 0 |
| 84 |
|
| 85 |
* - Identifier |
| 86 |
- Details |
| 87 |
* - ``V4L2_XFER_FUNC_DEFAULT`` |
| 88 |
- Use the default transfer function as defined by the colorspace. |
| 89 |
* - ``V4L2_XFER_FUNC_709`` |
| 90 |
- Use the Rec. 709 transfer function. |
| 91 |
* - ``V4L2_XFER_FUNC_SRGB`` |
| 92 |
- Use the sRGB transfer function. |
| 93 |
* - ``V4L2_XFER_FUNC_OPRGB`` |
| 94 |
- Use the opRGB transfer function. |
| 95 |
* - ``V4L2_XFER_FUNC_SMPTE240M`` |
| 96 |
- Use the SMPTE 240M transfer function. |
| 97 |
* - ``V4L2_XFER_FUNC_NONE`` |
| 98 |
- Do not use a transfer function (i.e. use linear RGB values). |
| 99 |
* - ``V4L2_XFER_FUNC_DCI_P3`` |
| 100 |
- Use the DCI-P3 transfer function. |
| 101 |
* - ``V4L2_XFER_FUNC_SMPTE2084`` |
| 102 |
- Use the SMPTE 2084 transfer function. See :ref:`xf-smpte-2084`. |
| 103 |
|
| 104 |
|
| 105 |
|
| 106 |
.. c:type:: v4l2_ycbcr_encoding |
| 107 |
|
| 108 |
.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| |
| 109 |
|
| 110 |
.. flat-table:: V4L2 Y'CbCr Encodings |
| 111 |
:header-rows: 1 |
| 112 |
:stub-columns: 0 |
| 113 |
|
| 114 |
* - Identifier |
| 115 |
- Details |
| 116 |
* - ``V4L2_YCBCR_ENC_DEFAULT`` |
| 117 |
- Use the default Y'CbCr encoding as defined by the colorspace. |
| 118 |
* - ``V4L2_YCBCR_ENC_601`` |
| 119 |
- Use the BT.601 Y'CbCr encoding. |
| 120 |
* - ``V4L2_YCBCR_ENC_709`` |
| 121 |
- Use the Rec. 709 Y'CbCr encoding. |
| 122 |
* - ``V4L2_YCBCR_ENC_XV601`` |
| 123 |
- Use the extended gamut xvYCC BT.601 encoding. |
| 124 |
* - ``V4L2_YCBCR_ENC_XV709`` |
| 125 |
- Use the extended gamut xvYCC Rec. 709 encoding. |
| 126 |
* - ``V4L2_YCBCR_ENC_BT2020`` |
| 127 |
- Use the default non-constant luminance BT.2020 Y'CbCr encoding. |
| 128 |
* - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM`` |
| 129 |
- Use the constant luminance BT.2020 Yc'CbcCrc encoding. |
| 130 |
* - ``V4L2_YCBCR_ENC_SMPTE_240M`` |
| 131 |
- Use the SMPTE 240M Y'CbCr encoding. |
| 132 |
|
| 133 |
|
| 134 |
|
| 135 |
.. c:type:: v4l2_hsv_encoding |
| 136 |
|
| 137 |
.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| |
| 138 |
|
| 139 |
.. flat-table:: V4L2 HSV Encodings |
| 140 |
:header-rows: 1 |
| 141 |
:stub-columns: 0 |
| 142 |
|
| 143 |
* - Identifier |
| 144 |
- Details |
| 145 |
* - ``V4L2_HSV_ENC_180`` |
| 146 |
- For the Hue, each LSB is two degrees. |
| 147 |
* - ``V4L2_HSV_ENC_256`` |
| 148 |
- For the Hue, the 360 degrees are mapped into 8 bits, i.e. each |
| 149 |
LSB is roughly 1.41 degrees. |
| 150 |
|
| 151 |
|
| 152 |
|
| 153 |
.. c:type:: v4l2_quantization |
| 154 |
|
| 155 |
.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| |
| 156 |
|
| 157 |
.. flat-table:: V4L2 Quantization Methods |
| 158 |
:header-rows: 1 |
| 159 |
:stub-columns: 0 |
| 160 |
|
| 161 |
* - Identifier |
| 162 |
- Details |
| 163 |
* - ``V4L2_QUANTIZATION_DEFAULT`` |
| 164 |
- Use the default quantization encoding as defined by the |
| 165 |
colorspace. This is always full range for R'G'B' and HSV. |
| 166 |
It is usually limited range for Y'CbCr. |
| 167 |
* - ``V4L2_QUANTIZATION_FULL_RANGE`` |
| 168 |
- Use the full range quantization encoding. I.e. the range [0…1] is |
| 169 |
mapped to [0…255] (with possible clipping to [1…254] to avoid the |
| 170 |
0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to |
| 171 |
[0…255] (with possible clipping to [1…254] to avoid the 0x00 and |
| 172 |
0xff values). |
| 173 |
* - ``V4L2_QUANTIZATION_LIM_RANGE`` |
| 174 |
- Use the limited range quantization encoding. I.e. the range [0…1] |
| 175 |
is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to |
| 176 |
[16…240]. Limited Range cannot be used with HSV. |