Documentation/media/uapi/v4l/format.rst

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