Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml

   1 <refentry id="vidioc-g-fbuf">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_G_FBUF</refname>
   9     <refname>VIDIOC_S_FBUF</refname>
  10     <refpurpose>Get or set frame buffer overlay parameters</refpurpose>
  11   </refnamediv>
  12
  13   <refsynopsisdiv>
  14     <funcsynopsis>
  15       <funcprototype>
  16         <funcdef>int <function>ioctl</function></funcdef>
  17         <paramdef>int <parameter>fd</parameter></paramdef>
  18         <paramdef>int <parameter>request</parameter></paramdef>
  19         <paramdef>struct v4l2_framebuffer *<parameter>argp</parameter></paramdef>
  20       </funcprototype>
  21     </funcsynopsis>
  22     <funcsynopsis>
  23       <funcprototype>
  24         <funcdef>int <function>ioctl</function></funcdef>
  25         <paramdef>int <parameter>fd</parameter></paramdef>
  26         <paramdef>int <parameter>request</parameter></paramdef>
  27         <paramdef>const struct v4l2_framebuffer *<parameter>argp</parameter></paramdef>
  28       </funcprototype>
  29     </funcsynopsis>
  30   </refsynopsisdiv>
  31
  32   <refsect1>
  33     <title>Arguments</title>
  34
  35     <variablelist>
  36       <varlistentry>
  37         <term><parameter>fd</parameter></term>
  38         <listitem>
  39           <para>&fd;</para>
  40         </listitem>
  41       </varlistentry>
  42       <varlistentry>
  43         <term><parameter>request</parameter></term>
  44         <listitem>
  45           <para>VIDIOC_G_FBUF, VIDIOC_S_FBUF</para>
  46         </listitem>
  47       </varlistentry>
  48       <varlistentry>
  49         <term><parameter>argp</parameter></term>
  50         <listitem>
  51           <para></para>
  52         </listitem>
  53       </varlistentry>
  54     </variablelist>
  55   </refsect1>
  56
  57   <refsect1>
  58     <title>Description</title>
  59
  60     <para>Applications can use the <constant>VIDIOC_G_FBUF</constant> and
  61 <constant>VIDIOC_S_FBUF</constant> ioctl to get and set the
  62 framebuffer parameters for a <link linkend="overlay">Video
  63 Overlay</link> or <link linkend="osd">Video Output Overlay</link>
  64 (OSD). The type of overlay is implied by the device type (capture or
  65 output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl.
  66 One <filename>/dev/videoN</filename> device must not support both
  67 kinds of overlay.</para>
  68
  69     <para>The V4L2 API distinguishes destructive and non-destructive
  70 overlays. A destructive overlay copies captured video images into the
  71 video memory of a graphics card. A non-destructive overlay blends
  72 video images into a VGA signal or graphics into a video signal.
  73 <wordasword>Video Output Overlays</wordasword> are always
  74 non-destructive.</para>
  75
  76     <para>To get the current parameters applications call the
  77 <constant>VIDIOC_G_FBUF</constant> ioctl with a pointer to a
  78 <structname>v4l2_framebuffer</structname> structure. The driver fills
  79 all fields of the structure or returns an &EINVAL; when overlays are
  80 not supported.</para>
  81
  82     <para>To set the parameters for a <wordasword>Video Output
  83 Overlay</wordasword>, applications must initialize the
  84 <structfield>flags</structfield> field of a struct
  85 <structname>v4l2_framebuffer</structname>. Since the framebuffer is
  86 implemented on the TV card all other parameters are determined by the
  87 driver. When an application calls <constant>VIDIOC_S_FBUF</constant>
  88 with a pointer to this structure, the driver prepares for the overlay
  89 and returns the framebuffer parameters as
  90 <constant>VIDIOC_G_FBUF</constant> does, or it returns an error
  91 code.</para>
  92
  93     <para>To set the parameters for a <wordasword>non-destructive
  94 Video Overlay</wordasword>, applications must initialize the
  95 <structfield>flags</structfield> field, the
  96 <structfield>fmt</structfield> substructure, and call
  97 <constant>VIDIOC_S_FBUF</constant>. Again the driver prepares for the
  98 overlay and returns the framebuffer parameters as
  99 <constant>VIDIOC_G_FBUF</constant> does, or it returns an error
 100 code.</para>
 101
 102     <para>For a <wordasword>destructive Video Overlay</wordasword>
 103 applications must additionally provide a
 104 <structfield>base</structfield> address. Setting up a DMA to a
 105 random memory location can jeopardize the system security, its
 106 stability or even damage the hardware, therefore only the superuser
 107 can set the parameters for a destructive video overlay.</para>
 108
 109     <!-- NB v4l2_pix_format is also specified in pixfmt.sgml.-->
 110
 111     <table pgwide="1" frame="none" id="v4l2-framebuffer">
 112       <title>struct <structname>v4l2_framebuffer</structname></title>
 113       <tgroup cols="4">
 114         &cs-ustr;
 115         <tbody valign="top">
 116           <row>
 117             <entry>__u32</entry>
 118             <entry><structfield>capability</structfield></entry>
 119             <entry></entry>
 120             <entry>Overlay capability flags set by the driver, see
 121 <xref linkend="framebuffer-cap" />.</entry>
 122           </row>
 123           <row>
 124             <entry>__u32</entry>
 125             <entry><structfield>flags</structfield></entry>
 126             <entry></entry>
 127             <entry>Overlay control flags set by application and
 128 driver, see <xref linkend="framebuffer-flags" /></entry>
 129           </row>
 130           <row>
 131             <entry>void *</entry>
 132             <entry><structfield>base</structfield></entry>
 133             <entry></entry>
 134             <entry>Physical base address of the framebuffer,
 135 that is the address of the pixel in the top left corner of the
 136 framebuffer.<footnote><para>A physical base address may not suit all
 137 platforms. GK notes in theory we should pass something like PCI device
 138 + memory region + offset instead. If you encounter problems please
 139 discuss on the linux-media mailing list: &v4l-ml;.</para></footnote></entry>
 140           </row>
 141           <row>
 142             <entry></entry>
 143             <entry></entry>
 144             <entry></entry>
 145             <entry>This field is irrelevant to
 146 <wordasword>non-destructive Video Overlays</wordasword>. For
 147 <wordasword>destructive Video Overlays</wordasword> applications must
 148 provide a base address. The driver may accept only base addresses
 149 which are a multiple of two, four or eight bytes. For
 150 <wordasword>Video Output Overlays</wordasword> the driver must return
 151 a valid base address, so applications can find the corresponding Linux
 152 framebuffer device (see <xref linkend="osd" />).</entry>
 153           </row>
 154           <row>
 155             <entry>&v4l2-pix-format;</entry>
 156             <entry><structfield>fmt</structfield></entry>
 157             <entry></entry>
 158             <entry>Layout of the frame buffer. The
 159 <structname>v4l2_pix_format</structname> structure is defined in <xref
 160 linkend="pixfmt" />, for clarification the fields and acceptable values
 161             are listed below:</entry>
 162           </row>
 163           <row>
 164             <entry></entry>
 165             <entry>__u32</entry>
 166             <entry><structfield>width</structfield></entry>
 167             <entry>Width of the frame buffer in pixels.</entry>
 168           </row>
 169           <row>
 170             <entry></entry>
 171             <entry>__u32</entry>
 172             <entry><structfield>height</structfield></entry>
 173             <entry>Height of the frame buffer in pixels.</entry>
 174           </row>
 175           <row>
 176             <entry></entry>
 177             <entry>__u32</entry>
 178             <entry><structfield>pixelformat</structfield></entry>
 179             <entry>The pixel format of the
 180 framebuffer.</entry>
 181           </row>
 182           <row>
 183             <entry></entry>
 184             <entry></entry>
 185             <entry></entry>
 186             <entry>For <wordasword>non-destructive Video
 187 Overlays</wordasword> this field only defines a format for the
 188 &v4l2-window; <structfield>chromakey</structfield> field.</entry>
 189           </row>
 190           <row>
 191             <entry></entry>
 192             <entry></entry>
 193             <entry></entry>
 194             <entry>For <wordasword>destructive Video
 195 Overlays</wordasword> applications must initialize this field. For
 196 <wordasword>Video Output Overlays</wordasword> the driver must return
 197 a valid format.</entry>
 198           </row>
 199           <row>
 200             <entry></entry>
 201             <entry></entry>
 202             <entry></entry>
 203             <entry>Usually this is an RGB format (for example
 204 <link linkend="V4L2-PIX-FMT-RGB565"><constant>V4L2_PIX_FMT_RGB565</constant></link>)
 205 but YUV formats (only packed YUV formats when chroma keying is used,
 206 not including <constant>V4L2_PIX_FMT_YUYV</constant> and
 207 <constant>V4L2_PIX_FMT_UYVY</constant>) and the
 208 <constant>V4L2_PIX_FMT_PAL8</constant> format are also permitted. The
 209 behavior of the driver when an application requests a compressed
 210 format is undefined. See <xref linkend="pixfmt" /> for information on
 211 pixel formats.</entry>
 212           </row>
 213           <row>
 214             <entry></entry>
 215             <entry>&v4l2-field;</entry>
 216             <entry><structfield>field</structfield></entry>
 217             <entry>Drivers and applications shall ignore this field.
 218 If applicable, the field order is selected with the &VIDIOC-S-FMT;
 219 ioctl, using the <structfield>field</structfield> field of
 220 &v4l2-window;.</entry>
 221           </row>
 222           <row>
 223             <entry></entry>
 224             <entry>__u32</entry>
 225             <entry><structfield>bytesperline</structfield></entry>
 226             <entry>Distance in bytes between the leftmost pixels in
 227 two adjacent lines.</entry>
 228           </row>
 229           <row>
 230             <entry spanname="hspan"><para>This field is irrelevant to
 231 <wordasword>non-destructive Video
 232 Overlays</wordasword>.</para><para>For <wordasword>destructive Video
 233 Overlays</wordasword> both applications and drivers can set this field
 234 to request padding bytes at the end of each line. Drivers however may
 235 ignore the requested value, returning <structfield>width</structfield>
 236 times bytes-per-pixel or a larger value required by the hardware. That
 237 implies applications can just set this field to zero to get a
 238 reasonable default.</para><para>For <wordasword>Video Output
 239 Overlays</wordasword> the driver must return a valid
 240 value.</para><para>Video hardware may access padding bytes, therefore
 241 they must reside in accessible memory. Consider for example the case
 242 where padding bytes after the last line of an image cross a system
 243 page boundary. Capture devices may write padding bytes, the value is
 244 undefined. Output devices ignore the contents of padding
 245 bytes.</para><para>When the image format is planar the
 246 <structfield>bytesperline</structfield> value applies to the largest
 247 plane and is divided by the same factor as the
 248 <structfield>width</structfield> field for any smaller planes. For
 249 example the Cb and Cr planes of a YUV 4:2:0 image have half as many
 250 padding bytes following each line as the Y plane. To avoid ambiguities
 251 drivers must return a <structfield>bytesperline</structfield> value
 252 rounded up to a multiple of the scale factor.</para></entry>
 253           </row>
 254           <row>
 255             <entry></entry>
 256             <entry>__u32</entry>
 257             <entry><structfield>sizeimage</structfield></entry>
 258             <entry><para>This field is irrelevant to
 259 <wordasword>non-destructive Video Overlays</wordasword>. For
 260 <wordasword>destructive Video Overlays</wordasword> applications must
 261 initialize this field. For <wordasword>Video Output
 262 Overlays</wordasword> the driver must return a valid
 263 format.</para><para>Together with <structfield>base</structfield> it
 264 defines the framebuffer memory accessible by the
 265 driver.</para></entry>
 266           </row>
 267           <row>
 268             <entry></entry>
 269             <entry>&v4l2-colorspace;</entry>
 270             <entry><structfield>colorspace</structfield></entry>
 271             <entry>This information supplements the
 272 <structfield>pixelformat</structfield> and must be set by the driver,
 273 see <xref linkend="colorspaces" />.</entry>
 274           </row>
 275           <row>
 276             <entry></entry>
 277             <entry>__u32</entry>
 278             <entry><structfield>priv</structfield></entry>
 279             <entry>Reserved for additional information about custom
 280 (driver defined) formats. When not used drivers and applications must
 281 set this field to zero.</entry>
 282           </row>
 283         </tbody>
 284       </tgroup>
 285     </table>
 286
 287     <table pgwide="1" frame="none" id="framebuffer-cap">
 288       <title>Frame Buffer Capability Flags</title>
 289       <tgroup cols="3">
 290         &cs-def;
 291         <tbody valign="top">
 292           <row>
 293             <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant></entry>
 294             <entry>0x0001</entry>
 295             <entry>The device is capable of non-destructive overlays.
 296 When the driver clears this flag, only destructive overlays are
 297 supported. There are no drivers yet which support both destructive and
 298 non-destructive overlays.</entry>
 299           </row>
 300           <row>
 301             <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
 302             <entry>0x0002</entry>
 303             <entry>The device supports clipping by chroma-keying the
 304 images. That is, image pixels replace pixels in the VGA or video
 305 signal only where the latter assume a certain color. Chroma-keying
 306 makes no sense for destructive overlays.</entry>
 307           </row>
 308           <row>
 309             <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant></entry>
 310             <entry>0x0004</entry>
 311             <entry>The device supports clipping using a list of clip
 312 rectangles.</entry>
 313           </row>
 314           <row>
 315             <entry><constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant></entry>
 316             <entry>0x0008</entry>
 317             <entry>The device supports clipping using a bit mask.</entry>
 318           </row>
 319           <row>
 320             <entry><constant>V4L2_FBUF_CAP_LOCAL_ALPHA</constant></entry>
 321             <entry>0x0010</entry>
 322             <entry>The device supports clipping/blending using the
 323 alpha channel of the framebuffer or VGA signal. Alpha blending makes
 324 no sense for destructive overlays.</entry>
 325           </row>
 326           <row>
 327             <entry><constant>V4L2_FBUF_CAP_GLOBAL_ALPHA</constant></entry>
 328             <entry>0x0020</entry>
 329             <entry>The device supports alpha blending using a global
 330 alpha value. Alpha blending makes no sense for destructive overlays.</entry>
 331           </row>
 332           <row>
 333             <entry><constant>V4L2_FBUF_CAP_LOCAL_INV_ALPHA</constant></entry>
 334             <entry>0x0040</entry>
 335             <entry>The device supports clipping/blending using the
 336 inverted alpha channel of the framebuffer or VGA signal. Alpha
 337 blending makes no sense for destructive overlays.</entry>
 338           </row>
 339           <row>
 340             <entry><constant>V4L2_FBUF_CAP_SRC_CHROMAKEY</constant></entry>
 341             <entry>0x0080</entry>
 342             <entry>The device supports Source Chroma-keying. Framebuffer pixels
 343 with the chroma-key colors are replaced by video pixels, which is exactly opposite of
 344 <constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
 345           </row>
 346         </tbody>
 347       </tgroup>
 348     </table>
 349
 350     <table pgwide="1" frame="none" id="framebuffer-flags">
 351       <title>Frame Buffer Flags</title>
 352       <tgroup cols="3">
 353         &cs-def;
 354         <tbody valign="top">
 355           <row>
 356             <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry>
 357             <entry>0x0001</entry>
 358             <entry>The framebuffer is the primary graphics surface.
 359 In other words, the overlay is destructive. [?]</entry>
 360           </row>
 361           <row>
 362             <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry>
 363             <entry>0x0002</entry>
 364             <entry>The frame buffer is an overlay surface the same
 365 size as the capture. [?]</entry>
 366           </row>
 367           <row>
 368             <entry spanname="hspan">The purpose of
 369 <constant>V4L2_FBUF_FLAG_PRIMARY</constant> and
 370 <constant>V4L2_FBUF_FLAG_OVERLAY</constant> was never quite clear.
 371 Most drivers seem to ignore these flags. For compatibility with the
 372 <wordasword>bttv</wordasword> driver applications should set the
 373 <constant>V4L2_FBUF_FLAG_OVERLAY</constant> flag.</entry>
 374           </row>
 375           <row>
 376             <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry>
 377             <entry>0x0004</entry>
 378             <entry>Use chroma-keying. The chroma-key color is
 379 determined by the <structfield>chromakey</structfield> field of
 380 &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
 381                 linkend="overlay" />
 382 and
 383             <xref linkend="osd" />.</entry>
 384           </row>
 385           <row>
 386             <entry spanname="hspan">There are no flags to enable
 387 clipping using a list of clip rectangles or a bitmap. These methods
 388 are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
 389                 linkend="overlay" /> and <xref linkend="osd" />.</entry>
 390           </row>
 391           <row>
 392             <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry>
 393             <entry>0x0008</entry>
 394             <entry>Use the alpha channel of the framebuffer to clip or
 395 blend framebuffer pixels with video images. The blend
 396 function is: output = framebuffer pixel * alpha + video pixel * (1 -
 397 alpha). The actual alpha depth depends on the framebuffer pixel
 398 format.</entry>
 399           </row>
 400           <row>
 401             <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry>
 402             <entry>0x0010</entry>
 403             <entry>Use a global alpha value to blend the framebuffer
 404 with video images. The blend function is: output = (framebuffer pixel
 405 * alpha + video pixel * (255 - alpha)) / 255. The alpha value is
 406 determined by the <structfield>global_alpha</structfield> field of
 407 &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
 408                 linkend="overlay" />
 409 and <xref linkend="osd" />.</entry>
 410           </row>
 411           <row>
 412             <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry>
 413             <entry>0x0020</entry>
 414             <entry>Like
 415 <constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, use the alpha channel
 416 of the framebuffer to clip or blend framebuffer pixels with video
 417 images, but with an inverted alpha value. The blend function is:
 418 output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The
 419 actual alpha depth depends on the framebuffer pixel format.</entry>
 420           </row>
 421           <row>
 422             <entry><constant>V4L2_FBUF_FLAG_SRC_CHROMAKEY</constant></entry>
 423             <entry>0x0040</entry>
 424             <entry>Use source chroma-keying. The source chroma-key color is
 425 determined by the <structfield>chromakey</structfield> field of
 426 &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
 427 linkend="overlay" /> and <xref linkend="osd" />.
 428 Both chroma-keying are mutual exclusive to each other, so same
 429 <structfield>chromakey</structfield> field of &v4l2-window; is being used.</entry>
 430           </row>
 431         </tbody>
 432       </tgroup>
 433     </table>
 434   </refsect1>
 435
 436   <refsect1>
 437     &return-value;
 438
 439     <variablelist>
 440       <varlistentry>
 441         <term><errorcode>EPERM</errorcode></term>
 442         <listitem>
 443           <para><constant>VIDIOC_S_FBUF</constant> can only be called
 444 by a privileged user to negotiate the parameters for a destructive
 445 overlay.</para>
 446         </listitem>
 447       </varlistentry>
 448       <varlistentry>
 449         <term><errorcode>EINVAL</errorcode></term>
 450         <listitem>
 451           <para>The <constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para>
 452         </listitem>
 453       </varlistentry>
 454     </variablelist>
 455   </refsect1>
 456 </refentry>