V4L2에서 색공간 정의하기

색공간을 구성하는 네 값

V4L2의 색공간은 네 값으로 정의됩니다. 첫째 `enum v4l2_colorspace` 식별자는 색도 좌표와 기본 전달 함수, 기본 Y'CbCr 인코딩, 기본 양자화 방식을 한꺼번에 선택합니다.

둘째 `enum v4l2_xfer_func`는 색공간의 기본값과 다른 전달 함수를 지정합니다. 셋째 `enum v4l2_ycbcr_encoding`은 비표준 Y'CbCr 인코딩을, 넷째 `enum v4l2_quantization`은 비표준 양자화 방식을 선택합니다.

일반적인 경우에는 `struct v4l2_pix_format` 또는 `struct v4l2_pix_format_mplane`의 `colorspace` 필드만 채우면 됩니다. 나머지 세 필드는 기본값을 따르지 않아야 할 때만 명시적으로 덮어씁니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

****************************
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 색조 인코딩과 기본 양자화

HSV 형식에서 Hue는 원통형 색 표현의 각도로 정의됩니다. 보통 0도부터 360도까지 쓰는 이 각도를 8비트에 넣는 방법은 두 가지입니다.

`V4L2_HSV_ENC_180`은 각도를 2로 나누어 0부터 179까지 표현합니다. `V4L2_HSV_ENC_256`은 약 1.41로 나누어 8비트 전체인 0부터 255까지 사용합니다. 어떤 방식을 썼는지는 `enum v4l2_hsv_encoding`으로 표시합니다.

모든 색공간에서 R'G'B'의 기본 양자화는 전체 범위입니다. HSV 형식도 예외 없이 항상 전체 범위를 사용하므로 제한 범위 양자화를 선택할 수 없습니다.

.. _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. HSV formats are always full range.

enum v4l2_colorspace

`enum v4l2_colorspace`는 영상의 색도 좌표와 그 색공간에 대응하는 기본 전달 함수, Y'CbCr 인코딩, 양자화 방식을 선택합니다. 세부 수학 정의는 각 참조 절에서 다룹니다.

`V4L2_COLORSPACE_RAW`는 표준 디스플레이 색공간을 뜻하지 않습니다. 센서나 장치 고유의 원시 데이터를 전달하는 표식이므로, 이를 해석하는 소프트웨어가 해당 장치의 처리 파이프라인과 내부 색 표현을 별도로 알아야 합니다.

.. tabularcolumns:: |p{6.7cm}|p{10.8cm}|

.. 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_OPRGB``
      - See :ref:`col-oprgb`.
    * - ``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.

enum v4l2_xfer_func

`enum v4l2_xfer_func`는 색공간에 내장된 기본 전달 함수를 그대로 쓰거나, 특정 표준의 비선형 전달 함수 또는 선형 RGB를 명시합니다.

`V4L2_XFER_FUNC_NONE`은 이미 선형화된 RGB 데이터를 명시하는 선택입니다. `DEFAULT`와 달리 어떤 비선형 변환도 적용하지 않는다는 의미가 ABI에 직접 기록됩니다.

.. c:type:: v4l2_xfer_func

.. tabularcolumns:: |p{5.5cm}|p{12.0cm}|

.. 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_OPRGB``
      - Use the opRGB 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. See :ref:`xf-smpte-2084`.

enum v4l2_ycbcr_encoding

`enum v4l2_ycbcr_encoding`은 R'G'B' 성분을 휘도와 색차 성분으로 표현할 때 사용하는 계수와 방식의 표준을 선택합니다.

BT.2020의 두 식별자는 휘도 신호를 만드는 방식이 다릅니다. 일반 `BT2020`은 비상수 휘도 Y'CbCr이고, `BT2020_CONST_LUM`은 상수 휘도 Yc'CbcCrc입니다.

.. c:type:: v4l2_ycbcr_encoding

.. tabularcolumns:: |p{7.2cm}|p{10.3cm}|

.. 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.

enum v4l2_hsv_encoding

`enum v4l2_hsv_encoding`은 HSV 영상의 Hue 각도를 8비트 코드로 환산하는 규칙을 표시합니다. Saturation과 Value가 아니라 Hue 축의 스케일만 구분합니다.

.. 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.

enum v4l2_quantization

`enum v4l2_quantization`은 정규화된 성분 값을 디지털 코드 범위에 배치하는 방식을 선택합니다. `DEFAULT`는 색공간이 정한 규칙을 따릅니다.

기본값은 R'G'B'와 HSV에서는 항상 전체 범위이고 Y'CbCr에서는 보통 제한 범위입니다. HSV에는 제한 범위를 사용할 수 없습니다.

전체 범위는 가능한 코드 공간을 거의 모두 사용하고, 제한 범위는 방송 영상의 headroom과 footroom을 남깁니다. 선택한 범위를 잘못 해석하면 검정과 흰색 레벨, 색차 진폭이 달라집니다.

.. 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' 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]. Limited Range cannot be used with HSV.