0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _standard:
0004
0005 ***************
0006 Video Standards
0007 ***************
0008
0009 Video devices typically support one or more different video standards or
0010 variations of standards. Each video input and output may support another
0011 set of standards. This set is reported by the ``std`` field of struct
0012 :c:type:`v4l2_input` and struct
0013 :c:type:`v4l2_output` returned by the
0014 :ref:`VIDIOC_ENUMINPUT` and
0015 :ref:`VIDIOC_ENUMOUTPUT` ioctls, respectively.
0016
0017 V4L2 defines one bit for each analog video standard currently in use
0018 worldwide, and sets aside bits for driver defined standards, e. g.
0019 hybrid standards to watch NTSC video tapes on PAL TVs and vice versa.
0020 Applications can use the predefined bits to select a particular
0021 standard, although presenting the user a menu of supported standards is
0022 preferred. To enumerate and query the attributes of the supported
0023 standards applications use the :ref:`VIDIOC_ENUMSTD`
0024 ioctl.
0025
0026 Many of the defined standards are actually just variations of a few
0027 major standards. The hardware may in fact not distinguish between them,
0028 or do so internal and switch automatically. Therefore enumerated
0029 standards also contain sets of one or more standard bits.
0030
0031 Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL
0032 signals. The first enumerated standard is a set of B and G/PAL, switched
0033 automatically depending on the selected radio frequency in UHF or VHF
0034 band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a
0035 Composite input may collapse standards, enumerating "PAL-B/G/H/I",
0036 "NTSC-M" and "SECAM-D/K". [#f1]_
0037
0038 To query and select the standard used by the current video input or
0039 output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
0040 :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctl, respectively. The
0041 *received* standard can be sensed with the
0042 :ref:`VIDIOC_QUERYSTD` ioctl.
0043
0044 .. note::
0045
0046 The parameter of all these ioctls is a pointer to a
0047 :ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an
0048 index into the standard enumeration. Drivers must implement all video
0049 standard ioctls when the device has one or more video inputs or outputs.
0050
0051 Special rules apply to devices such as USB cameras where the notion of
0052 video standards makes little sense. More generally for any capture or
0053 output device which is:
0054
0055 - incapable of capturing fields or frames at the nominal rate of the
0056 video standard, or
0057
0058 - that does not support the video standard formats at all.
0059
0060 Here the driver shall set the ``std`` field of struct
0061 :c:type:`v4l2_input` and struct
0062 :c:type:`v4l2_output` to zero and the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`,
0063 :ref:`VIDIOC_S_STD <VIDIOC_G_STD>`, :ref:`VIDIOC_QUERYSTD` and :ref:`VIDIOC_ENUMSTD` ioctls
0064 shall return the ``ENOTTY`` error code or the ``EINVAL`` error code.
0065
0066 Applications can make use of the :ref:`input-capabilities` and
0067 :ref:`output-capabilities` flags to determine whether the video
0068 standard ioctls can be used with the given input or output.
0069
0070 Example: Information about the current video standard
0071 =====================================================
0072
0073 .. code-block:: c
0074
0075 v4l2_std_id std_id;
0076 struct v4l2_standard standard;
0077
0078 if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) {
0079 /* Note when VIDIOC_ENUMSTD always returns ENOTTY this
0080 is no video device or it falls under the USB exception,
0081 and VIDIOC_G_STD returning ENOTTY is no error. */
0082
0083 perror("VIDIOC_G_STD");
0084 exit(EXIT_FAILURE);
0085 }
0086
0087 memset(&standard, 0, sizeof(standard));
0088 standard.index = 0;
0089
0090 while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
0091 if (standard.id & std_id) {
0092 printf("Current video standard: %s\\n", standard.name);
0093 exit(EXIT_SUCCESS);
0094 }
0095
0096 standard.index++;
0097 }
0098
0099 /* EINVAL indicates the end of the enumeration, which cannot be
0100 empty unless this device falls under the USB exception. */
0101
0102 if (errno == EINVAL || standard.index == 0) {
0103 perror("VIDIOC_ENUMSTD");
0104 exit(EXIT_FAILURE);
0105 }
0106
0107 Example: Listing the video standards supported by the current input
0108 ===================================================================
0109
0110 .. code-block:: c
0111
0112 struct v4l2_input input;
0113 struct v4l2_standard standard;
0114
0115 memset(&input, 0, sizeof(input));
0116
0117 if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
0118 perror("VIDIOC_G_INPUT");
0119 exit(EXIT_FAILURE);
0120 }
0121
0122 if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
0123 perror("VIDIOC_ENUM_INPUT");
0124 exit(EXIT_FAILURE);
0125 }
0126
0127 printf("Current input %s supports:\\n", input.name);
0128
0129 memset(&standard, 0, sizeof(standard));
0130 standard.index = 0;
0131
0132 while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
0133 if (standard.id & input.std)
0134 printf("%s\\n", standard.name);
0135
0136 standard.index++;
0137 }
0138
0139 /* EINVAL indicates the end of the enumeration, which cannot be
0140 empty unless this device falls under the USB exception. */
0141
0142 if (errno != EINVAL || standard.index == 0) {
0143 perror("VIDIOC_ENUMSTD");
0144 exit(EXIT_FAILURE);
0145 }
0146
0147 Example: Selecting a new video standard
0148 =======================================
0149
0150 .. code-block:: c
0151
0152 struct v4l2_input input;
0153 v4l2_std_id std_id;
0154
0155 memset(&input, 0, sizeof(input));
0156
0157 if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
0158 perror("VIDIOC_G_INPUT");
0159 exit(EXIT_FAILURE);
0160 }
0161
0162 if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
0163 perror("VIDIOC_ENUM_INPUT");
0164 exit(EXIT_FAILURE);
0165 }
0166
0167 if (0 == (input.std & V4L2_STD_PAL_BG)) {
0168 fprintf(stderr, "Oops. B/G PAL is not supported.\\n");
0169 exit(EXIT_FAILURE);
0170 }
0171
0172 /* Note this is also supposed to work when only B
0173 or G/PAL is supported. */
0174
0175 std_id = V4L2_STD_PAL_BG;
0176
0177 if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) {
0178 perror("VIDIOC_S_STD");
0179 exit(EXIT_FAILURE);
0180 }
0181
0182 .. [#f1]
0183 Some users are already confused by technical terms PAL, NTSC and
0184 SECAM. There is no point asking them to distinguish between B, G, D,
0185 or K when the software or hardware can do that automatically.
