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