Codebase list virt-viewer / 428c3e3
Add some multimonitor documentation These two files describe some of the behavior and requirements for virt-viewer in fullscreen multimonitor mode Jonathon Jongsma 8 years ago
2 changed file(s) with 238 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
+140
-0
docs/multimonitor-fullscreen-settings less more
0 =================================================================
1 File Format
2 =================================================================
3
4 The configuration file is a GKeyFile format file. The GUID is
5 the 'group' name, and the mapping configuration for the guest is
6 specified with a 'monitor-mapping' key. The 'monitor-mapping' key
7 is an array of mappings from display ID to monitor ID. Since
8 GKeyFile uses ';' as an array separator, we use ':' as the
9 mapping separator. Display and monitor IDS both use 1-based
10 indices (i.e. the first display is 1, not 0).
11
12 So, to map guest display 1 to client monitor 1, use "1:1". To
13 map guest display 1 to client monitor 2 and guest display 2 to
14 client monitor 3, use "1:2;2:3".
15
16 Fallback configuration is specified in the same manner, but uses
17 the group name 'fallback'.
18
19 =================================================================
20 A. Basic example
21 =================================================================
22
23 [6485b20f-e9da-614c-72b0-60a7857e7886]
24 monitor-mapping=1:2
25
26 A1. When connecting to guest 6485b... on a client with 2
27 monitors, it will enable only guest display #1 and display it on
28 monitor #2.
29
30 A2. When connecting to guest 6485b... on a client with 1 monitor,
31 the "1:2" mapping refers to a non-existant monitor and will thus
32 be ignored (C4). Because there are no valid display mappings
33 specified, the configuration will be considered invalid (B13).
34 The guest will then be displayed according to the default
35 behavior (open 1 display on monitor 1)
36
37 A3. When connecting to any other guest, it will use default
38 behavior (enable 1 display for each monitor and map them N:N)
39
40
41 =================================================================
42 B. Basic example with fallback
43 =================================================================
44
45 [6485b20f-e9da-614c-72b0-60a7857e7886]
46 monitor-mapping=1:2
47
48 [fallback]
49 monitor-mapping=1:2;2:3;3:4
50
51 B1. same as A1
52
53 B2. same as A2
54
55 B3. When connecting to another guest on a client with 4 monitors:
56 it will enable 3 displays and assign them to monitors 2, 3 and 4.
57
58 B4. When connecting to another guest on a client with 3 monitors:
59 it will enable 2 displays and assign them to monitors 2 and 3
60
61 B5. When connecting to another guest on a client with 1 monitor:
62 no mappings are valid, so default behavior will be used.
63
64
65 =================================================================
66 C. Same display referenced multiple times
67 =================================================================
68
69 [6485b20f-e9da-614c-72b0-60a7857e7886]
70 monitor-mapping=1:1;1:2
71
72 C1. configuration is invalid because it is ambiguous (display 1
73 is mapped to both monitor 1 and monitor 2). Default behavior
74 will be used.
75
76
77 =================================================================
78 D. Same monitor referenced multiple times
79 =================================================================
80
81 [6485b20f-e9da-614c-72b0-60a7857e7886]
82 monitor-mapping=1:1;2:1
83
84 D1. configuration is invalid because it is ambiguous (both guest
85 display 1 and guest display 2 and mapped to monitor 1). Default
86 behavior will be used.
87
88
89 =================================================================
90 E. Multiple configurations for same GUID
91 =================================================================
92
93 [6485b20f-e9da-614c-72b0-60a7857e7886]
94 monitor-mapping=1:1;2:2
95
96 [6485b20f-e9da-614c-72b0-60a7857e7886]
97 monitor-mapping=1:2;2:3
98
99 E1. Since two configurations are given for the same guest, the
100 last one will be used. Two guest displays will be enabled and
101 will be shown on monitors 2 and 3
102
103
104 =================================================================
105 F. multiple monitor-mapping keys for same GUID
106 =================================================================
107
108 [6485b20f-e9da-614c-72b0-60a7857e7886]
109 monitor-mapping=1:1;2:2
110 monitor-mapping=1:2;2:3
111
112 F1. Since two configurations are given for the same guest, the
113 last one will be used. Two guest displays will be enabled and
114 will be shown on monitors 2 and 3
115
116
117 =================================================================
118 G. 'sparse' displays
119 =================================================================
120
121 [6485b20f-e9da-614c-72b0-60a7857e7886]
122 monitor-mapping=1:1;3:2
123
124 G1. configuration is invalid. Enabled guest displays must be
125 specified without any gaps between displays.
126
127
128 =================================================================
129 H. configuration specifies more displays than guest can enable
130 =================================================================
131
132 [6485b20f-e9da-614c-72b0-60a7857e7886]
133 monitor-mapping=1:1;2:2;3:3
134
135 H1. If guest 6485b... is a windows guest with only 2 display
136 devices, we will enable displays 1 and 2 on the guest, and assign
137 them to monitors 1 and 2 (respectively) on the client. Guest
138 display 3 will be disabled.
139
+98
-0
docs/multimonitor-requirements less more
0 Fullscreen Startup Mode
1 -----------------------
2 A. Default fullscreen behavior
3 Assume:
4 NG = number of displays supported by the guest
5 NC = number of monitors on the client
6 N = the lesser of NG and NC
7 A1. at startup, enable N displays on the guest
8 A2. if N == NC, map guest display X to physical monitor X
9 A3. if N < NC, map guest display X to physical monitor X+1 (the primary
10 monitor likely has an application menu, etc, so keep that free for local use)
11 A4. Arrange guest displays in the same geometry as the physical monitors
12
13 B. Custom monitor mapping configuration
14 B1. configuration file is specific to a particular user on a particular client
15 machine. Different users on same machine can use different
16 configurations.
17 B2. configuration only applies to fullscreen startup mode
18 B3. configuration should be simple to edit by hand
19 B4. It must be possible to specify a custom configuration for a specific
20 guest vm
21 B5. guest-specific configuration is identified by GUID
22 B6. It must be possible to specify a fallback configuration that will be used
23 for all guests without an explicit configuration
24 B7. It must be possible to specify how many guest displays to enable
25 B8. It must be possible to specify which guest display to map to which to
26 client monitor
27 B9. configuration format must be flexible and support a wide range of guest
28 and client configurations
29 B10. if the guest-specific configuration is invalid, we will attempt to use
30 the default/fallback configuration
31 B11. if the fallback configuration is invalid, we will revert to default
32 behavior (see A)
33 B12. Configuration must be considered invalid if it is not unambiguous
34 B13. A configuration that doesn't specify any displays will be considered
35 invalid
36 B14. if multiple configurations are given for the same guest, the last one
37 will be used.
38
39 - non-requirements (these are features that were considered but I propose that
40 they are explicitly not supported)
41 - no need to have separate configurations depending on how many guest
42 displays are currently enabled
43 - complicates startup (have to wait to receive display config before
44 setting up anything)
45 - complicates config file format
46 - the number of guest displays may have been set by another user since you
47 last logged in, so it's not clear to me that we want to make
48 configuration decisions based on something you can't control
49 - no need to specify the geometry arrangement of displays
50 - just match the arrangement of the physical monitors that the display
51 will be mapped to
52 - no need to specify different guest configurations based on client
53 configuration (e.g. separate guest configurations for when the client
54 machine has 4 monitors vs when it has 2 monitors)
55 - complicates config file format
56 - possibly unnecessary if we satisfy B9
57
58 - Implications of high-level requirements
59 1. per-guest display mapping will always work with virt-viewer because
60 virt-viewer can get the GUID from libvirt <B5>
61 2. per-guest display mapping may not work with *remote-viewer* in many cases.
62 If you're connecting to a vm on a host that is running an older version
63 of spice-server (e.g. RHEL6), the GUID is not sent over the spice
64 protocol, so remote-viewer doesn't have any way of determining a guest's
65 GUID <B5>
66
67 - Derived requirements
68 C1. Use GKeyFile <B3>
69 C2. need to add a 'Guest Details' dialog to virt-viewer so that the user can
70 determine the GUID of the guest. <B3><B5>
71 C3. if config file specifies more guest displays than can be enabled on the
72 guest, simply ignore (disable) the extra displays <B9>
73 C4. if config file specifies that a display should be mapped to a client
74 monitor that doesn't exist, that display will not be enabled <B9>
75 C5. if config file specifies that a given guest display will map to multiple
76 client monitors, it will be considered invalid <B12>
77 C6. if the config file specifies that multiple guest displays will map to the
78 same client monitor, it will be considered invalid <B12>
79
80
81 Normal (non-fullscreen) Startup Mode
82 ------------------------------------
83 D1. Client must not change Guest configuration at startup
84 D2. Client must open a window for every display that is enabled on the guest
85 D3. Client should allow the native window manager to place the display windows
86 at appropriate positions
87 D4. Client will not prevent displays from being larger than client monitors,
88 but the window manager may impose some size restrictions.
89 D5. Toggling fullscreen mode after startup should only affect the window that
90 was acted upon
91 - currently if client is started in fullscreen mode, exiting fullscreen
92 mode for one window will also exit fullscreen mode for all other windows
93 -- that will need to be changed.
94 - (If fullscreen toggle worked at the application level rather than the
95 window level, it's much more difficult to decide what to do if there are
96 more windows open than client monitors. It's easier to leave those sorts
97 of policy decisions to the user.)