1XCOMPOSITE(3)                    libXcomposite                   XCOMPOSITE(3)
2
3
4

NAME

6       Xcomposite - X Composite Extension library
7

SYNOPSIS

9       #include <X11/extensions/Xcomposite.h>
10
11       Bool XCompositeQueryExtension(Display *dpy, int *event_base_return,
12                                     int *error_base_return);
13
14       Status XCompositeQueryVersion(Display *dpy, int *major_version_return,
15                                     int *minor_version_return);
16
17       int XCompositeVersion(void);
18
19       void XCompositeRedirectWindow(Display *dpy, Window window, int update);
20
21       void XCompositeRedirectSubwindows(Display *dpy, Window window,
22                                         int update);
23
24       void XCompositeUnredirectWindow(Display *dpy, Window window,
25                                       int update);
26
27       void XCompositeUnredirectSubwindows(Display *dpy, Window window,
28                                           int update);
29
30       XserverRegion XCompositeCreateRegionFromBorderClip(Display *dpy,
31                                                          Window window);
32
33       Pixmap XCompositeNameWindowPixmap(Display *dpy, Window window);
34
35       Window XCompositeGetOverlayWindow(Display *dpy, Window window);
36
37       void XCompositeReleaseOverlayWindow(Display *dpy, Window window);
38

DESCRIPTION

40       The composite extension provides several related mechanisms:
41
42       Per-hierarchy storage
43           The rendering of an entire hierarchy of windows is redirected to
44           off-screen storage. The pixels of that hierarchy are available
45           whenever it is viewable. Storage is automatically reallocated when
46           the top level window changes size. Contents beyond the geometry of
47           the top window are not preserved.
48
49       Automatic shadow update
50           When a hierarchy is rendered off-screen, the X server provides an
51           automatic mechanism for presenting those contents within the parent
52           window. The implementation is free to make this update lag behind
53           actual rendering operations by an unspecified amount of time. This
54           automatic update mechanism may be disabled so that the parent
55           window contents can be completely determined by an external
56           application.
57
58       Composite Overlay Window
59           Version 0.3 of the protocol adds the Composite Overlay Window,
60           which provides compositing managers with a surface on which to draw
61           without interference. This window is always above normal windows
62           and is always below the screen saver window. It is an InputOutput
63           window whose width and height are the screen dimensions. Its visual
64           is the root visual and its border width is zero. Attempts to
65           redirect it using the composite extension are ignored. This window
66           does not appear in the reply of the QueryTree request. It is also
67           an override redirect window. These last two features make it
68           invisible to window managers and other X11 clients. The only way to
69           access the XID of this window is via the CompositeGetOverlayWindow
70           request. Initially, the Composite Overlay Window is unmapped.
71
72       Parent window clipping
73           Version 0.4 of the protocol modifies the semantics of parent window
74           clipping in the presence of manual redirected children. With this
75           version, the area in the parent covered by manual redirected
76           children is left in the parent clip list instead of being removed
77           as in older versions.
78
79       Per-hierarchy storage may be created for individual windows or for all
80       children of a window. Manual shadow update may be selected by only a
81       single application for each window; manual update may also be selected
82       on a per-window basis or for each child of a window. Detecting when to
83       update may be done with the Damage extension.
84
85       The off-screen storage includes the window contents, its borders and
86       the contents of all descendants.
87

ARGUMENTS

89       display
90           Pointer to the Display structure returned from XOpenDisplay for the
91           connection to the X server.
92
93       event_base_return
94           Pointer to integer where the base value for Composite Extension
95           events will be stored.
96
97       error_base_return
98           Pointer to integer where the base value for Composite Extension
99           errors will be stored.
100
101       major_version_return
102           Pointer to integer where the major version of the Composite
103           Extension supported by the X server will be stored.
104
105       minor_version_return
106           Pointer to integer where the minor version of the Composite
107           Extension supported by the X server will be stored.
108
109       window
110           Specifies the window ID to operate on.
111
112       update
113           Specifies the mode for updating the window contents. Must be either
114           CompositeRedirectAutomatic or CompositeRedirectManual.
115

FUNCTIONS

