VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IFramebuffer Interface Reference
Inheritance diagram for IFramebuffer:

## Public Member Functions
void | notifyUpdate (in unsigned long x, in unsigned long y, in unsigned long width, in unsigned long height)
| Informs about an update.
void | notifyUpdateImage (in unsigned long x, in unsigned long y, in unsigned long width, in unsigned long height, in octet[] image)
| Informs about an update and provides 32bpp bitmap.
void | notifyChange (in unsigned long screenId, in unsigned long xOrigin, in unsigned long yOrigin, in unsigned long width, in unsigned long height)
| Requests a size change.
void | videoModeSupported (in unsigned long width, in unsigned long height, in unsigned long bpp, [retval] out boolean supported)
| Returns whether the frame buffer implementation is willing to support a given video mode.
void | getVisibleRegion (in octetPtr rectangles, in unsigned long count, [retval] out unsigned long countCopied)
| Returns the visible region of this frame buffer.
void | setVisibleRegion (in octetPtr rectangles, in unsigned long count)
| Suggests a new visible region to this frame buffer.
void | processVHWACommand (in octetPtr command, in long enmCmd, in boolean fromGuest)
| Posts a Video HW Acceleration Command to the frame buffer for processing.
void | notify3DEvent (in unsigned long type, in octet[] data)
| Notifies framebuffer about 3D backend event.

## Public Attributes
readonly attribute unsigned long | width
| Frame buffer width, in pixels.
readonly attribute unsigned long | height
| Frame buffer height, in pixels.
readonly attribute unsigned long | bitsPerPixel
| Color depth, in bits per pixel.
readonly attribute unsigned long | bytesPerLine
| Scan line size, in bytes.
readonly attribute BitmapFormat | pixelFormat
| Frame buffer pixel format.
readonly attribute unsigned long | heightReduction
| Hint from the frame buffer about how much of the standard screen height it wants to use for itself.
readonly attribute IFramebufferOverlay | overlay
| An alpha-blended overlay which is superposed over the frame buffer.
readonly attribute long long | winId
| Platform-dependent identifier of the window where context of this frame buffer is drawn, or zero if there's no such window.
readonly attribute FramebufferCapabilities[] | capabilities
| Capabilities of the framebuffer instance.

## Member Function Documentation

## ◆ notifyUpdate()

void IFramebuffer::notifyUpdate | ( | in unsigned long | x,
|  | in unsigned long | y,
|  | in unsigned long | width,
|  | in unsigned long | height
| ) |  |

Informs about an update.

Gets called by the display object where this buffer is registered.

Parameters

  x | X position of update.
  y | Y position of update.
  width | Width of update.
  height | Height of update.

## ◆ notifyUpdateImage()

void IFramebuffer::notifyUpdateImage | ( | in unsigned long | x,
|  | in unsigned long | y,
|  | in unsigned long | width,
|  | in unsigned long | height,
|  | in octet[] | image
| ) |  |

Informs about an update and provides 32bpp bitmap.

Parameters

  x | X position of update.
  y | Y position of update.
  width | Width of update.
  height | Height of update.
  image | Array with 32BPP image data.

## ◆ notifyChange()

void IFramebuffer::notifyChange | ( | in unsigned long | screenId,
|  | in unsigned long | xOrigin,
|  | in unsigned long | yOrigin,
|  | in unsigned long | width,
|  | in unsigned long | height
| ) |  |

Requests a size change.

Parameters

  screenId | Logical guest screen number.
  xOrigin | Location of the screen in the guest.
  yOrigin | Location of the screen in the guest.
  width | Width of the guest display, in pixels.
  height | Height of the guest display, in pixels.

## ◆ videoModeSupported()

void IFramebuffer::videoModeSupported | ( | in unsigned long | width,
|  | in unsigned long | height,
|  | in unsigned long | bpp,
|  | [retval] out boolean | supported
| ) |  |

Returns whether the frame buffer implementation is willing to support a given video mode.

In case it is not able to render the video mode (or for some reason not willing), it should return `false`. Usually this method is called when the guest asks the VMM device whether a given video mode is supported so the information returned is directly exposed to the guest. It is important that this method returns very quickly.

## ◆ getVisibleRegion()

void IFramebuffer::getVisibleRegion | ( | in octetPtr | rectangles,
|  | in unsigned long | count,
|  | [retval] out unsigned long | countCopied
| ) |  |

Returns the visible region of this frame buffer.

If the rectangles parameter is `null` then the value of the count parameter is ignored and the number of elements necessary to describe the current visible region is returned in countCopied.

