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. Video Output Overlays are in practice always 299non-destructive.</entry> 300 </row> 301 <row> 302 <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry> 303 <entry>0x0002</entry> 304 <entry>The device supports clipping by chroma-keying the 305images. That is, image pixels replace pixels in the VGA or video 306signal only where the latter assume a certain color. Chroma-keying 307makes no sense for destructive overlays.</entry> 308 </row> 309 <row> 310 <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant></entry> 311 <entry>0x0004</entry> 312 <entry>The device supports clipping using a list of clip 313rectangles.</entry> 314 </row> 315 <row> 316 <entry><constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant></entry> 317 <entry>0x0008</entry> 318 <entry>The device supports clipping using a bit mask.</entry> 319 </row> 320 <row> 321 <entry><constant>V4L2_FBUF_CAP_LOCAL_ALPHA</constant></entry> 322 <entry>0x0010</entry> 323 <entry>The device supports clipping/blending using the 324alpha channel of the framebuffer or VGA signal. Alpha blending makes 325no sense for destructive overlays.</entry> 326 </row> 327 <row> 328 <entry><constant>V4L2_FBUF_CAP_GLOBAL_ALPHA</constant></entry> 329 <entry>0x0020</entry> 330 <entry>The device supports alpha blending using a global 331alpha value. Alpha blending makes no sense for destructive overlays.</entry> 332 </row> 333 <row> 334 <entry><constant>V4L2_FBUF_CAP_LOCAL_INV_ALPHA</constant></entry> 335 <entry>0x0040</entry> 336 <entry>The device supports clipping/blending using the 337inverted alpha channel of the framebuffer or VGA signal. Alpha 338blending makes no sense for destructive overlays.</entry> 339 </row> 340 <row> 341 <entry><constant>V4L2_FBUF_CAP_SRC_CHROMAKEY</constant></entry> 342 <entry>0x0080</entry> 343 <entry>The device supports Source Chroma-keying. Video pixels 344with the chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of 345<constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry> 346 </row> 347 </tbody> 348 </tgroup> 349 </table> 350 351 <table pgwide="1" frame="none" id="framebuffer-flags"> 352 <title>Frame Buffer Flags</title> 353 <tgroup cols="3"> 354 &cs-def; 355 <tbody valign="top"> 356 <row> 357 <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry> 358 <entry>0x0001</entry> 359 <entry>The framebuffer is the primary graphics surface. 360In other words, the overlay is destructive. This flag is typically set by any 361driver that doesn't have the <constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant> 362capability and it is cleared otherwise.</entry> 363 </row> 364 <row> 365 <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry> 366 <entry>0x0002</entry> 367 <entry>If this flag is set for a video capture device, then the 368driver will set the initial overlay size to cover the full framebuffer size, 369otherwise the existing overlay size (as set by &VIDIOC-S-FMT;) will be used. 370 371Only one video capture driver (bttv) supports this flag. The use of this flag 372for capture devices is deprecated. There is no way to detect which drivers 373support this flag, so the only reliable method of setting the overlay size is 374through &VIDIOC-S-FMT;. 375 376If this flag is set for a video output device, then the video output overlay 377window is relative to the top-left corner of the framebuffer and restricted 378to the size of the framebuffer. If it is cleared, then the video output 379overlay window is relative to the video output display. 380 </entry> 381 </row> 382 <row> 383 <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry> 384 <entry>0x0004</entry> 385 <entry>Use chroma-keying. The chroma-key color is 386determined by the <structfield>chromakey</structfield> field of 387&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref 388 linkend="overlay" /> 389and 390 <xref linkend="osd" />.</entry> 391 </row> 392 <row> 393 <entry spanname="hspan">There are no flags to enable 394clipping using a list of clip rectangles or a bitmap. These methods 395are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref 396 linkend="overlay" /> and <xref linkend="osd" />.</entry> 397 </row> 398 <row> 399 <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry> 400 <entry>0x0008</entry> 401 <entry>Use the alpha channel of the framebuffer to clip or 402blend framebuffer pixels with video images. The blend 403function is: output = framebuffer pixel * alpha + video pixel * (1 - 404alpha). The actual alpha depth depends on the framebuffer pixel 405format.</entry> 406 </row> 407 <row> 408 <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry> 409 <entry>0x0010</entry> 410 <entry>Use a global alpha value to blend the framebuffer 411with video images. The blend function is: output = (framebuffer pixel 412* alpha + video pixel * (255 - alpha)) / 255. The alpha value is 413determined by the <structfield>global_alpha</structfield> field of 414&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref 415 linkend="overlay" /> 416and <xref linkend="osd" />.</entry> 417 </row> 418 <row> 419 <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry> 420 <entry>0x0020</entry> 421 <entry>Like 422<constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, use the alpha channel 423of the framebuffer to clip or blend framebuffer pixels with video 424images, but with an inverted alpha value. The blend function is: 425output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The 426actual alpha depth depends on the framebuffer pixel format.</entry> 427 </row> 428 <row> 429 <entry><constant>V4L2_FBUF_FLAG_SRC_CHROMAKEY</constant></entry> 430 <entry>0x0040</entry> 431 <entry>Use source chroma-keying. The source chroma-key color is 432determined by the <structfield>chromakey</structfield> field of 433&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref 434linkend="overlay" /> and <xref linkend="osd" />. 435Both chroma-keying are mutual exclusive to each other, so same 436<structfield>chromakey</structfield> field of &v4l2-window; is being used.</entry> 437 </row> 438 </tbody> 439 </tgroup> 440 </table> 441 </refsect1> 442 443 <refsect1> 444 &return-value; 445 446 <variablelist> 447 <varlistentry> 448 <term><errorcode>EPERM</errorcode></term> 449 <listitem> 450 <para><constant>VIDIOC_S_FBUF</constant> can only be called 451by a privileged user to negotiate the parameters for a destructive 452overlay.</para> 453 </listitem> 454 </varlistentry> 455 <varlistentry> 456 <term><errorcode>EINVAL</errorcode></term> 457 <listitem> 458 <para>The <constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para> 459 </listitem> 460 </varlistentry> 461 </variablelist> 462 </refsect1> 463</refentry> 464