비디오 캡처 인터페이스

캡처 기능과 장치 파일

비디오 캡처 장치는 아날로그 비디오 신호를 샘플링하고 디지털화한 영상을 메모리에 저장합니다. 오늘날 거의 모든 장치는 초당 25 또는 30 frame의 전체 속도로 캡처할 수 있습니다. 이 인터페이스를 사용하면 애플리케이션이 캡처 과정을 제어하고 드라이버의 영상을 사용자 공간으로 옮길 수 있습니다.

관례적으로 V4L2 비디오 캡처 장치는 major 번호 81, minor 번호 0부터 63까지인 character device 특수 파일 `/dev/video`, `/dev/video0`부터 `/dev/video63`을 통해 접근합니다. `/dev/video`는 보통 선호하는 비디오 장치를 가리키는 symbolic link입니다.

비디오 출력 장치도 동일한 장치 파일 이름을 사용한다는 점에 유의해야 합니다. 파일 이름만으로 캡처 장치와 출력 장치를 구별할 수 없습니다.

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

.. _capture:

***********************
Video Capture Interface
***********************

Video capture devices sample an analog video signal and store the
digitized images in memory. Today nearly all devices can capture at full
25 or 30 frames/second. With this interface applications can control the
capture process and move images from the driver into user space.

Conventionally V4L2 video capture 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 for video output devices.

capability 조회와 보조 기능

비디오 캡처 인터페이스를 지원하는 장치는 `VIDIOC_QUERYCAP` ioctl이 반환하는 `struct v4l2_capability`의 `capabilities` 필드에 `V4L2_CAP_VIDEO_CAPTURE` 또는 `V4L2_CAP_VIDEO_CAPTURE_MPLANE` flag를 설정합니다.

장치는 보조 기능으로 video overlay의 `V4L2_CAP_VIDEO_OVERLAY`와 raw VBI capture의 `V4L2_CAP_VBI_CAPTURE` 인터페이스도 지원할 수 있습니다. read/write 또는 streaming I/O 방식 가운데 적어도 하나는 반드시 지원해야 하며 tuner와 audio input은 선택 사항입니다.

비디오 캡처 장치는 필요에 따라 audio input, tuner, control, cropping과 scaling, streaming parameter ioctl을 지원해야 합니다. 모든 비디오 캡처 장치는 video input ioctl을 반드시 지원해야 합니다.

Querying Capabilities
=====================

Devices supporting the video capture interface set the
``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_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:`video overlay <overlay>`
(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>`
(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or
streaming I/O methods must be supported. Tuners and audio inputs are
optional.

Supplemental Functions
======================

Video capture devices shall support :ref:`audio input <audio>`,
:ref:`tuner`, :ref:`controls <control>`,
:ref:`cropping and scaling <crop>` and
:ref:`streaming parameter <streaming-par>` ioctls as needed. The
:ref:`video input <video>` ioctls must be supported by all video
capture devices.

crop과 영상 형식의 공동 협상

캡처 결과는 cropping parameter와 image format parameter가 함께 결정합니다. cropping은 비디오 화면에서 캡처할 영역을 고르고, image format은 RGB 또는 YUV 형식, pixel당 bit 수, 폭과 높이처럼 영상이 메모리에 저장되는 방식을 정합니다. 두 parameter는 처리 과정의 scaling 방식도 함께 정의합니다.

Unix 도구 체인이 장치를 설정한 뒤 일반 파일처럼 읽을 수 있게 하려면 이 parameter들을 `open()` 시점에 초기화해서는 안 됩니다. 따라서 제대로 작성된 V4L2 애플리케이션은 cropping과 scaling을 포함해 실제로 원하는 설정을 얻었는지 스스로 확인해야 합니다.

cropping 초기화에는 최소한 parameter를 기본값으로 되돌리는 과정이 필요하며, 구체적인 예는 `crop` 절에 제시되어 있습니다.

Image Format Negotiation
========================

The result of a capture operation is determined by cropping and image
format parameters. The former select an area of the video picture to
capture, 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 reading
from 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

현재 영상 형식을 조회하려면 애플리케이션은 `struct v4l2_format`의 `type`을 `V4L2_BUF_TYPE_VIDEO_CAPTURE` 또는 `V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`으로 설정하고 구조체 포인터와 함께 `VIDIOC_G_FMT`를 호출합니다. 드라이버는 `fmt` union의 `struct v4l2_pix_format pix` 또는 `struct v4l2_pix_format_mplane pix_mp` 멤버를 채웁니다.

다른 parameter를 요청하려면 같은 방식으로 `type`을 설정하고 `fmt` union의 `struct v4l2_pix_format` 관련 필드를 모두 초기화하거나, 더 좋은 방법으로 `VIDIOC_G_FMT` 결과에서 필요한 필드만 수정한 뒤 구조체 포인터와 함께 `VIDIOC_S_FMT`를 호출합니다. 로컬 원문은 이 대목의 union 멤버 이름을 `vbi`로 표기합니다. 드라이버는 요청값을 조정할 수 있으며 최종적으로 `VIDIOC_G_FMT`와 같은 형태의 실제 parameter를 돌려줍니다.

`VIDIOC_TRY_FMT`는 I/O를 중지하거나 시간이 걸릴 수 있는 하드웨어 준비를 수행하지 않고도 `VIDIOC_S_FMT`처럼 하드웨어 한계를 시험하는 데 사용할 수 있습니다.

`struct v4l2_pix_format`과 `struct v4l2_pix_format_mplane`의 내용은 `pixfmt` 절에서 설명합니다. 비디오 캡처 장치는 요청을 모두 무시하고 항상 기본값만 반환하더라도 `VIDIOC_G_FMT`와 `VIDIOC_S_FMT`를 모두 구현해야 합니다. `VIDIOC_TRY_FMT` 구현은 선택 사항입니다.

To query the current image format applications set the ``type`` field of
a struct :c:type:`v4l2_format` to
``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
``V4L2_BUF_TYPE_VIDEO_CAPTURE_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 capture 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.

read와 streaming I/O

비디오 캡처 장치는 `read()` 함수와 streaming I/O 가운데 하나 이상을 지원할 수 있습니다. streaming 방식에는 memory mapping과 user pointer 방식이 포함됩니다.

각 데이터 전송 방식의 buffer 준비, queue 처리와 동기화에 관한 세부 사항은 `io` 절을 참조해야 합니다.

Reading Images
==============

A video capture device may support the :ref:`read() function <func-read>`
and/or streaming (:ref:`memory mapping <func-mmap>` or
:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.