← Documents Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst GitHub 원문 ↗

Linux 6.18.37 · Userspace API / Media / V4L

V4L2 다중 평면 포맷 구조체

평면별 버퍼 크기와 행 간격, 공통 영상 속성 및 색도 필드의 관계를 설명합니다.

Source pathDocumentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약·해설

pixfmt-v4l2-mplane.rst:1-123

평면별 버퍼 크기와 행 간격, 공통 영상 속성 및 색도 필드의 관계를 설명합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3 ******************************
4 Multi-planar format structures
5 ******************************
6
7 The struct :c:type:`v4l2_plane_pix_format` structures define size
8 and layout for each of the planes in a multi-planar format. The
9 struct :c:type:`v4l2_pix_format_mplane` structure contains
10 information common to all planes (such as image width and height) and an
11 array of struct :c:type:`v4l2_plane_pix_format` structures,
12 describing all planes of that format.
13
14
15
16 .. tabularcolumns:: |p{1.4cm}|p{4.0cm}|p{11.9cm}|
17
18 .. c:type:: v4l2_plane_pix_format
19
20 .. flat-table:: struct v4l2_plane_pix_format
21 :header-rows: 0
22 :stub-columns: 0
23 :widths: 1 1 2
24
25 * - __u32
26 - ``sizeimage``
27 - Maximum size in bytes required for image data in this plane,
28 set by the driver. When the image consists of variable length
29 compressed data this is the number of bytes required by the
30 codec to support the worst-case compression scenario.
31
32 The driver will set the value for uncompressed images.
33
34 Clients are allowed to set the sizeimage field for variable length
35 compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at
36 :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the
37 value itself, or it may modify the provided value based on
38 alignment requirements or minimum/maximum size requirements.
39 If the client wants to leave this to the driver, then it should
40 set sizeimage to 0.
41 * - __u32
42 - ``bytesperline``
43 - Distance in bytes between the leftmost pixels in two adjacent
44 lines. See struct :c:type:`v4l2_pix_format`.
45 * - __u16
46 - ``reserved[6]``
47 - Reserved for future extensions. Should be zeroed by drivers and
48 applications.
49
50
51 .. raw:: latex
52
53 \small
54
55 .. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.3cm}|
56
57 .. c:type:: v4l2_pix_format_mplane
58
59 .. flat-table:: struct v4l2_pix_format_mplane
60 :header-rows: 0
61 :stub-columns: 0
62 :widths: 1 1 2
63
64 * - __u32
65 - ``width``
66 - Image width in pixels. See struct
67 :c:type:`v4l2_pix_format`.
68 * - __u32
69 - ``height``
70 - Image height in pixels. See struct
71 :c:type:`v4l2_pix_format`.
72 * - __u32
73 - ``pixelformat``
74 - The pixel format. Both single- and multi-planar four character
75 codes can be used.
76 * - __u32
77 - ``field``
78 - Field order, from enum :c:type:`v4l2_field`.
79 See struct :c:type:`v4l2_pix_format`.
80 * - __u32
81 - ``colorspace``
82 - Colorspace encoding, from enum :c:type:`v4l2_colorspace`.
83 See struct :c:type:`v4l2_pix_format`.
84 * - struct :c:type:`v4l2_plane_pix_format`
85 - ``plane_fmt[VIDEO_MAX_PLANES]``
86 - An array of structures describing format of each plane this pixel
87 format consists of. The number of valid entries in this array has
88 to be put in the ``num_planes`` field.
89 * - __u8
90 - ``num_planes``
91 - Number of planes (i.e. separate memory buffers) for this format
92 and the number of valid entries in the ``plane_fmt`` array.
93 * - __u8
94 - ``flags``
95 - Flags set by the application or driver, see :ref:`format-flags`.
96 * - union {
97 - (anonymous)
98 * - __u8
99 - ``ycbcr_enc``
100 - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
101 See struct :c:type:`v4l2_pix_format`.
102 * - __u8
103 - ``hsv_enc``
104 - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
105 See struct :c:type:`v4l2_pix_format`.
106 * - }
107 -
108 * - __u8
109 - ``quantization``
110 - Quantization range, from enum :c:type:`v4l2_quantization`.
111 See struct :c:type:`v4l2_pix_format`.
112 * - __u8
113 - ``xfer_func``
114 - Transfer function, from enum :c:type:`v4l2_xfer_func`.
115 See struct :c:type:`v4l2_pix_format`.
116 * - __u8
117 - ``reserved[7]``
118 - Reserved for future extensions. Should be zeroed by drivers and
119 applications.
120
121 .. raw:: latex
122
123 \normalsize
124

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

평면별 크기와 배치

1-50

`v4l2_plane_pix_format` 구조체는 다중 평면 포맷을 이루는 각 평면의 크기와 메모리 배치를 정의합니다. `v4l2_pix_format_mplane`은 영상 너비와 높이처럼 모든 평면에 공통인 정보와, 각 평면을 설명하는 `v4l2_plane_pix_format` 배열을 함께 담습니다.

