compositeproto.txt

   1                          Composite Extension
   2                              Version 0.4
   3                               2007-7-3
   4                             Keith Packard
   5                           keithp@keithp.com
   6                             Deron Johnson
   7                         deron.johnson@sun.com
   8
   9 1. Introduction
  10
  11 Many user interface operations would benefit from having pixel contents of
  12 window hierarchies available without respect to sibling and antecedent
  13 clipping. In addition, placing control over the composition of these pixel
  14 contents into a final screen image in an external application will enable
  15 a flexible system for dynamic application content presentation.
  16
  17 2. Acknowledgements
  18
  19 This small extension has been brewing for several years, contributors to
  20 both early prototypes and the final design include:
  21
  22  +      Bill Haneman for motivating the ability to magnify occluded windows
  23         with his work on accessibility
  24
  25  +      Carsten Haitzler for Enlightenment, the original eye-candy window
  26         manager which demonstrated that clever hacks are an awfully
  27         close substitute for changes in the underlying system.
  28
  29  +      Jim Gettys for key insights into the relationship between damage
  30         events and per-window pixmap usage
  31
  32  +      Mike Harris and Owen Taylor for figuring out what to call it.
  33
  34  +      Deron Johnson for the Looking Glass implementation and
  35         a prototype of the coordinate transformation mechanism.
  36
  37  +      Ryan Lortie for helping figure out reasonable parent clipping
  38         semantics in the presense of manual redirected children.
  39
  40 3. Architecture
  41
  42 The composite extension provides three related mechanisms:
  43
  44  1.     Per-hierarchy storage. The rendering of an entire hierarchy of windows
  45         is redirected to off-screen storage. The pixels of that hierarchy
  46         are available whenever it is viewable. Storage is automatically
  47         reallocated when the top level window changes size. Contents beyond
  48         the geometry of the top window are not preserved.
  49
  50  2.     Automatic shadow update. When a hierarchy is rendered off-screen,
  51         the X server provides an automatic mechanism for presenting those
  52         contents within the parent window. The implementation is free to
  53         make this update lag behind actual rendering operations by an
  54         unspecified amount of time. This automatic update mechanism may
  55         be disabled so that the parent window contents can be completely
  56         determined by an external application.
  57
  58  3.     External parent - child pointer coordinate transformation.
  59         When a hierarchy is under manual compositing, the relationship
  60         of coordinates within the parent to those in the child may
  61         not be known within the X server. This mechanism provides
  62         for redirection of these transformations through a client.
  63
  64 Per-hierarchy storage may be created for individual windows or for all
  65 children of a window. Manual shadow update may be selected by only a single
  66 application for each window; manual update may also be selected on a
  67 per-window basis or for each child of a window. Detecting when to update
  68 may be done with the Damage extension.
  69
  70 The off-screen storage includes the window contents, its borders and the
  71 contents of all descendants.
  72
  73 3.1 NameWindowPixmap
  74
  75 Version 0.2 of the protocol introduces a mechanism for associating an XID
  76 with the off-screen pixmap used to store these contents. This can be used
  77 to hold onto window contents after the window is unmapped (and hence animate
  78 it's disappearance), and also to access the border of the window, which is
  79 not reachable through the Window ID itself. A new pixmap is created each
  80 time the window is mapped or resized; as these events are nicely signalled
  81 with existing events, no additional notification is needed. The old pixmap
  82 will remain allocated as long as the Pixmap ID is left valid, it is
  83 important that the client use the FreePixmap request when it is done with
  84 the contents and to create a new name for the newly allocated pixmap.
  85
  86 In automatic update mode, the X server is itself responsible for presenting
  87 the child window contents within the parent. It seems reasonable, then, for
  88 rendering to the parent window to be clipped so as not to interfere with any
  89 child window content. In an environment with a mixure of manual and
  90 automatic updating windows, rendering to the parent in the area nominally
  91 occupied by a manual update window should be able to affect parent pixel
  92 values in those areas, but such rendering should be clipped to automatic
  93 update windows, and presumably to other manual update windows managed by
  94 other applications. In any of these cases, it should be easy to ensure that
  95 rendering has no effect on any non-redirected windows.
  96
  97 Instead of attempting to define new clipping modes for rendering, the
  98 Composite extension instead defines ClipByChildren rendering to the parent
  99 to exclude regions occupied by redirected windows (either automatic or
 100 manual). The CreateRegionFromBorderClip request can be used along with
 101 IncludeInferiors clipping modes to restrict manual shadow updates to the
 102 apporpriate region of the screen. Bracketing operations with
 103 GrabServer/UngrabServer will permit atomic sequences that can update the
 104 screen without artifact. As all of these operations are asynchronous,
 105 network latency should not adversely affect update latency.
 106
 107 3.2 Composite Overlay Window
 108
 109 Version 0.3 of the protocol adds the Composite Overlay Window, which
 110 provides compositing managers with a surface on which to draw without
 111 interference. This window is always above normal windows and is always
 112 below the screen saver window. It is an InputOutput window whose width
 113 and height are the screen dimensions. Its visual is the root visual
 114 and its border width is zero.  Attempts to redirect it using the
 115 composite extension are ignored.  This window does not appear in the
 116 reply of the QueryTree request. It is also an override redirect window.
 117 These last two features make it invisible to window managers and other X11
 118 clients. The only way to access the XID of this window is via the
 119 CompositeGetOverlayWindow request. Initially, the Composite Overlay
 120 Window is unmapped.
 121
 122 CompositeGetOverlayWindow returns the XID of the Composite Overlay
 123 Window. If the window has not yet been mapped, it is mapped by this
 124 request. When all clients who have called this request have terminated
 125 their X11 connections the window is unmapped.
 126
 127 Composite managers may render directly to the Composite Overlay
 128 Window, or they may reparent other windows to be children of this
 129 window and render to these. Multiple clients may render to the
 130 Composite Overlay Window, create child windows of it, reshape it, and
 131 redefine its input region, but the specific arbitration rules followed
 132 by these clients is not defined by this specification; these policies
 133 should be defined by the clients themselves.
 134
 135 3.3 Clipping semantics redefined
 136
 137 Version 0.4 of the protocol changes the semantics of clipping in the
 138 presense of manual redirect children. In version 0.3, a parent was always
 139 clipped to child windows, independent of the kind of redirection going on.
 140 With version 0.4, the parent is no longer clipped to child windows which are
 141 manually redirected. This means the parent can draw in the child region without using
 142 IncludeInferiors mode, and (perhaps more importantly), it will receive
 143 expose events in those regions caused by other actions. This new behaviour
 144 is not selectable.
 145
 146 4. Errors
 147
 148 The composite extension does not define any new errors.
 149
 150 5. Types
 151
 152         UPDATETYPE      { Automatic, Manual }
 153
 154         CompositeCoordinate
 155                 child:                  Window
 156                 x, y:                   CARD16
 157
 158 7. Extension Initialization
 159
 160 The client must negotiate the version of the extension before executing
 161 extension requests. Otherwise, the server will return BadRequest for any
 162 operations other than QueryVersion.
 163
 164     QueryVersion
 165
 166                 client-major-version:           CARD32
 167                 client-minor-version:           CARD32
 168
 169                 ->
 170
 171                 major-version:                  CARD32
 172                 minor-version:                  CARD32
 173
 174         The client sends the highest supported version to the server and
 175         the server sends the highest version it supports, but no higher than
 176         the requested version. Major versions changes can introduce
 177         incompatibilities in existing functionality, minor version
 178         changes introduce only backward compatible changes. It is
 179         the client's responsibility to ensure that the server supports
 180         a version which is compatible with its expectations. Servers
 181         are encouraged to support multiple versions of the extension.
 182
 183 8. Hierarchy Redirection
 184
 185     RedirectWindow
 186
 187                 window:                         Window
 188                 update:                         UPDATETYPE
 189
 190                 errors: Window, Access, Match
 191
 192         The hierarchy starting at 'window' is directed to off-screen
 193         storage. 'update' specifies whether the contents are mirrored to
 194         the parent window automatically or not. Only one client may specify
 195         an update type of Manual, another attempt will result in an
 196         Access error. When all clients enabling redirection terminate,
 197         the redirection will automatically be disabled.
 198
 199         The root window may not be redirected. Doing so results in a Match
 200         error.
 201
 202     RedirectSubwindows
 203
 204                 window:                         Window
 205                 update                          UPDATETYPE
 206
 207                 errors: Window, Access
 208
 209         Hierarchies starting at all current and future children of window
 210         will be redirected as in RedirectWindow. If update is Manual,
 211         then painting of the window background during window manipulation
 212         and ClearArea requests is inhibited.
 213
 214     UnredirectWindow:
 215
 216                 window:                         Window
 217
 218                 errors: Window, Value
 219
 220         Redirection of the specified window will be terminated. If
 221         the specified window was not selected for redirection by the
 222         current client, a 'Value' error results.
 223
 224     UnredirectWindows:
 225
 226                 window:                         Window
 227
 228                 errors: Window, Value
 229
 230         Redirection of all children of window will be terminated. If
 231         the specified window was not selected for sub-redirection by the
 232         current client, a 'Value' error results.
 233
 234 9. Clip lists
 235
 236     CreateRegionFromBorderClip
 237
 238                 region:                         Region
 239                 window:                         Window
 240
 241                 errors: Window, IDChoice
 242
 243         This request creates a region containing the "usual" border clip
 244         value; that is the area of the window clipped against siblings and
 245         the parent. This region can be used to restrict rendering to
 246         suitable areas while updating only a single window. The region
 247         is copied at the moment the request is executed; future changes
 248         to the window hierarchy will not be reflected in this region.
 249
 250 10. Associating a Pixmap ID with the off-screen storage (0.2 and later)
 251
 252     NameWindowPixmap
 253
 254                 window:                         Window
 255                 pixmap:                         Pixmap
 256
 257                 errors: Window, Match, IDChoice
 258
 259         This request makes 'pixmap' a reference to the off-screen storage
 260         for 'window'. This pixmap will remain allocated until freed, even
 261         if 'window' is unmapped, reconfigured or destroyed. However,
 262         'window' will get a new pixmap allocated each time it is
 263         mapped or resized, so this request will need to be reinvoked for
 264         the client to continue to refer to the storage holding the current
 265         window contents. Generates a 'Match' error if 'window' is not
 266         redirected or is not visible.
 267
 268 11. Composite Overlay Window (0.3 and later)
 269
 270     CompositeGetOverlayWindow
 271
 272                 window:                         Window
 273
 274                 ->
 275
 276                 overlayWin:                     Window
 277
 278     This request returns the XID of the Composite Overlay Window for
 279     the screen specified by the argument 'window'. This request
 280     indicates that the client wishes to use the Composite Overlay
 281     Window of this screen. If this Composite Overlay Window has not
 282     yet been mapped, it is mapped by this request.
 283
 284     The Composite Overlay Window for a particular screen will be
 285     unmapped when all clients who have invoked this request have
 286     also invoked CompositeReleaseOverlayWindow for that screen. Also,
 287     CompositeReleaseOverlayWindow for a screen will be implicitly
 288     called when a client using the Composite Overlay Window on that
 289     screen terminates its X11 connection.
 290
 291
 292     CompositeReleaseOverlayWindow
 293
 294                 window:                         Window
 295
 296     This request specifies that the client is no longer using the
 297     Composite Overlay Window on the screen specified by the
 298     argument 'window'. A screen's Composite Overlay Window is
 299     unmapped when there are no longer any clients using it.
 300
 301 12. External coordinate transformation (0.4 and later)
 302
 303     RedirectCoordinate
 304
 305                 window:                         Window
 306                 redirect:                       BOOL
 307
 308                 errors: Window, Access
 309
 310         If 'redirect' is TRUE, the requesting client is placed in charge of
 311         coordinate transformations between 'window' and its children. If
 312         'redirect' is FALSE, any such redirection is disabled. Any
 313         transformations needed by the server will be delivered to the
 314         requesting client in TransformCoordinateNotify events and the
 315         requesting client must reply with matching TransformCoordinate
 316         requests for the server to continue with the operation.
 317
 318         Generates an 'Access' error if another client has
 319         redirected coordinates for 'window'.
 320
 321     TransformCoordinate
 322
 323                 window:                         Window
 324                 serialNumber:                   CARD32
 325                 x, y:                           INT16
 326                 coordinates:                    LISTofCompositeCoordinate
 327
 328         This provides the transformation data needed by the server for a
 329         single TransformCoordinateNotify event. 'serialNumber' must match
 330         the serial number delivered in the event. 'x' and 'y' represent the
 331         coordinate from the event relative to the 'window'. 'coordinates'
 332         represent the coordinate from the event relative to each child
 333         listed. Any children not listed in 'coordinates' are given the
 334         default transformation using the child window position within the
 335         parent as a simple translation.
 336
 337         The result of this is that any pointer data seen by means of
 338         the protocol will appear to reflect the transformation
 339         performed by this request.