Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_ENUMSTD: |
5377d91f MH |
4 | |
5 | ******************** | |
6 | ioctl VIDIOC_ENUMSTD | |
7 | ******************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_ENUMSTD - Enumerate supported video standards |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
b7e67f6c | 18 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_standard *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_ENUMSTD | |
29 | ||
30 | ``argp`` | |
31 | ||
32 | ||
15e7d615 | 33 | Description |
5377d91f MH |
34 | =========== |
35 | ||
36 | To query the attributes of a video standard, especially a custom (driver | |
37 | defined) one, applications initialize the ``index`` field of struct | |
2212ff25 | 38 | :ref:`v4l2_standard <v4l2-standard>` and call the :ref:`VIDIOC_ENUMSTD` |
5377d91f | 39 | ioctl with a pointer to this structure. Drivers fill the rest of the |
cdb4af0f | 40 | structure or return an ``EINVAL`` error code when the index is out of |
5377d91f | 41 | bounds. To enumerate all standards applications shall begin at index |
cdb4af0f | 42 | zero, incrementing by one until the driver returns ``EINVAL``. Drivers may |
5377d91f | 43 | enumerate a different set of standards after switching the video input |
4855307b | 44 | or output. [#f1]_ |
5377d91f MH |
45 | |
46 | ||
47 | .. _v4l2-standard: | |
48 | ||
49 | .. flat-table:: struct v4l2_standard | |
50 | :header-rows: 0 | |
51 | :stub-columns: 0 | |
52 | :widths: 1 1 2 | |
53 | ||
54 | ||
55 | - .. row 1 | |
56 | ||
57 | - __u32 | |
58 | ||
59 | - ``index`` | |
60 | ||
61 | - Number of the video standard, set by the application. | |
62 | ||
63 | - .. row 2 | |
64 | ||
65 | - :ref:`v4l2_std_id <v4l2-std-id>` | |
66 | ||
67 | - ``id`` | |
68 | ||
69 | - The bits in this field identify the standard as one of the common | |
0579e6e3 MCC |
70 | standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are |
71 | set as custom standards. Multiple bits can be set if the hardware | |
72 | does not distinguish between these standards, however separate | |
73 | indices do not indicate the opposite. The ``id`` must be unique. | |
74 | No other enumerated :ref:`struct v4l2_standard <v4l2-standard>` structure, | |
75 | for this input or output anyway, can contain the same set of bits. | |
5377d91f MH |
76 | |
77 | - .. row 3 | |
78 | ||
79 | - __u8 | |
80 | ||
8968da9b | 81 | - ``name``\ [24] |
5377d91f MH |
82 | |
83 | - Name of the standard, a NUL-terminated ASCII string, for example: | |
0579e6e3 MCC |
84 | "PAL-B/G", "NTSC Japan". This information is intended for the |
85 | user. | |
5377d91f MH |
86 | |
87 | - .. row 4 | |
88 | ||
89 | - struct :ref:`v4l2_fract <v4l2-fract>` | |
90 | ||
91 | - ``frameperiod`` | |
92 | ||
93 | - The frame period (not field period) is numerator / denominator. | |
0579e6e3 | 94 | For example M/NTSC has a frame period of 1001 / 30000 seconds. |
5377d91f MH |
95 | |
96 | - .. row 5 | |
97 | ||
98 | - __u32 | |
99 | ||
100 | - ``framelines`` | |
101 | ||
102 | - Total lines per frame including blanking, e. g. 625 for B/PAL. | |
103 | ||
104 | - .. row 6 | |
105 | ||
106 | - __u32 | |
107 | ||
8968da9b | 108 | - ``reserved``\ [4] |
5377d91f MH |
109 | |
110 | - Reserved for future extensions. Drivers must set the array to | |
0579e6e3 | 111 | zero. |
5377d91f MH |
112 | |
113 | ||
114 | ||
115 | .. _v4l2-fract: | |
116 | ||
117 | .. flat-table:: struct v4l2_fract | |
118 | :header-rows: 0 | |
119 | :stub-columns: 0 | |
120 | :widths: 1 1 2 | |
121 | ||
122 | ||
123 | - .. row 1 | |
124 | ||
125 | - __u32 | |
126 | ||
127 | - ``numerator`` | |
128 | ||
0579e6e3 | 129 | - |
5377d91f MH |
130 | |
131 | - .. row 2 | |
132 | ||
133 | - __u32 | |
134 | ||
135 | - ``denominator`` | |
136 | ||
0579e6e3 | 137 | - |
5377d91f MH |
138 | |
139 | ||
140 | ||
141 | .. _v4l2-std-id: | |
142 | ||
143 | .. flat-table:: typedef v4l2_std_id | |
144 | :header-rows: 0 | |
145 | :stub-columns: 0 | |
146 | :widths: 1 1 2 | |
147 | ||
148 | ||
149 | - .. row 1 | |
150 | ||
151 | - __u64 | |
152 | ||
153 | - ``v4l2_std_id`` | |
154 | ||
155 | - This type is a set, each bit representing another video standard | |
0579e6e3 MCC |
156 | as listed below and in :ref:`video-standards`. The 32 most |
157 | significant bits are reserved for custom (driver defined) video | |
158 | standards. | |
5377d91f MH |
159 | |
160 | ||
161 | ||
162 | .. code-block:: c | |
163 | ||
164 | #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) | |
165 | #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002) | |
166 | #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004) | |
167 | #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008) | |
168 | #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010) | |
169 | #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020) | |
170 | #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040) | |
171 | #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080) | |
172 | ||
173 | #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100) | |
174 | #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200) | |
175 | #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400) | |
176 | #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800) | |
177 | ||
178 | ``V4L2_STD_PAL_60`` is a hybrid standard with 525 lines, 60 Hz refresh | |
179 | rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some | |
180 | PAL video recorders can play back NTSC tapes in this mode for display on | |
181 | a 50/60 Hz agnostic PAL TV. | |
182 | ||
183 | ||
184 | .. code-block:: c | |
185 | ||
186 | #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) | |
187 | #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) | |
188 | #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000) | |
189 | ||
190 | ``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh | |
191 | rate, and NTSC color modulation with a 4.43 MHz color subcarrier. | |
192 | ||
193 | ||
194 | .. code-block:: c | |
195 | ||
196 | #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) | |
197 | ||
198 | #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000) | |
199 | #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000) | |
200 | #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000) | |
201 | #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000) | |
202 | #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000) | |
203 | #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000) | |
204 | #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000) | |
205 | #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000) | |
206 | ||
207 | /* ATSC/HDTV */ | |
208 | #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000) | |
209 | #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000) | |
210 | ||
211 | ``V4L2_STD_ATSC_8_VSB`` and ``V4L2_STD_ATSC_16_VSB`` are U.S. | |
212 | terrestrial digital TV standards. Presently the V4L2 API does not | |
213 | support digital TV. See also the Linux DVB API at | |
214 | `https://linuxtv.org <https://linuxtv.org>`__. | |
215 | ||
216 | ||
217 | .. code-block:: c | |
218 | ||
219 | #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B | | |
0579e6e3 MCC |
220 | V4L2_STD_PAL_B1 | |
221 | V4L2_STD_PAL_G) | |
5377d91f | 222 | #define V4L2_STD_B (V4L2_STD_PAL_B | |
0579e6e3 MCC |
223 | V4L2_STD_PAL_B1 | |
224 | V4L2_STD_SECAM_B) | |
5377d91f | 225 | #define V4L2_STD_GH (V4L2_STD_PAL_G | |
0579e6e3 MCC |
226 | V4L2_STD_PAL_H | |
227 | V4L2_STD_SECAM_G | | |
228 | V4L2_STD_SECAM_H) | |
5377d91f | 229 | #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D | |
0579e6e3 MCC |
230 | V4L2_STD_PAL_D1 | |
231 | V4L2_STD_PAL_K) | |
5377d91f | 232 | #define V4L2_STD_PAL (V4L2_STD_PAL_BG | |
0579e6e3 MCC |
233 | V4L2_STD_PAL_DK | |
234 | V4L2_STD_PAL_H | | |
235 | V4L2_STD_PAL_I) | |
5377d91f | 236 | #define V4L2_STD_NTSC (V4L2_STD_NTSC_M | |
0579e6e3 MCC |
237 | V4L2_STD_NTSC_M_JP | |
238 | V4L2_STD_NTSC_M_KR) | |
5377d91f | 239 | #define V4L2_STD_MN (V4L2_STD_PAL_M | |
0579e6e3 MCC |
240 | V4L2_STD_PAL_N | |
241 | V4L2_STD_PAL_Nc | | |
242 | V4L2_STD_NTSC) | |
5377d91f | 243 | #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D | |
0579e6e3 MCC |
244 | V4L2_STD_SECAM_K | |
245 | V4L2_STD_SECAM_K1) | |
5377d91f | 246 | #define V4L2_STD_DK (V4L2_STD_PAL_DK | |
0579e6e3 | 247 | V4L2_STD_SECAM_DK) |
5377d91f MH |
248 | |
249 | #define V4L2_STD_SECAM (V4L2_STD_SECAM_B | | |
0579e6e3 MCC |
250 | V4L2_STD_SECAM_G | |
251 | V4L2_STD_SECAM_H | | |
252 | V4L2_STD_SECAM_DK | | |
253 | V4L2_STD_SECAM_L | | |
254 | V4L2_STD_SECAM_LC) | |
5377d91f MH |
255 | |
256 | #define V4L2_STD_525_60 (V4L2_STD_PAL_M | | |
0579e6e3 MCC |
257 | V4L2_STD_PAL_60 | |
258 | V4L2_STD_NTSC | | |
259 | V4L2_STD_NTSC_443) | |
5377d91f | 260 | #define V4L2_STD_625_50 (V4L2_STD_PAL | |
0579e6e3 MCC |
261 | V4L2_STD_PAL_N | |
262 | V4L2_STD_PAL_Nc | | |
263 | V4L2_STD_SECAM) | |
5377d91f MH |
264 | |
265 | #define V4L2_STD_UNKNOWN 0 | |
266 | #define V4L2_STD_ALL (V4L2_STD_525_60 | | |
0579e6e3 | 267 | V4L2_STD_625_50) |
5377d91f MH |
268 | |
269 | ||
270 | .. _video-standards: | |
271 | ||
edec4f44 | 272 | .. flat-table:: Video Standards (based on :ref:`itu470`) |
5377d91f MH |
273 | :header-rows: 1 |
274 | :stub-columns: 0 | |
275 | ||
276 | ||
277 | - .. row 1 | |
278 | ||
279 | - Characteristics | |
280 | ||
4855307b | 281 | - M/NTSC [#f2]_ |
5377d91f MH |
282 | |
283 | - M/PAL | |
284 | ||
4855307b | 285 | - N/PAL [#f3]_ |
5377d91f MH |
286 | |
287 | - B, B1, G/PAL | |
288 | ||
289 | - D, D1, K/PAL | |
290 | ||
291 | - H/PAL | |
292 | ||
293 | - I/PAL | |
294 | ||
295 | - B, G/SECAM | |
296 | ||
297 | - D, K/SECAM | |
298 | ||
299 | - K1/SECAM | |
300 | ||
301 | - L/SECAM | |
302 | ||
303 | - .. row 2 | |
304 | ||
305 | - Frame lines | |
306 | ||
307 | - :cspan:`1` 525 | |
308 | ||
309 | - :cspan:`9` 625 | |
310 | ||
311 | - .. row 3 | |
312 | ||
313 | - Frame period (s) | |
314 | ||
315 | - :cspan:`1` 1001/30000 | |
316 | ||
317 | - :cspan:`9` 1/25 | |
318 | ||
319 | - .. row 4 | |
320 | ||
321 | - Chrominance sub-carrier frequency (Hz) | |
322 | ||
323 | - 3579545 ± 10 | |
324 | ||
325 | - 3579611.49 ± 10 | |
326 | ||
327 | - 4433618.75 ± 5 (3582056.25 ± 5) | |
328 | ||
329 | - :cspan:`3` 4433618.75 ± 5 | |
330 | ||
331 | - 4433618.75 ± 1 | |
332 | ||
18759441 | 333 | - :cspan:`3` f\ :sub:`OR` = 4406250 ± 2000, f\ :sub:`OB` = 4250000 ± 2000 |
5377d91f MH |
334 | |
335 | - .. row 5 | |
336 | ||
337 | - Nominal radio-frequency channel bandwidth (MHz) | |
338 | ||
339 | - 6 | |
340 | ||
341 | - 6 | |
342 | ||
343 | - 6 | |
344 | ||
345 | - B: 7; B1, G: 8 | |
346 | ||
347 | - 8 | |
348 | ||
349 | - 8 | |
350 | ||
351 | - 8 | |
352 | ||
353 | - 8 | |
354 | ||
355 | - 8 | |
356 | ||
357 | - 8 | |
358 | ||
359 | - 8 | |
360 | ||
361 | - .. row 6 | |
362 | ||
363 | - Sound carrier relative to vision carrier (MHz) | |
364 | ||
18759441 | 365 | - 4.5 |
5377d91f | 366 | |
18759441 | 367 | - 4.5 |
5377d91f | 368 | |
18759441 | 369 | - 4.5 |
5377d91f | 370 | |
18759441 | 371 | - 5.5 ± 0.001 [#f4]_ [#f5]_ [#f6]_ [#f7]_ |
5377d91f | 372 | |
18759441 | 373 | - 6.5 ± 0.001 |
5377d91f | 374 | |
18759441 | 375 | - 5.5 |
5377d91f | 376 | |
18759441 | 377 | - 5.9996 ± 0.0005 |
5377d91f | 378 | |
18759441 | 379 | - 5.5 ± 0.001 |
5377d91f | 380 | |
18759441 | 381 | - 6.5 ± 0.001 |
5377d91f | 382 | |
18759441 | 383 | - 6.5 |
5377d91f | 384 | |
18759441 | 385 | - 6.5 [#f8]_ |
5377d91f MH |
386 | |
387 | ||
15e7d615 | 388 | Return Value |
5377d91f MH |
389 | ============ |
390 | ||
391 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
392 | appropriately. The generic error codes are described at the | |
393 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
394 | ||
395 | EINVAL | |
396 | The struct :ref:`v4l2_standard <v4l2-standard>` ``index`` is out | |
397 | of bounds. | |
398 | ||
399 | ENODATA | |
400 | Standard video timings are not supported for this input or output. | |
401 | ||
4855307b | 402 | .. [#f1] |
5377d91f | 403 | The supported standards may overlap and we need an unambiguous set to |
4e03cb76 | 404 | find the current standard returned by :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`. |
5377d91f | 405 | |
4855307b | 406 | .. [#f2] |
5377d91f MH |
407 | Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP). |
408 | ||
4855307b | 409 | .. [#f3] |
5377d91f | 410 | The values in brackets apply to the combination N/PAL a.k.a. |
eba9e91c | 411 | N\ :sub:`C` used in Argentina (V4L2_STD_PAL_Nc). |
5377d91f | 412 | |
4855307b | 413 | .. [#f4] |
5377d91f MH |
414 | In the Federal Republic of Germany, Austria, Italy, the Netherlands, |
415 | Slovakia and Switzerland a system of two sound carriers is used, the | |
416 | frequency of the second carrier being 242.1875 kHz above the | |
417 | frequency of the first sound carrier. For stereophonic sound | |
418 | transmissions a similar system is used in Australia. | |
419 | ||
4855307b | 420 | .. [#f5] |
5377d91f MH |
421 | New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from |
422 | the vision carrier. | |
423 | ||
4855307b | 424 | .. [#f6] |
5377d91f MH |
425 | In Denmark, Finland, New Zealand, Sweden and Spain a system of two |
426 | sound carriers is used. In Iceland, Norway and Poland the same system | |
427 | is being introduced. The second carrier is 5.85 MHz above the vision | |
428 | carrier and is DQPSK modulated with 728 kbit/s sound and data | |
429 | multiplex. (NICAM system) | |
430 | ||
4855307b | 431 | .. [#f7] |
5377d91f MH |
432 | In the United Kingdom, a system of two sound carriers is used. The |
433 | second sound carrier is 6.552 MHz above the vision carrier and is | |
434 | DQPSK modulated with a 728 kbit/s sound and data multiplex able to | |
435 | carry two sound channels. (NICAM system) | |
436 | ||
4855307b | 437 | .. [#f8] |
5377d91f MH |
438 | In France, a digital carrier 5.85 MHz away from the vision carrier |
439 | may be used in addition to the main sound carrier. It is modulated in | |
440 | differentially encoded QPSK with a 728 kbit/s sound and data | |
441 | multiplexer capable of carrying two sound channels. (NICAM system) |