VIDIOC_ENUMOUTPUT ioctl

목적, 호출 형식과 인자

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

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

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

.. _VIDIOC_ENUMOUTPUT:

***********************
ioctl VIDIOC_ENUMOUTPUT
***********************

Name
====

VIDIOC_ENUMOUTPUT - Enumerate video outputs

Synopsis
========

.. c:macro:: VIDIOC_ENUMOUTPUT

``int ioctl(int fd, VIDIOC_ENUMOUTPUT, struct v4l2_output *argp)``

Arguments
=========

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

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

비디오 출력 열거 절차

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

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

연속 열거에서 `EINVAL`은 더 이상 출력이 없다는 종료 표지이며, 특정 index를 직접 조회할 때는 요청한 순번이 유효하지 않다는 오류입니다.

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

To query the attributes of a video outputs applications initialize the
``index`` field of struct :c:type:`v4l2_output` and call
the :ref:`VIDIOC_ENUMOUTPUT` 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 outputs applications
shall begin at index zero, incrementing by one until the driver returns
``EINVAL``.

v4l2_output 구조체

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

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

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

`type`이 `V4L2_OUTPUT_TYPE_MODULATOR`이면 `modulator`는 `struct v4l2_modulator.index`와 같은 RF modulator 순번입니다. 관련 modulator 규칙은 `tuner` 문서에 정의됩니다.

`std`는 이 출력이 지원하는 비디오 표준 전체를 나타냅니다. 표준 전환 방법은 `standard` 문서를 따르며, `reserved[3]`은 드라이버가 반드시 0으로 반환해야 합니다.

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. c:type:: v4l2_output

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

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

	When the driver does not enumerate audio outputs no bits must be
	set. Applications shall not interpret this as lack of audio
	support. Drivers may automatically select audio outputs without
	enumerating them.

	For details on audio outputs and how to select the current output
	see :ref:`audio`.
    * - __u32
      - ``modulator``
      - Output devices can have zero or more RF modulators. When the
	``type`` is ``V4L2_OUTPUT_TYPE_MODULATOR`` this is an RF connector
	and this field identifies the modulator. It corresponds to struct
	:c:type:`v4l2_modulator` field ``index``. For
	details on modulators see :ref:`tuner`.
    * - :ref:`v4l2_std_id <v4l2-std-id>`
      - ``std``
      - Every video output 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
      - ``capabilities``
      - This field provides capabilities for the output. See
	:ref:`output-capabilities` for flags.
    * - __u32
      - ``reserved``\ [3]
      - Reserved for future extensions. Drivers must set the array to
	zero.

출력 유형

`V4L2_OUTPUT_TYPE_ANALOG`라는 이름은 역사적인 명칭입니다. HDMI도 이 유형에 포함되며, 현재 API를 새로 이름 붙였다면 `V4L2_OUTPUT_TYPE_VIDEO`에 가까운 의미입니다.

.. tabularcolumns:: |p{7.5cm}|p{0.6cm}|p{9.2cm}|

.. _output-type:

.. flat-table:: Output Type
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_OUTPUT_TYPE_MODULATOR``
      - 1
      - This output is an analog TV modulator.
    * - ``V4L2_OUTPUT_TYPE_ANALOG``
      - 2
      - Any non-modulator video output, for example Composite Video,
	S-Video, HDMI. The naming as ``_TYPE_ANALOG`` is historical,
	today we would have called it ``_TYPE_VIDEO``.
    * - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY``
      - 3
      - The video output will be copied to a :ref:`video overlay <overlay>`.

출력 기능 플래그

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

.. tabularcolumns:: |p{6.4cm}|p{2.4cm}|p{8.5cm}|

.. _output-capabilities:

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

    * - ``V4L2_OUT_CAP_DV_TIMINGS``
      - 0x00000002
      - This output supports setting video timings by using
	``VIDIOC_S_DV_TIMINGS``.
    * - ``V4L2_OUT_CAP_STD``
      - 0x00000004
      - This output supports setting the TV standard by using
	``VIDIOC_S_STD``.
    * - ``V4L2_OUT_CAP_NATIVE_SIZE``
      - 0x00000008
      - This output 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_output` ``index`` is out of
    bounds.