xglcomp
view doc/compositeproto.txt @ 6:3f908f812ec7
added docs
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Fri, 29 Jan 2016 10:23:08 +0200 |
| parents | |
| children |
line source
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
9 1. Introduction
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.
17 2. Acknowledgements
19 This small extension has been brewing for several years, contributors to
20 both early prototypes and the final design include:
22 + Bill Haneman for motivating the ability to magnify occluded windows
23 with his work on accessibility
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.
29 + Jim Gettys for key insights into the relationship between damage
30 events and per-window pixmap usage
32 + Mike Harris and Owen Taylor for figuring out what to call it.
34 + Deron Johnson for the Looking Glass implementation and
35 a prototype of the coordinate transformation mechanism.
37 + Ryan Lortie for helping figure out reasonable parent clipping
38 semantics in the presense of manual redirected children.
40 3. Architecture
42 The composite extension provides three related mechanisms:
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.
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.
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.
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.
70 The off-screen storage includes the window contents, its borders and the
71 contents of all descendants.
73 3.1 NameWindowPixmap
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.
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.
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.
107 3.2 Composite Overlay Window
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.
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.
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.
135 3.3 Clipping semantics redefined
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.
146 4. Errors
148 The composite extension does not define any new errors.
150 5. Types
152 UPDATETYPE { Automatic, Manual }
154 CompositeCoordinate
155 child: Window
156 x, y: CARD16
158 7. Extension Initialization
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.
164 QueryVersion
166 client-major-version: CARD32
167 client-minor-version: CARD32
169 ->
171 major-version: CARD32
172 minor-version: CARD32
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.
183 8. Hierarchy Redirection
185 RedirectWindow
187 window: Window
188 update: UPDATETYPE
190 errors: Window, Access, Match
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.
199 The root window may not be redirected. Doing so results in a Match
200 error.
202 RedirectSubwindows
204 window: Window
205 update UPDATETYPE
207 errors: Window, Access
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.
214 UnredirectWindow:
216 window: Window
218 errors: Window, Value
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.
224 UnredirectWindows:
226 window: Window
228 errors: Window, Value
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.
234 9. Clip lists
236 CreateRegionFromBorderClip
238 region: Region
239 window: Window
241 errors: Window, IDChoice
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.
250 10. Associating a Pixmap ID with the off-screen storage (0.2 and later)
252 NameWindowPixmap
254 window: Window
255 pixmap: Pixmap
257 errors: Window, Match, IDChoice
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.
268 11. Composite Overlay Window (0.3 and later)
270 CompositeGetOverlayWindow
272 window: Window
274 ->
276 overlayWin: Window
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.
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.
292 CompositeReleaseOverlayWindow
294 window: Window
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.
301 12. External coordinate transformation (0.4 and later)
303 RedirectCoordinate
305 window: Window
306 redirect: BOOL
308 errors: Window, Access
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.
318 Generates an 'Access' error if another client has
319 redirected coordinates for 'window'.
321 TransformCoordinate
323 window: Window
324 serialNumber: CARD32
325 x, y: INT16
326 coordinates: LISTofCompositeCoordinate
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.
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.