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