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