docbook: fix 8250 naming in device-drivers

[linux-2.6-block.git] / Documentation / DocBook / media / v4l / vidioc-g-fbuf.xml

<refentry id="vidioc-g-fbuf">
  <refmeta>
    <refentrytitle>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</refentrytitle>
    &manvol;
  </refmeta>

  <refnamediv>
    <refname>VIDIOC_G_FBUF</refname>
    <refname>VIDIOC_S_FBUF</refname>
    <refpurpose>Get or set frame buffer overlay parameters</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>struct v4l2_framebuffer *<parameter>argp</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>const struct v4l2_framebuffer *<parameter>argp</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Arguments</title>

    <variablelist>
      <varlistentry>
	<term><parameter>fd</parameter></term>
	<listitem>
	  <para>&fd;</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>request</parameter></term>
	<listitem>
	  <para>VIDIOC_G_FBUF, VIDIOC_S_FBUF</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>argp</parameter></term>
	<listitem>
	  <para></para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>Applications can use the <constant>VIDIOC_G_FBUF</constant> and
<constant>VIDIOC_S_FBUF</constant> ioctl to get and set the
framebuffer parameters for a <link linkend="overlay">Video
Overlay</link> or <link linkend="osd">Video Output Overlay</link>
(OSD). The type of overlay is implied by the device type (capture or
output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl.
One <filename>/dev/videoN</filename> device must not support both
kinds of overlay.</para>

    <para>The V4L2 API distinguishes destructive and non-destructive
overlays. A destructive overlay copies captured video images into the
video memory of a graphics card. A non-destructive overlay blends
video images into a VGA signal or graphics into a video signal.
<wordasword>Video Output Overlays</wordasword> are always
non-destructive.</para>

    <para>To get the current parameters applications call the
<constant>VIDIOC_G_FBUF</constant> ioctl with a pointer to a
<structname>v4l2_framebuffer</structname> structure. The driver fills
all fields of the structure or returns an &EINVAL; when overlays are
not supported.</para>

    <para>To set the parameters for a <wordasword>Video Output
Overlay</wordasword>, applications must initialize the
<structfield>flags</structfield> field of a struct
<structname>v4l2_framebuffer</structname>. Since the framebuffer is
implemented on the TV card all other parameters are determined by the
driver. When an application calls <constant>VIDIOC_S_FBUF</constant>
with a pointer to this structure, the driver prepares for the overlay
and returns the framebuffer parameters as
<constant>VIDIOC_G_FBUF</constant> does, or it returns an error
code.</para>

    <para>To set the parameters for a <wordasword>non-destructive
Video Overlay</wordasword>, applications must initialize the
<structfield>flags</structfield> field, the
<structfield>fmt</structfield> substructure, and call
<constant>VIDIOC_S_FBUF</constant>. Again the driver prepares for the
overlay and returns the framebuffer parameters as
<constant>VIDIOC_G_FBUF</constant> does, or it returns an error
code.</para>

    <para>For a <wordasword>destructive Video Overlay</wordasword>
applications must additionally provide a
<structfield>base</structfield> address. Setting up a DMA to a
random memory location can jeopardize the system security, its
stability or even damage the hardware, therefore only the superuser
can set the parameters for a destructive video overlay.</para>

    <!-- NB v4l2_pix_format is also specified in pixfmt.sgml.-->

    <table pgwide="1" frame="none" id="v4l2-framebuffer">
      <title>struct <structname>v4l2_framebuffer</structname></title>
      <tgroup cols="4">
	&cs-ustr;
	<tbody valign="top">
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>capability</structfield></entry>
	    <entry></entry>
	    <entry>Overlay capability flags set by the driver, see
<xref linkend="framebuffer-cap" />.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>flags</structfield></entry>
	    <entry></entry>
	    <entry>Overlay control flags set by application and
driver, see <xref linkend="framebuffer-flags" /></entry>
	  </row>
	  <row>
	    <entry>void *</entry>
	    <entry><structfield>base</structfield></entry>
	    <entry></entry>
	    <entry>Physical base address of the framebuffer,
that is the address of the pixel in the top left corner of the
framebuffer.<footnote><para>A physical base address may not suit all
platforms. GK notes in theory we should pass something like PCI device
+ memory region + offset instead. If you encounter problems please
discuss on the linux-media mailing list: &v4l-ml;.</para></footnote></entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>This field is irrelevant to
<wordasword>non-destructive Video Overlays</wordasword>. For
<wordasword>destructive Video Overlays</wordasword> applications must
provide a base address. The driver may accept only base addresses
which are a multiple of two, four or eight bytes. For
<wordasword>Video Output Overlays</wordasword> the driver must return
a valid base address, so applications can find the corresponding Linux
framebuffer device (see <xref linkend="osd" />).</entry>
	  </row>
	  <row>
	    <entry>&v4l2-pix-format;</entry>
	    <entry><structfield>fmt</structfield></entry>
	    <entry></entry>
	    <entry>Layout of the frame buffer. The
<structname>v4l2_pix_format</structname> structure is defined in <xref
linkend="pixfmt" />, for clarification the fields and acceptable values
	    are listed below:</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>width</structfield></entry>
	    <entry>Width of the frame buffer in pixels.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>height</structfield></entry>
	    <entry>Height of the frame buffer in pixels.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>pixelformat</structfield></entry>
	    <entry>The pixel format of the
framebuffer.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>For <wordasword>non-destructive Video
Overlays</wordasword> this field only defines a format for the
&v4l2-window; <structfield>chromakey</structfield> field.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>For <wordasword>destructive Video
Overlays</wordasword> applications must initialize this field. For
<wordasword>Video Output Overlays</wordasword> the driver must return
a valid format.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>Usually this is an RGB format (for example
<link linkend="V4L2-PIX-FMT-RGB565"><constant>V4L2_PIX_FMT_RGB565</constant></link>)
but YUV formats (only packed YUV formats when chroma keying is used,
not including <constant>V4L2_PIX_FMT_YUYV</constant> and
<constant>V4L2_PIX_FMT_UYVY</constant>) and the
<constant>V4L2_PIX_FMT_PAL8</constant> format are also permitted. The
behavior of the driver when an application requests a compressed
format is undefined. See <xref linkend="pixfmt" /> for information on
pixel formats.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>&v4l2-field;</entry>
	    <entry><structfield>field</structfield></entry>
	    <entry>Drivers and applications shall ignore this field.
If applicable, the field order is selected with the &VIDIOC-S-FMT;
ioctl, using the <structfield>field</structfield> field of
&v4l2-window;.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>bytesperline</structfield></entry>
	    <entry>Distance in bytes between the leftmost pixels in
two adjacent lines.</entry>
	  </row>
	  <row>
	    <entry spanname="hspan"><para>This field is irrelevant to
<wordasword>non-destructive Video
Overlays</wordasword>.</para><para>For <wordasword>destructive Video
Overlays</wordasword> both applications and drivers can set this field
to request padding bytes at the end of each line. Drivers however may
ignore the requested value, returning <structfield>width</structfield>
times bytes-per-pixel or a larger value required by the hardware. That
implies applications can just set this field to zero to get a
reasonable default.</para><para>For <wordasword>Video Output
Overlays</wordasword> the driver must return a valid
value.</para><para>Video hardware may access padding bytes, therefore
they must reside in accessible memory. Consider for example the case
where padding bytes after the last line of an image cross a system
page boundary. Capture devices may write padding bytes, the value is
undefined. Output devices ignore the contents of padding
bytes.</para><para>When the image format is planar the
<structfield>bytesperline</structfield> value applies to the largest
plane and is divided by the same factor as the
<structfield>width</structfield> field for any smaller planes. For
example the Cb and Cr planes of a YUV 4:2:0 image have half as many
padding bytes following each line as the Y plane. To avoid ambiguities
drivers must return a <structfield>bytesperline</structfield> value
rounded up to a multiple of the scale factor.</para></entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>sizeimage</structfield></entry>
	    <entry><para>This field is irrelevant to
<wordasword>non-destructive Video Overlays</wordasword>. For
<wordasword>destructive Video Overlays</wordasword> applications must
initialize this field. For <wordasword>Video Output
Overlays</wordasword> the driver must return a valid
format.</para><para>Together with <structfield>base</structfield> it
defines the framebuffer memory accessible by the
driver.</para></entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>&v4l2-colorspace;</entry>
	    <entry><structfield>colorspace</structfield></entry>
	    <entry>This information supplements the
<structfield>pixelformat</structfield> and must be set by the driver,
see <xref linkend="colorspaces" />.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>priv</structfield></entry>
	    <entry>Reserved for additional information about custom
(driver defined) formats. When not used drivers and applications must
set this field to zero.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table pgwide="1" frame="none" id="framebuffer-cap">
      <title>Frame Buffer Capability Flags</title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant></entry>
	    <entry>0x0001</entry>
	    <entry>The device is capable of non-destructive overlays.
When the driver clears this flag, only destructive overlays are
supported. There are no drivers yet which support both destructive and
non-destructive overlays. Video Output Overlays are in practice always
non-destructive.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
	    <entry>0x0002</entry>
	    <entry>The device supports clipping by chroma-keying the
images. That is, image pixels replace pixels in the VGA or video
signal only where the latter assume a certain color. Chroma-keying
makes no sense for destructive overlays.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant></entry>
	    <entry>0x0004</entry>
	    <entry>The device supports clipping using a list of clip
rectangles.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant></entry>
	    <entry>0x0008</entry>
	    <entry>The device supports clipping using a bit mask.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_LOCAL_ALPHA</constant></entry>
	    <entry>0x0010</entry>
	    <entry>The device supports clipping/blending using the
alpha channel of the framebuffer or VGA signal. Alpha blending makes
no sense for destructive overlays.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_GLOBAL_ALPHA</constant></entry>
	    <entry>0x0020</entry>
	    <entry>The device supports alpha blending using a global
alpha value. Alpha blending makes no sense for destructive overlays.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_LOCAL_INV_ALPHA</constant></entry>
	    <entry>0x0040</entry>
	    <entry>The device supports clipping/blending using the
inverted alpha channel of the framebuffer or VGA signal. Alpha
blending makes no sense for destructive overlays.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_CAP_SRC_CHROMAKEY</constant></entry>
	    <entry>0x0080</entry>
	    <entry>The device supports Source Chroma-keying. Video pixels
with the chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of
<constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table pgwide="1" frame="none" id="framebuffer-flags">
      <title>Frame Buffer Flags</title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry>
	    <entry>0x0001</entry>
	    <entry>The framebuffer is the primary graphics surface.
In other words, the overlay is destructive. This flag is typically set by any
driver that doesn't have the <constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant>
capability and it is cleared otherwise.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry>
	    <entry>0x0002</entry>
	    <entry>If this flag is set for a video capture device, then the
driver will set the initial overlay size to cover the full framebuffer size,
otherwise the existing overlay size (as set by &VIDIOC-S-FMT;) will be used.

Only one video capture driver (bttv) supports this flag. The use of this flag
for capture devices is deprecated. There is no way to detect which drivers
support this flag, so the only reliable method of setting the overlay size is
through &VIDIOC-S-FMT;.

If this flag is set for a video output device, then the video output overlay
window is relative to the top-left corner of the framebuffer and restricted
to the size of the framebuffer. If it is cleared, then the video output
overlay window is relative to the video output display.
            </entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry>
	    <entry>0x0004</entry>
	    <entry>Use chroma-keying. The chroma-key color is
determined by the <structfield>chromakey</structfield> field of
&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
		linkend="overlay" />
and
	    <xref linkend="osd" />.</entry>
	  </row>
	  <row>
	    <entry spanname="hspan">There are no flags to enable
clipping using a list of clip rectangles or a bitmap. These methods
are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
		linkend="overlay" /> and <xref linkend="osd" />.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry>
	    <entry>0x0008</entry>
	    <entry>Use the alpha channel of the framebuffer to clip or
blend framebuffer pixels with video images. The blend
function is: output = framebuffer pixel * alpha + video pixel * (1 -
alpha). The actual alpha depth depends on the framebuffer pixel
format.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry>
	    <entry>0x0010</entry>
	    <entry>Use a global alpha value to blend the framebuffer
with video images. The blend function is: output = (framebuffer pixel
* alpha + video pixel * (255 - alpha)) / 255. The alpha value is
determined by the <structfield>global_alpha</structfield> field of
&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
		linkend="overlay" />
and <xref linkend="osd" />.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry>
	    <entry>0x0020</entry>
	    <entry>Like
<constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, use the alpha channel
of the framebuffer to clip or blend framebuffer pixels with video
images, but with an inverted alpha value. The blend function is:
output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The
actual alpha depth depends on the framebuffer pixel format.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_FBUF_FLAG_SRC_CHROMAKEY</constant></entry>
	    <entry>0x0040</entry>
	    <entry>Use source chroma-keying. The source chroma-key color is
determined by the <structfield>chromakey</structfield> field of
&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
linkend="overlay" /> and <xref linkend="osd" />.
Both chroma-keying are mutual exclusive to each other, so same
<structfield>chromakey</structfield> field of &v4l2-window; is being used.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1>
    &return-value;

    <variablelist>
      <varlistentry>
	<term><errorcode>EPERM</errorcode></term>
	<listitem>
	  <para><constant>VIDIOC_S_FBUF</constant> can only be called
by a privileged user to negotiate the parameters for a destructive
overlay.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><errorcode>EINVAL</errorcode></term>
	<listitem>
	  <para>The <constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
</refentry>