VirtualBox Main API
Public Member Functions | List of all members
IDisplay Interface Reference

The IDisplay interface represents the virtual machine's display. More...

Inheritance diagram for IDisplay:

Public Member Functions

void getScreenResolution (in unsigned long screenId, out unsigned long width, out unsigned long height, out unsigned long bitsPerPixel, out long xOrigin, out long yOrigin, out GuestMonitorStatus guestMonitorStatus)
 Queries certain attributes such as display width, height, color depth and the X and Y origin for a given guest screen. More...
 
void attachFramebuffer (in unsigned long screenId, in IFramebuffer framebuffer, [retval] out wstringUUID id)
 Sets the graphics update target for a screen. More...
 
void detachFramebuffer (in unsigned long screenId, in wstringUUID id)
 Removes the graphics updates target for a screen. More...
 
void queryFramebuffer (in unsigned long screenId, [retval] out IFramebuffer framebuffer)
 Queries the graphics updates targets for a screen. More...
 
void setVideoModeHint (in unsigned long display, in boolean enabled, in boolean changeOrigin, in long originX, in long originY, in unsigned long width, in unsigned long height, in unsigned long bitsPerPixel)
 Asks VirtualBox to request the given video mode from the guest. More...
 
void setSeamlessMode (in boolean enabled)
 Enables or disables seamless guest display rendering (seamless desktop integration) mode. More...
 
void takeScreenShot (in unsigned long screenId, in octetPtr address, in unsigned long width, in unsigned long height, in BitmapFormat bitmapFormat)
 Takes a screen shot of the requested size and format and copies it to the buffer allocated by the caller and pointed to by address. More...
 
void takeScreenShotToArray (in unsigned long screenId, in unsigned long width, in unsigned long height, in BitmapFormat bitmapFormat, [retval] out octet[] screenData)
 Takes a guest screen shot of the requested size and format and returns it as an array of bytes. More...
 
void drawToScreen (in unsigned long screenId, in octetPtr address, in unsigned long x, in unsigned long y, in unsigned long width, in unsigned long height)
 Draws a 32-bpp image of the specified size from the given buffer to the given point on the VM display. More...
 
void invalidateAndUpdate ()
 Does a full invalidation of the VM display and instructs the VM to update it. More...
 
void invalidateAndUpdateScreen (in unsigned long screenId)
 Redraw the specified VM screen. More...
 
void completeVHWACommand (in octetPtr command)
 Signals that the Video HW Acceleration command has completed. More...
 
void viewportChanged (in unsigned long screenId, in unsigned long x, in unsigned long y, in unsigned long width, in unsigned long height)
 Signals that framebuffer window viewport has changed. More...
 
void querySourceBitmap (in unsigned long screenId, out IDisplaySourceBitmap displaySourceBitmap)
 Obtains the guest screen bitmap parameters. More...
 
void notifyScaleFactorChange (in unsigned long screenId, in unsigned long u32ScaleFactorWMultiplied, in unsigned long u32ScaleFactorHMultiplied)
 Notify OpenGL HGCM host service about graphics content scaling factor change. More...
 
void notifyHiDPIOutputPolicyChange (in boolean fUnscaledHiDPI)
 Notify OpenGL HGCM host service about HiDPI monitor scaling policy change. More...
 

Detailed Description

The IDisplay interface represents the virtual machine's display.

The object implementing this interface is contained in each IConsole::display attribute and represents the visual output of the virtual machine.

The virtual display supports pluggable output targets represented by the IFramebuffer interface. Examples of the output target are a window on the host computer or an RDP session's display on a remote computer.

Interface ID:
{7303A66D-433B-25A4-F9A8-FCADF87E0C2A}

Member Function Documentation

void IDisplay::getScreenResolution ( in unsigned long  screenId,
out unsigned long  width,
out unsigned long  height,
out unsigned long  bitsPerPixel,
out long  xOrigin,
out long  yOrigin,
out GuestMonitorStatus  guestMonitorStatus 
)

Queries certain attributes such as display width, height, color depth and the X and Y origin for a given guest screen.

The parameters xOrigin and yOrigin return the X and Y coordinates of the framebuffer's origin.

All return parameters are optional.

void IDisplay::attachFramebuffer ( in unsigned long  screenId,
in IFramebuffer  framebuffer,
[retval] out wstringUUID  id 
)

Sets the graphics update target for a screen.

void IDisplay::detachFramebuffer ( in unsigned long  screenId,
in wstringUUID  id 
)

Removes the graphics updates target for a screen.

void IDisplay::queryFramebuffer ( in unsigned long  screenId,
[retval] out IFramebuffer  framebuffer 
)

Queries the graphics updates targets for a screen.

