# IFramebuffer Interface Reference

List of all members.

## Public Member Functions
void | lock ()
| Locks the framebuffer.
void | unlock ()
| Unlocks the framebuffer.
void | notifyUpdate (in unsigned long x, in unsigned long y, in unsigned long width, in unsigned long height,[retval] out boolean finished)
| Informs about an update.
void | requestResize (in unsigned long screenId, in unsigned long pixelFormat, in octetPtr VRAM, in unsigned long bitsPerPixel, in unsigned long bytesPerLine, in unsigned long width, in unsigned long height,[retval] out boolean finished)
| Requests a size and pixel format change.
void | operationSupported (in FramebufferAccelerationOperation operation,[retval] out boolean supported)
| Returns whether the given acceleration operation is supported by the IFramebuffer implementation.
void | videoModeSupported (in unsigned long width, in unsigned long height, in unsigned long bpp,[retval] out boolean supported)
| Returns whether the framebuffer implementation is willing to support a given video mode.
void | solidFill (in unsigned long x, in unsigned long y, in unsigned long width, in unsigned long height, in unsigned long color,[retval] out boolean handled)
| Fills the specified rectangle on screen with a solid color.
void | copyScreenBits (in unsigned long xDst, in unsigned long yDst, in unsigned long xSrc, in unsigned long ySrc, in unsigned long width, in unsigned long height,[retval] out boolean handled)
| Copies specified rectangle on the screen.
void | getVisibleRegion (in octetPtr rectangles, in unsigned long count,[retval] out unsigned long countCopied)
| Returns the visible region of this framebuffer.
void | setVisibleRegion (in octetPtr rectangles, in unsigned long count)
| Suggests a new visible region to this framebuffer.
## Public Attributes
readonly attribute octetPtr | address
| Address of the start byte of the framebuffer.
readonly attribute unsigned long | width
| Framebuffer width, in pixels.
readonly attribute unsigned long | height
| Framebuffer 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 unsigned long | pixelFormat
| Framebuffer pixel format.
readonly attribute boolean | usesGuestVRAM
| Defines whether this framebuffer uses the virtual video card's memory buffer (guest VRAM) directly or not.
readonly attribute unsigned long | heightReduction
| Hint from the framebuffer 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 framebuffer.

## Member Function Documentation

void IFramebuffer::lock | ( |  | ) |

Locks the framebuffer.

Gets called by the IDisplay object where this framebuffer is bound to.

void IFramebuffer::unlock | ( |  | ) |

Unlocks the framebuffer.

Gets called by the IDisplay object where this framebuffer is bound to.

void IFramebuffer::notifyUpdate | ( | in unsigned long | x,
|  | in unsigned long | y,
|  | in unsigned long | width,
|  | in unsigned long | height,
|  | [retval] out boolean | finished |
| ) |  |  |

Informs about an update.

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

void IFramebuffer::requestResize | ( | in unsigned long | screenId,
|  | in unsigned long | pixelFormat,
|  | in octetPtr | VRAM,
|  | in unsigned long | bitsPerPixel,
|  | in unsigned long | bytesPerLine,
|  | in unsigned long | width,
|  | in unsigned long | height,
|  | [retval] out boolean | finished |
| ) |  |  |

Requests a size and pixel format change.

There are two modes of working with the video buffer of the virtual machine. The indirect mode implies that the IFramebuffer implementation allocates a memory buffer for the requested display mode and provides it to the virtual machine. In direct mode, the IFramebuffer implementation uses the memory buffer allocated and owned by the virtual machine. This buffer represents the video memory of the emulated video adapter (so called guest VRAM). The direct mode is usually faster because the implementation gets a raw pointer to the guest VRAM buffer which it can directly use for visualising the contents of the virtual display, as opposed to the indirect mode where the contents of guest VRAM are copied to the memory buffer provided by the implementation every time a display update occurs.

It is important to note that the direct mode is really fast only when the implementation uses the given guest VRAM buffer directly, for example, by blitting it to the window representing the virtual machine's display, which saves at least one copy operation comparing to the indirect mode. However, using the guest VRAM buffer directly is not always possible: the format and the color depth of this buffer may be not supported by the target window, or it may be unknown (opaque) as in case of text or non-linear multi-plane VGA video modes. In this case, the indirect mode (that is always available) should be used as a fallback: when the guest VRAM contents are copied to the implementation-provided memory buffer, color and format conversion is done authomatically by the underlying code.

The pixelFormat parameter defines whether the direct mode is available or not. If pixelFormat is PixelFormat::Opaque then direct access to the guest VRAM buffer is not available -- the VRAM, bitsPerPixel and bytesPerLine parameters must be ignored and the implementation must use the indirect mode (where it provides its own buffer in one of the supported formats). In all other cases, pixelFormat together with bitsPerPixel and bytesPerLine define the format of the video memory buffer pointed to by the VRAM parameter and the implementation is free to choose which mode to use. To indicate that this framebuffer uses the direct mode, the implementation of the usesGuestVRAM attribute must return `true` and address must return exactly the same address that is passed in the VRAM parameter of this method; otherwise it is assumed that the indirect strategy is chosen.

