Merge remote-tracking branch 'omap_dss2/for-next'
[deliverable/linux.git] / Documentation / media / uapi / v4l / format.rst
CommitLineData
5377d91f
MH
1.. -*- coding: utf-8; mode: rst -*-
2
3.. _format:
4
5************
6Data Formats
7************
8
9
10Data Format Negotiation
11=======================
12
13Different devices exchange different kinds of data with applications,
14for example video images, raw or sliced VBI data, RDS datagrams. Even
15within one kind many different formats are possible, in particular an
16abundance of image formats. Although drivers must provide a default and
17the selection persists across closing and reopening a device,
18applications should always negotiate a data format before engaging in
19data exchange. Negotiation means the application asks for a particular
20format and the driver selects and reports the best the hardware can do
21to satisfy the request. Of course applications can also just query the
22current selection.
23
24A single mechanism exists to negotiate all data formats using the
e8be7e97 25aggregate struct :c:type:`v4l2_format` and the
4e03cb76 26:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
af4a4d0d
MCC
27:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the
28:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine
5377d91f
MH
29what the hardware *could* do, without actually selecting a new data
30format. The data formats supported by the V4L2 API are covered in the
31respective device section in :ref:`devices`. For a closer look at
32image formats see :ref:`pixfmt`.
33
2212ff25 34The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the
5377d91f
MH
35initialization sequence. Prior to this point multiple panel applications
36can access the same device concurrently to select the current input,
2212ff25 37change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
5377d91f
MH
38assigns a logical stream (video data, VBI data etc.) exclusively to one
39file descriptor.
40
41Exclusive means no other application, more precisely no other file
42descriptor, can grab this stream or change device properties
43inconsistent with the negotiated parameters. A video standard change for
44example, when the new standard uses a different number of scan lines,
45can invalidate the selected image format. Therefore only the file
46descriptor owning the stream can make invalidating changes. Accordingly
47multiple file descriptors which grabbed different logical streams
48prevent each other from interfering with their settings. When for
49example video overlay is about to start or already in progress,
50simultaneous video capturing may be restricted to the same cropping and
51image size.
52
2212ff25 53When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side
5377d91f 54effects are implied by the next step, the selection of an I/O method
7347081e 55with the :ref:`VIDIOC_REQBUFS` ioctl or implicit
5377d91f
MH
56with the first :ref:`read() <func-read>` or
57:ref:`write() <func-write>` call.
58
59Generally only one logical stream can be assigned to a file descriptor,
60the exception being drivers permitting simultaneous video capturing and
61overlay using the same file descriptor for compatibility with V4L and
62earlier versions of V4L2. Switching the logical stream or returning into
63"panel mode" is possible by closing and reopening the device. Drivers
2212ff25 64*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
5377d91f
MH
65
66All drivers exchanging data with applications must support the
4e03cb76 67:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the
2212ff25 68:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.
5377d91f
MH
69
70
71Image Format Enumeration
72========================
73
74Apart of the generic format negotiation functions a special ioctl to
75enumerate all image formats supported by video capture, overlay or
4855307b 76output devices is available. [#f1]_
5377d91f 77
7347081e 78The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported
5377d91f
MH
79by all drivers exchanging image data with applications.
80
81 **Important**
82
83 Drivers are not supposed to convert image formats in kernel space.
84 They must enumerate only formats directly supported by the hardware.
85 If necessary driver writers should publish an example conversion
86 routine or library for integration into applications.
87
4855307b 88.. [#f1]
5377d91f
MH
89 Enumerating formats an application has no a-priori knowledge of
90 (otherwise it could explicitly ask for them and need not enumerate)
91 seems useless, but there are applications serving as proxy between
92 drivers and the actual video applications for which this is useful.
This page took 0.069961 seconds and 5 git commands to generate.