>
##iinncclluuddee <
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.
_d_i_s_p_l_a_y
Pointer to the
DDiissppllaayy
structure returned from
XXOOppeennDDiissppllaayy
for the connection to the X server.
_e_v_e_n_t___b_a_s_e_p
Pointer to integer where the base value for Composite Extension events will be stored.
_e_r_r_o_r___b_a_s_e_p
Pointer to integer where the base value for Composite Extension errors will be stored.
_m_a_j_o_r___v_e_r_s_i_o_n_p
Pointer to integer where the major version of the Composite Extension supported by the X server will be stored.
_m_i_n_o_r___v_e_r_s_i_o_n_p
Pointer to integer where the minor version of the Composite Extension supported by the X server will be stored.
_w_i_n_d_o_w
Specifies the window ID to operate on.
_u_p_d_a_t_e
Specifies the mode for updating the window contents. Must be either
CCoommppoossiitteeRReeddiirreeccttAAuuttoommaattiicc
or
CCoommppoossiitteeRReeddiirreeccttMMaannuuaall.
XXCCoommppoossiitteeQQuueerryyEExxtteennssiioonn
XXCCoommppoossiitteeQQuueerryyEExxtteennssiioonn
determines if the Composite Extension is available on the given display. It returns
TTrruuee
if the extension is supported, otherwise
FFaallssee. 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.
XXCCoommppoossiitteeQQuueerryyVVeerrssiioonn
XXCCoommppoossiitteeQQuueerryyVVeerrssiioonn
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.
XXCCoommppoossiitteeVVeerrssiioonn
XXCCoommppoossiitteeVVeerrssiioonn
returns the version of the X Composite library. The version number is encoded as:
(major * 10000) + (minor * 100) + revision
XXCCoommppoossiitteeRReeddiirreeccttWWiinnddooww
XXCCoommppoossiitteeRReeddiirreeccttWWiinnddooww
requests the X server to direct the hierarchy starting at
_w_i_n_d_o_w
to off-screen storage. The
_u_p_d_a_t_e
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
CCoommppoossiitteeRReeddiirreeccttMMaannuuaall, another attempt will result in a
BadAccess
error. When all clients enabling redirection terminate, the redirection will automatically be disabled.
XXCCoommppoossiitteeRReeddiirreeccttSSuubbwwiinnddoowwss
XXCCoommppoossiitteeRReeddiirreeccttSSuubbwwiinnddoowwss
requests the X server to redirect hierarchies starting at all current and future children of
_w_i_n_d_o_w
as in
XXCCoommppoossiitteeRReeddiirreeccttWWiinnddooww. If
_u_p_d_a_t_e
is
CCoommppoossiitteeRReeddiirreeccttMMaannuuaall, then painting of the window background during window manipulation and ClearArea requests is inhibited.
XXCCoommppoossiitteeUUnnrreeddiirreeccttWWiinnddooww
XXCCoommppoossiitteeUUnnrreeddiirreeccttWWiinnddooww
requests the X server to terminate redirection of
_w_i_n_d_o_w. If the specified window was not selected for redirection by the current client, a
BadValue
error results.
XXCCoommppoossiitteeUUnnrreeddiirreeccttSSuubbwwiinnddoowwss
XXCCoommppoossiitteeUUnnrreeddiirreeccttWWiinnddooww
requests the X server to terminate redirection of all children of
_w_i_n_d_o_w. If the specified window was not selected for sub-redirection by the current client, a
BadValue
error results.
XXCCoommppoossiitteeCCrreeaatteeRReeggiioonnFFrroommBBoorrddeerrCClliipp
XXCCoommppoossiitteeCCrreeaatteeRReeggiioonnFFrroommBBoorrddeerrCClliipp
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.
XXCCoommppoossiitteeNNaammeeWWiinnddoowwPPiixxmmaapp
XXCCoommppoossiitteeNNaammeeWWiinnddoowwPPiixxmmaapp
creates and returns a pixmap id that serves as a reference to the off-screen storage for
_w_i_n_d_o_w. 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
_w_i_n_d_o_w
is not redirected or is not visible.
XXCCoommppoossiitteeGGeettOOvveerrllaayyWWiinnddooww
XXCCoommppoossiitteeGGeettOOvveerrllaayyWWiinnddooww
returns the window ID of the Composite Overlay Window for the screen specified by the argument
_w_i_n_d_o_w. 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.
XXCCoommppoossiitteeRReelleeaasseeOOvveerrllaayyWWiinnddooww
This request specifies that the client is no longer using the Composite Overlay Window on the screen specified by the argument
_w_i_n_d_o_w. A screen's Composite Overlay Window is unmapped when there are no longer any clients using it.
KKeeiitthh PPaacckkaarrdd
DDeerroonn JJoohhnnssoonn
DESCRIPTION
ARGUMENTS
FUNCTIONS
For example, version 1.4.6 would be encoded as the integer 10406.
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.
The X server must support at least version 0.2 of the Composite Extension for
XXCCoommppoossiitteeNNaammeeWWiinnddoowwPPiixxmmaapp.
The Composite Overlay Window for a particular screen will be unmapped when all clients who have called this function have either called
XXCCoommppoossiitteeRReelleeaasseeOOvveerrllaayyWWiinnddooww
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
XXCCoommppoossiitteeGGeettOOvveerrllaayyWWiinnddooww.
The X server must support at least version 0.3 of the Composite Extension for
XXCCoommppoossiitteeRReelleeaasseeOOvveerrllaayyWWiinnddooww.
AUTHORS