Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _standard: | |
4 | ||
5 | *************** | |
6 | Video Standards | |
7 | *************** | |
8 | ||
9 | Video devices typically support one or more different video standards or | |
10 | variations of standards. Each video input and output may support another | |
11 | set of standards. This set is reported by the ``std`` field of struct | |
12 | :ref:`v4l2_input <v4l2-input>` and struct | |
13 | :ref:`v4l2_output <v4l2-output>` returned by the | |
7347081e MCC |
14 | :ref:`VIDIOC_ENUMINPUT` and |
15 | :ref:`VIDIOC_ENUMOUTPUT` ioctls, respectively. | |
5377d91f MH |
16 | |
17 | V4L2 defines one bit for each analog video standard currently in use | |
18 | worldwide, and sets aside bits for driver defined standards, e. g. | |
19 | hybrid standards to watch NTSC video tapes on PAL TVs and vice versa. | |
20 | Applications can use the predefined bits to select a particular | |
21 | standard, although presenting the user a menu of supported standards is | |
22 | preferred. To enumerate and query the attributes of the supported | |
7347081e | 23 | standards applications use the :ref:`VIDIOC_ENUMSTD` |
5377d91f MH |
24 | ioctl. |
25 | ||
26 | Many of the defined standards are actually just variations of a few | |
27 | major standards. The hardware may in fact not distinguish between them, | |
28 | or do so internal and switch automatically. Therefore enumerated | |
29 | standards also contain sets of one or more standard bits. | |
30 | ||
31 | Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL | |
32 | signals. The first enumerated standard is a set of B and G/PAL, switched | |
33 | automatically depending on the selected radio frequency in UHF or VHF | |
34 | band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a | |
35 | Composite input may collapse standards, enumerating "PAL-B/G/H/I", | |
36 | "NTSC-M" and "SECAM-D/K". [1]_ | |
37 | ||
38 | To query and select the standard used by the current video input or | |
4e03cb76 | 39 | output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and |
af4a4d0d | 40 | :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctl, respectively. The |
5377d91f | 41 | *received* standard can be sensed with the |
7347081e | 42 | :ref:`VIDIOC_QUERYSTD` ioctl. Note that the |
5377d91f MH |
43 | parameter of all these ioctls is a pointer to a |
44 | :ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an | |
45 | index into the standard enumeration. Drivers must implement all video | |
46 | standard ioctls when the device has one or more video inputs or outputs. | |
47 | ||
48 | Special rules apply to devices such as USB cameras where the notion of | |
49 | video standards makes little sense. More generally for any capture or | |
50 | output device which is: | |
51 | ||
52 | - incapable of capturing fields or frames at the nominal rate of the | |
53 | video standard, or | |
54 | ||
55 | - that does not support the video standard formats at all. | |
56 | ||
57 | Here the driver shall set the ``std`` field of struct | |
58 | :ref:`v4l2_input <v4l2-input>` and struct | |
4e03cb76 | 59 | :ref:`v4l2_output <v4l2-output>` to zero and the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`, |
2212ff25 | 60 | :ref:`VIDIOC_S_STD <VIDIOC_G_STD>`, :ref:`VIDIOC_QUERYSTD` and :ref:`VIDIOC_ENUMSTD` ioctls |
cdb4af0f | 61 | shall return the ``ENOTTY`` error code or the ``EINVAL`` error code. |
5377d91f MH |
62 | |
63 | Applications can make use of the :ref:`input-capabilities` and | |
64 | :ref:`output-capabilities` flags to determine whether the video | |
65 | standard ioctls can be used with the given input or output. | |
66 | ||
67 | ||
68 | .. code-block:: c | |
da1621c3 | 69 | :caption: Example 1.5. Information about the current video standard |
5377d91f MH |
70 | |
71 | v4l2_std_id std_id; | |
72 | struct v4l2_standard standard; | |
73 | ||
74 | if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) { | |
0579e6e3 MCC |
75 | /* Note when VIDIOC_ENUMSTD always returns ENOTTY this |
76 | is no video device or it falls under the USB exception, | |
77 | and VIDIOC_G_STD returning ENOTTY is no error. */ | |
5377d91f | 78 | |
0579e6e3 MCC |
79 | perror("VIDIOC_G_STD"); |
80 | exit(EXIT_FAILURE); | |
5377d91f MH |
81 | } |
82 | ||
83 | memset(&standard, 0, sizeof(standard)); | |
84 | standard.index = 0; | |
85 | ||
86 | while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) { | |
0579e6e3 MCC |
87 | if (standard.id & std_id) { |
88 | printf("Current video standard: %s\\n", standard.name); | |
89 | exit(EXIT_SUCCESS); | |
90 | } | |
5377d91f | 91 | |
0579e6e3 | 92 | standard.index++; |
5377d91f MH |
93 | } |
94 | ||
95 | /* EINVAL indicates the end of the enumeration, which cannot be | |
96 | empty unless this device falls under the USB exception. */ | |
97 | ||
98 | if (errno == EINVAL || standard.index == 0) { | |
0579e6e3 MCC |
99 | perror("VIDIOC_ENUMSTD"); |
100 | exit(EXIT_FAILURE); | |
5377d91f MH |
101 | } |
102 | ||
103 | ||
104 | .. code-block:: c | |
da1621c3 | 105 | :caption: Example 1.6. Listing the video standards supported by the current input |
5377d91f MH |
106 | |
107 | struct v4l2_input input; | |
108 | struct v4l2_standard standard; | |
109 | ||
110 | memset(&input, 0, sizeof(input)); | |
111 | ||
112 | if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) { | |
0579e6e3 MCC |
113 | perror("VIDIOC_G_INPUT"); |
114 | exit(EXIT_FAILURE); | |
5377d91f MH |
115 | } |
116 | ||
117 | if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) { | |
0579e6e3 MCC |
118 | perror("VIDIOC_ENUM_INPUT"); |
119 | exit(EXIT_FAILURE); | |
5377d91f MH |
120 | } |
121 | ||
122 | printf("Current input %s supports:\\n", input.name); | |
123 | ||
124 | memset(&standard, 0, sizeof(standard)); | |
125 | standard.index = 0; | |
126 | ||
127 | while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) { | |
0579e6e3 MCC |
128 | if (standard.id & input.std) |
129 | printf("%s\\n", standard.name); | |
5377d91f | 130 | |
0579e6e3 | 131 | standard.index++; |
5377d91f MH |
132 | } |
133 | ||
134 | /* EINVAL indicates the end of the enumeration, which cannot be | |
135 | empty unless this device falls under the USB exception. */ | |
136 | ||
137 | if (errno != EINVAL || standard.index == 0) { | |
0579e6e3 MCC |
138 | perror("VIDIOC_ENUMSTD"); |
139 | exit(EXIT_FAILURE); | |
5377d91f MH |
140 | } |
141 | ||
142 | ||
143 | .. code-block:: c | |
da1621c3 | 144 | :caption: Example 1.7. Selecting a new video standard |
5377d91f MH |
145 | |
146 | struct v4l2_input input; | |
147 | v4l2_std_id std_id; | |
148 | ||
149 | memset(&input, 0, sizeof(input)); | |
150 | ||
151 | if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) { | |
0579e6e3 MCC |
152 | perror("VIDIOC_G_INPUT"); |
153 | exit(EXIT_FAILURE); | |
5377d91f MH |
154 | } |
155 | ||
156 | if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) { | |
0579e6e3 MCC |
157 | perror("VIDIOC_ENUM_INPUT"); |
158 | exit(EXIT_FAILURE); | |
5377d91f MH |
159 | } |
160 | ||
161 | if (0 == (input.std & V4L2_STD_PAL_BG)) { | |
0579e6e3 MCC |
162 | fprintf(stderr, "Oops. B/G PAL is not supported.\\n"); |
163 | exit(EXIT_FAILURE); | |
5377d91f MH |
164 | } |
165 | ||
166 | /* Note this is also supposed to work when only B | |
167 | or G/PAL is supported. */ | |
168 | ||
169 | std_id = V4L2_STD_PAL_BG; | |
170 | ||
171 | if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) { | |
0579e6e3 MCC |
172 | perror("VIDIOC_S_STD"); |
173 | exit(EXIT_FAILURE); | |
5377d91f MH |
174 | } |
175 | ||
176 | .. [1] | |
177 | Some users are already confused by technical terms PAL, NTSC and | |
178 | SECAM. There is no point asking them to distinguish between B, G, D, | |
179 | or K when the software or hardware can do that automatically. |