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 62framebuffer parameters for a <link linkend="overlay">Video 63Overlay</link> or <link linkend="osd">Video Output Overlay</link> 64(OSD). The type of overlay is implied by the device type (capture or 65output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl. 66One <filename>/dev/videoN</filename> device must not support both 67kinds of overlay.</para> 68 69 <para>The V4L2 API distinguishes destructive and non-destructive 70overlays. A destructive overlay copies captured video images into the 71video memory of a graphics card. A non-destructive overlay blends 72video images into a VGA signal or graphics into a video signal. 73<wordasword>Video Output Overlays</wordasword> are always 74non-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 79all fields of the structure or returns an &EINVAL; when overlays are 80not supported.</para> 81 82 <para>To set the parameters for a <wordasword>Video Output 83Overlay</wordasword>, applications must initialize the 84<structfield>flags</structfield> field of a struct 85<structname>v4l2_framebuffer</structname>. Since the framebuffer is 86implemented on the TV card all other parameters are determined by the 87driver. When an application calls <constant>VIDIOC_S_FBUF</constant> 88with a pointer to this structure, the driver prepares for the overlay 89and returns the framebuffer parameters as 90<constant>VIDIOC_G_FBUF</constant> does, or it returns an error 91code.</para> 92 93 <para>To set the parameters for a <wordasword>non-destructive 94Video 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 98overlay and returns the framebuffer parameters as 99<constant>VIDIOC_G_FBUF</constant> does, or it returns an error 100code.</para> 101 102 <para>For a <wordasword>destructive Video Overlay</wordasword> 103applications must additionally provide a 104<structfield>base</structfield> address. Setting up a DMA to a 105random memory location can jeopardize the system security, its 106stability or even damage the hardware, therefore only the superuser 107can 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 128driver, 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, 135that is the address of the pixel in the top left corner of the 136framebuffer.<footnote><para>A physical base address may not suit all 137platforms. GK notes in theory we should pass something like PCI device 138+ memory region + offset instead. If you encounter problems please 139discuss 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 148provide a base address. The driver may accept only base addresses 149which are a multiple of two, four or eight bytes. For 150<wordasword>Video Output Overlays</wordasword> the driver must return 151a valid base address, so applications can find the corresponding Linux 152framebuffer 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 160linkend="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 180framebuffer.</entry> 181 </row> 182 <row> 183 <entry></entry> 184 <entry></entry> 185 <entry></entry> 186 <entry>For <wordasword>non-destructive Video 187Overlays</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 195Overlays</wordasword> applications must initialize this field. For 196<wordasword>Video Output Overlays</wordasword> the driver must return 197a 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>) 205but YUV formats (only packed YUV formats when chroma keying is used, 206not 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 209behavior of the driver when an application requests a compressed 210format is undefined. See <xref linkend="pixfmt" /> for information on 211pixel 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. 218If applicable, the field order is selected with the &VIDIOC-S-FMT; 219ioctl, 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 227two adjacent lines.</entry> 228 </row> 229 <row> 230 <entry spanname="hspan"><para>This field is irrelevant to 231<wordasword>non-destructive Video 232Overlays</wordasword>.</para><para>For <wordasword>destructive Video 233Overlays</wordasword> both applications and drivers can set this field 234to request padding bytes at the end of each line. Drivers however may 235ignore the requested value, returning <structfield>width</structfield> 236times bytes-per-pixel or a larger value required by the hardware. That 237implies applications can just set this field to zero to get a 238reasonable default.</para><para>For <wordasword>Video Output 239Overlays</wordasword> the driver must return a valid 240value.</para><para>Video hardware may access padding bytes, therefore 241they must reside in accessible memory. Consider for example the case 242where padding bytes after the last line of an image cross a system 243page boundary. Capture devices may write padding bytes, the value is 244undefined. Output devices ignore the contents of padding 245bytes.</para><para>When the image format is planar the 246<structfield>bytesperline</structfield> value applies to the largest 247plane and is divided by the same factor as the 248<structfield>width</structfield> field for any smaller planes. For 249example the Cb and Cr planes of a YUV 4:2:0 image have half as many 250padding bytes following each line as the Y plane. To avoid ambiguities 251drivers must return a <structfield>bytesperline</structfield> value 252rounded 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 261initialize this field. For <wordasword>Video Output 262Overlays</wordasword> the driver must return a valid 263format.</para><para>Together with <structfield>base</structfield> it 264defines the framebuffer memory accessible by the 265driver.</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, 273see <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 281set 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. 296When the driver clears this flag, only destructive overlays are 297supported. There are no drivers yet which support both destructive and 298non-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 304images. That is, image pixels replace pixels in the VGA or video 305signal only where the latter assume a certain color. Chroma-keying 306makes 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 312rectangles.</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 323alpha channel of the framebuffer or VGA signal. Alpha blending makes 324no 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 330alpha 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 336inverted alpha channel of the framebuffer or VGA signal. Alpha 337blending 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 343with 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. 359In 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 365size 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. 371Most 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 379determined by the <structfield>chromakey</structfield> field of 380&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref 381 linkend="overlay" /> 382and 383 <xref linkend="osd" />.</entry> 384 </row> 385 <row> 386 <entry spanname="hspan">There are no flags to enable 387clipping using a list of clip rectangles or a bitmap. These methods 388are 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 395blend framebuffer pixels with video images. The blend 396function is: output = framebuffer pixel * alpha + video pixel * (1 - 397alpha). The actual alpha depth depends on the framebuffer pixel 398format.</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 404with video images. The blend function is: output = (framebuffer pixel 405* alpha + video pixel * (255 - alpha)) / 255. The alpha value is 406determined by the <structfield>global_alpha</structfield> field of 407&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref 408 linkend="overlay" /> 409and <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 416of the framebuffer to clip or blend framebuffer pixels with video 417images, but with an inverted alpha value. The blend function is: 418output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The 419actual 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 425determined by the <structfield>chromakey</structfield> field of 426&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref 427linkend="overlay" /> and <xref linkend="osd" />. 428Both 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 444by a privileged user to negotiate the parameters for a destructive 445overlay.</para> 446 </listitem> 447 </varlistentry> 448 <varlistentry> 449 <term><errorcode>EBUSY</errorcode></term> 450 <listitem> 451 <para>The framebuffer parameters cannot be changed at this 452time because overlay is already enabled, or capturing is enabled 453and the hardware cannot capture and overlay simultaneously.</para> 454 </listitem> 455 </varlistentry> 456 <varlistentry> 457 <term><errorcode>EINVAL</errorcode></term> 458 <listitem> 459 <para>The ioctl is not supported or the 460<constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para> 461 </listitem> 462 </varlistentry> 463 </variablelist> 464 </refsect1> 465</refentry> 466 467<!-- 468Local Variables: 469mode: sgml 470sgml-parent-document: "v4l2.sgml" 471indent-tabs-mode: nil 472End: 473--> 474