compositeproto.txt revision 17ca54c3
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 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 2349. 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 25010. 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 26811. 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