Documentation/media/uapi/v4l/standard.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _standard:
   4
   5 ***************
   6 Video Standards
   7 ***************
   8
   9 Video devices typically support one or more different video standards or
  10 variations of standards. Each video input and output may support another
  11 set 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
  17 V4L2 defines one bit for each analog video standard currently in use
  18 worldwide, and sets aside bits for driver defined standards, e. g.
  19 hybrid standards to watch NTSC video tapes on PAL TVs and vice versa.
  20 Applications can use the predefined bits to select a particular
  21 standard, although presenting the user a menu of supported standards is
  22 preferred. To enumerate and query the attributes of the supported
  23 standards applications use the :ref:`VIDIOC_ENUMSTD`
  24 ioctl.
  25
  26 Many of the defined standards are actually just variations of a few
  27 major standards. The hardware may in fact not distinguish between them,
  28 or do so internal and switch automatically. Therefore enumerated
  29 standards also contain sets of one or more standard bits.
  30
  31 Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL
  32 signals. The first enumerated standard is a set of B and G/PAL, switched
  33 automatically depending on the selected radio frequency in UHF or VHF
  34 band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a
  35 Composite input may collapse standards, enumerating "PAL-B/G/H/I",
  36 "NTSC-M" and "SECAM-D/K". [#f1]_
  37
  38 To query and select the standard used by the current video input or
  39 output 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
  51 Special rules apply to devices such as USB cameras where the notion of
  52 video standards makes little sense. More generally for any capture or
  53 output 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
  60 Here 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
  64 shall return the ``ENOTTY`` error code or the ``EINVAL`` error code.
  65
  66 Applications can make use of the :ref:`input-capabilities` and
  67 :ref:`output-capabilities` flags to determine whether the video
  68 standard ioctls can be used with the given input or output.
  69
  70 Example: 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
 107 Example: 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
 147 Example: 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.