Re: Proposing _NET_WM_STATE_FULLSCREEN_EXCLUSIVE

["Ryan C. Gordon" <icculus icculus org>]

> Just following up, since this is (I think) the only outstanding concern
> before I submit a new draft.

We'll talk about this issue more, but for now, I present the second 
draft. I've left this specific concern as a TODO note, so we'll 
accommodate it in a third (and hopefully final!) draft after this one, 
but I'd like to start getting feedback on all the changes in the meantime.

The updated text is pasted into this email. If you want the 
change-by-change revision history, take a look over here...

    http://hg.icculus.org/icculus/wm-fullscreen-spec/shortlog

...we'll move this into freedesktop's wm-spec revision control when 
everyone is generally happy with the language. Here are the significant 
changes since the original draft:

- Changed name to _NET_WM_STATE_FULLSCREEN_RESOLUTION

- Added text to allow this to work with both real physical resolution 
changes and/or a compositor rescaling a backbuffer.

- Added _NET_RESOLUTIONS root window property, to let WM control 
available resolutions and take all need for XRandR out of the app.

- Added an optional _NET_FULLSCREEN_TEMPORARY root window property, so 
apps that are listening for XRandR events outside of the Window Manager 
can decide if this event is a permanent change or not.

- A lot of MUST language became SHOULD or MAY.

- Added a note that the Window Manager SHOULD maintain aspect ratio.

- Places that discussed the window's "current dimensions" now talk about 
the window's size hints.

- Iconification is no longer a hard requirement; WMs can do what makes 
sense for their environment.

- Explicitly note that this hint is used when the window is mapped.

- Corrected various typos and trivial details.

Below is the updated text. I've tried to address all voiced concerns, 
but if I've missed something, please let me know!

Thanks,
--ryan.


This is an addition to the spec for _NET_WM_STATE:
    http://standards.freedesktop.org/wm-spec/1.5/ar01s05.html#id2760470

Rationale:

There are some problems with the current _NET_WM_STATE_FULLSCREEN hint 
that we would like to address.

First, it is not explicit in its instructions to Window Managers; for 
example, we found some Window Managers required the window to be marked 
resizable (Metacity) and others did not (XFCE); it's not clear which is 
correct. It doesn't address virtual desktop size verses physical 
resolution. This proposal tries to be very clear about exactly what 
steps are required.

Second, the window manager needs to be responsible for changing 
resolutions. If an app tries to use XVidMode, the virtual desktop will 
not be resized and _NET_WM_STATE_FULLSCREEN will size the window 
incorrectly. If an app instead tries to use XRandR, the rest of the 
desktop may change irreversibly; icons may move around, other app 
windows may shrink down. Worse still, if an app changes the resolution 
with XVidMode or XRandR and then crashes before cleaning itself up, the 
desktop will remain in the wrong state until the user takes heroic 
measures to fix it. Moving this operation into the Window Manager and 
associating it with a specific window lets the system know that this is 
a temporary state change, instead of two discrete actions that may be 
unrelated, so that it can protect desktop state appropriately. This also 
has the side benefit of centralizing a complex negotiation with X11 
extensions and multiple processes into one place--the Window 
Manager--instead of every application.

Certainly _NET_WM_STATE_FULLSCREEN still has a place; it still makes 
good sense that the example given, a presentation program, use that 
hint. For applications like video games, which need more control over 
window geometry and specific monitor resolutions, a new hint is 
extremely useful.

There are other benefits to moving resolution switches to the window 
manager: the desktop environment may want to offer the user a 
configuration mechanism that limits desired resolutions outside of what 
the X server advertises, and more importantly, they may want to make use 
of compositing to transparently emulate a resolution change--that is, 
scale a smaller backbuffer that matches the requested resolution up to 
the hardware's native resolution. The end result is more centralized 
user preference and desktop environment policy.


Specification:

A Window Manager supporting this specification MUST add 
_NET_WM_STATE_FULLSCREEN_RESOLUTION to the list of atoms reported by the 
_NET_SUPPORTED property.


