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 --> 112