struct v4l2_plane_pix_format
필드한국어 설명
`__u32 sizeimage`이 평면의 영상 데이터에 필요한 최대 바이트 수이며 드라이버가 설정합니다. 가변 길이 압축 데이터라면 코덱의 최악 압축 상황을 처리하는 데 필요한 크기입니다. 비압축 영상에서는 드라이버가 값을 정합니다. `VIDIOC_ENUM_FMT`에서 `V4L2_FMT_FLAG_COMPRESSED`로 표시된 가변 길이 압축 포맷은 클라이언트가 값을 제안할 수 있지만, 드라이버가 무시하거나 정렬 및 최소·최대 크기 조건에 맞게 바꿀 수 있습니다. 드라이버에 맡기려면 0을 설정합니다.
`__u32 bytesperline`서로 인접한 두 행의 가장 왼쪽 픽셀 사이 거리(바이트)입니다. 자세한 규칙은 `v4l2_pix_format`의 같은 필드를 따릅니다.
`__u16 reserved[6]`향후 확장을 위한 예약 영역입니다. 드라이버와 애플리케이션 모두 0으로 초기화해야 합니다.

각 항목은 한 평면에 필요한 버퍼 크기와 행 간격을 기술합니다.

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

******************************
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{1.4cm}|p{4.0cm}|p{11.9cm}|

.. 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,
	set by the driver. When the image consists of variable length
	compressed data this is the number of bytes required by the
	codec to support the worst-case compression scenario.

	The driver will set the value for uncompressed images.

	Clients are allowed to set the sizeimage field for variable length
	compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at
	:ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the
	value itself, or it may modify the provided value based on
	alignment requirements or minimum/maximum size requirements.
	If the client wants to leave this to the driver, then it should
	set sizeimage to 0.
    * - __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.

모든 평면에 공통인 포맷 정보

51-123

`v4l2_pix_format_mplane`은 공통 영상 속성과 평면별 배열을 결합합니다. `num_planes`는 실제로 분리된 메모리 버퍼의 수인 동시에 `plane_fmt` 배열에서 유효한 원소 수입니다.

struct v4l2_pix_format_mplane
필드한국어 설명
`__u32 width`픽셀 단위 영상 너비입니다. `v4l2_pix_format`의 너비 규칙을 따릅니다.
`__u32 height`픽셀 단위 영상 높이입니다. `v4l2_pix_format`의 높이 규칙을 따릅니다.
`__u32 pixelformat`픽셀 포맷입니다. 단일 평면 및 다중 평면 FourCC를 모두 사용할 수 있습니다.
`__u32 field``v4l2_field` 열거형의 필드 순서입니다. `v4l2_pix_format`의 규칙을 따릅니다.
`__u32 colorspace``v4l2_colorspace` 열거형의 색공간 인코딩입니다. `v4l2_pix_format`의 규칙을 따릅니다.
`plane_fmt[VIDEO_MAX_PLANES]`각 평면의 포맷을 설명하는 `v4l2_plane_pix_format` 배열입니다. 유효 원소 수는 `num_planes`에 기록해야 합니다.
`__u8 num_planes`이 포맷의 평면 수, 즉 서로 분리된 메모리 버퍼 수이며 `plane_fmt`의 유효 원소 수도 뜻합니다.
`__u8 flags`애플리케이션 또는 드라이버가 설정하는 포맷 플래그입니다. `format-flags`를 참조합니다.
`__u8 ycbcr_enc` / `hsv_enc`익명 공용체의 Y'CbCr 또는 HSV 인코딩 값입니다. 각각 `v4l2_ycbcr_encoding`, `v4l2_hsv_encoding` 열거형을 사용하며 `v4l2_pix_format`의 규칙을 따릅니다.
`__u8 quantization``v4l2_quantization` 열거형의 양자화 범위입니다. `v4l2_pix_format`의 규칙을 따릅니다.
`__u8 xfer_func``v4l2_xfer_func` 열거형의 전달 함수입니다. `v4l2_pix_format`의 규칙을 따릅니다.
`__u8 reserved[7]`향후 확장을 위한 예약 영역입니다. 드라이버와 애플리케이션 모두 0으로 초기화해야 합니다.

단일 평면과 다중 평면 FourCC를 모두 사용할 수 있으며, 색도 관련 항목은 단일 평면 구조체의 의미를 공유합니다.

다중 평면 배열 설정
영상 공통 속성과 픽셀 포맷을 설정합니다.각 분리 버퍼의 `plane_fmt` 항목에 `sizeimage`와 `bytesperline`을 기록합니다.유효한 항목 수를 `num_planes`에 기록하고 나머지 예약 바이트를 0으로 둡니다.

배열의 유효 범위와 예약 필드를 명시적으로 맞춥니다.

.. raw:: latex

    \small

.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.3cm}|

.. 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.
    * - __u32
      - ``field``
      - Field order, from enum :c:type:`v4l2_field`.
        See struct :c:type:`v4l2_pix_format`.
    * - __u32
      - ``colorspace``
      - Colorspace encoding, from enum :c:type:`v4l2_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`.
    * - union {
      - (anonymous)
    * - __u8
      - ``ycbcr_enc``
      - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
	See struct :c:type:`v4l2_pix_format`.
    * - __u8
      - ``hsv_enc``
      - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
	See struct :c:type:`v4l2_pix_format`.
    * - }
      -
    * - __u8
      - ``quantization``
      - Quantization range, from enum :c:type:`v4l2_quantization`.
	See struct :c:type:`v4l2_pix_format`.
    * - __u8
      - ``xfer_func``
      - Transfer function, from enum :c:type:`v4l2_xfer_func`.
	See struct :c:type:`v4l2_pix_format`.
    * - __u8
      - ``reserved[7]``
      - Reserved for future extensions. Should be zeroed by drivers and
	applications.

.. raw:: latex

    \normalsize