This manual page is for Mac OS X version 10.6.3

Reading manual pages

XCOMPOSITE(3)                                   X Version 11                                   XCOMPOSITE(3)



NAME
       Xcomposite - X Composite Extension library

SYNOPSIS
       #include <X11/extensions/Xcomposite.h>

       Bool XCompositeQueryExtension(Display *dpy, int *event_basep, int *error_basep);

       Status XCompositeQueryVersion(Display *dpy, int *major_versionp, int *minor_versionp);

       int XCompositeVersion(void);

       void XCompositeRedirectWindow(Display *dpy, Window window, int update);

       void XCompositeRedirectSubwindows(Display *dpy, Window window, int update);

       void XCompositeUnredirectWindow(Display *dpy, Window window, int update);

       void XCompositeUnredirectSubwindows(Display *dpy, Window window, int update);

       XserverRegion XCompositeCreateRegionFromBorderClip(Display *dpy, Window window);

       Pixmap XCompositeNameWindowPixmap(Display *dpy, Window window);

       Window XCompositeGetOverlayWindow(Display *dpy, Window window);

       void XCompositeReleaseOverlayWindow(Display *dpy, Window window);

DESCRIPTION
       The composite extension provides several related mechanisms:

       Per-hierarchy storage
           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.

       Automatic shadow update
           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.

       Composite Overlay Window
           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.

       Parent window clipping
           Version 0.4 of the protocol modifies the semantics of parent window clipping in the presence of
           manual redirected children. With this version, the area in the parent covered by manual
           redirected children is left in the parent clip list instead of being removed as in older
           versions.

       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.

       The off-screen storage includes the window contents, its borders and the contents of all descendants.

ARGUMENTS
       display
           Pointer to the Display structure returned from XOpenDisplay for the connection to the X server.

       event_basep
           Pointer to integer where the base value for Composite Extension events will be stored.

       error_basep
           Pointer to integer where the base value for Composite Extension errors will be stored.

       major_versionp
           Pointer to integer where the major version of the Composite Extension supported by the X server
           will be stored.

       minor_versionp
           Pointer to integer where the minor version of the Composite Extension supported by the X server
           will be stored.

       window
           Specifies the window ID to operate on.

       update
           Specifies the mode for updating the window contents. Must be either CompositeRedirectAutomatic or
           CompositeRedirectManual.

FUNCTIONS
       XCompositeQueryExtension

           XCompositeQueryExtension determines if the Composite Extension is available on the given display.
           It returns True if the extension is supported, otherwise False. 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.

       XCompositeQueryVersion

           XCompositeQueryVersion 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.

       XCompositeVersion

           XCompositeVersion returns the version of the X Composite library. The version number is encoded
           as: (major * 10000) + (minor * 100) + revision

           For example, version 1.4.6 would be encoded as the integer 10406.

       XCompositeRedirectWindow

           XCompositeRedirectWindow requests the X server to direct the hierarchy starting at window to
           off-screen storage. The update 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
           CompositeRedirectManual, another attempt will result in a BadAccess error. When all clients
           enabling redirection terminate, the redirection will automatically be disabled.

           The root window may not be redirected. Doing so results in a BadMatch error. Specifying an
           invalid window id will result in a BadWindow error.

       XCompositeRedirectSubwindows

           XCompositeRedirectSubwindows requests the X server to redirect hierarchies starting at all
           current and future children of window as in XCompositeRedirectWindow. If update is
           CompositeRedirectManual, then painting of the window background during window manipulation and
           ClearArea requests is inhibited.

       XCompositeUnredirectWindow

           XCompositeUnredirectWindow requests the X server to terminate redirection of window. If the
           specified window was not selected for redirection by the current client, a BadValue error
           results.

       XCompositeUnredirectSubwindows

           XCompositeUnredirectWindow requests the X server to terminate redirection of all children of
           window. If the specified window was not selected for sub-redirection by the current client, a
           BadValue error results.

       XCompositeCreateRegionFromBorderClip

           XCompositeCreateRegionFromBorderClip 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.

       XCompositeNameWindowPixmap

           XCompositeNameWindowPixmap creates and returns a pixmap id that serves as a reference to the
           off-screen storage for window. 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 BadMatch error
           if window is not redirected or is not visible.

           The X server must support at least version 0.2 of the Composite Extension for
           XCompositeNameWindowPixmap.

       XCompositeGetOverlayWindow

           XCompositeGetOverlayWindow returns the window ID of the Composite Overlay Window for the screen
           specified by the argument window. 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.

           The Composite Overlay Window for a particular screen will be unmapped when all clients who have
           called this function have either called XCompositeReleaseOverlayWindow for that screen, or
           terminated their connection to the X server.

           The X server must support at least version 0.3 of the Composite Extension for
           XCompositeGetOverlayWindow.

       XCompositeReleaseOverlayWindow
           This request specifies that the client is no longer using the Composite Overlay Window on the
           screen specified by the argument window. A screen's Composite Overlay Window is unmapped when
           there are no longer any clients using it.

           The X server must support at least version 0.3 of the Composite Extension for
           XCompositeReleaseOverlayWindow.

AUTHORS
       Keith Packard <keithp@keithp.com>
           Extension specification and implementation

       Deron Johnson <deron.johnson@sun.com>
           Overlay Window specification and implementation




libXcomposite 0.4.0                   <pubdate>23 April 2007</pubdate>                         XCOMPOSITE(3)