VIDIOC_G_FMT·VIDIOC_S_FMT·VIDIOC_TRY_FMT ioctl

목적, 호출 형식과 인자

`VIDIOC_G_FMT`, `VIDIOC_S_FMT`, `VIDIOC_TRY_FMT`는 드라이버와 애플리케이션 사이에서 교환하는 데이터 형식, 일반적으로 영상 형식을 조회·설정하거나 시험합니다.

세 ioctl은 모두 `struct v4l2_format *argp`를 받습니다. `fd`는 `open()`이 반환한 파일 디스크립터이고, `argp`는 stream type과 해당 형식 구조체를 담은 `v4l2_format`을 가리킵니다.

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

.. _VIDIOC_G_FMT:

************************************************
ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
************************************************

Name
====

VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format

Synopsis
========

.. c:macro:: VIDIOC_G_FMT

``int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)``

.. c:macro:: VIDIOC_S_FMT

``int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)``

.. c:macro:: VIDIOC_TRY_FMT

``int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)``

Arguments
=========

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

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

현재 형식 조회

현재 매개변수를 조회하려면 `v4l2_format.type`을 대상 buffer 또는 stream type으로 설정합니다. 영상 캡처 장치는 예를 들어 `V4L2_BUF_TYPE_VIDEO_CAPTURE` 또는 `V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`을 사용합니다.

`VIDIOC_G_FMT`를 호출하면 드라이버가 `fmt` union의 대응 멤버를 채웁니다. 단일 plane 영상 캡처에서는 `struct v4l2_pix_format pix`, multi-planar 캡처에서는 `struct v4l2_pix_format_mplane pix_mp`입니다.

요청한 buffer type을 장치가 지원하지 않으면 `EINVAL`을 반환합니다. union 멤버는 반드시 `type`에 대응하는 형식으로 해석해야 합니다.

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

These ioctls are used to negotiate the format of data (typically image
format) exchanged between driver and application.

To query the current parameters applications set the ``type`` field of a
struct :c:type:`v4l2_format` to the respective buffer (stream)
type. For example video capture devices use
``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this structure the driver fills
the respective member of the ``fmt`` union. In case of video capture
devices that is either the struct
:c:type:`v4l2_pix_format` ``pix`` or the struct
:c:type:`v4l2_pix_format_mplane` ``pix_mp``
member. When the requested buffer type is not supported drivers return
an ``EINVAL`` error code.

형식 설정과 상태 없는 시험

현재 형식을 바꾸려면 `type`과 그 type에 대응하는 `fmt` union 멤버의 모든 필드를 초기화합니다. 먼저 현재 매개변수를 조회하고 애플리케이션에 맞지 않는 값만 수정하는 방식이 권장됩니다.

`VIDIOC_S_FMT`를 호출하면 드라이버는 하드웨어 능력에 맞춰 값을 검사하고 조정합니다. `type`이 잘못된 경우 외에는 되도록 오류를 반환하지 않아야 하며, 이 조정 과정으로 양쪽이 받아들일 수 있는 매개변수와 장치 한계를 탐색합니다.

성공한 S_FMT는 하드웨어를 프로그램하고 자원을 할당해 데이터 교환을 준비할 수 있습니다. 마지막에는 G_FMT와 같은 현재 형식 매개변수를 구조체에 반환합니다. 단순하고 유연하지 않은 장치는 입력을 모두 무시하고 기본값만 반환할 수도 있습니다.

애플리케이션과 데이터를 교환하는 모든 V4L2 장치는 G_FMT와 S_FMT를 구현해야 합니다. S_FMT에서 지원하지 않는 buffer type은 `EINVAL`, I/O 진행 중이거나 자원을 사용할 수 없으면 `EBUSY`입니다.

`VIDIOC_TRY_FMT`는 드라이버 상태를 바꾸지 않는다는 점을 제외하면 S_FMT와 같습니다. 언제든 호출할 수 있고 `EBUSY`를 반환하지 않으며, I/O를 중단하거나 시간이 오래 걸리는 하드웨어 준비 없이 형식을 협상하고 하드웨어 한계를 확인합니다.

TRY_FMT 구현은 강력히 권장되지만 의무는 아닙니다. 구현된 경우 동일한 입력 또는 출력에 대해 TRY_FMT가 반환하는 형식은 S_FMT의 반환 형식과 반드시 같아야 합니다.

