diff options
Diffstat (limited to 'Documentation/DocBook/v4l/dev-capture.xml')
-rw-r--r-- | Documentation/DocBook/v4l/dev-capture.xml | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/dev-capture.xml b/Documentation/DocBook/v4l/dev-capture.xml new file mode 100644 index 000000000000..32807e43f170 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-capture.xml | |||
@@ -0,0 +1,115 @@ | |||
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 | --> | ||