16
Many user interface operations would benefit from having pixel contents of
17
window hierarchies available without respect to sibling and antecedent
18
clipping. In addition, placing control over the composition of these pixel
19
contents into a final screen image in an external application will enable
20
a flexible system for dynamic application content presentation.
24
This small extension has been brewing for several years, contributors to
25
both early prototypes and the final design include:
27
+ Bill Haneman for motivating the ability to magnify occluded windows
28
with his work on accessibility
30
+ Carsten Haitzler for Enlightenment, the original eye-candy window
31
manager which demonstrated that clever hacks are an awfully
32
close substitute for changes in the underlying system.
34
+ Jim Gettys for key insights into the relationship between damage
35
events and per-window pixmap usage
37
+ Mike Harris and Owen Taylor for figuring out what to call it.
41
The composite extension provides two related mechanisms:
43
1. Per-hierarchy storage. The rendering of an entire hierarchy of windows
44
is redirected to off-screen storage. The pixels of that hierarchy
45
are available whenever it is viewable. Storage is automatically
46
reallocated when the top level window changes size. Contents beyond
47
the geometry of the top window are not preserved.
49
2. Automatic shadow update. When a hierarchy is rendered off-screen,
50
the X server provides an automatic mechanism for presenting those
51
contents within the parent window. The implementation is free to
52
make this update lag behind actual rendering operations by an
53
unspecified amount of time. This automatic update mechanism may
54
be disabled so that the parent window contents can be completely
55
determined by an external application.
57
Per-hierarchy storage may be created for individual windows or for all
58
children of a window. Manual shadow update may be selected by only a single
59
application for each window; manual update may also be selected on a
60
per-window basis or for each child of a window. Detecting when to update
61
may be done with the Damage extension.
63
The off-screen storage includes the window contents, its borders and the
64
contents of all descendants.
66
Version 0.2 of the protocol introduces a mechanism for associating an XID
67
with the off-screen pixmap used to store these contents. This can be used
68
to hold onto window contents after the window is unmapped (and hence animate
69
it's disappearance), and also to access the border of the window, which is
70
not reachable through the Window ID itself. A new pixmap is created each
71
time the window is mapped or resized; as these events are nicely signalled
72
with existing events, no additional notification is needed. The old pixmap
73
will remain allocated as long as the Pixmap ID is left valid, it is
74
important that the client use the FreePixmap request when it is done with
75
the contents and to create a new name for the newly allocated pixmap.
77
In automatic update mode, the X server is itself responsible for presenting
78
the child window contents within the parent. It seems reasonable, then, for
79
rendering to the parent window to be clipped so as not to interfere with any
80
child window content. In an environment with a mixure of manual and
81
automatic updating windows, rendering to the parent in the area nominally
82
occupied by a manual update window should be able to affect parent pixel
83
values in those areas, but such rendering should be clipped to automatic
84
update windows, and presumably to other manual update windows managed by
85
other applications. In any of these cases, it should be easy to ensure that
86
rendering has no effect on any non-redirected windows.
88
Instead of attempting to define new clipping modes for rendering, the
89
Composite extension instead defines ClipByChildren rendering to the parent
90
to exclude regions occupied by redirected windows (either automatic or
91
manual). The CreateRegionFromBorderClip request can be used along with
92
IncludeInferiors clipping modes to restrict manual shadow updates to the
93
apporpriate region of the screen. Bracketing operations with
94
GrabServer/UngrabServer will permit atomic sequences that can update the
95
screen without artifact. As all of these operations are asynchronous,
96
network latency should not adversely affect update latency.
100
The composite extension does not define any new errors.
104
UPDATETYPE { Automatic, Manual }
108
The composite extension does not define any new events.
110
7. Extension Initialization
112
The client must negotiate the version of the extension before executing
113
extension requests. Otherwise, the server will return BadRequest for any
114
operations other than QueryVersion.
118
client-major-version: CARD32
119
client-minor-version: CARD32
123
major-version: CARD32
124
minor-version: CARD32
126
The client sends the highest supported version to the server and
127
the server sends the highest version it supports, but no higher than
128
the requested version. Major versions changes can introduce
129
incompatibilities in existing functionality, minor version
130
changes introduce only backward compatible changes. It is
131
the client's responsibility to ensure that the server supports
132
a version which is compatible with its expectations. Servers
133
are encouraged to support multiple versions of the extension.
135
8. Hierarchy Redirection
142
errors: Window, Access, Match
144
The hierarchy starting at 'window' is directed to off-screen
145
storage. 'automatic-update' specifies whether the contents
146
are mirrored to the parent window automatically or not. Only
147
one client may specify this flag, another attempt will result in an
148
Access error. When all clients enabling redirection terminate,
149
the redirection will automatically be disabled.
151
The root window may not be redirected. Doing so results in a Match
159
errors: Window, Access
161
Hierarchies starting at all current and future children of window
162
will be redirected as in RedirectWindow. If update is Manual,
163
then painting of the window background during window manipulation
164
and ClearArea requests is inhibited.
170
errors: Window, Value
172
Redirection of the specified window will be terminated. If
173
the specified window was not selected for redirection by the
174
current client, a 'Value' error results.
180
errors: Window, Value
182
Redirection of all children of window will be terminated. If
183
the specified window was not selected for sub-redirection by the
184
current client, a 'Value' error results.
188
CreateRegionFromBorderClip
193
errors: Window, IDChoice
195
This request creates a region containing the "usual" border clip
196
value; that is the area of the window clipped against siblings and
197
the parent. This region can be used to restrict rendering to
198
suitable areas while updating only a single window. The region
199
is copied at the moment the request is executed; future changes
200
to the window hierarchy will not be reflected in this region.
202
10. Associating a Pixmap ID with the off-screen storage (0.2 and later)
209
errors: Window, Match, IDChoice
211
This request makes 'pixmap' a reference to the off-screen storage
212
for 'window'. This pixmap will remain allocated until freed, even
213
if 'window' is unmapped, reconfigured or destroyed. However,
214
'window' will get a new pixmap allocated each time it is
215
mapped or resized, so this request will need to be reinvoked for
216
the client to continue to refer to the storage holding the current
217
window contents. Generates a 'Match' error if 'window' is not
222
11. Composite Overlay Window
224
The Composite Overlay Window provides composite managers with a
225
surface on which to draw without interference. This window is always
226
above normal windows and is always below the screen saver window. It
227
is an InputOutput window whose width and height are the screen
228
dimensions. Its visual is the root visual and its border width is
229
zero. Attempts to redirect it using the composite extension are
230
ignored. This window does not appear in the reply of the QueryTree
231
request. It is also an override redirect window. These last two
232
features make it invisible to window managers and other X11
233
clients. The only way to access the XID of this window is via the
234
CompositeGetOverlayWindow request. Initially, the Composite Overlay
237
CompositeGetOverlayWindow returns the XID of the Composite Overlay
238
Window. If the window has not yet been mapped, it is mapped by this
239
request. When all clients who have called this request have terminated
240
their X11 connections the window is unmapped.
242
Composite managers may render directly to the Composite Overlay
243
Window, or they may reparent other windows to be children of this
244
window and render to these. Multiple clients may render to the
245
Composite Overlay Window, create child windows of it, reshape it, and
246
redefine its input region, but the specific arbitration rules followed
247
by these clients is not defined by this specification; these policies
248
should be defined by the clients themselves.
250
CompositeGetOverlayWindow
258
This request returns the XID of the Composite Overlay Window for
259
the screen specified by the argument 'window'. This request
260
indicates that the client wishes to use the Composite Overlay
261
Window of this screen. If this Composite Overlay Window has not
262
yet been mapped, it is mapped by this request.
264
The Composite Overlay Window for a particular screen will be
265
unmapped when all clients who have invoked this request have
266
also invoked CompositeReleaseOverlayWindow for that screen. Also,
267
CompositeReleaseOverlayWindow for a screen will be implicitly
268
called when a client using the Composite Overlay Window on that
269
screen terminates its X11 connection.
272
CompositeReleaseOverlayWindow
276
This request specifies that the client is no longer using the
277
Composite Overlay Window on the screen specified by the
278
argument 'window'. A screen's Composite Overlay Window is
279
unmapped when there are no longer any clients using it.
added
removed
specs/Composite/protocol
