1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
2 .. c:namespace:: V4L
3
4 .. _format:
5
6 ************
7 Data Formats
8 ************
9
10 Data Format Negotiation
11 =======================
12
13 Different devices exchange different kinds of
14 for example video images, raw or sliced VBI da
15 within one kind many different formats are pos
16 abundance of image formats. Although drivers m
17 the selection persists across closing and reop
18 applications should always negotiate a data fo
19 data exchange. Negotiation means the applicati
20 format and the driver selects and reports the
21 to satisfy the request. Of course applications
22 current selection.
23
24 A single mechanism exists to negotiate all dat
25 aggregate struct :c:type:`v4l2_format` and the
26 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
27 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Add
28 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can
29 what the hardware *could* do, without actually
30 format. The data formats supported by the V4L2
31 respective device section in :ref:`devices`. F
32 image formats see :ref:`pixfmt`.
33
34 The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl i
35 initialization sequence. Prior to this point m
36 can access the same device concurrently to sel
37 change controls or modify other properties. Th
38 assigns a logical stream (video data, VBI data
39 file descriptor.
40
41 Exclusive means no other application, more pre
42 descriptor, can grab this stream or change dev
43 inconsistent with the negotiated parameters. A
44 example, when the new standard uses a differen
45 can invalidate the selected image format. Ther
46 descriptor owning the stream can make invalida
47 multiple file descriptors which grabbed differ
48 prevent each other from interfering with their
49 example video overlay is about to start or alr
50 simultaneous video capturing may be restricted
51 image size.
52
53 When applications omit the :ref:`VIDIOC_S_FMT
54 effects are implied by the next step, the sele
55 with the :ref:`VIDIOC_REQBUFS` ioctl or implic
56 with the first :c:func:`read()` or
57 :c:func:`write()` call.
58
59 Generally only one logical stream can be assig
60 the exception being drivers permitting simulta
61 overlay using the same file descriptor for com
62 earlier versions of V4L2. Switching the logica
63 "panel mode" is possible by closing and reopen
64 *may* support a switch using :ref:`VIDIOC_S_FM
65
66 All drivers exchanging data with applications
67 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`V
68 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly
69
70 Image Format Enumeration
71 ========================
72
73 Apart of the generic format negotiation functi
74 enumerate all image formats supported by video
75 output devices is available. [#f1]_
76
77 The :ref:`VIDIOC_ENUM_FMT` ioctl must be suppo
78 by all drivers exchanging image data with appl
79
80 .. important::
81
82 Drivers are not supposed to convert image
83 They must enumerate only formats directly
84 If necessary driver writers should publish
85 routine or library for integration into ap
86
87 .. [#f1]
88 Enumerating formats an application has no a
89 (otherwise it could explicitly ask for them
90 seems useless, but there are applications s
91 drivers and the actual video applications f
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.