xglcomp

annotate doc/compositeproto.txt @ 15:6726f29ebbb8

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