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

   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>
 107
 108   <!--
 109 Local Variables:
 110 mode: sgml
 111 sgml-parent-document: "v4l2.sgml"
 112 indent-tabs-mode: nil
 113 End:
 114   -->