Documentation/media/uapi/v4l/vidioc-enumstd.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_ENUMSTD:
   4
   5 ********************
   6 ioctl VIDIOC_ENUMSTD
   7 ********************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_ENUMSTD - Enumerate supported video standards
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp )
  19     :name: VIDIOC_ENUMSTD
  20
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :ref:`open() <func-open>`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`v4l2_standard`.
  30
  31
  32 Description
  33 ===========
  34
  35 To query the attributes of a video standard, especially a custom (driver
  36 defined) one, applications initialize the ``index`` field of struct
  37 :c:type:`v4l2_standard` and call the :ref:`VIDIOC_ENUMSTD`
  38 ioctl with a pointer to this structure. Drivers fill the rest of the
  39 structure or return an ``EINVAL`` error code when the index is out of
  40 bounds. To enumerate all standards applications shall begin at index
  41 zero, incrementing by one until the driver returns ``EINVAL``. Drivers may
  42 enumerate a different set of standards after switching the video input
  43 or output. [#f1]_
  44
  45
  46 .. c:type:: v4l2_standard
  47
  48 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  49
  50 .. flat-table:: struct v4l2_standard
  51     :header-rows:  0
  52     :stub-columns: 0
  53     :widths:       1 1 2
  54
  55     * - __u32
  56       - ``index``
  57       - Number of the video standard, set by the application.
  58     * - :ref:`v4l2_std_id <v4l2-std-id>`
  59       - ``id``
  60       - The bits in this field identify the standard as one of the common
  61         standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are
  62         set as custom standards. Multiple bits can be set if the hardware
  63         does not distinguish between these standards, however separate
  64         indices do not indicate the opposite. The ``id`` must be unique.
  65         No other enumerated struct :c:type:`v4l2_standard` structure,
  66         for this input or output anyway, can contain the same set of bits.
  67     * - __u8
  68       - ``name``\ [24]
  69       - Name of the standard, a NUL-terminated ASCII string, for example:
  70         "PAL-B/G", "NTSC Japan". This information is intended for the
  71         user.
  72     * - struct :c:type:`v4l2_fract`
  73       - ``frameperiod``
  74       - The frame period (not field period) is numerator / denominator.
  75         For example M/NTSC has a frame period of 1001 / 30000 seconds.
  76     * - __u32
  77       - ``framelines``
  78       - Total lines per frame including blanking, e. g. 625 for B/PAL.
  79     * - __u32
  80       - ``reserved``\ [4]
  81       - Reserved for future extensions. Drivers must set the array to
  82         zero.
  83
  84
  85
  86 .. c:type:: v4l2_fract
  87
  88 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  89
  90 .. flat-table:: struct v4l2_fract
  91     :header-rows:  0
  92     :stub-columns: 0
  93     :widths:       1 1 2
  94
  95     * - __u32
  96       - ``numerator``
  97       -
  98     * - __u32
  99       - ``denominator``
 100       -
 101
 102
 103 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 104
 105 .. _v4l2-std-id:
 106
 107 .. flat-table:: typedef v4l2_std_id
 108     :header-rows:  0
 109     :stub-columns: 0
 110     :widths:       1 1 2
 111
 112     * - __u64
 113       - ``v4l2_std_id``
 114       - This type is a set, each bit representing another video standard
 115         as listed below and in :ref:`video-standards`. The 32 most
 116         significant bits are reserved for custom (driver defined) video
 117         standards.
 118
 119
 120
 121 .. code-block:: c
 122
 123     #define V4L2_STD_PAL_B          ((v4l2_std_id)0x00000001)
 124     #define V4L2_STD_PAL_B1         ((v4l2_std_id)0x00000002)
 125     #define V4L2_STD_PAL_G          ((v4l2_std_id)0x00000004)
 126     #define V4L2_STD_PAL_H          ((v4l2_std_id)0x00000008)
 127     #define V4L2_STD_PAL_I          ((v4l2_std_id)0x00000010)
 128     #define V4L2_STD_PAL_D          ((v4l2_std_id)0x00000020)
 129     #define V4L2_STD_PAL_D1         ((v4l2_std_id)0x00000040)
 130     #define V4L2_STD_PAL_K          ((v4l2_std_id)0x00000080)
 131
 132     #define V4L2_STD_PAL_M          ((v4l2_std_id)0x00000100)
 133     #define V4L2_STD_PAL_N          ((v4l2_std_id)0x00000200)
 134     #define V4L2_STD_PAL_Nc         ((v4l2_std_id)0x00000400)
 135     #define V4L2_STD_PAL_60         ((v4l2_std_id)0x00000800)
 136
 137 ``V4L2_STD_PAL_60`` is a hybrid standard with 525 lines, 60 Hz refresh
 138 rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some
 139 PAL video recorders can play back NTSC tapes in this mode for display on
 140 a 50/60 Hz agnostic PAL TV.
 141
 142
 143 .. code-block:: c
 144
 145     #define V4L2_STD_NTSC_M         ((v4l2_std_id)0x00001000)
 146     #define V4L2_STD_NTSC_M_JP      ((v4l2_std_id)0x00002000)
 147     #define V4L2_STD_NTSC_443       ((v4l2_std_id)0x00004000)
 148
 149 ``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh
 150 rate, and NTSC color modulation with a 4.43 MHz color subcarrier.
 151
 152
 153 .. code-block:: c
 154
 155     #define V4L2_STD_NTSC_M_KR      ((v4l2_std_id)0x00008000)
 156
 157     #define V4L2_STD_SECAM_B        ((v4l2_std_id)0x00010000)
 158     #define V4L2_STD_SECAM_D        ((v4l2_std_id)0x00020000)
 159     #define V4L2_STD_SECAM_G        ((v4l2_std_id)0x00040000)
 160     #define V4L2_STD_SECAM_H        ((v4l2_std_id)0x00080000)
 161     #define V4L2_STD_SECAM_K        ((v4l2_std_id)0x00100000)
 162     #define V4L2_STD_SECAM_K1       ((v4l2_std_id)0x00200000)
 163     #define V4L2_STD_SECAM_L        ((v4l2_std_id)0x00400000)
 164     #define V4L2_STD_SECAM_LC       ((v4l2_std_id)0x00800000)
 165
 166     /* ATSC/HDTV */
 167     #define V4L2_STD_ATSC_8_VSB     ((v4l2_std_id)0x01000000)
 168     #define V4L2_STD_ATSC_16_VSB    ((v4l2_std_id)0x02000000)
 169
 170 ``V4L2_STD_ATSC_8_VSB`` and ``V4L2_STD_ATSC_16_VSB`` are U.S.
 171 terrestrial digital TV standards. Presently the V4L2 API does not
 172 support digital TV. See also the Linux DVB API at
 173 `https://linuxtv.org <https://linuxtv.org>`__.
 174
 175
 176 .. code-block:: c
 177
 178     #define V4L2_STD_PAL_BG         (V4L2_STD_PAL_B         |
 179                      V4L2_STD_PAL_B1        |
 180                      V4L2_STD_PAL_G)
 181     #define V4L2_STD_B              (V4L2_STD_PAL_B         |
 182                      V4L2_STD_PAL_B1        |
 183                      V4L2_STD_SECAM_B)
 184     #define V4L2_STD_GH             (V4L2_STD_PAL_G         |
 185                      V4L2_STD_PAL_H         |
 186                      V4L2_STD_SECAM_G       |
 187                      V4L2_STD_SECAM_H)
 188     #define V4L2_STD_PAL_DK         (V4L2_STD_PAL_D         |
 189                      V4L2_STD_PAL_D1        |
 190                      V4L2_STD_PAL_K)
 191     #define V4L2_STD_PAL            (V4L2_STD_PAL_BG        |
 192                      V4L2_STD_PAL_DK        |
 193                      V4L2_STD_PAL_H         |
 194                      V4L2_STD_PAL_I)
 195     #define V4L2_STD_NTSC           (V4L2_STD_NTSC_M        |
 196                      V4L2_STD_NTSC_M_JP     |
 197                      V4L2_STD_NTSC_M_KR)
 198     #define V4L2_STD_MN             (V4L2_STD_PAL_M         |
 199                      V4L2_STD_PAL_N         |
 200                      V4L2_STD_PAL_Nc        |
 201                      V4L2_STD_NTSC)
 202     #define V4L2_STD_SECAM_DK       (V4L2_STD_SECAM_D       |
 203                      V4L2_STD_SECAM_K       |
 204                      V4L2_STD_SECAM_K1)
 205     #define V4L2_STD_DK             (V4L2_STD_PAL_DK        |
 206                      V4L2_STD_SECAM_DK)
 207
 208     #define V4L2_STD_SECAM          (V4L2_STD_SECAM_B       |
 209                      V4L2_STD_SECAM_G       |
 210                      V4L2_STD_SECAM_H       |
 211                      V4L2_STD_SECAM_DK      |
 212                      V4L2_STD_SECAM_L       |
 213                      V4L2_STD_SECAM_LC)
 214
 215     #define V4L2_STD_525_60         (V4L2_STD_PAL_M         |
 216                      V4L2_STD_PAL_60        |
 217                      V4L2_STD_NTSC          |
 218                      V4L2_STD_NTSC_443)
 219     #define V4L2_STD_625_50         (V4L2_STD_PAL           |
 220                      V4L2_STD_PAL_N         |
 221                      V4L2_STD_PAL_Nc        |
 222                      V4L2_STD_SECAM)
 223
 224     #define V4L2_STD_UNKNOWN        0
 225     #define V4L2_STD_ALL            (V4L2_STD_525_60        |
 226                      V4L2_STD_625_50)
 227
 228
 229 .. raw:: latex
 230
 231     \begingroup
 232     \tiny
 233     \setlength{\tabcolsep}{2pt}
 234
 235 ..                            NTSC/M   PAL/M    /N       /B       /D       /H       /I        SECAM/B    /D       /K1     /L
 236 .. tabularcolumns:: |p{1.43cm}|p{1.38cm}|p{1.59cm}|p{1.7cm}|p{1.7cm}|p{1.17cm}|p{0.64cm}|p{1.71cm}|p{1.6cm}|p{1.07cm}|p{1.07cm}|p{1.07cm}|
 237
 238 .. _video-standards:
 239
 240 .. flat-table:: Video Standards (based on :ref:`itu470`)
 241     :header-rows:  1
 242     :stub-columns: 0
 243
 244     * - Characteristics
 245       - M/NTSC [#f2]_
 246       - M/PAL
 247       - N/PAL [#f3]_
 248       - B, B1, G/PAL
 249       - D, D1, K/PAL
 250       - H/PAL
 251       - I/PAL
 252       - B, G/SECAM
 253       - D, K/SECAM
 254       - K1/SECAM
 255       - L/SECAM
 256     * - Frame lines
 257       - :cspan:`1` 525
 258       - :cspan:`8` 625
 259     * - Frame period (s)
 260       - :cspan:`1` 1001/30000
 261       - :cspan:`8` 1/25
 262     * - Chrominance sub-carrier frequency (Hz)
 263       - 3579545 ± 10
 264       - 3579611.49 ± 10
 265       - 4433618.75 ± 5
 266
 267         (3582056.25 ± 5)
 268       - :cspan:`3` 4433618.75 ± 5
 269       - 4433618.75 ± 1
 270       - :cspan:`2` f\ :sub:`OR` = 4406250 ± 2000,
 271
 272         f\ :sub:`OB` = 4250000 ± 2000
 273     * - Nominal radio-frequency channel bandwidth (MHz)
 274       - 6
 275       - 6
 276       - 6
 277       - B: 7; B1, G: 8
 278       - 8
 279       - 8
 280       - 8
 281       - 8
 282       - 8
 283       - 8
 284       - 8
 285     * - Sound carrier relative to vision carrier (MHz)
 286       - 4.5
 287       - 4.5
 288       - 4.5
 289       - 5.5 ± 0.001  [#f4]_  [#f5]_  [#f6]_  [#f7]_
 290       - 6.5 ± 0.001
 291       - 5.5
 292       - 5.9996 ± 0.0005
 293       - 5.5 ± 0.001
 294       - 6.5 ± 0.001
 295       - 6.5
 296       - 6.5 [#f8]_
 297
 298 .. raw:: latex
 299
 300     \endgroup
 301
 302
 303
 304 Return Value
 305 ============
 306
 307 On success 0 is returned, on error -1 and the ``errno`` variable is set
 308 appropriately. The generic error codes are described at the
 309 :ref:`Generic Error Codes <gen-errors>` chapter.
 310
 311 EINVAL
 312     The struct :c:type:`v4l2_standard` ``index`` is out
 313     of bounds.
 314
 315 ENODATA
 316     Standard video timings are not supported for this input or output.
 317
 318 .. [#f1]
 319    The supported standards may overlap and we need an unambiguous set to
 320    find the current standard returned by :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`.
 321
 322 .. [#f2]
 323    Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP).
 324
 325 .. [#f3]
 326    The values in brackets apply to the combination N/PAL a.k.a.
 327    N\ :sub:`C` used in Argentina (V4L2_STD_PAL_Nc).
 328
 329 .. [#f4]
 330    In the Federal Republic of Germany, Austria, Italy, the Netherlands,
 331    Slovakia and Switzerland a system of two sound carriers is used, the
 332    frequency of the second carrier being 242.1875 kHz above the
 333    frequency of the first sound carrier. For stereophonic sound
 334    transmissions a similar system is used in Australia.
 335
 336 .. [#f5]
 337    New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from
 338    the vision carrier.
 339
 340 .. [#f6]
 341    In Denmark, Finland, New Zealand, Sweden and Spain a system of two
 342    sound carriers is used. In Iceland, Norway and Poland the same system
 343    is being introduced. The second carrier is 5.85 MHz above the vision
 344    carrier and is DQPSK modulated with 728 kbit/s sound and data
 345    multiplex. (NICAM system)
 346
 347 .. [#f7]
 348    In the United Kingdom, a system of two sound carriers is used. The
 349    second sound carrier is 6.552 MHz above the vision carrier and is
 350    DQPSK modulated with a 728 kbit/s sound and data multiplex able to
 351    carry two sound channels. (NICAM system)
 352
 353 .. [#f8]
 354    In France, a digital carrier 5.85 MHz away from the vision carrier
 355    may be used in addition to the main sound carrier. It is modulated in
 356    differentially encoded QPSK with a 728 kbit/s sound and data
 357    multiplexer capable of carrying two sound channels. (NICAM system)