Proposal for the Composite Overlay Window spec

[Deron Johnson]

Here is my draft proposal for the Composite Overlay Window spec
that was discussed at the Xorg conference. At that time, there
were no objections to my integrating this. Please review and
if you have any objections let me know by this Friday. Otherwise
I will proceed to integrate it.

Addition to Composite Extension (Version TBD):

The Composite Overlay Window provides composite managers with a
surface to draw on without interference. This window is always above
normal windows and is always below the screen saver window. It is an
InputOutput window whose width and height are the screen
dimensions. Its visual is the root visual and its border width is
zero.  Attempts to redirect it using the composite extension are
ignored.  This window does not appear in the reply of the QueryTree
request. It is also an override redirect window. These last two
features make it invisible to window managers and other X11
clients. The only way to access the XID of this window is via the
CompositeGetOverlayWindow request. Initially, the Composite Overlay
Window is unmapped.

CompositeGetOverlayWindow returns the XID of the Composite Overlay
Window. If the window has not yet been mapped, it is mapped by this
request. When all clients who have called this request have terminated
their X11 connections the window is unmapped.

Composite managers may render directly to the Composite Overlay
Window, or they may reparent other windows to be children of this
window and render to these. Multiple clients may render to the
Composite Overlay Window, create child windows of it, reshape it, and
redefine its input region, but the specific arbitration rules followed
by these clients is not defined by this specification; these policies
should be defined by the clients themselves.

CompositeGetOverlayWindow
    window:			Window
==>
    overlayWin:			Window

    This request returns the XID of the Composite Overlay Window for
    the screen specified by the argument 'window'. This request
    indicates that the client wishes to use the Composite Overlay
    Window of this screen. If this Composite Overlay Window has not
    yet been mapped, it is mapped by this request.

    The Composite Overlay Window for a particular screen will be
    unmapped when all clients who have invoked this request have
    also invoked CompositeReleaseOverlayWindow for that screen. Also,
    CompositeReleaseOverlayWindow for a screen will be implicitly
    called when a client using the Composite Overlay Window on that
    screen terminates its X11 connection.

CompositeReleaseOverlayWindow
    window:			Window

    This request specifies that the client is no longer using the
    Composite Overlay Window on the screen specified by the
    argument 'window'. A screen's Composite Overlay Window is
    unmapped when there are no longer any clients using it.