Based on kernel version 4.7.2. Page generated on 2016-08-22 22:44 EST.
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>
