[virt-tools-list] [PATCH virt-viewer] Add some multimonitor documentation
Jonathon Jongsma
jjongsma at redhat.com
Tue Nov 3 16:49:20 UTC 2015
Ah, thanks for the reminder. Looks like Pavel suggested some changes
and I never got around to making them. Will submit a new version.
On Mon, 2015-10-26 at 13:18 +0100, Fabiano Fidêncio wrote:
> Can we revisit this one?
>
> On Thu, Jun 4, 2015 at 5:26 PM, Jonathon Jongsma <jjongsma at redhat.com
> > 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
> > +=================================================================
> > +
> > + [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 at redhat.com
> > https://www.redhat.com/mailman/listinfo/virt-tools-list
More information about the virt-tools-list
mailing list