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