요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
.. c:namespace:: V4L
4
.. _format:
6
************
7
Data Formats
8
************
10
Data Format Negotiation
11
=======================
13
Different devices exchange different kinds of data with applications,
14
for example video images, raw or sliced VBI data, RDS datagrams. Even
15
within one kind many different formats are possible, in particular there is an
16
abundance of image formats. Although drivers must provide a default and
17
the selection persists across closing and reopening a device,
18
applications should always negotiate a data format before engaging in
19
data exchange. Negotiation means the application asks for a particular
20
format and the driver selects and reports the best the hardware can do
21
to satisfy the request. Of course applications can also just query the
22
current selection.
24
A single mechanism exists to negotiate all data formats using the
25
aggregate struct :c:type:`v4l2_format` and the
26
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
27
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the
28
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine
29
what the hardware *could* do, without actually selecting a new data
30
format. The data formats supported by the V4L2 API are covered in the
31
respective device section in :ref:`devices`. For a closer look at
32
image formats see :ref:`pixfmt`.
34
The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the
35
initialization sequence. Prior to this point multiple panel applications
36
can access the same device concurrently to select the current input,
37
change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
38
assigns a logical stream (video data, VBI data etc.) exclusively to one
39
file descriptor.
41
Exclusive means no other application, more precisely no other file
42
descriptor, can grab this stream or change device properties
43
inconsistent with the negotiated parameters. A video standard change for
44
example, when the new standard uses a different number of scan lines,
45
can invalidate the selected image format. Therefore only the file
46
descriptor owning the stream can make invalidating changes. Accordingly
47
multiple file descriptors which grabbed different logical streams
48
prevent each other from interfering with their settings. When for
49
example video overlay is about to start or already in progress,
50
simultaneous video capturing may be restricted to the same cropping and
51
image size.
53
When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side
54
effects are implied by the next step, the selection of an I/O method
55
with the :ref:`VIDIOC_REQBUFS` ioctl or implicit
56
with the first :c:func:`read()` or
57
:c:func:`write()` call.
59
Generally only one logical stream can be assigned to a file descriptor,
60
the exception being drivers permitting simultaneous video capturing and
61
overlay using the same file descriptor for compatibility with V4L and
62
earlier versions of V4L2. Switching the logical stream or returning into
63
"panel mode" is possible by closing and reopening the device. Drivers
64
*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
66
All drivers exchanging data with applications must support the
67
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the
68
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.
70
Image Format Enumeration
71
========================
73
Apart of the generic format negotiation functions a special ioctl to
74
enumerate all image formats supported by video capture, overlay or
75
output devices is available. [#f1]_
77
The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported
78
by all drivers exchanging image data with applications.
80
.. important::
82
Drivers are not supposed to convert image formats in kernel space.
83
They must enumerate only formats directly supported by the hardware.
84
If necessary driver writers should publish an example conversion
85
routine or library for integration into applications.
87
.. [#f1]
88
Enumerating formats an application has no a-priori knowledge of
89
(otherwise it could explicitly ask for them and need not enumerate)
90
seems useless, but there are applications serving as proxy between
91
drivers and the actual video applications for which this is useful.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
데이터 형식 협상과 stream 소유권
1-69V4L2 장치는 video image, raw 또는 sliced VBI data, RDS datagram처럼 서로 다른 데이터를 application과 교환하고 각 종류 안에도 많은 format이 있습니다. Driver는 기본 format을 제공하고 선택은 장치를 닫았다 다시 열어도 유지되지만, application은 data exchange 전에 항상 format을 협상해야 합니다. Application이 원하는 값을 요청하면 driver가 hardware로 가능한 최선의 값을 선택해 보고하며 현재 선택만 조회할 수도 있습니다.
모든 data format은 aggregate `v4l2_format`과 `VIDIOC_G_FMT`, `VIDIOC_S_FMT`로 협상합니다. `VIDIOC_TRY_FMT`은 실제 선택을 바꾸지 않고 hardware가 수행할 수 있는 값을 시험합니다. 각 format은 device 절에, image format은 pixel format 절에 설명됩니다.
첫 `VIDIOC_S_FMT`은 초기화 과정의 중요한 전환점입니다. 그전에는 여러 panel application이 동시에 input과 control 등의 속성을 바꿀 수 있지만, 첫 호출 뒤에는 video나 VBI 같은 logical stream 하나가 해당 file descriptor에 독점 배정됩니다.
독점 배정 뒤에는 다른 file descriptor가 그 stream을 가져가거나 협상값과 모순되는 속성을 바꿀 수 없습니다. 예를 들어 scan line 수가 달라지는 video standard 변경은 선택한 image format을 무효화하므로 stream 소유자만 수행할 수 있습니다. 서로 다른 logical stream을 가진 descriptor들도 상대 설정을 방해할 수 없고, overlay와 capture를 동시에 쓰면 같은 crop과 image size가 요구될 수 있습니다.
`VIDIOC_G_FMT`로 현재 format 조회→`VIDIOC_TRY_FMT`로 후보값 시험→`VIDIOC_S_FMT`로 실제 format 선택→Logical stream을 file descriptor에 독점 배정→`VIDIOC_REQBUFS` 또는 첫 read/write로 I/O 시작
Format 선택을 생략해도 첫 I/O 준비 동작에서 같은 소유권 효과가 생깁니다.
Application이 `VIDIOC_S_FMT`을 생략하면 `VIDIOC_REQBUFS`로 I/O method를 고르거나 첫 `read()`/`write()`를 호출할 때 잠금 효과가 암묵적으로 생깁니다. 일반적으로 descriptor 하나에는 logical stream 하나만 배정됩니다. 구형 V4L 호환을 위해 같은 descriptor에서 capture와 overlay를 허용하는 드라이버가 예외입니다. Stream을 바꾸거나 panel mode로 돌아가려면 장치를 닫고 다시 열며, 일부 driver는 `VIDIOC_S_FMT` 전환도 지원할 수 있습니다.
Data를 application과 교환하는 모든 driver는 `VIDIOC_G_FMT`과 `VIDIOC_S_FMT`을 구현해야 합니다. `VIDIOC_TRY_FMT` 구현은 강력히 권장되지만 선택 사항입니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _format:
************
Data Formats
************
Data Format Negotiation
=======================
Different devices exchange different kinds of data with applications,
for example video images, raw or sliced VBI data, RDS datagrams. Even
within one kind many different formats are possible, in particular there is an
abundance of image formats. Although drivers must provide a default and
the selection persists across closing and reopening a device,
applications should always negotiate a data format before engaging in
data exchange. Negotiation means the application asks for a particular
format and the driver selects and reports the best the hardware can do
to satisfy the request. Of course applications can also just query the
current selection.
A single mechanism exists to negotiate all data formats using the
aggregate struct :c:type:`v4l2_format` and the
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine
what the hardware *could* do, without actually selecting a new data
format. The data formats supported by the V4L2 API are covered in the
respective device section in :ref:`devices`. For a closer look at
image formats see :ref:`pixfmt`.
The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the
initialization sequence. Prior to this point multiple panel applications
can access the same device concurrently to select the current input,
change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
assigns a logical stream (video data, VBI data etc.) exclusively to one
file descriptor.
Exclusive means no other application, more precisely no other file
descriptor, can grab this stream or change device properties
inconsistent with the negotiated parameters. A video standard change for
example, when the new standard uses a different number of scan lines,
can invalidate the selected image format. Therefore only the file
descriptor owning the stream can make invalidating changes. Accordingly
multiple file descriptors which grabbed different logical streams
prevent each other from interfering with their settings. When for
example video overlay is about to start or already in progress,
simultaneous video capturing may be restricted to the same cropping and
image size.
When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side
effects are implied by the next step, the selection of an I/O method
with the :ref:`VIDIOC_REQBUFS` ioctl or implicit
with the first :c:func:`read()` or
:c:func:`write()` call.
Generally only one logical stream can be assigned to a file descriptor,
the exception being drivers permitting simultaneous video capturing and
overlay using the same file descriptor for compatibility with V4L and
earlier versions of V4L2. Switching the logical stream or returning into
"panel mode" is possible by closing and reopening the device. Drivers
*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
All drivers exchanging data with applications must support the
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.
Image format 열거
70-91일반 format 협상 외에 capture, overlay 또는 output 장치가 지원하는 모든 image format을 열거하는 `VIDIOC_ENUM_FMT`이 있습니다. Image data를 application과 교환하는 모든 driver는 이 ioctl을 지원해야 합니다.
Driver는 kernel space에서 image format을 변환해서는 안 됩니다. `VIDIOC_ENUM_FMT`에는 hardware가 직접 지원하는 format만 나열해야 하며, 변환이 필요하면 driver 작성자는 application에 통합할 예제 routine이나 library를 제공해야 합니다.
사전에 모르는 format을 열거하는 기능은 일반 application에는 불필요해 보일 수 있지만, driver와 실제 video application 사이에서 proxy로 동작하는 프로그램에는 유용합니다.
항목설명
`VIDIOC_G_FMT`현재 선택된 data format을 조회합니다.
`VIDIOC_TRY_FMT`상태 변경 없이 요청값을 hardware가 어떻게 조정할지 시험합니다.
`VIDIOC_S_FMT`Format을 선택하고 logical stream 소유권을 확립합니다.
`VIDIOC_ENUM_FMT`Hardware가 직접 지원하는 image format을 열거합니다.
조회, 시험, 선택과 열거를 분리합니다.
Image Format Enumeration
========================
Apart of the generic format negotiation functions a special ioctl to
enumerate all image formats supported by video capture, overlay or
output devices is available. [#f1]_
The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported
by all drivers exchanging image data with applications.
.. important::
Drivers are not supposed to convert image formats in kernel space.
They must enumerate only formats directly supported by the hardware.
If necessary driver writers should publish an example conversion
routine or library for integration into applications.
.. [#f1]
Enumerating formats an application has no a-priori knowledge of
(otherwise it could explicitly ask for them and need not enumerate)
seems useless, but there are applications serving as proxy between
drivers and the actual video applications for which this is useful.
요약·해설
format.rst:1-91Application은 실제 I/O 전에 format을 협상해야 하며 첫 `VIDIOC_S_FMT`은 logical stream 소유권을 descriptor에 고정합니다. Driver는 hardware-native image format만 열거해야 합니다.