VIDIOC_SUBDEV_G_FMT 및 VIDIOC_SUBDEV_S_FMT ioctl

목적, 호출 형식과 인자

`VIDIOC_SUBDEV_G_FMT`과 `VIDIOC_SUBDEV_S_FMT`은 이미지 파이프라인의 특정 서브디바이스 pad에서 프레임 형식을 협상합니다. `argp`는 `struct v4l2_subdev_format`을 가리킵니다.

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

.. _VIDIOC_SUBDEV_G_FMT:

**********************************************
ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
**********************************************

Name
====

VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad

Synopsis
========

.. c:macro:: VIDIOC_SUBDEV_G_FMT

``int ioctl(int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp)``

.. c:macro:: VIDIOC_SUBDEV_S_FMT

``int ioctl(int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp)``

Arguments
=========

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

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

형식 조회·설정과 TRY 협상

현재 형식을 조회하려면 `pad`를 원하는 pad 번호로, `which`를 `V4L2_SUBDEV_FORMAT_ACTIVE`로 설정하고 G_FMT을 호출합니다. 드라이버는 `format` 필드를 채웁니다.

형식을 바꾸려면 `pad`, `which`, `format`의 모든 멤버를 설정해 S_FMT을 호출합니다. 드라이버는 요청을 하드웨어 capability에 맞게 가장 가까운 지원 형식으로 조정하고 장치를 구성한 뒤, 현재 형식을 구조체에 되돌려 줍니다.

`which = V4L2_SUBDEV_FORMAT_TRY`이면 실제 장치에는 적용하지 않고 ACTIVE와 같은 조정 규칙으로 계산한 결과를 파일 핸들에 저장합니다. 파일 핸들마다 try 상태가 분리되므로 두 응용 프로그램이 서로 간섭하지 않습니다.

출력 pad의 형식을 시험하려면 먼저 입력 pad에 S_FMT으로 try 형식을 설정합니다. 이어서 출력 pad의 기본 try 형식을 G_FMT으로 읽거나 원하는 출력 형식을 S_FMT으로 설정한 뒤 반환값을 확인합니다.

Try format은 active format에 의존하지 않지만 현재 링크 구성과 서브디바이스 control 값에는 의존할 수 있습니다. 예를 들어 저역 통과 잡음 필터가 경계 픽셀을 잘라 출력 크기를 바꿀 수 있습니다.

읽기 전용 노드의 S_FMT은 TRY에만 허용되며 ACTIVE 요청은 `EPERM`입니다. 단순히 요청 형식이 capability와 맞지 않는 경우에는 오류 대신 가장 가까운 지원 형식으로 수정해야 합니다.

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

These ioctls are used to negotiate the frame format at specific subdev
pads in the image pipeline.

To retrieve the current format applications set the ``pad`` field of a
struct :c:type:`v4l2_subdev_format` to the desired
pad number as reported by the media API and the ``which`` field to
``V4L2_SUBDEV_FORMAT_ACTIVE``. When they call the
``VIDIOC_SUBDEV_G_FMT`` ioctl with a pointer to this structure the
driver fills the members of the ``format`` field.

To change the current format applications set both the ``pad`` and
``which`` fields and all members of the ``format`` field. When they call
the ``VIDIOC_SUBDEV_S_FMT`` ioctl with a pointer to this structure the
driver verifies the requested format, adjusts it based on the hardware
capabilities and configures the device. Upon return the struct
:c:type:`v4l2_subdev_format` contains the current
format as would be returned by a ``VIDIOC_SUBDEV_G_FMT`` call.

Applications can query the device capabilities by setting the ``which``
to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' formats are not applied
to the device by the driver, but are changed exactly as active formats
and stored in the sub-device file handle. Two applications querying the
same sub-device would thus not interact with each other.

For instance, to try a format at the output pad of a sub-device,
applications would first set the try format at the sub-device input with
the ``VIDIOC_SUBDEV_S_FMT`` ioctl. They would then either retrieve the
default format at the output pad with the ``VIDIOC_SUBDEV_G_FMT`` ioctl,
or set the desired output pad format with the ``VIDIOC_SUBDEV_S_FMT``
ioctl and check the returned value.

Try formats do not depend on active formats, but can depend on the
current links configuration or sub-device controls value. For instance,
a low-pass noise filter might crop pixels at the frame boundaries,
modifying its output frame size.

If the subdev device node has been registered in read-only mode, calls to
``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
variable is set to ``-EPERM``.

Drivers must not return an error solely because the requested format
doesn't match the device capabilities. They must instead modify the
format to match what the hardware can provide. The modified format
should be as close as possible to the original request.

구조체와 format whence

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

.. c:type:: v4l2_subdev_format

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

    * - __u32
      - ``pad``
      - Pad number as reported by the media controller API.
    * - __u32
      - ``which``
      - Format to modified, from enum
	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
    * - struct :c:type:`v4l2_mbus_framefmt`
      - ``format``
      - Definition of an image format, see :c:type:`v4l2_mbus_framefmt` for
	details.
    * - __u32
      - ``stream``
      - Stream identifier.
    * - __u32
      - ``reserved``\ [7]
      - Reserved for future extensions. Applications and drivers must set
	the array to zero.


.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _v4l2-subdev-format-whence:

.. flat-table:: enum v4l2_subdev_format_whence
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - V4L2_SUBDEV_FORMAT_TRY
      - 0
      - Try formats, used for querying device capabilities.
    * - V4L2_SUBDEV_FORMAT_ACTIVE
      - 1
      - Active formats, applied to the hardware.

반환값, 오류와 원문 중복 문단

성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다. 원문 150~154행에는 같은 일반 반환 설명이 반복되어 있으며, 이 전문 번역 페이지에서도 해당 원문과 줄 좌표를 그대로 보존합니다.

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.

EBUSY
    The format can't be changed because the pad is currently busy. This
    can be caused, for instance, by an active video stream on the pad.
    The ioctl must not be retried without performing another action to
    fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT``

EINVAL
    The struct :c:type:`v4l2_subdev_format` ``pad`` references a non-existing
    pad, or the ``which`` field has an unsupported value.

EPERM
    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.

============

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.