If rectangles is not `null` but count is less than the required number of elements to store region data, the method will report a failure. If count is equal or greater than the required number of elements, then the actual number of elements copied to the provided array will be returned in countCopied.

Parameters

  rectangles | Pointer to the `RTRECT` array to receive region data.
  count | Number of `RTRECT` elements in the rectangles array.
  countCopied | Number of elements copied to the rectangles array.

Note
  The address of the provided array must be in the process space of this IFramebuffer object.
  Method not yet implemented.

Warning
  This method is non-scriptable. In particular, this also means that an attempt to call it from a process other than the process that has created and owns the object will most likely fail or crash your application.

## ◆ setVisibleRegion()

void IFramebuffer::setVisibleRegion | ( | in octetPtr | rectangles,
|  | in unsigned long | count
| ) |  |

Suggests a new visible region to this frame buffer.

This region represents the area of the VM display which is a union of regions of all top-level windows of the guest operating system running inside the VM (if the Guest Additions for this system support this functionality). This information may be used by the frontends to implement the seamless desktop integration feature.

Parameters

  rectangles | Pointer to the `RTRECT` array.
  count | Number of `RTRECT` elements in the rectangles array.

Note
  The address of the provided array must be in the process space of this IFramebuffer object.
  The IFramebuffer implementation must make a copy of the provided array of rectangles.
  Method not yet implemented.

Warning
  This method is non-scriptable. In particular, this also means that an attempt to call it from a process other than the process that has created and owns the object will most likely fail or crash your application.

## ◆ processVHWACommand()

void IFramebuffer::processVHWACommand | ( | in octetPtr | command,
|  | in long | enmCmd,
|  | in boolean | fromGuest
| ) |  |

Posts a Video HW Acceleration Command to the frame buffer for processing.

The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color conversion, overlaying, etc.) are posted from quest to the host to be processed by the host hardware.

Parameters

  command | Pointer to VBOXVHWACMD containing the command to execute.
  enmCmd | The validated VBOXVHWACMD::enmCmd value from the command.
  fromGuest | Set when the command origins from the guest, clear if host.

Note
  The address of the provided command must be in the process space of this IFramebuffer object.

Warning
  This method is non-scriptable. In particular, this also means that an attempt to call it from a process other than the process that has created and owns the object will most likely fail or crash your application.

## ◆ notify3DEvent()

void IFramebuffer::notify3DEvent | ( | in unsigned long | type,
|  | in octet[] | data
| ) |  |

Notifies framebuffer about 3D backend event.

Parameters

  type | event type. VBOX3D_NOTIFY_TYPE_* in VBoxVideo3D.h
  data | event-specific data, depends on the supplied event type

## Member Data Documentation

## ◆ width

readonly attribute unsigned long IFramebuffer::width

Frame buffer width, in pixels.

## ◆ height

readonly attribute unsigned long IFramebuffer::height

Frame buffer height, in pixels.

## ◆ bitsPerPixel

readonly attribute unsigned long IFramebuffer::bitsPerPixel

Color depth, in bits per pixel.

## ◆ bytesPerLine

readonly attribute unsigned long IFramebuffer::bytesPerLine

Scan line size, in bytes.

## ◆ pixelFormat

readonly attribute BitmapFormat IFramebuffer::pixelFormat

Frame buffer pixel format.

It's one of the values defined by BitmapFormat.

Note
  This attribute must never (and will never) return BitmapFormat_Opaque – the format of the frame buffer must be always known.

## ◆ heightReduction

readonly attribute unsigned long IFramebuffer::heightReduction

Hint from the frame buffer about how much of the standard screen height it wants to use for itself.

This information is exposed to the guest through the VESA BIOS and VMMDev interface so that it can use it for determining its video mode table. It is not guaranteed that the guest respects the value.

## ◆ overlay

readonly attribute IFramebufferOverlay IFramebuffer::overlay

An alpha-blended overlay which is superposed over the frame buffer.

The initial purpose is to allow the display of icons providing information about the VM state, including disk activity, in front ends which do not have other means of doing that. The overlay is designed to controlled exclusively by IDisplay. It has no locking of its own, and any changes made to it are not guaranteed to be visible until the affected portion of IFramebuffer is updated. The overlay can be created lazily the first time it is requested. This attribute can also return `null` to signal that the overlay is not implemented.

## ◆ winId

readonly attribute long long IFramebuffer::winId

Platform-dependent identifier of the window where context of this frame buffer is drawn, or zero if there's no such window.

## ◆ capabilities

readonly attribute FramebufferCapabilities [] IFramebuffer::capabilities

Capabilities of the framebuffer instance.

For the meaning of individual capability flags see FramebufferCapabilities.