Changes between Version 6 and Version 7 of Guest_resizing

Timestamp:: May 30, 2019 2:30:11 PM (6 years ago)
Author:: Michael Thayer
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

Guest_resizing

-              v6
+              v7
 Please feel free to send documentation patches to the vbox-dev [wiki:Mailing_lists mailing list].
+Please feel free to send documentation patches to the vbox-dev [https://www.virtualbox.org/wiki/Mailing_lists mailing list].
 = Mechanics of host-guest dynamic resizing =
 …
 == The guest video device ==
 !VirtualBox virtual machines contain an emulated graphics card which can currently support up to 64 monitor outputs (the actual number is set by the user before starting the machine).  Each output can be set to any resolution which the configured video RAM size will support (potentially using overlapping video RAM areas).  Normally it will be controlled by the Guest Additions video driver, but it can also be controlled by a VGA driver or using the VESA BIOS, which can only set a limit set of the resolutions that the card can handle, and only on the first screen.  When the guest sets a new resolution on a given monitor output the user interface resizes the matching window to fit.  This only happens once for each resolution change.  If it appears to be repeating, the guest has probably got stuck setting and resetting resolutions.
+!VirtualBox virtual machines contain an emulated graphics card which can currently support up to 64 monitor outputs (the actual number is set by the user before starting the machine).  Each output can be set to any resolution which the configured video RAM size will support (potentially using overlapping video RAM areas).  Normally it will be controlled by the Guest Additions video driver or the Linux VMSVGA driver, but it can also be controlled by a VGA driver or using the VESA BIOS, which can only set a limit set of the resolutions that the card can handle, and only on the first screen.  When the guest sets a new resolution on a given monitor output the user interface resizes the matching window to fit.  This only happens once for each resolution change.  If it appears to be repeating, the guest has probably got stuck setting and resetting resolutions.
 == Resize requests from the host ==
+== Resizing triggered by the host ==
 The !VirtualBox graphics card has a mechanism to transmit resize requests from the host to the guest operating system.  Generally the Guest Additions graphics driver tells the guest that a monitor of the given size has been plugged into the matching monitor output.  If automatic resizing is enabled, then when the user directly or indirectly resizes a virtual machine screen window on the host system (an example of indirect resizing would be a window manager adjusting the size) the graphical interface sends one of these "size hints" to the guest.  The expected result is that the guest operating system will almost immediately resize that output to the size requested.  The user interface will see that the new output size matches the window's size and will not attempt to change it.
+Virtual machines typically display into windows on the host computer, so it is convenient if the guest operating system can be told to adjust its display to fit well into the windows.  This is done by simulating monitors with preferred resolutions of the host window sizes, and simulating monitor re-plugs when the host windows are resized.  There are currently two ways that the guest can read the monitor size, depending on its driver and helper set-up.  The VBox(S)VGA device gives the guest the information directly, whereas when the VMSVGA device is in use a helper has to read the monitor information from the so-called VMM (virtual machine monitor) device and tell the driver.  There is no guarantee that the guest will actually use the preferred size, but it usually does.
+In theory the guest could decide to set a slightly different size, perhaps just by one or two pixels, and the host could try to insist on the original one, but in practice this has not been observed.  What is more common is that the guest ignores the request for some reason - for example if the user has accidentally told GNOME Shell in a guest that they only want a certain resolution.  Another known problem is that on older Linux guests without kernel graphics drivers we send an ACPI monitor change notification, which a few older guests interpret as a request to cycle to the next available resolution after the resize has already taken place.  No modern Linux system is known to be affected, and as of X.Org Server 1.19 in the guest we require use of the kernel driver.
+In Linux guests, the VBox(S)VGA drivers generate a random monitor serial number each time the size changes, because those guests remember monitors by serial number and may set a different resolution if a monitor they have seen before is connected.  (There is a good reason for this on a physical computer of course, but we do not want it in our virtual ones.)  The serial number trick does not work with VMSVGA, which can cause resizing to fail.  Deleting the file ~/config/Monitors.xml in the guest helps.  Another known problem is that on older Linux guests without kernel graphics drivers we send an ACPI monitor change notification, which a few older guests interpret as a request to cycle to the next available resolution after the resize has already taken place.  No modern Linux system is known to be affected, and as of X.Org Server 1.19 in the guest we require use of the kernel driver.
+Legacy drivers, including the ones in the BIOS and EFI, are not able to read the preferred size.  That should be fixable, but no one has yet found time to do it.  Once the guest loads a more capable driver it reads the last preferred size requested by the host and adjusts to that (this currently does not work as expected with the Windows drivers, but should be fixed soon).
 == Guest Additions components ==