VIDIOC_ENUM_FRAMESIZES ioctl

목적, 호출 형식과 인자

`VIDIOC_ENUM_FRAMESIZES`는 지정한 pixel format에 대해 장치가 지원하는 모든 frame size, 즉 픽셀 단위의 너비와 높이를 열거하는 ioctl입니다. 호출 형식은 `int ioctl(int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp)`입니다.

`fd`는 `open()`이 반환한 파일 디스크립터입니다. `argp`는 응용 프로그램이 `index`와 pixel format을 넣고 드라이버로부터 frame width와 height를 돌려받는 `struct v4l2_frmsizeenum`을 가리킵니다.

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

.. _VIDIOC_ENUM_FRAMESIZES:

****************************
ioctl VIDIOC_ENUM_FRAMESIZES
****************************

Name
====

VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes

Synopsis
========

.. c:macro:: VIDIOC_ENUM_FRAMESIZES

``int ioctl(int fd, VIDIOC_ENUM_FRAMESIZES, struct v4l2_frmsizeenum *argp)``

Arguments
=========

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

``argp``
    Pointer to struct :c:type:`v4l2_frmsizeenum`
    that contains an index and pixel format and receives a frame width
    and height.

열거 방식과 일관성

지원 pixel format은 `VIDIOC_ENUM_FMT`로 먼저 얻습니다. 이 ioctl의 반환 방식과 `v4l2_frmsizeenum.type`은 장치가 지원하는 frame size 표현 유형에 따라 달라집니다.

응용 프로그램은 `index` 0으로 처음 호출한 뒤 `type`을 확인해야 합니다. 더 많은 크기를 얻기 위해 index를 증가시키는 방식은 `V4L2_FRMSIZE_TYPE_DISCRETE`에서만 의미가 있습니다.

frame size가 반환되는 순서에는 특별한 의미가 없으며 잠재적인 기본 format size를 나타내지도 않습니다. 응용 프로그램이 열거 중 다른 ioctl을 호출하지 않으면 열거 데이터는 스스로 바뀌지 않으므로 일관된 결과를 가정할 수 있습니다.

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

This ioctl allows applications to enumerate all frame sizes (i. e. width
and height in pixels) that the device supports for the given pixel
format.

The supported pixel formats can be obtained by using the
:ref:`VIDIOC_ENUM_FMT` function.

The return value and the content of the ``v4l2_frmsizeenum.type`` field
depend on the type of frame sizes the device supports. Here are the
semantics of the function for the different cases:

-  **Discrete:** The function returns success if the given index value
   (zero-based) is valid. The application should increase the index by
   one for each call until ``EINVAL`` is returned. The
   ``v4l2_frmsizeenum.type`` field is set to
   ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the
   ``discrete`` member is valid.

-  **Step-wise:** The function returns success if the given index value
   is zero and ``EINVAL`` for any other index value. The
   ``v4l2_frmsizeenum.type`` field is set to
   ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the
   ``stepwise`` member is valid.

-  **Continuous:** This is a special case of the step-wise type above.
   The function returns success if the given index value is zero and
   ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type``
   field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of
   the union only the ``stepwise`` member is valid and the
   ``step_width`` and ``step_height`` values are set to 1.

When the application calls the function with index zero, it must check
the ``type`` field to determine the type of frame size enumeration the
device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
it make sense to increase the index value to receive more frame sizes.

.. note::

   The order in which the frame sizes are returned has no special
   meaning. In particular does it not say anything about potential default
   format sizes.

Applications can assume that the enumeration data does not change
without any interaction from the application itself. This means that the
enumeration data is consistent if the application does not perform any
other ioctl calls while it runs the frame size enumeration.

v4l2_frmsize_discrete 구조체

아래 구조체에서 IN은 응용 프로그램이 채우는 값, OUT은 드라이버가 채우는 값입니다. 응용 프로그램은 IN 필드를 제외한 모든 멤버를 0으로 초기화해야 합니다. `v4l2_frmsize_discrete`는 한 개의 고정 frame size를 나타냅니다.

Structs
=======

In the structs below, *IN* denotes a value that has to be filled in by
the application, *OUT* denotes values that the driver fills in. The
application should zero out all members except for the *IN* fields.

.. c:type:: v4l2_frmsize_discrete

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

    * - __u32
      - ``width``
      - Width of the frame [pixel].
    * - __u32
      - ``height``
      - Height of the frame [pixel].

v4l2_frmsize_stepwise 구조체

Step-wise 유형에서 유효한 크기는 각 축의 최소값부터 최대값까지 해당 step의 배수로 증가하는 조합입니다. Continuous 유형은 같은 구조체를 사용하되 두 step 값이 모두 1이므로 범위 안의 모든 정수 픽셀 크기를 표현합니다.

.. c:type:: v4l2_frmsize_stepwise

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

    * - __u32
      - ``min_width``
      - Minimum frame width [pixel].
    * - __u32
      - ``max_width``
      - Maximum frame width [pixel].
    * - __u32
      - ``step_width``
      - Frame width step size [pixel].
    * - __u32
      - ``min_height``
      - Minimum frame height [pixel].
    * - __u32
      - ``max_height``
      - Maximum frame height [pixel].
    * - __u32
      - ``step_height``
      - Frame height step size [pixel].

v4l2_frmsizeenum 구조체

`type`이 선택한 union 멤버만 유효합니다. Discrete에서는 `discrete`, Step-wise와 Continuous에서는 `stepwise`를 읽어야 하며, 예약 필드는 호출 전후 모두 0 규칙을 지켜야 합니다.

.. c:type:: v4l2_frmsizeenum

.. tabularcolumns:: |p{6.4cm}|p{2.8cm}|p{8.1cm}|

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

    * - __u32
      - ``index``
      - IN: Index of the given frame size in the enumeration.
    * - __u32
      - ``pixel_format``
      - IN: Pixel format for which the frame sizes are enumerated.
    * - __u32
      - ``type``
      - OUT: Frame size type the device supports.
    * - union {
      - (anonymous)
      - OUT: Frame size with the given index.
    * - struct :c:type:`v4l2_frmsize_discrete`
      - ``discrete``
      -
    * - struct :c:type:`v4l2_frmsize_stepwise`
      - ``stepwise``
      -
    * - }
      -
      -
    * - __u32
      - ``reserved[2]``
      - Reserved space for future use. Must be zeroed by drivers and
	applications.

v4l2_frmsizetypes 열거형

Enums
=====

.. c:type:: v4l2_frmsizetypes

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

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

    * - ``V4L2_FRMSIZE_TYPE_DISCRETE``
      - 1
      - Discrete frame size.
    * - ``V4L2_FRMSIZE_TYPE_CONTINUOUS``
      - 2
      - Continuous frame size.
    * - ``V4L2_FRMSIZE_TYPE_STEPWISE``
      - 3
      - Step-wise defined frame size.

반환값

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 적절한 값으로 설정하며, 공통 오류 코드는 Generic Error Codes 장을 따릅니다. 열거 종료 또는 유형별로 허용되지 않는 index에서 반환되는 `EINVAL`을 정상적인 반복 종료 조건으로 처리해야 합니다.

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.