diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/format.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/format.rst | 99 |
1 files changed, 0 insertions, 99 deletions
diff --git a/Documentation/media/uapi/v4l/format.rst b/Documentation/media/uapi/v4l/format.rst deleted file mode 100644 index 9cdb296333b8..000000000000 --- a/Documentation/media/uapi/v4l/format.rst +++ /dev/null @@ -1,99 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _format: - -************ -Data Formats -************ - - -Data Format Negotiation -======================= - -Different devices exchange different kinds of data with applications, -for example video images, raw or sliced VBI data, RDS datagrams. Even -within one kind many different formats are possible, in particular there is an -abundance of image formats. Although drivers must provide a default and -the selection persists across closing and reopening a device, -applications should always negotiate a data format before engaging in -data exchange. Negotiation means the application asks for a particular -format and the driver selects and reports the best the hardware can do -to satisfy the request. Of course applications can also just query the -current selection. - -A single mechanism exists to negotiate all data formats using the -aggregate struct :c:type:`v4l2_format` and the -:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and -:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the -:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine -what the hardware *could* do, without actually selecting a new data -format. The data formats supported by the V4L2 API are covered in the -respective device section in :ref:`devices`. For a closer look at -image formats see :ref:`pixfmt`. - -The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the -initialization sequence. Prior to this point multiple panel applications -can access the same device concurrently to select the current input, -change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` -assigns a logical stream (video data, VBI data etc.) exclusively to one -file descriptor. - -Exclusive means no other application, more precisely no other file -descriptor, can grab this stream or change device properties -inconsistent with the negotiated parameters. A video standard change for -example, when the new standard uses a different number of scan lines, -can invalidate the selected image format. Therefore only the file -descriptor owning the stream can make invalidating changes. Accordingly -multiple file descriptors which grabbed different logical streams -prevent each other from interfering with their settings. When for -example video overlay is about to start or already in progress, -simultaneous video capturing may be restricted to the same cropping and -image size. - -When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side -effects are implied by the next step, the selection of an I/O method -with the :ref:`VIDIOC_REQBUFS` ioctl or implicit -with the first :ref:`read() <func-read>` or -:ref:`write() <func-write>` call. - -Generally only one logical stream can be assigned to a file descriptor, -the exception being drivers permitting simultaneous video capturing and -overlay using the same file descriptor for compatibility with V4L and -earlier versions of V4L2. Switching the logical stream or returning into -"panel mode" is possible by closing and reopening the device. Drivers -*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. - -All drivers exchanging data with applications must support the -:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the -:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. - - -Image Format Enumeration -======================== - -Apart of the generic format negotiation functions a special ioctl to -enumerate all image formats supported by video capture, overlay or -output devices is available. [#f1]_ - -The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported -by all drivers exchanging image data with applications. - -.. important:: - - Drivers are not supposed to convert image formats in kernel space. - They must enumerate only formats directly supported by the hardware. - If necessary driver writers should publish an example conversion - routine or library for integration into applications. - -.. [#f1] - Enumerating formats an application has no a-priori knowledge of - (otherwise it could explicitly ask for them and need not enumerate) - seems useless, but there are applications serving as proxy between - drivers and the actual video applications for which this is useful. |