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/userspace-api/media/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. _VIDIOC_ENUMSTD: 11 12******************************************* 13ioctl VIDIOC_ENUMSTD, VIDIOC_SUBDEV_ENUMSTD 14******************************************* 15 16Name 17==== 18 19VIDIOC_ENUMSTD - VIDIOC_SUBDEV_ENUMSTD - Enumerate supported video standards 20 21 22Synopsis 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 32Arguments 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 42Description 43=========== 44 45To query the attributes of a video standard, especially a custom (driver 46defined) one, applications initialize the ``index`` field of struct 47:c:type:`v4l2_standard` and call the :ref:`VIDIOC_ENUMSTD` 48ioctl with a pointer to this structure. Drivers fill the rest of the 49structure or return an ``EINVAL`` error code when the index is out of 50bounds. To enumerate all standards applications shall begin at index 51zero, incrementing by one until the driver returns ``EINVAL``. Drivers may 52enumerate a different set of standards after switching the video input 53or 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 148rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some 149PAL video recorders can play back NTSC tapes in this mode for display on 150a 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 160rate, 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. 181terrestrial digital TV standards. Presently the V4L2 API does not 182support 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 314Return Value 315============ 316 317On success 0 is returned, on error -1 and the ``errno`` variable is set 318appropriately. The generic error codes are described at the 319:ref:`Generic Error Codes <gen-errors>` chapter. 320 321EINVAL 322 The struct :c:type:`v4l2_standard` ``index`` is out 323 of bounds. 324 325ENODATA 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) 368