Documentation/media/uapi/v4l/vidioc-enumstd.rst

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