Documentation/DocBook/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> flag in the
  21 <structfield>capabilities</structfield> field of &v4l2-capability;
  22 returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
  23 they may also support the <link linkend="raw-vbi">raw VBI
  24 output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At
  25 least one of the read/write or streaming I/O methods must be
  26 supported. 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
  33 linkend="audio">audio output</link>, <link
  34 linkend="tuner">modulator</link>, <link linkend="control">controls</link>,
  35 <link linkend="crop">cropping and scaling</link> and <link
  36 linkend="streaming-par">streaming parameter</link> ioctls as needed.
  37 The <link linkend="video">video output</link> and <link
  38 linkend="standard">video standard</link> ioctls must be supported by
  39 all 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
  46 parameters. The former select an area of the video picture where the
  47 image will appear, the latter how images are stored in memory, &ie; in
  48 RGB or YUV format, the number of bits per pixel or width and height.
  49 Together they also define how images are scaled in the process.</para>
  50
  51     <para>As usual these parameters are <emphasis>not</emphasis> reset
  52 at &func-open; time to permit Unix tool chains, programming a device
  53 and then writing to it as if it was a plain file. Well written V4L2
  54 applications ensure they really get what they want, including cropping
  55 and scaling.</para>
  56
  57     <para>Cropping initialization at minimum requires to reset the
  58 parameters to defaults. An example is given in <xref
  59 linkend="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
  65 the &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
  70 initialize all fields of the &v4l2-pix-format;
  71 <structfield>vbi</structfield> member of the
  72 <structfield>fmt</structfield> union, or better just modify the
  73 results of <constant>VIDIOC_G_FMT</constant>, and call the
  74 &VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
  75 adjust 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
  80 without disabling I/O or possibly time consuming hardware
  81 preparations.</para>
  82
  83     <para>The contents of &v4l2-pix-format; are discussed in <xref
  84 linkend="pixfmt" />. See also the specification of the
  85 <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
  86 and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
  87 output 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
  91 returns 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
  99 linkend="rw">write() function</link> and/or streaming (<link
 100 linkend="mmap">memory mapping</link> or <link
 101 linkend="userp">user pointer</link>) I/O. See <xref
 102 linkend="io" /> for details.</para>
 103   </section>
 104
 105   <!--
 106 Local Variables:
 107 mode: sgml
 108 sgml-parent-document: "v4l2.sgml"
 109 indent-tabs-mode: nil
 110 End:
 111   -->