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.
void	attachFramebuffer (in unsigned long screenId, in IFramebuffer framebuffer, [retval] out wstringUUID id)
	Sets the graphics update target for a screen.
void	detachFramebuffer (in unsigned long screenId, in wstringUUID id)
	Removes the graphics updates target for a screen.
void	queryFramebuffer (in unsigned long screenId, [retval] out IFramebuffer framebuffer)
	Queries the graphics updates targets for a screen.
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, in boolean notify)
	Changes the monitor information reported by a given output of the guest graphics device.
void	getVideoModeHint (in unsigned long display, out boolean enabled, out boolean changeOrigin, out long originX, out long originY, out unsigned long width, out unsigned long height, out unsigned long bitsPerPixel)
	Queries the monitor information for a given guest output.
void	setSeamlessMode (in boolean enabled)
	Enables or disables seamless guest display rendering (seamless desktop integration) mode.
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.
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.
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.
void	invalidateAndUpdate ()
	Does a full invalidation of the VM display and instructs the VM to update it.
void	invalidateAndUpdateScreen (in unsigned long screenId)
	Redraw the specified VM screen.
void	completeVHWACommand (in octetPtr command)
	Signals that the Video HW Acceleration command has completed.
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.
void	querySourceBitmap (in unsigned long screenId, out IDisplaySourceBitmap displaySourceBitmap)
	Obtains the guest screen bitmap parameters.
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.
void	notifyHiDPIOutputPolicyChange (in boolean fUnscaledHiDPI)
	Notify OpenGL HGCM host service about HiDPI monitor scaling policy change.
void	setScreenLayout (in ScreenLayoutMode screenLayoutMode, in IGuestScreenInfo[] guestScreenInfo)
	Set video modes for the guest screens.
void	detachScreens (in long[] screenIds)
	Unplugs monitors from the virtual graphics card.
void	createGuestScreenInfo (in unsigned long display, in GuestMonitorStatus status, in boolean primary, in boolean changeOrigin, in long originX, in long originY, in unsigned long width, in unsigned long height, in unsigned long bitsPerPixel, [retval] out IGuestScreenInfo guestScreenInfo)
	Make a IGuestScreenInfo object with the provided parameters.

Public Attributes
readonly attribute IGuestScreenInfo[]	guestScreenLayout
	Layout of the guest screens.

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:

{4680B2DE-8690-11E9-B83D-5719E53CF1DE}

Member Function Documentation

getScreenResolution()

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.

attachFramebuffer()

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

Sets the graphics update target for a screen.

detachFramebuffer()

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

Removes the graphics updates target for a screen.

queryFramebuffer()

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

Queries the graphics updates targets for a screen.

setVideoModeHint()

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,
		in boolean	notify
	)

Changes the monitor information reported by a given output of the guest graphics device.

This information can be read by the guest if suitable drivers and driver tools are available, including but not limited to those in the Guest Additions. The guest will receive monitor hotplug notification when the monitor information is changed, and the information itself will be available to the guest until the next change. The information should not be resent if the guest does not resize in response. The guest might have chosen to ignore the change, or the resize might happen later when a suitable driver is started.

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).

Todo:

Rename this to setMonitorInfo for 7.0.

Parameters

display	The number of the guest output to change.
enabled	True if a monitor is connected, False otherwise.
changeOrigin	True, if the position of the guest screen is specified, False otherwise.
originX	The X origin of the guest screen.
originY	The Y origin of the guest screen.
width	The width of the guest screen.
height	The height of the guest screen.
bitsPerPixel	The number of bits per pixel of the guest screen.
notify	Whether the guest should be notified of the change. Normally this is wished, but it might not be when re-setting monitor information from the last session (no hotplug happened, as it is still the same virtual monitor). Might also be useful if several monitors are to be changed at once, but this would not reflect physical hardware well, and we also have setScreenLayout for that.

Expected result codes:

E_INVALIDARG

The display value is higher then the number of outputs.

getVideoModeHint()

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

Queries the monitor information for a given guest output.

See setVideoModeHint. If no monitor information has been set yet by a front-end the preferred mode values returned will be zero.

Todo:

Rename this to getMonitorInfo for 7.0.

Parameters

display	The number of the guest output to query.
enabled	True if a monitor is connected, False otherwise.
changeOrigin	True, if the position of the guest screen was specified, False otherwise.
originX	The X origin of the guest screen.
originY	The Y origin of the guest screen.
width	The width of the monitor preferred mode.
height	The height of the monitor preferred mode.
bitsPerPixel	The number of bits per pixel of the monitor preferred mode.

Expected result codes:

E_INVALIDARG

The display value is higher than the number of outputs.

setSeamlessMode()

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.

takeScreenShot()

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.

takeScreenShotToArray()

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

screenId	The guest monitor to take screenshot from.
width	Desired image width.
height	Desired image height.
bitmapFormat	The requested format.
screenData	Array with resulting screen data.

drawToScreen()

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

screenId	Monitor to take the screenshot from.
address	Address to store the screenshot to
x	Relative to the screen top left corner.
y	Relative to the screen top left corner.
width	Desired image width.
height	Desired 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.

invalidateAndUpdate()

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.

invalidateAndUpdateScreen()

void IDisplay::invalidateAndUpdateScreen

(

in unsigned long

screenId

)

Redraw the specified VM screen.

Parameters

screenId

The guest screen to redraw.

completeVHWACommand()

void IDisplay::completeVHWACommand

(

in octetPtr

command

)

Signals that the Video HW Acceleration command has completed.

Parameters

command

Pointer 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.

viewportChanged()

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

screenId	Monitor to take the screenshot from.
x	Framebuffer x offset.
y	Framebuffer y offset.
width	Viewport width.
height	Viewport height.

Expected result codes:

E_INVALIDARG

The specified viewport data is invalid.

querySourceBitmap()

void IDisplay::querySourceBitmap	(	in unsigned long	screenId,
		out IDisplaySourceBitmap	displaySourceBitmap
	)

Obtains the guest screen bitmap parameters.

notifyScaleFactorChange()

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.

notifyHiDPIOutputPolicyChange()

void IDisplay::notifyHiDPIOutputPolicyChange

(

in boolean

fUnscaledHiDPI

)

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

setScreenLayout()

void IDisplay::setScreenLayout	(	in ScreenLayoutMode	screenLayoutMode,
		in IGuestScreenInfo[]	guestScreenInfo
	)

Set video modes for the guest screens.

detachScreens()

void IDisplay::detachScreens

(

in long[]

screenIds

)

Unplugs monitors from the virtual graphics card.

createGuestScreenInfo()

void IDisplay::createGuestScreenInfo	(	in unsigned long	display,
		in GuestMonitorStatus	status,
		in boolean	primary,
		in boolean	changeOrigin,
		in long	originX,
		in long	originY,
		in unsigned long	width,
		in unsigned long	height,
		in unsigned long	bitsPerPixel,
		[retval] out IGuestScreenInfo	guestScreenInfo
	)

Make a IGuestScreenInfo object with the provided parameters.

Parameters

display	The number of the guest display.
status	True, if this guest screen is enabled, False otherwise.
primary	Whether this guest monitor must be primary.
changeOrigin	True, if the origin of the guest screen should be changed, False otherwise.
originX	The X origin of the guest screen.
originY	The Y origin of the guest screen.
width	The width of the guest screen.
height	The height of the guest screen.
bitsPerPixel	The number of bits per pixel of the guest screen.
guestScreenInfo	The created object.

Member Data Documentation

guestScreenLayout

readonly attribute IGuestScreenInfo [] IDisplay::guestScreenLayout

Layout of the guest screens.