diff options
Diffstat (limited to 'kernel/Documentation/DocBook/media/v4l/dev-output.xml')
-rw-r--r-- | kernel/Documentation/DocBook/media/v4l/dev-output.xml | 106 |
1 files changed, 106 insertions, 0 deletions
diff --git a/kernel/Documentation/DocBook/media/v4l/dev-output.xml b/kernel/Documentation/DocBook/media/v4l/dev-output.xml new file mode 100644 index 000000000..9130a3dc7 --- /dev/null +++ b/kernel/Documentation/DocBook/media/v4l/dev-output.xml @@ -0,0 +1,106 @@ + <title>Video Output Interface</title> + + <para>Video output devices encode stills or image sequences as +analog video signal. With this interface applications can +control the encoding process and move images from user space to +the driver.</para> + + <para>Conventionally V4L2 video output devices are accessed through +character device special files named <filename>/dev/video</filename> +and <filename>/dev/video0</filename> to +<filename>/dev/video63</filename> with major number 81 and minor +numbers 0 to 63. <filename>/dev/video</filename> is typically a +symbolic link to the preferred video device. Note the same device +files are used for video capture devices.</para> + + <section> + <title>Querying Capabilities</title> + + <para>Devices supporting the video output interface set the +<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or +<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the +<structfield>capabilities</structfield> field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions +they may also support the <link linkend="raw-vbi">raw VBI +output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At +least one of the read/write or streaming I/O methods must be +supported. Modulators and audio outputs are optional.</para> + </section> + + <section> + <title>Supplemental Functions</title> + + <para>Video output devices shall support <link +linkend="audio">audio output</link>, <link +linkend="tuner">modulator</link>, <link linkend="control">controls</link>, +<link linkend="crop">cropping and scaling</link> and <link +linkend="streaming-par">streaming parameter</link> ioctls as needed. +The <link linkend="video">video output</link> and <link +linkend="standard">video standard</link> ioctls must be supported by +all video output devices.</para> + </section> + + <section> + <title>Image Format Negotiation</title> + + <para>The output is determined by cropping and image format +parameters. The former select an area of the video picture where the +image will appear, the latter how images are stored in memory, &ie; in +RGB or YUV format, the number of bits per pixel or width and height. +Together they also define how images are scaled in the process.</para> + + <para>As usual these parameters are <emphasis>not</emphasis> reset +at &func-open; time to permit Unix tool chains, programming a device +and then writing to it as if it was a plain file. Well written V4L2 +applications ensure they really get what they want, including cropping +and scaling.</para> + + <para>Cropping initialization at minimum requires to reset the +parameters to defaults. An example is given in <xref +linkend="crop" />.</para> + + <para>To query the current image format applications set the +<structfield>type</structfield> field of a &v4l2-format; to +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the +&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill +the &v4l2-pix-format; <structfield>pix</structfield> or the +&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the +<structfield>fmt</structfield> union.</para> + + <para>To request different parameters applications set the +<structfield>type</structfield> field of a &v4l2-format; as above and +initialize all fields of the &v4l2-pix-format; +<structfield>vbi</structfield> member of the +<structfield>fmt</structfield> union, or better just modify the +results of <constant>VIDIOC_G_FMT</constant>, and call the +&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may +adjust the parameters and finally return the actual parameters as +<constant>VIDIOC_G_FMT</constant> does.</para> + + <para>Like <constant>VIDIOC_S_FMT</constant> the +&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations +without disabling I/O or possibly time consuming hardware +preparations.</para> + + <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane; +are discussed in <xref linkend="pixfmt" />. See also the specification of the +<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> +and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video +output devices must implement both the +<constant>VIDIOC_G_FMT</constant> and +<constant>VIDIOC_S_FMT</constant> ioctl, even if +<constant>VIDIOC_S_FMT</constant> ignores all requests and always +returns default parameters as <constant>VIDIOC_G_FMT</constant> does. +<constant>VIDIOC_TRY_FMT</constant> is optional.</para> + </section> + + <section> + <title>Writing Images</title> + + <para>A video output device may support the <link +linkend="rw">write() function</link> and/or streaming (<link +linkend="mmap">memory mapping</link> or <link +linkend="userp">user pointer</link>) I/O. See <xref +linkend="io" /> for details.</para> + </section> |