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