About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / dev-capture.xml

Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:44 EST.

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>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.