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