ARM: 7409/1: Do not call flush_cache_user_range with mmap_sem held
[linux/fpc-iii.git] / Documentation / DocBook / v4l / dev-capture.xml
blob2237c661f26aceb3a65ec5992bc0dc8e542c7752
1   <title>Video Capture Interface</title>
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>
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>
17   <section>
18     <title>Querying Capabilities</title>
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>
33   <section>
34     <title>Supplemental Functions</title>
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>
46   <section>
47     <title>Image Format Negotiation</title>
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>
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>
62     <para>Cropping initialization at minimum requires to reset the
63 parameters to defaults. An example is given in <xref
64 linkend="crop" />.</para>
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>
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>
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>
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>
102   <section>
103     <title>Reading Images</title>
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>
112   <!--
113 Local Variables:
114 mode: sgml
115 sgml-parent-document: "v4l2.sgml"
116 indent-tabs-mode: nil
117 End:
118   -->