1 <title>Video Capture Interface</title> 2 3 <para>Video capture devices sample an analog video signal and store 4the digitized images in memory. Today nearly all devices can capture 5at full 25 or 30 frames/second. With this interface applications can 6control the capture process and move images from the driver into user 7space.</para> 8 9 <para>Conventionally V4L2 video capture devices are accessed through 10character device special files named <filename>/dev/video</filename> 11and <filename>/dev/video0</filename> to 12<filename>/dev/video63</filename> with major number 81 and minor 13numbers 0 to 63. <filename>/dev/video</filename> is typically a 14symbolic link to the preferred video device. Note the same device 15files 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; 24returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions 25they may also support the <link linkend="overlay">video overlay</link> 26(<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link 27linkend="raw-vbi">raw VBI capture</link> 28(<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of 29the read/write or streaming I/O methods must be supported. Tuners and 30audio inputs are optional.</para> 31 </section> 32 33 <section> 34 <title>Supplemental Functions</title> 35 36 <para>Video capture devices shall support <link 37linkend="audio">audio input</link>, <link 38linkend="tuner">tuner</link>, <link linkend="control">controls</link>, 39<link linkend="crop">cropping and scaling</link> and <link 40linkend="streaming-par">streaming parameter</link> ioctls as needed. 41The <link linkend="video">video input</link> and <link 42linkend="standard">video standard</link> ioctls must be supported by 43all 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 50cropping and image format parameters. The former select an area of the 51video 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 53height. Together they also define how images are scaled in the 54process.</para> 55 56 <para>As usual these parameters are <emphasis>not</emphasis> reset 57at &func-open; time to permit Unix tool chains, programming a device 58and then reading from it as if it was a plain file. Well written V4L2 59applications ensure they really get what they want, including cropping 60and scaling.</para> 61 62 <para>Cropping initialization at minimum requires to reset the 63parameters to defaults. An example is given in <xref 64linkend="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 71the &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 77initialize all fields of the &v4l2-pix-format; 78<structfield>vbi</structfield> member of the 79<structfield>fmt</structfield> union, or better just modify the 80results of <constant>VIDIOC_G_FMT</constant>, and call the 81&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may 82adjust 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 87without disabling I/O or possibly time consuming hardware 88preparations.</para> 89 90 <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane; 91are discussed in <xref linkend="pixfmt" />. See also the specification of the 92<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> 93and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video 94capture 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 98returns 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 106linkend="rw">read() function</link> and/or streaming (<link 107linkend="mmap">memory mapping</link> or <link 108linkend="userp">user pointer</link>) I/O. See <xref 109linkend="io" /> for details.</para> 110 </section> 111