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