linux-pinenote/Documentation/DocBook/media/v4l/dev-output.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>