0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_ENUMSTD:
0005
0006 *******************************************
0007 ioctl VIDIOC_ENUMSTD, VIDIOC_SUBDEV_ENUMSTD
0008 *******************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_ENUMSTD - VIDIOC_SUBDEV_ENUMSTD - Enumerate supported video standards
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_ENUMSTD
0019
0020 ``int ioctl(int fd, VIDIOC_ENUMSTD, struct v4l2_standard *argp)``
0021
0022 .. c:macro:: VIDIOC_SUBDEV_ENUMSTD
0023
0024 ``int ioctl(int fd, VIDIOC_SUBDEV_ENUMSTD, struct v4l2_standard *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_standard`.
0034
0035 Description
0036 ===========
0037
0038 To query the attributes of a video standard, especially a custom (driver
0039 defined) one, applications initialize the ``index`` field of struct
0040 :c:type:`v4l2_standard` and call the :ref:`VIDIOC_ENUMSTD`
0041 ioctl with a pointer to this structure. Drivers fill the rest of the
0042 structure or return an ``EINVAL`` error code when the index is out of
0043 bounds. To enumerate all standards applications shall begin at index
0044 zero, incrementing by one until the driver returns ``EINVAL``. Drivers may
0045 enumerate a different set of standards after switching the video input
0046 or output. [#f1]_
0047
0048 .. c:type:: v4l2_standard
0049
0050 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0051
0052 .. flat-table:: struct v4l2_standard
0053 :header-rows: 0
0054 :stub-columns: 0
0055 :widths: 1 1 2
0056
0057 * - __u32
0058 - ``index``
0059 - Number of the video standard, set by the application.
0060 * - :ref:`v4l2_std_id <v4l2-std-id>`
0061 - ``id``
0062 - The bits in this field identify the standard as one of the common
0063 standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are
0064 set as custom standards. Multiple bits can be set if the hardware
0065 does not distinguish between these standards, however separate
0066 indices do not indicate the opposite. The ``id`` must be unique.
0067 No other enumerated struct :c:type:`v4l2_standard` structure,
0068 for this input or output anyway, can contain the same set of bits.
0069 * - __u8
0070 - ``name``\ [24]
0071 - Name of the standard, a NUL-terminated ASCII string, for example:
0072 "PAL-B/G", "NTSC Japan". This information is intended for the
0073 user.
0074 * - struct :c:type:`v4l2_fract`
0075 - ``frameperiod``
0076 - The frame period (not field period) is numerator / denominator.
0077 For example M/NTSC has a frame period of 1001 / 30000 seconds.
0078 * - __u32
0079 - ``framelines``
0080 - Total lines per frame including blanking, e. g. 625 for B/PAL.
0081 * - __u32
0082 - ``reserved``\ [4]
0083 - Reserved for future extensions. Drivers must set the array to
0084 zero.
0085
0086
0087 .. c:type:: v4l2_fract
0088
0089 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0090
0091 .. flat-table:: struct v4l2_fract
0092 :header-rows: 0
0093 :stub-columns: 0
0094 :widths: 1 1 2
0095
0096 * - __u32
0097 - ``numerator``
0098 -
0099 * - __u32
0100 - ``denominator``
0101 -
0102
0103 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0104
0105 .. _v4l2-std-id:
0106
0107 .. flat-table:: typedef v4l2_std_id
0108 :header-rows: 0
0109 :stub-columns: 0
0110 :widths: 1 1 2
0111
0112 * - __u64
0113 - ``v4l2_std_id``
0114 - This type is a set, each bit representing another video standard
0115 as listed below and in :ref:`video-standards`. The 32 most
0116 significant bits are reserved for custom (driver defined) video
0117 standards.
0118
0119
0120 .. code-block:: c
0121
0122 #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
0123 #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002)
0124 #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004)
0125 #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008)
0126 #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010)
0127 #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020)
0128 #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040)
0129 #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080)
0130
0131 #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100)
0132 #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200)
0133 #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400)
0134 #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800)
0135
0136 ``V4L2_STD_PAL_60`` is a hybrid standard with 525 lines, 60 Hz refresh
0137 rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some
0138 PAL video recorders can play back NTSC tapes in this mode for display on
0139 a 50/60 Hz agnostic PAL TV.
0140
0141 .. code-block:: c
0142
0143 #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
0144 #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
0145 #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000)
0146
0147 ``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh
0148 rate, and NTSC color modulation with a 4.43 MHz color subcarrier.
0149
0150 .. code-block:: c
0151
0152 #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000)
0153
0154 #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000)
0155 #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000)
0156 #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000)
0157 #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000)
0158 #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000)
0159 #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000)
0160 #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000)
0161 #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000)
0162
0163 /* ATSC/HDTV */
0164 #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
0165 #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
0166
0167 ``V4L2_STD_ATSC_8_VSB`` and ``V4L2_STD_ATSC_16_VSB`` are U.S.
0168 terrestrial digital TV standards. Presently the V4L2 API does not
0169 support digital TV. See also the Linux DVB API at
0170 `https://linuxtv.org <https://linuxtv.org>`__.
0171
0172 .. code-block:: c
0173
0174 #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |
0175 V4L2_STD_PAL_B1 |
0176 V4L2_STD_PAL_G)
0177 #define V4L2_STD_B (V4L2_STD_PAL_B |
0178 V4L2_STD_PAL_B1 |
0179 V4L2_STD_SECAM_B)
0180 #define V4L2_STD_GH (V4L2_STD_PAL_G |
0181 V4L2_STD_PAL_H |
0182 V4L2_STD_SECAM_G |
0183 V4L2_STD_SECAM_H)
0184 #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |
0185 V4L2_STD_PAL_D1 |
0186 V4L2_STD_PAL_K)
0187 #define V4L2_STD_PAL (V4L2_STD_PAL_BG |
0188 V4L2_STD_PAL_DK |
0189 V4L2_STD_PAL_H |
0190 V4L2_STD_PAL_I)
0191 #define V4L2_STD_NTSC (V4L2_STD_NTSC_M |
0192 V4L2_STD_NTSC_M_JP |
0193 V4L2_STD_NTSC_M_KR)
0194 #define V4L2_STD_MN (V4L2_STD_PAL_M |
0195 V4L2_STD_PAL_N |
0196 V4L2_STD_PAL_Nc |
0197 V4L2_STD_NTSC)
0198 #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |
0199 V4L2_STD_SECAM_K |
0200 V4L2_STD_SECAM_K1)
0201 #define V4L2_STD_DK (V4L2_STD_PAL_DK |
0202 V4L2_STD_SECAM_DK)
0203
0204 #define V4L2_STD_SECAM (V4L2_STD_SECAM_B |
0205 V4L2_STD_SECAM_G |
0206 V4L2_STD_SECAM_H |
0207 V4L2_STD_SECAM_DK |
0208 V4L2_STD_SECAM_L |
0209 V4L2_STD_SECAM_LC)
0210
0211 #define V4L2_STD_525_60 (V4L2_STD_PAL_M |
0212 V4L2_STD_PAL_60 |
0213 V4L2_STD_NTSC |
0214 V4L2_STD_NTSC_443)
0215 #define V4L2_STD_625_50 (V4L2_STD_PAL |
0216 V4L2_STD_PAL_N |
0217 V4L2_STD_PAL_Nc |
0218 V4L2_STD_SECAM)
0219
0220 #define V4L2_STD_UNKNOWN 0
0221 #define V4L2_STD_ALL (V4L2_STD_525_60 |
0222 V4L2_STD_625_50)
0223
0224 .. raw:: latex
0225
0226 \begingroup
0227 \tiny
0228 \setlength{\tabcolsep}{2pt}
0229
0230 .. NTSC/M PAL/M /N /B /D /H /I SECAM/B /D /K1 /L
0231 .. 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}|
0232
0233 .. _video-standards:
0234
0235 .. flat-table:: Video Standards (based on :ref:`itu470`)
0236 :header-rows: 1
0237 :stub-columns: 0
0238
0239 * - Characteristics
0240 - M/NTSC [#f2]_
0241 - M/PAL
0242 - N/PAL [#f3]_
0243 - B, B1, G/PAL
0244 - D, D1, K/PAL
0245 - H/PAL
0246 - I/PAL
0247 - B, G/SECAM
0248 - D, K/SECAM
0249 - K1/SECAM
0250 - L/SECAM
0251 * - Frame lines
0252 - :cspan:`1` 525
0253 - :cspan:`8` 625
0254 * - Frame period (s)
0255 - :cspan:`1` 1001/30000
0256 - :cspan:`8` 1/25
0257 * - Chrominance sub-carrier frequency (Hz)
0258 - 3579545 ± 10
0259 - 3579611.49 ± 10
0260 - 4433618.75 ± 5
0261
0262 (3582056.25 ± 5)
0263 - :cspan:`3` 4433618.75 ± 5
0264 - 4433618.75 ± 1
0265 - :cspan:`2` f\ :sub:`OR` = 4406250 ± 2000,
0266
0267 f\ :sub:`OB` = 4250000 ± 2000
0268 * - Nominal radio-frequency channel bandwidth (MHz)
0269 - 6
0270 - 6
0271 - 6
0272 - B: 7; B1, G: 8
0273 - 8
0274 - 8
0275 - 8
0276 - 8
0277 - 8
0278 - 8
0279 - 8
0280 * - Sound carrier relative to vision carrier (MHz)
0281 - 4.5
0282 - 4.5
0283 - 4.5
0284 - 5.5 ± 0.001 [#f4]_ [#f5]_ [#f6]_ [#f7]_
0285 - 6.5 ± 0.001
0286 - 5.5
0287 - 5.9996 ± 0.0005
0288 - 5.5 ± 0.001
0289 - 6.5 ± 0.001
0290 - 6.5
0291 - 6.5 [#f8]_
0292
0293 .. raw:: latex
0294
0295 \endgroup
0296
0297
0298 Return Value
0299 ============
0300
0301 On success 0 is returned, on error -1 and the ``errno`` variable is set
0302 appropriately. The generic error codes are described at the
0303 :ref:`Generic Error Codes <gen-errors>` chapter.
0304
0305 EINVAL
0306 The struct :c:type:`v4l2_standard` ``index`` is out
0307 of bounds.
0308
0309 ENODATA
0310 Standard video timings are not supported for this input or output.
0311
0312 .. [#f1]
0313 The supported standards may overlap and we need an unambiguous set to
0314 find the current standard returned by :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`.
0315
0316 .. [#f2]
0317 Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP).
0318
0319 .. [#f3]
0320 The values in brackets apply to the combination N/PAL a.k.a.
0321 N\ :sub:`C` used in Argentina (V4L2_STD_PAL_Nc).
0322
0323 .. [#f4]
0324 In the Federal Republic of Germany, Austria, Italy, the Netherlands,
0325 Slovakia and Switzerland a system of two sound carriers is used, the
0326 frequency of the second carrier being 242.1875 kHz above the
0327 frequency of the first sound carrier. For stereophonic sound
0328 transmissions a similar system is used in Australia.
0329
0330 .. [#f5]
0331 New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from
0332 the vision carrier.
0333
0334 .. [#f6]
0335 In Denmark, Finland, New Zealand, Sweden and Spain a system of two
0336 sound carriers is used. In Iceland, Norway and Poland the same system
0337 is being introduced. The second carrier is 5.85 MHz above the vision
0338 carrier and is DQPSK modulated with 728 kbit/s sound and data
0339 multiplex. (NICAM system)
0340
0341 .. [#f7]
0342 In the United Kingdom, a system of two sound carriers is used. The
0343 second sound carrier is 6.552 MHz above the vision carrier and is
0344 DQPSK modulated with a 728 kbit/s sound and data multiplex able to
0345 carry two sound channels. (NICAM system)
0346
0347 .. [#f8]
0348 In France, a digital carrier 5.85 MHz away from the vision carrier
0349 may be used in addition to the main sound carrier. It is modulated in
0350 differentially encoded QPSK with a 728 kbit/s sound and data
0351 multiplexer capable of carrying two sound channels. (NICAM system)
