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