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>struct</entry>
 156             <entry><structfield>fmt</structfield></entry>
 157             <entry></entry>
 158             <entry>Layout of the frame buffer.</entry>
 159           </row>
 160           <row>
 161             <entry></entry>
 162             <entry>__u32</entry>
 163             <entry><structfield>width</structfield></entry>
 164             <entry>Width of the frame buffer in pixels.</entry>
 165           </row>
 166           <row>
 167             <entry></entry>
 168             <entry>__u32</entry>
 169             <entry><structfield>height</structfield></entry>
 170             <entry>Height of the frame buffer in pixels.</entry>
 171           </row>
 172           <row>
 173             <entry></entry>
 174             <entry>__u32</entry>
 175             <entry><structfield>pixelformat</structfield></entry>
 176             <entry>The pixel format of the
 177 framebuffer.</entry>
 178           </row>
 179           <row>
 180             <entry></entry>
 181             <entry></entry>
 182             <entry></entry>
 183             <entry>For <wordasword>non-destructive Video
 184 Overlays</wordasword> this field only defines a format for the
 185 &v4l2-window; <structfield>chromakey</structfield> field.</entry>
 186           </row>
 187           <row>
 188             <entry></entry>
 189             <entry></entry>
 190             <entry></entry>
 191             <entry>For <wordasword>destructive Video
 192 Overlays</wordasword> applications must initialize this field. For
 193 <wordasword>Video Output Overlays</wordasword> the driver must return
 194 a valid format.</entry>
 195           </row>
 196           <row>
 197             <entry></entry>
 198             <entry></entry>
 199             <entry></entry>
 200             <entry>Usually this is an RGB format (for example
 201 <link linkend="V4L2-PIX-FMT-RGB565"><constant>V4L2_PIX_FMT_RGB565</constant></link>)
 202 but YUV formats (only packed YUV formats when chroma keying is used,
 203 not including <constant>V4L2_PIX_FMT_YUYV</constant> and
 204 <constant>V4L2_PIX_FMT_UYVY</constant>) and the
 205 <constant>V4L2_PIX_FMT_PAL8</constant> format are also permitted. The
 206 behavior of the driver when an application requests a compressed
 207 format is undefined. See <xref linkend="pixfmt" /> for information on
 208 pixel formats.</entry>
 209           </row>
 210           <row>
 211             <entry></entry>
 212             <entry>&v4l2-field;</entry>
 213             <entry><structfield>field</structfield></entry>
 214             <entry>Drivers and applications shall ignore this field.
 215 If applicable, the field order is selected with the &VIDIOC-S-FMT;
 216 ioctl, using the <structfield>field</structfield> field of
 217 &v4l2-window;.</entry>
 218           </row>
 219           <row>
 220             <entry></entry>
 221             <entry>__u32</entry>
 222             <entry><structfield>bytesperline</structfield></entry>
 223             <entry>Distance in bytes between the leftmost pixels in
 224 two adjacent lines.</entry>
 225           </row>
 226           <row>
 227             <entry spanname="hspan"><para>This field is irrelevant to
 228 <wordasword>non-destructive Video
 229 Overlays</wordasword>.</para><para>For <wordasword>destructive Video
 230 Overlays</wordasword> both applications and drivers can set this field
 231 to request padding bytes at the end of each line. Drivers however may
 232 ignore the requested value, returning <structfield>width</structfield>
 233 times bytes-per-pixel or a larger value required by the hardware. That
 234 implies applications can just set this field to zero to get a
 235 reasonable default.</para><para>For <wordasword>Video Output
 236 Overlays</wordasword> the driver must return a valid
 237 value.</para><para>Video hardware may access padding bytes, therefore
 238 they must reside in accessible memory. Consider for example the case
 239 where padding bytes after the last line of an image cross a system
 240 page boundary. Capture devices may write padding bytes, the value is
 241 undefined. Output devices ignore the contents of padding
 242 bytes.</para><para>When the image format is planar the
 243 <structfield>bytesperline</structfield> value applies to the first
 244 plane and is divided by the same factor as the
 245 <structfield>width</structfield> field for the other planes. For
 246 example the Cb and Cr planes of a YUV 4:2:0 image have half as many
 247 padding bytes following each line as the Y plane. To avoid ambiguities
 248 drivers must return a <structfield>bytesperline</structfield> value
 249 rounded up to a multiple of the scale factor.</para></entry>
 250           </row>
 251           <row>
 252             <entry></entry>
 253             <entry>__u32</entry>
 254             <entry><structfield>sizeimage</structfield></entry>
 255             <entry><para>This field is irrelevant to
 256 <wordasword>non-destructive Video Overlays</wordasword>. For
 257 <wordasword>destructive Video Overlays</wordasword> applications must
 258 initialize this field. For <wordasword>Video Output
 259 Overlays</wordasword> the driver must return a valid
 260 format.</para><para>Together with <structfield>base</structfield> it
 261 defines the framebuffer memory accessible by the
 262 driver.</para></entry>
 263           </row>
 264           <row>
 265             <entry></entry>
 266             <entry>&v4l2-colorspace;</entry>
 267             <entry><structfield>colorspace</structfield></entry>
 268             <entry>This information supplements the
 269 <structfield>pixelformat</structfield> and must be set by the driver,
 270 see <xref linkend="colorspaces" />.</entry>
 271           </row>
 272           <row>
 273             <entry></entry>
 274             <entry>__u32</entry>
 275             <entry><structfield>priv</structfield></entry>
 276             <entry>Reserved. Drivers and applications must set this field to
 277 zero.</entry>
 278           </row>
 279         </tbody>
 280       </tgroup>
 281     </table>
 282
 283     <table pgwide="1" frame="none" id="framebuffer-cap">
 284       <title>Frame Buffer Capability Flags</title>
 285       <tgroup cols="3">
 286         &cs-def;
 287         <tbody valign="top">
 288           <row>
 289             <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant></entry>
 290             <entry>0x0001</entry>
 291             <entry>The device is capable of non-destructive overlays.
 292 When the driver clears this flag, only destructive overlays are
 293 supported. There are no drivers yet which support both destructive and
 294 non-destructive overlays. Video Output Overlays are in practice always
 295 non-destructive.</entry>
 296           </row>
 297           <row>
 298             <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
 299             <entry>0x0002</entry>
 300             <entry>The device supports clipping by chroma-keying the
 301 images. That is, image pixels replace pixels in the VGA or video
 302 signal only where the latter assume a certain color. Chroma-keying
 303 makes no sense for destructive overlays.</entry>
 304           </row>
 305           <row>
 306             <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant></entry>
 307             <entry>0x0004</entry>
 308             <entry>The device supports clipping using a list of clip
 309 rectangles.</entry>
 310           </row>
 311           <row>
 312             <entry><constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant></entry>
 313             <entry>0x0008</entry>
 314             <entry>The device supports clipping using a bit mask.</entry>
 315           </row>
 316           <row>
 317             <entry><constant>V4L2_FBUF_CAP_LOCAL_ALPHA</constant></entry>
 318             <entry>0x0010</entry>
 319             <entry>The device supports clipping/blending using the
 320 alpha channel of the framebuffer or VGA signal. Alpha blending makes
 321 no sense for destructive overlays.</entry>
 322           </row>
 323           <row>
 324             <entry><constant>V4L2_FBUF_CAP_GLOBAL_ALPHA</constant></entry>
 325             <entry>0x0020</entry>
 326             <entry>The device supports alpha blending using a global
 327 alpha value. Alpha blending makes no sense for destructive overlays.</entry>
 328           </row>
 329           <row>
 330             <entry><constant>V4L2_FBUF_CAP_LOCAL_INV_ALPHA</constant></entry>
 331             <entry>0x0040</entry>
 332             <entry>The device supports clipping/blending using the
 333 inverted alpha channel of the framebuffer or VGA signal. Alpha
 334 blending makes no sense for destructive overlays.</entry>
 335           </row>
 336           <row>
 337             <entry><constant>V4L2_FBUF_CAP_SRC_CHROMAKEY</constant></entry>
 338             <entry>0x0080</entry>
 339             <entry>The device supports Source Chroma-keying. Video pixels
 340 with the chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of
 341 <constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
 342           </row>
 343         </tbody>
 344       </tgroup>
 345     </table>
 346
 347     <table pgwide="1" frame="none" id="framebuffer-flags">
 348       <title>Frame Buffer Flags</title>
 349       <tgroup cols="3">
 350         &cs-def;
 351         <tbody valign="top">
 352           <row>
 353             <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry>
 354             <entry>0x0001</entry>
 355             <entry>The framebuffer is the primary graphics surface.
 356 In other words, the overlay is destructive. This flag is typically set by any
 357 driver that doesn't have the <constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant>
 358 capability and it is cleared otherwise.</entry>
 359           </row>
 360           <row>
 361             <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry>
 362             <entry>0x0002</entry>
 363             <entry>If this flag is set for a video capture device, then the
 364 driver will set the initial overlay size to cover the full framebuffer size,
 365 otherwise the existing overlay size (as set by &VIDIOC-S-FMT;) will be used.
 366
 367 Only one video capture driver (bttv) supports this flag. The use of this flag
 368 for capture devices is deprecated. There is no way to detect which drivers
 369 support this flag, so the only reliable method of setting the overlay size is
 370 through &VIDIOC-S-FMT;.
 371
 372 If this flag is set for a video output device, then the video output overlay
 373 window is relative to the top-left corner of the framebuffer and restricted
 374 to the size of the framebuffer. If it is cleared, then the video output
 375 overlay window is relative to the video output display.
 376             </entry>
 377           </row>
 378           <row>
 379             <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry>
 380             <entry>0x0004</entry>
 381             <entry>Use chroma-keying. The chroma-key color is
 382 determined by the <structfield>chromakey</structfield> field of
 383 &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
 384                 linkend="overlay" />
 385 and
 386             <xref linkend="osd" />.</entry>
 387           </row>
 388           <row>
 389             <entry spanname="hspan">There are no flags to enable
 390 clipping using a list of clip rectangles or a bitmap. These methods
 391 are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
 392                 linkend="overlay" /> and <xref linkend="osd" />.</entry>
 393           </row>
 394           <row>
 395             <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry>
 396             <entry>0x0008</entry>
 397             <entry>Use the alpha channel of the framebuffer to clip or
 398 blend framebuffer pixels with video images. The blend
 399 function is: output = framebuffer pixel * alpha + video pixel * (1 -
 400 alpha). The actual alpha depth depends on the framebuffer pixel
 401 format.</entry>
 402           </row>
 403           <row>
 404             <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry>
 405             <entry>0x0010</entry>
 406             <entry>Use a global alpha value to blend the framebuffer
 407 with video images. The blend function is: output = (framebuffer pixel
 408 * alpha + video pixel * (255 - alpha)) / 255. The alpha value is
 409 determined by the <structfield>global_alpha</structfield> field of
 410 &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
 411                 linkend="overlay" />
 412 and <xref linkend="osd" />.</entry>
 413           </row>
 414           <row>
 415             <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry>
 416             <entry>0x0020</entry>
 417             <entry>Like
 418 <constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, use the alpha channel
 419 of the framebuffer to clip or blend framebuffer pixels with video
 420 images, but with an inverted alpha value. The blend function is:
 421 output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The
 422 actual alpha depth depends on the framebuffer pixel format.</entry>
 423           </row>
 424           <row>
 425             <entry><constant>V4L2_FBUF_FLAG_SRC_CHROMAKEY</constant></entry>
 426             <entry>0x0040</entry>
 427             <entry>Use source chroma-keying. The source chroma-key color is
 428 determined by the <structfield>chromakey</structfield> field of
 429 &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
 430 linkend="overlay" /> and <xref linkend="osd" />.
 431 Both chroma-keying are mutual exclusive to each other, so same
 432 <structfield>chromakey</structfield> field of &v4l2-window; is being used.</entry>
 433           </row>
 434         </tbody>
 435       </tgroup>
 436     </table>
 437   </refsect1>
 438
 439   <refsect1>
 440     &return-value;
 441
 442     <variablelist>
 443       <varlistentry>
 444         <term><errorcode>EPERM</errorcode></term>
 445         <listitem>
 446           <para><constant>VIDIOC_S_FBUF</constant> can only be called
 447 by a privileged user to negotiate the parameters for a destructive
 448 overlay.</para>
 449         </listitem>
 450       </varlistentry>
 451       <varlistentry>
 452         <term><errorcode>EINVAL</errorcode></term>
 453         <listitem>
 454           <para>The <constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para>
 455         </listitem>
 456       </varlistentry>
 457     </variablelist>
 458   </refsect1>
 459 </refentry>