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
46 when the top level window changes size. Contents beyond the
47 geometry of the top window are not preserved.
48 Automatic shadow update
50 When a hierarchy is rendered off-screen, the X server provides
51 an automatic mechanism for presenting those contents within the
52 parent window. The implementation is free to make this update
53 lag behind actual rendering operations by an unspecified amount
54 of time. This automatic update mechanism may be disabled so that
55 the parent window contents can be completely determined by an
56 external 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
61 draw without interference. This window is always above normal
62 windows and is always below the screen saver window. It is an
63 InputOutput window whose width and height are the screen
64 dimensions. Its visual is the root visual and its border width
65 is zero. Attempts to redirect it using the composite extension
66 are ignored. This window does not appear in the reply of the
67 QueryTree request. It is also an override redirect window. These
68 last two features make it invisible to window managers and other
69 X11 clients. The only way to access the XID of this window is
70 via the CompositeGetOverlayWindow request. Initially, the
71 Composite Overlay Window is unmapped.
72 Parent window clipping
74 Version 0.4 of the protocol modifies the semantics of parent
75 window clipping in the presence of manual redirected children.
76 With this version, the area in the parent covered by manual
77 redirected children is left in the parent clip list instead of
78 being removed as in older versions.
79 Per-hierarchy storage may be created for individual windows or for all
81 children of a window. Manual shadow update may be selected by only a
82 single application for each window; manual update may also be selected
83 on a per-window basis or for each child of a window. Detecting when to
84 update may be done with the Damage extension.
85 The off-screen storage includes the window contents, its borders and
87 the contents of all descendants.
88
90 display
91 Pointer to the Display structure returned from XOpenDisplay for
92 the connection to the X server.
93 event_base_return
95 Pointer to integer where the base value for Composite Extension
96 events will be stored.
97 error_base_return
99 Pointer to integer where the base value for Composite Extension
100 errors will be stored.
101 major_version_return
103 Pointer to integer where the major version of the Composite
104 Extension supported by the X server will be stored.
105 minor_version_return
107 Pointer to integer where the minor version of the Composite
108 Extension supported by the X server will be stored.
109 window Specifies the window ID to operate on.
111 update Specifies the mode for updating the window contents. Must be
113 either CompositeRedirectAutomatic or CompositeRedirectManual.
114
116 XCompositeQueryExtension
117 XCompositeQueryExtension determines if the Composite Extension
118 is available on the given display. It returns True if the
119 extension is supported, otherwise False. If the extension is
120 present, the base values for events and errors are returned, and
121 can be used to decode incoming event and error values.
122 XCompositeQueryVersion
124 XCompositeQueryVersion determines if the X Server supports a
125 version of the X Composite Extension which is compatible with
126 the client library. A non-zero Status is returned if a
127 compatible version of the extension is supported, otherwise a
128 zero Status is returned. If the extension is supported, the
129 major and minor version numbers are returned to indicate the
130 level of Composite Extension support. No other XComposite
131 functions (except XCompositeQueryExtension) may be called before
132 this function. If a client violates this rule, the effects of
133 all subsequent XComposite calls that it makes are undefined.
134 XCompositeVersion
136 XCompositeVersion returns the version of the X Composite
137 library. The version number is encoded as: (major * 10000) +
138 (minor * 100) + revision
139 For example, version 1.4.6 would be encoded as the integer
141 10406.
142 XCompositeRedirectWindow
144 XCompositeRedirectWindow requests the X server to direct the
145 hierarchy starting at window to off-screen storage. The update
146 argument specifies whether the contents are mirrored to the
147 parent window automatically or not. Only one client at a time
148 may specify an update type of CompositeRedirectManual, another
149 attempt will result in a BadAccess error. When all clients
150 enabling redirection terminate, the redirection will
151 automatically be disabled.
152 The root window may not be redirected. Doing so results in a
154 BadMatch error. Specifying an invalid window id will result in a
155 BadWindow error.
156 XCompositeRedirectSubwindows
158 XCompositeRedirectSubwindows requests the X server to redirect
159 hierarchies starting at all current and future children of
160 window as in XCompositeRedirectWindow. If update is
161 CompositeRedirectManual, then painting of the window background
162 during window manipulation and ClearArea requests is inhibited.
163 XCompositeUnredirectWindow
165 XCompositeUnredirectWindow requests the X server to terminate
166 redirection of window. If the specified window was not selected
167 for redirection by the current client, a BadValue error results.
168 XCompositeUnredirectSubwindows
170 XCompositeUnredirectWindow requests the X server to terminate
171 redirection of all children of window. If the specified window
172 was not selected for sub-redirection by the current client, a
173 BadValue error results.
174 XCompositeCreateRegionFromBorderClip
176 XCompositeCreateRegionFromBorderClip creates a region containing
177 the "usual" border clip value; that is the area of the window
178 clipped against siblings and the parent. This region can be used
179 to restrict rendering to suitable areas while updating only a
180 single window. The region is copied at the moment the request is
181 executed; future changes to the window hierarchy will not be
182 reflected in this region.
183 XCompositeNameWindowPixmap
185 XCompositeNameWindowPixmap creates and returns a pixmap id that
186 serves as a reference to the off-screen storage for window. This
187 pixmap will remain allocated until freed, even if the window is
188 unmapped, reconfigured or destroyed. However, the window will
189 get a new pixmap allocated each time it is mapped or resized, so
190 this function will need to be reinvoked for the client to
191 continue to refer to the storage holding the current window
192 contents. Generates a BadMatch error if window is not redirected
193 or is not visible.
194 The X server must support at least version 0.2 of the Composite
196 Extension for XCompositeNameWindowPixmap.
197 XCompositeGetOverlayWindow
199 XCompositeGetOverlayWindow returns the window ID of the
200 Composite Overlay Window for the screen specified by the
201 argument window. This function notifies the X server that the
202 client wishes to use the Composite Overlay Window of this
203 screen. If this Composite Overlay Window has not yet been
204 mapped, it is mapped by this request.
205 The Composite Overlay Window for a particular screen will be
207 unmapped when all clients who have called this function have
208 either called XCompositeReleaseOverlayWindow for that screen, or
209 terminated their connection to the X server.
210 The X server must support at least version 0.3 of the Composite
212 Extension for XCompositeGetOverlayWindow.
213 XCompositeReleaseOverlayWindow
215 This request specifies that the client is no longer using the
216 Composite Overlay Window on the screen specified by the argument
217 window. A screen's Composite Overlay Window is unmapped when
218 there are no longer any clients using it.
219 The X server must support at least version 0.3 of the Composite
221 Extension for XCompositeReleaseOverlayWindow.
222
224 Keith Packard <keithp@keithp.com>, Deron Johnson
225 <deron.johnson@sun.com>.
226 23 April 2007 XCOMPOSITE(3)