Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame^] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _format: |
| 4 | |
| 5 | ************ |
| 6 | Data Formats |
| 7 | ************ |
| 8 | |
| 9 | |
| 10 | Data Format Negotiation |
| 11 | ======================= |
| 12 | |
| 13 | Different devices exchange different kinds of data with applications, |
| 14 | for example video images, raw or sliced VBI data, RDS datagrams. Even |
| 15 | within one kind many different formats are possible, in particular an |
| 16 | abundance of image formats. Although drivers must provide a default and |
| 17 | the selection persists across closing and reopening a device, |
| 18 | applications should always negotiate a data format before engaging in |
| 19 | data exchange. Negotiation means the application asks for a particular |
| 20 | format and the driver selects and reports the best the hardware can do |
| 21 | to satisfy the request. Of course applications can also just query the |
| 22 | current selection. |
| 23 | |
| 24 | A single mechanism exists to negotiate all data formats using the |
| 25 | aggregate struct :ref:`v4l2_format <v4l2-format>` and the |
| 26 | :ref:`VIDIOC_G_FMT <vidioc-g-fmt>` and |
| 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 |
| 29 | what the hardware *could* do, without actually selecting a new data |
| 30 | format. The data formats supported by the V4L2 API are covered in the |
| 31 | respective device section in :ref:`devices`. For a closer look at |
| 32 | image formats see :ref:`pixfmt`. |
| 33 | |
| 34 | The ``VIDIOC_S_FMT`` ioctl is a major turning-point in the |
| 35 | initialization sequence. Prior to this point multiple panel applications |
| 36 | can access the same device concurrently to select the current input, |
| 37 | change controls or modify other properties. The first ``VIDIOC_S_FMT`` |
| 38 | assigns a logical stream (video data, VBI data etc.) exclusively to one |
| 39 | file descriptor. |
| 40 | |
| 41 | Exclusive means no other application, more precisely no other file |
| 42 | descriptor, can grab this stream or change device properties |
| 43 | inconsistent with the negotiated parameters. A video standard change for |
| 44 | example, when the new standard uses a different number of scan lines, |
| 45 | can invalidate the selected image format. Therefore only the file |
| 46 | descriptor owning the stream can make invalidating changes. Accordingly |
| 47 | multiple file descriptors which grabbed different logical streams |
| 48 | prevent each other from interfering with their settings. When for |
| 49 | example video overlay is about to start or already in progress, |
| 50 | simultaneous video capturing may be restricted to the same cropping and |
| 51 | image size. |
| 52 | |
| 53 | When applications omit the ``VIDIOC_S_FMT`` ioctl its locking side |
| 54 | effects are implied by the next step, the selection of an I/O method |
| 55 | with the :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl or implicit |
| 56 | with the first :ref:`read() <func-read>` or |
| 57 | :ref:`write() <func-write>` call. |
| 58 | |
| 59 | Generally only one logical stream can be assigned to a file descriptor, |
| 60 | the exception being drivers permitting simultaneous video capturing and |
| 61 | overlay using the same file descriptor for compatibility with V4L and |
| 62 | earlier versions of V4L2. Switching the logical stream or returning into |
| 63 | "panel mode" is possible by closing and reopening the device. Drivers |
| 64 | *may* support a switch using ``VIDIOC_S_FMT``. |
| 65 | |
| 66 | All drivers exchanging data with applications must support the |
| 67 | ``VIDIOC_G_FMT`` and ``VIDIOC_S_FMT`` ioctl. Implementation of the |
| 68 | ``VIDIOC_TRY_FMT`` is highly recommended but optional. |
| 69 | |
| 70 | |
| 71 | Image Format Enumeration |
| 72 | ======================== |
| 73 | |
| 74 | Apart of the generic format negotiation functions a special ioctl to |
| 75 | enumerate all image formats supported by video capture, overlay or |
| 76 | output devices is available. [1]_ |
| 77 | |
| 78 | The :ref:`VIDIOC_ENUM_FMT <vidioc-enum-fmt>` ioctl must be supported |
| 79 | by 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 | |
| 88 | .. [1] |
| 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. |
| 93 | |
| 94 | |
| 95 | .. ------------------------------------------------------------------------------ |
| 96 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 97 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 98 | .. from the linux kernel, refer to: |
| 99 | .. |
| 100 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 101 | .. ------------------------------------------------------------------------------ |