These two files describe some of the behavior and requirements for virt-viewer in fullscreen multimonitor mode --- I've had these two documents lying around on my computer that I created when working on the fullscreen multimonitor functionality. I thought it might be useful to keep them in the repository to describe the expected behavior of these features since it's not always obvious. docs/multimonitor-fullscreen-settings | 141 ++++++++++++++++++++++++++++++++++ docs/multimonitor-requirements | 98 +++++++++++++++++++++++ 2 files changed, 239 insertions(+) create mode 100644 docs/multimonitor-fullscreen-settings create mode 100644 docs/multimonitor-requirements diff --git a/docs/multimonitor-fullscreen-settings b/docs/multimonitor-fullscreen-settings new file mode 100644 index 0000000..1b6d98e --- /dev/null +++ b/docs/multimonitor-fullscreen-settings @@ -0,0 +1,141 @@ +================================================================= +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. When connecting to guest 6485b... we will enable displays 1 +and 3 on the guest, and assign them to monitors 1 and 2 +(respectively) on the client. Guest display 2 will be disabled. + + +================================================================= +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. + diff --git a/docs/multimonitor-requirements b/docs/multimonitor-requirements new file mode 100644 index 0000000..8be3f72 --- /dev/null +++ b/docs/multimonitor-requirements @@ -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. Displays that are larger than client monitors should be ??? + - should we zoom them out to fit? + 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.) -- 2.1.0 _______________________________________________ virt-tools-list mailing list virt-tools-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/virt-tools-list
