1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 254f38fcaSMauro Carvalho Chehab 354f38fcaSMauro Carvalho Chehab**************************** 454f38fcaSMauro Carvalho ChehabDefining Colorspaces in V4L2 554f38fcaSMauro Carvalho Chehab**************************** 654f38fcaSMauro Carvalho Chehab 754f38fcaSMauro Carvalho ChehabIn V4L2 colorspaces are defined by four values. The first is the 854f38fcaSMauro Carvalho Chehabcolorspace identifier (enum :c:type:`v4l2_colorspace`) 954f38fcaSMauro Carvalho Chehabwhich defines the chromaticities, the default transfer function, the 1054f38fcaSMauro Carvalho Chehabdefault Y'CbCr encoding and the default quantization method. The second 1154f38fcaSMauro Carvalho Chehabis the transfer function identifier (enum 1254f38fcaSMauro Carvalho Chehab:c:type:`v4l2_xfer_func`) to specify non-standard 1354f38fcaSMauro Carvalho Chehabtransfer functions. The third is the Y'CbCr encoding identifier (enum 1454f38fcaSMauro Carvalho Chehab:c:type:`v4l2_ycbcr_encoding`) to specify 1554f38fcaSMauro Carvalho Chehabnon-standard Y'CbCr encodings and the fourth is the quantization 1654f38fcaSMauro Carvalho Chehabidentifier (enum :c:type:`v4l2_quantization`) to 1754f38fcaSMauro Carvalho Chehabspecify non-standard quantization methods. Most of the time only the 1854f38fcaSMauro Carvalho Chehabcolorspace field of struct :c:type:`v4l2_pix_format` 1954f38fcaSMauro Carvalho Chehabor struct :c:type:`v4l2_pix_format_mplane` 2054f38fcaSMauro Carvalho Chehabneeds to be filled in. 2154f38fcaSMauro Carvalho Chehab 2254f38fcaSMauro Carvalho Chehab.. _hsv-colorspace: 2354f38fcaSMauro Carvalho Chehab 2454f38fcaSMauro Carvalho ChehabOn :ref:`HSV formats <hsv-formats>` the *Hue* is defined as the angle on 2554f38fcaSMauro Carvalho Chehabthe cylindrical color representation. Usually this angle is measured in 2654f38fcaSMauro Carvalho Chehabdegrees, i.e. 0-360. When we map this angle value into 8 bits, there are 2754f38fcaSMauro Carvalho Chehabtwo basic ways to do it: Divide the angular value by 2 (0-179), or use the 2854f38fcaSMauro Carvalho Chehabwhole range, 0-255, dividing the angular value by 1.41. The enum 2954f38fcaSMauro Carvalho Chehab:c:type:`v4l2_hsv_encoding` specifies which encoding is used. 3054f38fcaSMauro Carvalho Chehab 3154f38fcaSMauro Carvalho Chehab.. note:: The default R'G'B' quantization is full range for all 32b305dfe2SHans Verkuil colorspaces. HSV formats are always full range. 3354f38fcaSMauro Carvalho Chehab 3454f38fcaSMauro Carvalho Chehab.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| 3554f38fcaSMauro Carvalho Chehab 3654f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_colorspace 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho Chehab.. flat-table:: V4L2 Colorspaces 3954f38fcaSMauro Carvalho Chehab :header-rows: 1 4054f38fcaSMauro Carvalho Chehab :stub-columns: 0 4154f38fcaSMauro Carvalho Chehab 4254f38fcaSMauro Carvalho Chehab * - Identifier 4354f38fcaSMauro Carvalho Chehab - Details 4454f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_DEFAULT`` 4554f38fcaSMauro Carvalho Chehab - The default colorspace. This can be used by applications to let 4654f38fcaSMauro Carvalho Chehab the driver fill in the colorspace. 4754f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_SMPTE170M`` 4854f38fcaSMauro Carvalho Chehab - See :ref:`col-smpte-170m`. 4954f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_REC709`` 5054f38fcaSMauro Carvalho Chehab - See :ref:`col-rec709`. 5154f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_SRGB`` 5254f38fcaSMauro Carvalho Chehab - See :ref:`col-srgb`. 5354f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_OPRGB`` 5454f38fcaSMauro Carvalho Chehab - See :ref:`col-oprgb`. 5554f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_BT2020`` 5654f38fcaSMauro Carvalho Chehab - See :ref:`col-bt2020`. 5754f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_DCI_P3`` 5854f38fcaSMauro Carvalho Chehab - See :ref:`col-dcip3`. 5954f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_SMPTE240M`` 6054f38fcaSMauro Carvalho Chehab - See :ref:`col-smpte-240m`. 6154f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_470_SYSTEM_M`` 6254f38fcaSMauro Carvalho Chehab - See :ref:`col-sysm`. 6354f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_470_SYSTEM_BG`` 6454f38fcaSMauro Carvalho Chehab - See :ref:`col-sysbg`. 6554f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_JPEG`` 6654f38fcaSMauro Carvalho Chehab - See :ref:`col-jpeg`. 6754f38fcaSMauro Carvalho Chehab * - ``V4L2_COLORSPACE_RAW`` 6854f38fcaSMauro Carvalho Chehab - The raw colorspace. This is used for raw image capture where the 6954f38fcaSMauro Carvalho Chehab image is minimally processed and is using the internal colorspace 7054f38fcaSMauro Carvalho Chehab of the device. The software that processes an image using this 7154f38fcaSMauro Carvalho Chehab 'colorspace' will have to know the internals of the capture 7254f38fcaSMauro Carvalho Chehab device. 7354f38fcaSMauro Carvalho Chehab 7454f38fcaSMauro Carvalho Chehab 7554f38fcaSMauro Carvalho Chehab 7654f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_xfer_func 7754f38fcaSMauro Carvalho Chehab 7854f38fcaSMauro Carvalho Chehab.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| 7954f38fcaSMauro Carvalho Chehab 8054f38fcaSMauro Carvalho Chehab.. flat-table:: V4L2 Transfer Function 8154f38fcaSMauro Carvalho Chehab :header-rows: 1 8254f38fcaSMauro Carvalho Chehab :stub-columns: 0 8354f38fcaSMauro Carvalho Chehab 8454f38fcaSMauro Carvalho Chehab * - Identifier 8554f38fcaSMauro Carvalho Chehab - Details 8654f38fcaSMauro Carvalho Chehab * - ``V4L2_XFER_FUNC_DEFAULT`` 8754f38fcaSMauro Carvalho Chehab - Use the default transfer function as defined by the colorspace. 8854f38fcaSMauro Carvalho Chehab * - ``V4L2_XFER_FUNC_709`` 8954f38fcaSMauro Carvalho Chehab - Use the Rec. 709 transfer function. 9054f38fcaSMauro Carvalho Chehab * - ``V4L2_XFER_FUNC_SRGB`` 9154f38fcaSMauro Carvalho Chehab - Use the sRGB transfer function. 9254f38fcaSMauro Carvalho Chehab * - ``V4L2_XFER_FUNC_OPRGB`` 9354f38fcaSMauro Carvalho Chehab - Use the opRGB transfer function. 9454f38fcaSMauro Carvalho Chehab * - ``V4L2_XFER_FUNC_SMPTE240M`` 9554f38fcaSMauro Carvalho Chehab - Use the SMPTE 240M transfer function. 9654f38fcaSMauro Carvalho Chehab * - ``V4L2_XFER_FUNC_NONE`` 9754f38fcaSMauro Carvalho Chehab - Do not use a transfer function (i.e. use linear RGB values). 9854f38fcaSMauro Carvalho Chehab * - ``V4L2_XFER_FUNC_DCI_P3`` 9954f38fcaSMauro Carvalho Chehab - Use the DCI-P3 transfer function. 10054f38fcaSMauro Carvalho Chehab * - ``V4L2_XFER_FUNC_SMPTE2084`` 10154f38fcaSMauro Carvalho Chehab - Use the SMPTE 2084 transfer function. See :ref:`xf-smpte-2084`. 10254f38fcaSMauro Carvalho Chehab 10354f38fcaSMauro Carvalho Chehab 10454f38fcaSMauro Carvalho Chehab 10554f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_ycbcr_encoding 10654f38fcaSMauro Carvalho Chehab 10754f38fcaSMauro Carvalho Chehab.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| 10854f38fcaSMauro Carvalho Chehab 10954f38fcaSMauro Carvalho Chehab.. flat-table:: V4L2 Y'CbCr Encodings 11054f38fcaSMauro Carvalho Chehab :header-rows: 1 11154f38fcaSMauro Carvalho Chehab :stub-columns: 0 11254f38fcaSMauro Carvalho Chehab 11354f38fcaSMauro Carvalho Chehab * - Identifier 11454f38fcaSMauro Carvalho Chehab - Details 11554f38fcaSMauro Carvalho Chehab * - ``V4L2_YCBCR_ENC_DEFAULT`` 11654f38fcaSMauro Carvalho Chehab - Use the default Y'CbCr encoding as defined by the colorspace. 11754f38fcaSMauro Carvalho Chehab * - ``V4L2_YCBCR_ENC_601`` 11854f38fcaSMauro Carvalho Chehab - Use the BT.601 Y'CbCr encoding. 11954f38fcaSMauro Carvalho Chehab * - ``V4L2_YCBCR_ENC_709`` 12054f38fcaSMauro Carvalho Chehab - Use the Rec. 709 Y'CbCr encoding. 12154f38fcaSMauro Carvalho Chehab * - ``V4L2_YCBCR_ENC_XV601`` 12254f38fcaSMauro Carvalho Chehab - Use the extended gamut xvYCC BT.601 encoding. 12354f38fcaSMauro Carvalho Chehab * - ``V4L2_YCBCR_ENC_XV709`` 12454f38fcaSMauro Carvalho Chehab - Use the extended gamut xvYCC Rec. 709 encoding. 12554f38fcaSMauro Carvalho Chehab * - ``V4L2_YCBCR_ENC_BT2020`` 12654f38fcaSMauro Carvalho Chehab - Use the default non-constant luminance BT.2020 Y'CbCr encoding. 12754f38fcaSMauro Carvalho Chehab * - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM`` 12854f38fcaSMauro Carvalho Chehab - Use the constant luminance BT.2020 Yc'CbcCrc encoding. 12954f38fcaSMauro Carvalho Chehab * - ``V4L2_YCBCR_ENC_SMPTE_240M`` 13054f38fcaSMauro Carvalho Chehab - Use the SMPTE 240M Y'CbCr encoding. 13154f38fcaSMauro Carvalho Chehab 13254f38fcaSMauro Carvalho Chehab 13354f38fcaSMauro Carvalho Chehab 13454f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_hsv_encoding 13554f38fcaSMauro Carvalho Chehab 13654f38fcaSMauro Carvalho Chehab.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| 13754f38fcaSMauro Carvalho Chehab 13854f38fcaSMauro Carvalho Chehab.. flat-table:: V4L2 HSV Encodings 13954f38fcaSMauro Carvalho Chehab :header-rows: 1 14054f38fcaSMauro Carvalho Chehab :stub-columns: 0 14154f38fcaSMauro Carvalho Chehab 14254f38fcaSMauro Carvalho Chehab * - Identifier 14354f38fcaSMauro Carvalho Chehab - Details 14454f38fcaSMauro Carvalho Chehab * - ``V4L2_HSV_ENC_180`` 14554f38fcaSMauro Carvalho Chehab - For the Hue, each LSB is two degrees. 14654f38fcaSMauro Carvalho Chehab * - ``V4L2_HSV_ENC_256`` 14754f38fcaSMauro Carvalho Chehab - For the Hue, the 360 degrees are mapped into 8 bits, i.e. each 14854f38fcaSMauro Carvalho Chehab LSB is roughly 1.41 degrees. 14954f38fcaSMauro Carvalho Chehab 15054f38fcaSMauro Carvalho Chehab 15154f38fcaSMauro Carvalho Chehab 15254f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_quantization 15354f38fcaSMauro Carvalho Chehab 15454f38fcaSMauro Carvalho Chehab.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| 15554f38fcaSMauro Carvalho Chehab 15654f38fcaSMauro Carvalho Chehab.. flat-table:: V4L2 Quantization Methods 15754f38fcaSMauro Carvalho Chehab :header-rows: 1 15854f38fcaSMauro Carvalho Chehab :stub-columns: 0 15954f38fcaSMauro Carvalho Chehab 16054f38fcaSMauro Carvalho Chehab * - Identifier 16154f38fcaSMauro Carvalho Chehab - Details 16254f38fcaSMauro Carvalho Chehab * - ``V4L2_QUANTIZATION_DEFAULT`` 16354f38fcaSMauro Carvalho Chehab - Use the default quantization encoding as defined by the 164b305dfe2SHans Verkuil colorspace. This is always full range for R'G'B' and HSV. 165b305dfe2SHans Verkuil It is usually limited range for Y'CbCr. 16654f38fcaSMauro Carvalho Chehab * - ``V4L2_QUANTIZATION_FULL_RANGE`` 16754f38fcaSMauro Carvalho Chehab - Use the full range quantization encoding. I.e. the range [0…1] is 16854f38fcaSMauro Carvalho Chehab mapped to [0…255] (with possible clipping to [1…254] to avoid the 16954f38fcaSMauro Carvalho Chehab 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to 17054f38fcaSMauro Carvalho Chehab [0…255] (with possible clipping to [1…254] to avoid the 0x00 and 17154f38fcaSMauro Carvalho Chehab 0xff values). 17254f38fcaSMauro Carvalho Chehab * - ``V4L2_QUANTIZATION_LIM_RANGE`` 17354f38fcaSMauro Carvalho Chehab - Use the limited range quantization encoding. I.e. the range [0…1] 17454f38fcaSMauro Carvalho Chehab is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to 175b305dfe2SHans Verkuil [16…240]. Limited Range cannot be used with HSV. 176