Documentation/DocBook/v4l/dev-capture.xml

   1   <title>Video Capture Interface</title>
   2
   3   <para>Video capture devices sample an analog video signal and store
   4 the digitized images in memory. Today nearly all devices can capture
   5 at full 25 or 30 frames/second. With this interface applications can
   6 control the capture process and move images from the driver into user
   7 space.</para>
   8
   9   <para>Conventionally V4L2 video capture devices are accessed through
  10 character device special files named <filename>/dev/video</filename>
  11 and <filename>/dev/video0</filename> to
  12 <filename>/dev/video63</filename> with major number 81 and minor
  13 numbers 0 to 63. <filename>/dev/video</filename> is typically a
  14 symbolic link to the preferred video device. Note the same device
  15 files are used for video output devices.</para>
  16
  17   <section>
  18     <title>Querying Capabilities</title>
  19
  20     <para>Devices supporting the video capture interface set the
  21 <constant>V4L2_CAP_VIDEO_CAPTURE</constant> flag in the
  22 <structfield>capabilities</structfield> field of &v4l2-capability;
  23 returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
  24 they may also support the <link linkend="overlay">video overlay</link>
  25 (<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link
  26 linkend="raw-vbi">raw VBI capture</link>
  27 (<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of
  28 the read/write or streaming I/O methods must be supported. Tuners and
  29 audio inputs are optional.</para>
  30   </section>
  31
  32   <section>
  33     <title>Supplemental Functions</title>
  34
  35     <para>Video capture devices shall support <link
  36 linkend="audio">audio input</link>, <link
  37 linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
  38 <link linkend="crop">cropping and scaling</link> and <link
  39 linkend="streaming-par">streaming parameter</link> ioctls as needed.
  40 The <link linkend="video">video input</link> and <link
  41 linkend="standard">video standard</link> ioctls must be supported by
  42 all video capture devices.</para>
  43   </section>
  44
  45   <section>
  46     <title>Image Format Negotiation</title>
  47
  48     <para>The result of a capture operation is determined by
  49 cropping and image format parameters. The former select an area of the
  50 video picture to capture, the latter how images are stored in memory,
  51 &ie; in RGB or YUV format, the number of bits per pixel or width and
  52 height. Together they also define how images are scaled in the
  53 process.</para>
  54
  55     <para>As usual these parameters are <emphasis>not</emphasis> reset
  56 at &func-open; time to permit Unix tool chains, programming a device
  57 and then reading from it as if it was a plain file. Well written V4L2
  58 applications ensure they really get what they want, including cropping
  59 and scaling.</para>
  60
  61     <para>Cropping initialization at minimum requires to reset the
  62 parameters to defaults. An example is given in <xref
  63 linkend="crop" />.</para>
  64
  65     <para>To query the current image format applications set the
  66 <structfield>type</structfield> field of a &v4l2-format; to
  67 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and call the
  68 &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
  69 the &v4l2-pix-format; <structfield>pix</structfield> member of the
  70 <structfield>fmt</structfield> union.</para>
  71
  72     <para>To request different parameters applications set the
  73 <structfield>type</structfield> field of a &v4l2-format; as above and
  74 initialize all fields of the &v4l2-pix-format;
  75 <structfield>vbi</structfield> member of the
  76 <structfield>fmt</structfield> union, or better just modify the
  77 results of <constant>VIDIOC_G_FMT</constant>, and call the
  78 &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
  79 adjust the parameters and finally return the actual parameters as
  80 <constant>VIDIOC_G_FMT</constant> does.</para>
  81
  82     <para>Like <constant>VIDIOC_S_FMT</constant> the
  83 &VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
  84 without disabling I/O or possibly time consuming hardware
  85 preparations.</para>
  86
  87     <para>The contents of &v4l2-pix-format; are discussed in <xref
  88 linkend="pixfmt" />. See also the specification of the
  89 <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
  90 and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
  91 capture devices must implement both the
  92 <constant>VIDIOC_G_FMT</constant> and
  93 <constant>VIDIOC_S_FMT</constant> ioctl, even if
  94 <constant>VIDIOC_S_FMT</constant> ignores all requests and always
  95 returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
  96 <constant>VIDIOC_TRY_FMT</constant> is optional.</para>
  97   </section>
  98
  99   <section>
 100     <title>Reading Images</title>
 101
 102     <para>A video capture device may support the <link
 103 linkend="rw">read() function</link> and/or streaming (<link
 104 linkend="mmap">memory mapping</link> or <link
 105 linkend="userp">user pointer</link>) I/O. See <xref
 106 linkend="io" /> for details.</para>
 107   </section>
 108
 109   <!--
 110 Local Variables:
 111 mode: sgml
 112 sgml-parent-document: "v4l2.sgml"
 113 indent-tabs-mode: nil
 114 End:
 115   -->