53b5d5749b
Add DocBook documentation for the new multi-planar API extensions to the Video for Linux 2 API DocBook. Signed-off-by: Pawel Osciak <pawel@osciak.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
114 lines
4.8 KiB
XML
114 lines
4.8 KiB
XML
<title>Video Output Interface</title>
|
|
|
|
<para>Video output devices encode stills or image sequences as
|
|
analog video signal. With this interface applications can
|
|
control the encoding process and move images from user space to
|
|
the driver.</para>
|
|
|
|
<para>Conventionally V4L2 video output devices are accessed through
|
|
character device special files named <filename>/dev/video</filename>
|
|
and <filename>/dev/video0</filename> to
|
|
<filename>/dev/video63</filename> with major number 81 and minor
|
|
numbers 0 to 63. <filename>/dev/video</filename> is typically a
|
|
symbolic link to the preferred video device. Note the same device
|
|
files are used for video capture devices.</para>
|
|
|
|
<section>
|
|
<title>Querying Capabilities</title>
|
|
|
|
<para>Devices supporting the video output interface set the
|
|
<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or
|
|
<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the
|
|
<structfield>capabilities</structfield> field of &v4l2-capability;
|
|
returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
|
|
they may also support the <link linkend="raw-vbi">raw VBI
|
|
output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At
|
|
least one of the read/write or streaming I/O methods must be
|
|
supported. Modulators and audio outputs are optional.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Supplemental Functions</title>
|
|
|
|
<para>Video output devices shall support <link
|
|
linkend="audio">audio output</link>, <link
|
|
linkend="tuner">modulator</link>, <link linkend="control">controls</link>,
|
|
<link linkend="crop">cropping and scaling</link> and <link
|
|
linkend="streaming-par">streaming parameter</link> ioctls as needed.
|
|
The <link linkend="video">video output</link> and <link
|
|
linkend="standard">video standard</link> ioctls must be supported by
|
|
all video output devices.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Image Format Negotiation</title>
|
|
|
|
<para>The output is determined by cropping and image format
|
|
parameters. The former select an area of the video picture where the
|
|
image will appear, the latter how images are stored in memory, &ie; in
|
|
RGB or YUV format, the number of bits per pixel or width and height.
|
|
Together they also define how images are scaled in the process.</para>
|
|
|
|
<para>As usual these parameters are <emphasis>not</emphasis> reset
|
|
at &func-open; time to permit Unix tool chains, programming a device
|
|
and then writing to it as if it was a plain file. Well written V4L2
|
|
applications ensure they really get what they want, including cropping
|
|
and scaling.</para>
|
|
|
|
<para>Cropping initialization at minimum requires to reset the
|
|
parameters to defaults. An example is given in <xref
|
|
linkend="crop" />.</para>
|
|
|
|
<para>To query the current image format applications set the
|
|
<structfield>type</structfield> field of a &v4l2-format; to
|
|
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
|
|
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the
|
|
&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
|
|
the &v4l2-pix-format; <structfield>pix</structfield> or the
|
|
&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
|
|
<structfield>fmt</structfield> union.</para>
|
|
|
|
<para>To request different parameters applications set the
|
|
<structfield>type</structfield> field of a &v4l2-format; as above and
|
|
initialize all fields of the &v4l2-pix-format;
|
|
<structfield>vbi</structfield> member of the
|
|
<structfield>fmt</structfield> union, or better just modify the
|
|
results of <constant>VIDIOC_G_FMT</constant>, and call the
|
|
&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
|
|
adjust the parameters and finally return the actual parameters as
|
|
<constant>VIDIOC_G_FMT</constant> does.</para>
|
|
|
|
<para>Like <constant>VIDIOC_S_FMT</constant> the
|
|
&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
|
|
without disabling I/O or possibly time consuming hardware
|
|
preparations.</para>
|
|
|
|
<para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
|
|
are discussed in <xref linkend="pixfmt" />. See also the specification of the
|
|
<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
|
|
and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
|
|
output devices must implement both the
|
|
<constant>VIDIOC_G_FMT</constant> and
|
|
<constant>VIDIOC_S_FMT</constant> ioctl, even if
|
|
<constant>VIDIOC_S_FMT</constant> ignores all requests and always
|
|
returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
|
|
<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Writing Images</title>
|
|
|
|
<para>A video output device may support the <link
|
|
linkend="rw">write() function</link> and/or streaming (<link
|
|
linkend="mmap">memory mapping</link> or <link
|
|
linkend="userp">user pointer</link>) I/O. See <xref
|
|
linkend="io" /> for details.</para>
|
|
</section>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-parent-document: "v4l2.sgml"
|
|
indent-tabs-mode: nil
|
|
End:
|
|
-->
|