Add some multimonitor documentation

These two files describe some of the behavior and requirements for
virt-viewer in fullscreen multimonitor mode

1 files changed, 140 insertions, 0 deletions

diff --git a/docs/multimonitor-fullscreen-settings b/docs/multimonitor-fullscreen-settings
new file mode 100644
index 0000000..7ec4432
--- /dev/null
+++ b/docs/multimonitor-fullscreen-settings
@@ -0,0 +1,140 @@
+=================================================================
+File Format
+=================================================================
+
+The configuration file is a GKeyFile format file.  The GUID is
+the 'group' name, and the mapping configuration for the guest is
+specified with a 'monitor-mapping' key. The 'monitor-mapping' key
+is an array of mappings from display ID to monitor ID. Since
+GKeyFile uses ';' as an array separator, we use ':' as the
+mapping separator. Display and monitor IDS both use 1-based
+indices (i.e. the first display is 1, not 0).
+
+So, to map guest display 1 to client monitor 1, use "1:1".  To
+map guest display 1 to client monitor 2 and guest display 2 to
+client monitor 3, use "1:2;2:3".
+
+Fallback configuration is specified in the same manner, but uses
+the group name 'fallback'.
+
+=================================================================
+A. Basic example
+=================================================================
+
+  [6485b20f-e9da-614c-72b0-60a7857e7886]
+  monitor-mapping=1:2
+
+A1. When connecting to guest 6485b... on a client with 2
+monitors, it will enable only guest display #1 and display it on
+monitor #2.
+
+A2. When connecting to guest 6485b... on a client with 1 monitor,
+the "1:2" mapping refers to a non-existant monitor and will thus
+be ignored (C4). Because there are no valid display mappings
+specified, the configuration will be considered invalid (B13).
+The guest will then be displayed according to the default
+behavior (open 1 display on monitor 1)
+
+A3. When connecting to any other guest, it will use default
+behavior (enable 1 display for each monitor and map them N:N)
+
+
+=================================================================
+B. Basic example with fallback
+=================================================================
+
+  [6485b20f-e9da-614c-72b0-60a7857e7886]
+  monitor-mapping=1:2
+  
+  [fallback]
+  monitor-mapping=1:2;2:3;3:4
+
+B1. same as A1
+
+B2. same as A2
+
+B3. When connecting to another guest on a client with 4 monitors:
+it will enable 3 displays and assign them to monitors 2, 3 and 4.
+
+B4. When connecting to another guest on a client with 3 monitors:
+it will enable 2 displays and assign them to monitors 2 and 3
+
+B5. When connecting to another guest on a client with 1 monitor:
+no mappings are valid, so default behavior will be used.
+
+
+=================================================================
+C. Same display referenced multiple times
+=================================================================
+
+  [6485b20f-e9da-614c-72b0-60a7857e7886]
+  monitor-mapping=1:1;1:2
+
+C1. configuration is invalid because it is ambiguous (display 1
+is mapped to both monitor 1 and monitor 2).  Default behavior
+will be used.
+
+
+=================================================================
+D. Same monitor referenced multiple times
+=================================================================
+
+  [6485b20f-e9da-614c-72b0-60a7857e7886]
+  monitor-mapping=1:1;2:1
+
+D1. configuration is invalid because it is ambiguous (both guest
+display 1 and guest display 2 and mapped to monitor 1).  Default
+behavior will be used.
+
+
+=================================================================
+E. Multiple configurations for same GUID
+=================================================================
+
+  [6485b20f-e9da-614c-72b0-60a7857e7886]
+  monitor-mapping=1:1;2:2
+  
+  [6485b20f-e9da-614c-72b0-60a7857e7886]
+  monitor-mapping=1:2;2:3
+
+E1. Since two configurations are given for the same guest, the
+last one will be used. Two guest displays will be enabled and
+will be shown on monitors 2 and 3
+
+
+=================================================================
+F. multiple monitor-mapping keys for same GUID
+=================================================================
+
+  [6485b20f-e9da-614c-72b0-60a7857e7886]
+  monitor-mapping=1:1;2:2
+  monitor-mapping=1:2;2:3
+
+F1. Since two configurations are given for the same guest, the
+last one will be used. Two guest displays will be enabled and
+will be shown on monitors 2 and 3
+
+
+=================================================================
+G. 'sparse' displays
+=================================================================
+
+  [6485b20f-e9da-614c-72b0-60a7857e7886]
+  monitor-mapping=1:1;3:2
+
+G1. configuration is invalid. Enabled guest displays must be
+specified without any gaps between displays.
+
+
+=================================================================
+H. configuration specifies more displays than guest can enable
+=================================================================
+
+  [6485b20f-e9da-614c-72b0-60a7857e7886]
+  monitor-mapping=1:1;2:2;3:3
+
+H1. If guest 6485b... is a windows guest with only 2 display
+devices, we will enable displays 1 and 2 on the guest, and assign
+them to monitors 1 and 2 (respectively) on the client.  Guest
+display 3 will be disabled.
+