Documentation/userspace-api/media/v4l/vidioc-enumstd.rst

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