요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
3
.. _selection-vs-crop:
5
********************************
6
Comparison with old cropping API
7
********************************
9
The selection API was introduced to cope with deficiencies of the
10
older :ref:`CROP API <crop>`, that was designed to control simple
11
capture devices. Later the cropping API was adopted by video output
12
drivers. The ioctls are used to select a part of the display were the
13
video signal is inserted. It should be considered as an API abuse
14
because the described operation is actually the composing. The
15
selection API makes a clear distinction between composing and cropping
16
operations by setting the appropriate targets.
18
The CROP API lacks any support for composing to and cropping from an
19
image inside a memory buffer. The application could configure a
20
capture device to fill only a part of an image by abusing V4L2
21
API. Cropping a smaller image from a larger one is achieved by setting
22
the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`.
23
Introducing an image offsets could be done by modifying field
24
``m_userptr`` at struct :c:type:`v4l2_buffer` before calling
25
:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided
26
because they are not portable (endianness), and do not work for
27
macroblock and Bayer formats and mmap buffers.
29
The selection API deals with configuration of buffer
30
cropping/composing in a clear, intuitive and portable way. Next, with
31
the selection API the concepts of the padded target and constraints
32
flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct
33
:c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no
34
way to extend their functionality. The new struct
35
:c:type:`v4l2_selection` provides a lot of place for future
36
extensions.
38
Driver developers are encouraged to implement only selection API. The
39
former cropping API would be simulated using the new one.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
기존 CROP API의 한계와 대체 이유
1-39기존 CROP API는 단순한 캡처 장치를 위해 설계되었지만, 출력 드라이버에서는 화면에 영상을 넣을 위치를 선택하는 용도로도 사용되었습니다. 이 동작은 실제로 자르기가 아니라 합성이므로, 선택 API는 `target`으로 CROP과 COMPOSE를 명확히 구분합니다.
기존 API에는 메모리 버퍼로 합성하거나 버퍼에서 자르는 기능을 표현할 방법이 없었습니다. 일부 구현은 `v4l2_pix_format.bytesperline`으로 버퍼 일부를 채우거나 자르고, `VIDIOC_QBUF` 전에 `v4l2_buffer.m_userptr`를 바꿔 시작 오프셋을 조정했습니다.
이 우회 방식은 엔디언과 메모리 배치에 종속되어 이식성이 낮고, 매크로블록 또는 Bayer 형식과 mmap I/O에서는 제대로 동작하지 않습니다. 선택 API는 이를 명시적이고 이식 가능한 사각형으로 표현하며, 패딩 대상과 제약 플래그도 제공합니다.
`v4l2_crop`과 `v4l2_cropcap`에는 예약 필드가 없어 기능 확장이 어렵지만 `v4l2_selection`에는 확장 공간이 있습니다. 드라이버는 선택 API만 구현하는 것이 권장되며, 필요한 경우 커널이 기존 CROP API 동작을 선택 API로 모의할 수 있습니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. _selection-vs-crop:
********************************
Comparison with old cropping API
********************************
The selection API was introduced to cope with deficiencies of the
older :ref:`CROP API <crop>`, that was designed to control simple
capture devices. Later the cropping API was adopted by video output
drivers. The ioctls are used to select a part of the display were the
video signal is inserted. It should be considered as an API abuse
because the described operation is actually the composing. The
selection API makes a clear distinction between composing and cropping
operations by setting the appropriate targets.
The CROP API lacks any support for composing to and cropping from an
image inside a memory buffer. The application could configure a
capture device to fill only a part of an image by abusing V4L2
API. Cropping a smaller image from a larger one is achieved by setting
the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`.
Introducing an image offsets could be done by modifying field
``m_userptr`` at struct :c:type:`v4l2_buffer` before calling
:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided
because they are not portable (endianness), and do not work for
macroblock and Bayer formats and mmap buffers.
The selection API deals with configuration of buffer
cropping/composing in a clear, intuitive and portable way. Next, with
the selection API the concepts of the padded target and constraints
flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct
:c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no
way to extend their functionality. The new struct
:c:type:`v4l2_selection` provides a lot of place for future
extensions.
Driver developers are encouraged to implement only selection API. The
former cropping API would be simulated using the new one.
요약·해설
selection-api-vs-crop-api.rst:1-39기존 CROP API의 한계와 선택 API로 대체하는 이유를 설명합니다.