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