About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:38 EST.

1	  <title>Video Output Interface</title>
2	
3	  <para>Video output devices encode stills or image sequences as
4	analog video signal. With this interface applications can
5	control the encoding process and move images from user space to
6	the driver.</para>
7	
8	  <para>Conventionally V4L2 video output devices are accessed through
9	character device special files named <filename>/dev/video</filename>
10	and <filename>/dev/video0</filename> to
11	<filename>/dev/video63</filename> with major number 81 and minor
12	numbers 0 to 63. <filename>/dev/video</filename> is typically a
13	symbolic link to the preferred video device. Note the same device
14	files are used for video capture devices.</para>
15	
16	  <section>
17	    <title>Querying Capabilities</title>
18	
19	    <para>Devices supporting the video output interface set the
20	<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or
21	<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</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="raw-vbi">raw VBI
25	output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At
26	least one of the read/write or streaming I/O methods must be
27	supported. Modulators and audio outputs are optional.</para>
28	  </section>
29	
30	  <section>
31	    <title>Supplemental Functions</title>
32	
33	    <para>Video output devices shall support <link
34	linkend="audio">audio output</link>, <link
35	linkend="tuner">modulator</link>, <link linkend="control">controls</link>,
36	<link linkend="crop">cropping and scaling</link> and <link
37	linkend="streaming-par">streaming parameter</link> ioctls as needed.
38	The <link linkend="video">video output</link> and <link
39	linkend="standard">video standard</link> ioctls must be supported by
40	all video output devices.</para>
41	  </section>
42	
43	  <section>
44	    <title>Image Format Negotiation</title>
45	
46	    <para>The output is determined by cropping and image format
47	parameters. The former select an area of the video picture where the
48	image will appear, the latter how images are stored in memory, &ie; in
49	RGB or YUV format, the number of bits per pixel or width and height.
50	Together they also define how images are scaled in the process.</para>
51	
52	    <para>As usual these parameters are <emphasis>not</emphasis> reset
53	at &func-open; time to permit Unix tool chains, programming a device
54	and then writing to it as if it was a plain file. Well written V4L2
55	applications ensure they really get what they want, including cropping
56	and scaling.</para>
57	
58	    <para>Cropping initialization at minimum requires to reset the
59	parameters to defaults. An example is given in <xref
60	linkend="crop" />.</para>
61	
62	    <para>To query the current image format applications set the
63	<structfield>type</structfield> field of a &v4l2-format; to
64	<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
65	<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the
66	&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
67	the &v4l2-pix-format; <structfield>pix</structfield> or the
68	&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
69	<structfield>fmt</structfield> union.</para>
70	
71	    <para>To request different parameters applications set the
72	<structfield>type</structfield> field of a &v4l2-format; as above and
73	initialize all fields of the &v4l2-pix-format;
74	<structfield>vbi</structfield> member of the
75	<structfield>fmt</structfield> union, or better just modify the
76	results of <constant>VIDIOC_G_FMT</constant>, and call the
77	&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
78	adjust the parameters and finally return the actual parameters as
79	<constant>VIDIOC_G_FMT</constant> does.</para>
80	
81	    <para>Like <constant>VIDIOC_S_FMT</constant> the
82	&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
83	without disabling I/O or possibly time consuming hardware
84	preparations.</para>
85	
86	    <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
87	are discussed in <xref linkend="pixfmt" />. See also the specification of the
88	<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
89	and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
90	output devices must implement both the
91	<constant>VIDIOC_G_FMT</constant> and
92	<constant>VIDIOC_S_FMT</constant> ioctl, even if
93	<constant>VIDIOC_S_FMT</constant> ignores all requests and always
94	returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
95	<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
96	  </section>
97	
98	  <section>
99	    <title>Writing Images</title>
100	
101	    <para>A video output device may support the <link
102	linkend="rw">write() function</link> and/or streaming (<link
103	linkend="mmap">memory mapping</link> or <link
104	linkend="userp">user pointer</link>) I/O. See <xref
105	linkend="io" /> for details.</para>
106	  </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.