The width and height parameters represent the size of the requested display mode in both modes. In case of indirect mode, the provided memory buffer should be big enough to store data of the given display mode. In case of direct mode, it is guaranteed that the given VRAM buffer contains enough space to represent the display mode of the given size. Note that this framebuffer's width and height attributes must return exactly the same values as passed to this method after the resize is completed (see below).

The finished output parameter determines if the implementation has finished resizing the framebuffer or not. If, for some reason, the resize cannot be finished immediately during this call, finished must be set to `false`, and the implementation must call IDisplay::resizeCompleted() after it has returned from this method as soon as possible. If finished is `false`, the machine will not call any framebuffer methods until IDisplay::resizeCompleted() is called.

Note that if the direct mode is chosen, the bitsPerPixel, bytesPerLine and pixelFormat attributes of this framebuffer must return exactly the same values as specified in the parameters of this method, after the resize is completed. If the indirect mode is chosen, these attributes must return values describing the format of the implementation's own memory buffer address points to. Note also that the bitsPerPixel value must always correlate with pixelFormat. Note that the pixelFormat attribute must never return PixelFormat::Opaque regardless of the selected mode.

Parameters:

  | screenId | Logical screen number. Must be used in the corresponding call to IDisplay::resizeCompleted() if this call is made.
  | pixelFormat | Pixel format of the memory buffer pointed to by VRAM. See also FramebufferPixelFormat.
  | VRAM | Pointer to the virtual video card's VRAM (may be `null`).
  | bitsPerPixel | Color depth, bits per pixel.
  | bytesPerLine | Size of one scan line, in bytes.
  | width | Width of the guest display, in pixels.
  | height | Height of the guest display, in pixels.
  | finished | Can the VM start using the new framebuffer immediately after this method returns or it should wait for IDisplay::resizeCompleted().

Note:
  This method is called by the IDisplay object under the lock() provided by this IFramebuffer implementation. If this method returns `false` in finished, then this lock is not released until IDisplay::resizeCompleted() is called.

Warning:
  This method is non-scriptable. In particluar, 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.

void IFramebuffer::operationSupported | ( | in FramebufferAccelerationOperation | operation,
|  | [retval] out boolean | supported |
| ) |  |  |

Returns whether the given acceleration operation is supported by the IFramebuffer implementation.

If not, the display object will not attempt to call the corresponding IFramebuffer entry point. Even if an operation is indicated to supported, the IFramebuffer implementation always has the option to return non supported from the corresponding acceleration method in which case the operation will be performed by the display engine. This allows for reduced IFramebuffer implementation complexity where only common cases are handled.

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

Returns whether the framebuffer 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.

void IFramebuffer::solidFill | ( | in unsigned long | x,
|  | in unsigned long | y,
|  | in unsigned long | width,
|  | in unsigned long | height,
|  | in unsigned long | color,
|  | [retval] out boolean | handled |
| ) |  |  |

Fills the specified rectangle on screen with a solid color.

void IFramebuffer::copyScreenBits | ( | in unsigned long | xDst,
|  | in unsigned long | yDst,
|  | in unsigned long | xSrc,
|  | in unsigned long | ySrc,
|  | in unsigned long | width,
|  | in unsigned long | height,
|  | [retval] out boolean | handled |
| ) |  |  |

Copies specified rectangle on the screen.

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

Returns the visible region of this framebuffer.

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.

Warning:
  This method is non-scriptable. In particluar, 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.

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

Suggests a new visible region to this framebuffer.

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.

Warning:
  This method is non-scriptable. In particluar, 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.

## Member Data Documentation

readonly attribute octetPtr IFramebuffer::address

Address of the start byte of the framebuffer.

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

readonly attribute unsigned long IFramebuffer::width

Framebuffer width, in pixels.

readonly attribute unsigned long IFramebuffer::height

Framebuffer height, in pixels.

readonly attribute unsigned long IFramebuffer::bitsPerPixel

Color depth, in bits per pixel.

When pixelFormat is FOURCC_RGB, valid values are: 8, 15, 16, 24 and 32.

readonly attribute unsigned long IFramebuffer::bytesPerLine

Scan line size, in bytes.

When pixelFormat is FOURCC_RGB, the size of the scan line must be aligned to 32 bits.

readonly attribute unsigned long IFramebuffer::pixelFormat

Framebuffer pixel format.

It's either one of the values defined by FramebufferPixelFormat or a raw FOURCC code.

Note:
  This attribute must never return PixelFormat::Opaque -- the format of the buffer address points to must be always known.

readonly attribute boolean IFramebuffer::usesGuestVRAM

Defines whether this framebuffer uses the virtual video card's memory buffer (guest VRAM) directly or not.

See IFramebuffer::requestResize() for more information.

readonly attribute unsigned long IFramebuffer::heightReduction

Hint from the framebuffer 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.

readonly attribute IFramebufferOverlay IFramebuffer::overlay

An alpha-blended overlay which is superposed over the framebuffer.

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.