Merge remote-tracking branch 'omap_dss2/for-next'
[deliverable/linux.git] / Documentation / media / uapi / v4l / vidioc-enum-frameintervals.rst
CommitLineData
5377d91f
MH
1.. -*- coding: utf-8; mode: rst -*-
2
af4a4d0d 3.. _VIDIOC_ENUM_FRAMEINTERVALS:
5377d91f
MH
4
5********************************
6ioctl VIDIOC_ENUM_FRAMEINTERVALS
7********************************
8
15e7d615 9Name
586027ce 10====
5377d91f 11
586027ce 12VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals
5377d91f 13
15e7d615
MCC
14
15Synopsis
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 22Arguments
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 34Description
5377d91f
MH
35===========
36
37This ioctl allows applications to enumerate all frame intervals that the
38device supports for the given pixel format and frame size.
39
40The 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
44The return value and the content of the ``v4l2_frmivalenum.type`` field
45depend on the type of frame intervals the device supports. Here are the
46semantics 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
68When the application calls the function with index zero, it must check
69the ``type`` field to determine the type of frame interval enumeration
70the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type
71does it make sense to increase the index value to receive more frame
72intervals.
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
80Applications can assume that the enumeration data does not change
81without any interaction from the application itself. This means that the
82enumeration data is consistent if the application does not perform any
83other 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
96Structs
97=======
98
99In the structs below, *IN* denotes a value that has to be filled in by
100the application, *OUT* denotes values that the driver fills in. The
101application 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
230Enums
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 269Return Value
5377d91f
MH
270============
271
272On success 0 is returned, on error -1 and the ``errno`` variable is set
273appropriately. The generic error codes are described at the
274:ref:`Generic Error Codes <gen-errors>` chapter.
This page took 0.060634 seconds and 5 git commands to generate.