← Documents Documentation/userspace-api/media/v4l/planar-apis.rst GitHub 원문 ↗

Linux 6.18.37 · Userspace API / Media / V4L

단일·다중 평면 API

분리된 평면 버퍼와 관련 ioctl 구조체의 차이를 설명합니다.

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

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

1. 요약·해설

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

요약·해설

planar-apis.rst:1-61

분리된 평면 버퍼와 관련 ioctl 구조체의 차이를 설명합니다.

2. 영어 원문 전체

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

원문 전체 펼치기
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3 .. _planar-apis:
4
5 *****************************
6 Single- and multi-planar APIs
7 *****************************
8
9 Some devices require data for each input or output video frame to be
10 placed in discontiguous memory buffers. In such cases, one video frame
11 has to be addressed using more than one memory address, i.e. one pointer
12 per "plane". A plane is a sub-buffer of the current frame. For examples
13 of such formats see :ref:`pixfmt`.
14
15 Initially, V4L2 API did not support multi-planar buffers and a set of
16 extensions has been introduced to handle them. Those extensions
17 constitute what is being referred to as the "multi-planar API".
18
19 Some of the V4L2 API calls and structures are interpreted differently,
20 depending on whether single- or multi-planar API is being used. An
21 application can choose whether to use one or the other by passing a
22 corresponding buffer type to its ioctl calls. Multi-planar versions of
23 buffer types are suffixed with an ``_MPLANE`` string. For a list of
24 available multi-planar buffer types see enum
25 :c:type:`v4l2_buf_type`.
26
27
28 Multi-planar formats
29 ====================
30
31 Multi-planar API introduces new multi-planar formats. Those formats use
32 a separate set of FourCC codes. It is important to distinguish between
33 the multi-planar API and a multi-planar format. Multi-planar API calls
34 can handle all single-planar formats as well (as long as they are passed
35 in multi-planar API structures), while the single-planar API cannot
36 handle multi-planar formats.
37
38
39 Calls that distinguish between single and multi-planar APIs
40 ===========================================================
41
42 :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
43 Two additional multi-planar capabilities are added. They can be set
44 together with non-multi-planar ones for devices that handle both
45 single- and multi-planar formats.
46
47 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`
48 New structures for describing multi-planar formats are added: struct
49 :c:type:`v4l2_pix_format_mplane` and
50 struct :c:type:`v4l2_plane_pix_format`.
51 Drivers may define new multi-planar formats, which have distinct
52 FourCC codes from the existing single-planar ones.
53
54 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`
55 A new struct :c:type:`v4l2_plane` structure for
56 describing planes is added. Arrays of this structure are passed in
57 the new ``m.planes`` field of struct
58 :c:type:`v4l2_buffer`.
59
60 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
61 Will allocate multi-planar buffers as requested.
62

3. 한국어 전문 번역

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

분리된 프레임 버퍼

1-27

일부 장치는 입력 또는 출력 프레임의 데이터를 서로 떨어진 메모리 버퍼에 배치해야 합니다. 이때 프레임 하나를 둘 이상의 주소, 즉 평면마다 포인터 하나로 지정합니다. 평면은 현재 프레임을 이루는 하위 버퍼입니다.

초기 V4L2 API에는 다중 평면 버퍼 지원이 없었고, 이를 처리하기 위한 확장 집합이 다중 평면 API로 추가되었습니다. ioctl에 전달하는 버퍼 유형으로 단일 또는 다중 평면 API를 선택하며, 다중 평면 유형은 `_MPLANE` 접미사를 사용합니다. 사용 가능한 유형은 `v4l2_buf_type`을 참조합니다.

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

.. _planar-apis:

*****************************
Single- and multi-planar APIs
*****************************

Some devices require data for each input or output video frame to be
placed in discontiguous memory buffers. In such cases, one video frame
has to be addressed using more than one memory address, i.e. one pointer
per "plane". A plane is a sub-buffer of the current frame. For examples
of such formats see :ref:`pixfmt`.

Initially, V4L2 API did not support multi-planar buffers and a set of
extensions has been introduced to handle them. Those extensions
constitute what is being referred to as the "multi-planar API".

Some of the V4L2 API calls and structures are interpreted differently,
depending on whether single- or multi-planar API is being used. An
application can choose whether to use one or the other by passing a
corresponding buffer type to its ioctl calls. Multi-planar versions of
buffer types are suffixed with an ``_MPLANE`` string. For a list of
available multi-planar buffer types see enum
:c:type:`v4l2_buf_type`.

다중 평면 API와 포맷의 구분

28-38

다중 평면 API는 별도의 FourCC를 사용하는 다중 평면 포맷도 도입합니다. 하지만 API와 포맷은 서로 다른 개념입니다.

다중 평면 API 호출은 단일 평면 포맷을 다중 평면 구조체에 담아 처리할 수 있습니다. 반대로 단일 평면 API는 다중 평면 포맷을 처리할 수 없습니다.

Multi-planar formats
====================

Multi-planar API introduces new multi-planar formats. Those formats use
a separate set of FourCC codes. It is important to distinguish between
the multi-planar API and a multi-planar format. Multi-planar API calls
can handle all single-planar formats as well (as long as they are passed
in multi-planar API structures), while the single-planar API cannot
handle multi-planar formats.

API에 따라 달라지는 호출

39-61
단일·다중 평면 API 구분 지점
호출다중 평면 해석
VIDIOC_QUERYCAP단일 평면 기능과 함께 설정할 수 있는 다중 평면 기능 비트 두 개가 추가됩니다.
VIDIOC_G_FMT / S_FMT / TRY_FMT다중 평면 포맷을 설명하는 `v4l2_pix_format_mplane`과 `v4l2_plane_pix_format`을 사용합니다. 드라이버는 단일 평면 FourCC와 구별되는 새 다중 평면 FourCC를 정의할 수 있습니다.
VIDIOC_QBUF / DQBUF / QUERYBUF평면을 설명하는 `v4l2_plane` 배열을 `v4l2_buffer.m.planes`에 전달합니다.
VIDIOC_REQBUFS요청한 다중 평면 버퍼를 할당합니다.

같은 ioctl이라도 버퍼 유형에 따라 기능 비트와 구조체 해석이 달라집니다.

Calls that distinguish between single and multi-planar APIs
===========================================================

:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
    Two additional multi-planar capabilities are added. They can be set
    together with non-multi-planar ones for devices that handle both
    single- and multi-planar formats.

:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`
    New structures for describing multi-planar formats are added: struct
    :c:type:`v4l2_pix_format_mplane` and
    struct :c:type:`v4l2_plane_pix_format`.
    Drivers may define new multi-planar formats, which have distinct
    FourCC codes from the existing single-planar ones.

:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`
    A new struct :c:type:`v4l2_plane` structure for
    describing planes is added. Arrays of this structure are passed in
    the new ``m.planes`` field of struct
    :c:type:`v4l2_buffer`.

:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
    Will allocate multi-planar buffers as requested.