1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4.. _VIDIOC_ENUMSTD: 5 6******************************************* 7ioctl VIDIOC_ENUMSTD, VIDIOC_SUBDEV_ENUMSTD 8******************************************* 9 10Name 11==== 12 13VIDIOC_ENUMSTD - VIDIOC_SUBDEV_ENUMSTD - Enumerate supported video standards 14 15Synopsis 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 26Arguments 27========= 28 29``fd`` 30 File descriptor returned by :c:func:`open()`. 31 32``argp`` 33 Pointer to struct :c:type:`v4l2_standard`. 34 35Description 36=========== 37 38To query the attributes of a video standard, especially a custom (driver 39defined) one, applications initialize the ``index`` field of struct 40:c:type:`v4l2_standard` and call the :ref:`VIDIOC_ENUMSTD` 41ioctl with a pointer to this structure. Drivers fill the rest of the 42structure or return an ``EINVAL`` error code when the index is out of 43bounds. To enumerate all standards applications shall begin at index 44zero, incrementing by one until the driver returns ``EINVAL``. Drivers may 45enumerate a different set of standards after switching the video input 46or output. [#f1]_ 47 48.. c:type:: v4l2_standard 49 50.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| 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.5cm}| 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.5cm}| 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 137rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some 138PAL video recorders can play back NTSC tapes in this mode for display on 139a 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 148rate, 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. 168terrestrial digital TV standards. Presently the V4L2 API does not 169support 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 298Return Value 299============ 300 301On success 0 is returned, on error -1 and the ``errno`` variable is set 302appropriately. The generic error codes are described at the 303:ref:`Generic Error Codes <gen-errors>` chapter. 304 305EINVAL 306 The struct :c:type:`v4l2_standard` ``index`` is out 307 of bounds. 308 309ENODATA 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) 352