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

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