forked from Minki/linux
2ddb77bb11
The documentation says that the bytesperline field in v4l2_pix_format refers to the largest plane in the case of planar formats (i.e. multiple planes stores in a single buffer). For almost all planar formats the first plane is also the largest (or equal) plane, except for two formats: V4L2_PIX_FMT_NV24/NV42. For this YUV 4:4:4 format the second chroma plane is twice the size of the first luma plane. Looking at the very few drivers that support this format the bytesperline value that they report is actually that of the first plane and not that of the largest plane. Rather than fixing the drivers it makes more sense to update the documentation since it is very difficult to use the largest plane for this. You would have to check what the format is in order to know to which plane bytesperline belongs, which makes calculations much more difficult. This patch updates the documentation accordingly. Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
460 lines
18 KiB
XML
460 lines
18 KiB
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>struct</entry>
|
|
<entry><structfield>fmt</structfield></entry>
|
|
<entry></entry>
|
|
<entry>Layout of the frame buffer.</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 first
|
|
plane and is divided by the same factor as the
|
|
<structfield>width</structfield> field for the other 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. 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>
|