1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL:
4
5***************************************
6ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
7***************************************
8
9Name
10====
11
12VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals
13
14
15Synopsis
16========
17
18.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp )
19    :name: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
20
21
22Arguments
23=========
24
25``fd``
26    File descriptor returned by :ref:`open() <func-open>`.
27
28``argp``
29    Pointer to struct :c:type:`v4l2_subdev_frame_interval_enum`.
30
31
32Description
33===========
34
35This ioctl lets applications enumerate available frame intervals on a
36given sub-device pad. Frame intervals only makes sense for sub-devices
37that can control the frame period on their own. This includes, for
38instance, image sensors and TV tuners.
39
40For the common use case of image sensors, the frame intervals available
41on the sub-device output pad depend on the frame format and size on the
42same pad. Applications must thus specify the desired format and size
43when enumerating frame intervals.
44
45To enumerate frame intervals applications initialize the ``index``,
46``pad``, ``which``, ``code``, ``width`` and ``height`` fields of struct
47:c:type:`v4l2_subdev_frame_interval_enum`
48and call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL` ioctl with a pointer
49to this structure. Drivers fill the rest of the structure or return an
50EINVAL error code if one of the input fields is invalid. All frame
51intervals are enumerable by beginning at index zero and incrementing by
52one until ``EINVAL`` is returned.
53
54Available frame intervals may depend on the current 'try' formats at
55other pads of the sub-device, as well as on the current active links.
56See :ref:`VIDIOC_SUBDEV_G_FMT` for more
57information about the try formats.
58
59Sub-devices that support the frame interval enumeration ioctl should
60implemented it on a single pad only. Its behaviour when supported on
61multiple pads of the same sub-device is not defined.
62
63.. c:type:: v4l2_subdev_frame_interval_enum
64
65.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
66
67.. flat-table:: struct v4l2_subdev_frame_interval_enum
68    :header-rows:  0
69    :stub-columns: 0
70    :widths:       1 1 2
71
72    * - __u32
73      - ``index``
74      - Number of the format in the enumeration, set by the application.
75    * - __u32
76      - ``pad``
77      - Pad number as reported by the media controller API.
78    * - __u32
79      - ``code``
80      - The media bus format code, as defined in
81	:ref:`v4l2-mbus-format`.
82    * - __u32
83      - ``width``
84      - Frame width, in pixels.
85    * - __u32
86      - ``height``
87      - Frame height, in pixels.
88    * - struct :c:type:`v4l2_fract`
89      - ``interval``
90      - Period, in seconds, between consecutive video frames.
91    * - __u32
92      - ``which``
93      - Frame intervals to be enumerated, from enum
94	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
95    * - __u32
96      - ``reserved``\ [8]
97      - Reserved for future extensions. Applications and drivers must set
98	the array to zero.
99
100
101Return Value
102============
103
104On success 0 is returned, on error -1 and the ``errno`` variable is set
105appropriately. The generic error codes are described at the
106:ref:`Generic Error Codes <gen-errors>` chapter.
107
108EINVAL
109    The struct
110    :c:type:`v4l2_subdev_frame_interval_enum`
111    ``pad`` references a non-existing pad, one of the ``code``,
112    ``width`` or ``height`` fields are invalid for the given pad or the
113    ``index`` field is out of bounds.
114