1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L 2 .. c:namespace:: V4L
3 3
4 .. _diff-v4l: 4 .. _diff-v4l:
5 5
6 ******************************** 6 ********************************
7 Differences between V4L and V4L2 7 Differences between V4L and V4L2
8 ******************************** 8 ********************************
9 9
10 The Video For Linux API was first introduced i 10 The Video For Linux API was first introduced in Linux 2.1 to unify and
11 replace various TV and radio device related in 11 replace various TV and radio device related interfaces, developed
12 independently by driver writers in prior years 12 independently by driver writers in prior years. Starting with Linux 2.5
13 the much improved V4L2 API replaces the V4L AP 13 the much improved V4L2 API replaces the V4L API. The support for the old
14 V4L calls were removed from Kernel, but the li 14 V4L calls were removed from Kernel, but the library :ref:`libv4l`
15 supports the conversion of a V4L API system ca 15 supports the conversion of a V4L API system call into a V4L2 one.
16 16
17 Opening and Closing Devices 17 Opening and Closing Devices
18 =========================== 18 ===========================
19 19
20 For compatibility reasons the character device 20 For compatibility reasons the character device file names recommended
21 for V4L2 video capture, overlay, radio and raw 21 for V4L2 video capture, overlay, radio and raw vbi capture devices did
22 not change from those used by V4L. They are li 22 not change from those used by V4L. They are listed in :ref:`devices`
23 and below in :ref:`v4l-dev`. 23 and below in :ref:`v4l-dev`.
24 24
25 The teletext devices (minor range 192-223) hav 25 The teletext devices (minor range 192-223) have been removed in V4L2 and
26 no longer exist. There is no hardware availabl 26 no longer exist. There is no hardware available anymore for handling
27 pure teletext. Instead raw or sliced VBI is us 27 pure teletext. Instead raw or sliced VBI is used.
28 28
29 The V4L ``videodev`` module automatically assi 29 The V4L ``videodev`` module automatically assigns minor numbers to
30 drivers in load order, depending on the regist 30 drivers in load order, depending on the registered device type. We
31 recommend that V4L2 drivers by default registe 31 recommend that V4L2 drivers by default register devices with the same
32 numbers, but the system administrator can assi 32 numbers, but the system administrator can assign arbitrary minor numbers
33 using driver module options. The major device 33 using driver module options. The major device number remains 81.
34 34
35 .. _v4l-dev: 35 .. _v4l-dev:
36 36
37 .. flat-table:: V4L Device Types, Names and Nu 37 .. flat-table:: V4L Device Types, Names and Numbers
38 :header-rows: 1 38 :header-rows: 1
39 :stub-columns: 0 39 :stub-columns: 0
40 40
41 * - Device Type 41 * - Device Type
42 - File Name 42 - File Name
43 - Minor Numbers 43 - Minor Numbers
44 * - Video capture and overlay 44 * - Video capture and overlay
45 - ``/dev/video`` and ``/dev/bttv0``\ [# 45 - ``/dev/video`` and ``/dev/bttv0``\ [#f1]_, ``/dev/video0`` to
46 ``/dev/video63`` 46 ``/dev/video63``
47 - 0-63 47 - 0-63
48 * - Radio receiver 48 * - Radio receiver
49 - ``/dev/radio``\ [#f2]_, ``/dev/radio0 49 - ``/dev/radio``\ [#f2]_, ``/dev/radio0`` to ``/dev/radio63``
50 - 64-127 50 - 64-127
51 * - Raw VBI capture 51 * - Raw VBI capture
52 - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/ 52 - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
53 - 224-255 53 - 224-255
54 54
55 V4L prohibits (or used to prohibit) multiple o 55 V4L prohibits (or used to prohibit) multiple opens of a device file.
56 V4L2 drivers *may* support multiple opens, see 56 V4L2 drivers *may* support multiple opens, see :ref:`open` for details
57 and consequences. 57 and consequences.
58 58
59 V4L drivers respond to V4L2 ioctls with an ``E 59 V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
60 60
61 Querying Capabilities 61 Querying Capabilities
62 ===================== 62 =====================
63 63
64 The V4L ``VIDIOCGCAP`` ioctl is equivalent to 64 The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's
65 :ref:`VIDIOC_QUERYCAP`. 65 :ref:`VIDIOC_QUERYCAP`.
66 66
67 The ``name`` field in struct ``video_capabilit 67 The ``name`` field in struct ``video_capability`` became
68 ``card`` in struct :c:type:`v4l2_capability`, 68 ``card`` in struct :c:type:`v4l2_capability`, ``type``
69 was replaced by ``capabilities``. Note V4L2 do 69 was replaced by ``capabilities``. Note V4L2 does not distinguish between
70 device types like this, better think of basic 70 device types like this, better think of basic video input, video output
71 and radio devices supporting a set of related 71 and radio devices supporting a set of related functions like video
72 capturing, video overlay and VBI capturing. Se 72 capturing, video overlay and VBI capturing. See :ref:`open` for an
73 introduction. 73 introduction.
74 74
75 .. raw:: latex 75 .. raw:: latex
76 76
77 \small 77 \small
78 78
79 .. tabularcolumns:: |p{5.3cm}|p{6.7cm}|p{5.3cm 79 .. tabularcolumns:: |p{5.3cm}|p{6.7cm}|p{5.3cm}|
80 80
81 .. cssclass:: longtable 81 .. cssclass:: longtable
82 82
83 .. flat-table:: 83 .. flat-table::
84 :header-rows: 1 84 :header-rows: 1
85 :stub-columns: 0 85 :stub-columns: 0
86 86
87 * - ``struct video_capability`` ``type`` 87 * - ``struct video_capability`` ``type``
88 - struct :c:type:`v4l2_capability` 88 - struct :c:type:`v4l2_capability`
89 ``capabilities`` flags 89 ``capabilities`` flags
90 - Purpose 90 - Purpose
91 * - ``VID_TYPE_CAPTURE`` 91 * - ``VID_TYPE_CAPTURE``
92 - ``V4L2_CAP_VIDEO_CAPTURE`` 92 - ``V4L2_CAP_VIDEO_CAPTURE``
93 - The :ref:`video capture <capture>` int 93 - The :ref:`video capture <capture>` interface is supported.
94 * - ``VID_TYPE_TUNER`` 94 * - ``VID_TYPE_TUNER``
95 - ``V4L2_CAP_TUNER`` 95 - ``V4L2_CAP_TUNER``
96 - The device has a :ref:`tuner or modula 96 - The device has a :ref:`tuner or modulator <tuner>`.
97 * - ``VID_TYPE_TELETEXT`` 97 * - ``VID_TYPE_TELETEXT``
98 - ``V4L2_CAP_VBI_CAPTURE`` 98 - ``V4L2_CAP_VBI_CAPTURE``
99 - The :ref:`raw VBI capture <raw-vbi>` i 99 - The :ref:`raw VBI capture <raw-vbi>` interface is supported.
100 * - ``VID_TYPE_OVERLAY`` 100 * - ``VID_TYPE_OVERLAY``
101 - ``V4L2_CAP_VIDEO_OVERLAY`` 101 - ``V4L2_CAP_VIDEO_OVERLAY``
102 - The :ref:`video overlay <overlay>` int 102 - The :ref:`video overlay <overlay>` interface is supported.
103 * - ``VID_TYPE_CHROMAKEY`` 103 * - ``VID_TYPE_CHROMAKEY``
104 - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ` 104 - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct
105 :c:type:`v4l2_framebuffer` 105 :c:type:`v4l2_framebuffer`
106 - Whether chromakey overlay is supported 106 - Whether chromakey overlay is supported. For more information on
107 overlay see :ref:`overlay`. 107 overlay see :ref:`overlay`.
108 * - ``VID_TYPE_CLIPPING`` 108 * - ``VID_TYPE_CLIPPING``
109 - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and 109 - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
110 ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in f 110 ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of
111 struct :c:type:`v4l2_framebuffer` 111 struct :c:type:`v4l2_framebuffer`
112 - Whether clipping the overlaid image is 112 - Whether clipping the overlaid image is supported, see
113 :ref:`overlay`. 113 :ref:`overlay`.
114 * - ``VID_TYPE_FRAMERAM`` 114 * - ``VID_TYPE_FRAMERAM``
115 - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not s 115 - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability``
116 of struct :c:type:`v4l2_framebuffer` 116 of struct :c:type:`v4l2_framebuffer`
117 - Whether overlay overwrites frame buffe 117 - Whether overlay overwrites frame buffer memory, see
118 :ref:`overlay`. 118 :ref:`overlay`.
119 * - ``VID_TYPE_SCALES`` 119 * - ``VID_TYPE_SCALES``
120 - ``-`` 120 - ``-``
121 - This flag indicates if the hardware ca 121 - This flag indicates if the hardware can scale images. The V4L2 API
122 implies the scale factor by setting th 122 implies the scale factor by setting the cropping dimensions and
123 image size with the :ref:`VIDIOC_S_CRO 123 image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and
124 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioc 124 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The
125 driver returns the closest sizes possi 125 driver returns the closest sizes possible. For more information on
126 cropping and scaling see :ref:`crop`. 126 cropping and scaling see :ref:`crop`.
127 * - ``VID_TYPE_MONOCHROME`` 127 * - ``VID_TYPE_MONOCHROME``
128 - ``-`` 128 - ``-``
129 - Applications can enumerate the support 129 - Applications can enumerate the supported image formats with the
130 :ref:`VIDIOC_ENUM_FMT` ioctl to determ 130 :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
131 the device supports grey scale capturi 131 the device supports grey scale capturing only. For more
132 information on image formats see :ref: 132 information on image formats see :ref:`pixfmt`.
133 * - ``VID_TYPE_SUBCAPTURE`` 133 * - ``VID_TYPE_SUBCAPTURE``
134 - ``-`` 134 - ``-``
135 - Applications can call the :ref:`VIDIOC 135 - Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>`
136 ioctl to determine if the device suppo 136 ioctl to determine if the device supports capturing a subsection
137 of the full picture ("cropping" in V4L 137 of the full picture ("cropping" in V4L2). If not, the ioctl
138 returns the ``EINVAL`` error code. For 138 returns the ``EINVAL`` error code. For more information on cropping
139 and scaling see :ref:`crop`. 139 and scaling see :ref:`crop`.
140 * - ``VID_TYPE_MPEG_DECODER`` 140 * - ``VID_TYPE_MPEG_DECODER``
141 - ``-`` 141 - ``-``
142 - Applications can enumerate the support 142 - Applications can enumerate the supported image formats with the
143 :ref:`VIDIOC_ENUM_FMT` ioctl to determ 143 :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
144 the device supports MPEG streams. 144 the device supports MPEG streams.
145 * - ``VID_TYPE_MPEG_ENCODER`` 145 * - ``VID_TYPE_MPEG_ENCODER``
146 - ``-`` 146 - ``-``
147 - See above. 147 - See above.
148 * - ``VID_TYPE_MJPEG_DECODER`` 148 * - ``VID_TYPE_MJPEG_DECODER``
149 - ``-`` 149 - ``-``
150 - See above. 150 - See above.
151 * - ``VID_TYPE_MJPEG_ENCODER`` 151 * - ``VID_TYPE_MJPEG_ENCODER``
152 - ``-`` 152 - ``-``
153 - See above. 153 - See above.
154 154
155 .. raw:: latex 155 .. raw:: latex
156 156
157 \normalsize 157 \normalsize
158 158
159 The ``audios`` field was replaced by ``capabil 159 The ``audios`` field was replaced by ``capabilities`` flag
160 ``V4L2_CAP_AUDIO``, indicating *if* the device 160 ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
161 outputs. To determine their number application 161 outputs. To determine their number applications can enumerate audio
162 inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G 162 inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The
163 audio ioctls are described in :ref:`audio`. 163 audio ioctls are described in :ref:`audio`.
164 164
165 The ``maxwidth``, ``maxheight``, ``minwidth`` 165 The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields
166 were removed. Calling the :ref:`VIDIOC_S_FMT < 166 were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
167 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl wit 167 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired
168 dimensions returns the closest size possible, 168 dimensions returns the closest size possible, taking into account the
169 current video standard, cropping and scaling l 169 current video standard, cropping and scaling limitations.
170 170
171 Video Sources 171 Video Sources
172 ============= 172 =============
173 173
174 V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCS 174 V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct
175 ``video_channel`` to enumerate the video input 175 ``video_channel`` to enumerate the video inputs of a V4L
176 device. The equivalent V4L2 ioctls are 176 device. The equivalent V4L2 ioctls are
177 :ref:`VIDIOC_ENUMINPUT`, 177 :ref:`VIDIOC_ENUMINPUT`,
178 :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and 178 :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
179 :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using s 179 :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct
180 :c:type:`v4l2_input` as discussed in :ref:`vid 180 :c:type:`v4l2_input` as discussed in :ref:`video`.
181 181
182 The ``channel`` field counting inputs was rena 182 The ``channel`` field counting inputs was renamed to ``index``, the
183 video input types were renamed as follows: 183 video input types were renamed as follows:
184 184
185 185
186 .. flat-table:: 186 .. flat-table::
187 :header-rows: 1 187 :header-rows: 1
188 :stub-columns: 0 188 :stub-columns: 0
189 189
190 * - struct ``video_channel`` ``type`` 190 * - struct ``video_channel`` ``type``
191 - struct :c:type:`v4l2_input` ``type`` 191 - struct :c:type:`v4l2_input` ``type``
192 * - ``VIDEO_TYPE_TV`` 192 * - ``VIDEO_TYPE_TV``
193 - ``V4L2_INPUT_TYPE_TUNER`` 193 - ``V4L2_INPUT_TYPE_TUNER``
194 * - ``VIDEO_TYPE_CAMERA`` 194 * - ``VIDEO_TYPE_CAMERA``
195 - ``V4L2_INPUT_TYPE_CAMERA`` 195 - ``V4L2_INPUT_TYPE_CAMERA``
196 196
197 Unlike the ``tuners`` field expressing the num 197 Unlike the ``tuners`` field expressing the number of tuners of this
198 input, V4L2 assumes each video input is connec 198 input, V4L2 assumes each video input is connected to at most one tuner.
199 However a tuner can have more than one input, 199 However a tuner can have more than one input, i. e. RF connectors, and a
200 device can have multiple tuners. The index num 200 device can have multiple tuners. The index number of the tuner
201 associated with the input, if any, is stored i 201 associated with the input, if any, is stored in field ``tuner`` of
202 struct :c:type:`v4l2_input`. Enumeration of tu 202 struct :c:type:`v4l2_input`. Enumeration of tuners is
203 discussed in :ref:`tuner`. 203 discussed in :ref:`tuner`.
204 204
205 The redundant ``VIDEO_VC_TUNER`` flag was drop 205 The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs
206 associated with a tuner are of type ``V4L2_INP 206 associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The
207 ``VIDEO_VC_AUDIO`` flag was replaced by the `` 207 ``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2
208 considers devices with up to 32 audio inputs. 208 considers devices with up to 32 audio inputs. Each set bit in the
209 ``audioset`` field represents one audio input 209 ``audioset`` field represents one audio input this video input combines
210 with. For information about audio inputs and h 210 with. For information about audio inputs and how to switch between them
211 see :ref:`audio`. 211 see :ref:`audio`.
212 212
213 The ``norm`` field describing the supported vi 213 The ``norm`` field describing the supported video standards was replaced
214 by ``std``. The V4L specification mentions a f 214 by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``
215 indicating whether the standard can be changed 215 indicating whether the standard can be changed. This flag was a later
216 addition together with the ``norm`` field and 216 addition together with the ``norm`` field and has been removed in the
217 meantime. V4L2 has a similar, albeit more comp 217 meantime. V4L2 has a similar, albeit more comprehensive approach to
218 video standards, see :ref:`standard` for more 218 video standards, see :ref:`standard` for more information.
219 219
220 Tuning 220 Tuning
221 ====== 221 ======
222 222
223 The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` 223 The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct
224 ``video_tuner`` can be used to enumerate the t 224 ``video_tuner`` can be used to enumerate the tuners of a
225 V4L TV or radio device. The equivalent V4L2 io 225 V4L TV or radio device. The equivalent V4L2 ioctls are
226 :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and 226 :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
227 :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using s 227 :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct
228 :c:type:`v4l2_tuner`. Tuners are covered in :r 228 :c:type:`v4l2_tuner`. Tuners are covered in :ref:`tuner`.
229 229
230 The ``tuner`` field counting tuners was rename 230 The ``tuner`` field counting tuners was renamed to ``index``. The fields
231 ``name``, ``rangelow`` and ``rangehigh`` remai 231 ``name``, ``rangelow`` and ``rangehigh`` remained unchanged.
232 232
233 The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` 233 The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM``
234 flags indicating the supported video standards 234 flags indicating the supported video standards were dropped. This
235 information is now contained in the associated 235 information is now contained in the associated struct
236 :c:type:`v4l2_input`. No replacement exists fo 236 :c:type:`v4l2_input`. No replacement exists for the
237 ``VIDEO_TUNER_NORM`` flag indicating whether t 237 ``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be
238 switched. The ``mode`` field to select a diffe 238 switched. The ``mode`` field to select a different video standard was
239 replaced by a whole new set of ioctls and stru 239 replaced by a whole new set of ioctls and structures described in
240 :ref:`standard`. Due to its ubiquity it should 240 :ref:`standard`. Due to its ubiquity it should be mentioned the BTTV
241 driver supports several standards in addition 241 driver supports several standards in addition to the regular
242 ``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ` 242 ``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and
243 ``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentin 243 ``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC
244 Japan with numbers 3-6 (sic). 244 Japan with numbers 3-6 (sic).
245 245
246 The ``VIDEO_TUNER_STEREO_ON`` flag indicating 246 The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became
247 ``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchan 247 ``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also
248 permits the detection of monaural and bilingua 248 permits the detection of monaural and bilingual audio, see the
249 definition of struct :c:type:`v4l2_tuner` for 249 definition of struct :c:type:`v4l2_tuner` for details.
250 Presently no replacement exists for the ``VIDE 250 Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and
251 ``VIDEO_TUNER_MBS_ON`` flags. 251 ``VIDEO_TUNER_MBS_ON`` flags.
252 252
253 The ``VIDEO_TUNER_LOW`` flag was renamed to `` 253 The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in
254 the struct :c:type:`v4l2_tuner` ``capability`` 254 the struct :c:type:`v4l2_tuner` ``capability`` field.
255 255
256 The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl 256 The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner
257 frequency where renamed to 257 frequency where renamed to
258 :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` 258 :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
259 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` 259 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer
260 to a struct :c:type:`v4l2_frequency` instead o 260 to a struct :c:type:`v4l2_frequency` instead of an
261 unsigned long integer. 261 unsigned long integer.
262 262
263 .. _v4l-image-properties: 263 .. _v4l-image-properties:
264 264
265 Image Properties 265 Image Properties
266 ================ 266 ================
267 267
268 V4L2 has no equivalent of the ``VIDIOCGPICT`` 268 V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl
269 and struct ``video_picture``. The following fi 269 and struct ``video_picture``. The following fields where
270 replaced by V4L2 controls accessible with the 270 replaced by V4L2 controls accessible with the
271 :ref:`VIDIOC_QUERYCTRL`, 271 :ref:`VIDIOC_QUERYCTRL`,
272 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and 272 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
273 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: 273 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
274 274
275 275
276 .. flat-table:: 276 .. flat-table::
277 :header-rows: 1 277 :header-rows: 1
278 :stub-columns: 0 278 :stub-columns: 0
279 279
280 * - struct ``video_picture`` 280 * - struct ``video_picture``
281 - V4L2 Control ID 281 - V4L2 Control ID
282 * - ``brightness`` 282 * - ``brightness``
283 - ``V4L2_CID_BRIGHTNESS`` 283 - ``V4L2_CID_BRIGHTNESS``
284 * - ``hue`` 284 * - ``hue``
285 - ``V4L2_CID_HUE`` 285 - ``V4L2_CID_HUE``
286 * - ``colour`` 286 * - ``colour``
287 - ``V4L2_CID_SATURATION`` 287 - ``V4L2_CID_SATURATION``
288 * - ``contrast`` 288 * - ``contrast``
289 - ``V4L2_CID_CONTRAST`` 289 - ``V4L2_CID_CONTRAST``
290 * - ``whiteness`` 290 * - ``whiteness``
291 - ``V4L2_CID_WHITENESS`` 291 - ``V4L2_CID_WHITENESS``
292 292
293 The V4L picture controls are assumed to range 293 The V4L picture controls are assumed to range from 0 to 65535 with no
294 particular reset value. The V4L2 API permits a 294 particular reset value. The V4L2 API permits arbitrary limits and
295 defaults which can be queried with the 295 defaults which can be queried with the
296 :ref:`VIDIOC_QUERYCTRL` ioctl. For general 296 :ref:`VIDIOC_QUERYCTRL` ioctl. For general
297 information about controls see :ref:`control`. 297 information about controls see :ref:`control`.
298 298
299 The ``depth`` (average number of bits per pixe 299 The ``depth`` (average number of bits per pixel) of a video image is
300 implied by the selected image format. V4L2 doe 300 implied by the selected image format. V4L2 does not explicitly provide
301 such information assuming applications recogni 301 such information assuming applications recognizing the format are aware
302 of the image depth and others need not know. T 302 of the image depth and others need not know. The ``palette`` field moved
303 into the struct :c:type:`v4l2_pix_format`: 303 into the struct :c:type:`v4l2_pix_format`:
304 304
305 305
306 .. flat-table:: 306 .. flat-table::
307 :header-rows: 1 307 :header-rows: 1
308 :stub-columns: 0 308 :stub-columns: 0
309 309
310 * - struct ``video_picture`` ``palette`` 310 * - struct ``video_picture`` ``palette``
311 - struct :c:type:`v4l2_pix_format` ``pix 311 - struct :c:type:`v4l2_pix_format` ``pixfmt``
312 * - ``VIDEO_PALETTE_GREY`` 312 * - ``VIDEO_PALETTE_GREY``
313 - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT- 313 - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>`
314 * - ``VIDEO_PALETTE_HI240`` 314 * - ``VIDEO_PALETTE_HI240``
315 - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reser 315 - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [#f3]_
316 * - ``VIDEO_PALETTE_RGB565`` 316 * - ``VIDEO_PALETTE_RGB565``
317 - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb> 317 - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>`
318 * - ``VIDEO_PALETTE_RGB555`` 318 * - ``VIDEO_PALETTE_RGB555``
319 - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb> 319 - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>`
320 * - ``VIDEO_PALETTE_RGB24`` 320 * - ``VIDEO_PALETTE_RGB24``
321 - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>` 321 - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>`
322 * - ``VIDEO_PALETTE_RGB32`` 322 * - ``VIDEO_PALETTE_RGB32``
323 - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` 323 - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [#f4]_
324 * - ``VIDEO_PALETTE_YUV422`` 324 * - ``VIDEO_PALETTE_YUV422``
325 - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT- 325 - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
326 * - ``VIDEO_PALETTE_YUYV``\ [#f5]_ 326 * - ``VIDEO_PALETTE_YUYV``\ [#f5]_
327 - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT- 327 - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
328 * - ``VIDEO_PALETTE_UYVY`` 328 * - ``VIDEO_PALETTE_UYVY``
329 - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT- 329 - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`
330 * - ``VIDEO_PALETTE_YUV420`` 330 * - ``VIDEO_PALETTE_YUV420``
331 - None 331 - None
332 * - ``VIDEO_PALETTE_YUV411`` 332 * - ``VIDEO_PALETTE_YUV411``
333 - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT- 333 - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [#f6]_
334 * - ``VIDEO_PALETTE_RAW`` 334 * - ``VIDEO_PALETTE_RAW``
335 - None [#f7]_ 335 - None [#f7]_
336 * - ``VIDEO_PALETTE_YUV422P`` 336 * - ``VIDEO_PALETTE_YUV422P``
337 - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-F 337 - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>`
338 * - ``VIDEO_PALETTE_YUV411P`` 338 * - ``VIDEO_PALETTE_YUV411P``
339 - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-F 339 - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [#f8]_
340 * - ``VIDEO_PALETTE_YUV420P`` 340 * - ``VIDEO_PALETTE_YUV420P``
341 - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FM 341 - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`
342 * - ``VIDEO_PALETTE_YUV410P`` 342 * - ``VIDEO_PALETTE_YUV410P``
343 - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FM 343 - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`
344 344
345 V4L2 image formats are defined in :ref:`pixfmt 345 V4L2 image formats are defined in :ref:`pixfmt`. The image format can
346 be selected with the :ref:`VIDIOC_S_FMT <VIDIO 346 be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
347 347
348 Audio 348 Audio
349 ===== 349 =====
350 350
351 The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioct 351 The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct
352 ``video_audio`` are used to enumerate the audi 352 ``video_audio`` are used to enumerate the audio inputs
353 of a V4L device. The equivalent V4L2 ioctls ar 353 of a V4L device. The equivalent V4L2 ioctls are
354 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and 354 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
355 :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using s 355 :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct
356 :c:type:`v4l2_audio` as discussed in :ref:`aud 356 :c:type:`v4l2_audio` as discussed in :ref:`audio`.
357 357
358 The ``audio`` "channel number" field counting 358 The ``audio`` "channel number" field counting audio inputs was renamed
359 to ``index``. 359 to ``index``.
360 360
361 On ``VIDIOCSAUDIO`` the ``mode`` field selects 361 On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the
362 ``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, 362 ``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or
363 ``VIDEO_SOUND_LANG2`` audio demodulation modes 363 ``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio
364 standard is BTSC ``VIDEO_SOUND_LANG2`` refers 364 standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and
365 ``VIDEO_SOUND_LANG1`` is meaningless. Also und 365 ``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L
366 specification, there is no way to query the se 366 specification, there is no way to query the selected mode. On
367 ``VIDIOCGAUDIO`` the driver returns the *actua 367 ``VIDIOCGAUDIO`` the driver returns the *actually received* audio
368 programmes in this field. In the V4L2 API this 368 programmes in this field. In the V4L2 API this information is stored in
369 the struct :c:type:`v4l2_tuner` ``rxsubchans`` 369 the struct :c:type:`v4l2_tuner` ``rxsubchans`` and
370 ``audmode`` fields, respectively. See :ref:`tu 370 ``audmode`` fields, respectively. See :ref:`tuner` for more
371 information on tuners. Related to audio modes 371 information on tuners. Related to audio modes struct
372 :c:type:`v4l2_audio` also reports if this is a 372 :c:type:`v4l2_audio` also reports if this is a mono or
373 stereo input, regardless if the source is a tu 373 stereo input, regardless if the source is a tuner.
374 374
375 The following fields where replaced by V4L2 co 375 The following fields where replaced by V4L2 controls accessible with the
376 :ref:`VIDIOC_QUERYCTRL`, 376 :ref:`VIDIOC_QUERYCTRL`,
377 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and 377 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
378 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: 378 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
379 379
380 380
381 .. flat-table:: 381 .. flat-table::
382 :header-rows: 1 382 :header-rows: 1
383 :stub-columns: 0 383 :stub-columns: 0
384 384
385 * - struct ``video_audio`` 385 * - struct ``video_audio``
386 - V4L2 Control ID 386 - V4L2 Control ID
387 * - ``volume`` 387 * - ``volume``
388 - ``V4L2_CID_AUDIO_VOLUME`` 388 - ``V4L2_CID_AUDIO_VOLUME``
389 * - ``bass`` 389 * - ``bass``
390 - ``V4L2_CID_AUDIO_BASS`` 390 - ``V4L2_CID_AUDIO_BASS``
391 * - ``treble`` 391 * - ``treble``
392 - ``V4L2_CID_AUDIO_TREBLE`` 392 - ``V4L2_CID_AUDIO_TREBLE``
393 * - ``balance`` 393 * - ``balance``
394 - ``V4L2_CID_AUDIO_BALANCE`` 394 - ``V4L2_CID_AUDIO_BALANCE``
395 395
396 To determine which of these controls are suppo 396 To determine which of these controls are supported by a driver V4L
397 provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, 397 provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
398 ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALAN 398 ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
399 :ref:`VIDIOC_QUERYCTRL` ioctl reports if the 399 :ref:`VIDIOC_QUERYCTRL` ioctl reports if the
400 respective control is supported. Accordingly t 400 respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``
401 and ``VIDEO_AUDIO_MUTE`` flags where replaced 401 and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean
402 ``V4L2_CID_AUDIO_MUTE`` control. 402 ``V4L2_CID_AUDIO_MUTE`` control.
403 403
404 All V4L2 controls have a ``step`` attribute re 404 All V4L2 controls have a ``step`` attribute replacing the struct
405 ``video_audio`` ``step`` field. The V4L audio 405 ``video_audio`` ``step`` field. The V4L audio controls
406 are assumed to range from 0 to 65535 with no p 406 are assumed to range from 0 to 65535 with no particular reset value. The
407 V4L2 API permits arbitrary limits and defaults 407 V4L2 API permits arbitrary limits and defaults which can be queried with
408 the :ref:`VIDIOC_QUERYCTRL` ioctl. For general 408 the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
409 information about controls see :ref:`control`. 409 information about controls see :ref:`control`.
410 410
411 Frame Buffer Overlay 411 Frame Buffer Overlay
412 ==================== 412 ====================
413 413
414 The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` 414 The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are
415 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and 415 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
416 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``ba 416 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct
417 ``video_buffer`` remained unchanged, except V4 417 ``video_buffer`` remained unchanged, except V4L2 defines
418 a flag to indicate non-destructive overlays in 418 a flag to indicate non-destructive overlays instead of a ``NULL``
419 pointer. All other fields moved into the struc 419 pointer. All other fields moved into the struct
420 :c:type:`v4l2_pix_format` ``fmt`` substructure 420 :c:type:`v4l2_pix_format` ``fmt`` substructure of
421 struct :c:type:`v4l2_framebuffer`. The ``depth 421 struct :c:type:`v4l2_framebuffer`. The ``depth``
422 field was replaced by ``pixelformat``. See :re 422 field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a
423 list of RGB formats and their respective color 423 list of RGB formats and their respective color depths.
424 424
425 Instead of the special ioctls ``VIDIOCGWIN`` a 425 Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2
426 uses the general-purpose data format negotiati 426 uses the general-purpose data format negotiation ioctls
427 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and 427 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
428 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take 428 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
429 :c:type:`v4l2_format` as argument. Here the `` 429 :c:type:`v4l2_format` as argument. Here the ``win`` member
430 of the ``fmt`` union is used, a struct 430 of the ``fmt`` union is used, a struct
431 :c:type:`v4l2_window`. 431 :c:type:`v4l2_window`.
432 432
433 The ``x``, ``y``, ``width`` and ``height`` fie 433 The ``x``, ``y``, ``width`` and ``height`` fields of struct
434 ``video_window`` moved into struct 434 ``video_window`` moved into struct
435 :c:type:`v4l2_rect` substructure ``w`` of stru 435 :c:type:`v4l2_rect` substructure ``w`` of struct
436 :c:type:`v4l2_window`. The ``chromakey``, ``cl 436 :c:type:`v4l2_window`. The ``chromakey``, ``clips``, and
437 ``clipcount`` fields remained unchanged. Struc 437 ``clipcount`` fields remained unchanged. Struct
438 ``video_clip`` was renamed to struct 438 ``video_clip`` was renamed to struct
439 :c:type:`v4l2_clip`, also containing a struct 439 :c:type:`v4l2_clip`, also containing a struct
440 :c:type:`v4l2_rect`, but the semantics are sti 440 :c:type:`v4l2_rect`, but the semantics are still the same.
441 441
442 The ``VIDEO_WINDOW_INTERLACE`` flag was droppe 442 The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications
443 must set the ``field`` field to ``V4L2_FIELD_A 443 must set the ``field`` field to ``V4L2_FIELD_ANY`` or
444 ``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_ 444 ``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved
445 into struct :c:type:`v4l2_framebuffer`, under 445 into struct :c:type:`v4l2_framebuffer`, under the new
446 name ``V4L2_FBUF_FLAG_CHROMAKEY``. 446 name ``V4L2_FBUF_FLAG_CHROMAKEY``.
447 447
448 In V4L, storing a bitmap pointer in ``clips`` 448 In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``
449 to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap 449 to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed
450 size bitmap of 1024 × 625 bits. Struct :c:typ 450 size bitmap of 1024 × 625 bits. Struct :c:type:`v4l2_window`
451 has a separate ``bitmap`` pointer field for th 451 has a separate ``bitmap`` pointer field for this purpose and the bitmap
452 size is determined by ``w.width`` and ``w.heig 452 size is determined by ``w.width`` and ``w.height``.
453 453
454 The ``VIDIOCCAPTURE`` ioctl to enable or disab 454 The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
455 :ref:`VIDIOC_OVERLAY`. 455 :ref:`VIDIOC_OVERLAY`.
456 456
457 Cropping 457 Cropping
458 ======== 458 ========
459 459
460 To capture only a subsection of the full pictu 460 To capture only a subsection of the full picture V4L defines the
461 ``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioct 461 ``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct
462 ``video_capture``. The equivalent V4L2 ioctls 462 ``video_capture``. The equivalent V4L2 ioctls are
463 :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and 463 :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
464 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using str 464 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct
465 :c:type:`v4l2_crop`, and the related 465 :c:type:`v4l2_crop`, and the related
466 :ref:`VIDIOC_CROPCAP` ioctl. This is a rather 466 :ref:`VIDIOC_CROPCAP` ioctl. This is a rather
467 complex matter, see :ref:`crop` for details. 467 complex matter, see :ref:`crop` for details.
468 468
469 The ``x``, ``y``, ``width`` and ``height`` fie 469 The ``x``, ``y``, ``width`` and ``height`` fields moved into struct
470 :c:type:`v4l2_rect` substructure ``c`` of stru 470 :c:type:`v4l2_rect` substructure ``c`` of struct
471 :c:type:`v4l2_crop`. The ``decimation`` field 471 :c:type:`v4l2_crop`. The ``decimation`` field was dropped. In
472 the V4L2 API the scaling factor is implied by 472 the V4L2 API the scaling factor is implied by the size of the cropping
473 rectangle and the size of the captured or over 473 rectangle and the size of the captured or overlaid image.
474 474
475 The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_ 475 The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture
476 only the odd or even field, respectively, were 476 only the odd or even field, respectively, were replaced by
477 ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` i 477 ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named
478 ``field`` of struct :c:type:`v4l2_pix_format` 478 ``field`` of struct :c:type:`v4l2_pix_format` and
479 struct :c:type:`v4l2_window`. These structures 479 struct :c:type:`v4l2_window`. These structures are used to
480 select a capture or overlay format with the 480 select a capture or overlay format with the
481 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. 481 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
482 482
483 Reading Images, Memory Mapping 483 Reading Images, Memory Mapping
484 ============================== 484 ==============================
485 485
486 Capturing using the read method 486 Capturing using the read method
487 ------------------------------- 487 -------------------------------
488 488
489 There is no essential difference between readi 489 There is no essential difference between reading images from a V4L or
490 V4L2 device using the :c:func:`read()` functio 490 V4L2 device using the :c:func:`read()` function, however V4L2
491 drivers are not required to support this I/O m 491 drivers are not required to support this I/O method. Applications can
492 determine if the function is available with th 492 determine if the function is available with the
493 :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices 493 :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
494 exchanging data with applications must support 494 exchanging data with applications must support the
495 :c:func:`select()` and :c:func:`poll()` 495 :c:func:`select()` and :c:func:`poll()`
496 functions. 496 functions.
497 497
498 To select an image format and size, V4L provid 498 To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
499 ``VIDIOCSWIN`` ioctls. V4L2 uses the general-p 499 ``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format
500 negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_ 500 negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
501 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take 501 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
502 :c:type:`v4l2_format` as argument, here the st 502 :c:type:`v4l2_format` as argument, here the struct
503 :c:type:`v4l2_pix_format` named ``pix`` of its 503 :c:type:`v4l2_pix_format` named ``pix`` of its
504 ``fmt`` union is used. 504 ``fmt`` union is used.
505 505
506 For more information about the V4L2 read inter 506 For more information about the V4L2 read interface see :ref:`rw`.
507 507
508 Capturing using memory mapping 508 Capturing using memory mapping
509 ------------------------------ 509 ------------------------------
510 510
511 Applications can read from V4L devices by mapp 511 Applications can read from V4L devices by mapping buffers in device
512 memory, or more often just buffers allocated i 512 memory, or more often just buffers allocated in DMA-able system memory,
513 into their address space. This avoids the data 513 into their address space. This avoids the data copying overhead of the
514 read method. V4L2 supports memory mapping as w 514 read method. V4L2 supports memory mapping as well, with a few
515 differences. 515 differences.
516 516
517 517
518 .. flat-table:: 518 .. flat-table::
519 :header-rows: 1 519 :header-rows: 1
520 :stub-columns: 0 520 :stub-columns: 0
521 521
522 * - V4L 522 * - V4L
523 - V4L2 523 - V4L2
524 * - 524 * -
525 - The image format must be selected befo 525 - The image format must be selected before buffers are allocated,
526 with the :ref:`VIDIOC_S_FMT <VIDIOC_G_ 526 with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no
527 format is selected the driver may use 527 format is selected the driver may use the last, possibly by
528 another application requested format. 528 another application requested format.
529 * - Applications cannot change the number 529 * - Applications cannot change the number of buffers. The it is built
530 into the driver, unless it has a modul 530 into the driver, unless it has a module option to change the
531 number when the driver module is loade 531 number when the driver module is loaded.
532 - The :ref:`VIDIOC_REQBUFS` ioctl alloca 532 - The :ref:`VIDIOC_REQBUFS` ioctl allocates the
533 desired number of buffers, this is a r 533 desired number of buffers, this is a required step in the
534 initialization sequence. 534 initialization sequence.
535 * - Drivers map all buffers as one contigu 535 * - Drivers map all buffers as one contiguous range of memory. The
536 ``VIDIOCGMBUF`` ioctl is available to 536 ``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
537 the offset of each buffer from the sta 537 the offset of each buffer from the start of the virtual file, and
538 the overall amount of memory used, whi 538 the overall amount of memory used, which can be used as arguments
539 for the :c:func:`mmap()` function. 539 for the :c:func:`mmap()` function.
540 - Buffers are individually mapped. The o 540 - Buffers are individually mapped. The offset and size of each
541 buffer can be determined with the 541 buffer can be determined with the
542 :ref:`VIDIOC_QUERYBUF` ioctl. 542 :ref:`VIDIOC_QUERYBUF` ioctl.
543 * - The ``VIDIOCMCAPTURE`` ioctl prepares 543 * - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It
544 also determines the image format for t 544 also determines the image format for this buffer. The ioctl
545 returns immediately, eventually with a 545 returns immediately, eventually with an ``EAGAIN`` error code if no
546 video signal had been detected. When t 546 video signal had been detected. When the driver supports more than
547 one buffer applications can call the i 547 one buffer applications can call the ioctl multiple times and thus
548 have multiple outstanding capture requ 548 have multiple outstanding capture requests.
549 549
550 The ``VIDIOCSYNC`` ioctl suspends exec 550 The ``VIDIOCSYNC`` ioctl suspends execution until a particular
551 buffer has been filled. 551 buffer has been filled.
552 - Drivers maintain an incoming and outgo 552 - Drivers maintain an incoming and outgoing queue.
553 :ref:`VIDIOC_QBUF` enqueues any empty 553 :ref:`VIDIOC_QBUF` enqueues any empty buffer into
554 the incoming queue. Filled buffers are 554 the incoming queue. Filled buffers are dequeued from the outgoing
555 queue with the :ref:`VIDIOC_DQBUF <VID 555 queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
556 until filled buffers become available 556 until filled buffers become available this function,
557 :c:func:`select()` or :c:func:`poll()` 557 :c:func:`select()` or :c:func:`poll()` can
558 be used. The :ref:`VIDIOC_STREAMON` io 558 be used. The :ref:`VIDIOC_STREAMON` ioctl
559 must be called once after enqueuing on 559 must be called once after enqueuing one or more buffers to start
560 capturing. Its counterpart 560 capturing. Its counterpart
561 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMO 561 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and
562 dequeues all buffers from both queues. 562 dequeues all buffers from both queues. Applications can query the
563 signal status, if known, with the 563 signal status, if known, with the
564 :ref:`VIDIOC_ENUMINPUT` ioctl. 564 :ref:`VIDIOC_ENUMINPUT` ioctl.
565 565
566 For a more in-depth discussion of memory mappi 566 For a more in-depth discussion of memory mapping and examples, see
567 :ref:`mmap`. 567 :ref:`mmap`.
568 568
569 Reading Raw VBI Data 569 Reading Raw VBI Data
570 ==================== 570 ====================
571 571
572 Originally the V4L API did not specify a raw V 572 Originally the V4L API did not specify a raw VBI capture interface, only
573 the device file ``/dev/vbi`` was reserved for 573 the device file ``/dev/vbi`` was reserved for this purpose. The only
574 driver supporting this interface was the BTTV 574 driver supporting this interface was the BTTV driver, de-facto defining
575 the V4L VBI interface. Reading from the device 575 the V4L VBI interface. Reading from the device yields a raw VBI image
576 with the following parameters: 576 with the following parameters:
577 577
578 578
579 .. flat-table:: 579 .. flat-table::
580 :header-rows: 1 580 :header-rows: 1
581 :stub-columns: 0 581 :stub-columns: 0
582 582
583 * - struct :c:type:`v4l2_vbi_format` 583 * - struct :c:type:`v4l2_vbi_format`
584 - V4L, BTTV driver 584 - V4L, BTTV driver
585 * - sampling_rate 585 * - sampling_rate
586 - 28636363 Hz NTSC (or any other 525-lin 586 - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL
587 and SECAM (625-line standards) 587 and SECAM (625-line standards)
588 * - offset 588 * - offset
589 - ? 589 - ?
590 * - samples_per_line 590 * - samples_per_line
591 - 2048 591 - 2048
592 * - sample_format 592 * - sample_format
593 - V4L2_PIX_FMT_GREY. The last four bytes 593 - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness
594 integer) contain a frame counter. 594 integer) contain a frame counter.
595 * - start[] 595 * - start[]
596 - 10, 273 NTSC; 22, 335 PAL and SECAM 596 - 10, 273 NTSC; 22, 335 PAL and SECAM
597 * - count[] 597 * - count[]
598 - 16, 16 [#f9]_ 598 - 16, 16 [#f9]_
599 * - flags 599 * - flags
600 - 0 600 - 0
601 601
602 Undocumented in the V4L specification, in Linu 602 Undocumented in the V4L specification, in Linux 2.3 the
603 ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls 603 ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
604 ``vbi_format`` were added to determine the VBI 604 ``vbi_format`` were added to determine the VBI image
605 parameters. These ioctls are only partially co 605 parameters. These ioctls are only partially compatible with the V4L2 VBI
606 interface specified in :ref:`raw-vbi`. 606 interface specified in :ref:`raw-vbi`.
607 607
608 An ``offset`` field does not exist, ``sample_f 608 An ``offset`` field does not exist, ``sample_format`` is supposed to be
609 ``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PI 609 ``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The
610 remaining fields are probably equivalent to st 610 remaining fields are probably equivalent to struct
611 :c:type:`v4l2_vbi_format`. 611 :c:type:`v4l2_vbi_format`.
612 612
613 Apparently only the Zoran (ZR 36120) driver im 613 Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
614 semantics differ from those specified for V4L2 614 semantics differ from those specified for V4L2 in two ways. The
615 parameters are reset on :c:func:`open()` and 615 parameters are reset on :c:func:`open()` and
616 ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` 616 ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
617 are invalid. 617 are invalid.
618 618
619 Miscellaneous 619 Miscellaneous
620 ============= 620 =============
621 621
622 V4L2 has no equivalent of the ``VIDIOCGUNIT`` 622 V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can
623 find the VBI device associated with a video ca 623 find the VBI device associated with a video capture device (or vice
624 versa) by reopening the device and requesting 624 versa) by reopening the device and requesting VBI data. For details see
625 :ref:`open`. 625 :ref:`open`.
626 626
627 No replacement exists for ``VIDIOCKEY``, and t 627 No replacement exists for ``VIDIOCKEY``, and the V4L functions for
628 microcode programming. A new interface for MPE 628 microcode programming. A new interface for MPEG compression and playback
629 devices is documented in :ref:`extended-contro 629 devices is documented in :ref:`extended-controls`.
630 630
631 .. [#f1] 631 .. [#f1]
632 According to Documentation/admin-guide/devi 632 According to Documentation/admin-guide/devices.rst these should be symbolic links
633 to ``/dev/video0``. Note the original bttv 633 to ``/dev/video0``. Note the original bttv interface is not
634 compatible with V4L or V4L2. 634 compatible with V4L or V4L2.
635 635
636 .. [#f2] 636 .. [#f2]
637 According to ``Documentation/admin-guide/de 637 According to ``Documentation/admin-guide/devices.rst`` a symbolic link to
638 ``/dev/radio0``. 638 ``/dev/radio0``.
639 639
640 .. [#f3] 640 .. [#f3]
641 This is a custom format used by the BTTV dr 641 This is a custom format used by the BTTV driver, not one of the V4L2
642 standard formats. 642 standard formats.
643 643
644 .. [#f4] 644 .. [#f4]
645 Presumably all V4L RGB formats are little-e 645 Presumably all V4L RGB formats are little-endian, although some
646 drivers might interpret them according to m 646 drivers might interpret them according to machine endianness. V4L2
647 defines little-endian, big-endian and red/b 647 defines little-endian, big-endian and red/blue swapped variants. For
648 details see :ref:`pixfmt-rgb`. 648 details see :ref:`pixfmt-rgb`.
649 649
650 .. [#f5] 650 .. [#f5]
651 ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETT 651 ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same
652 formats. Some V4L drivers respond to one, s 652 formats. Some V4L drivers respond to one, some to the other.
653 653
654 .. [#f6] 654 .. [#f6]
655 Not to be confused with ``V4L2_PIX_FMT_YUV4 655 Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar
656 format. 656 format.
657 657
658 .. [#f7] 658 .. [#f7]
659 V4L explains this as: "RAW capture (BT848)" 659 V4L explains this as: "RAW capture (BT848)"
660 660
661 .. [#f8] 661 .. [#f8]
662 Not to be confused with ``V4L2_PIX_FMT_Y41P 662 Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed
663 format. 663 format.
664 664
665 .. [#f9] 665 .. [#f9]
666 Old driver versions used different values, 666 Old driver versions used different values, eventually the custom
667 ``BTTV_VBISIZE`` ioctl was added to query t 667 ``BTTV_VBISIZE`` ioctl was added to query the correct values.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.