void IDisplay::setVideoModeHint ( in unsigned long  display,
in boolean  enabled,
in boolean  changeOrigin,
in long  originX,
in long  originY,
in unsigned long  width,
in unsigned long  height,
in unsigned long  bitsPerPixel 
)

Asks VirtualBox to request the given video mode from the guest.

This is just a hint and it cannot be guaranteed that the requested resolution will be used. Guest Additions are required for the request to be seen by guests. The caller should issue the request and wait for a resolution change and after a timeout retry.

Specifying 0 for either width, height or bitsPerPixel parameters means that the corresponding values should be taken from the current video mode (i.e. left unchanged).

If the guest OS supports multi-monitor configuration then the display parameter specifies the number of the guest display to send the hint to: 0 is the primary display, 1 is the first secondary and so on. If the multi-monitor configuration is not supported, display must be 0.

Parameters
displayThe number of the guest display to send the hint to.
enabledTrue, if this guest screen is enabled, False otherwise.
changeOriginTrue, if the origin of the guest screen should be changed, False otherwise.
originXThe X origin of the guest screen.
originYThe Y origin of the guest screen.
Expected result codes:
E_INVALIDARG The display is not associated with any monitor.
void IDisplay::setSeamlessMode ( in boolean  enabled)

Enables or disables seamless guest display rendering (seamless desktop integration) mode.

Note
Calling this method has no effect if IGuest::getFacilityStatus with facility Seamless does not return Active.
void IDisplay::takeScreenShot ( in unsigned long  screenId,
in octetPtr  address,
in unsigned long  width,
in unsigned long  height,
in BitmapFormat  bitmapFormat 
)

Takes a screen shot of the requested size and format and copies it to the buffer allocated by the caller and pointed to by address.

The buffer size must be enough for a 32 bits per pixel bitmap, i.e. width * height * 4 bytes.

Note
This API can be used only locally by a VM process through the COM/XPCOM C++ API as it requires pointer support. It is not available for scripting languages, Java or any webservice clients. Unless you are writing a new VM frontend use takeScreenShotToArray.
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 IDisplay::takeScreenShotToArray ( in unsigned long  screenId,
in unsigned long  width,
in unsigned long  height,
in BitmapFormat  bitmapFormat,
[retval] out octet[]  screenData 
)

Takes a guest screen shot of the requested size and format and returns it as an array of bytes.

Parameters
screenIdThe guest monitor to take screenshot from.
widthDesired image width.
heightDesired image height.
bitmapFormatThe requested format.
screenDataArray with resulting screen data.
void IDisplay::drawToScreen ( in unsigned long  screenId,
in octetPtr  address,
in unsigned long  x,
in unsigned long  y,
in unsigned long  width,
in unsigned long  height 
)

Draws a 32-bpp image of the specified size from the given buffer to the given point on the VM display.

Parameters
screenIdMonitor to take the screenshot from.
addressAddress to store the screenshot to
xRelative to the screen top left corner.
yRelative to the screen top left corner.
widthDesired image width.
heightDesired image height.
Expected result codes:
E_NOTIMPL Feature not implemented.
VBOX_E_IPRT_ERROR Could not draw to screen.
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 IDisplay::invalidateAndUpdate ( )

Does a full invalidation of the VM display and instructs the VM to update it.

Expected result codes:
VBOX_E_IPRT_ERROR Could not invalidate and update screen.
void IDisplay::invalidateAndUpdateScreen ( in unsigned long  screenId)

Redraw the specified VM screen.

Parameters
screenIdThe guest screen to redraw.
void IDisplay::completeVHWACommand ( in octetPtr  command)

Signals that the Video HW Acceleration command has completed.

Parameters
commandPointer to VBOXVHWACMD containing the completed command.
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 IDisplay::viewportChanged ( in unsigned long  screenId,
in unsigned long  x,
in unsigned long  y,
in unsigned long  width,
in unsigned long  height 
)

Signals that framebuffer window viewport has changed.

Parameters
screenIdMonitor to take the screenshot from.
xFramebuffer x offset.
yFramebuffer y offset.
widthViewport width.
heightViewport height.
Expected result codes:
E_INVALIDARG The specified viewport data is invalid.
void IDisplay::querySourceBitmap ( in unsigned long  screenId,
out IDisplaySourceBitmap  displaySourceBitmap 
)

Obtains the guest screen bitmap parameters.

void IDisplay::notifyScaleFactorChange ( in unsigned long  screenId,
in unsigned long  u32ScaleFactorWMultiplied,
in unsigned long  u32ScaleFactorHMultiplied 
)

Notify OpenGL HGCM host service about graphics content scaling factor change.

void IDisplay::notifyHiDPIOutputPolicyChange ( in boolean  fUnscaledHiDPI)

Notify OpenGL HGCM host service about HiDPI monitor scaling policy change.