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 [])
 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
 334           ± 2000
 335
 336     -  .. row 5
 337
 338        -  Nominal radio-frequency channel bandwidth (MHz)
 339
 340        -  6
 341
 342        -  6
 343
 344        -  6
 345
 346        -  B: 7; B1, G: 8
 347
 348        -  8
 349
 350        -  8
 351
 352        -  8
 353
 354        -  8
 355
 356        -  8
 357
 358        -  8
 359
 360        -  8
 361
 362     -  .. row 6
 363
 364        -  Sound carrier relative to vision carrier (MHz)
 365
 366        -  + 4.5
 367
 368        -  + 4.5
 369
 370        -  + 4.5
 371
 372        -  + 5.5 ± 0.001  [#f4]_  [#f5]_  [#f6]_  [#f7]_
 373
 374        -  + 6.5 ± 0.001
 375
 376        -  + 5.5
 377
 378        -  + 5.9996 ± 0.0005
 379
 380        -  + 5.5 ± 0.001
 381
 382        -  + 6.5 ± 0.001
 383
 384        -  + 6.5
 385
 386        -  + 6.5  [#f8]_
 387
 388
 389 Return Value
 390 ============
 391
 392 On success 0 is returned, on error -1 and the ``errno`` variable is set
 393 appropriately. The generic error codes are described at the
 394 :ref:`Generic Error Codes <gen-errors>` chapter.
 395
 396 EINVAL
 397     The struct :ref:`v4l2_standard <v4l2-standard>` ``index`` is out
 398     of bounds.
 399
 400 ENODATA
 401     Standard video timings are not supported for this input or output.
 402
 403 .. [#f1]
 404    The supported standards may overlap and we need an unambiguous set to
 405    find the current standard returned by :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`.
 406
 407 .. [#f2]
 408    Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP).
 409
 410 .. [#f3]
 411    The values in brackets apply to the combination N/PAL a.k.a.
 412    N\ :sub:`C` used in Argentina (V4L2_STD_PAL_Nc).
 413
 414 .. [#f4]
 415    In the Federal Republic of Germany, Austria, Italy, the Netherlands,
 416    Slovakia and Switzerland a system of two sound carriers is used, the
 417    frequency of the second carrier being 242.1875 kHz above the
 418    frequency of the first sound carrier. For stereophonic sound
 419    transmissions a similar system is used in Australia.
 420
 421 .. [#f5]
 422    New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from
 423    the vision carrier.
 424
 425 .. [#f6]
 426    In Denmark, Finland, New Zealand, Sweden and Spain a system of two
 427    sound carriers is used. In Iceland, Norway and Poland the same system
 428    is being introduced. The second carrier is 5.85 MHz above the vision
 429    carrier and is DQPSK modulated with 728 kbit/s sound and data
 430    multiplex. (NICAM system)
 431
 432 .. [#f7]
 433    In the United Kingdom, a system of two sound carriers is used. The
 434    second sound carrier is 6.552 MHz above the vision carrier and is
 435    DQPSK modulated with a 728 kbit/s sound and data multiplex able to
 436    carry two sound channels. (NICAM system)
 437
 438 .. [#f8]
 439    In France, a digital carrier 5.85 MHz away from the vision carrier
 440    may be used in addition to the main sound carrier. It is modulated in
 441    differentially encoded QPSK with a 728 kbit/s sound and data
 442    multiplexer capable of carrying two sound channels. (NICAM system)