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