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 :ref:`v4l2_input <v4l2-input>` and struct
  13 :ref:`v4l2_output <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:: The parameter of all these ioctls is a pointer to a
  45    :ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an
  46    index into the standard enumeration. Drivers must implement all video
  47    standard ioctls when the device has one or more video inputs or outputs.
  48
  49 Special rules apply to devices such as USB cameras where the notion of
  50 video standards makes little sense. More generally for any capture or
  51 output device which is:
  52
  53 -  incapable of capturing fields or frames at the nominal rate of the
  54    video standard, or
  55
  56 -  that does not support the video standard formats at all.
  57
  58 Here the driver shall set the ``std`` field of struct
  59 :ref:`v4l2_input <v4l2-input>` and struct
  60 :ref:`v4l2_output <v4l2-output>` to zero and the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`,
  61 :ref:`VIDIOC_S_STD <VIDIOC_G_STD>`, :ref:`VIDIOC_QUERYSTD` and :ref:`VIDIOC_ENUMSTD` ioctls
  62 shall return the ``ENOTTY`` error code or the ``EINVAL`` error code.
  63
  64 Applications can make use of the :ref:`input-capabilities` and
  65 :ref:`output-capabilities` flags to determine whether the video
  66 standard ioctls can be used with the given input or output.
  67
  68 Example: Information about the current video standard
  69 =====================================================
  70
  71 .. code-block:: c
  72
  73     v4l2_std_id std_id;
  74     struct v4l2_standard standard;
  75
  76     if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) {
  77         /* Note when VIDIOC_ENUMSTD always returns ENOTTY this
  78            is no video device or it falls under the USB exception,
  79            and VIDIOC_G_STD returning ENOTTY is no error. */
  80
  81         perror("VIDIOC_G_STD");
  82         exit(EXIT_FAILURE);
  83     }
  84
  85     memset(&standard, 0, sizeof(standard));
  86     standard.index = 0;
  87
  88     while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
  89         if (standard.id & std_id) {
  90                printf("Current video standard: %s\\n", standard.name);
  91                exit(EXIT_SUCCESS);
  92         }
  93
  94         standard.index++;
  95     }
  96
  97     /* EINVAL indicates the end of the enumeration, which cannot be
  98        empty unless this device falls under the USB exception. */
  99
 100     if (errno == EINVAL || standard.index == 0) {
 101         perror("VIDIOC_ENUMSTD");
 102         exit(EXIT_FAILURE);
 103     }
 104
 105 Example: Listing the video standards supported by the current input
 106 ===================================================================
 107
 108 .. code-block:: c
 109
 110     struct v4l2_input input;
 111     struct v4l2_standard standard;
 112
 113     memset(&input, 0, sizeof(input));
 114
 115     if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
 116         perror("VIDIOC_G_INPUT");
 117         exit(EXIT_FAILURE);
 118     }
 119
 120     if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
 121         perror("VIDIOC_ENUM_INPUT");
 122         exit(EXIT_FAILURE);
 123     }
 124
 125     printf("Current input %s supports:\\n", input.name);
 126
 127     memset(&standard, 0, sizeof(standard));
 128     standard.index = 0;
 129
 130     while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
 131         if (standard.id & input.std)
 132             printf("%s\\n", standard.name);
 133
 134         standard.index++;
 135     }
 136
 137     /* EINVAL indicates the end of the enumeration, which cannot be
 138        empty unless this device falls under the USB exception. */
 139
 140     if (errno != EINVAL || standard.index == 0) {
 141         perror("VIDIOC_ENUMSTD");
 142         exit(EXIT_FAILURE);
 143     }
 144
 145 Example: Selecting a new video standard
 146 =======================================
 147
 148 .. code-block:: c
 149
 150     struct v4l2_input input;
 151     v4l2_std_id std_id;
 152
 153     memset(&input, 0, sizeof(input));
 154
 155     if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
 156         perror("VIDIOC_G_INPUT");
 157         exit(EXIT_FAILURE);
 158     }
 159
 160     if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
 161         perror("VIDIOC_ENUM_INPUT");
 162         exit(EXIT_FAILURE);
 163     }
 164
 165     if (0 == (input.std & V4L2_STD_PAL_BG)) {
 166         fprintf(stderr, "Oops. B/G PAL is not supported.\\n");
 167         exit(EXIT_FAILURE);
 168     }
 169
 170     /* Note this is also supposed to work when only B
 171        or G/PAL is supported. */
 172
 173     std_id = V4L2_STD_PAL_BG;
 174
 175     if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) {
 176         perror("VIDIOC_S_STD");
 177         exit(EXIT_FAILURE);
 178     }
 179
 180 .. [#f1]
 181    Some users are already confused by technical terms PAL, NTSC and
 182    SECAM. There is no point asking them to distinguish between B, G, D,
 183    or K when the software or hardware can do that automatically.