1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _VIDIOC_ENUM_FRAMEINTERVALS: 4 5******************************** 6ioctl VIDIOC_ENUM_FRAMEINTERVALS 7******************************** 8 9Name 10==== 11 12VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals 13 14 15Synopsis 16======== 17 18.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp ) 19 :name: VIDIOC_ENUM_FRAMEINTERVALS 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_frmivalenum` 30 that contains a pixel format and size and receives a frame interval. 31 32 33Description 34=========== 35 36This ioctl allows applications to enumerate all frame intervals that the 37device supports for the given pixel format and frame size. 38 39The supported pixel formats and frame sizes can be obtained by using the 40:ref:`VIDIOC_ENUM_FMT` and 41:ref:`VIDIOC_ENUM_FRAMESIZES` functions. 42 43The return value and the content of the ``v4l2_frmivalenum.type`` field 44depend on the type of frame intervals the device supports. Here are the 45semantics of the function for the different cases: 46 47- **Discrete:** The function returns success if the given index value 48 (zero-based) is valid. The application should increase the index by 49 one for each call until ``EINVAL`` is returned. The 50 `v4l2_frmivalenum.type` field is set to 51 `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only 52 the `discrete` member is valid. 53 54- **Step-wise:** The function returns success if the given index value 55 is zero and ``EINVAL`` for any other index value. The 56 ``v4l2_frmivalenum.type`` field is set to 57 ``V4L2_FRMIVAL_TYPE_STEPWISE`` by the driver. Of the union only the 58 ``stepwise`` member is valid. 59 60- **Continuous:** This is a special case of the step-wise type above. 61 The function returns success if the given index value is zero and 62 ``EINVAL`` for any other index value. The ``v4l2_frmivalenum.type`` 63 field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of 64 the union only the ``stepwise`` member is valid and the ``step`` 65 value is set to 1. 66 67When the application calls the function with index zero, it must check 68the ``type`` field to determine the type of frame interval enumeration 69the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type 70does it make sense to increase the index value to receive more frame 71intervals. 72 73.. note:: 74 75 The order in which the frame intervals are returned has no 76 special meaning. In particular does it not say anything about potential 77 default frame intervals. 78 79Applications can assume that the enumeration data does not change 80without any interaction from the application itself. This means that the 81enumeration data is consistent if the application does not perform any 82other ioctl calls while it runs the frame interval enumeration. 83 84.. note:: 85 86 **Frame intervals and frame rates:** The V4L2 API uses frame 87 intervals instead of frame rates. Given the frame interval the frame 88 rate can be computed as follows: 89 90 :: 91 92 frame_rate = 1 / frame_interval 93 94 95Structs 96======= 97 98In the structs below, *IN* denotes a value that has to be filled in by 99the application, *OUT* denotes values that the driver fills in. The 100application should zero out all members except for the *IN* fields. 101 102 103.. c:type:: v4l2_frmival_stepwise 104 105.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 106 107.. flat-table:: struct v4l2_frmival_stepwise 108 :header-rows: 0 109 :stub-columns: 0 110 :widths: 1 1 2 111 112 * - struct :c:type:`v4l2_fract` 113 - ``min`` 114 - Minimum frame interval [s]. 115 * - struct :c:type:`v4l2_fract` 116 - ``max`` 117 - Maximum frame interval [s]. 118 * - struct :c:type:`v4l2_fract` 119 - ``step`` 120 - Frame interval step size [s]. 121 122 123 124.. c:type:: v4l2_frmivalenum 125 126.. tabularcolumns:: |p{1.8cm}|p{4.4cm}|p{2.4cm}|p{8.9cm}| 127 128.. flat-table:: struct v4l2_frmivalenum 129 :header-rows: 0 130 :stub-columns: 0 131 132 * - __u32 133 - ``index`` 134 - IN: Index of the given frame interval in the enumeration. 135 * - __u32 136 - ``pixel_format`` 137 - IN: Pixel format for which the frame intervals are enumerated. 138 * - __u32 139 - ``width`` 140 - IN: Frame width for which the frame intervals are enumerated. 141 * - __u32 142 - ``height`` 143 - IN: Frame height for which the frame intervals are enumerated. 144 * - __u32 145 - ``type`` 146 - OUT: Frame interval type the device supports. 147 * - union { 148 - (anonymous) 149 - OUT: Frame interval with the given index. 150 * - struct :c:type:`v4l2_fract` 151 - ``discrete`` 152 - Frame interval [s]. 153 * - struct :c:type:`v4l2_frmival_stepwise` 154 - ``stepwise`` 155 - 156 * - } 157 - 158 - 159 * - __u32 160 - ``reserved[2]`` 161 - 162 - Reserved space for future use. Must be zeroed by drivers and 163 applications. 164 165 166 167Enums 168===== 169 170 171.. c:type:: v4l2_frmivaltypes 172 173.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 174 175.. flat-table:: enum v4l2_frmivaltypes 176 :header-rows: 0 177 :stub-columns: 0 178 :widths: 3 1 4 179 180 * - ``V4L2_FRMIVAL_TYPE_DISCRETE`` 181 - 1 182 - Discrete frame interval. 183 * - ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` 184 - 2 185 - Continuous frame interval. 186 * - ``V4L2_FRMIVAL_TYPE_STEPWISE`` 187 - 3 188 - Step-wise defined frame interval. 189 190 191Return Value 192============ 193 194On success 0 is returned, on error -1 and the ``errno`` variable is set 195appropriately. The generic error codes are described at the 196:ref:`Generic Error Codes <gen-errors>` chapter. 197