Based on kernel version 4.7.2. Page generated on 2016-08-22 22:44 EST.
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> or 22 <constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant> flag in the 23 <structfield>capabilities</structfield> field of &v4l2-capability; 24 returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions 25 they may also support the <link linkend="overlay">video overlay</link> 26 (<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link 27 linkend="raw-vbi">raw VBI capture</link> 28 (<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of 29 the read/write or streaming I/O methods must be supported. Tuners and 30 audio inputs are optional.</para> 31 </section> 32 33 <section> 34 <title>Supplemental Functions</title> 35 36 <para>Video capture devices shall support <link 37 linkend="audio">audio input</link>, <link 38 linkend="tuner">tuner</link>, <link linkend="control">controls</link>, 39 <link linkend="crop">cropping and scaling</link> and <link 40 linkend="streaming-par">streaming parameter</link> ioctls as needed. 41 The <link linkend="video">video input</link> and <link 42 linkend="standard">video standard</link> ioctls must be supported by 43 all video capture devices.</para> 44 </section> 45 46 <section> 47 <title>Image Format Negotiation</title> 48 49 <para>The result of a capture operation is determined by 50 cropping and image format parameters. The former select an area of the 51 video picture to capture, the latter how images are stored in memory, 52 &ie; in RGB or YUV format, the number of bits per pixel or width and 53 height. Together they also define how images are scaled in the 54 process.</para> 55 56 <para>As usual these parameters are <emphasis>not</emphasis> reset 57 at &func-open; time to permit Unix tool chains, programming a device 58 and then reading from it as if it was a plain file. Well written V4L2 59 applications ensure they really get what they want, including cropping 60 and scaling.</para> 61 62 <para>Cropping initialization at minimum requires to reset the 63 parameters to defaults. An example is given in <xref 64 linkend="crop" />.</para> 65 66 <para>To query the current image format applications set the 67 <structfield>type</structfield> field of a &v4l2-format; to 68 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or 69 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and call the 70 &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill 71 the &v4l2-pix-format; <structfield>pix</structfield> or the 72 &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the 73 <structfield>fmt</structfield> union.</para> 74 75 <para>To request different parameters applications set the 76 <structfield>type</structfield> field of a &v4l2-format; as above and 77 initialize all fields of the &v4l2-pix-format; 78 <structfield>vbi</structfield> member of the 79 <structfield>fmt</structfield> union, or better just modify the 80 results of <constant>VIDIOC_G_FMT</constant>, and call the 81 &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may 82 adjust the parameters and finally return the actual parameters as 83 <constant>VIDIOC_G_FMT</constant> does.</para> 84 85 <para>Like <constant>VIDIOC_S_FMT</constant> the 86 &VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations 87 without disabling I/O or possibly time consuming hardware 88 preparations.</para> 89 90 <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane; 91 are discussed in <xref linkend="pixfmt" />. See also the specification of the 92 <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> 93 and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video 94 capture devices must implement both the 95 <constant>VIDIOC_G_FMT</constant> and 96 <constant>VIDIOC_S_FMT</constant> ioctl, even if 97 <constant>VIDIOC_S_FMT</constant> ignores all requests and always 98 returns default parameters as <constant>VIDIOC_G_FMT</constant> does. 99 <constant>VIDIOC_TRY_FMT</constant> is optional.</para> 100 </section> 101 102 <section> 103 <title>Reading Images</title> 104 105 <para>A video capture device may support the <link 106 linkend="rw">read() function</link> and/or streaming (<link 107 linkend="mmap">memory mapping</link> or <link 108 linkend="userp">user pointer</link>) I/O. See <xref 109 linkend="io" /> for details.</para> 110 </section>
