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