mirror of
https://gitlab.uni-freiburg.de/opensourcevdi/virt-viewer
synced 2026-01-03 23:49:04 +00:00
Add some multimonitor documentation
These two files describe some of the behavior and requirements for virt-viewer in fullscreen multimonitor mode
This commit is contained in:
Jonathon Jongsma
parent
fdf55b6ce3
commit
428c3e3fdb
140
docs/multimonitor-fullscreen-settings
Normal file
140
docs/multimonitor-fullscreen-settings
Normal file
@ -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.
|
||||
|
||||
98
docs/multimonitor-requirements
Normal file
98
docs/multimonitor-requirements
Normal file
@ -0,0 +1,98 @@
|
||||
Fullscreen Startup Mode
|
||||
-----------------------
|
||||
A. Default fullscreen behavior
|
||||
Assume:
|
||||
NG = number of displays supported by the guest
|
||||
NC = number of monitors on the client
|
||||
N = the lesser of NG and NC
|
||||
A1. at startup, enable N displays on the guest
|
||||
A2. if N == NC, map guest display X to physical monitor X
|
||||
A3. if N < NC, map guest display X to physical monitor X+1 (the primary
|
||||
monitor likely has an application menu, etc, so keep that free for local use)
|
||||
A4. Arrange guest displays in the same geometry as the physical monitors
|
||||
|
||||
B. Custom monitor mapping configuration
|
||||
B1. configuration file is specific to a particular user on a particular client
|
||||
machine. Different users on same machine can use different
|
||||
configurations.
|
||||
B2. configuration only applies to fullscreen startup mode
|
||||
B3. configuration should be simple to edit by hand
|
||||
B4. It must be possible to specify a custom configuration for a specific
|
||||
guest vm
|
||||
B5. guest-specific configuration is identified by GUID
|
||||
B6. It must be possible to specify a fallback configuration that will be used
|
||||
for all guests without an explicit configuration
|
||||
B7. It must be possible to specify how many guest displays to enable
|
||||
B8. It must be possible to specify which guest display to map to which to
|
||||
client monitor
|
||||
B9. configuration format must be flexible and support a wide range of guest
|
||||
and client configurations
|
||||
B10. if the guest-specific configuration is invalid, we will attempt to use
|
||||
the default/fallback configuration
|
||||
B11. if the fallback configuration is invalid, we will revert to default
|
||||
behavior (see A)
|
||||
B12. Configuration must be considered invalid if it is not unambiguous
|
||||
B13. A configuration that doesn't specify any displays will be considered
|
||||
invalid
|
||||
B14. if multiple configurations are given for the same guest, the last one
|
||||
will be used.
|
||||
|
||||
- non-requirements (these are features that were considered but I propose that
|
||||
they are explicitly not supported)
|
||||
- no need to have separate configurations depending on how many guest
|
||||
displays are currently enabled
|
||||
- complicates startup (have to wait to receive display config before
|
||||
setting up anything)
|
||||
- complicates config file format
|
||||
- the number of guest displays may have been set by another user since you
|
||||
last logged in, so it's not clear to me that we want to make
|
||||
configuration decisions based on something you can't control
|
||||
- no need to specify the geometry arrangement of displays
|
||||
- just match the arrangement of the physical monitors that the display
|
||||
will be mapped to
|
||||
- no need to specify different guest configurations based on client
|
||||
configuration (e.g. separate guest configurations for when the client
|
||||
machine has 4 monitors vs when it has 2 monitors)
|
||||
- complicates config file format
|
||||
- possibly unnecessary if we satisfy B9
|
||||
|
||||
- Implications of high-level requirements
|
||||
1. per-guest display mapping will always work with virt-viewer because
|
||||
virt-viewer can get the GUID from libvirt <B5>
|
||||
2. per-guest display mapping may not work with *remote-viewer* in many cases.
|
||||
If you're connecting to a vm on a host that is running an older version
|
||||
of spice-server (e.g. RHEL6), the GUID is not sent over the spice
|
||||
protocol, so remote-viewer doesn't have any way of determining a guest's
|
||||
GUID <B5>
|
||||
|
||||
- Derived requirements
|
||||
C1. Use GKeyFile <B3>
|
||||
C2. need to add a 'Guest Details' dialog to virt-viewer so that the user can
|
||||
determine the GUID of the guest. <B3><B5>
|
||||
C3. if config file specifies more guest displays than can be enabled on the
|
||||
guest, simply ignore (disable) the extra displays <B9>
|
||||
C4. if config file specifies that a display should be mapped to a client
|
||||
monitor that doesn't exist, that display will not be enabled <B9>
|
||||
C5. if config file specifies that a given guest display will map to multiple
|
||||
client monitors, it will be considered invalid <B12>
|
||||
C6. if the config file specifies that multiple guest displays will map to the
|
||||
same client monitor, it will be considered invalid <B12>
|
||||
|
||||
|
||||
Normal (non-fullscreen) Startup Mode
|
||||
------------------------------------
|
||||
D1. Client must not change Guest configuration at startup
|
||||
D2. Client must open a window for every display that is enabled on the guest
|
||||
D3. Client should allow the native window manager to place the display windows
|
||||
at appropriate positions
|
||||
D4. Client will not prevent displays from being larger than client monitors,
|
||||
but the window manager may impose some size restrictions.
|
||||
D5. Toggling fullscreen mode after startup should only affect the window that
|
||||
was acted upon
|
||||
- currently if client is started in fullscreen mode, exiting fullscreen
|
||||
mode for one window will also exit fullscreen mode for all other windows
|
||||
-- that will need to be changed.
|
||||
- (If fullscreen toggle worked at the application level rather than the
|
||||
window level, it's much more difficult to decide what to do if there are
|
||||
more windows open than client monitors. It's easier to leave those sorts
|
||||
of policy decisions to the user.)
|
||||
Loading…
Reference in New Issue
Block a user