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
46              when the top level window changes size. Contents beyond the
47              geometry of the top window are not preserved.
48
49       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
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
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
73       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
80       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
86       The off-screen storage includes the window contents, its borders and
87       the contents of all descendants.
88

ARGUMENTS

90       display
91              Pointer to the Display structure returned from XOpenDisplay for
92              the connection to the X server.
93
94       event_base_return
95              Pointer to integer where the base value for Composite Extension
96              events will be stored.
97
98       error_base_return
99              Pointer to integer where the base value for Composite Extension
100              errors will be stored.
101
102       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
106       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
110       window Specifies the window ID to operate on.
111
112       update Specifies the mode for updating the window contents. Must be
113              either CompositeRedirectAutomatic or CompositeRedirectManual.
114

FUNCTIONS

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
123       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
135       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
140              For example, version 1.4.6 would be encoded as the integer
141              10406.
142
143       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
153              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
157       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
164       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
169       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
175       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
184       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
195              The X server must support at least version 0.2 of the Composite
196              Extension for XCompositeNameWindowPixmap.
197
198       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
206              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
211              The X server must support at least version 0.3 of the Composite
212              Extension for XCompositeGetOverlayWindow.
213
214       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
220              The X server must support at least version 0.3 of the Composite
221              Extension for XCompositeReleaseOverlayWindow.
222

AUTHOR

224       Keith Packard <keithp@keithp.com>, Deron Johnson
225       <deron.johnson@sun.com>.
226
227
228
229                                 23 April 2007                   XCOMPOSITE(3)
Impressum