VIDIOC_ENUMINPUT ioctl

목적, 호출 형식과 인자

`VIDIOC_ENUMINPUT`은 비디오 입력을 열거하는 ioctl입니다. 호출 형식은 `int ioctl(int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp)`입니다.

`fd`는 `open()`이 반환한 파일 디스크립터이며, `argp`는 조회할 입력 순번과 드라이버가 반환하는 입력 속성을 담는 `struct v4l2_input`을 가리킵니다.

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

.. _VIDIOC_ENUMINPUT:

**********************
ioctl VIDIOC_ENUMINPUT
**********************

Name
====

VIDIOC_ENUMINPUT - Enumerate video inputs

Synopsis
========

.. c:macro:: VIDIOC_ENUMINPUT

``int ioctl(int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_input`.

비디오 입력 열거 절차

응용 프로그램은 `v4l2_input.index`에 조회할 입력 순번을 넣고 `VIDIOC_ENUMINPUT`을 호출합니다. 드라이버는 구조체의 나머지 필드를 채우며, 순번이 범위를 벗어나면 `EINVAL`을 반환합니다.

모든 입력을 조사하려면 index 0에서 시작해 한 번에 1씩 증가시키고, 드라이버가 `EINVAL`을 반환할 때 열거를 끝냅니다.

따라서 연속 열거 중의 `EINVAL`은 다음 입력이 없다는 정상적인 종료 표지로 사용할 수 있지만, 임의의 index를 조회할 때는 요청한 순번이 유효하지 않다는 오류입니다.

Description
===========

To query the attributes of a video input applications initialize the
``index`` field of struct :c:type:`v4l2_input` and call the
:ref:`VIDIOC_ENUMINPUT` with a pointer to this structure. Drivers
fill the rest of the structure or return an ``EINVAL`` error code when the
index is out of bounds. To enumerate all inputs applications shall begin
at index zero, incrementing by one until the driver returns ``EINVAL``.

v4l2_input 구조체

`name`은 `Vin (Composite 2)` 같은 NUL 종료 ASCII 문자열입니다. 사용자가 실제 단자를 식별할 수 있도록 장치에 인쇄된 커넥터 이름을 제공하는 것이 좋습니다.

`audioset`은 최대 32개의 오디오 입력과 비디오 입력 사이의 선택 가능 관계를 나타냅니다. 최하위 비트는 오디오 입력 0, 최상위 비트는 입력 31에 대응하며 비트가 여러 개 설정되거나 하나도 설정되지 않을 수 있습니다.

드라이버가 오디오 입력을 별도로 열거하지 않는다면 `audioset`의 모든 비트가 0이어야 합니다. 그러나 이를 오디오 미지원으로 해석해서는 안 됩니다. 선택지가 없어 오디오 소스를 자동으로 정하는 드라이버도 있기 때문입니다. 오디오 입력 조회와 현재 입력 선택은 `audio` 문서를 따릅니다.

`type`이 `V4L2_INPUT_TYPE_TUNER`이면 `tuner`는 `struct v4l2_tuner.index`와 같은 RF demodulator 순번입니다. `std`는 지원하는 비디오 표준 전체를 나타내며 표준 전환 방법은 `standard` 문서에 정의됩니다.

`status`의 센서 방향 비트는 입력 선택 여부와 관계없이 의미가 있지만, 그 밖의 상태 비트는 이 입력이 현재 입력일 때만 유효합니다. `reserved[3]`은 드라이버가 반드시 0으로 반환해야 합니다.

.. tabularcolumns:: |p{3.0cm}|p{3.5cm}|p{10.8cm}|

.. c:type:: v4l2_input

.. flat-table:: struct v4l2_input
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``index``
      - Identifies the input, set by the application.
    * - __u8
      - ``name``\ [32]
      - Name of the video input, a NUL-terminated ASCII string, for
	example: "Vin (Composite 2)". This information is intended for the
	user, preferably the connector label on the device itself.
    * - __u32
      - ``type``
      - Type of the input, see :ref:`input-type`.
    * - __u32
      - ``audioset``
      - Drivers can enumerate up to 32 video and audio inputs. This field
	shows which audio inputs were selectable as audio source if this
	was the currently selected video input. It is a bit mask. The LSB
	corresponds to audio input 0, the MSB to input 31. Any number of
	bits can be set, or none.

	When the driver does not enumerate audio inputs no bits must be
	set. Applications shall not interpret this as lack of audio
	support. Some drivers automatically select audio sources and do
	not enumerate them since there is no choice anyway.

	For details on audio inputs and how to select the current input
	see :ref:`audio`.
    * - __u32
      - ``tuner``
      - Capture devices can have zero or more tuners (RF demodulators).
	When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
	RF connector and this field identifies the tuner. It corresponds
	to struct :c:type:`v4l2_tuner` field ``index``. For
	details on tuners see :ref:`tuner`.
    * - :ref:`v4l2_std_id <v4l2-std-id>`
      - ``std``
      - Every video input supports one or more different video standards.
	This field is a set of all supported standards. For details on
	video standards and how to switch see :ref:`standard`.
    * - __u32
      - ``status``
      - This field provides status information about the input. See
	:ref:`input-status` for flags. With the exception of the sensor
	orientation bits ``status`` is only valid when this is the current
	input.
    * - __u32
      - ``capabilities``
      - This field provides capabilities for the input. See
	:ref:`input-capabilities` for flags.
    * - __u32
      - ``reserved``\ [3]
      - Reserved for future extensions. Drivers must set the array to
	zero.

입력 유형

`V4L2_INPUT_TYPE_CAMERA`라는 이름은 역사적인 명칭입니다. 현재 API를 새로 이름 붙였다면 `V4L2_INPUT_TYPE_VIDEO`에 가까운 의미이며 카메라 센서만 뜻하지 않습니다.

.. tabularcolumns:: |p{6.6cm}|p{1.0cm}|p{9.7cm}|

.. _input-type:

.. flat-table:: Input Types
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_INPUT_TYPE_TUNER``
      - 1
      - This input uses a tuner (RF demodulator).
    * - ``V4L2_INPUT_TYPE_CAMERA``
      - 2
      - Any non-tuner video input, for example Composite Video,
	S-Video, HDMI, camera sensor. The naming as ``_TYPE_CAMERA`` is historical,
	today we would have called it ``_TYPE_VIDEO``.
    * - ``V4L2_INPUT_TYPE_TOUCH``
      - 3
      - This input is a touch device for capturing raw touch data.

입력 상태 플래그

`V4L2_IN_ST_HFLIP | V4L2_IN_ST_VFLIP` 조합은 180도 회전과 같습니다. 이 두 비트는 신호를 userspace로 전달하기 전에 장치가 방향을 바로잡지 않았음을 알립니다.

`V4L2_IN_ST_COLOR_KILL`은 회로가 존재한다는 뜻만이 아닙니다. color killer가 활성화되어 있으며 색상 변조가 없다고 판단해 실제로 색상 디코딩을 껐다는 뜻입니다.

.. tabularcolumns:: |p{5.6cm}|p{2.6cm}|p{9.1cm}|

.. _input-status:

.. flat-table:: Input Status Flags
    :header-rows:  0
    :stub-columns: 0

    * - :cspan:`2` General
    * - ``V4L2_IN_ST_NO_POWER``
      - 0x00000001
      - Attached device is off.
    * - ``V4L2_IN_ST_NO_SIGNAL``
      - 0x00000002
      -
    * - ``V4L2_IN_ST_NO_COLOR``
      - 0x00000004
      - The hardware supports color decoding, but does not detect color
	modulation in the signal.
    * - :cspan:`2` Sensor Orientation
    * - ``V4L2_IN_ST_HFLIP``
      - 0x00000010
      - The input is connected to a device that produces a signal that is
	flipped horizontally and does not correct this before passing the
	signal to userspace.
    * - ``V4L2_IN_ST_VFLIP``
      - 0x00000020
      - The input is connected to a device that produces a signal that is
	flipped vertically and does not correct this before passing the
	signal to userspace.
	.. note:: A 180 degree rotation is the same as HFLIP | VFLIP
    * - :cspan:`2` Analog Video
    * - ``V4L2_IN_ST_NO_H_LOCK``
      - 0x00000100
      - No horizontal sync lock.
    * - ``V4L2_IN_ST_COLOR_KILL``
      - 0x00000200
      - A color killer circuit automatically disables color decoding when
	it detects no color modulation. When this flag is set the color
	killer is enabled *and* has shut off color decoding.
    * - ``V4L2_IN_ST_NO_V_LOCK``
      - 0x00000400
      - No vertical sync lock.
    * - ``V4L2_IN_ST_NO_STD_LOCK``
      - 0x00000800
      - No standard format lock in case of auto-detection format
	by the component.
    * - :cspan:`2` Digital Video
    * - ``V4L2_IN_ST_NO_SYNC``
      - 0x00010000
      - No synchronization lock.
    * - ``V4L2_IN_ST_NO_EQU``
      - 0x00020000
      - No equalizer lock.
    * - ``V4L2_IN_ST_NO_CARRIER``
      - 0x00040000
      - Carrier recovery failed.
    * - :cspan:`2` VCR and Set-Top Box
    * - ``V4L2_IN_ST_MACROVISION``
      - 0x01000000
      - Macrovision is an analog copy prevention system mangling the video
	signal to confuse video recorders. When this flag is set
	Macrovision has been detected.
    * - ``V4L2_IN_ST_NO_ACCESS``
      - 0x02000000
      - Conditional access denied.
    * - ``V4L2_IN_ST_VTR``
      - 0x04000000
      - VTR time constant. [?]

입력 기능 플래그

기능 비트는 해당 입력에서 사용할 설정 API를 고르는 기준입니다. native size 선택의 상세 규칙은 공통 V4L2 selection 문서를 따릅니다.

.. tabularcolumns:: |p{6.6cm}|p{2.4cm}|p{8.3cm}|

.. _input-capabilities:

.. flat-table:: Input capabilities
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_IN_CAP_DV_TIMINGS``
      - 0x00000002
      - This input supports setting video timings by using
	``VIDIOC_S_DV_TIMINGS``.
    * - ``V4L2_IN_CAP_STD``
      - 0x00000004
      - This input supports setting the TV standard by using
	``VIDIOC_S_STD``.
    * - ``V4L2_IN_CAP_NATIVE_SIZE``
      - 0x00000008
      - This input supports setting the native size using the
	``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
	:ref:`v4l2-selections-common`.

반환값과 EINVAL

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 적절한 값으로 설정하며, 공통 오류 코드는 Generic Error Codes 장을 따릅니다.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The struct :c:type:`v4l2_input` ``index`` is out of
    bounds.