summaryrefslogtreecommitdiff
path: root/man/Xcomposite.xml
blob: 94de15bc36f1ed89c7525cb60fe6778b4389b82b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
            "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" >
<reference>
<!--
 Based on proto/compositeproto/compositeproto.txt

 Conversion to DocBook/XML API documentation is:

 Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the
 "Software"), to deal in the Software without restriction, including
 without limitation the rights to use, copy, modify, merge, publish,
 distribute, and/or sell copies of the Software, and to permit persons
 to whom the Software is furnished to do so, provided that the above
 copyright notice(s) and this permission notice appear in all copies of
 the Software and that both the above copyright notice(s) and this
 permission notice appear in supporting documentation.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 Except as contained in this notice, the name of a copyright holder
 shall not be used in advertising or otherwise to promote the sale, use
 or other dealings in this Software without prior written authorization
 of the copyright holder.

 -->
<title>X Composite Extension Library</title>

<refentry id='Xcomposite.man'>
 <refentryinfo>
  <productname>__vendorversion__</productname>
  <pubdate>23 April 2007</pubdate>
  <authorgroup>
   <author><firstname>Keith</firstname><surname>Packard</surname>
	   <contrib>Extension specification and implementation</contrib>
	   <email>keithp@keithp.com</email>
   </author>
   <author><firstname>Deron</firstname><surname>Johnson</surname>
	   <contrib>Overlay Window specification and implementation</contrib>
	   <email>deron.johnson@sun.com</email>
   </author>
  </authorgroup>
 </refentryinfo>

 <refmeta>
  <refentrytitle>Xcomposite</refentrytitle>
  <manvolnum>__libmansuffix__</manvolnum>
 </refmeta>
 <refnamediv>
  <refname>Xcomposite</refname>
  <refpurpose>X Composite Extension library</refpurpose>
 </refnamediv>
 <refsynopsisdiv><funcsynopsis>
  <funcsynopsisinfo>#include &lt;X11/extensions/Xcomposite.h&gt;</funcsynopsisinfo>
  <funcprototype>
   <funcdef>Bool <function>XCompositeQueryExtension</function></funcdef>
   <paramdef><type>Display *</type><parameter>dpy</parameter></paramdef>
   <paramdef>int *<parameter>event_basep</parameter></paramdef>
   <paramdef>int *<parameter>error_basep</parameter></paramdef>
  </funcprototype>
  <funcprototype>
   <funcdef>Status <function>XCompositeQueryVersion</function></funcdef>
   <paramdef>Display *<parameter>dpy</parameter></paramdef>
   <paramdef>int *<parameter>major_versionp</parameter></paramdef>
   <paramdef>int *<parameter>minor_versionp</parameter></paramdef>
  </funcprototype>
  <funcprototype>
   <funcdef>int <function>XCompositeVersion</function></funcdef>
   <void />
  </funcprototype>
  <funcprototype>
   <funcdef>void <function>XCompositeRedirectWindow</function></funcdef>
   <paramdef>Display *<parameter>dpy</parameter></paramdef>
   <paramdef>Window <parameter>window</parameter></paramdef>
   <paramdef>int <parameter>update</parameter></paramdef>
  </funcprototype>
  <funcprototype>
   <funcdef>void <function>XCompositeRedirectSubwindows</function></funcdef>
   <paramdef>Display *<parameter>dpy</parameter></paramdef>
   <paramdef>Window <parameter>window</parameter></paramdef>
   <paramdef>int <parameter>update</parameter></paramdef>
  </funcprototype>
  <funcprototype>
   <funcdef>void <function>XCompositeUnredirectWindow</function></funcdef>
   <paramdef>Display *<parameter>dpy</parameter></paramdef>
   <paramdef>Window <parameter>window</parameter></paramdef>
   <paramdef>int <parameter>update</parameter></paramdef>
  </funcprototype>
  <funcprototype>
   <funcdef>void <function>XCompositeUnredirectSubwindows</function></funcdef>
   <paramdef>Display *<parameter>dpy</parameter></paramdef>
   <paramdef>Window <parameter>window</parameter></paramdef>
   <paramdef>int <parameter>update</parameter></paramdef>
  </funcprototype>
  <funcprototype>
   <funcdef>XserverRegion <function>XCompositeCreateRegionFromBorderClip</function></funcdef>
   <paramdef>Display *<parameter>dpy</parameter></paramdef>
   <paramdef>Window <parameter>window</parameter></paramdef>
  </funcprototype>
  <funcprototype>
   <funcdef>Pixmap <function>XCompositeNameWindowPixmap</function></funcdef>
   <paramdef>Display *<parameter>dpy</parameter></paramdef>
   <paramdef>Window <parameter>window</parameter></paramdef>
  </funcprototype>
  <funcprototype>
   <funcdef>Window <function>XCompositeGetOverlayWindow</function></funcdef>
   <paramdef>Display *<parameter>dpy</parameter></paramdef>
   <paramdef>Window <parameter>window</parameter></paramdef>
  </funcprototype>
  <funcprototype>
   <funcdef>void <function>XCompositeReleaseOverlayWindow</function></funcdef>
   <paramdef>Display *<parameter>dpy</parameter></paramdef>
   <paramdef>Window <parameter>window</parameter></paramdef>
  </funcprototype>
 </funcsynopsis></refsynopsisdiv>

