123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459 |
- <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>
|