186 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3.. _standard:4 5***************6Video Standards7***************8 9Video devices typically support one or more different video standards or10variations of standards. Each video input and output may support another11set of standards. This set is reported by the ``std`` field of struct12:c:type:`v4l2_input` and struct13:c:type:`v4l2_output` returned by the14:ref:`VIDIOC_ENUMINPUT` and15:ref:`VIDIOC_ENUMOUTPUT` ioctls, respectively.16 17V4L2 defines one bit for each analog video standard currently in use18worldwide, 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 particular21standard, although presenting the user a menu of supported standards is22preferred. To enumerate and query the attributes of the supported23standards applications use the :ref:`VIDIOC_ENUMSTD`24ioctl.25 26Many of the defined standards are actually just variations of a few27major standards. The hardware may in fact not distinguish between them,28or do so internal and switch automatically. Therefore enumerated29standards also contain sets of one or more standard bits.30 31Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL32signals. The first enumerated standard is a set of B and G/PAL, switched33automatically depending on the selected radio frequency in UHF or VHF34band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a35Composite 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 or39output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and40:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctl, respectively. The41*received* standard can be sensed with the42:ref:`VIDIOC_QUERYSTD` ioctl.43 44.. note::45 46 The parameter of all these ioctls is a pointer to a47 :ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an48 index into the standard enumeration. Drivers must implement all video49 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 of52video standards makes little sense. More generally for any capture or53output device which is:54 55- incapable of capturing fields or frames at the nominal rate of the56 video standard, or57 58- that does not support the video standard formats at all.59 60Here the driver shall set the ``std`` field of struct61:c:type:`v4l2_input` and struct62: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` ioctls64shall return the ``ENOTTY`` error code or the ``EINVAL`` error code.65 66Applications can make use of the :ref:`input-capabilities` and67:ref:`output-capabilities` flags to determine whether the video68standard ioctls can be used with the given input or output.69 70Example: Information about the current video standard71=====================================================72 73.. code-block:: c74 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 this80 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 be100 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 input108===================================================================109 110.. code-block:: c111 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 be140 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 standard148=======================================149 150.. code-block:: c151 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 B173 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 and184 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