1<?xml version="1.0" encoding="UTF-8" ?> 2<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" > 4<reference> 5<!-- 6 Based on proto/compositeproto/compositeproto.txt 7 8 Conversion to DocBook/XML API documentation is: 9 10 Copyright (c) 2007, Oracle and/or its affiliates. All rights reserved. 11 12 Permission is hereby granted, free of charge, to any person obtaining a 13 copy of this software and associated documentation files (the "Software"), 14 to deal in the Software without restriction, including without limitation 15 the rights to use, copy, modify, merge, publish, distribute, sublicense, 16 and/or sell copies of the Software, and to permit persons to whom the 17 Software is furnished to do so, subject to the following conditions: 18 19 The above copyright notice and this permission notice (including the next 20 paragraph) shall be included in all copies or substantial portions of the 21 Software. 22 23 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 24 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 25 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 26 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 27 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 28 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 29 DEALINGS IN THE SOFTWARE. 30 31 --> 32<title>X Composite Extension Library</title> 33 34<refentry id='Xcomposite.man'> 35 <refentryinfo> 36 <productname>__vendorversion__</productname> 37 <pubdate>23 April 2007</pubdate> 38 <authorgroup> 39 <author><firstname>Keith</firstname><surname>Packard</surname> 40 <contrib>Extension specification and implementation</contrib> 41 <email>keithp@keithp.com</email> 42 </author> 43 <author><firstname>Deron</firstname><surname>Johnson</surname> 44 <contrib>Overlay Window specification and implementation</contrib> 45 <email>deron.johnson@sun.com</email> 46 </author> 47 </authorgroup> 48 </refentryinfo> 49 50 <refmeta> 51 <refentrytitle>Xcomposite</refentrytitle> 52 <manvolnum>__libmansuffix__</manvolnum> 53 </refmeta> 54 <refnamediv> 55 <refname>Xcomposite</refname> 56 <refpurpose>X Composite Extension library</refpurpose> 57 </refnamediv> 58 <refsynopsisdiv><funcsynopsis> 59 <funcsynopsisinfo>#include <X11/extensions/Xcomposite.h></funcsynopsisinfo> 60 <funcprototype> 61 <funcdef>Bool <function>XCompositeQueryExtension</function></funcdef> 62 <paramdef><type>Display *</type><parameter>dpy</parameter></paramdef> 63 <paramdef>int *<parameter>event_base_return</parameter></paramdef> 64 <paramdef>int *<parameter>error_base_return</parameter></paramdef> 65 </funcprototype> 66 <funcprototype> 67 <funcdef>Status <function>XCompositeQueryVersion</function></funcdef> 68 <paramdef>Display *<parameter>dpy</parameter></paramdef> 69 <paramdef>int *<parameter>major_version_return</parameter></paramdef> 70 <paramdef>int *<parameter>minor_version_return</parameter></paramdef> 71 </funcprototype> 72 <funcprototype> 73 <funcdef>int <function>XCompositeVersion</function></funcdef> 74 <void /> 75 </funcprototype> 76 <funcprototype> 77 <funcdef>void <function>XCompositeRedirectWindow</function></funcdef> 78 <paramdef>Display *<parameter>dpy</parameter></paramdef> 79 <paramdef>Window <parameter>window</parameter></paramdef> 80 <paramdef>int <parameter>update</parameter></paramdef> 81 </funcprototype> 82 <funcprototype> 83 <funcdef>void <function>XCompositeRedirectSubwindows</function></funcdef> 84 <paramdef>Display *<parameter>dpy</parameter></paramdef> 85 <paramdef>Window <parameter>window</parameter></paramdef> 86 <paramdef>int <parameter>update</parameter></paramdef> 87 </funcprototype> 88 <funcprototype> 89 <funcdef>void <function>XCompositeUnredirectWindow</function></funcdef> 90 <paramdef>Display *<parameter>dpy</parameter></paramdef> 91 <paramdef>Window <parameter>window</parameter></paramdef> 92 <paramdef>int <parameter>update</parameter></paramdef> 93 </funcprototype> 94 <funcprototype> 95 <funcdef>void <function>XCompositeUnredirectSubwindows</function></funcdef> 96 <paramdef>Display *<parameter>dpy</parameter></paramdef> 97 <paramdef>Window <parameter>window</parameter></paramdef> 98 <paramdef>int <parameter>update</parameter></paramdef> 99 </funcprototype> 100 <funcprototype> 101 <funcdef>XserverRegion <function>XCompositeCreateRegionFromBorderClip</function></funcdef> 102 <paramdef>Display *<parameter>dpy</parameter></paramdef> 103 <paramdef>Window <parameter>window</parameter></paramdef> 104 </funcprototype> 105 <funcprototype> 106 <funcdef>Pixmap <function>XCompositeNameWindowPixmap</function></funcdef> 107 <paramdef>Display *<parameter>dpy</parameter></paramdef> 108 <paramdef>Window <parameter>window</parameter></paramdef> 109 </funcprototype> 110 <funcprototype> 111 <funcdef>Window <function>XCompositeGetOverlayWindow</function></funcdef> 112 <paramdef>Display *<parameter>dpy</parameter></paramdef> 113 <paramdef>Window <parameter>window</parameter></paramdef> 114 </funcprototype> 115 <funcprototype> 116 <funcdef>void <function>XCompositeReleaseOverlayWindow</function></funcdef> 117 <paramdef>Display *<parameter>dpy</parameter></paramdef> 118 <paramdef>Window <parameter>window</parameter></paramdef> 119 </funcprototype> 120 </funcsynopsis></refsynopsisdiv> 121 122<refsect1><title>Description</title> 123<para> 124The composite extension provides several related mechanisms: 125 <variablelist> 126 <varlistentry> 127 <term>Per-hierarchy storage</term> 128 <listitem><para> 129 The rendering of an entire hierarchy of windows 130 is redirected to off-screen storage. The pixels of that hierarchy 131 are available whenever it is viewable. Storage is automatically 132 reallocated when the top level window changes size. Contents beyond 133 the geometry of the top window are not preserved. 134 </para></listitem> 135 </varlistentry> 136 <varlistentry> 137 <term>Automatic shadow update</term> 138 <listitem><para> 139 When a hierarchy is rendered off-screen, 140 the X server provides an automatic mechanism for presenting those 141 contents within the parent window. The implementation is free to 142 make this update lag behind actual rendering operations by an 143 unspecified amount of time. This automatic update mechanism may 144 be disabled so that the parent window contents can be completely 145 determined by an external application. 146 </para></listitem> 147 </varlistentry> 148 <varlistentry> 149 <term>Composite Overlay Window</term> 150 <listitem><para> 151 Version 0.3 of the protocol adds the Composite Overlay Window, which 152 provides compositing managers with a surface on which to draw without 153 interference. This window is always above normal windows and is always 154 below the screen saver window. It is an InputOutput window whose width 155 and height are the screen dimensions. Its visual is the root visual 156 and its border width is zero. Attempts to redirect it using the 157 composite extension are ignored. This window does not appear in the 158 reply of the QueryTree request. It is also an override redirect window. 159 These last two features make it invisible to window managers and other 160 X11 clients. The only way to access the XID of this window is via the 161 CompositeGetOverlayWindow request. Initially, the Composite Overlay 162 Window is unmapped. 163 </para></listitem> 164 </varlistentry> 165 <varlistentry> 166 <term>Parent window clipping</term> 167 <listitem><para> 168 Version 0.4 of the protocol modifies the semantics of parent window 169 clipping in the presence of manual redirected children. With this 170 version, the area in the parent covered by manual redirected 171 children is left in the parent clip list instead of being removed as 172 in older versions. 173 </para></listitem> 174 </varlistentry> 175 </variablelist> 176</para> 177<para> 178Per-hierarchy storage may be created for individual windows or for all 179children of a window. Manual shadow update may be selected by only a single 180application for each window; manual update may also be selected on a 181per-window basis or for each child of a window. Detecting when to update 182may be done with the Damage extension. 183</para> 184<para> 185The off-screen storage includes the window contents, its borders and the 186contents of all descendants. 187</para> 188</refsect1> 189<refsect1><title>Arguments</title> 190<para> 191 <variablelist> 192 <varlistentry> 193 <term><parameter>display</parameter></term> 194 <listitem><para> 195 Pointer to the <type>Display</type> structure returned from 196 <function>XOpenDisplay</function> for the connection to the X server. 197 </para></listitem> 198 </varlistentry> 199 <varlistentry> 200 <term><parameter>event_base_return</parameter></term> 201 <listitem><para> 202 Pointer to integer where the base value for Composite Extension events 203 will be stored. 204 </para></listitem> 205 </varlistentry> 206 <varlistentry> 207 <term><parameter>error_base_return</parameter></term> 208 <listitem><para> 209 Pointer to integer where the base value for Composite Extension errors 210 will be stored. 211 </para></listitem> 212 </varlistentry> 213 <varlistentry> 214 <term><parameter>major_version_return</parameter></term> 215 <listitem><para> 216 Pointer to integer where the major version of the Composite Extension 217 supported by the X server will be stored. 218 </para></listitem> 219 </varlistentry> 220 <varlistentry> 221 <term><parameter>minor_version_return</parameter></term> 222 <listitem><para> 223 Pointer to integer where the minor version of the Composite Extension 224 supported by the X server will be stored. 225 </para></listitem> 226 </varlistentry> 227 <varlistentry> 228 <term><parameter>window</parameter></term> 229 <listitem><para> 230 Specifies the window ID to operate on. 231 </para></listitem> 232 </varlistentry> 233 <varlistentry> 234 <term><parameter>update</parameter></term> 235 <listitem><para> 236 Specifies the mode for updating the window contents. Must be either 237 <constant>CompositeRedirectAutomatic</constant> or 238 <constant>CompositeRedirectManual</constant>. 239 </para></listitem> 240 </varlistentry> 241 </variablelist> 242</para></refsect1> 243<refsect1><title>Functions</title> 244<para> 245 <variablelist> 246 <varlistentry> 247 <term><function>XCompositeQueryExtension</function></term> 248 <listitem><para> 249 <function>XCompositeQueryExtension</function> determines if the 250 Composite Extension is available on the given display. It returns 251 <constant>True</constant> if the extension is supported, otherwise 252 <constant>False</constant>. If the extension is present, the base 253 values for events and errors are returned, and can be used to 254 decode incoming event and error values. 255 </para></listitem> 256 </varlistentry> 257 <varlistentry> 258 <term><function>XCompositeQueryVersion</function></term> 259 <listitem><para> 260 <function>XCompositeQueryVersion</function> determines if the X Server 261 supports a version of the X Composite Extension which is compatible 262 with the client library. A non-zero Status is returned if a compatible 263 version of the extension is supported, otherwise a zero Status is returned. 264 If the extension is supported, the major and minor version numbers are 265 returned to indicate the level of Composite Extension support. 266 No other XComposite functions (except XCompositeQueryExtension) may be 267 called before this function. If a client violates this rule, the 268 effects of all subsequent XComposite calls that it makes are undefined. 269 </para></listitem> 270 </varlistentry> 271 <varlistentry> 272 <term><function>XCompositeVersion</function></term> 273 <listitem><para> 274 <function>XCompositeVersion</function> returns the version of the 275 X Composite library. The version number is encoded as: 276 <blockquote><para><code language="C"> 277 (major * 10000) + (minor * 100) + revision 278 </code></para></blockquote> 279 </para> 280 <para> 281 For example, version 1.4.6 would be encoded as the integer 10406. 282 </para></listitem> 283 </varlistentry> 284 <varlistentry> 285 <term><function>XCompositeRedirectWindow</function></term> 286 <listitem><para> 287 <function>XCompositeRedirectWindow</function> requests the X server 288 to direct the hierarchy starting at <parameter>window</parameter> to 289 off-screen storage. 290 The <parameter>update</parameter> argument specifies whether 291 the contents are mirrored to the parent window automatically or not. 292 Only one client at a time may specify an update type of 293 <constant>CompositeRedirectManual</constant>, another attempt will 294 result in a <errorname>BadAccess</errorname> error. When all clients 295 enabling redirection terminate, the redirection will automatically be 296 disabled. 297 </para><para> 298 The root window may not be redirected. Doing so results in a 299 <errorname>BadMatch</errorname> error. Specifying an invalid 300 window id will result in a <errorname>BadWindow</errorname> error. 301 </para></listitem> 302 </varlistentry> 303 <varlistentry> 304 <term><function>XCompositeRedirectSubwindows</function></term> 305 <listitem><para> 306 <function>XCompositeRedirectSubwindows</function> requests the X 307 server to redirect hierarchies starting at all current and future 308 children of <parameter>window</parameter> as in 309 <function>XCompositeRedirectWindow</function>. 310 If <parameter>update</parameter> is 311 <constant>CompositeRedirectManual</constant>, then painting of the 312 window background during window manipulation and ClearArea requests 313 is inhibited. 314 </para></listitem> 315 </varlistentry> 316 <varlistentry> 317 <term><function>XCompositeUnredirectWindow</function></term> 318 <listitem><para> 319 <function>XCompositeUnredirectWindow</function> requests the X 320 server to terminate redirection of <parameter>window</parameter>. 321 If the specified window was not selected for redirection by the 322 current client, a <errorname>BadValue</errorname> error results. 323 </para></listitem> 324 </varlistentry> 325 <varlistentry> 326 <term><function>XCompositeUnredirectSubwindows</function></term> 327 <listitem><para> 328 <function>XCompositeUnredirectWindow</function> requests the X 329 server to terminate redirection of all children of 330 <parameter>window</parameter>. 331 If the specified window was not selected for sub-redirection by the 332 current client, a <errorname>BadValue</errorname> error results. 333 </para></listitem> 334 </varlistentry> 335 <varlistentry> 336 <term><function>XCompositeCreateRegionFromBorderClip</function></term> 337 <listitem><para> 338 <function>XCompositeCreateRegionFromBorderClip</function> 339 creates a region containing the "usual" border clip 340 value; that is the area of the window clipped against siblings and 341 the parent. This region can be used to restrict rendering to 342 suitable areas while updating only a single window. The region 343 is copied at the moment the request is executed; future changes 344 to the window hierarchy will not be reflected in this region. 345 </para></listitem> 346 </varlistentry> 347 <varlistentry> 348 <term><function>XCompositeNameWindowPixmap</function></term> 349 <listitem><para> 350 <function>XCompositeNameWindowPixmap</function> creates and returns 351 a pixmap id that serves as a reference to the off-screen storage for 352 <parameter>window</parameter>. This pixmap will remain allocated 353 until freed, even if the window is unmapped, reconfigured or 354 destroyed. However, the window will get a new pixmap allocated each 355 time it is mapped or resized, so this function will need to be 356 reinvoked for the client to continue to refer to the storage holding 357 the current window contents. Generates a 358 <errorname>BadMatch</errorname> error if <parameter>window</parameter> 359 is not redirected or is not visible. 360 </para><para> 361 The X server must support at least version 0.2 of the Composite 362 Extension for <function>XCompositeNameWindowPixmap</function>. 363 </para></listitem> 364 </varlistentry> 365 <varlistentry> 366 <term><function>XCompositeGetOverlayWindow</function></term> 367 <listitem><para> 368 <function>XCompositeGetOverlayWindow</function> returns the window ID 369 of the Composite Overlay Window for 370 the screen specified by the argument <parameter>window</parameter>. 371 This function notifies the X server that the client wishes to use 372 the Composite Overlay Window of this screen. If this 373 Composite Overlay Window has not yet been mapped, it is mapped by this 374 request. 375 </para><para> 376 The Composite Overlay Window for a particular screen will be 377 unmapped when all clients who have called this function have 378 either called <function>XCompositeReleaseOverlayWindow</function> 379 for that screen, or terminated their connection to the X server. 380 </para><para> 381 The X server must support at least version 0.3 of the Composite 382 Extension for <function>XCompositeGetOverlayWindow</function>. 383 </para></listitem> 384 </varlistentry> 385 <varlistentry> 386 <term><function>XCompositeReleaseOverlayWindow</function></term> 387 <listitem><para> 388 This request specifies that the client is no longer using the 389 Composite Overlay Window on the screen specified by the 390 argument <parameter>window</parameter>. A screen's Composite 391 Overlay Window is unmapped when there are no longer any clients using it. 392 </para><para> 393 The X server must support at least version 0.3 of the Composite 394 Extension for <function>XCompositeReleaseOverlayWindow</function>. 395 </para></listitem> 396 </varlistentry> 397 </variablelist> 398</para> 399</refsect1> 400</refentry> 401</reference> 402