| 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 | |
| 55 | - .. row 1 |
| 56 | |
| 57 | - __u32 |
| 58 | |
| 59 | - ``index`` |
| 60 | |
| 61 | - Number of the video standard, set by the application. |
| 62 | |
| 63 | - .. row 2 |
| 64 | |
| 65 | - :ref:`v4l2_std_id <v4l2-std-id>` |
| 66 | |
| 67 | - ``id`` |
| 68 | |
| 69 | - The bits in this field identify the standard as one of the common |
| 70 | standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are |
| 71 | set as custom standards. Multiple bits can be set if the hardware |
| 72 | does not distinguish between these standards, however separate |
| 73 | indices do not indicate the opposite. The ``id`` must be unique. |
| 74 | No other enumerated struct :c:type:`v4l2_standard` structure, |
| 75 | for this input or output anyway, can contain the same set of bits. |
| 76 | |
| 77 | - .. row 3 |
| 78 | |
| 79 | - __u8 |
| 80 | |
| 81 | - ``name``\ [24] |
| 82 | |
| 83 | - Name of the standard, a NUL-terminated ASCII string, for example: |
| 84 | "PAL-B/G", "NTSC Japan". This information is intended for the |
| 85 | user. |
| 86 | |
| 87 | - .. row 4 |
| 88 | |
| 89 | - struct :c:type:`v4l2_fract` |
| 90 | |
| 91 | - ``frameperiod`` |
| 92 | |
| 93 | - The frame period (not field period) is numerator / denominator. |
| 94 | For example M/NTSC has a frame period of 1001 / 30000 seconds. |
| 95 | |
| 96 | - .. row 5 |
| 97 | |
| 98 | - __u32 |
| 99 | |
| 100 | - ``framelines`` |
| 101 | |
| 102 | - Total lines per frame including blanking, e. g. 625 for B/PAL. |
| 103 | |
| 104 | - .. row 6 |
| 105 | |
| 106 | - __u32 |
| 107 | |
| 108 | - ``reserved``\ [4] |
| 109 | |
| 110 | - Reserved for future extensions. Drivers must set the array to |
| 111 | zero. |
| 112 | |
| 113 | |
| 114 | |
| 115 | .. c:type:: v4l2_fract |
| 116 | |
| 117 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
| 118 | |
| 119 | .. flat-table:: struct v4l2_fract |
| 120 | :header-rows: 0 |
| 121 | :stub-columns: 0 |
| 122 | :widths: 1 1 2 |
| 123 | |
| 124 | |
| 125 | - .. row 1 |
| 126 | |
| 127 | - __u32 |
| 128 | |
| 129 | - ``numerator`` |
| 130 | |
| 131 | - |
| 132 | |
| 133 | - .. row 2 |
| 134 | |
| 135 | - __u32 |
| 136 | |
| 137 | - ``denominator`` |
| 138 | |
| 139 | - |
| 140 | |
| 141 | |
| 142 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
| 143 | |
| 144 | .. _v4l2-std-id: |
| 145 | |
| 146 | .. flat-table:: typedef v4l2_std_id |
| 147 | :header-rows: 0 |
| 148 | :stub-columns: 0 |
| 149 | :widths: 1 1 2 |
| 150 | |
| 151 | |
| 152 | - .. row 1 |
| 153 | |
| 154 | - __u64 |
| 155 | |
| 156 | - ``v4l2_std_id`` |
| 157 | |
| 158 | - This type is a set, each bit representing another video standard |
| 159 | as listed below and in :ref:`video-standards`. The 32 most |
| 160 | significant bits are reserved for custom (driver defined) video |
| 161 | standards. |
| 162 | |
| 163 | |
| 164 | |
| 165 | .. code-block:: c |
| 166 | |
| 167 | #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) |
| 168 | #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002) |
| 169 | #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004) |
| 170 | #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008) |
| 171 | #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010) |
| 172 | #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020) |
| 173 | #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040) |
| 174 | #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080) |
| 175 | |
| 176 | #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100) |
| 177 | #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200) |
| 178 | #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400) |
| 179 | #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800) |
| 180 | |
| 181 | ``V4L2_STD_PAL_60`` is a hybrid standard with 525 lines, 60 Hz refresh |
| 182 | rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some |
| 183 | PAL video recorders can play back NTSC tapes in this mode for display on |
| 184 | a 50/60 Hz agnostic PAL TV. |
| 185 | |
| 186 | |
| 187 | .. code-block:: c |
| 188 | |
| 189 | #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) |
| 190 | #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) |
| 191 | #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000) |
| 192 | |
| 193 | ``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh |
| 194 | rate, and NTSC color modulation with a 4.43 MHz color subcarrier. |
| 195 | |
| 196 | |
| 197 | .. code-block:: c |
| 198 | |
| 199 | #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) |
| 200 | |
| 201 | #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000) |
| 202 | #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000) |
| 203 | #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000) |
| 204 | #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000) |
| 205 | #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000) |
| 206 | #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000) |
| 207 | #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000) |
| 208 | #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000) |
| 209 | |
| 210 | /* ATSC/HDTV */ |
| 211 | #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000) |
| 212 | #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000) |
| 213 | |
| 214 | ``V4L2_STD_ATSC_8_VSB`` and ``V4L2_STD_ATSC_16_VSB`` are U.S. |
| 215 | terrestrial digital TV standards. Presently the V4L2 API does not |
| 216 | support digital TV. See also the Linux DVB API at |
| 217 | `https://linuxtv.org <https://linuxtv.org>`__. |
| 218 | |
| 219 | |
| 220 | .. code-block:: c |
| 221 | |
| 222 | #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B | |
| 223 | V4L2_STD_PAL_B1 | |
| 224 | V4L2_STD_PAL_G) |
| 225 | #define V4L2_STD_B (V4L2_STD_PAL_B | |
| 226 | V4L2_STD_PAL_B1 | |
| 227 | V4L2_STD_SECAM_B) |
| 228 | #define V4L2_STD_GH (V4L2_STD_PAL_G | |
| 229 | V4L2_STD_PAL_H | |
| 230 | V4L2_STD_SECAM_G | |
| 231 | V4L2_STD_SECAM_H) |
| 232 | #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D | |
| 233 | V4L2_STD_PAL_D1 | |
| 234 | V4L2_STD_PAL_K) |
| 235 | #define V4L2_STD_PAL (V4L2_STD_PAL_BG | |
| 236 | V4L2_STD_PAL_DK | |
| 237 | V4L2_STD_PAL_H | |
| 238 | V4L2_STD_PAL_I) |
| 239 | #define V4L2_STD_NTSC (V4L2_STD_NTSC_M | |
| 240 | V4L2_STD_NTSC_M_JP | |
| 241 | V4L2_STD_NTSC_M_KR) |
| 242 | #define V4L2_STD_MN (V4L2_STD_PAL_M | |
| 243 | V4L2_STD_PAL_N | |
| 244 | V4L2_STD_PAL_Nc | |
| 245 | V4L2_STD_NTSC) |
| 246 | #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D | |
| 247 | V4L2_STD_SECAM_K | |
| 248 | V4L2_STD_SECAM_K1) |
| 249 | #define V4L2_STD_DK (V4L2_STD_PAL_DK | |
| 250 | V4L2_STD_SECAM_DK) |
| 251 | |
| 252 | #define V4L2_STD_SECAM (V4L2_STD_SECAM_B | |
| 253 | V4L2_STD_SECAM_G | |
| 254 | V4L2_STD_SECAM_H | |
| 255 | V4L2_STD_SECAM_DK | |
| 256 | V4L2_STD_SECAM_L | |
| 257 | V4L2_STD_SECAM_LC) |
| 258 | |
| 259 | #define V4L2_STD_525_60 (V4L2_STD_PAL_M | |
| 260 | V4L2_STD_PAL_60 | |
| 261 | V4L2_STD_NTSC | |
| 262 | V4L2_STD_NTSC_443) |
| 263 | #define V4L2_STD_625_50 (V4L2_STD_PAL | |
| 264 | V4L2_STD_PAL_N | |
| 265 | V4L2_STD_PAL_Nc | |
| 266 | V4L2_STD_SECAM) |
| 267 | |
| 268 | #define V4L2_STD_UNKNOWN 0 |
| 269 | #define V4L2_STD_ALL (V4L2_STD_525_60 | |
| 270 | V4L2_STD_625_50) |
| 271 | |
| 272 | .. raw:: latex |
| 273 | |
| 274 | \begin{adjustbox}{width=\columnwidth} |
| 275 | |
| 276 | .. NTSC/M PAL/M /N /B /D /H /I SECAM/B /D /K1 /L |
| 277 | .. 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}| |
| 278 | |
| 279 | .. _video-standards: |
| 280 | |
| 281 | .. flat-table:: Video Standards (based on :ref:`itu470`) |
| 282 | :header-rows: 1 |
| 283 | :stub-columns: 0 |
| 284 | |
| 285 | |
| 286 | - .. row 1 |
| 287 | |
| 288 | - Characteristics |
| 289 | |
| 290 | - M/NTSC [#f2]_ |
| 291 | |
| 292 | - M/PAL |
| 293 | |
| 294 | - N/PAL [#f3]_ |
| 295 | |
| 296 | - B, B1, G/PAL |
| 297 | |
| 298 | - D, D1, K/PAL |
| 299 | |
| 300 | - H/PAL |
| 301 | |
| 302 | - I/PAL |
| 303 | |
| 304 | - B, G/SECAM |
| 305 | |
| 306 | - D, K/SECAM |
| 307 | |
| 308 | - K1/SECAM |
| 309 | |
| 310 | - L/SECAM |
| 311 | |
| 312 | - .. row 2 |
| 313 | |
| 314 | - Frame lines |
| 315 | |
| 316 | - :cspan:`1` 525 |
| 317 | |
| 318 | - :cspan:`8` 625 |
| 319 | |
| 320 | - .. row 3 |
| 321 | |
| 322 | - Frame period (s) |
| 323 | |
| 324 | - :cspan:`1` 1001/30000 |
| 325 | |
| 326 | - :cspan:`8` 1/25 |
| 327 | |
| 328 | - .. row 4 |
| 329 | |
| 330 | - Chrominance sub-carrier frequency (Hz) |
| 331 | |
| 332 | - 3579545 ± 10 |
| 333 | |
| 334 | - 3579611.49 ± 10 |
| 335 | |
| 336 | - 4433618.75 ± 5 |
| 337 | |
| 338 | (3582056.25 ± 5) |
| 339 | |
| 340 | - :cspan:`3` 4433618.75 ± 5 |
| 341 | |
| 342 | - 4433618.75 ± 1 |
| 343 | |
| 344 | - :cspan:`2` f\ :sub:`OR` = 4406250 ± 2000, |
| 345 | |
| 346 | f\ :sub:`OB` = 4250000 ± 2000 |
| 347 | |
| 348 | - .. row 5 |
| 349 | |
| 350 | - Nominal radio-frequency channel bandwidth (MHz) |
| 351 | |
| 352 | - 6 |
| 353 | |
| 354 | - 6 |
| 355 | |
| 356 | - 6 |
| 357 | |
| 358 | - B: 7; B1, G: 8 |
| 359 | |
| 360 | - 8 |
| 361 | |
| 362 | - 8 |
| 363 | |
| 364 | - 8 |
| 365 | |
| 366 | - 8 |
| 367 | |
| 368 | - 8 |
| 369 | |
| 370 | - 8 |
| 371 | |
| 372 | - 8 |
| 373 | |
| 374 | - .. row 6 |
| 375 | |
| 376 | - Sound carrier relative to vision carrier (MHz) |
| 377 | |
| 378 | - 4.5 |
| 379 | |
| 380 | - 4.5 |
| 381 | |
| 382 | - 4.5 |
| 383 | |
| 384 | - 5.5 ± 0.001 [#f4]_ [#f5]_ [#f6]_ [#f7]_ |
| 385 | |
| 386 | - 6.5 ± 0.001 |
| 387 | |
| 388 | - 5.5 |
| 389 | |
| 390 | - 5.9996 ± 0.0005 |
| 391 | |
| 392 | - 5.5 ± 0.001 |
| 393 | |
| 394 | - 6.5 ± 0.001 |
| 395 | |
| 396 | - 6.5 |
| 397 | |
| 398 | - 6.5 [#f8]_ |
| 399 | |
| 400 | .. raw:: latex |
| 401 | |
| 402 | \end{adjustbox}\newline\newline |
| 403 | |
| 404 | |
| 405 | |
| 406 | Return Value |
| 407 | ============ |
| 408 | |
| 409 | On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 410 | appropriately. The generic error codes are described at the |
| 411 | :ref:`Generic Error Codes <gen-errors>` chapter. |
| 412 | |
| 413 | EINVAL |
| 414 | The struct :c:type:`v4l2_standard` ``index`` is out |
| 415 | of bounds. |
| 416 | |
| 417 | ENODATA |
| 418 | Standard video timings are not supported for this input or output. |
| 419 | |
| 420 | .. [#f1] |
| 421 | The supported standards may overlap and we need an unambiguous set to |
| 422 | find the current standard returned by :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`. |
| 423 | |
| 424 | .. [#f2] |
| 425 | Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP). |
| 426 | |
| 427 | .. [#f3] |
| 428 | The values in brackets apply to the combination N/PAL a.k.a. |
| 429 | N\ :sub:`C` used in Argentina (V4L2_STD_PAL_Nc). |
| 430 | |
| 431 | .. [#f4] |
| 432 | In the Federal Republic of Germany, Austria, Italy, the Netherlands, |
| 433 | Slovakia and Switzerland a system of two sound carriers is used, the |
| 434 | frequency of the second carrier being 242.1875 kHz above the |
| 435 | frequency of the first sound carrier. For stereophonic sound |
| 436 | transmissions a similar system is used in Australia. |
| 437 | |
| 438 | .. [#f5] |
| 439 | New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from |
| 440 | the vision carrier. |
| 441 | |
| 442 | .. [#f6] |
| 443 | In Denmark, Finland, New Zealand, Sweden and Spain a system of two |
| 444 | sound carriers is used. In Iceland, Norway and Poland the same system |
| 445 | is being introduced. The second carrier is 5.85 MHz above the vision |
| 446 | carrier and is DQPSK modulated with 728 kbit/s sound and data |
| 447 | multiplex. (NICAM system) |
| 448 | |
| 449 | .. [#f7] |
| 450 | In the United Kingdom, a system of two sound carriers is used. The |
| 451 | second sound carrier is 6.552 MHz above the vision carrier and is |
| 452 | DQPSK modulated with a 728 kbit/s sound and data multiplex able to |
| 453 | carry two sound channels. (NICAM system) |
| 454 | |
| 455 | .. [#f8] |
| 456 | In France, a digital carrier 5.85 MHz away from the vision carrier |
| 457 | may be used in addition to the main sound carrier. It is modulated in |
| 458 | differentially encoded QPSK with a 728 kbit/s sound and data |
| 459 | multiplexer capable of carrying two sound channels. (NICAM system) |