Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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 | --> |