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