352 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_ENUMSTD:5 6*******************************************7ioctl VIDIOC_ENUMSTD, VIDIOC_SUBDEV_ENUMSTD8*******************************************9 10Name11====12 13VIDIOC_ENUMSTD - VIDIOC_SUBDEV_ENUMSTD - Enumerate supported video standards14 15Synopsis16========17 18.. c:macro:: VIDIOC_ENUMSTD19 20``int ioctl(int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp)``21 22.. c:macro:: VIDIOC_SUBDEV_ENUMSTD23 24``int ioctl(int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp)``25 26Arguments27=========28 29``fd``30 File descriptor returned by :c:func:`open()`.31 32``argp``33 Pointer to struct :c:type:`v4l2_standard`.34 35Description36===========37 38To query the attributes of a video standard, especially a custom (driver39defined) one, applications initialize the ``index`` field of struct40:c:type:`v4l2_standard` and call the :ref:`VIDIOC_ENUMSTD`41ioctl with a pointer to this structure. Drivers fill the rest of the42structure or return an ``EINVAL`` error code when the index is out of43bounds. To enumerate all standards applications shall begin at index44zero, incrementing by one until the driver returns ``EINVAL``. Drivers may45enumerate a different set of standards after switching the video input46or output. [#f1]_47 48.. c:type:: v4l2_standard49 50.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|51 52.. flat-table:: struct v4l2_standard53 :header-rows: 054 :stub-columns: 055 :widths: 1 1 256 57 * - __u3258 - ``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 common63 standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are64 set as custom standards. Multiple bits can be set if the hardware65 does not distinguish between these standards, however separate66 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 * - __u870 - ``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 the73 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 * - __u3279 - ``framelines``80 - Total lines per frame including blanking, e. g. 625 for B/PAL.81 * - __u3282 - ``reserved``\ [4]83 - Reserved for future extensions. Drivers must set the array to84 zero.85 86 87.. c:type:: v4l2_fract88 89.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|90 91.. flat-table:: struct v4l2_fract92 :header-rows: 093 :stub-columns: 094 :widths: 1 1 295 96 * - __u3297 - ``numerator``98 -99 * - __u32100 - ``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_id108 :header-rows: 0109 :stub-columns: 0110 :widths: 1 1 2111 112 * - __u64113 - ``v4l2_std_id``114 - This type is a set, each bit representing another video standard115 as listed below and in :ref:`video-standards`. The 32 most116 significant bits are reserved for custom (driver defined) video117 standards.118 119 120.. code-block:: c121 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 refresh137rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some138PAL video recorders can play back NTSC tapes in this mode for display on139a 50/60 Hz agnostic PAL TV.140 141.. code-block:: c142 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 refresh148rate, and NTSC color modulation with a 4.43 MHz color subcarrier.149 150.. code-block:: c151 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 not169support digital TV. See also the Linux DVB API at170`https://linuxtv.org <https://linuxtv.org>`__.171 172.. code-block:: c173 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 0221 #define V4L2_STD_ALL (V4L2_STD_525_60 |222 V4L2_STD_625_50)223 224.. raw:: latex225 226 \begingroup227 \tiny228 \setlength{\tabcolsep}{2pt}229 230.. NTSC/M PAL/M /N /B /D /H /I SECAM/B /D /K1 /L231.. 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: 1237 :stub-columns: 0238 239 * - Characteristics240 - M/NTSC [#f2]_241 - M/PAL242 - N/PAL [#f3]_243 - B, B1, G/PAL244 - D, D1, K/PAL245 - H/PAL246 - I/PAL247 - B, G/SECAM248 - D, K/SECAM249 - K1/SECAM250 - L/SECAM251 * - Frame lines252 - :cspan:`1` 525253 - :cspan:`8` 625254 * - Frame period (s)255 - :cspan:`1` 1001/30000256 - :cspan:`8` 1/25257 * - Chrominance sub-carrier frequency (Hz)258 - 3579545 ± 10259 - 3579611.49 ± 10260 - 4433618.75 ± 5261 262 (3582056.25 ± 5)263 - :cspan:`3` 4433618.75 ± 5264 - 4433618.75 ± 1265 - :cspan:`2` f\ :sub:`OR` = 4406250 ± 2000,266 267 f\ :sub:`OB` = 4250000 ± 2000268 * - Nominal radio-frequency channel bandwidth (MHz)269 - 6270 - 6271 - 6272 - B: 7; B1, G: 8273 - 8274 - 8275 - 8276 - 8277 - 8278 - 8279 - 8280 * - Sound carrier relative to vision carrier (MHz)281 - 4.5282 - 4.5283 - 4.5284 - 5.5 ± 0.001 [#f4]_ [#f5]_ [#f6]_ [#f7]_285 - 6.5 ± 0.001286 - 5.5287 - 5.9996 ± 0.0005288 - 5.5 ± 0.001289 - 6.5 ± 0.001290 - 6.5291 - 6.5 [#f8]_292 293.. raw:: latex294 295 \endgroup296 297 298Return Value299============300 301On success 0 is returned, on error -1 and the ``errno`` variable is set302appropriately. The generic error codes are described at the303:ref:`Generic Error Codes <gen-errors>` chapter.304 305EINVAL306 The struct :c:type:`v4l2_standard` ``index`` is out307 of bounds.308 309ENODATA310 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 to314 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, the326 frequency of the second carrier being 242.1875 kHz above the327 frequency of the first sound carrier. For stereophonic sound328 transmissions a similar system is used in Australia.329 330.. [#f5]331 New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from332 the vision carrier.333 334.. [#f6]335 In Denmark, Finland, New Zealand, Sweden and Spain a system of two336 sound carriers is used. In Iceland, Norway and Poland the same system337 is being introduced. The second carrier is 5.85 MHz above the vision338 carrier and is DQPSK modulated with 728 kbit/s sound and data339 multiplex. (NICAM system)340 341.. [#f7]342 In the United Kingdom, a system of two sound carriers is used. The343 second sound carrier is 6.552 MHz above the vision carrier and is344 DQPSK modulated with a 728 kbit/s sound and data multiplex able to345 carry two sound channels. (NICAM system)346 347.. [#f8]348 In France, a digital carrier 5.85 MHz away from the vision carrier349 may be used in addition to the main sound carrier. It is modulated in350 differentially encoded QPSK with a 728 kbit/s sound and data351 multiplexer capable of carrying two sound channels. (NICAM system)352