요약·해설과 원문, 전문 번역을 서로 분리했습니다. 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
.. _output:
6
**********************
7
Video Output Interface
8
**********************
10
Video output devices encode stills or image sequences as analog video
11
signal. With this interface applications can control the encoding
12
process and move images from user space to the driver.
14
Conventionally V4L2 video output devices are accessed through character
15
device special files named ``/dev/video`` and ``/dev/video0`` to
16
``/dev/video63`` with major number 81 and minor numbers 0 to 63.
17
``/dev/video`` is typically a symbolic link to the preferred video
18
device.
20
.. note:: The same device file names are used also for video capture devices.
22
Querying Capabilities
23
=====================
25
Devices supporting the video output interface set the
26
``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in
27
the ``capabilities`` field of struct
28
:c:type:`v4l2_capability` returned by the
29
:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
30
functions they may also support the :ref:`raw VBI output <raw-vbi>`
31
(``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or
32
streaming I/O methods must be supported. Modulators and audio outputs
33
are optional.
35
Supplemental Functions
36
======================
38
Video output devices shall support :ref:`audio output <audio>`,
39
:ref:`modulator <tuner>`, :ref:`controls <control>`,
40
:ref:`cropping and scaling <crop>` and
41
:ref:`streaming parameter <streaming-par>` ioctls as needed. The
42
:ref:`video output <video>` ioctls must be supported by all video
43
output devices.
45
Image Format Negotiation
46
========================
48
The output is determined by cropping and image format parameters. The
49
former select an area of the video picture where the image will appear,
50
the latter how images are stored in memory, i. e. in RGB or YUV format,
51
the number of bits per pixel or width and height. Together they also
52
define how images are scaled in the process.
54
As usual these parameters are *not* reset at :c:func:`open()`
55
time to permit Unix tool chains, programming a device and then writing
56
to it as if it was a plain file. Well written V4L2 applications ensure
57
they really get what they want, including cropping and scaling.
59
Cropping initialization at minimum requires to reset the parameters to
60
defaults. An example is given in :ref:`crop`.
62
To query the current image format applications set the ``type`` field of
63
a struct :c:type:`v4l2_format` to
64
``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
65
and call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer
66
to this structure. Drivers fill the struct
67
:c:type:`v4l2_pix_format` ``pix`` or the struct
68
:c:type:`v4l2_pix_format_mplane` ``pix_mp``
69
member of the ``fmt`` union.
71
To request different parameters applications set the ``type`` field of a
72
struct :c:type:`v4l2_format` as above and initialize all
73
fields of the struct :c:type:`v4l2_pix_format`
74
``vbi`` member of the ``fmt`` union, or better just modify the results
75
of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
76
ioctl with a pointer to this structure. Drivers may adjust the
77
parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
78
does.
80
Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
81
can be used to learn about hardware limitations without disabling I/O or
82
possibly time consuming hardware preparations.
84
The contents of struct :c:type:`v4l2_pix_format` and
85
struct :c:type:`v4l2_pix_format_mplane` are
86
discussed in :ref:`pixfmt`. See also the specification of the
87
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
88
details. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
89
and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
90
requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
91
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
93
Writing Images
94
==============
96
A video output device may support the :ref:`write() function <rw>`
97
and/or streaming (:ref:`memory mapping <mmap>` or
98
:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
출력 장치, capability와 보조 기능
1-44비디오 출력 장치는 정지 영상이나 image sequence를 analog video signal로 encode합니다. 이 인터페이스로 애플리케이션은 encoding 과정을 제어하고 사용자 공간의 영상을 driver로 전달합니다.
관례적으로 V4L2 video output 장치는 major 81, minor 0부터 63인 `/dev/video`, `/dev/video0`부터 `/dev/video63` character device로 접근합니다. `/dev/video`는 보통 선호 video device의 symbolic link이며 같은 이름을 video capture 장치도 사용합니다.
output 장치는 `VIDIOC_QUERYCAP`이 반환하는 `struct v4l2_capability.capabilities`에 `V4L2_CAP_VIDEO_OUTPUT` 또는 `V4L2_CAP_VIDEO_OUTPUT_MPLANE`을 설정합니다. 보조 기능으로 `V4L2_CAP_VBI_OUTPUT` raw VBI output을 지원할 수 있습니다.
read/write 또는 streaming I/O 중 적어도 하나를 지원해야 하며 modulator와 audio output은 선택 사항입니다. 필요에 따라 audio output, modulator, control, cropping/scaling, streaming parameter ioctl을 지원하고, 모든 output 장치는 video output ioctl을 반드시 지원해야 합니다.
항목설명
V4L2_CAP_VIDEO_OUTPUTsingle-planar video output
V4L2_CAP_VIDEO_OUTPUT_MPLANEmulti-planar video output
V4L2_CAP_VBI_OUTPUT선택적인 raw VBI output
필수 I/Oread/write 또는 streaming 중 적어도 하나
선택 기능modulator와 audio output
필수 output 기능과 선택적 보조 기능입니다.
VIDIOC_QUERYCAP 호출→VIDEO_OUTPUT 또는 VIDEO_OUTPUT_MPLANE 확인→read/write 또는 streaming 방식 확인→필요한 VBI, audio, modulator, control 확인→video output ioctl 지원 확인
장치 node에서 출력 경로와 보조 기능을 확인합니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _output:
**********************
Video Output Interface
**********************
Video output devices encode stills or image sequences as analog video
signal. With this interface applications can control the encoding
process and move images from user space to the driver.
Conventionally V4L2 video output devices are accessed through character
device special files named ``/dev/video`` and ``/dev/video0`` to
``/dev/video63`` with major number 81 and minor numbers 0 to 63.
``/dev/video`` is typically a symbolic link to the preferred video
device.
.. note:: The same device file names are used also for video capture devices.
Querying Capabilities
=====================
Devices supporting the video output interface set the
``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in
the ``capabilities`` field of struct
:c:type:`v4l2_capability` returned by the
:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
functions they may also support the :ref:`raw VBI output <raw-vbi>`
(``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or
streaming I/O methods must be supported. Modulators and audio outputs
are optional.
Supplemental Functions
======================
Video output devices shall support :ref:`audio output <audio>`,
:ref:`modulator <tuner>`, :ref:`controls <control>`,
:ref:`cropping and scaling <crop>` and
:ref:`streaming parameter <streaming-par>` ioctls as needed. The
:ref:`video output <video>` ioctls must be supported by all video
output devices.
Crop과 image format의 공동 협상
45-61출력 결과는 cropping parameter와 image format parameter가 함께 결정합니다. cropping은 video picture에서 영상이 나타날 영역을 고르고, image format은 RGB/YUV, pixel당 bit 수, width와 height 등 memory 내 저장 방식을 정합니다. 두 설정이 처리 중 scaling도 함께 정의합니다.
Unix tool chain이 장치를 설정한 뒤 일반 파일처럼 쓸 수 있도록 이 parameter는 `open()` 때 초기화되지 않습니다. 따라서 V4L2 애플리케이션은 cropping과 scaling을 포함해 실제로 원하는 설정을 얻었는지 스스로 확인해야 합니다.
cropping 초기화에는 최소한 parameter를 기본값으로 되돌리는 작업이 필요하며 예제는 `crop` 절에 있습니다.
Image format으로 memory layout 선택→Crop으로 outgoing signal의 표시 영역 선택→두 rectangle 크기로 scaling 결정→open 이후 유지된 실제값 재확인
memory image와 outgoing video 영역의 관계입니다.
Image Format Negotiation
========================
The output is determined by cropping and image format parameters. The
former select an area of the video picture where the image will appear,
the latter how images are stored in memory, i. e. in RGB or YUV format,
the number of bits per pixel or width and height. Together they also
define how images are scaled in the process.
As usual these parameters are *not* reset at :c:func:`open()`
time to permit Unix tool chains, programming a device and then writing
to it as if it was a plain file. Well written V4L2 applications ensure
they really get what they want, including cropping and scaling.
Cropping initialization at minimum requires to reset the parameters to
defaults. An example is given in :ref:`crop`.
G_FMT, S_FMT와 TRY_FMT
62-92현재 image format을 조회하려면 `struct v4l2_format.type`을 `V4L2_BUF_TYPE_VIDEO_OUTPUT` 또는 `V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`으로 설정하고 `VIDIOC_G_FMT`를 호출합니다. driver는 `fmt` union의 `struct v4l2_pix_format pix` 또는 `struct v4l2_pix_format_mplane pix_mp`를 채웁니다.
다른 parameter를 요청하려면 같은 type을 설정하고 관련 `struct v4l2_pix_format` 필드를 모두 초기화하거나, 더 좋은 방법으로 G_FMT 결과에서 필요한 필드만 수정해 `VIDIOC_S_FMT`를 호출합니다. 로컬 원문은 이 문장의 union 멤버를 `vbi`로 표기합니다. driver는 요청을 조정하고 G_FMT와 같은 실제 parameter를 반환합니다.
`VIDIOC_TRY_FMT`는 I/O를 중지하거나 시간이 걸리는 하드웨어 준비를 하지 않고 S_FMT처럼 하드웨어 한계를 확인하는 데 사용할 수 있습니다.
`struct v4l2_pix_format`과 `struct v4l2_pix_format_mplane`은 `pixfmt` 절에서 설명합니다. output 장치는 요청을 모두 무시하고 기본값만 반환하더라도 G_FMT와 S_FMT를 반드시 구현해야 하며 TRY_FMT는 선택 사항입니다.
항목설명
VIDIOC_G_FMT현재 실제 output format 조회, 필수
VIDIOC_S_FMT새 output format 요청과 조정값 반환, 필수
VIDIOC_TRY_FMTstate를 바꾸지 않는 format 시험, 선택
pixsingle-planar v4l2_pix_format
pix_mpmulti-planar v4l2_pix_format_mplane
조회, 적용, 비파괴 시험의 구현 의무입니다.
type에 VIDEO_OUTPUT 또는 VIDEO_OUTPUT_MPLANE 지정→VIDIOC_G_FMT로 현재값 조회→필요한 pix/pix_mp 필드 수정→VIDIOC_S_FMT로 요청→driver가 반환한 조정값 확인
현재값을 수정해 실제 지원 format을 확정합니다.
To query the current image format applications set the ``type`` field of
a struct :c:type:`v4l2_format` to
``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
and call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer
to this structure. Drivers fill the struct
:c:type:`v4l2_pix_format` ``pix`` or the struct
:c:type:`v4l2_pix_format_mplane` ``pix_mp``
member of the ``fmt`` union.
To request different parameters applications set the ``type`` field of a
struct :c:type:`v4l2_format` as above and initialize all
fields of the struct :c:type:`v4l2_pix_format`
``vbi`` member of the ``fmt`` union, or better just modify the results
of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
ioctl with a pointer to this structure. Drivers may adjust the
parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
does.
Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
can be used to learn about hardware limitations without disabling I/O or
possibly time consuming hardware preparations.
The contents of struct :c:type:`v4l2_pix_format` and
struct :c:type:`v4l2_pix_format_mplane` are
discussed in :ref:`pixfmt`. See also the specification of the
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
details. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
write와 streaming I/O
93-98비디오 출력 장치는 `write()` 함수와 streaming I/O 가운데 하나 이상을 지원할 수 있습니다. streaming 방식에는 memory mapping과 user pointer가 포함되며 세부 buffer 절차는 `io` 절을 참조합니다.
항목설명
write()write 함수로 image data 전달
Memory mappingmapping된 streaming buffer 사용
User pointer애플리케이션 buffer 주소를 제공
userspace에서 driver로 image를 보내는 경로입니다.
Writing Images
==============
A video output device may support the :ref:`write() function <rw>`
and/or streaming (:ref:`memory mapping <mmap>` or
:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
요약·해설
dev-output.rst:1-98Video output은 userspace image를 outgoing signal로 encode합니다. 장치 설정이 open 때 초기화되지 않으므로 crop과 format의 반환값을 명시적으로 검증해야 합니다.