1XCOMPOSITE(3) libXcomposite XCOMPOSITE(3)
2
6 Xcomposite - X Composite Extension library
7
9 #include <X11/extensions/Xcomposite.h>
10 Bool XCompositeQueryExtension(Display *dpy, int *event_base_return,
12 int *error_base_return);
13 Status XCompositeQueryVersion(Display *dpy, int *major_version_return,
15 int *minor_version_return);
16 int XCompositeVersion(void);
18 void XCompositeRedirectWindow(Display *dpy, Window window, int update);
20 void XCompositeRedirectSubwindows(Display *dpy, Window window,
22 int update);
23 void XCompositeUnredirectWindow(Display *dpy, Window window,
25 int update);
26 void XCompositeUnredirectSubwindows(Display *dpy, Window window,
28 int update);
29 XserverRegion XCompositeCreateRegionFromBorderClip(Display *dpy,
31 Window window);
32 Pixmap XCompositeNameWindowPixmap(Display *dpy, Window window);
34 Window XCompositeGetOverlayWindow(Display *dpy, Window window);
36 void XCompositeReleaseOverlayWindow(Display *dpy, Window window);
38
40 The composite extension provides several related mechanisms:
41 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 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 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 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 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 The off-screen storage includes the window contents, its borders and
86 the contents of all descendants.
87
89 display
90 Pointer to the Display structure returned from XOpenDisplay for the
91 connection to the X server.
92 event_base_return
94 Pointer to integer where the base value for Composite Extension
95 events will be stored.
96 error_base_return
98 Pointer to integer where the base value for Composite Extension
99 errors will be stored.
100 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 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 window
110 Specifies the window ID to operate on.
111 update
113 Specifies the mode for updating the window contents. Must be either
114 CompositeRedirectAutomatic or CompositeRedirectManual.
115
117 XCompositeQueryExtension
118 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 XCompositeQueryVersion
126 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 XCompositeVersion
139 XCompositeVersion returns the version of the X Composite library.
141 The version number is encoded as: (major * 10000) + (minor * 100) +
142 revision
143 For example, version 1.4.6 would be encoded as the integer 10406.
145 XCompositeRedirectWindow
147 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 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 XCompositeRedirectSubwindows
161 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 XCompositeUnredirectWindow
169 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 XCompositeUnredirectSubwindows
175 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 XCompositeCreateRegionFromBorderClip
182 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 XCompositeNameWindowPixmap
192 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 The X server must support at least version 0.2 of the Composite
203 Extension for XCompositeNameWindowPixmap.
204 XCompositeGetOverlayWindow
206 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 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 The X server must support at least version 0.3 of the Composite
220 Extension for XCompositeGetOverlayWindow.
221 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 The X server must support at least version 0.3 of the Composite
229 Extension for XCompositeReleaseOverlayWindow.
230
232 Keith Packard <keithp@keithp.com>
233 Extension specification and implementation
234 Deron Johnson <deron.johnson@sun.com>
236 Overlay Window specification and implementation
237 <pubdate>23 April 2007</pubdate> XCOMPOSITE(3)