[virt-tools-list] [PATCH virt-viewer] Add some multimonitor documentation

Pavel Grunt pgrunt at redhat.com
Thu Jun 4 16:23:31 UTC 2015


Hi Jonathon,

thanks for sharing the documents.

On Thu, 2015-06-04 at 10:26 -0500, Jonathon Jongsma wrote:
> 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
> +=================================================================
This is not supported now
> +
> +  [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)

This is not implemented yet, but sounds reasonable.

> +  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?

Let the window manager to take care of this :) 
https://www.redhat.com/archives/virt-tools-list/2015-May/msg00103.html

> +  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.)

ack from me for having docs in the repo.

Pavel




More information about the virt-tools-list mailing list