Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.
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>
