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