| 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.
|
