Documentation/media/uapi/v4l/dev-codec.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 .. _codec:
  11
  12 ***************
  13 Codec Interface
  14 ***************
  15
  16 A V4L2 codec can compress, decompress, transform, or otherwise convert
  17 video data from one format into another format, in memory. Typically
  18 such devices are memory-to-memory devices (i.e. devices with the
  19 ``V4L2_CAP_VIDEO_M2M`` or ``V4L2_CAP_VIDEO_M2M_MPLANE`` capability set).
  20
  21 A memory-to-memory video node acts just like a normal video node, but it
  22 supports both output (sending frames from memory to the codec hardware)
  23 and capture (receiving the processed frames from the codec hardware into
  24 memory) stream I/O. An application will have to setup the stream I/O for
  25 both sides and finally call :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
  26 for both capture and output to start the codec.
  27
  28 Video compression codecs use the MPEG controls to setup their codec
  29 parameters
  30
  31 .. note::
  32
  33    The MPEG controls actually support many more codecs than
  34    just MPEG. See :ref:`mpeg-controls`.
  35
  36 Memory-to-memory devices function as a shared resource: you can
  37 open the video node multiple times, each application setting up their
  38 own codec properties that are local to the file handle, and each can use
  39 it independently from the others. The driver will arbitrate access to
  40 the codec and reprogram it whenever another file handler gets access.
  41 This is different from the usual video node behavior where the video
  42 properties are global to the device (i.e. changing something through one
  43 file handle is visible through another file handle).