<refsect1><title>Description</title>
<para>
The composite extension provides several related mechanisms:
 <variablelist>
  <varlistentry>
   <term>Per-hierarchy storage</term>
   <listitem><para>
	The rendering of an entire hierarchy of windows
 	is redirected to off-screen storage. The pixels of that hierarchy
	are available whenever it is viewable. Storage is automatically
	reallocated when the top level window changes size. Contents beyond
	the geometry of the top window are not preserved.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term>Automatic shadow update</term>
   <listitem><para>
 	When a hierarchy is rendered off-screen,
 	the X server provides an automatic mechanism for presenting those
	contents within the parent window. The implementation is free to
	make this update lag behind actual rendering operations by an
	unspecified amount of time. This automatic update mechanism may
	be disabled so that the parent window contents can be completely
	determined by an external application.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term>Composite Overlay Window</term>
   <listitem><para>
	Version 0.3 of the protocol adds the Composite Overlay Window, which
	provides compositing managers with a surface on which to draw without
	interference. This window is always above normal windows and is always
	below the screen saver window. It is an InputOutput window whose width
	and height are the screen dimensions. Its visual is the root visual
	and its border width is zero.  Attempts to redirect it using the
	composite extension are ignored.  This window does not appear in the
	reply of the QueryTree request. It is also an override redirect window.
	These last two features make it invisible to window managers and other
	X11 clients. The only way to access the XID of this window is via the
	CompositeGetOverlayWindow request. Initially, the Composite Overlay
	Window is unmapped.
   </para></listitem>
  </varlistentry>
 </variablelist>
</para>
<para>
Per-hierarchy storage may be created for individual windows or for all
children of a window. Manual shadow update may be selected by only a single
application for each window; manual update may also be selected on a
per-window basis or for each child of a window. Detecting when to update
may be done with the Damage extension.
</para>
<para>
The off-screen storage includes the window contents, its borders and the
contents of all descendants.
</para>
</refsect1>
<refsect1><title>Arguments</title>
<para>
 <variablelist>
  <varlistentry>
   <term><parameter>display</parameter></term>
   <listitem><para>
    Pointer to the <type>Display</type> structure returned from 
    <function>XOpenDisplay</function> for the connection to the X server.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>event_basep</parameter></term>
   <listitem><para>
    Pointer to integer where the base value for Composite Extension events
    will be stored.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>error_basep</parameter></term>
   <listitem><para>
    Pointer to integer where the base value for Composite Extension errors
    will be stored.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>major_versionp</parameter></term>
   <listitem><para>
    Pointer to integer where the major version of the Composite Extension
    supported by the X server will be stored.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>minor_versionp</parameter></term>
   <listitem><para>
    Pointer to integer where the minor version of the Composite Extension
    supported by the X server will be stored.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>window</parameter></term>
   <listitem><para>
    Specifies the window ID to operate on.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>update</parameter></term>
   <listitem><para>
    Specifies the mode for updating the window contents.   Must be either
    <constant>CompositeRedirectAutomatic</constant> or
    <constant>CompositeRedirectManual</constant>.
   </para></listitem>
  </varlistentry>
 </variablelist>
