1.. -*- coding: utf-8; mode: rst -*- 2 3.. _VIDIOC_ENUMSTD: 4 5******************** 6ioctl VIDIOC_ENUMSTD 7******************** 8 9Name 10==== 11 12VIDIOC_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 22Arguments 23========= 24 25``fd`` 26 File descriptor returned by :ref:`open() <func-open>`. 27 28``argp`` 29 30 31Description 32=========== 33 34To query the attributes of a video standard, especially a custom (driver 35defined) one, applications initialize the ``index`` field of struct 36:c:type:`v4l2_standard` and call the :ref:`VIDIOC_ENUMSTD` 37ioctl with a pointer to this structure. Drivers fill the rest of the 38structure or return an ``EINVAL`` error code when the index is out of 39bounds. To enumerate all standards applications shall begin at index 40zero, incrementing by one until the driver returns ``EINVAL``. Drivers may 41enumerate a different set of standards after switching the video input 42or 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 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 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 149rate, 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. 170terrestrial digital TV standards. Presently the V4L2 API does not 171support 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 300Return Value 301============ 302 303On success 0 is returned, on error -1 and the ``errno`` variable is set 304appropriately. The generic error codes are described at the 305:ref:`Generic Error Codes <gen-errors>` chapter. 306 307EINVAL 308 The struct :c:type:`v4l2_standard` ``index`` is out 309 of bounds. 310 311ENODATA 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) 354