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 <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 :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`,
  60 :ref:`VIDIOC_S_STD <VIDIOC_G_STD>`, :ref:`VIDIOC_QUERYSTD` and :ref:`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     :caption: Example 5: Information about the current video standard
  70
  71     v4l2_std_id std_id;
  72     struct v4l2_standard standard;
  73
  74     if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) {
  75         /* Note when VIDIOC_ENUMSTD always returns ENOTTY this
  76            is no video device or it falls under the USB exception,
  77            and VIDIOC_G_STD returning ENOTTY is no error. */
  78
  79         perror("VIDIOC_G_STD");
  80         exit(EXIT_FAILURE);
  81     }
  82
  83     memset(&standard, 0, sizeof(standard));
  84     standard.index = 0;
  85
  86     while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
  87         if (standard.id & std_id) {
  88                printf("Current video standard: %s\\n", standard.name);
  89                exit(EXIT_SUCCESS);
  90         }
  91
  92         standard.index++;
  93     }
  94
  95     /* EINVAL indicates the end of the enumeration, which cannot be
  96        empty unless this device falls under the USB exception. */
  97
  98     if (errno == EINVAL || standard.index == 0) {
  99         perror("VIDIOC_ENUMSTD");
 100         exit(EXIT_FAILURE);
 101     }
 102
 103
 104 .. code-block:: c
 105     :caption: Example 6: Listing the video standards supported by the current input
 106
 107     struct v4l2_input input;
 108     struct v4l2_standard standard;
 109
 110     memset(&input, 0, sizeof(input));
 111
 112     if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
 113         perror("VIDIOC_G_INPUT");
 114         exit(EXIT_FAILURE);
 115     }
 116
 117     if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
 118         perror("VIDIOC_ENUM_INPUT");
 119         exit(EXIT_FAILURE);
 120     }
 121
 122     printf("Current input %s supports:\\n", input.name);
 123
 124     memset(&standard, 0, sizeof(standard));
 125     standard.index = 0;
 126
 127     while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
 128         if (standard.id & input.std)
 129             printf("%s\\n", standard.name);
 130
 131         standard.index++;
 132     }
 133
 134     /* EINVAL indicates the end of the enumeration, which cannot be
 135        empty unless this device falls under the USB exception. */
 136
 137     if (errno != EINVAL || standard.index == 0) {
 138         perror("VIDIOC_ENUMSTD");
 139         exit(EXIT_FAILURE);
 140     }
 141
 142
 143 .. code-block:: c
 144     :caption: Example 7: Selecting a new video standard
 145
 146     struct v4l2_input input;
 147     v4l2_std_id std_id;
 148
 149     memset(&input, 0, sizeof(input));
 150
 151     if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
 152         perror("VIDIOC_G_INPUT");
 153         exit(EXIT_FAILURE);
 154     }
 155
 156     if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
 157         perror("VIDIOC_ENUM_INPUT");
 158         exit(EXIT_FAILURE);
 159     }
 160
 161     if (0 == (input.std & V4L2_STD_PAL_BG)) {
 162         fprintf(stderr, "Oops. B/G PAL is not supported.\\n");
 163         exit(EXIT_FAILURE);
 164     }
 165
 166     /* Note this is also supposed to work when only B
 167        or G/PAL is supported. */
 168
 169     std_id = V4L2_STD_PAL_BG;
 170
 171     if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) {
 172         perror("VIDIOC_S_STD");
 173         exit(EXIT_FAILURE);
 174     }
 175
 176 .. [1]
 177    Some users are already confused by technical terms PAL, NTSC and
 178    SECAM. There is no point asking them to distinguish between B, G, D,
 179    or K when the software or hardware can do that automatically.
 180
 181
 182 .. ------------------------------------------------------------------------------
 183 .. This file was automatically converted from DocBook-XML with the dbxml
 184 .. library (https://github.com/return42/sphkerneldoc). The origin XML comes
 185 .. from the linux kernel, refer to:
 186 ..
 187 .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
 188 .. ------------------------------------------------------------------------------