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