To change the current format parameters applications initialize the
``type`` field and all fields of the respective ``fmt`` union member.
For details see the documentation of the various devices types in
:ref:`devices`. Good practice is to query the current parameters
first, and to modify only those parameters not suitable for the
application. When the application calls the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
a pointer to a struct :c:type:`v4l2_format` structure the driver
checks and adjusts the parameters against hardware abilities. Drivers
should not return an error code unless the ``type`` field is invalid,
this is a mechanism to fathom device capabilities and to approach
parameters acceptable for both the application and driver. On success
the driver may program the hardware, allocate resources and generally
prepare for data exchange. Finally the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl returns
the current format parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Very simple,
inflexible devices may even ignore all input and always return the
default parameters. However all V4L2 devices exchanging data with the
application must implement the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
ioctl. When the requested buffer type is not supported drivers return an
EINVAL error code on a :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` attempt. When I/O is already in
progress or the resource is not available for other reasons drivers
return the ``EBUSY`` error code.

The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` with one
exception: it does not change driver state. It can also be called at any
time, never returning ``EBUSY``. This function is provided to negotiate
parameters, to learn about hardware limitations, without disabling I/O
or possibly time consuming hardware preparations. Although strongly
recommended drivers are not required to implement this ioctl.

The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output.

struct v4l2_format

`v4l2_format.type`은 `enum v4l2_buf_type`의 데이터 stream type입니다. 익명 union `fmt`에서는 이 type에 대응하는 멤버 하나만 유효합니다.

`pix`와 `pix_mp`는 같은 영상 목적이지만 각각 single-planar와 multi-planar API에 대응합니다. `win`, `vbi`, `sliced`, `sdr`, `meta`는 서로 다른 stream type의 배치와 매개변수를 정의하므로 type을 바꿀 때 union 내용도 전부 다시 초기화해야 합니다.

.. c:type:: v4l2_format

.. tabularcolumns::  |p{7.4cm}|p{4.4cm}|p{5.5cm}|

.. flat-table:: struct v4l2_format
    :header-rows:  0
    :stub-columns: 0

    * - __u32
      - ``type``
      - Type of the data stream, see :c:type:`v4l2_buf_type`.
    * - union {
      - ``fmt``
    * - struct :c:type:`v4l2_pix_format`
      - ``pix``
      - Definition of an image format, see :ref:`pixfmt`, used by video
	capture and output devices.
    * - struct :c:type:`v4l2_pix_format_mplane`
      - ``pix_mp``
      - Definition of an image format, see :ref:`pixfmt`, used by video
	capture and output devices that support the
	:ref:`multi-planar version of the API <planar-apis>`.
    * - struct :c:type:`v4l2_window`
      - ``win``
      - Definition of an overlaid image, see :ref:`overlay`, used by
	video overlay devices.
    * - struct :c:type:`v4l2_vbi_format`
      - ``vbi``
      - Raw VBI capture or output parameters. This is discussed in more
	detail in :ref:`raw-vbi`. Used by raw VBI capture and output
	devices.
    * - struct :c:type:`v4l2_sliced_vbi_format`
      - ``sliced``
      - Sliced VBI capture or output parameters. See :ref:`sliced` for
	details. Used by sliced VBI capture and output devices.
    * - struct :c:type:`v4l2_sdr_format`
      - ``sdr``
      - Definition of a data format, see :ref:`pixfmt`, used by SDR
	capture and output devices.
    * - struct :c:type:`v4l2_meta_format`
      - ``meta``
      - Definition of a metadata format, see :ref:`meta-formats`, used by
	metadata capture devices.
    * - __u8
      - ``raw_data``\ [200]
      - Place holder for future extensions.
    * - }
      -

반환값과 오류

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 설정하며, 아래 전용 오류 외에도 Generic Error Codes 장의 공통 오류가 적용됩니다.

TRY_FMT는 어떤 시점에도 상태를 바꾸지 않고 호출할 수 있으므로 `EBUSY`를 반환하지 않습니다. S_FMT의 `EBUSY`가 예상되면 TRY_FMT로 먼저 최종 조정 형식을 확인할 수 있습니다.

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_format` ``type`` field is
    invalid or the requested buffer type not supported.

EBUSY
    The device is busy and cannot change the format. This could be
    because or the device is streaming or buffers are allocated or
    queued to the driver. Relevant for :ref:`VIDIOC_S_FMT
    <VIDIOC_G_FMT>` only.