compositeproto.txt revision ea1d6981
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 91. Introduction 10 11Many user interface operations would benefit from having pixel contents of 12window hierarchies available without respect to sibling and antecedent 13clipping. In addition, placing control over the composition of these pixel 14contents into a final screen image in an external application will enable 15a flexible system for dynamic application content presentation. 16 172. Acknowledgements 18 19This small extension has been brewing for several years, contributors to 20both 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 presence of manual redirected children. 39 403. Architecture 41 42The 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 64Per-hierarchy storage may be created for individual windows or for all 65children of a window. Manual shadow update may be selected by only a single 66application for each window; manual update may also be selected on a 67per-window basis or for each child of a window. Detecting when to update 68may be done with the Damage extension. 69 70The off-screen storage includes the window contents, its borders and the 71contents of all descendants. 72 733.1 NameWindowPixmap 74 75Version 0.2 of the protocol introduces a mechanism for associating an XID 76with the off-screen pixmap used to store these contents. This can be used 77to hold onto window contents after the window is unmapped (and hence animate 78it's disappearance), and also to access the border of the window, which is 79not reachable through the Window ID itself. A new pixmap is created each 80time the window is mapped or resized; as these events are nicely signalled 81with existing events, no additional notification is needed. The old pixmap 82will remain allocated as long as the Pixmap ID is left valid, it is 83important that the client use the FreePixmap request when it is done with 84the contents and to create a new name for the newly allocated pixmap. 85 86In automatic update mode, the X server is itself responsible for presenting 87the child window contents within the parent. It seems reasonable, then, for 88rendering to the parent window to be clipped so as not to interfere with any 89child window content. In an environment with a mixture of manual and 90automatic updating windows, rendering to the parent in the area nominally 91occupied by a manual update window should be able to affect parent pixel 92values in those areas, but such rendering should be clipped to automatic 93update windows, and presumably to other manual update windows managed by 94other applications. In any of these cases, it should be easy to ensure that 95rendering has no effect on any non-redirected windows. 96 97Instead of attempting to define new clipping modes for rendering, the 98Composite extension instead defines ClipByChildren rendering to the parent 99to exclude regions occupied by redirected windows (either automatic or 100manual). The CreateRegionFromBorderClip request can be used along with 101IncludeInferiors clipping modes to restrict manual shadow updates to the 102apporpriate region of the screen. Bracketing operations with 103GrabServer/UngrabServer will permit atomic sequences that can update the 104screen without artifact. As all of these operations are asynchronous, 105network latency should not adversely affect update latency. 106 1073.2 Composite Overlay Window 108 109Version 0.3 of the protocol adds the Composite Overlay Window, which 110provides compositing managers with a surface on which to draw without 111interference. This window is always above normal windows and is always 112below the screen saver window. It is an InputOutput window whose width 113and height are the screen dimensions. Its visual is the root visual 114and its border width is zero. Attempts to redirect it using the 115composite extension are ignored. This window does not appear in the 116reply of the QueryTree request. It is also an override redirect window. 117These last two features make it invisible to window managers and other X11 118clients. The only way to access the XID of this window is via the 119CompositeGetOverlayWindow request. Initially, the Composite Overlay 120Window is unmapped. 121 122CompositeGetOverlayWindow returns the XID of the Composite Overlay 123Window. If the window has not yet been mapped, it is mapped by this 124request. When all clients who have called this request have terminated 125their X11 connections the window is unmapped. 126 127Composite managers may render directly to the Composite Overlay 128Window, or they may reparent other windows to be children of this 129window and render to these. Multiple clients may render to the 130Composite Overlay Window, create child windows of it, reshape it, and 131redefine its input region, but the specific arbitration rules followed 132by these clients is not defined by this specification; these policies 133should be defined by the clients themselves. 134 1353.3 Clipping semantics redefined 136 137Version 0.4 of the protocol changes the semantics of clipping in the 138presence of manual redirect children. In version 0.3, a parent was always 139clipped to child windows, independent of the kind of redirection going on. 140With version 0.4, the parent is no longer clipped to child windows which are 141manually redirected. This means the parent can draw in the child region without using 142IncludeInferiors mode, and (perhaps more importantly), it will receive 143expose events in those regions caused by other actions. This new behaviour 144is not selectable. 145 1464. Errors 147 148The composite extension does not define any new errors. 149 1505. Types 151 152 UPDATETYPE { Automatic, Manual } 153 154 CompositeCoordinate 155 child: Window 156 x, y: CARD16 157 1587. Extension Initialization 159 160The client must negotiate the version of the extension before executing 161extension requests. Otherwise, the server will return BadRequest for any 162operations 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 1838. 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 update: UPDATETYPE 218 219 errors: Window, Value 220 221 Redirection of the specified window will be terminated. If 222 the specified window was not selected for redirection by the 223 current client, or if the update type does not match the 224 current client's previously requested update type, a 'Value' 225 error results. 226 227 UnredirectSubwindows: 228 229 window: Window 230 update: UPDATETYPE 231 232 errors: Window, Value 233 234 Redirection of all children of window will be terminated. If 235 the specified window was not selected for sub-redirection by the 236 current client, or if the update type does not match the 237 current client's previously requested update type, a 'Value' 238 error results. 239 2409. Clip lists 241 242 CreateRegionFromBorderClip 243 244 region: Region 245 window: Window 246 247 errors: Window, IDChoice 248 249 This request creates a region containing the "usual" border clip 250 value; that is the area of the window clipped against siblings and 251 the parent. This region can be used to restrict rendering to 252 suitable areas while updating only a single window. The region 253 is copied at the moment the request is executed; future changes 254 to the window hierarchy will not be reflected in this region. 255 25610. Associating a Pixmap ID with the off-screen storage (0.2 and later) 257 258 NameWindowPixmap 259 260 window: Window 261 pixmap: Pixmap 262 263 errors: Window, Match, IDChoice 264 265 This request makes 'pixmap' a reference to the off-screen storage 266 for 'window'. This pixmap will remain allocated until freed, even 267 if 'window' is unmapped, reconfigured or destroyed. However, 268 'window' will get a new pixmap allocated each time it is 269 mapped or resized, so this request will need to be reinvoked for 270 the client to continue to refer to the storage holding the current 271 window contents. Generates a 'Match' error if 'window' is not 272 redirected or is not visible. 273 27411. Composite Overlay Window (0.3 and later) 275 276 CompositeGetOverlayWindow 277 278 window: Window 279 280 -> 281 282 overlayWin: Window 283 284 This request returns the XID of the Composite Overlay Window for 285 the screen specified by the argument 'window'. This request 286 indicates that the client wishes to use the Composite Overlay 287 Window of this screen. If this Composite Overlay Window has not 288 yet been mapped, it is mapped by this request. 289 290 The Composite Overlay Window for a particular screen will be 291 unmapped when all clients who have invoked this request have 292 also invoked CompositeReleaseOverlayWindow for that screen. Also, 293 CompositeReleaseOverlayWindow for a screen will be implicitly 294 called when a client using the Composite Overlay Window on that 295 screen terminates its X11 connection. 296 297 298 CompositeReleaseOverlayWindow 299 300 window: Window 301 302 This request specifies that the client is no longer using the 303 Composite Overlay Window on the screen specified by the 304 argument 'window'. A screen's Composite Overlay Window is 305 unmapped when there are no longer any clients using it. 306