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

Public Member Functions

void lock ()
 Locks the frame buffer.
void unlock ()
 Unlocks the frame buffer.
void notifyUpdate (in unsigned long x, in unsigned long y, in unsigned long width, in unsigned long height)
 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 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)
 Posts a Video HW Acceleration Command to the frame buffer for processing.
void notify3DEvent (in unsigned long type, in octetPtr data)
 Notifies framebuffer about 3D backend event.

Public Attributes

readonly attribute octetPtr address
 Address of the start byte of the frame buffer.
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 unsigned long pixelFormat
 Frame buffer pixel format.
readonly attribute boolean usesGuestVRAM
 Defines whether this frame buffer uses the virtual video card's memory buffer (guest VRAM) directly or not.
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.

Member Function Documentation

void IFramebuffer::lock ( )

Locks the frame buffer.

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

void IFramebuffer::unlock ( )

Unlocks the frame buffer.

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

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.

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 <i>indirect</i> mode implies that the IFramebuffer
    implementation allocates a memory buffer for the requested display mode
    and provides it to the virtual machine. In <i>direct</i> 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 <i>guest VRAM</i>). The direct mode is
    usually faster because the implementation gets a raw pointer to the
    guest VRAM buffer which it can directly use for visualizing 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 automatically by the underlying code.

    The @a pixelFormat parameter defines whether the direct mode is
    available or not. If @a pixelFormat is @link ::FramebufferPixelFormat_Opaque FramebufferPixelFormat_Opaque@endlink<b></b> then direct access to the guest
    VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
    @a 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, @a pixelFormat together with
    @a bitsPerPixel and @a bytesPerLine define the format of the video memory
    buffer pointed to by the @a VRAM parameter and the implementation is
    free to choose which mode to use. To indicate that this frame buffer uses
    the direct mode, the implementation of the @link #usesGuestVRAM usesGuestVRAM@endlink<b></b>
    attribute must return @c true and @link #address address@endlink<b></b> must
    return exactly the same address that is passed in the @a VRAM parameter
    of this method; otherwise it is assumed that the indirect strategy is
    chosen.

    The @a width and @a 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
    @a VRAM buffer contains enough space to represent the display mode of the
    given size. Note that this frame buffer's @link #width width@endlink<b></b> and @link #height height@endlink<b></b> attributes must return exactly the same values as
    passed to this method after the resize is completed (see below).

    The @a finished output parameter determines if the implementation has
    finished resizing the frame buffer or not. If, for some reason, the
    resize cannot be finished immediately during this call, @a finished
    must be set to @c false, and the implementation must call
    @link IDisplay::resizeCompleted IDisplay::resizeCompleted@endlink<b></b> after it has returned from
    this method as soon as possible. If @a finished is @c false, the
    machine will not call any frame buffer methods until
    @link IDisplay::resizeCompleted IDisplay::resizeCompleted@endlink<b></b> is called.

    Note that if the direct mode is chosen, the @link #bitsPerPixel bitsPerPixel@endlink<b></b>,
    @link #bytesPerLine bytesPerLine@endlink<b></b> and @link #pixelFormat pixelFormat@endlink<b></b> attributes of
    this frame buffer 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 @link #address address@endlink<b></b> points to. Note also that the @link #bitsPerPixel bitsPerPixel@endlink<b></b>
    value must always correlate with @link #pixelFormat pixelFormat@endlink<b></b>. Note that
    the @link #pixelFormat pixelFormat@endlink<b></b> attribute must never return @link ::FramebufferPixelFormat_Opaque FramebufferPixelFormat_Opaque@endlink<b></b> regardless of the selected mode.
Parameters
screenIdLogical screen number. Must be used in the corresponding call to IDisplay::resizeCompleted if this call is made.
pixelFormatPixel format of the memory buffer pointed to by VRAM. See also FramebufferPixelFormat.
VRAMPointer to the virtual video card's VRAM (may be null).
bitsPerPixelColor depth, bits per pixel.
bytesPerLineSize of one scan line, in bytes.
widthWidth of the guest display, in pixels.
heightHeight of the guest display, in pixels.
finishedCan the VM start using the new frame buffer 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 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.
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.

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 @a rectangles parameter is @c null then the value of the
    @a count parameter is ignored and the number of elements necessary to
    describe the current visible region is returned in @a countCopied.

    If @a rectangles is not @c null but @a count is less
    than the required number of elements to store region data, the method
    will report a failure. If @a 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 @a countCopied.
Parameters
rectanglesPointer to the RTRECT array to receive region data.
countNumber of RTRECT elements in the rectangles array.
countCopiedNumber 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.
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
rectanglesPointer to the RTRECT array.
countNumber 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.
void IFramebuffer::processVHWACommand ( in octetPtr  command)

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
commandPointer to VBOXVHWACMD containing the command to execute.
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.
void IFramebuffer::notify3DEvent ( in unsigned long  type,
in octetPtr  data 
)

Notifies framebuffer about 3D backend event.

Parameters
typeevent type. Currently only VBOX3D_NOTIFY_EVENT_TYPE_VISIBLE_3DDATA is supported.
dataevent-specific data, depends on the supplied event type
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.

Member Data Documentation

readonly attribute octetPtr IFramebuffer::address

Address of the start byte of the frame buffer.

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

Frame buffer width, in pixels.

readonly attribute unsigned long IFramebuffer::height

Frame buffer 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

Frame buffer pixel format.

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

Note
This attribute must never (and will never) return FramebufferPixelFormat_Opaque – the format of the frame buffer must be always known.
readonly attribute boolean IFramebuffer::usesGuestVRAM

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

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.

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.

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.