</para></refsect1>
<refsect1><title>Functions</title>
<para>
 <variablelist>
  <varlistentry>
   <term><function>XCompositeQueryExtension</function></term>
   <listitem><para>
    <function>XCompositeQueryExtension</function> determines if the 
    Composite Extension is available on the given display.   It returns 
    <constant>True</constant> if the extension is supported, otherwise 
    <constant>False</constant>.   If the extension is present, the base 
    values for events and errors are returned, and can be used to 
    decode incoming event and error values.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><function>XCompositeQueryVersion</function></term>
   <listitem><para>
    <function>XCompositeQueryVersion</function> determines if the X Server
    supports a version of the X Composite Extension which is compatible 
    with the client library. A non-zero Status is returned if a compatible
    version of the extension is supported, otherwise a zero Status is returned.
    If the extension is supported, the major and minor version numbers are 
    returned to indicate the level of Composite Extension support.
    No other XComposite functions (except XCompositeQueryExtension) may be 
    called before this function.  If a client violates this  rule, the
    effects of all subsequent XComposite calls that it makes are undefined.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><function>XCompositeVersion</function></term>
   <listitem><para>
    <function>XCompositeVersion</function> returns the version of the 
    X Composite library.   The version number is encoded as:
    <blockquote><para><code language="C">
     (major * 10000) + (minor * 100) + revision
    </code></para></blockquote>
   </para>
   <para>
    For example, version 1.4.6 would be encoded as the integer 10406.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><function>XCompositeRedirectWindow</function></term>
   <listitem><para>
	<function>XCompositeRedirectWindow</function> requests the X server 
	to direct the hierarchy starting at <parameter>window</parameter> to 
	off-screen storage. 
        The <parameter>update</parameter> argument specifies whether 
        the contents are mirrored to the parent window automatically or not.
        Only one client at a time may specify an update type of 
	<constant>CompositeRedirectManual</constant>, another attempt will 
	result in a <errorname>BadAccess</errorname> error.  When all clients 
        enabling redirection terminate, the redirection will automatically be
        disabled.
   </para><para>
	The root window may not be redirected. Doing so results in a 
	<errorname>BadMatch</errorname>	error.  Specifying an invalid
        window id will result in a <errorname>BadWindow</errorname> error.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><function>XCompositeRedirectSubwindows</function></term>
   <listitem><para>
	<function>XCompositeRedirectSubwindows</function> requests the X 
	server to redirect hierarchies starting at all current and future 
	children of <parameter>window</parameter> as in 
	<function>XCompositeRedirectWindow</function>. 
	If <parameter>update</parameter> is 
	<constant>CompositeRedirectManual</constant>, then painting of the 
	window background during window manipulation and ClearArea requests 
	is inhibited.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><function>XCompositeUnredirectWindow</function></term>
   <listitem><para>
	<function>XCompositeUnredirectWindow</function> requests the X 
	server to terminate redirection of <parameter>window</parameter>.
	If the specified window was not selected for redirection by the
	current client, a <errorname>BadValue</errorname> error results.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><function>XCompositeUnredirectSubwindows</function></term>
   <listitem><para>
	<function>XCompositeUnredirectWindow</function> requests the X 
	server to terminate redirection of all children of
	<parameter>window</parameter>.
	If the specified window was not selected for sub-redirection by the
	current client, a <errorname>BadValue</errorname> error results.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><function>XCompositeCreateRegionFromBorderClip</function></term>
   <listitem><para>
	<function>XCompositeCreateRegionFromBorderClip</function>
	creates a region containing the "usual" border clip
	value; that is the area of the window clipped against siblings and
	the parent. This region can be used to restrict rendering to
	suitable areas while updating only a single window. The region
	is copied at the moment the request is executed; future changes
	to the window hierarchy will not be reflected in this region.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><function>XCompositeNameWindowPixmap</function></term>
   <listitem><para>
	<function>XCompositeNameWindowPixmap</function> creates and returns
	a pixmap id that serves as a reference to the off-screen storage for
	<parameter>window</parameter>. This pixmap will remain allocated 
	until freed, even if the window is unmapped, reconfigured or 
	destroyed. However, the window will get a new pixmap allocated each 
	time it is mapped or resized, so this function will need to be 
	reinvoked for the client to continue to refer to the storage holding
	the current window contents. Generates a 
	<errorname>BadMatch</errorname>	error if <parameter>window</parameter>
	is not redirected or is not visible.
   </para><para>
        The X server must support at least version 0.2 of the Composite
	Extension for <function>XCompositeNameWindowPixmap</function>.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><function>XCompositeGetOverlayWindow</function></term>
   <listitem><para>
    <function>XCompositeGetOverlayWindow</function> returns the window ID
    of the Composite Overlay Window for 
    the screen specified by the argument <parameter>window</parameter>. 
    This function notifies the X server that the client wishes to use 
    the Composite Overlay Window of this screen. If this 
    Composite Overlay Window has not yet been mapped, it is mapped by this 
    request.
   </para><para>
    The Composite Overlay Window for a particular screen will be 
    unmapped when all clients who have called this function have 
    either called <function>XCompositeReleaseOverlayWindow</function>
    for that screen, or terminated their connection to the X server.
   </para><para>
    The X server must support at least version 0.3 of the Composite
    Extension for <function>XCompositeGetOverlayWindow</function>.
   </para></listitem>
  </varlistentry>
  <varlistentry>
   <term><function>XCompositeReleaseOverlayWindow</function></term>
   <listitem><para>
    This request specifies that the client is no longer using the 
    Composite Overlay Window on the screen specified by the 
    argument <parameter>window</parameter>. A screen&apos;s Composite 
    Overlay Window is unmapped when there are no longer any clients using it.
   </para><para>
    The X server must support at least version 0.3 of the Composite
    Extension for <function>XCompositeReleaseOverlayWindow</function>.
   </para></listitem>
  </varlistentry>
 </variablelist>
</para>
</refsect1>
</refentry>
</reference>