Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_ENUM_FRAMEINTERVALS: |
5377d91f MH |
4 | |
5 | ******************************** | |
6 | ioctl VIDIOC_ENUM_FRAMEINTERVALS | |
7 | ******************************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
41d80465 MCC |
18 | .. c:function:: int ioctl( int fd, VIDIOC_ENUM_FRAMEINTERVALS, struct v4l2_frmivalenum *argp ) |
19 | :name: VIDIOC_ENUM_FRAMEINTERVALS | |
5377d91f | 20 | |
586027ce | 21 | |
15e7d615 | 22 | Arguments |
5377d91f MH |
23 | ========= |
24 | ||
25 | ``fd`` | |
26 | File descriptor returned by :ref:`open() <func-open>`. | |
27 | ||
5377d91f | 28 | ``argp`` |
e8be7e97 | 29 | Pointer to a struct :c:type:`v4l2_frmivalenum` |
5377d91f MH |
30 | structure that contains a pixel format and size and receives a frame |
31 | interval. | |
32 | ||
33 | ||
15e7d615 | 34 | Description |
5377d91f MH |
35 | =========== |
36 | ||
37 | This ioctl allows applications to enumerate all frame intervals that the | |
38 | device supports for the given pixel format and frame size. | |
39 | ||
40 | The supported pixel formats and frame sizes can be obtained by using the | |
7347081e MCC |
41 | :ref:`VIDIOC_ENUM_FMT` and |
42 | :ref:`VIDIOC_ENUM_FRAMESIZES` functions. | |
5377d91f MH |
43 | |
44 | The return value and the content of the ``v4l2_frmivalenum.type`` field | |
45 | depend on the type of frame intervals the device supports. Here are the | |
46 | semantics of the function for the different cases: | |
47 | ||
48 | - **Discrete:** The function returns success if the given index value | |
49 | (zero-based) is valid. The application should increase the index by | |
50 | one for each call until ``EINVAL`` is returned. The | |
51 | `v4l2_frmivalenum.type` field is set to | |
52 | `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only | |
53 | the `discrete` member is valid. | |
54 | ||
55 | - **Step-wise:** The function returns success if the given index value | |
56 | is zero and ``EINVAL`` for any other index value. The | |
57 | ``v4l2_frmivalenum.type`` field is set to | |
58 | ``V4L2_FRMIVAL_TYPE_STEPWISE`` by the driver. Of the union only the | |
59 | ``stepwise`` member is valid. | |
60 | ||
61 | - **Continuous:** This is a special case of the step-wise type above. | |
62 | The function returns success if the given index value is zero and | |
63 | ``EINVAL`` for any other index value. The ``v4l2_frmivalenum.type`` | |
64 | field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of | |
65 | the union only the ``stepwise`` member is valid and the ``step`` | |
66 | value is set to 1. | |
67 | ||
68 | When the application calls the function with index zero, it must check | |
69 | the ``type`` field to determine the type of frame interval enumeration | |
70 | the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type | |
71 | does it make sense to increase the index value to receive more frame | |
72 | intervals. | |
73 | ||
b6b6e678 MCC |
74 | .. note:: |
75 | ||
76 | The order in which the frame intervals are returned has no | |
706f8a99 MCC |
77 | special meaning. In particular does it not say anything about potential |
78 | default frame intervals. | |
5377d91f MH |
79 | |
80 | Applications can assume that the enumeration data does not change | |
81 | without any interaction from the application itself. This means that the | |
82 | enumeration data is consistent if the application does not perform any | |
83 | other ioctl calls while it runs the frame interval enumeration. | |
84 | ||
706f8a99 | 85 | .. note:: |
5377d91f | 86 | |
706f8a99 | 87 | **Frame intervals and frame rates:** The V4L2 API uses frame |
5377d91f MH |
88 | intervals instead of frame rates. Given the frame interval the frame |
89 | rate can be computed as follows: | |
90 | ||
5377d91f MH |
91 | :: |
92 | ||
93 | frame_rate = 1 / frame_interval | |
94 | ||
95 | ||
96 | Structs | |
97 | ======= | |
98 | ||
99 | In the structs below, *IN* denotes a value that has to be filled in by | |
100 | the application, *OUT* denotes values that the driver fills in. The | |
101 | application should zero out all members except for the *IN* fields. | |
102 | ||
103 | ||
e8be7e97 | 104 | .. c:type:: v4l2_frmival_stepwise |
5377d91f | 105 | |
5bd4bb78 MCC |
106 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
107 | ||
5377d91f MH |
108 | .. flat-table:: struct v4l2_frmival_stepwise |
109 | :header-rows: 0 | |
110 | :stub-columns: 0 | |
111 | :widths: 1 1 2 | |
112 | ||
113 | ||
114 | - .. row 1 | |
115 | ||
e8be7e97 | 116 | - struct :c:type:`v4l2_fract` |
5377d91f MH |
117 | |
118 | - ``min`` | |
119 | ||
120 | - Minimum frame interval [s]. | |
121 | ||
122 | - .. row 2 | |
123 | ||
e8be7e97 | 124 | - struct :c:type:`v4l2_fract` |
5377d91f MH |
125 | |
126 | - ``max`` | |
127 | ||
128 | - Maximum frame interval [s]. | |
129 | ||
130 | - .. row 3 | |
131 | ||
e8be7e97 | 132 | - struct :c:type:`v4l2_fract` |
5377d91f MH |
133 | |
134 | - ``step`` | |
135 | ||
136 | - Frame interval step size [s]. | |
137 | ||
138 | ||
139 | ||
e8be7e97 | 140 | .. c:type:: v4l2_frmivalenum |
5377d91f MH |
141 | |
142 | .. flat-table:: struct v4l2_frmivalenum | |
143 | :header-rows: 0 | |
144 | :stub-columns: 0 | |
145 | ||
146 | ||
147 | - .. row 1 | |
148 | ||
149 | - __u32 | |
150 | ||
151 | - ``index`` | |
152 | ||
0579e6e3 | 153 | - |
5377d91f MH |
154 | - IN: Index of the given frame interval in the enumeration. |
155 | ||
156 | - .. row 2 | |
157 | ||
158 | - __u32 | |
159 | ||
160 | - ``pixel_format`` | |
161 | ||
0579e6e3 | 162 | - |
5377d91f MH |
163 | - IN: Pixel format for which the frame intervals are enumerated. |
164 | ||
165 | - .. row 3 | |
166 | ||
167 | - __u32 | |
168 | ||
169 | - ``width`` | |
170 | ||
0579e6e3 | 171 | - |
5377d91f MH |
172 | - IN: Frame width for which the frame intervals are enumerated. |
173 | ||
174 | - .. row 4 | |
175 | ||
176 | - __u32 | |
177 | ||
178 | - ``height`` | |
179 | ||
0579e6e3 | 180 | - |
5377d91f MH |
181 | - IN: Frame height for which the frame intervals are enumerated. |
182 | ||
183 | - .. row 5 | |
184 | ||
185 | - __u32 | |
186 | ||
187 | - ``type`` | |
188 | ||
0579e6e3 | 189 | - |
5377d91f MH |
190 | - OUT: Frame interval type the device supports. |
191 | ||
192 | - .. row 6 | |
193 | ||
194 | - union | |
195 | ||
0579e6e3 MCC |
196 | - |
197 | - | |
5377d91f MH |
198 | - OUT: Frame interval with the given index. |
199 | ||
200 | - .. row 7 | |
201 | ||
0579e6e3 | 202 | - |
e8be7e97 | 203 | - struct :c:type:`v4l2_fract` |
5377d91f MH |
204 | |
205 | - ``discrete`` | |
206 | ||
207 | - Frame interval [s]. | |
208 | ||
209 | - .. row 8 | |
210 | ||
0579e6e3 | 211 | - |
e8be7e97 | 212 | - struct :c:type:`v4l2_frmival_stepwise` |
5377d91f MH |
213 | |
214 | - ``stepwise`` | |
215 | ||
0579e6e3 | 216 | - |
5377d91f MH |
217 | |
218 | - .. row 9 | |
219 | ||
220 | - __u32 | |
221 | ||
8968da9b | 222 | - ``reserved[2]`` |
5377d91f | 223 | |
0579e6e3 | 224 | - |
5377d91f | 225 | - Reserved space for future use. Must be zeroed by drivers and |
0579e6e3 | 226 | applications. |
5377d91f MH |
227 | |
228 | ||
229 | ||
230 | Enums | |
231 | ===== | |
232 | ||
233 | ||
56683d7d | 234 | .. c:type:: v4l2_frmivaltypes |
5377d91f | 235 | |
5bd4bb78 MCC |
236 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
237 | ||
5377d91f MH |
238 | .. flat-table:: enum v4l2_frmivaltypes |
239 | :header-rows: 0 | |
240 | :stub-columns: 0 | |
241 | :widths: 3 1 4 | |
242 | ||
243 | ||
244 | - .. row 1 | |
245 | ||
246 | - ``V4L2_FRMIVAL_TYPE_DISCRETE`` | |
247 | ||
248 | - 1 | |
249 | ||
250 | - Discrete frame interval. | |
251 | ||
252 | - .. row 2 | |
253 | ||
254 | - ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` | |
255 | ||
256 | - 2 | |
257 | ||
258 | - Continuous frame interval. | |
259 | ||
260 | - .. row 3 | |
261 | ||
262 | - ``V4L2_FRMIVAL_TYPE_STEPWISE`` | |
263 | ||
264 | - 3 | |
265 | ||
266 | - Step-wise defined frame interval. | |
267 | ||
268 | ||
15e7d615 | 269 | Return Value |
5377d91f MH |
270 | ============ |
271 | ||
272 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
273 | appropriately. The generic error codes are described at the | |
274 | :ref:`Generic Error Codes <gen-errors>` chapter. |