Documentation/media/uapi/v4l/standard.rst

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