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