--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+****************************
+Defining Colorspaces in V4L2
+****************************
+
+In V4L2 colorspaces are defined by four values. The first is the
+colorspace identifier (enum :c:type:`v4l2_colorspace`)
+which defines the chromaticities, the default transfer function, the
+default Y'CbCr encoding and the default quantization method. The second
+is the transfer function identifier (enum
+:c:type:`v4l2_xfer_func`) to specify non-standard
+transfer functions. The third is the Y'CbCr encoding identifier (enum
+:c:type:`v4l2_ycbcr_encoding`) to specify
+non-standard Y'CbCr encodings and the fourth is the quantization
+identifier (enum :c:type:`v4l2_quantization`) to
+specify non-standard quantization methods. Most of the time only the
+colorspace field of struct :c:type:`v4l2_pix_format`
+or struct :c:type:`v4l2_pix_format_mplane`
+needs to be filled in.
+
+.. _hsv-colorspace:
+
+On :ref:`HSV formats <hsv-formats>` the *Hue* is defined as the angle on
+the cylindrical color representation. Usually this angle is measured in
+degrees, i.e. 0-360. When we map this angle value into 8 bits, there are
+two basic ways to do it: Divide the angular value by 2 (0-179), or use the
+whole range, 0-255, dividing the angular value by 1.41. The enum
+:c:type:`v4l2_hsv_encoding` specifies which encoding is used.
+
+.. note:: The default R'G'B' quantization is full range for all
+ colorspaces except for BT.2020 which uses limited range R'G'B'
+ quantization.
+
+.. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
+
+.. c:type:: v4l2_colorspace
+
+.. flat-table:: V4L2 Colorspaces
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Details
+ * - ``V4L2_COLORSPACE_DEFAULT``
+ - The default colorspace. This can be used by applications to let
+ the driver fill in the colorspace.
+ * - ``V4L2_COLORSPACE_SMPTE170M``
+ - See :ref:`col-smpte-170m`.
+ * - ``V4L2_COLORSPACE_REC709``
+ - See :ref:`col-rec709`.
+ * - ``V4L2_COLORSPACE_SRGB``
+ - See :ref:`col-srgb`.
+ * - ``V4L2_COLORSPACE_ADOBERGB``
+ - See :ref:`col-adobergb`.
+ * - ``V4L2_COLORSPACE_BT2020``
+ - See :ref:`col-bt2020`.
+ * - ``V4L2_COLORSPACE_DCI_P3``
+ - See :ref:`col-dcip3`.
+ * - ``V4L2_COLORSPACE_SMPTE240M``
+ - See :ref:`col-smpte-240m`.
+ * - ``V4L2_COLORSPACE_470_SYSTEM_M``
+ - See :ref:`col-sysm`.
+ * - ``V4L2_COLORSPACE_470_SYSTEM_BG``
+ - See :ref:`col-sysbg`.
+ * - ``V4L2_COLORSPACE_JPEG``
+ - See :ref:`col-jpeg`.
+ * - ``V4L2_COLORSPACE_RAW``
+ - The raw colorspace. This is used for raw image capture where the
+ image is minimally processed and is using the internal colorspace
+ of the device. The software that processes an image using this
+ 'colorspace' will have to know the internals of the capture
+ device.
+
+
+
+.. c:type:: v4l2_xfer_func
+
+.. flat-table:: V4L2 Transfer Function
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Details
+ * - ``V4L2_XFER_FUNC_DEFAULT``
+ - Use the default transfer function as defined by the colorspace.
+ * - ``V4L2_XFER_FUNC_709``
+ - Use the Rec. 709 transfer function.
+ * - ``V4L2_XFER_FUNC_SRGB``
+ - Use the sRGB transfer function.
+ * - ``V4L2_XFER_FUNC_ADOBERGB``
+ - Use the AdobeRGB transfer function.
+ * - ``V4L2_XFER_FUNC_SMPTE240M``
+ - Use the SMPTE 240M transfer function.
+ * - ``V4L2_XFER_FUNC_NONE``
+ - Do not use a transfer function (i.e. use linear RGB values).
+ * - ``V4L2_XFER_FUNC_DCI_P3``
+ - Use the DCI-P3 transfer function.
+ * - ``V4L2_XFER_FUNC_SMPTE2084``
+ - Use the SMPTE 2084 transfer function.
+
+
+
+.. c:type:: v4l2_ycbcr_encoding
+
+.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
+
+.. flat-table:: V4L2 Y'CbCr Encodings
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Details
+ * - ``V4L2_YCBCR_ENC_DEFAULT``
+ - Use the default Y'CbCr encoding as defined by the colorspace.
+ * - ``V4L2_YCBCR_ENC_601``
+ - Use the BT.601 Y'CbCr encoding.
+ * - ``V4L2_YCBCR_ENC_709``
+ - Use the Rec. 709 Y'CbCr encoding.
+ * - ``V4L2_YCBCR_ENC_XV601``
+ - Use the extended gamut xvYCC BT.601 encoding.
+ * - ``V4L2_YCBCR_ENC_XV709``
+ - Use the extended gamut xvYCC Rec. 709 encoding.
+ * - ``V4L2_YCBCR_ENC_BT2020``
+ - Use the default non-constant luminance BT.2020 Y'CbCr encoding.
+ * - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM``
+ - Use the constant luminance BT.2020 Yc'CbcCrc encoding.
+ * - ``V4L2_YCBCR_ENC_SMPTE_240M``
+ - Use the SMPTE 240M Y'CbCr encoding.
+
+
+
+.. c:type:: v4l2_hsv_encoding
+
+.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
+
+.. flat-table:: V4L2 HSV Encodings
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Details
+ * - ``V4L2_HSV_ENC_180``
+ - For the Hue, each LSB is two degrees.
+ * - ``V4L2_HSV_ENC_256``
+ - For the Hue, the 360 degrees are mapped into 8 bits, i.e. each
+ LSB is roughly 1.41 degrees.
+
+
+
+.. c:type:: v4l2_quantization
+
+.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
+
+.. flat-table:: V4L2 Quantization Methods
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Details
+ * - ``V4L2_QUANTIZATION_DEFAULT``
+ - Use the default quantization encoding as defined by the
+ colorspace. This is always full range for R'G'B' (except for the
+ BT.2020 colorspace) and HSV. It is usually limited range for Y'CbCr.
+ * - ``V4L2_QUANTIZATION_FULL_RANGE``
+ - Use the full range quantization encoding. I.e. the range [0…1] is
+ mapped to [0…255] (with possible clipping to [1…254] to avoid the
+ 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to
+ [0…255] (with possible clipping to [1…254] to avoid the 0x00 and
+ 0xff values).
+ * - ``V4L2_QUANTIZATION_LIM_RANGE``
+ - Use the limited range quantization encoding. I.e. the range [0…1]
+ is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to
+ [16…240].
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+********************************
+Detailed Colorspace Descriptions
+********************************
+
+
+.. _col-smpte-170m:
+
+Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M)
+=================================================
+
+The :ref:`smpte170m` standard defines the colorspace used by NTSC and
+PAL and by SDTV in general. The default transfer function is
+``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
+range. The chromaticities of the primary colors and the white reference
+are:
+
+
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: SMPTE 170M Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - Color
+ - x
+ - y
+ * - Red
+ - 0.630
+ - 0.340
+ * - Green
+ - 0.310
+ - 0.595
+ * - Blue
+ - 0.155
+ - 0.070
+ * - White Reference (D65)
+ - 0.3127
+ - 0.3290
+
+
+The red, green and blue chromaticities are also often referred to as the
+SMPTE C set, so this colorspace is sometimes called SMPTE C as well.
+
+The transfer function defined for SMPTE 170M is the same as the one
+defined in Rec. 709.
+
+.. math::
+
+ L' = -1.099(-L)^{0.45} + 0.099 \text{, for } L \le-0.018
+
+ L' = 4.5L \text{, for } -0.018 < L < 0.018
+
+ L' = 1.099L^{0.45} - 0.099 \text{, for } L \ge 0.018
+
+Inverse Transfer function:
+
+.. math::
+
+ L = -\left( \frac{L' - 0.099}{-1.099} \right) ^{\frac{1}{0.45}} \text{, for } L' \le -0.081
+
+ L = \frac{L'}{4.5} \text{, for } -0.081 < L' < 0.081
+
+ L = \left(\frac{L' + 0.099}{1.099}\right)^{\frac{1}{0.45} } \text{, for } L' \ge 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+.. math::
+
+ Y' = 0.2990R' + 0.5870G' + 0.1140B'
+
+ Cb = -0.1687R' - 0.3313G' + 0.5B'
+
+ Cr = 0.5R' - 0.4187G' - 0.0813B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. This conversion to Y'CbCr is identical to the one defined in
+the :ref:`itu601` standard and this colorspace is sometimes called
+BT.601 as well, even though BT.601 does not mention any color primaries.
+
+The default quantization is limited range, but full range is possible
+although rarely seen.
+
+
+.. _col-rec709:
+
+Colorspace Rec. 709 (V4L2_COLORSPACE_REC709)
+============================================
+
+The :ref:`itu709` standard defines the colorspace used by HDTV in
+general. The default transfer function is ``V4L2_XFER_FUNC_709``. The
+default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr
+quantization is limited range. The chromaticities of the primary colors
+and the white reference are:
+
+
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: Rec. 709 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - Color
+ - x
+ - y
+ * - Red
+ - 0.640
+ - 0.330
+ * - Green
+ - 0.300
+ - 0.600
+ * - Blue
+ - 0.150
+ - 0.060
+ * - White Reference (D65)
+ - 0.3127
+ - 0.3290
+
+
+The full name of this standard is Rec. ITU-R BT.709-5.
+
+Transfer function. Normally L is in the range [0…1], but for the
+extended gamut xvYCC encoding values outside that range are allowed.
+
+.. math::
+
+ L' = -1.099(-L)^{0.45} + 0.099 \text{, for } L \le -0.018
+
+ L' = 4.5L \text{, for } -0.018 < L < 0.018
+
+ L' = 1.099L^{0.45} - 0.099 \text{, for } L \ge 0.018
+
+Inverse Transfer function:
+
+.. math::
+
+ L = -\left( \frac{L' - 0.099}{-1.099} \right)^\frac{1}{0.45} \text{, for } L' \le -0.081
+
+ L = \frac{L'}{4.5}\text{, for } -0.081 < L' < 0.081
+
+ L = \left(\frac{L' + 0.099}{1.099}\right)^{\frac{1}{0.45} } \text{, for } L' \ge 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_709`` encoding:
+
+.. math::
+
+ Y' = 0.2126R' + 0.7152G' + 0.0722B'
+
+ Cb = -0.1146R' - 0.3854G' + 0.5B'
+
+ Cr = 0.5R' - 0.4542G' - 0.0458B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5].
+
+The default quantization is limited range, but full range is possible
+although rarely seen.
+
+The ``V4L2_YCBCR_ENC_709`` encoding described above is the default for
+this colorspace, but it can be overridden with ``V4L2_YCBCR_ENC_601``,
+in which case the BT.601 Y'CbCr encoding is used.
+
+Two additional extended gamut Y'CbCr encodings are also possible with
+this colorspace:
+
+The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is
+similar to the Rec. 709 encoding, but it allows for R', G' and B' values
+that are outside the range [0…1]. The resulting Y', Cb and Cr values are
+scaled and offset according to the limited range formula:
+
+.. math::
+
+ Y' = \frac{219}{256} * (0.2126R' + 0.7152G' + 0.0722B') + \frac{16}{256}
+
+ Cb = \frac{224}{256} * (-0.1146R' - 0.3854G' + 0.5B')
+
+ Cr = \frac{224}{256} * (0.5R' - 0.4542G' - 0.0458B')
+
+The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is
+similar to the BT.601 encoding, but it allows for R', G' and B' values
+that are outside the range [0…1]. The resulting Y', Cb and Cr values are
+scaled and offset according to the limited range formula:
+
+.. math::
+
+ Y' = \frac{219}{256} * (0.2990R' + 0.5870G' + 0.1140B') + \frac{16}{256}
+
+ Cb = \frac{224}{256} * (-0.1687R' - 0.3313G' + 0.5B')
+
+ Cr = \frac{224}{256} * (0.5R' - 0.4187G' - 0.0813B')
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5] and quantized without further scaling or offsets.
+The non-standard xvYCC 709 or xvYCC 601 encodings can be
+used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``.
+As seen by the xvYCC formulas these encodings always use limited range quantization,
+there is no full range variant. The whole point of these extended gamut encodings
+is that values outside the limited range are still valid, although they
+map to R', G' and B' values outside the [0…1] range and are therefore outside
+the Rec. 709 colorspace gamut.
+
+
+.. _col-srgb:
+
+Colorspace sRGB (V4L2_COLORSPACE_SRGB)
+======================================
+
+The :ref:`srgb` standard defines the colorspace used by most webcams
+and computer graphics. The default transfer function is
+``V4L2_XFER_FUNC_SRGB``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited range.
+
+Note that the :ref:`sycc` standard specifies full range quantization,
+however all current capture hardware supported by the kernel convert
+R'G'B' to limited range Y'CbCr. So choosing full range as the default
+would break how applications interpret the quantization range.
+
+The chromaticities of the primary colors and the white reference are:
+
+
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: sRGB Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - Color
+ - x
+ - y
+ * - Red
+ - 0.640
+ - 0.330
+ * - Green
+ - 0.300
+ - 0.600
+ * - Blue
+ - 0.150
+ - 0.060
+ * - White Reference (D65)
+ - 0.3127
+ - 0.3290
+
+
+These chromaticities are identical to the Rec. 709 colorspace.
+
+Transfer function. Note that negative values for L are only used by the
+Y'CbCr conversion.
+
+.. math::
+
+ L' = -1.055(-L)^{\frac{1}{2.4} } + 0.055\text{, for }L < -0.0031308
+
+ L' = 12.92L\text{, for }-0.0031308 \le L \le 0.0031308
+
+ L' = 1.055L ^{\frac{1}{2.4} } - 0.055\text{, for }0.0031308 < L \le 1
+
+Inverse Transfer function:
+
+.. math::
+
+ L = -((-L' + 0.055) / 1.055) ^{2.4}\text{, for }L' < -0.04045
+
+ L = L' / 12.92\text{, for }-0.04045 \le L' \le 0.04045
+
+ L = ((L' + 0.055) / 1.055) ^{2.4}\text{, for }L' > 0.04045
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding as defined by :ref:`sycc`:
+
+.. math::
+
+ Y' = 0.2990R' + 0.5870G' + 0.1140B'
+
+ Cb = -0.1687R' - 0.3313G' + 0.5B'
+
+ Cr = 0.5R' - 0.4187G' - 0.0813B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. This transform is identical to one defined in SMPTE
+170M/BT.601. The Y'CbCr quantization is limited range.
+
+
+.. _col-adobergb:
+
+Colorspace Adobe RGB (V4L2_COLORSPACE_ADOBERGB)
+===============================================
+
+The :ref:`adobergb` standard defines the colorspace used by computer
+graphics that use the AdobeRGB colorspace. This is also known as the
+:ref:`oprgb` standard. The default transfer function is
+``V4L2_XFER_FUNC_ADOBERGB``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
+range.
+
+Note that the :ref:`oprgb` standard specifies full range quantization,
+however all current capture hardware supported by the kernel convert
+R'G'B' to limited range Y'CbCr. So choosing full range as the default
+would break how applications interpret the quantization range.
+
+The chromaticities of the primary colors and the white reference are:
+
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: Adobe RGB Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - Color
+ - x
+ - y
+ * - Red
+ - 0.6400
+ - 0.3300
+ * - Green
+ - 0.2100
+ - 0.7100
+ * - Blue
+ - 0.1500
+ - 0.0600
+ * - White Reference (D65)
+ - 0.3127
+ - 0.3290
+
+
+
+Transfer function:
+
+.. math::
+
+ L' = L ^{\frac{1}{2.19921875}}
+
+Inverse Transfer function:
+
+.. math::
+
+ L = L'^{(2.19921875)}
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+.. math::
+
+ Y' = 0.2990R' + 0.5870G' + 0.1140B'
+
+ Cb = -0.1687R' - 0.3313G' + 0.5B'
+
+ Cr = 0.5R' - 0.4187G' - 0.0813B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. This transform is identical to one defined in SMPTE
+170M/BT.601. The Y'CbCr quantization is limited range.
+
+
+.. _col-bt2020:
+
+Colorspace BT.2020 (V4L2_COLORSPACE_BT2020)
+===========================================
+
+The :ref:`itu2020` standard defines the colorspace used by Ultra-high
+definition television (UHDTV). The default transfer function is
+``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_BT2020``. The default R'G'B' quantization is limited
+range (!), and so is the default Y'CbCr quantization. The chromaticities
+of the primary colors and the white reference are:
+
+
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: BT.2020 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - Color
+ - x
+ - y
+ * - Red
+ - 0.708
+ - 0.292
+ * - Green
+ - 0.170
+ - 0.797
+ * - Blue
+ - 0.131
+ - 0.046
+ * - White Reference (D65)
+ - 0.3127
+ - 0.3290
+
+
+
+Transfer function (same as Rec. 709):
+
+.. math::
+
+ L' = 4.5L\text{, for }0 \le L < 0.018
+
+ L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1
+
+Inverse Transfer function:
+
+.. math::
+
+ L = L' / 4.5\text{, for } L' < 0.081
+
+ L = \left( \frac{L' + 0.099}{1.099}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_BT2020`` encoding:
+
+.. math::
+
+ Y' = 0.2627R' + 0.6780G' + 0.0593B'
+
+ Cb = -0.1396R' - 0.3604G' + 0.5B'
+
+ Cr = 0.5R' - 0.4598G' - 0.0402B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range.
+
+There is also an alternate constant luminance R'G'B' to Yc'CbcCrc
+(``V4L2_YCBCR_ENC_BT2020_CONST_LUM``) encoding:
+
+Luma:
+
+.. math::
+ :nowrap:
+
+ \begin{align*}
+ Yc' = (0.2627R + 0.6780G + 0.0593B)'& \\
+ B' - Yc' \le 0:& \\
+ &Cbc = (B' - Yc') / 1.9404 \\
+ B' - Yc' > 0: & \\
+ &Cbc = (B' - Yc') / 1.5816 \\
+ R' - Yc' \le 0:& \\
+ &Crc = (R' - Y') / 1.7184 \\
+ R' - Yc' > 0:& \\
+ &Crc = (R' - Y') / 0.9936
+ \end{align*}
+
+Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the
+range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.
+
+
+.. _col-dcip3:
+
+Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3)
+==========================================
+
+The :ref:`smpte431` standard defines the colorspace used by cinema
+projectors that use the DCI-P3 colorspace. The default transfer function
+is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_709``. The default Y'CbCr quantization is limited range.
+
+.. note::
+
+ Note that this colorspace standard does not specify a
+ Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this
+ default Y'CbCr encoding was picked because it is the HDTV encoding.
+
+The chromaticities of the primary colors and the white reference are:
+
+
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: DCI-P3 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - Color
+ - x
+ - y
+ * - Red
+ - 0.6800
+ - 0.3200
+ * - Green
+ - 0.2650
+ - 0.6900
+ * - Blue
+ - 0.1500
+ - 0.0600
+ * - White Reference
+ - 0.3140
+ - 0.3510
+
+
+
+Transfer function:
+
+.. math::
+
+ L' = L^{\frac{1}{2.6}}
+
+Inverse Transfer function:
+
+.. math::
+
+ L = L'^{(2.6)}
+
+Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709.
+
+
+.. _col-smpte-240m:
+
+Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M)
+=================================================
+
+The :ref:`smpte240m` standard was an interim standard used during the
+early days of HDTV (1988-1998). It has been superseded by Rec. 709. The
+default transfer function is ``V4L2_XFER_FUNC_SMPTE240M``. The default
+Y'CbCr encoding is ``V4L2_YCBCR_ENC_SMPTE240M``. The default Y'CbCr
+quantization is limited range. The chromaticities of the primary colors
+and the white reference are:
+
+
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: SMPTE 240M Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - Color
+ - x
+ - y
+ * - Red
+ - 0.630
+ - 0.340
+ * - Green
+ - 0.310
+ - 0.595
+ * - Blue
+ - 0.155
+ - 0.070
+ * - White Reference (D65)
+ - 0.3127
+ - 0.3290
+
+
+These chromaticities are identical to the SMPTE 170M colorspace.
+
+Transfer function:
+
+.. math::
+
+ L' = 4L\text{, for } 0 \le L < 0.0228
+
+ L' = 1.1115L ^{0.45} - 0.1115\text{, for } 0.0228 \le L \le 1
+
+Inverse Transfer function:
+
+.. math::
+
+ L = \frac{L'}{4}\text{, for } 0 \le L' < 0.0913
+
+ L = \left( \frac{L' + 0.1115}{1.1115}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.0913
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_SMPTE240M`` encoding:
+
+.. math::
+
+ Y' = 0.2122R' + 0.7013G' + 0.0865B'
+
+ Cb = -0.1161R' - 0.3839G' + 0.5B'
+
+ Cr = 0.5R' - 0.4451G' - 0.0549B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the
+range [-0.5…0.5]. The Y'CbCr quantization is limited range.
+
+
+.. _col-sysm:
+
+Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M)
+===================================================
+
+This standard defines the colorspace used by NTSC in 1953. In practice
+this colorspace is obsolete and SMPTE 170M should be used instead. The
+default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr
+encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is
+limited range. The chromaticities of the primary colors and the white
+reference are:
+
+
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: NTSC 1953 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - Color
+ - x
+ - y
+ * - Red
+ - 0.67
+ - 0.33
+ * - Green
+ - 0.21
+ - 0.71
+ * - Blue
+ - 0.14
+ - 0.08
+ * - White Reference (C)
+ - 0.310
+ - 0.316
+
+
+.. note::
+
+ This colorspace uses Illuminant C instead of D65 as the white
+ reference. To correctly convert an image in this colorspace to another
+ that uses D65 you need to apply a chromatic adaptation algorithm such as
+ the Bradford method.
+
+The transfer function was never properly defined for NTSC 1953. The Rec.
+709 transfer function is recommended in the literature:
+
+.. math::
+
+ L' = 4.5L\text{, for } 0 \le L < 0.018
+
+ L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1
+
+Inverse Transfer function:
+
+.. math::
+
+ L = \frac{L'}{4.5} \text{, for } L' < 0.081
+
+ L = \left( \frac{L' + 0.099}{1.099}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+.. math::
+
+ Y' = 0.2990R' + 0.5870G' + 0.1140B'
+
+ Cb = -0.1687R' - 0.3313G' + 0.5B'
+
+ Cr = 0.5R' - 0.4187G' - 0.0813B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
+identical to one defined in SMPTE 170M/BT.601.
+
+
+.. _col-sysbg:
+
+Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG)
+=========================================================
+
+The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM
+in 1975. In practice this colorspace is obsolete and SMPTE 170M should
+be used instead. The default transfer function is
+``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
+range. The chromaticities of the primary colors and the white reference
+are:
+
+
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: EBU Tech. 3213 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - Color
+ - x
+ - y
+ * - Red
+ - 0.64
+ - 0.33
+ * - Green
+ - 0.29
+ - 0.60
+ * - Blue
+ - 0.15
+ - 0.06
+ * - White Reference (D65)
+ - 0.3127
+ - 0.3290
+
+
+
+The transfer function was never properly defined for this colorspace.
+The Rec. 709 transfer function is recommended in the literature:
+
+.. math::
+
+ L' = 4.5L\text{, for } 0 \le L < 0.018
+
+ L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1
+
+Inverse Transfer function:
+
+.. math::
+
+ L = \frac{L'}{4.5} \text{, for } L' < 0.081
+
+ L = \left(\frac{L' + 0.099}{1.099} \right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+.. math::
+
+ Y' = 0.2990R' + 0.5870G' + 0.1140B'
+
+ Cb = -0.1687R' - 0.3313G' + 0.5B'
+
+ Cr = 0.5R' - 0.4187G' - 0.0813B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
+identical to one defined in SMPTE 170M/BT.601.
+
+
+.. _col-jpeg:
+
+Colorspace JPEG (V4L2_COLORSPACE_JPEG)
+======================================
+
+This colorspace defines the colorspace used by most (Motion-)JPEG
+formats. The chromaticities of the primary colors and the white
+reference are identical to sRGB. The transfer function use is
+``V4L2_XFER_FUNC_SRGB``. The Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``
+with full range quantization where Y' is scaled to [0…255] and Cb/Cr are
+scaled to [-128…128] and then clipped to [-128…127].
+
+.. note::
+
+ The JPEG standard does not actually store colorspace
+ information. So if something other than sRGB is used, then the driver
+ will have to set that information explicitly. Effectively
+ ``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for
+ ``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and
+ ``V4L2_QUANTIZATION_FULL_RANGE``.
+
+***************************************
+Detailed Transfer Function Descriptions
+***************************************
+
+.. _xf-smpte-2084:
+
+Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084)
+=======================================================
+
+The :ref:`smpte2084` standard defines the transfer function used by
+High Dynamic Range content.
+
+Constants:
+ m1 = (2610 / 4096) / 4
+
+ m2 = (2523 / 4096) * 128
+
+ c1 = 3424 / 4096
+
+ c2 = (2413 / 4096) * 32
+
+ c3 = (2392 / 4096) * 32
+
+Transfer function:
+ L' = ((c1 + c2 * L\ :sup:`m1`) / (1 + c3 * L\ :sup:`m1`))\ :sup:`m2`
+
+Inverse Transfer function:
+ L = (max(L':sup:`1/m2` - c1, 0) / (c2 - c3 *
+ L'\ :sup:`1/m2`))\ :sup:`1/m1`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-******************************
-Single-planar format structure
-******************************
-
-.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}|
-
-.. c:type:: v4l2_pix_format
-
-.. cssclass:: longtable
-
-.. flat-table:: struct v4l2_pix_format
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
- * - __u32
- - ``width``
- - Image width in pixels.
- * - __u32
- - ``height``
- - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
- ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
- refers to the number of lines in the field, otherwise it refers to
- the number of lines in the frame (which is twice the field height
- for interlaced formats).
- * - :cspan:`2` Applications set these fields to request an image
- size, drivers return the closest possible values. In case of
- planar formats the ``width`` and ``height`` applies to the largest
- plane. To avoid ambiguities drivers must return values rounded up
- to a multiple of the scale factor of any smaller planes. For
- example when the image format is YUV 4:2:0, ``width`` and
- ``height`` must be multiples of two.
- * - __u32
- - ``pixelformat``
- - The pixel format or type of compression, set by the application.
- This is a little endian
- :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
- RGB formats in :ref:`rgb-formats`, YUV formats in
- :ref:`yuv-formats`, and reserved codes in
- :ref:`reserved-formats`
- * - enum :c:type::`v4l2_field`
- - ``field``
- - Video images are typically interlaced. Applications can request to
- capture or output only the top or bottom field, or both fields
- interlaced or sequentially stored in one buffer or alternating in
- separate buffers. Drivers return the actual field order selected.
- For more details on fields see :ref:`field-order`.
- * - __u32
- - ``bytesperline``
- - Distance in bytes between the leftmost pixels in two adjacent
- lines.
- * - :cspan:`2`
-
- Both applications and drivers can set this field to request
- padding bytes at the end of each line. Drivers however may ignore
- the value requested by the application, returning ``width`` times
- bytes per pixel or a larger value required by the hardware. That
- implies applications can just set this field to zero to get a
- reasonable default.
-
- Video hardware may access padding bytes, therefore they must
- reside in accessible memory. Consider cases where padding bytes
- after the last line of an image cross a system page boundary.
- Input devices may write padding bytes, the value is undefined.
- Output devices ignore the contents of padding bytes.
-
- When the image format is planar the ``bytesperline`` value applies
- to the first plane and is divided by the same factor as the
- ``width`` field for the other planes. For example the Cb and Cr
- planes of a YUV 4:2:0 image have half as many padding bytes
- following each line as the Y plane. To avoid ambiguities drivers
- must return a ``bytesperline`` value rounded up to a multiple of
- the scale factor.
-
- For compressed formats the ``bytesperline`` value makes no sense.
- Applications and drivers must set this to 0 in that case.
- * - __u32
- - ``sizeimage``
- - Size in bytes of the buffer to hold a complete image, set by the
- driver. Usually this is ``bytesperline`` times ``height``. When
- the image consists of variable length compressed data this is the
- maximum number of bytes required to hold an image.
- * - enum :c:type:`v4l2_colorspace`
- - ``colorspace``
- - This information supplements the ``pixelformat`` and must be set
- by the driver for capture streams and by the application for
- output streams, see :ref:`colorspaces`.
- * - __u32
- - ``priv``
- - This field indicates whether the remaining fields of the
- struct :c:type:`v4l2_pix_format`, also called the
- extended fields, are valid. When set to
- ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
- have been correctly initialized. When set to any other value it
- indicates that the extended fields contain undefined values.
-
- Applications that wish to use the pixel format extended fields
- must first ensure that the feature is supported by querying the
- device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
- capability. If the capability isn't set the pixel format extended
- fields are not supported and using the extended fields will lead
- to undefined results.
-
- To use the extended fields, applications must set the ``priv``
- field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
- fields and zero the unused bytes of the
- struct :c:type:`v4l2_format` ``raw_data`` field.
-
- When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
- drivers must act as if all the extended fields were set to zero.
- On return drivers must set the ``priv`` field to
- ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
- applicable values.
- * - __u32
- - ``flags``
- - Flags set by the application or driver, see :ref:`format-flags`.
- * - enum :c:type:`v4l2_ycbcr_encoding`
- - ``ycbcr_enc``
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
- * - enum :c:type:`v4l2_hsv_encoding`
- - ``hsv_enc``
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
- * - enum :c:type:`v4l2_quantization`
- - ``quantization``
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
- * - enum :c:type:`v4l2_xfer_func`
- - ``xfer_func``
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-******************************
-Multi-planar format structures
-******************************
-
-The struct :c:type:`v4l2_plane_pix_format` structures define size
-and layout for each of the planes in a multi-planar format. The
-struct :c:type:`v4l2_pix_format_mplane` structure contains
-information common to all planes (such as image width and height) and an
-array of struct :c:type:`v4l2_plane_pix_format` structures,
-describing all planes of that format.
-
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. c:type:: v4l2_plane_pix_format
-
-.. flat-table:: struct v4l2_plane_pix_format
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
- * - __u32
- - ``sizeimage``
- - Maximum size in bytes required for image data in this plane.
- * - __u32
- - ``bytesperline``
- - Distance in bytes between the leftmost pixels in two adjacent
- lines. See struct :c:type:`v4l2_pix_format`.
- * - __u16
- - ``reserved[6]``
- - Reserved for future extensions. Should be zeroed by drivers and
- applications.
-
-
-.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.5cm}|
-
-.. c:type:: v4l2_pix_format_mplane
-
-.. flat-table:: struct v4l2_pix_format_mplane
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
- * - __u32
- - ``width``
- - Image width in pixels. See struct
- :c:type:`v4l2_pix_format`.
- * - __u32
- - ``height``
- - Image height in pixels. See struct
- :c:type:`v4l2_pix_format`.
- * - __u32
- - ``pixelformat``
- - The pixel format. Both single- and multi-planar four character
- codes can be used.
- * - enum :c:type:`v4l2_field`
- - ``field``
- - See struct :c:type:`v4l2_pix_format`.
- * - enum :c:type:`v4l2_colorspace`
- - ``colorspace``
- - See struct :c:type:`v4l2_pix_format`.
- * - struct :c:type:`v4l2_plane_pix_format`
- - ``plane_fmt[VIDEO_MAX_PLANES]``
- - An array of structures describing format of each plane this pixel
- format consists of. The number of valid entries in this array has
- to be put in the ``num_planes`` field.
- * - __u8
- - ``num_planes``
- - Number of planes (i.e. separate memory buffers) for this format
- and the number of valid entries in the ``plane_fmt`` array.
- * - __u8
- - ``flags``
- - Flags set by the application or driver, see :ref:`format-flags`.
- * - enum :c:type:`v4l2_ycbcr_encoding`
- - ``ycbcr_enc``
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
- * - enum :c:type:`v4l2_hsv_encoding`
- - ``hsv_enc``
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
- * - enum :c:type:`v4l2_quantization`
- - ``quantization``
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
- * - enum :c:type:`v4l2_xfer_func`
- - ``xfer_func``
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
- * - __u8
- - ``reserved[7]``
- - Reserved for future extensions. Should be zeroed by drivers and
- applications.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-**********************
-Standard Image Formats
-**********************
-
-In order to exchange images between drivers and applications, it is
-necessary to have standard image data formats which both sides will
-interpret the same way. V4L2 includes several such formats, and this
-section is intended to be an unambiguous specification of the standard
-image data formats in V4L2.
-
-V4L2 drivers are not limited to these formats, however. Driver-specific
-formats are possible. In that case the application may depend on a codec
-to convert images to one of the standard formats when needed. But the
-data can still be stored and retrieved in the proprietary format. For
-example, a device may support a proprietary compressed format.
-Applications can still capture and save the data in the compressed
-format, saving much disk space, and later use a codec to convert the
-images to the X Windows screen format when the video is to be displayed.
-
-Even so, ultimately, some standard formats are needed, so the V4L2
-specification would not be complete without well-defined standard
-formats.
-
-The V4L2 standard formats are mainly uncompressed formats. The pixels
-are always arranged in memory from left to right, and from top to
-bottom. The first byte of data in the image buffer is always for the
-leftmost pixel of the topmost row. Following that is the pixel
-immediately to its right, and so on until the end of the top row of
-pixels. Following the rightmost pixel of the row there may be zero or
-more bytes of padding to guarantee that each row of pixel data has a
-certain alignment. Following the pad bytes, if any, is data for the
-leftmost pixel of the second row from the top, and so on. The last row
-has just as many pad bytes after it as the other rows.
-
-In V4L2 each format has an identifier which looks like ``PIX_FMT_XXX``,
-defined in the :ref:`videodev2.h <videodev>` header file. These
-identifiers represent
-:ref:`four character (FourCC) codes <v4l2-fourcc>` which are also
-listed below, however they are not the same as those used in the Windows
-world.
-
-For some formats, data is stored in separate, discontiguous memory
-buffers. Those formats are identified by a separate set of FourCC codes
-and are referred to as "multi-planar formats". For example, a
-:ref:`YUV422 <V4L2-PIX-FMT-YUV422M>` frame is normally stored in one
-memory buffer, but it can also be placed in two or three separate
-buffers, with Y component in one buffer and CbCr components in another
-in the 2-planar version or with each component in its own buffer in the
-3-planar case. Those sub-buffers are referred to as "*planes*".
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-****************************
-Defining Colorspaces in V4L2
-****************************
-
-In V4L2 colorspaces are defined by four values. The first is the
-colorspace identifier (enum :c:type:`v4l2_colorspace`)
-which defines the chromaticities, the default transfer function, the
-default Y'CbCr encoding and the default quantization method. The second
-is the transfer function identifier (enum
-:c:type:`v4l2_xfer_func`) to specify non-standard
-transfer functions. The third is the Y'CbCr encoding identifier (enum
-:c:type:`v4l2_ycbcr_encoding`) to specify
-non-standard Y'CbCr encodings and the fourth is the quantization
-identifier (enum :c:type:`v4l2_quantization`) to
-specify non-standard quantization methods. Most of the time only the
-colorspace field of struct :c:type:`v4l2_pix_format`
-or struct :c:type:`v4l2_pix_format_mplane`
-needs to be filled in.
-
-.. _hsv-colorspace:
-
-On :ref:`HSV formats <hsv-formats>` the *Hue* is defined as the angle on
-the cylindrical color representation. Usually this angle is measured in
-degrees, i.e. 0-360. When we map this angle value into 8 bits, there are
-two basic ways to do it: Divide the angular value by 2 (0-179), or use the
-whole range, 0-255, dividing the angular value by 1.41. The enum
-:c:type:`v4l2_hsv_encoding` specifies which encoding is used.
-
-.. note:: The default R'G'B' quantization is full range for all
- colorspaces except for BT.2020 which uses limited range R'G'B'
- quantization.
-
-.. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
-
-.. c:type:: v4l2_colorspace
-
-.. flat-table:: V4L2 Colorspaces
- :header-rows: 1
- :stub-columns: 0
-
- * - Identifier
- - Details
- * - ``V4L2_COLORSPACE_DEFAULT``
- - The default colorspace. This can be used by applications to let
- the driver fill in the colorspace.
- * - ``V4L2_COLORSPACE_SMPTE170M``
- - See :ref:`col-smpte-170m`.
- * - ``V4L2_COLORSPACE_REC709``
- - See :ref:`col-rec709`.
- * - ``V4L2_COLORSPACE_SRGB``
- - See :ref:`col-srgb`.
- * - ``V4L2_COLORSPACE_ADOBERGB``
- - See :ref:`col-adobergb`.
- * - ``V4L2_COLORSPACE_BT2020``
- - See :ref:`col-bt2020`.
- * - ``V4L2_COLORSPACE_DCI_P3``
- - See :ref:`col-dcip3`.
- * - ``V4L2_COLORSPACE_SMPTE240M``
- - See :ref:`col-smpte-240m`.
- * - ``V4L2_COLORSPACE_470_SYSTEM_M``
- - See :ref:`col-sysm`.
- * - ``V4L2_COLORSPACE_470_SYSTEM_BG``
- - See :ref:`col-sysbg`.
- * - ``V4L2_COLORSPACE_JPEG``
- - See :ref:`col-jpeg`.
- * - ``V4L2_COLORSPACE_RAW``
- - The raw colorspace. This is used for raw image capture where the
- image is minimally processed and is using the internal colorspace
- of the device. The software that processes an image using this
- 'colorspace' will have to know the internals of the capture
- device.
-
-
-
-.. c:type:: v4l2_xfer_func
-
-.. flat-table:: V4L2 Transfer Function
- :header-rows: 1
- :stub-columns: 0
-
- * - Identifier
- - Details
- * - ``V4L2_XFER_FUNC_DEFAULT``
- - Use the default transfer function as defined by the colorspace.
- * - ``V4L2_XFER_FUNC_709``
- - Use the Rec. 709 transfer function.
- * - ``V4L2_XFER_FUNC_SRGB``
- - Use the sRGB transfer function.
- * - ``V4L2_XFER_FUNC_ADOBERGB``
- - Use the AdobeRGB transfer function.
- * - ``V4L2_XFER_FUNC_SMPTE240M``
- - Use the SMPTE 240M transfer function.
- * - ``V4L2_XFER_FUNC_NONE``
- - Do not use a transfer function (i.e. use linear RGB values).
- * - ``V4L2_XFER_FUNC_DCI_P3``
- - Use the DCI-P3 transfer function.
- * - ``V4L2_XFER_FUNC_SMPTE2084``
- - Use the SMPTE 2084 transfer function.
-
-
-
-.. c:type:: v4l2_ycbcr_encoding
-
-.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
-
-.. flat-table:: V4L2 Y'CbCr Encodings
- :header-rows: 1
- :stub-columns: 0
-
- * - Identifier
- - Details
- * - ``V4L2_YCBCR_ENC_DEFAULT``
- - Use the default Y'CbCr encoding as defined by the colorspace.
- * - ``V4L2_YCBCR_ENC_601``
- - Use the BT.601 Y'CbCr encoding.
- * - ``V4L2_YCBCR_ENC_709``
- - Use the Rec. 709 Y'CbCr encoding.
- * - ``V4L2_YCBCR_ENC_XV601``
- - Use the extended gamut xvYCC BT.601 encoding.
- * - ``V4L2_YCBCR_ENC_XV709``
- - Use the extended gamut xvYCC Rec. 709 encoding.
- * - ``V4L2_YCBCR_ENC_BT2020``
- - Use the default non-constant luminance BT.2020 Y'CbCr encoding.
- * - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM``
- - Use the constant luminance BT.2020 Yc'CbcCrc encoding.
- * - ``V4L2_YCBCR_ENC_SMPTE_240M``
- - Use the SMPTE 240M Y'CbCr encoding.
-
-
-
-.. c:type:: v4l2_hsv_encoding
-
-.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
-
-.. flat-table:: V4L2 HSV Encodings
- :header-rows: 1
- :stub-columns: 0
-
- * - Identifier
- - Details
- * - ``V4L2_HSV_ENC_180``
- - For the Hue, each LSB is two degrees.
- * - ``V4L2_HSV_ENC_256``
- - For the Hue, the 360 degrees are mapped into 8 bits, i.e. each
- LSB is roughly 1.41 degrees.
-
-
-
-.. c:type:: v4l2_quantization
-
-.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
-
-.. flat-table:: V4L2 Quantization Methods
- :header-rows: 1
- :stub-columns: 0
-
- * - Identifier
- - Details
- * - ``V4L2_QUANTIZATION_DEFAULT``
- - Use the default quantization encoding as defined by the
- colorspace. This is always full range for R'G'B' (except for the
- BT.2020 colorspace) and HSV. It is usually limited range for Y'CbCr.
- * - ``V4L2_QUANTIZATION_FULL_RANGE``
- - Use the full range quantization encoding. I.e. the range [0…1] is
- mapped to [0…255] (with possible clipping to [1…254] to avoid the
- 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to
- [0…255] (with possible clipping to [1…254] to avoid the 0x00 and
- 0xff values).
- * - ``V4L2_QUANTIZATION_LIM_RANGE``
- - Use the limited range quantization encoding. I.e. the range [0…1]
- is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to
- [16…240].
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-********************************
-Detailed Colorspace Descriptions
-********************************
-
-
-.. _col-smpte-170m:
-
-Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M)
-=================================================
-
-The :ref:`smpte170m` standard defines the colorspace used by NTSC and
-PAL and by SDTV in general. The default transfer function is
-``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
-range. The chromaticities of the primary colors and the white reference
-are:
-
-
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: SMPTE 170M Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
- * - Color
- - x
- - y
- * - Red
- - 0.630
- - 0.340
- * - Green
- - 0.310
- - 0.595
- * - Blue
- - 0.155
- - 0.070
- * - White Reference (D65)
- - 0.3127
- - 0.3290
-
-
-The red, green and blue chromaticities are also often referred to as the
-SMPTE C set, so this colorspace is sometimes called SMPTE C as well.
-
-The transfer function defined for SMPTE 170M is the same as the one
-defined in Rec. 709.
-
-.. math::
-
- L' = -1.099(-L)^{0.45} + 0.099 \text{, for } L \le-0.018
-
- L' = 4.5L \text{, for } -0.018 < L < 0.018
-
- L' = 1.099L^{0.45} - 0.099 \text{, for } L \ge 0.018
-
-Inverse Transfer function:
-
-.. math::
-
- L = -\left( \frac{L' - 0.099}{-1.099} \right) ^{\frac{1}{0.45}} \text{, for } L' \le -0.081
-
- L = \frac{L'}{4.5} \text{, for } -0.081 < L' < 0.081
-
- L = \left(\frac{L' + 0.099}{1.099}\right)^{\frac{1}{0.45} } \text{, for } L' \ge 0.081
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_601`` encoding:
-
-.. math::
-
- Y' = 0.2990R' + 0.5870G' + 0.1140B'
-
- Cb = -0.1687R' - 0.3313G' + 0.5B'
-
- Cr = 0.5R' - 0.4187G' - 0.0813B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. This conversion to Y'CbCr is identical to the one defined in
-the :ref:`itu601` standard and this colorspace is sometimes called
-BT.601 as well, even though BT.601 does not mention any color primaries.
-
-The default quantization is limited range, but full range is possible
-although rarely seen.
-
-
-.. _col-rec709:
-
-Colorspace Rec. 709 (V4L2_COLORSPACE_REC709)
-============================================
-
-The :ref:`itu709` standard defines the colorspace used by HDTV in
-general. The default transfer function is ``V4L2_XFER_FUNC_709``. The
-default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr
-quantization is limited range. The chromaticities of the primary colors
-and the white reference are:
-
-
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: Rec. 709 Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
- * - Color
- - x
- - y
- * - Red
- - 0.640
- - 0.330
- * - Green
- - 0.300
- - 0.600
- * - Blue
- - 0.150
- - 0.060
- * - White Reference (D65)
- - 0.3127
- - 0.3290
-
-
-The full name of this standard is Rec. ITU-R BT.709-5.
-
-Transfer function. Normally L is in the range [0…1], but for the
-extended gamut xvYCC encoding values outside that range are allowed.
-
-.. math::
-
- L' = -1.099(-L)^{0.45} + 0.099 \text{, for } L \le -0.018
-
- L' = 4.5L \text{, for } -0.018 < L < 0.018
-
- L' = 1.099L^{0.45} - 0.099 \text{, for } L \ge 0.018
-
-Inverse Transfer function:
-
-.. math::
-
- L = -\left( \frac{L' - 0.099}{-1.099} \right)^\frac{1}{0.45} \text{, for } L' \le -0.081
-
- L = \frac{L'}{4.5}\text{, for } -0.081 < L' < 0.081
-
- L = \left(\frac{L' + 0.099}{1.099}\right)^{\frac{1}{0.45} } \text{, for } L' \ge 0.081
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_709`` encoding:
-
-.. math::
-
- Y' = 0.2126R' + 0.7152G' + 0.0722B'
-
- Cb = -0.1146R' - 0.3854G' + 0.5B'
-
- Cr = 0.5R' - 0.4542G' - 0.0458B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5].
-
-The default quantization is limited range, but full range is possible
-although rarely seen.
-
-The ``V4L2_YCBCR_ENC_709`` encoding described above is the default for
-this colorspace, but it can be overridden with ``V4L2_YCBCR_ENC_601``,
-in which case the BT.601 Y'CbCr encoding is used.
-
-Two additional extended gamut Y'CbCr encodings are also possible with
-this colorspace:
-
-The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is
-similar to the Rec. 709 encoding, but it allows for R', G' and B' values
-that are outside the range [0…1]. The resulting Y', Cb and Cr values are
-scaled and offset according to the limited range formula:
-
-.. math::
-
- Y' = \frac{219}{256} * (0.2126R' + 0.7152G' + 0.0722B') + \frac{16}{256}
-
- Cb = \frac{224}{256} * (-0.1146R' - 0.3854G' + 0.5B')
-
- Cr = \frac{224}{256} * (0.5R' - 0.4542G' - 0.0458B')
-
-The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is
-similar to the BT.601 encoding, but it allows for R', G' and B' values
-that are outside the range [0…1]. The resulting Y', Cb and Cr values are
-scaled and offset according to the limited range formula:
-
-.. math::
-
- Y' = \frac{219}{256} * (0.2990R' + 0.5870G' + 0.1140B') + \frac{16}{256}
-
- Cb = \frac{224}{256} * (-0.1687R' - 0.3313G' + 0.5B')
-
- Cr = \frac{224}{256} * (0.5R' - 0.4187G' - 0.0813B')
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5] and quantized without further scaling or offsets.
-The non-standard xvYCC 709 or xvYCC 601 encodings can be
-used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``.
-As seen by the xvYCC formulas these encodings always use limited range quantization,
-there is no full range variant. The whole point of these extended gamut encodings
-is that values outside the limited range are still valid, although they
-map to R', G' and B' values outside the [0…1] range and are therefore outside
-the Rec. 709 colorspace gamut.
-
-
-.. _col-srgb:
-
-Colorspace sRGB (V4L2_COLORSPACE_SRGB)
-======================================
-
-The :ref:`srgb` standard defines the colorspace used by most webcams
-and computer graphics. The default transfer function is
-``V4L2_XFER_FUNC_SRGB``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited range.
-
-Note that the :ref:`sycc` standard specifies full range quantization,
-however all current capture hardware supported by the kernel convert
-R'G'B' to limited range Y'CbCr. So choosing full range as the default
-would break how applications interpret the quantization range.
-
-The chromaticities of the primary colors and the white reference are:
-
-
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: sRGB Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
- * - Color
- - x
- - y
- * - Red
- - 0.640
- - 0.330
- * - Green
- - 0.300
- - 0.600
- * - Blue
- - 0.150
- - 0.060
- * - White Reference (D65)
- - 0.3127
- - 0.3290
-
-
-These chromaticities are identical to the Rec. 709 colorspace.
-
-Transfer function. Note that negative values for L are only used by the
-Y'CbCr conversion.
-
-.. math::
-
- L' = -1.055(-L)^{\frac{1}{2.4} } + 0.055\text{, for }L < -0.0031308
-
- L' = 12.92L\text{, for }-0.0031308 \le L \le 0.0031308
-
- L' = 1.055L ^{\frac{1}{2.4} } - 0.055\text{, for }0.0031308 < L \le 1
-
-Inverse Transfer function:
-
-.. math::
-
- L = -((-L' + 0.055) / 1.055) ^{2.4}\text{, for }L' < -0.04045
-
- L = L' / 12.92\text{, for }-0.04045 \le L' \le 0.04045
-
- L = ((L' + 0.055) / 1.055) ^{2.4}\text{, for }L' > 0.04045
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_601`` encoding as defined by :ref:`sycc`:
-
-.. math::
-
- Y' = 0.2990R' + 0.5870G' + 0.1140B'
-
- Cb = -0.1687R' - 0.3313G' + 0.5B'
-
- Cr = 0.5R' - 0.4187G' - 0.0813B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. This transform is identical to one defined in SMPTE
-170M/BT.601. The Y'CbCr quantization is limited range.
-
-
-.. _col-adobergb:
-
-Colorspace Adobe RGB (V4L2_COLORSPACE_ADOBERGB)
-===============================================
-
-The :ref:`adobergb` standard defines the colorspace used by computer
-graphics that use the AdobeRGB colorspace. This is also known as the
-:ref:`oprgb` standard. The default transfer function is
-``V4L2_XFER_FUNC_ADOBERGB``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
-range.
-
-Note that the :ref:`oprgb` standard specifies full range quantization,
-however all current capture hardware supported by the kernel convert
-R'G'B' to limited range Y'CbCr. So choosing full range as the default
-would break how applications interpret the quantization range.
-
-The chromaticities of the primary colors and the white reference are:
-
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: Adobe RGB Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
- * - Color
- - x
- - y
- * - Red
- - 0.6400
- - 0.3300
- * - Green
- - 0.2100
- - 0.7100
- * - Blue
- - 0.1500
- - 0.0600
- * - White Reference (D65)
- - 0.3127
- - 0.3290
-
-
-
-Transfer function:
-
-.. math::
-
- L' = L ^{\frac{1}{2.19921875}}
-
-Inverse Transfer function:
-
-.. math::
-
- L = L'^{(2.19921875)}
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_601`` encoding:
-
-.. math::
-
- Y' = 0.2990R' + 0.5870G' + 0.1140B'
-
- Cb = -0.1687R' - 0.3313G' + 0.5B'
-
- Cr = 0.5R' - 0.4187G' - 0.0813B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. This transform is identical to one defined in SMPTE
-170M/BT.601. The Y'CbCr quantization is limited range.
-
-
-.. _col-bt2020:
-
-Colorspace BT.2020 (V4L2_COLORSPACE_BT2020)
-===========================================
-
-The :ref:`itu2020` standard defines the colorspace used by Ultra-high
-definition television (UHDTV). The default transfer function is
-``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_BT2020``. The default R'G'B' quantization is limited
-range (!), and so is the default Y'CbCr quantization. The chromaticities
-of the primary colors and the white reference are:
-
-
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: BT.2020 Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
- * - Color
- - x
- - y
- * - Red
- - 0.708
- - 0.292
- * - Green
- - 0.170
- - 0.797
- * - Blue
- - 0.131
- - 0.046
- * - White Reference (D65)
- - 0.3127
- - 0.3290
-
-
-
-Transfer function (same as Rec. 709):
-
-.. math::
-
- L' = 4.5L\text{, for }0 \le L < 0.018
-
- L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1
-
-Inverse Transfer function:
-
-.. math::
-
- L = L' / 4.5\text{, for } L' < 0.081
-
- L = \left( \frac{L' + 0.099}{1.099}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_BT2020`` encoding:
-
-.. math::
-
- Y' = 0.2627R' + 0.6780G' + 0.0593B'
-
- Cb = -0.1396R' - 0.3604G' + 0.5B'
-
- Cr = 0.5R' - 0.4598G' - 0.0402B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. The Y'CbCr quantization is limited range.
-
-There is also an alternate constant luminance R'G'B' to Yc'CbcCrc
-(``V4L2_YCBCR_ENC_BT2020_CONST_LUM``) encoding:
-
-Luma:
-
-.. math::
- :nowrap:
-
- \begin{align*}
- Yc' = (0.2627R + 0.6780G + 0.0593B)'& \\
- B' - Yc' \le 0:& \\
- &Cbc = (B' - Yc') / 1.9404 \\
- B' - Yc' > 0: & \\
- &Cbc = (B' - Yc') / 1.5816 \\
- R' - Yc' \le 0:& \\
- &Crc = (R' - Y') / 1.7184 \\
- R' - Yc' > 0:& \\
- &Crc = (R' - Y') / 0.9936
- \end{align*}
-
-Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the
-range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.
-
-
-.. _col-dcip3:
-
-Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3)
-==========================================
-
-The :ref:`smpte431` standard defines the colorspace used by cinema
-projectors that use the DCI-P3 colorspace. The default transfer function
-is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_709``. The default Y'CbCr quantization is limited range.
-
-.. note::
-
- Note that this colorspace standard does not specify a
- Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this
- default Y'CbCr encoding was picked because it is the HDTV encoding.
-
-The chromaticities of the primary colors and the white reference are:
-
-
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: DCI-P3 Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
- * - Color
- - x
- - y
- * - Red
- - 0.6800
- - 0.3200
- * - Green
- - 0.2650
- - 0.6900
- * - Blue
- - 0.1500
- - 0.0600
- * - White Reference
- - 0.3140
- - 0.3510
-
-
-
-Transfer function:
-
-.. math::
-
- L' = L^{\frac{1}{2.6}}
-
-Inverse Transfer function:
-
-.. math::
-
- L = L'^{(2.6)}
-
-Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709.
-
-
-.. _col-smpte-240m:
-
-Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M)
-=================================================
-
-The :ref:`smpte240m` standard was an interim standard used during the
-early days of HDTV (1988-1998). It has been superseded by Rec. 709. The
-default transfer function is ``V4L2_XFER_FUNC_SMPTE240M``. The default
-Y'CbCr encoding is ``V4L2_YCBCR_ENC_SMPTE240M``. The default Y'CbCr
-quantization is limited range. The chromaticities of the primary colors
-and the white reference are:
-
-
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: SMPTE 240M Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
- * - Color
- - x
- - y
- * - Red
- - 0.630
- - 0.340
- * - Green
- - 0.310
- - 0.595
- * - Blue
- - 0.155
- - 0.070
- * - White Reference (D65)
- - 0.3127
- - 0.3290
-
-
-These chromaticities are identical to the SMPTE 170M colorspace.
-
-Transfer function:
-
-.. math::
-
- L' = 4L\text{, for } 0 \le L < 0.0228
-
- L' = 1.1115L ^{0.45} - 0.1115\text{, for } 0.0228 \le L \le 1
-
-Inverse Transfer function:
-
-.. math::
-
- L = \frac{L'}{4}\text{, for } 0 \le L' < 0.0913
-
- L = \left( \frac{L' + 0.1115}{1.1115}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.0913
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_SMPTE240M`` encoding:
-
-.. math::
-
- Y' = 0.2122R' + 0.7013G' + 0.0865B'
-
- Cb = -0.1161R' - 0.3839G' + 0.5B'
-
- Cr = 0.5R' - 0.4451G' - 0.0549B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the
-range [-0.5…0.5]. The Y'CbCr quantization is limited range.
-
-
-.. _col-sysm:
-
-Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M)
-===================================================
-
-This standard defines the colorspace used by NTSC in 1953. In practice
-this colorspace is obsolete and SMPTE 170M should be used instead. The
-default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr
-encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is
-limited range. The chromaticities of the primary colors and the white
-reference are:
-
-
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: NTSC 1953 Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
- * - Color
- - x
- - y
- * - Red
- - 0.67
- - 0.33
- * - Green
- - 0.21
- - 0.71
- * - Blue
- - 0.14
- - 0.08
- * - White Reference (C)
- - 0.310
- - 0.316
-
-
-.. note::
-
- This colorspace uses Illuminant C instead of D65 as the white
- reference. To correctly convert an image in this colorspace to another
- that uses D65 you need to apply a chromatic adaptation algorithm such as
- the Bradford method.
-
-The transfer function was never properly defined for NTSC 1953. The Rec.
-709 transfer function is recommended in the literature:
-
-.. math::
-
- L' = 4.5L\text{, for } 0 \le L < 0.018
-
- L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1
-
-Inverse Transfer function:
-
-.. math::
-
- L = \frac{L'}{4.5} \text{, for } L' < 0.081
-
- L = \left( \frac{L' + 0.099}{1.099}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_601`` encoding:
-
-.. math::
-
- Y' = 0.2990R' + 0.5870G' + 0.1140B'
-
- Cb = -0.1687R' - 0.3313G' + 0.5B'
-
- Cr = 0.5R' - 0.4187G' - 0.0813B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
-identical to one defined in SMPTE 170M/BT.601.
-
-
-.. _col-sysbg:
-
-Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG)
-=========================================================
-
-The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM
-in 1975. In practice this colorspace is obsolete and SMPTE 170M should
-be used instead. The default transfer function is
-``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
-range. The chromaticities of the primary colors and the white reference
-are:
-
-
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: EBU Tech. 3213 Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
- * - Color
- - x
- - y
- * - Red
- - 0.64
- - 0.33
- * - Green
- - 0.29
- - 0.60
- * - Blue
- - 0.15
- - 0.06
- * - White Reference (D65)
- - 0.3127
- - 0.3290
-
-
-
-The transfer function was never properly defined for this colorspace.
-The Rec. 709 transfer function is recommended in the literature:
-
-.. math::
-
- L' = 4.5L\text{, for } 0 \le L < 0.018
-
- L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1
-
-Inverse Transfer function:
-
-.. math::
-
- L = \frac{L'}{4.5} \text{, for } L' < 0.081
-
- L = \left(\frac{L' + 0.099}{1.099} \right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_601`` encoding:
-
-.. math::
-
- Y' = 0.2990R' + 0.5870G' + 0.1140B'
-
- Cb = -0.1687R' - 0.3313G' + 0.5B'
-
- Cr = 0.5R' - 0.4187G' - 0.0813B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
-identical to one defined in SMPTE 170M/BT.601.
-
-
-.. _col-jpeg:
-
-Colorspace JPEG (V4L2_COLORSPACE_JPEG)
-======================================
-
-This colorspace defines the colorspace used by most (Motion-)JPEG
-formats. The chromaticities of the primary colors and the white
-reference are identical to sRGB. The transfer function use is
-``V4L2_XFER_FUNC_SRGB``. The Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``
-with full range quantization where Y' is scaled to [0…255] and Cb/Cr are
-scaled to [-128…128] and then clipped to [-128…127].
-
-.. note::
-
- The JPEG standard does not actually store colorspace
- information. So if something other than sRGB is used, then the driver
- will have to set that information explicitly. Effectively
- ``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for
- ``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and
- ``V4L2_QUANTIZATION_FULL_RANGE``.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-***************************************
-Detailed Transfer Function Descriptions
-***************************************
-
-
-.. _xf-smpte-2084:
-
-Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084)
-=======================================================
-
-The :ref:`smpte2084` standard defines the transfer function used by
-High Dynamic Range content.
-
-Constants:
- m1 = (2610 / 4096) / 4
-
- m2 = (2523 / 4096) * 128
-
- c1 = 3424 / 4096
-
- c2 = (2413 / 4096) * 32
-
- c3 = (2392 / 4096) * 32
-
-Transfer function:
- L' = ((c1 + c2 * L\ :sup:`m1`) / (1 + c3 * L\ :sup:`m1`))\ :sup:`m2`
-
-Inverse Transfer function:
- L = (max(L':sup:`1/m2` - c1, 0) / (c2 - c3 *
- L'\ :sup:`1/m2`))\ :sup:`1/m1`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-******************
-Compressed Formats
-******************
-
-
-.. _compressed-formats:
-
-.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
-
-.. flat-table:: Compressed Image Formats
- :header-rows: 1
- :stub-columns: 0
- :widths: 3 1 4
-
- * - Identifier
- - Code
- - Details
- * .. _V4L2-PIX-FMT-JPEG:
-
- - ``V4L2_PIX_FMT_JPEG``
- - 'JPEG'
- - TBD. See also :ref:`VIDIOC_G_JPEGCOMP <VIDIOC_G_JPEGCOMP>`,
- :ref:`VIDIOC_S_JPEGCOMP <VIDIOC_G_JPEGCOMP>`.
- * .. _V4L2-PIX-FMT-MPEG:
-
- - ``V4L2_PIX_FMT_MPEG``
- - 'MPEG'
- - MPEG multiplexed stream. The actual format is determined by
- extended control ``V4L2_CID_MPEG_STREAM_TYPE``, see
- :ref:`mpeg-control-id`.
- * .. _V4L2-PIX-FMT-H264:
-
- - ``V4L2_PIX_FMT_H264``
- - 'H264'
- - H264 video elementary stream with start codes.
- * .. _V4L2-PIX-FMT-H264-NO-SC:
-
- - ``V4L2_PIX_FMT_H264_NO_SC``
- - 'AVC1'
- - H264 video elementary stream without start codes.
- * .. _V4L2-PIX-FMT-H264-MVC:
-
- - ``V4L2_PIX_FMT_H264_MVC``
- - 'M264'
- - H264 MVC video elementary stream.
- * .. _V4L2-PIX-FMT-H263:
-
- - ``V4L2_PIX_FMT_H263``
- - 'H263'
- - H263 video elementary stream.
- * .. _V4L2-PIX-FMT-MPEG1:
-
- - ``V4L2_PIX_FMT_MPEG1``
- - 'MPG1'
- - MPEG1 video elementary stream.
- * .. _V4L2-PIX-FMT-MPEG2:
-
- - ``V4L2_PIX_FMT_MPEG2``
- - 'MPG2'
- - MPEG2 video elementary stream.
- * .. _V4L2-PIX-FMT-MPEG4:
-
- - ``V4L2_PIX_FMT_MPEG4``
- - 'MPG4'
- - MPEG4 video elementary stream.
- * .. _V4L2-PIX-FMT-XVID:
-
- - ``V4L2_PIX_FMT_XVID``
- - 'XVID'
- - Xvid video elementary stream.
- * .. _V4L2-PIX-FMT-VC1-ANNEX-G:
-
- - ``V4L2_PIX_FMT_VC1_ANNEX_G``
- - 'VC1G'
- - VC1, SMPTE 421M Annex G compliant stream.
- * .. _V4L2-PIX-FMT-VC1-ANNEX-L:
-
- - ``V4L2_PIX_FMT_VC1_ANNEX_L``
- - 'VC1L'
- - VC1, SMPTE 421M Annex L compliant stream.
- * .. _V4L2-PIX-FMT-VP8:
-
- - ``V4L2_PIX_FMT_VP8``
- - 'VP80'
- - VP8 video elementary stream.
- * .. _V4L2-PIX-FMT-VP9:
-
- - ``V4L2_PIX_FMT_VP9``
- - 'VP90'
- - VP9 video elementary stream.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+******************
+Compressed Formats
+******************
+
+
+.. _compressed-formats:
+
+.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
+
+.. flat-table:: Compressed Image Formats
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+ * - Identifier
+ - Code
+ - Details
+ * .. _V4L2-PIX-FMT-JPEG:
+
+ - ``V4L2_PIX_FMT_JPEG``
+ - 'JPEG'
+ - TBD. See also :ref:`VIDIOC_G_JPEGCOMP <VIDIOC_G_JPEGCOMP>`,
+ :ref:`VIDIOC_S_JPEGCOMP <VIDIOC_G_JPEGCOMP>`.
+ * .. _V4L2-PIX-FMT-MPEG:
+
+ - ``V4L2_PIX_FMT_MPEG``
+ - 'MPEG'
+ - MPEG multiplexed stream. The actual format is determined by
+ extended control ``V4L2_CID_MPEG_STREAM_TYPE``, see
+ :ref:`mpeg-control-id`.
+ * .. _V4L2-PIX-FMT-H264:
+
+ - ``V4L2_PIX_FMT_H264``
+ - 'H264'
+ - H264 video elementary stream with start codes.
+ * .. _V4L2-PIX-FMT-H264-NO-SC:
+
+ - ``V4L2_PIX_FMT_H264_NO_SC``
+ - 'AVC1'
+ - H264 video elementary stream without start codes.
+ * .. _V4L2-PIX-FMT-H264-MVC:
+
+ - ``V4L2_PIX_FMT_H264_MVC``
+ - 'M264'
+ - H264 MVC video elementary stream.
+ * .. _V4L2-PIX-FMT-H263:
+
+ - ``V4L2_PIX_FMT_H263``
+ - 'H263'
+ - H263 video elementary stream.
+ * .. _V4L2-PIX-FMT-MPEG1:
+
+ - ``V4L2_PIX_FMT_MPEG1``
+ - 'MPG1'
+ - MPEG1 video elementary stream.
+ * .. _V4L2-PIX-FMT-MPEG2:
+
+ - ``V4L2_PIX_FMT_MPEG2``
+ - 'MPG2'
+ - MPEG2 video elementary stream.
+ * .. _V4L2-PIX-FMT-MPEG4:
+
+ - ``V4L2_PIX_FMT_MPEG4``
+ - 'MPG4'
+ - MPEG4 video elementary stream.
+ * .. _V4L2-PIX-FMT-XVID:
+
+ - ``V4L2_PIX_FMT_XVID``
+ - 'XVID'
+ - Xvid video elementary stream.
+ * .. _V4L2-PIX-FMT-VC1-ANNEX-G:
+
+ - ``V4L2_PIX_FMT_VC1_ANNEX_G``
+ - 'VC1G'
+ - VC1, SMPTE 421M Annex G compliant stream.
+ * .. _V4L2-PIX-FMT-VC1-ANNEX-L:
+
+ - ``V4L2_PIX_FMT_VC1_ANNEX_L``
+ - 'VC1L'
+ - VC1, SMPTE 421M Annex L compliant stream.
+ * .. _V4L2-PIX-FMT-VP8:
+
+ - ``V4L2_PIX_FMT_VP8``
+ - 'VP80'
+ - VP8 video elementary stream.
+ * .. _V4L2-PIX-FMT-VP9:
+
+ - ``V4L2_PIX_FMT_VP9``
+ - 'VP90'
+ - VP9 video elementary stream.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+**********************
+Standard Image Formats
+**********************
+
+In order to exchange images between drivers and applications, it is
+necessary to have standard image data formats which both sides will
+interpret the same way. V4L2 includes several such formats, and this
+section is intended to be an unambiguous specification of the standard
+image data formats in V4L2.
+
+V4L2 drivers are not limited to these formats, however. Driver-specific
+formats are possible. In that case the application may depend on a codec
+to convert images to one of the standard formats when needed. But the
+data can still be stored and retrieved in the proprietary format. For
+example, a device may support a proprietary compressed format.
+Applications can still capture and save the data in the compressed
+format, saving much disk space, and later use a codec to convert the
+images to the X Windows screen format when the video is to be displayed.
+
+Even so, ultimately, some standard formats are needed, so the V4L2
+specification would not be complete without well-defined standard
+formats.
+
+The V4L2 standard formats are mainly uncompressed formats. The pixels
+are always arranged in memory from left to right, and from top to
+bottom. The first byte of data in the image buffer is always for the
+leftmost pixel of the topmost row. Following that is the pixel
+immediately to its right, and so on until the end of the top row of
+pixels. Following the rightmost pixel of the row there may be zero or
+more bytes of padding to guarantee that each row of pixel data has a
+certain alignment. Following the pad bytes, if any, is data for the
+leftmost pixel of the second row from the top, and so on. The last row
+has just as many pad bytes after it as the other rows.
+
+In V4L2 each format has an identifier which looks like ``PIX_FMT_XXX``,
+defined in the :ref:`videodev2.h <videodev>` header file. These
+identifiers represent
+:ref:`four character (FourCC) codes <v4l2-fourcc>` which are also
+listed below, however they are not the same as those used in the Windows
+world.
+
+For some formats, data is stored in separate, discontiguous memory
+buffers. Those formats are identified by a separate set of FourCC codes
+and are referred to as "multi-planar formats". For example, a
+:ref:`YUV422 <V4L2-PIX-FMT-YUV422M>` frame is normally stored in one
+memory buffer, but it can also be placed in two or three separate
+buffers, with Y component in one buffer and CbCr components in another
+in the 2-planar version or with each component in its own buffer in the
+3-planar case. Those sub-buffers are referred to as "*planes*".
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+******************************
+Multi-planar format structures
+******************************
+
+The struct :c:type:`v4l2_plane_pix_format` structures define size
+and layout for each of the planes in a multi-planar format. The
+struct :c:type:`v4l2_pix_format_mplane` structure contains
+information common to all planes (such as image width and height) and an
+array of struct :c:type:`v4l2_plane_pix_format` structures,
+describing all planes of that format.
+
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. c:type:: v4l2_plane_pix_format
+
+.. flat-table:: struct v4l2_plane_pix_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u32
+ - ``sizeimage``
+ - Maximum size in bytes required for image data in this plane.
+ * - __u32
+ - ``bytesperline``
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines. See struct :c:type:`v4l2_pix_format`.
+ * - __u16
+ - ``reserved[6]``
+ - Reserved for future extensions. Should be zeroed by drivers and
+ applications.
+
+
+.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.5cm}|
+
+.. c:type:: v4l2_pix_format_mplane
+
+.. flat-table:: struct v4l2_pix_format_mplane
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u32
+ - ``width``
+ - Image width in pixels. See struct
+ :c:type:`v4l2_pix_format`.
+ * - __u32
+ - ``height``
+ - Image height in pixels. See struct
+ :c:type:`v4l2_pix_format`.
+ * - __u32
+ - ``pixelformat``
+ - The pixel format. Both single- and multi-planar four character
+ codes can be used.
+ * - enum :c:type:`v4l2_field`
+ - ``field``
+ - See struct :c:type:`v4l2_pix_format`.
+ * - enum :c:type:`v4l2_colorspace`
+ - ``colorspace``
+ - See struct :c:type:`v4l2_pix_format`.
+ * - struct :c:type:`v4l2_plane_pix_format`
+ - ``plane_fmt[VIDEO_MAX_PLANES]``
+ - An array of structures describing format of each plane this pixel
+ format consists of. The number of valid entries in this array has
+ to be put in the ``num_planes`` field.
+ * - __u8
+ - ``num_planes``
+ - Number of planes (i.e. separate memory buffers) for this format
+ and the number of valid entries in the ``plane_fmt`` array.
+ * - __u8
+ - ``flags``
+ - Flags set by the application or driver, see :ref:`format-flags`.
+ * - enum :c:type:`v4l2_ycbcr_encoding`
+ - ``ycbcr_enc``
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+ * - enum :c:type:`v4l2_hsv_encoding`
+ - ``hsv_enc``
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+ * - enum :c:type:`v4l2_quantization`
+ - ``quantization``
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+ * - enum :c:type:`v4l2_xfer_func`
+ - ``xfer_func``
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+ * - __u8
+ - ``reserved[7]``
+ - Reserved for future extensions. Should be zeroed by drivers and
+ applications.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+******************************
+Single-planar format structure
+******************************
+
+.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}|
+
+.. c:type:: v4l2_pix_format
+
+.. cssclass:: longtable
+
+.. flat-table:: struct v4l2_pix_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u32
+ - ``width``
+ - Image width in pixels.
+ * - __u32
+ - ``height``
+ - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
+ ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
+ refers to the number of lines in the field, otherwise it refers to
+ the number of lines in the frame (which is twice the field height
+ for interlaced formats).
+ * - :cspan:`2` Applications set these fields to request an image
+ size, drivers return the closest possible values. In case of
+ planar formats the ``width`` and ``height`` applies to the largest
+ plane. To avoid ambiguities drivers must return values rounded up
+ to a multiple of the scale factor of any smaller planes. For
+ example when the image format is YUV 4:2:0, ``width`` and
+ ``height`` must be multiples of two.
+ * - __u32
+ - ``pixelformat``
+ - The pixel format or type of compression, set by the application.
+ This is a little endian
+ :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
+ RGB formats in :ref:`rgb-formats`, YUV formats in
+ :ref:`yuv-formats`, and reserved codes in
+ :ref:`reserved-formats`
+ * - enum :c:type::`v4l2_field`
+ - ``field``
+ - Video images are typically interlaced. Applications can request to
+ capture or output only the top or bottom field, or both fields
+ interlaced or sequentially stored in one buffer or alternating in
+ separate buffers. Drivers return the actual field order selected.
+ For more details on fields see :ref:`field-order`.
+ * - __u32
+ - ``bytesperline``
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines.
+ * - :cspan:`2`
+
+ Both applications and drivers can set this field to request
+ padding bytes at the end of each line. Drivers however may ignore
+ the value requested by the application, returning ``width`` times
+ bytes per pixel or a larger value required by the hardware. That
+ implies applications can just set this field to zero to get a
+ reasonable default.
+
+ Video hardware may access padding bytes, therefore they must
+ reside in accessible memory. Consider cases where padding bytes
+ after the last line of an image cross a system page boundary.
+ Input devices may write padding bytes, the value is undefined.
+ Output devices ignore the contents of padding bytes.
+
+ When the image format is planar the ``bytesperline`` value applies
+ to the first plane and is divided by the same factor as the
+ ``width`` field for the other planes. For example the Cb and Cr
+ planes of a YUV 4:2:0 image have half as many padding bytes
+ following each line as the Y plane. To avoid ambiguities drivers
+ must return a ``bytesperline`` value rounded up to a multiple of
+ the scale factor.
+
+ For compressed formats the ``bytesperline`` value makes no sense.
+ Applications and drivers must set this to 0 in that case.
+ * - __u32
+ - ``sizeimage``
+ - Size in bytes of the buffer to hold a complete image, set by the
+ driver. Usually this is ``bytesperline`` times ``height``. When
+ the image consists of variable length compressed data this is the
+ maximum number of bytes required to hold an image.
+ * - enum :c:type:`v4l2_colorspace`
+ - ``colorspace``
+ - This information supplements the ``pixelformat`` and must be set
+ by the driver for capture streams and by the application for
+ output streams, see :ref:`colorspaces`.
+ * - __u32
+ - ``priv``
+ - This field indicates whether the remaining fields of the
+ struct :c:type:`v4l2_pix_format`, also called the
+ extended fields, are valid. When set to
+ ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
+ have been correctly initialized. When set to any other value it
+ indicates that the extended fields contain undefined values.
+
+ Applications that wish to use the pixel format extended fields
+ must first ensure that the feature is supported by querying the
+ device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
+ capability. If the capability isn't set the pixel format extended
+ fields are not supported and using the extended fields will lead
+ to undefined results.
+
+ To use the extended fields, applications must set the ``priv``
+ field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
+ fields and zero the unused bytes of the
+ struct :c:type:`v4l2_format` ``raw_data`` field.
+
+ When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
+ drivers must act as if all the extended fields were set to zero.
+ On return drivers must set the ``priv`` field to
+ ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
+ applicable values.
+ * - __u32
+ - ``flags``
+ - Flags set by the application or driver, see :ref:`format-flags`.
+ * - enum :c:type:`v4l2_ycbcr_encoding`
+ - ``ycbcr_enc``
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+ * - enum :c:type:`v4l2_hsv_encoding`
+ - ``hsv_enc``
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+ * - enum :c:type:`v4l2_quantization`
+ - ``quantization``
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+ * - enum :c:type:`v4l2_xfer_func`
+ - ``xfer_func``
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
.. toctree::
:maxdepth: 1
- pixfmt-002
- pixfmt-003
- pixfmt-004
- colorspaces
- pixfmt-006
- pixfmt-007
- pixfmt-008
+ pixfmt-v4l2
+ pixfmt-v4l2-mplane
+ pixfmt-intro
pixfmt-indexed
pixfmt-rgb
yuv-formats
hsv-formats
depth-formats
- pixfmt-013
+ pixfmt-compressed
sdr-formats
tch-formats
meta-formats
pixfmt-reserved
+ colorspaces
+ colorspaces-defs
+ colorspaces-details
projects / openwrt / staging / blogic.git / commitdiff