VIDIOC_ENUM_FRAMEINTERVALS ioctl

목적, 호출 형식과 인자

`VIDIOC_ENUM_FRAMEINTERVALS`는 지정한 pixel format과 frame size에 대해 장치가 지원하는 모든 frame interval을 열거하는 ioctl입니다. 호출 형식은 `int ioctl(int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp)`입니다.

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

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

.. _VIDIOC_ENUM_FRAMEINTERVALS:

********************************
ioctl VIDIOC_ENUM_FRAMEINTERVALS
********************************

Name
====

VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals

Synopsis
========

.. c:macro:: VIDIOC_ENUM_FRAMEINTERVALS

``int ioctl(int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp)``

Arguments
=========

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

``argp``
    Pointer to struct :c:type:`v4l2_frmivalenum`
    that contains a pixel format and size and receives a frame interval.

열거 방식과 일관성

지원 pixel format은 `VIDIOC_ENUM_FMT`로, 지원 frame size는 `VIDIOC_ENUM_FRAMESIZES`로 먼저 얻습니다. 이 ioctl의 반환 방식과 `v4l2_frmivalenum.type`의 내용은 장치가 제공하는 frame interval 유형에 따라 달라집니다.

응용 프로그램은 `index` 0으로 처음 호출한 뒤 반드시 `type`을 검사해야 합니다. 더 많은 interval을 얻기 위해 `index`를 증가시키는 방식은 `V4L2_FRMIVAL_TYPE_DISCRETE`일 때만 의미가 있습니다.

frame interval이 반환되는 순서에는 특별한 의미가 없으며 기본 interval의 우선순위를 나타내지도 않습니다. 응용 프로그램이 열거 도중 다른 ioctl을 호출하지 않는다면 열거 데이터는 스스로 바뀌지 않고 일관되다고 가정할 수 있습니다.

V4L2 API는 frame rate가 아니라 frame interval을 사용합니다. frame rate는 `frame_rate = 1 / frame_interval`로 계산하므로 interval이 짧을수록 초당 frame 수가 많습니다.

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

This ioctl allows applications to enumerate all frame intervals that the
device supports for the given pixel format and frame size.

The supported pixel formats and frame sizes can be obtained by using the
:ref:`VIDIOC_ENUM_FMT` and
:ref:`VIDIOC_ENUM_FRAMESIZES` functions.

The return value and the content of the ``v4l2_frmivalenum.type`` field
depend on the type of frame intervals 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_frmivalenum.type` field is set to
   `V4L2_FRMIVAL_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_frmivalenum.type`` field is set to
   ``V4L2_FRMIVAL_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_frmivalenum.type``
   field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of
   the union only the ``stepwise`` member is valid and the ``step``
   value is set to 1.

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

.. note::

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

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 interval enumeration.

.. note::

   **Frame intervals and frame rates:** The V4L2 API uses frame
   intervals instead of frame rates. Given the frame interval the frame
   rate can be computed as follows:

   ::

       frame_rate = 1 / frame_interval

v4l2_frmival_stepwise 구조체

아래 구조체에서 응용 프로그램은 IN 필드만 채우고 나머지 멤버는 모두 0으로 초기화해야 합니다. OUT 필드는 드라이버가 채웁니다. `v4l2_frmival_stepwise`는 지원 interval 범위를 초 단위의 `v4l2_fract` 값으로 표현합니다.

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_frmival_stepwise

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

    * - struct :c:type:`v4l2_fract`
      - ``min``
      - Minimum frame interval [s].
    * - struct :c:type:`v4l2_fract`
      - ``max``
      - Maximum frame interval [s].
    * - struct :c:type:`v4l2_fract`
      - ``step``
      - Frame interval step size [s].

v4l2_frmivalenum 구조체

`type`이 결정한 union 멤버만 읽어야 합니다. Discrete에서는 `discrete`, Step-wise와 Continuous에서는 `stepwise`가 유효하며, 다른 union 해석은 정의되지 않습니다.

.. c:type:: v4l2_frmivalenum

.. tabularcolumns:: |p{4.9cm}|p{3.3cm}|p{9.1cm}|

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

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

v4l2_frmivaltypes 열거형

Enums
=====

.. c:type:: v4l2_frmivaltypes

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

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

    * - ``V4L2_FRMIVAL_TYPE_DISCRETE``
      - 1
      - Discrete frame interval.
    * - ``V4L2_FRMIVAL_TYPE_CONTINUOUS``
      - 2
      - Continuous frame interval.
    * - ``V4L2_FRMIVAL_TYPE_STEPWISE``
      - 3
      - Step-wise defined frame interval.

반환값

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 적절한 값으로 설정하며, 공통 오류 코드는 Generic Error Codes 장의 정의를 따릅니다. 열거에서는 지원하지 않는 조건이나 끝을 나타내는 `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.