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