Documentation/media/uapi/v4l/streaming-par.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 .. _streaming-par:
  11
  12 ********************
  13 Streaming Parameters
  14 ********************
  15
  16 Streaming parameters are intended to optimize the video capture process
  17 as well as I/O. Presently applications can request a high quality
  18 capture mode with the :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl.
  19
  20 The current video standard determines a nominal number of frames per
  21 second. If less than this number of frames is to be captured or output,
  22 applications can request frame skipping or duplicating on the driver
  23 side. This is especially useful when using the
  24 :ref:`read() <func-read>` or :ref:`write() <func-write>`, which are
  25 not augmented by timestamps or sequence counters, and to avoid
  26 unnecessary data copying.
  27
  28 Finally these ioctls can be used to determine the number of buffers used
  29 internally by a driver in read/write mode. For implications see the
  30 section discussing the :ref:`read() <func-read>` function.
  31
  32 To get and set the streaming parameters applications call the
  33 :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
  34 :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take
  35 a pointer to a struct :c:type:`v4l2_streamparm`, which
  36 contains a union holding separate parameters for input and output
  37 devices.
  38
  39 These ioctls are optional, drivers need not implement them. If so, they
  40 return the ``EINVAL`` error code.