Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
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> flag in the
22<structfield>capabilities</structfield> field of &v4l2-capability;
23returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
24they may also support the <link linkend="overlay">video overlay</link>
25(<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link
26linkend="raw-vbi">raw VBI capture</link>
27(<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of
28the read/write or streaming I/O methods must be supported. Tuners and
29audio inputs are optional.</para>
30 </section>
31
32 <section>
33 <title>Supplemental Functions</title>
34
35 <para>Video capture devices shall support <link
36linkend="audio">audio input</link>, <link
37linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
38<link linkend="crop">cropping and scaling</link> and <link
39linkend="streaming-par">streaming parameter</link> ioctls as needed.
40The <link linkend="video">video input</link> and <link
41linkend="standard">video standard</link> ioctls must be supported by
42all 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
49cropping and image format parameters. The former select an area of the
50video 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
52height. Together they also define how images are scaled in the
53process.</para>
54
55 <para>As usual these parameters are <emphasis>not</emphasis> reset
56at &func-open; time to permit Unix tool chains, programming a device
57and then reading from it as if it was a plain file. Well written V4L2
58applications ensure they really get what they want, including cropping
59and scaling.</para>
60
61 <para>Cropping initialization at minimum requires to reset the
62parameters to defaults. An example is given in <xref
63linkend="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
69the &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
74initialize all fields of the &v4l2-pix-format;
75<structfield>vbi</structfield> member of the
76<structfield>fmt</structfield> union, or better just modify the
77results of <constant>VIDIOC_G_FMT</constant>, and call the
78&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
79adjust 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
84without disabling I/O or possibly time consuming hardware
85preparations.</para>
86
87 <para>The contents of &v4l2-pix-format; are discussed in <xref
88linkend="pixfmt" />. See also the specification of the
89<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
90and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
91capture 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
95returns 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
103linkend="rw">read() function</link> and/or streaming (<link
104linkend="mmap">memory mapping</link> or <link
105linkend="userp">user pointer</link>) I/O. See <xref
106linkend="io" /> for details.</para>
107 </section>
108
109 <!--
110Local Variables:
111mode: sgml
112sgml-parent-document: "v4l2.sgml"
113indent-tabs-mode: nil
114End:
115 -->