1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _VIDIOC_ENUMSTD: 4 5******************************************* 6ioctl VIDIOC_ENUMSTD, VIDIOC_SUBDEV_ENUMSTD 7******************************************* 8 9Name 10==== 11 12VIDIOC_ENUMSTD - VIDIOC_SUBDEV_ENUMSTD - Enumerate supported video standards 13 14 15Synopsis 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 25Arguments 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 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 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 141rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some 142PAL video recorders can play back NTSC tapes in this mode for display on 143a 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 153rate, 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. 174terrestrial digital TV standards. Presently the V4L2 API does not 175support 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 307Return Value 308============ 309 310On success 0 is returned, on error -1 and the ``errno`` variable is set 311appropriately. The generic error codes are described at the 312:ref:`Generic Error Codes <gen-errors>` chapter. 313 314EINVAL 315 The struct :c:type:`v4l2_standard` ``index`` is out 316 of bounds. 317 318ENODATA 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) 361