117       XCompositeQueryExtension
118
119           XCompositeQueryExtension determines if the Composite Extension is
120           available on the given display. It returns True if the extension is
121           supported, otherwise False. If the extension is present, the base
122           values for events and errors are returned, and can be used to
123           decode incoming event and error values.
124
125       XCompositeQueryVersion
126
127           XCompositeQueryVersion determines if the X Server supports a
128           version of the X Composite Extension which is compatible with the
129           client library. A non-zero Status is returned if a compatible
130           version of the extension is supported, otherwise a zero Status is
131           returned. If the extension is supported, the major and minor
132           version numbers are returned to indicate the level of Composite
133           Extension support. No other XComposite functions (except
134           XCompositeQueryExtension) may be called before this function. If a
135           client violates this rule, the effects of all subsequent XComposite
136           calls that it makes are undefined.
137
138       XCompositeVersion
139
140           XCompositeVersion returns the version of the X Composite library.
141           The version number is encoded as: (major * 10000) + (minor * 100) +
142           revision
143
144           For example, version 1.4.6 would be encoded as the integer 10406.
145
146       XCompositeRedirectWindow
147
148           XCompositeRedirectWindow requests the X server to direct the
149           hierarchy starting at window to off-screen storage. The update
150           argument specifies whether the contents are mirrored to the parent
151           window automatically or not. Only one client at a time may specify
152           an update type of CompositeRedirectManual, another attempt will
153           result in a BadAccess error. When all clients enabling redirection
154           terminate, the redirection will automatically be disabled.
155
156           The root window may not be redirected. Doing so results in a
157           BadMatch error. Specifying an invalid window id will result in a
158           BadWindow error.
159
160       XCompositeRedirectSubwindows
161
162           XCompositeRedirectSubwindows requests the X server to redirect
163           hierarchies starting at all current and future children of window
164           as in XCompositeRedirectWindow. If update is
165           CompositeRedirectManual, then painting of the window background
166           during window manipulation and ClearArea requests is inhibited.
167
168       XCompositeUnredirectWindow
169
170           XCompositeUnredirectWindow requests the X server to terminate
171           redirection of window. If the specified window was not selected for
172           redirection by the current client, a BadValue error results.
173
174       XCompositeUnredirectSubwindows
175
176           XCompositeUnredirectWindow requests the X server to terminate
177           redirection of all children of window. If the specified window was
178           not selected for sub-redirection by the current client, a BadValue
179           error results.
180
181       XCompositeCreateRegionFromBorderClip
182
183           XCompositeCreateRegionFromBorderClip creates a region containing
184           the "usual" border clip value; that is the area of the window
185           clipped against siblings and the parent. This region can be used to
186           restrict rendering to suitable areas while updating only a single
187           window. The region is copied at the moment the request is executed;
188           future changes to the window hierarchy will not be reflected in
189           this region.
190
191       XCompositeNameWindowPixmap
192
193           XCompositeNameWindowPixmap creates and returns a pixmap id that
194           serves as a reference to the off-screen storage for window. This
195           pixmap will remain allocated until freed, even if the window is
196           unmapped, reconfigured or destroyed. However, the window will get a
197           new pixmap allocated each time it is mapped or resized, so this
198           function will need to be reinvoked for the client to continue to
199           refer to the storage holding the current window contents. Generates
200           a BadMatch error if window is not redirected or is not visible.
201
202           The X server must support at least version 0.2 of the Composite
203           Extension for XCompositeNameWindowPixmap.
204
205       XCompositeGetOverlayWindow
206
207           XCompositeGetOverlayWindow returns the window ID of the Composite
208           Overlay Window for the screen specified by the argument window.
209           This function notifies the X server that the client wishes to use
210           the Composite Overlay Window of this screen. If this Composite
211           Overlay Window has not yet been mapped, it is mapped by this
212           request.
213
214           The Composite Overlay Window for a particular screen will be
215           unmapped when all clients who have called this function have either
216           called XCompositeReleaseOverlayWindow for that screen, or
217           terminated their connection to the X server.
218
219           The X server must support at least version 0.3 of the Composite
220           Extension for XCompositeGetOverlayWindow.
221
222       XCompositeReleaseOverlayWindow
223           This request specifies that the client is no longer using the
224           Composite Overlay Window on the screen specified by the argument
225           window. A screen´s Composite Overlay Window is unmapped when there
226           are no longer any clients using it.
227
228           The X server must support at least version 0.3 of the Composite
229           Extension for XCompositeReleaseOverlayWindow.
230

AUTHORS

232       Keith Packard <keithp@keithp.com>
233           Extension specification and implementation
234
235       Deron Johnson <deron.johnson@sun.com>
236           Overlay Window specification and implementation
237
238
239
240                       <pubdate>23 April 2007</pubdate>          XCOMPOSITE(3)
Impressum