(Added to the list of Root Window Properties...)

_NET_RESOLUTIONS

_NET_RESOLUTIONS x, y, width, height, CARDINAL[4]/32

This array contains a list of all available resolutions that can be used 
with _NET_WM_STATE_FULLSCREEN_RESOLUTION. It MAY match the physical 
resolutions offered by the hardware, but it also MAY be an arbitrary 
list decided upon by the Window Manager. This property MAY change at any 
time, for example as hardware is connected, detached, or reconfigured. 
The four values in each element of the array comprise the monitor's 
current (x,y) position on the screen, and the dimensions of the given 
resolution.



_NET_FULLSCREEN_TEMPORARY

_NET_FULLSCREEN_TEMPORARY WINDOW[]/32

This array contains a list of all window ids that have temporarily 
changed a monitor's resolution with the 
_NET_WM_STATE_FULLSCREEN_RESOLUTION hint. This array MAY be updated to 
include or remove the window before any resolution change goes into 
effect. The intention is that applications that are listening for XRandR 
events can view this list and decide if they should ignore this 
resolution change.



(Added to the list of _NET_WM_ALLOWED_ACTIONS atoms...)
_NET_WM_ACTION_FULLSCREEN_RESOLUTION, ATOM

_NET_WM_ACTION_FULLSCREEN_RESOLUTION indicates that the window may be 
brought to fullscreen_resolution state, that is, it may use the 
_NET_WM_STATE_FULLSCREEN_RESOLUTION hint.



(Added to the list of _NET_WM_STATE hints...)

In relation to _NET_WM_STATE_FULLSCREEN_RESOLUTION, the Window Manager 
MAY simulate a physical resolution change by instead scaling the 
window's rendering, such as with a compositor, so long as the window is 
rendering into its expected dimensions and the given monitor is 
dedicated to that window.

_NET_WM_STATE_FULLSCREEN_RESOLUTION indicates that, when mapped, the 
Window Manager MUST change the resolution of the window's monitor to one 
that most closely matches the window's size hints. If no available 
resolution matches exactly, the Window Manager MUST select the closest 
available resolution larger than the window's maximum size hint, and 
SHOULD attempt to maintain the appropriate aspect ratio. The Window 
Manager MUST center the window within the new resolution, remove any 
window decorations, maintain its geometry based on its size hints, and 
grant it input focus. If the chosen resolution does not exactly match 
within the window's size hints, the Window Manager MUST obscure the rest 
of the monitor so that the window is the only thing visible. If there is 
no resolution that can completely contain the window's undecorated size 
hints, the Window Manager MUST refuse to allow this hint.

When a window successfully sets or removes this hint, the Window Manager 
MAY update the _NET_FULLSCREEN_TEMPORARY property on the root window 
before changing the resolution, to aid applications that are listening 
for resolution change events and would want to know that this resolution 
change is temporary.

If another window needs the monitor that is currently in use by the 
fullscreen window, the Window Manager MAY revert the resolution change 
and allow other windows access to the given monitor (for example, the 
Window Manager MAY iconify the window). In such a case, the Window 
Manager MUST restore the original resolution change when the monitor 
becomes available again. The Window Manager SHOULD NOT alter desktop 
state (icon positions, geometry of other windows, etc) during resolution 
changes, so that the state will be unchanged when the window ceases to 
be marked as fullscreen.

The _NET_WM_STATE_FULLSCREEN_RESOLUTION and _NET_WM_STATE_FULLSCREEN 
hints SHOULD NOT be used together by a window; in such a case, the 
Window Manager SHOULD reject the _NET_WM_STATE_FULLSCREEN hint.

If more than one window on the same monitor requests the 
_NET_WM_STATE_FULLSCREEN_RESOLUTION hint, the Window Manager SHOULD 
choose an appropriate method to manage their access to the monitor (for 
example, each window could be iconified until it has regained input focus).

For example, a video game would use this hint.


Issues:
- multiple fullscreen windows on different monitors.