Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XCOMPOSITE(3)			 libXcomposite			 XCOMPOSITE(3)

       Xcomposite - X Composite	Extension library

       #include	<X11/extensions/Xcomposite.h>

       Bool XCompositeQueryExtension(Display *dpy, int *event_base_return,
				     int *error_base_return);

       Status XCompositeQueryVersion(Display *dpy, int *major_version_return,
				     int *minor_version_return);

       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);

       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

       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.

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

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

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

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

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

	   Specifies the window	ID to operate on.

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


	   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 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 returns the version of the	X Composite library.
	   The version number is encoded as: (major * 10000) + (minor *	100) +

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


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


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

	   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.

	   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.

       Keith Packard <>
	   Extension specification and implementation

       Deron Johnson <>
	   Overlay Window specification	and implementation

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


Want to link to this manual page? Use this URL:

home | help