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 | ||
b7e67f6c | 18 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmivalenum *argp ) |
5377d91f | 19 | |
586027ce | 20 | |
15e7d615 | 21 | Arguments |
5377d91f MH |
22 | ========= |
23 | ||
24 | ``fd`` | |
25 | File descriptor returned by :ref:`open() <func-open>`. | |
26 | ||
27 | ``request`` | |
28 | VIDIOC_ENUM_FRAMEINTERVALS | |
29 | ||
30 | ``argp`` | |
31 | Pointer to a struct :ref:`v4l2_frmivalenum <v4l2-frmivalenum>` | |
32 | structure that contains a pixel format and size and receives a frame | |
33 | interval. | |
34 | ||
35 | ||
15e7d615 | 36 | Description |
5377d91f MH |
37 | =========== |
38 | ||
39 | This ioctl allows applications to enumerate all frame intervals that the | |
40 | device supports for the given pixel format and frame size. | |
41 | ||
42 | The supported pixel formats and frame sizes can be obtained by using the | |
7347081e MCC |
43 | :ref:`VIDIOC_ENUM_FMT` and |
44 | :ref:`VIDIOC_ENUM_FRAMESIZES` functions. | |
5377d91f MH |
45 | |
46 | The return value and the content of the ``v4l2_frmivalenum.type`` field | |
47 | depend on the type of frame intervals the device supports. Here are the | |
48 | semantics of the function for the different cases: | |
49 | ||
50 | - **Discrete:** The function returns success if the given index value | |
51 | (zero-based) is valid. The application should increase the index by | |
52 | one for each call until ``EINVAL`` is returned. The | |
53 | `v4l2_frmivalenum.type` field is set to | |
54 | `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only | |
55 | the `discrete` member is valid. | |
56 | ||
57 | - **Step-wise:** The function returns success if the given index value | |
58 | is zero and ``EINVAL`` for any other index value. The | |
59 | ``v4l2_frmivalenum.type`` field is set to | |
60 | ``V4L2_FRMIVAL_TYPE_STEPWISE`` by the driver. Of the union only the | |
61 | ``stepwise`` member is valid. | |
62 | ||
63 | - **Continuous:** This is a special case of the step-wise type above. | |
64 | The function returns success if the given index value is zero and | |
65 | ``EINVAL`` for any other index value. The ``v4l2_frmivalenum.type`` | |
66 | field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of | |
67 | the union only the ``stepwise`` member is valid and the ``step`` | |
68 | value is set to 1. | |
69 | ||
70 | When the application calls the function with index zero, it must check | |
71 | the ``type`` field to determine the type of frame interval enumeration | |
72 | the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type | |
73 | does it make sense to increase the index value to receive more frame | |
74 | intervals. | |
75 | ||
706f8a99 MCC |
76 | .. note:: The order in which the frame intervals are returned has no |
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 | ||
104 | .. _v4l2-frmival-stepwise: | |
105 | ||
106 | .. flat-table:: struct v4l2_frmival_stepwise | |
107 | :header-rows: 0 | |
108 | :stub-columns: 0 | |
109 | :widths: 1 1 2 | |
110 | ||
111 | ||
112 | - .. row 1 | |
113 | ||
114 | - struct :ref:`v4l2_fract <v4l2-fract>` | |
115 | ||
116 | - ``min`` | |
117 | ||
118 | - Minimum frame interval [s]. | |
119 | ||
120 | - .. row 2 | |
121 | ||
122 | - struct :ref:`v4l2_fract <v4l2-fract>` | |
123 | ||
124 | - ``max`` | |
125 | ||
126 | - Maximum frame interval [s]. | |
127 | ||
128 | - .. row 3 | |
129 | ||
130 | - struct :ref:`v4l2_fract <v4l2-fract>` | |
131 | ||
132 | - ``step`` | |
133 | ||
134 | - Frame interval step size [s]. | |
135 | ||
136 | ||
137 | ||
138 | .. _v4l2-frmivalenum: | |
139 | ||
140 | .. flat-table:: struct v4l2_frmivalenum | |
141 | :header-rows: 0 | |
142 | :stub-columns: 0 | |
143 | ||
144 | ||
145 | - .. row 1 | |
146 | ||
147 | - __u32 | |
148 | ||
149 | - ``index`` | |
150 | ||
0579e6e3 | 151 | - |
5377d91f MH |
152 | - IN: Index of the given frame interval in the enumeration. |
153 | ||
154 | - .. row 2 | |
155 | ||
156 | - __u32 | |
157 | ||
158 | - ``pixel_format`` | |
159 | ||
0579e6e3 | 160 | - |
5377d91f MH |
161 | - IN: Pixel format for which the frame intervals are enumerated. |
162 | ||
163 | - .. row 3 | |
164 | ||
165 | - __u32 | |
166 | ||
167 | - ``width`` | |
168 | ||
0579e6e3 | 169 | - |
5377d91f MH |
170 | - IN: Frame width for which the frame intervals are enumerated. |
171 | ||
172 | - .. row 4 | |
173 | ||
174 | - __u32 | |
175 | ||
176 | - ``height`` | |
177 | ||
0579e6e3 | 178 | - |
5377d91f MH |
179 | - IN: Frame height for which the frame intervals are enumerated. |
180 | ||
181 | - .. row 5 | |
182 | ||
183 | - __u32 | |
184 | ||
185 | - ``type`` | |
186 | ||
0579e6e3 | 187 | - |
5377d91f MH |
188 | - OUT: Frame interval type the device supports. |
189 | ||
190 | - .. row 6 | |
191 | ||
192 | - union | |
193 | ||
0579e6e3 MCC |
194 | - |
195 | - | |
5377d91f MH |
196 | - OUT: Frame interval with the given index. |
197 | ||
198 | - .. row 7 | |
199 | ||
0579e6e3 | 200 | - |
5377d91f MH |
201 | - struct :ref:`v4l2_fract <v4l2-fract>` |
202 | ||
203 | - ``discrete`` | |
204 | ||
205 | - Frame interval [s]. | |
206 | ||
207 | - .. row 8 | |
208 | ||
0579e6e3 | 209 | - |
5377d91f MH |
210 | - struct :ref:`v4l2_frmival_stepwise <v4l2-frmival-stepwise>` |
211 | ||
212 | - ``stepwise`` | |
213 | ||
0579e6e3 | 214 | - |
5377d91f MH |
215 | |
216 | - .. row 9 | |
217 | ||
218 | - __u32 | |
219 | ||
ffbab694 | 220 | - ``reserved\[2\]`` |
5377d91f | 221 | |
0579e6e3 | 222 | - |
5377d91f | 223 | - Reserved space for future use. Must be zeroed by drivers and |
0579e6e3 | 224 | applications. |
5377d91f MH |
225 | |
226 | ||
227 | ||
228 | Enums | |
229 | ===== | |
230 | ||
231 | ||
232 | .. _v4l2-frmivaltypes: | |
233 | ||
234 | .. flat-table:: enum v4l2_frmivaltypes | |
235 | :header-rows: 0 | |
236 | :stub-columns: 0 | |
237 | :widths: 3 1 4 | |
238 | ||
239 | ||
240 | - .. row 1 | |
241 | ||
242 | - ``V4L2_FRMIVAL_TYPE_DISCRETE`` | |
243 | ||
244 | - 1 | |
245 | ||
246 | - Discrete frame interval. | |
247 | ||
248 | - .. row 2 | |
249 | ||
250 | - ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` | |
251 | ||
252 | - 2 | |
253 | ||
254 | - Continuous frame interval. | |
255 | ||
256 | - .. row 3 | |
257 | ||
258 | - ``V4L2_FRMIVAL_TYPE_STEPWISE`` | |
259 | ||
260 | - 3 | |
261 | ||
262 | - Step-wise defined frame interval. | |
263 | ||
264 | ||
15e7d615 | 265 | Return Value |
5377d91f MH |
266 | ============ |
267 | ||
268 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
269 | appropriately. The generic error codes are described at the | |
270 | :ref:`Generic Error Codes <gen-errors>` chapter. |