1 files changed, 27 insertions, 0 deletions
diff --git a/doc/technical/Resizing.wiki b/doc/technical/Resizing.wiki
new file mode 100644
index 00000000..b6245ba3
--- /dev/null
+++ b/doc/technical/Resizing.wiki
@@ -0,0 +1,27 @@
+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 =
+
+In normal use, with the standard graphical user interface and with Guest Additions installed, !VirtualBox resizes guest desktops to match whenever the host window is resized.  This document describes the way the mechanism is supposed to - and usually does - work.  It also points out the tricky parts which might potentially fail.
+
+== 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 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.
+
+== Resizing triggered by the host ==
+
+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 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 ==
+=== Windows guests ===
+ * VBoxVideo: the main graphics driver loaded into the kernel.  It can tell how many screens (that is, screen connectors) the guest currently supports, and can enable and disable them as well as setting resolutions to them.  It reports this information to Windows on the guest.  It can not receive information from the host about screen changes (mode hints, monitor unplug or hotplug) itself, but provides an interface for a user-space tool which can to provide that information.  It remembers information received in the Windows registry and simply assumes when it loads that the configuration has not changed since it was last used.
+ * VBoxTray: a user-space daemon which is loaded when a user logs into Windows on the guest and runs as part of that session.  It can receive screen change information from the host and forward it to VBoxVideo.  It also handles seamless mode and other unrelated guest functionality.
+
+=== X.Org/Wayland guests ===
+ * vboxvideo.ko: the main graphics driver loaded into the kernel, currently Linux-only (3.11 and later).  It is known to be supported by X.Org Server 1.17 and later and by GNOME Shell/Wayland as of at least Fedora 25.  It can receive information from the host about screen changes (mode hints, monitor unplug or hotplug) itself, though it depends on user-space to handle that.  All half-recent GNOME Shell versions (X.Org and Wayland), Ubuntu Unity versions and KDE versions do that.
+ * VBoxClient: a user-space daemon which is loaded when a user logs into X.Org on the guest.  It is loaded by the desktop environment and works with most known ones.  For desktop environments which cannot handle screen changes themselves it does that for them (it waits two seconds before responding to the change to give the environment a chance to respond itself, rather than trying to guess which can and which can't).  It cannot do this before log-in of course.  It also handles seamless mode and other unrelated guest functionality.
+ * vboxvideo_drv.so: the main graphics driver, but a different version which runs inside X.Org/XFree86 in user-space.  It cannot co-exist with vboxvideo.ko, but does roughly the same job.  It is supported up to X.Org Server 1.18.  So X.Org 1.19 and later cannot be used with Linux 3.10 and earlier except with fall-back graphics.  This is not expected to be a problem.