From 0e1ac54142d49051da9a74f37a792225a4e8d7b0 Mon Sep 17 00:00:00 2001 From: marha Date: Sun, 5 Jun 2011 16:00:23 +0200 Subject: libX11 libXext libXmu mesa xkeyboard-config git update Jun 2011 --- libXext/specs/dbelib.xml | 1456 +++++++++++++++++++-------------------- libXext/specs/dpmslib.xml | 838 +++++++++++------------ libXext/specs/shapelib.xml | 1154 +++++++++++++++---------------- libXext/specs/synclib.xml | 1626 ++++++++++++++++++++++---------------------- 4 files changed, 2537 insertions(+), 2537 deletions(-) (limited to 'libXext') diff --git a/libXext/specs/dbelib.xml b/libXext/specs/dbelib.xml index c786cae81..5a969a287 100644 --- a/libXext/specs/dbelib.xml +++ b/libXext/specs/dbelib.xml @@ -1,728 +1,728 @@ - - - - - - - - - Double Buffer Extension Library - X Consortium Standard - - - - IanElliot - - - - DavideWiggins - - Hewlett-Packard Company - 1989X Consortium, Inc and Digital Equipment Corporation - 1992X Consortium, Inc and Intergraph Corporation - 1993X Consortium, Inc and Silicon Graphics, Inc. - 1994X Consortium, Inc and Hewlett-Packard Company - 1995X Consortium, Inc and Hewlett-Packard Company - Version 1.0 - X Consortium - X Version 11, Release 7 - - - -Permission to use, copy, modify, and distribute this documentation for any -purpose and without fee is hereby granted, provided that the above copyright -notice and this permission notice appear in all copies. Digital Equipment -Corporation, Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and -the X Consortium make no representations about the suitability for any -purpose of the information in this document. This documentation is provided -"as is" without express or implied warranty. - - - - - - - -Introduction - -The Double Buffer Extension (DBE) provides a standard way to utilize -double-buffering within the framework of the X Window System. -Double-buffering uses two buffers, called front and back, which hold images. -The front buffer is visible to the user; the back buffer is not. Successive -frames of an animation are rendered into the back buffer while the previously -rendered frame is displayed in the front buffer. When a new frame is ready, -the back and front buffers swap roles, making the new frame visible. Ideally, -this exchange appears to happen instantaneously to the user and with no -visual artifacts. Thus, only completely rendered images are presented to the -user, and they remain visible during the entire time it takes to render a new -frame. The result is a flicker-free animation. - - - - - -Goals - - -This extension should enable clients to: - - - - -Allocate and deallocate double-buffering for a window. - - - - -Draw to and read from the front and back buffers associated with a window. - - - - -Swap the front and back buffers associated with a window. - - - - -Specify a wide range of actions to be taken when a window is swapped. -This includes explicit, simple swap actions (defined below), and more -complex actions (for example, clearing ancillary buffers) that can be put -together within explicit "begin" and "end" requests (defined below). - - - - -Request that the front and back buffers associated with multiple -double-buffered windows be swapped simultaneously. - - - - - -In addition, the extension should: - - - - -Allow multiple clients to use double-buffering on the same window. - - - - -Support a range of implementation methods that can capitalize on -existing hardware features. - - - - -Add no new event types. - - - - -Be reasonably easy to integrate with a variety of direct graphics -hardware access (DGHA) architectures. - - - - - - - -Concepts - -Normal windows are created using the core CreateWindow request, which -allocates a set of window attributes and, for InputOutput windows, a front -buffer, into which an image can be drawn. The contents of this buffer will be -displayed when the window is visible. - - -This extension enables applications to use double-buffering with a window. -This involves creating a second buffer, called a back buffer, and associating -one or more back buffer names (XIDs) with the window for use when referring -to (that is, drawing to or reading from) the window’s back buffer. The back -buffer name is a DRAWABLE of type BACKBUFFER. - - -DBE provides a relative double-buffering model. One XID, the window, -always refers to the front buffer. One or more other XIDs, the back buffer -names, always refer to the back buffer. After a buffer swap, the window -continues to refer to the (new) front buffer, and the back buffer name -continues to refer to the (new) back buffer. Thus, applications and toolkits -that want to just render to the back buffer always use the back buffer name -for all drawing requests to the window. Portions of an application that want -to render to the front buffer always use the window XID for all drawing -requests to the window. - - -Multiple clients and toolkits can all use double-buffering on the same window. -DBE does not provide a request for querying whether a window has -double-buffering support, and if so, what the back buffer name is. Given the -asynchronous nature of the X Window System, this would cause race -conditions. Instead, DBE allows multiple back buffer names to exist for the -same window; they all refer to the same physical back buffer. The first time a -back buffer name is allocated for a window, the window becomes -double-buffered and the back buffer name is associated with the window. -Subsequently, the window already is a double-buffered window, and nothing -about the window changes when a new back buffer name is allocated, except -that the new back buffer name is associated with the window. The window -remains double-buffered until either the window is destroyed or until all of the -back buffer names for the window are deallocated. - - -In general, both the front and back buffers are treated the same. -particular, here are some important characteristics: - - - - -Only one buffer per window can be visible at a time (the front buffer). - - - - -Both buffers associated with a window have the same visual type, depth, -width, height, and shape as the window. - - - - -Both buffers associated with a window are "visible" (or "obscured") in -the same way. When an Expose event is generated for a window, both -buffers should be considered to be damaged in the exposed area. -Damage that occurs to either buffer will result in an Expose event on -the window. When a double-buffered window is exposed, both buffers -are tiled with the window background, exactly as stated by the core -protocol. Even though the back buffer is not visible, terms such as -obscure apply to the back buffer as well as to the front buffer. - - - - -It is acceptable at any time to pass a BACKBUFFER in any request, -notably any core or extension drawing request, that expects a -DRAWABLE. This enables an application to draw directly into -BACKBUFFERs in the same fashion as it would draw into any other -DRAWABLE. - - - - -It is an error (Window) to pass a BACKBUFFER in a core request that -expects a Window. - - - - -A BACKBUFFER will never be sent by core X in a reply, event, or -error where a Window is specified. - - - - -If core X11 backing-store and save-under applies to a double-buffered -window, it applies to both buffers equally. - - - - -If the core ClearArea request is executed on a double-buffered window, -the same area in both the front and back buffers is cleared. - - - - - -The effect of passing a window to a request that accepts a -DRAWABLE is -unchanged by this extension. The window and front buffer are synonomous -with each other. This includes obeying the GetImage -semantics and the -subwindow-mode semantics if a core graphics context is involved. Regardless -of whether the window was explicitly passed in a -GetImage request, or -implicitly referenced (that is, one of the window’s ancestors was passed in the -request), the front (that is, visible) buffer is always referenced. Thus, -DBE-naive screen dump clients will always get the front buffer. -GetImage on -a back buffer returns undefined image contents for any obscured regions of the -back buffer that fall within the image. - - -Drawing to a back buffer always uses the clip region that would be used to -draw to the front buffer with a GC subwindow-mode of -ClipByChildren. If -an ancestor of a double-buffered window is drawn to with a core GC having a -subwindow-mode of IncludeInferiors, the effect on the double-buffered -window’s back buffer depends on the depth of the double-buffered window -and the ancestor. If the depths are the same, the contents of the back buffer -of the double-buffered window are not changed. If the depths are different, -the contents of the back buffer of the double-buffered window are undefined -for the pixels that the IncludeInferiors drawing touched. - - - - -DBE adds no new events. DBE does not extend the semantics of any existing -events with the exception of adding a new DRAWABLE type called -BACKBUFFER. If events, replies, or errors that contain a DRAWABLE (for -example, GraphicsExpose) are generated in response to -a request, the -DRAWABLE returned will be the one specified in the request. - - -DBE advertises which visuals support double-buffering. - - -DBE does not include any timing or synchronization facilities. Applications -that need such facilities (for example, to maintain a constant frame rate) -should investigate the Synchronization Extension, an X Consortium standard. - - - -Window Management Operations - - -The basic philosophy of DBE is that both buffers are treated the same by core -X window management operations. - - -When the core DestroyWindow is executed on a -double-buffered window, both buffers associated with the window are -destroyed, and all back buffer names associated with the window are freed. - - -If the core ConfigureWindow request changes the size -of a window, both buffers assume the new size. If the window’s size -increases, the effect on the buffers depends on whether the implementation -honors bit gravity for buffers. -If bit gravity is implemented, then the contents of both buffers are moved in -accordance with the window’s bit gravity (see the core -ConfigureWindow -request), and the remaining areas are tiled with the window background. If -bit gravity is not implemented, then the entire unobscured region of both -buffers is tiled with the window background. In either case, -Expose events are -generated for the region that is tiled with the window background. -If the core GetGeometry request is executed on a BACKBUFFER, the -returned x, y, and border-width will be zero. - - -If the Shape extension -ShapeRectangles, -ShapeMask, -ShapeCombine, or -ShapeOffset -request is executed on a double-buffered window, both buffers -are reshaped to match the new window shape. The region difference is the -following: - - - - D = newshape − oldshape - - - -It is tiled with the window background in both buffers, and -Expose -events are generated for D. - - - - - -Complex Swap Actions - -DBE has no explicit knowledge of ancillary buffers (for example, depth buffers -or alpha buffers), and only has a limited set of defined swap actions. Some -applications may need a richer set of swap actions than DBE provides. Some -DBE implementations have knowledge of ancillary buffers, and/or can provide -a rich set of swap actions. Instead of continually extending DBE to increase -its set of swap actions, DBE provides a flexible "idiom" mechanism. If an -application’s needs are served by the defined swap actions, it should use them; -otherwise, it should use the following method of expressing a complex swap -action as an idiom. Following this policy will ensure the best possible -performance across a wide variety of implementations. - - -As suggested by the term "idiom," a complex swap action should be expressed -as a group/series of requests. Taken together, this group of requests may be -combined into an atomic operation by the implementation, in order to -maximize performance. The set of idioms actually recognized for optimization -is implementation dependent. -To help with idiom expression and -interpretation, an idiom must be surrounded by two protocol requests: -DBEBeginIdiom and DBEEndIdiom. -Unless this begin-end pair surrounds the idiom, it may not be recognized -by a given implementation, and performance will suffer. - - -For example, if an application wants to swap buffers for two windows, and use -core X to clear only certain planes of the back buffers, the application would -issue the following protocol requests as a group, and in the following order: - - - - - -DBEBeginIdiom request. - - - - -DBESwapBuffers request with XIDs for two windows, each of which uses -a swap action of Untouched. - - - - -Core X PolyFillRectangle request to the back buffer of one window. - - - - -Core X PolyFillRectangle request to the back buffer of the other -window. - - - - -DBEEndIdiom request. - - - - - -The DBEBeginIdiom and DBEEndIdiom -requests do not perform any actions -themselves. They are treated as markers by implementations that can -combine certain groups/series of requests as idioms, and are ignored by other -implementations or for nonrecognized groups/series of requests. If these -requests are sent out of order, or are mismatched, no errors are sent, and the -requests are executed as usual, though performance may suffer. - - - - -An idiom need not include a DBESwapBuffers request. -For example, if a swap action of Copied is desired, -but only some of the planes should be copied, a core X -CopyArea request may be used instead of -DBESwapBuffers. If -DBESwapBuffers is included in an idiom, it should -immediately follow the -DBEBeginIdiom request. Also, when the -DBESwapBuffers is included in an idiom, that -request’s swap action will still be valid, and if the swap action -might overlap with another request, then the final result of the idiom must be -as if the separate requests were executed serially. For example, if the -specified swap action is Untouched, and if a -PolyFillRectangle using a client clip -rectangle is done to the window’s back buffer after the -DBESwapBuffers request, then the contents of the new -back buffer (after the idiom) will be the -same as if the idiom was not recognized by the implementation. - - -It is highly recommended that Application Programming Interface (API) -providers define, and application developers use, "convenience" functions that -allow client applications to call one procedure that encapsulates common -idioms. These functions will generate the -DBEBeginIdiom request, the idiom -requests, and DBEEndIdiom request. Usage of these -functions will ensure best possible performance across a wide -variety of implementations. - - - - - - -C Language Binding - -All identifier The header for this extension is <X11/extensions/Xdbe.h>. -names provided by this header begin with Xdbe. - - - -Types - - -The type XdbeBackBuffer is a Drawable. - - - -The type XdbeSwapAction can be one of the constants -XdbeUndefined, -XdbeBackground, -XdbeUntouched, or -XdbeCopied. - - - - - -C Functions - -The C functions provide direct access to the protocol and add no additional -semantics. For complete details on the effects of these functions, refer to the -appropriate protocol request, which can be derived by replacing Xdbe at the -start of the function name with DBE. All functions that have return type -Status will return nonzero for success and -zero for failure. - - - - - Status XdbeQueryExtension - Display *dpy - int *major_version_return - int *minor_version_return - - - - -XdbeQueryExtension sets major version return and minor -version return to the major and minor DBE protocol version supported by -the server. If the DBE library is compatible with the version returned by -the server, it returns nonzero. If dpy does not support the DBE extension, -or if there was an error during communication with the server, or if the -server and library protocol versions are incompatible, it returns zero. -No other Xdbe functions may be called before this function. If a client -violates this rule, the effects of all subsequent Xdbe calls that it makes -are undefined. - - - - - XdbeScreenVisualInfo *XdbeGetVisualInfo - Display *dpy - Drawable *screen_specifiers - int *num_screens - - - - - -XdbeGetVisualInfo returns information about which -visuals support double buffering. The argument num_screens specifies how -many elements there are in the screen_specifiers list. Each drawable in -screen_specifiers designates a screen for which the supported visuals are -being requested. If num_screens is zero, information for all screens is -requested. In this case, upon return from this function, num_screens will -be set to the number of screens that were found. If an error occurs, -this function returns NULL; otherwise, it returns a pointer to a list of -XdbeScreenVisualInfo -structures of length num_screens. The nth element in the returned list -corresponds to the nth drawable in the screen_specifiers list, unless - -element in the returned list corresponds to the nth screen of the server, -starting with screen zero. - - - - -The XdbeScreenVisualInfo structure has the following fields: - - -int count number of items in visinfo -XdbeVisualInfo* visinfo list of visuals and depths for this screen - - - -The XdbeVisualInfo structure has the following fields: - - - -VisualID visual one visual ID that supports double-buffering -int depth depth of visual in bits -int perflevel performance level of visual - - - - - - void XdbeFreeVisualInfo XdbeGetVisualInfo - XdbeScreenVisualInfo *visual_info - - - - -XdbeFreeVisualInfo frees the list of -XdbeScreenVisualInfo returned by -XdbeGetVisualInfo. - - - - - - XdbeBackBuffer XdbeAllocateBackBufferName - Display *dpy - Window *window - XdbeSwapAction swap_action - - - - - -XdbeAllocateBackBufferName returns a drawable ID used -to refer to the back buffer of the specified window. The swap_action is a -hint to indicate the swap_action that will likely be used in subsequent -calls to XdbeSwapBuffers. The actual swap_action -used in calls to XdbeSwapBuffers does not have to be -the same as the swap_action passed to this function, though clients are -encouraged to provide accurate information whenever possible. - - - - - Status XdbeDeallocateBackBufferName - Display *dpy - XdbeBackBuffer buffer - - - - -XdbeDeallocateBackBufferName frees the specified -drawable ID, buffer, that was obtained via -XdbeAllocateBackBufferName. The buffer must be a valid -name for the back buffer of a window, or an -XdbeBadBuffer error results. - - - - - Status XdbeSwapBuffers - Display *dpy - XdbeSwapInfo *swap_info - int num_windows - - - - -XdbeSwapBuffers swaps the front and back buffers -for a list of windows. The argument num_windows specifies how many windows -are to have their buffers swapped; it is the number of elements in the -swap_info array. The argument swap_info specifies the information needed -per window to do the swap. - - -The XdbeSwapInfo structure has the following fields: - - - -Window swap_window window for which to swap buffers -XdbeSwapAction swap_action swap action to use for this swap window - - - - - Status XdbeBeginIdiom - Display *dpy - - - - -XdbeBeginIdiom marks the beginning of an idiom -sequence. See - - -for a complete discussion of idioms. - - - - - Status XdbeEndIdiom - Display *dpy - - - - -XdbeEndIdiom marks the end of an idiom sequence. - - - - - XdbeBackBufferAttributes *XdbeGetBackBufferAttributes - Display *dpy - XdbeBackBuffer buffer - - - - -XdbeGetBackBufferAttributes returns the attributes associated with -the specified buffer. - - -The XdbeBackBufferAttributes structure has the following fields: - - - -Window window window that buffer belongs to - - - -If buffer is not a valid XdbeBackBuffer, window is -set to None. - - -The returned XdbeBackBufferAttributes structure -can be freed with the Xlib function XFree. - - - - -Errors - -The XdbeBufferError structure has the following fields: - - -int type -Display * display Display the event was read from -XdbeBackBuffer buffer resource id -unsigned long serial serial number of failed request -unsigned char error code error base + XdbeBadBuffer -unsigned char request code Major op-code of failed request -unsigned char minor code Minor op-code of failed request - - - - - -Acknowledgements - - -We wish to thank the following individuals who have contributed their time -and talent toward shaping the DBE specification: - - -T. Alex Chen, IBM; Peter Daifuku, Silicon Graphics, Inc.; Ian Elliott, -Hewlett-Packard Company; Stephen Gildea, X Consortium, Inc.; Jim Graham, -Sun; Larry Hare, AGE Logic; Jay Hersh, X Consortium, Inc.; Daryl Huff, -Sun; Deron Dann Johnson, Sun; Louis Khouw, Sun; Mark Kilgard, Silicon -Graphics, Inc.; Rob Lembree, Digital Equipment Corporation; Alan Ricker, -Metheus; Michael Rosenblum, Digital Equipment Corporation; Bob Scheifler, -X Consortium, Inc.; Larry Seiler, Digital Equipment Corporation; Jeanne -Sparlin Smith, IBM; Jeff Stevenson, Hewlett-Packard Company; Walter -Strand, Metheus; Ken Tidwell, Hewlett-Packard Company; and David P. -Wiggins, X Consortium, Inc. - - -Mark provided the impetus to start the DBE project. Ian wrote the first draft -of the specification. David served as architect. - - - - -References - -Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension -Specification Version 3.3." - - -Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, "X -Synchronization Extension Version 3.0." - - - + + + + + + + + + Double Buffer Extension Library + X Consortium Standard + + + + IanElliot + + + + DavideWiggins + + Hewlett-Packard Company + 1989X Consortium, Inc and Digital Equipment Corporation + 1992X Consortium, Inc and Intergraph Corporation + 1993X Consortium, Inc and Silicon Graphics, Inc. + 1994X Consortium, Inc and Hewlett-Packard Company + 1995X Consortium, Inc and Hewlett-Packard Company + Version 1.0 + X Consortium + X Version 11, Release 7 + + + +Permission to use, copy, modify, and distribute this documentation for any +purpose and without fee is hereby granted, provided that the above copyright +notice and this permission notice appear in all copies. Digital Equipment +Corporation, Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and +the X Consortium make no representations about the suitability for any +purpose of the information in this document. This documentation is provided +"as is" without express or implied warranty. + + + + + + + +Introduction + +The Double Buffer Extension (DBE) provides a standard way to utilize +double-buffering within the framework of the X Window System. +Double-buffering uses two buffers, called front and back, which hold images. +The front buffer is visible to the user; the back buffer is not. Successive +frames of an animation are rendered into the back buffer while the previously +rendered frame is displayed in the front buffer. When a new frame is ready, +the back and front buffers swap roles, making the new frame visible. Ideally, +this exchange appears to happen instantaneously to the user and with no +visual artifacts. Thus, only completely rendered images are presented to the +user, and they remain visible during the entire time it takes to render a new +frame. The result is a flicker-free animation. + + + + + +Goals + + +This extension should enable clients to: + + + + +Allocate and deallocate double-buffering for a window. + + + + +Draw to and read from the front and back buffers associated with a window. + + + + +Swap the front and back buffers associated with a window. + + + + +Specify a wide range of actions to be taken when a window is swapped. +This includes explicit, simple swap actions (defined below), and more +complex actions (for example, clearing ancillary buffers) that can be put +together within explicit "begin" and "end" requests (defined below). + + + + +Request that the front and back buffers associated with multiple +double-buffered windows be swapped simultaneously. + + + + + +In addition, the extension should: + + + + +Allow multiple clients to use double-buffering on the same window. + + + + +Support a range of implementation methods that can capitalize on +existing hardware features. + + + + +Add no new event types. + + + + +Be reasonably easy to integrate with a variety of direct graphics +hardware access (DGHA) architectures. + + + + + + + +Concepts + +Normal windows are created using the core CreateWindow request, which +allocates a set of window attributes and, for InputOutput windows, a front +buffer, into which an image can be drawn. The contents of this buffer will be +displayed when the window is visible. + + +This extension enables applications to use double-buffering with a window. +This involves creating a second buffer, called a back buffer, and associating +one or more back buffer names (XIDs) with the window for use when referring +to (that is, drawing to or reading from) the window’s back buffer. The back +buffer name is a DRAWABLE of type BACKBUFFER. + + +DBE provides a relative double-buffering model. One XID, the window, +always refers to the front buffer. One or more other XIDs, the back buffer +names, always refer to the back buffer. After a buffer swap, the window +continues to refer to the (new) front buffer, and the back buffer name +continues to refer to the (new) back buffer. Thus, applications and toolkits +that want to just render to the back buffer always use the back buffer name +for all drawing requests to the window. Portions of an application that want +to render to the front buffer always use the window XID for all drawing +requests to the window. + + +Multiple clients and toolkits can all use double-buffering on the same window. +DBE does not provide a request for querying whether a window has +double-buffering support, and if so, what the back buffer name is. Given the +asynchronous nature of the X Window System, this would cause race +conditions. Instead, DBE allows multiple back buffer names to exist for the +same window; they all refer to the same physical back buffer. The first time a +back buffer name is allocated for a window, the window becomes +double-buffered and the back buffer name is associated with the window. +Subsequently, the window already is a double-buffered window, and nothing +about the window changes when a new back buffer name is allocated, except +that the new back buffer name is associated with the window. The window +remains double-buffered until either the window is destroyed or until all of the +back buffer names for the window are deallocated. + + +In general, both the front and back buffers are treated the same. +particular, here are some important characteristics: + + + + +Only one buffer per window can be visible at a time (the front buffer). + + + + +Both buffers associated with a window have the same visual type, depth, +width, height, and shape as the window. + + + + +Both buffers associated with a window are "visible" (or "obscured") in +the same way. When an Expose event is generated for a window, both +buffers should be considered to be damaged in the exposed area. +Damage that occurs to either buffer will result in an Expose event on +the window. When a double-buffered window is exposed, both buffers +are tiled with the window background, exactly as stated by the core +protocol. Even though the back buffer is not visible, terms such as +obscure apply to the back buffer as well as to the front buffer. + + + + +It is acceptable at any time to pass a BACKBUFFER in any request, +notably any core or extension drawing request, that expects a +DRAWABLE. This enables an application to draw directly into +BACKBUFFERs in the same fashion as it would draw into any other +DRAWABLE. + + + + +It is an error (Window) to pass a BACKBUFFER in a core request that +expects a Window. + + + + +A BACKBUFFER will never be sent by core X in a reply, event, or +error where a Window is specified. + + + + +If core X11 backing-store and save-under applies to a double-buffered +window, it applies to both buffers equally. + + + + +If the core ClearArea request is executed on a double-buffered window, +the same area in both the front and back buffers is cleared. + + + + + +The effect of passing a window to a request that accepts a +DRAWABLE is +unchanged by this extension. The window and front buffer are synonomous +with each other. This includes obeying the GetImage +semantics and the +subwindow-mode semantics if a core graphics context is involved. Regardless +of whether the window was explicitly passed in a +GetImage request, or +implicitly referenced (that is, one of the window’s ancestors was passed in the +request), the front (that is, visible) buffer is always referenced. Thus, +DBE-naive screen dump clients will always get the front buffer. +GetImage on +a back buffer returns undefined image contents for any obscured regions of the +back buffer that fall within the image. + + +Drawing to a back buffer always uses the clip region that would be used to +draw to the front buffer with a GC subwindow-mode of +ClipByChildren. If +an ancestor of a double-buffered window is drawn to with a core GC having a +subwindow-mode of IncludeInferiors, the effect on the double-buffered +window’s back buffer depends on the depth of the double-buffered window +and the ancestor. If the depths are the same, the contents of the back buffer +of the double-buffered window are not changed. If the depths are different, +the contents of the back buffer of the double-buffered window are undefined +for the pixels that the IncludeInferiors drawing touched. + + + + +DBE adds no new events. DBE does not extend the semantics of any existing +events with the exception of adding a new DRAWABLE type called +BACKBUFFER. If events, replies, or errors that contain a DRAWABLE (for +example, GraphicsExpose) are generated in response to +a request, the +DRAWABLE returned will be the one specified in the request. + + +DBE advertises which visuals support double-buffering. + + +DBE does not include any timing or synchronization facilities. Applications +that need such facilities (for example, to maintain a constant frame rate) +should investigate the Synchronization Extension, an X Consortium standard. + + + +Window Management Operations + + +The basic philosophy of DBE is that both buffers are treated the same by core +X window management operations. + + +When the core DestroyWindow is executed on a +double-buffered window, both buffers associated with the window are +destroyed, and all back buffer names associated with the window are freed. + + +If the core ConfigureWindow request changes the size +of a window, both buffers assume the new size. If the window’s size +increases, the effect on the buffers depends on whether the implementation +honors bit gravity for buffers. +If bit gravity is implemented, then the contents of both buffers are moved in +accordance with the window’s bit gravity (see the core +ConfigureWindow +request), and the remaining areas are tiled with the window background. If +bit gravity is not implemented, then the entire unobscured region of both +buffers is tiled with the window background. In either case, +Expose events are +generated for the region that is tiled with the window background. +If the core GetGeometry request is executed on a BACKBUFFER, the +returned x, y, and border-width will be zero. + + +If the Shape extension +ShapeRectangles, +ShapeMask, +ShapeCombine, or +ShapeOffset +request is executed on a double-buffered window, both buffers +are reshaped to match the new window shape. The region difference is the +following: + + + + D = newshape − oldshape + + + +It is tiled with the window background in both buffers, and +Expose +events are generated for D. + + + + + +Complex Swap Actions + +DBE has no explicit knowledge of ancillary buffers (for example, depth buffers +or alpha buffers), and only has a limited set of defined swap actions. Some +applications may need a richer set of swap actions than DBE provides. Some +DBE implementations have knowledge of ancillary buffers, and/or can provide +a rich set of swap actions. Instead of continually extending DBE to increase +its set of swap actions, DBE provides a flexible "idiom" mechanism. If an +application’s needs are served by the defined swap actions, it should use them; +otherwise, it should use the following method of expressing a complex swap +action as an idiom. Following this policy will ensure the best possible +performance across a wide variety of implementations. + + +As suggested by the term "idiom," a complex swap action should be expressed +as a group/series of requests. Taken together, this group of requests may be +combined into an atomic operation by the implementation, in order to +maximize performance. The set of idioms actually recognized for optimization +is implementation dependent. +To help with idiom expression and +interpretation, an idiom must be surrounded by two protocol requests: +DBEBeginIdiom and DBEEndIdiom. +Unless this begin-end pair surrounds the idiom, it may not be recognized +by a given implementation, and performance will suffer. + + +For example, if an application wants to swap buffers for two windows, and use +core X to clear only certain planes of the back buffers, the application would +issue the following protocol requests as a group, and in the following order: + + + + + +DBEBeginIdiom request. + + + + +DBESwapBuffers request with XIDs for two windows, each of which uses +a swap action of Untouched. + + + + +Core X PolyFillRectangle request to the back buffer of one window. + + + + +Core X PolyFillRectangle request to the back buffer of the other +window. + + + + +DBEEndIdiom request. + + + + + +The DBEBeginIdiom and DBEEndIdiom +requests do not perform any actions +themselves. They are treated as markers by implementations that can +combine certain groups/series of requests as idioms, and are ignored by other +implementations or for nonrecognized groups/series of requests. If these +requests are sent out of order, or are mismatched, no errors are sent, and the +requests are executed as usual, though performance may suffer. + + + + +An idiom need not include a DBESwapBuffers request. +For example, if a swap action of Copied is desired, +but only some of the planes should be copied, a core X +CopyArea request may be used instead of +DBESwapBuffers. If +DBESwapBuffers is included in an idiom, it should +immediately follow the +DBEBeginIdiom request. Also, when the +DBESwapBuffers is included in an idiom, that +request’s swap action will still be valid, and if the swap action +might overlap with another request, then the final result of the idiom must be +as if the separate requests were executed serially. For example, if the +specified swap action is Untouched, and if a +PolyFillRectangle using a client clip +rectangle is done to the window’s back buffer after the +DBESwapBuffers request, then the contents of the new +back buffer (after the idiom) will be the +same as if the idiom was not recognized by the implementation. + + +It is highly recommended that Application Programming Interface (API) +providers define, and application developers use, "convenience" functions that +allow client applications to call one procedure that encapsulates common +idioms. These functions will generate the +DBEBeginIdiom request, the idiom +requests, and DBEEndIdiom request. Usage of these +functions will ensure best possible performance across a wide +variety of implementations. + + + + + + +C Language Binding + +All identifier The header for this extension is <X11/extensions/Xdbe.h>. +names provided by this header begin with Xdbe. + + + +Types + + +The type XdbeBackBuffer is a Drawable. + + + +The type XdbeSwapAction can be one of the constants +XdbeUndefined, +XdbeBackground, +XdbeUntouched, or +XdbeCopied. + + + + + +C Functions + +The C functions provide direct access to the protocol and add no additional +semantics. For complete details on the effects of these functions, refer to the +appropriate protocol request, which can be derived by replacing Xdbe at the +start of the function name with DBE. All functions that have return type +Status will return nonzero for success and +zero for failure. + + + + + Status XdbeQueryExtension + Display *dpy + int *major_version_return + int *minor_version_return + + + + +XdbeQueryExtension sets major version return and minor +version return to the major and minor DBE protocol version supported by +the server. If the DBE library is compatible with the version returned by +the server, it returns nonzero. If dpy does not support the DBE extension, +or if there was an error during communication with the server, or if the +server and library protocol versions are incompatible, it returns zero. +No other Xdbe functions may be called before this function. If a client +violates this rule, the effects of all subsequent Xdbe calls that it makes +are undefined. + + + + + XdbeScreenVisualInfo *XdbeGetVisualInfo + Display *dpy + Drawable *screen_specifiers + int *num_screens + + + + + +XdbeGetVisualInfo returns information about which +visuals support double buffering. The argument num_screens specifies how +many elements there are in the screen_specifiers list. Each drawable in +screen_specifiers designates a screen for which the supported visuals are +being requested. If num_screens is zero, information for all screens is +requested. In this case, upon return from this function, num_screens will +be set to the number of screens that were found. If an error occurs, +this function returns NULL; otherwise, it returns a pointer to a list of +XdbeScreenVisualInfo +structures of length num_screens. The nth element in the returned list +corresponds to the nth drawable in the screen_specifiers list, unless + +element in the returned list corresponds to the nth screen of the server, +starting with screen zero. + + + + +The XdbeScreenVisualInfo structure has the following fields: + + +int count number of items in visinfo +XdbeVisualInfo* visinfo list of visuals and depths for this screen + + + +The XdbeVisualInfo structure has the following fields: + + + +VisualID visual one visual ID that supports double-buffering +int depth depth of visual in bits +int perflevel performance level of visual + + + + + + void XdbeFreeVisualInfo XdbeGetVisualInfo + XdbeScreenVisualInfo *visual_info + + + + +XdbeFreeVisualInfo frees the list of +XdbeScreenVisualInfo returned by +XdbeGetVisualInfo. + + + + + + XdbeBackBuffer XdbeAllocateBackBufferName + Display *dpy + Window *window + XdbeSwapAction swap_action + + + + + +XdbeAllocateBackBufferName returns a drawable ID used +to refer to the back buffer of the specified window. The swap_action is a +hint to indicate the swap_action that will likely be used in subsequent +calls to XdbeSwapBuffers. The actual swap_action +used in calls to XdbeSwapBuffers does not have to be +the same as the swap_action passed to this function, though clients are +encouraged to provide accurate information whenever possible. + + + + + Status XdbeDeallocateBackBufferName + Display *dpy + XdbeBackBuffer buffer + + + + +XdbeDeallocateBackBufferName frees the specified +drawable ID, buffer, that was obtained via +XdbeAllocateBackBufferName. The buffer must be a valid +name for the back buffer of a window, or an +XdbeBadBuffer error results. + + + + + Status XdbeSwapBuffers + Display *dpy + XdbeSwapInfo *swap_info + int num_windows + + + + +XdbeSwapBuffers swaps the front and back buffers +for a list of windows. The argument num_windows specifies how many windows +are to have their buffers swapped; it is the number of elements in the +swap_info array. The argument swap_info specifies the information needed +per window to do the swap. + + +The XdbeSwapInfo structure has the following fields: + + + +Window swap_window window for which to swap buffers +XdbeSwapAction swap_action swap action to use for this swap window + + + + + Status XdbeBeginIdiom + Display *dpy + + + + +XdbeBeginIdiom marks the beginning of an idiom +sequence. See + + +for a complete discussion of idioms. + + + + + Status XdbeEndIdiom + Display *dpy + + + + +XdbeEndIdiom marks the end of an idiom sequence. + + + + + XdbeBackBufferAttributes *XdbeGetBackBufferAttributes + Display *dpy + XdbeBackBuffer buffer + + + + +XdbeGetBackBufferAttributes returns the attributes associated with +the specified buffer. + + +The XdbeBackBufferAttributes structure has the following fields: + + + +Window window window that buffer belongs to + + + +If buffer is not a valid XdbeBackBuffer, window is +set to None. + + +The returned XdbeBackBufferAttributes structure +can be freed with the Xlib function XFree. + + + + +Errors + +The XdbeBufferError structure has the following fields: + + +int type +Display * display Display the event was read from +XdbeBackBuffer buffer resource id +unsigned long serial serial number of failed request +unsigned char error code error base + XdbeBadBuffer +unsigned char request code Major op-code of failed request +unsigned char minor code Minor op-code of failed request + + + + + +Acknowledgements + + +We wish to thank the following individuals who have contributed their time +and talent toward shaping the DBE specification: + + +T. Alex Chen, IBM; Peter Daifuku, Silicon Graphics, Inc.; Ian Elliott, +Hewlett-Packard Company; Stephen Gildea, X Consortium, Inc.; Jim Graham, +Sun; Larry Hare, AGE Logic; Jay Hersh, X Consortium, Inc.; Daryl Huff, +Sun; Deron Dann Johnson, Sun; Louis Khouw, Sun; Mark Kilgard, Silicon +Graphics, Inc.; Rob Lembree, Digital Equipment Corporation; Alan Ricker, +Metheus; Michael Rosenblum, Digital Equipment Corporation; Bob Scheifler, +X Consortium, Inc.; Larry Seiler, Digital Equipment Corporation; Jeanne +Sparlin Smith, IBM; Jeff Stevenson, Hewlett-Packard Company; Walter +Strand, Metheus; Ken Tidwell, Hewlett-Packard Company; and David P. +Wiggins, X Consortium, Inc. + + +Mark provided the impetus to start the DBE project. Ian wrote the first draft +of the specification. David served as architect. + + + + +References + +Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension +Specification Version 3.3." + + +Tim Glauert, Dave Carver, Jim Gettys, and David P. Wiggins, "X +Synchronization Extension Version 3.0." + + + diff --git a/libXext/specs/dpmslib.xml b/libXext/specs/dpmslib.xml index 809f3b77b..1fe81d2af 100644 --- a/libXext/specs/dpmslib.xml +++ b/libXext/specs/dpmslib.xml @@ -1,419 +1,419 @@ - - - - - - - - X Display Power Management Signaling (DPMS) Extension - X Consortium Standard - X Version 11, Release 6.8 - - - RobLembree - - - Digital Equipment Corporation - 1996X Consortium - Version 1.0 - X Consortium - X Version 11, Release 6.8 - - - -Permission to use, copy, modify, distribute, and sell this -documentation for any purpose is hereby granted without fee, -provided that the above copyright notice and this permission -notice appear in all copies. Digital Equipment Corporation -makes no representations about the suitability for any purpose -of the information in this document. This documentation is -provided "as is" without express or implied warranty. - - - -X Window System is a trademark of The Open Group. - - - - - - -Overview - -This extension provides X Protocol control over the VESA Display -Power Management Signaling (DPMS) characteristics of video boards -under control of the X Window System. - - - -Traditionally, the X Window System has provided for both blanking and -non-blanking screen savers. Timeouts associated with these built-in -screen saver mechanisms are limited to idle (dwell) time, and a change -timeout that specifies the change interval for non-blanking screen savers. - - - -The United States' Environmental Protection Agency (EPA) Energy Star program -requires that monitors power down after some idle time by default. -While it is possible to simply overload the existing screen saver timeouts, -this solution leaves the non-privileged user little to no control over -the DPMS characteristics of his or her system. For example, disabling -DPMS would require some unintended side effect in the core screen saver, -such as disabling the changing of a non-blanking screen saver. Providing -clients with this control requires an extension to the core X Window System -Protocol, and this extension seeks to fill this gap. - - - -There are four power levels specified by the Video Electronics Standards -Association (VESA) Display Power Management Signaling (DPMS) standard. -These are mapped onto the X DPMS Extension like this: - - - -DPMS Extension Power Levels - 0 DPMSModeOn In use - 1 DPMSModeStandby Blanked, low power - 2 DPMSModeSuspend Blanked, lower power - 3 DPMSModeOff Shut off, awaiting activity - - - - - -DPMS Functions - - - - - Bool DPMSQueryExtention - Display *display - int event_base - int error_base - - - - - - *display - Specifies the connection to the X server. - - - event_base - Specifies the return location for the assigned base event - - - error_base - Specifies the return location for the assigned base error - - - - -The DPMSQueryExtension function queries the X server to determine the -availability of the DPMS Extension. If the extension is available, the -return value is TRUE, and event_base and -error_base are set to the base event number -and base error number for the extension, respectively. Otherwise, the -return value is FALSE, and the values of -event_base and -error_base are undefined. - - - - - Status DPMSGetVersion - Display *display - int *major_version - int *minor_version - - - - - - display - Specifies the connection to the X server. - - - major_version - Specifies the return location for the extension major version. - - - minor_version - Specifies the return location for the extension minor version. - - - - - -The DPMSGetVersion function returns the version of the DPMS extension -implemented by the X server. The version is returned in -major_version and -minor_version. -The major version and minor version for this specification are '1' and '1', -respectively. The major version will be incremented for protocol -incompatible changes, and the minor version will be incremented for small, -upwardly compatible changes. - - - - - Bool DPMSCapable - Display *display - - - - - - display - Specifies the connection to the X server. - - - - - -The DPMSCapable function returns the DPMS capability of the X server, either -TRUE (capable of DPMS) or FALSE (incapable of DPMS). The capability of an -X server is implementation defined. For example, if a multi-headed X server -is capable of DPMS on one head, and incapable on another, the truth value of -this function is defined by the X server implementation. - - - - - Status DPMSSetTimeouts - Display *display - CARD16 standby - CARD16 suspend - CARD16 off - - - - - - display - Specifies the connection to the X server. - - - standby - Specifies the new standby timeout in seconds. - - - suspend - Specifies the new suspend timeout in seconds. - - - off - Specifies the new off timeout in seconds. - - - - -The DPMSSetTimeouts function permits applications to set the timeout values -used by the X server for DPMS timings. - - - -The value standby is the amount of time of -inactivity in seconds before standby mode is invoked. The actual effects of -this mode are implementation defined, but in the case of DPMS compliant -hardware, it is implemented by shutting off the horizontal sync signal, -and pulsing the vertical sync signal. -Standby mode provides the quickest monitor recovery time. Note also that -many monitors implement this mode identically to suspend mode. A value -of zero disables this mode. - - - -The value suspend is the amount of time of -inactivity in seconds before the second level of power savings is invoked. -Suspend mode's physical and electrical characteristics are implementation -defined, but in DPMS compliant hardware, results in the pulsing of the -horizontal sync signal, and shutting off of the vertical sync signal. -Suspend mode recovery is considered to be slower than standby mode, but -faster than off mode, however this is monitor dependent. As noted above, -many monitors implement this mode identically to standby mode. A value of -zero disables this mode. - - - -The value off is the amount of time of -inactivity in seconds before the third and final level of power savings is -invoked. Off mode's physical and electrical characteristics are -implementation defined, but in DPMS compliant hardware, is implemented by -shutting off both horizontal and vertical sync signals, resulting in -the power-down of the monitor. Recovery time is implementation dependant, -but frequently is similar to the power-up time of the monitor. A value -of zero disables this mode. - - - -Chronologically, standby mode occurs before or simultaneously with -suspend mode, and suspend mode must occur before or simultaneously with -off mode. Therefore, non-zero mode timeout values must be greater than -or equal to the timeout values of earlier modes. If inconsistent values -are supplied, a BadValue error will result. - - - - - Status DPMSGetTimeouts - Display *display - CARD16 *standby - CARD16 *suspend - CARD16 *off - - - - - - display - Specifies the connection to the X server. - - - standby - Specifies the new standby timeout in seconds. - - - suspend - Specifies the new suspend timeout in seconds. - - - off - Specifies the new off timeout in seconds. - - - - -The DPMSGetTimeouts function retrieves the timeout values used by the X -server for DPMS timings. - - - -The value standby is the amount of time of -inactivity in seconds before standby mode is invoked. A value of zero -indicates that this mode has been disabled. - - - -The value suspend is the amount of time of -inactivity in seconds before the second level of power savings is invoked. -A value of zero indicates that this mode has been disabled. - - - -The value off is the amount of time of -inactivity in seconds before the third and final level of power savings is -invoked. A value of zero indicates that this mode has been disabled. - - - - - Status DPMSEnable - Display *display - - - - - - display - Specifies the connection to the X server. - - - - -The DPMSEnable function enables DPMS on the specified display. When -enabled, DPMS will use the currently saved timeout values, and will -invoke the DPMS power mode appropriate for the amount of time that -the workstation input devices have been idle. If DPMSEnable is invoked -on a display with DPMS already enabled, no change is made, and no -error is returned. If DPMSEnable is invoked on a display without -support for DPMS, no change is made and no error is returned. - - - - - Status DPMSDisable - Display *display - - - - - - display - Specifies the connection to the X server. - - - - -The DPMSDisable function disables DPMS on the specified display. When -disabled, DPMS returns the display to DPMSModeOn. If DPMSDisable is -invoked on a display with DPMS already disabled, no change is made, -and no error is returned. If DPMSDisable is invoked on a display -without support for DPMS, no change is made and no error is returned. - - - - - Status DPMSForceLevel - Display *display - CARD16 level - - - - - - display - Specifies the connection to the X server. - - - level - Specifies the level to force power to. - - - - -The DPMSForceLevel function forces a DPMS capable display into the -specified power level. The level must be one of -DPMSModeOn, DPMSModeStandby, DPMSModeSuspend, or DPMSModeOff. -Values other than these will result in a BadValue error. If DPMS -is disabled on the display, a BadMatch protocol error will result. - - -Status DPMSInfo(display, power_level, state) - - - - Status DPMSInfo - Display *display - CARD16 power_level - BOOL *state - - - - - - display - Specifies the connection to the X server. - - - power_level - Specifies the current power level. - - - state - Specifies the current DPMS state. - - - - -The DPMSInfo function returns information about the current DPMS state. -The state return parameter indicates whether -or not DPMS is enabled (TRUE) or disabled (FALSE). The -power_level return parameter indicates the -current power level (one of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend, -or DPMSModeOff.) - - - - + + + + + + + + X Display Power Management Signaling (DPMS) Extension + X Consortium Standard + X Version 11, Release 6.8 + + + RobLembree + + + Digital Equipment Corporation + 1996X Consortium + Version 1.0 + X Consortium + X Version 11, Release 6.8 + + + +Permission to use, copy, modify, distribute, and sell this +documentation for any purpose is hereby granted without fee, +provided that the above copyright notice and this permission +notice appear in all copies. Digital Equipment Corporation +makes no representations about the suitability for any purpose +of the information in this document. This documentation is +provided "as is" without express or implied warranty. + + + +X Window System is a trademark of The Open Group. + + + + + + +Overview + +This extension provides X Protocol control over the VESA Display +Power Management Signaling (DPMS) characteristics of video boards +under control of the X Window System. + + + +Traditionally, the X Window System has provided for both blanking and +non-blanking screen savers. Timeouts associated with these built-in +screen saver mechanisms are limited to idle (dwell) time, and a change +timeout that specifies the change interval for non-blanking screen savers. + + + +The United States' Environmental Protection Agency (EPA) Energy Star program +requires that monitors power down after some idle time by default. +While it is possible to simply overload the existing screen saver timeouts, +this solution leaves the non-privileged user little to no control over +the DPMS characteristics of his or her system. For example, disabling +DPMS would require some unintended side effect in the core screen saver, +such as disabling the changing of a non-blanking screen saver. Providing +clients with this control requires an extension to the core X Window System +Protocol, and this extension seeks to fill this gap. + + + +There are four power levels specified by the Video Electronics Standards +Association (VESA) Display Power Management Signaling (DPMS) standard. +These are mapped onto the X DPMS Extension like this: + + + +DPMS Extension Power Levels + 0 DPMSModeOn In use + 1 DPMSModeStandby Blanked, low power + 2 DPMSModeSuspend Blanked, lower power + 3 DPMSModeOff Shut off, awaiting activity + + + + + +DPMS Functions + + + + + Bool DPMSQueryExtention + Display *display + int event_base + int error_base + + + + + + *display + Specifies the connection to the X server. + + + event_base + Specifies the return location for the assigned base event + + + error_base + Specifies the return location for the assigned base error + + + + +The DPMSQueryExtension function queries the X server to determine the +availability of the DPMS Extension. If the extension is available, the +return value is TRUE, and event_base and +error_base are set to the base event number +and base error number for the extension, respectively. Otherwise, the +return value is FALSE, and the values of +event_base and +error_base are undefined. + + + + + Status DPMSGetVersion + Display *display + int *major_version + int *minor_version + + + + + + display + Specifies the connection to the X server. + + + major_version + Specifies the return location for the extension major version. + + + minor_version + Specifies the return location for the extension minor version. + + + + + +The DPMSGetVersion function returns the version of the DPMS extension +implemented by the X server. The version is returned in +major_version and +minor_version. +The major version and minor version for this specification are '1' and '1', +respectively. The major version will be incremented for protocol +incompatible changes, and the minor version will be incremented for small, +upwardly compatible changes. + + + + + Bool DPMSCapable + Display *display + + + + + + display + Specifies the connection to the X server. + + + + + +The DPMSCapable function returns the DPMS capability of the X server, either +TRUE (capable of DPMS) or FALSE (incapable of DPMS). The capability of an +X server is implementation defined. For example, if a multi-headed X server +is capable of DPMS on one head, and incapable on another, the truth value of +this function is defined by the X server implementation. + + + + + Status DPMSSetTimeouts + Display *display + CARD16 standby + CARD16 suspend + CARD16 off + + + + + + display + Specifies the connection to the X server. + + + standby + Specifies the new standby timeout in seconds. + + + suspend + Specifies the new suspend timeout in seconds. + + + off + Specifies the new off timeout in seconds. + + + + +The DPMSSetTimeouts function permits applications to set the timeout values +used by the X server for DPMS timings. + + + +The value standby is the amount of time of +inactivity in seconds before standby mode is invoked. The actual effects of +this mode are implementation defined, but in the case of DPMS compliant +hardware, it is implemented by shutting off the horizontal sync signal, +and pulsing the vertical sync signal. +Standby mode provides the quickest monitor recovery time. Note also that +many monitors implement this mode identically to suspend mode. A value +of zero disables this mode. + + + +The value suspend is the amount of time of +inactivity in seconds before the second level of power savings is invoked. +Suspend mode's physical and electrical characteristics are implementation +defined, but in DPMS compliant hardware, results in the pulsing of the +horizontal sync signal, and shutting off of the vertical sync signal. +Suspend mode recovery is considered to be slower than standby mode, but +faster than off mode, however this is monitor dependent. As noted above, +many monitors implement this mode identically to standby mode. A value of +zero disables this mode. + + + +The value off is the amount of time of +inactivity in seconds before the third and final level of power savings is +invoked. Off mode's physical and electrical characteristics are +implementation defined, but in DPMS compliant hardware, is implemented by +shutting off both horizontal and vertical sync signals, resulting in +the power-down of the monitor. Recovery time is implementation dependant, +but frequently is similar to the power-up time of the monitor. A value +of zero disables this mode. + + + +Chronologically, standby mode occurs before or simultaneously with +suspend mode, and suspend mode must occur before or simultaneously with +off mode. Therefore, non-zero mode timeout values must be greater than +or equal to the timeout values of earlier modes. If inconsistent values +are supplied, a BadValue error will result. + + + + + Status DPMSGetTimeouts + Display *display + CARD16 *standby + CARD16 *suspend + CARD16 *off + + + + + + display + Specifies the connection to the X server. + + + standby + Specifies the new standby timeout in seconds. + + + suspend + Specifies the new suspend timeout in seconds. + + + off + Specifies the new off timeout in seconds. + + + + +The DPMSGetTimeouts function retrieves the timeout values used by the X +server for DPMS timings. + + + +The value standby is the amount of time of +inactivity in seconds before standby mode is invoked. A value of zero +indicates that this mode has been disabled. + + + +The value suspend is the amount of time of +inactivity in seconds before the second level of power savings is invoked. +A value of zero indicates that this mode has been disabled. + + + +The value off is the amount of time of +inactivity in seconds before the third and final level of power savings is +invoked. A value of zero indicates that this mode has been disabled. + + + + + Status DPMSEnable + Display *display + + + + + + display + Specifies the connection to the X server. + + + + +The DPMSEnable function enables DPMS on the specified display. When +enabled, DPMS will use the currently saved timeout values, and will +invoke the DPMS power mode appropriate for the amount of time that +the workstation input devices have been idle. If DPMSEnable is invoked +on a display with DPMS already enabled, no change is made, and no +error is returned. If DPMSEnable is invoked on a display without +support for DPMS, no change is made and no error is returned. + + + + + Status DPMSDisable + Display *display + + + + + + display + Specifies the connection to the X server. + + + + +The DPMSDisable function disables DPMS on the specified display. When +disabled, DPMS returns the display to DPMSModeOn. If DPMSDisable is +invoked on a display with DPMS already disabled, no change is made, +and no error is returned. If DPMSDisable is invoked on a display +without support for DPMS, no change is made and no error is returned. + + + + + Status DPMSForceLevel + Display *display + CARD16 level + + + + + + display + Specifies the connection to the X server. + + + level + Specifies the level to force power to. + + + + +The DPMSForceLevel function forces a DPMS capable display into the +specified power level. The level must be one of +DPMSModeOn, DPMSModeStandby, DPMSModeSuspend, or DPMSModeOff. +Values other than these will result in a BadValue error. If DPMS +is disabled on the display, a BadMatch protocol error will result. + + +Status DPMSInfo(display, power_level, state) + + + + Status DPMSInfo + Display *display + CARD16 power_level + BOOL *state + + + + + + display + Specifies the connection to the X server. + + + power_level + Specifies the current power level. + + + state + Specifies the current DPMS state. + + + + +The DPMSInfo function returns information about the current DPMS state. +The state return parameter indicates whether +or not DPMS is enabled (TRUE) or disabled (FALSE). The +power_level return parameter indicates the +current power level (one of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend, +or DPMSModeOff.) + + + + diff --git a/libXext/specs/shapelib.xml b/libXext/specs/shapelib.xml index 1d89cf1e1..a357da40b 100644 --- a/libXext/specs/shapelib.xml +++ b/libXext/specs/shapelib.xml @@ -1,577 +1,577 @@ - - - - - - - - X Nonrectangular Window Shape Extension Library - X Consortium Standard - X Version 11, Release 6.4 - - - KeithPackard - - - MIT X Consortium - 1989X Consortium - Version 1.0 - MIT X Consortium - X Version 11, Release 6.4 - - - - -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, sublicense, and/or sell copies of the Software, and -to permit persons to whom the Software is furnished to do so, subject to -the following conditions: - - - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - - - -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. -IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. - - - -Except as contained in this notice, the name of the X Consortium shall not be -used in advertising or otherwise to promote the sale, use or other dealings -in this Software without prior written authorization from the X Consortium. - - - - - -Overview - -This extension provides arbitrary window and border shapes within -the X11 protocol. - - - -The restriction of rectangular windows within the X protocol is a significant -limitation in the implementation of many styles of user interface. For -example, many transient windows would like to display a -“drop shadow” to give the illusion of 3 dimensions. As -another example, some user interface style guides call for buttons with -rounded corners; the full simulation of a nonrectangular shape, -particularly with respect to event distribution and cursor shape, is not -possible within the core X protocol. As a final example, round clocks -and nonrectangular icons are desirable visual addition to the desktop. - - - -This extension provides mechanisms for changing the visible shape of a -window to an arbitrary, possibly disjoint, nonrectangular form. The intent -of the extension is to supplement the existing semantics, not replace them. -In particular, it is desirable for clients that are unaware of the -extension to still be able to cope reasonably with shaped windows. For -example, window managers should still be able to negotiate screen -real estate in rectangular pieces. Toward this end, any shape specified for -a window is clipped by the bounding rectangle for the window as specified by -the window's geometry in the core protocol. An expected convention would be -that client programs expand their shape to fill the area offered by the -window manager. - - - - -Description - - -Each window (even with no shapes specified) is defined by two regions: the -bounding region and the -clip region. The bounding region is the -area of the parent window that the window will occupy (including border). -The clip region is the subset of the bounding region that is available for -subwindows and graphics. The area between the bounding region and the -clip region is defined to be the border of the window. - - - -A nonshaped window will have a bounding region that is a rectangle spanning -the window, including its border; the clip region will be a rectangle -filling the inside dimensions (not including the border). In this document, -these areas are referred to as the -default bounding region and the -default clip region. For a window with -inside size of width by -height and border width -bwidth, the default bounding and clip -regions are the rectangles (relative to the window origin): - - - -bounding.x = -bwidth -bounding.y = -bwidth -bounding.width = width + 2 * bwidth -bounding.height = height + 2 * bwidth - -clip.x = 0 -clip.y = 0 -clip.width = width -clip.height = height - - - -This extension allows a client to modify either or both of the bounding or -clip regions by specifying new regions that combine with the default -regions. These new regions are called the -client bounding region and the -client clip region. They are specified -relative to the origin of the window and are always defined by offsets -relative to the window origin (that is, region adjustments are not -required when the window is moved). Three mechanisms for specifying -regions are provided: a list of rectangles, a bitmap, and an existing -bounding or clip region from a window. This is modeled on the specification -of regions in graphics contexts in the core protocol and allows a variety -of different uses of the extension. - - - -When using an existing window shape as an operand in specifying a new shape, -the client region is used, unless none has been set, in which case the -default region is used instead. - - - -The effective bounding region of a window is -defined to be the intersection of the client bounding region with the default -bounding region. Any portion of the client bounding region that is not -included in the default bounding region will not be included in the -effective bounding region on the screen. This means that window managers -(or other geometry managers) used to dealing with rectangular client windows -will be able to constrain the client to a rectangular area of the screen. - - - -Construction of the effective bounding region is dynamic; the client bounding -region is not mutated to obtain the effective bounding region. If a client -bounding region is specified that extends beyond the current default bounding -region, and the window is later enlarged, the effective bounding region will -be enlarged to include more of the client bounding region. - - - -The effective clip region of a window is -defined to be the intersection of the client clip region with both the -default clip region and the client bounding region. Any portion of the -client clip region that is not included in both the default clip region -and the client bounding region will not be included in the effective clip -region on the screen. - - - -Construction of the effective clip region is dynamic; the client clip region is -not mutated to obtain the effective clip region. If a client clip region is -specified that extends beyond the current default clip region and the -window or its bounding region is later enlarged, the effective clip region will -be enlarged to include more of the client clip region if it is included in -the effective bounding region. - - - -The border of a window is defined to be the difference between the effective -bounding region and the effective clip region. If this region is empty, no -border is displayed. If this region is nonempty, the border is filled -using the border-tile or border-pixel of the window as specified in the core -protocol. Note that a window with a nonzero border width will never be able -to draw beyond the default clip region of the window. Also note that a zero -border width does not prevent a window from having a border, since the clip -shape can still be made smaller than the bounding shape. - - - -All output to the window and visible regions of any subwindows will be -clipped to the effective clip region. The server must not retain window -contents beyond the effective bounding region with backing store. The window's -origin (for graphics operations, background tiling, and subwindow placement) -is not affected by the existence of a bounding region or clip region. - - - -Areas that are inside the default bounding region but outside the effective -bounding region are not part of the window; these areas of the screen will -be occupied by other windows. Input events that occur within the default -bounding region but outside the effective bounding region will be delivered as -if the window was not occluding the event position. Events that occur in -a nonrectangular border of a window will be delivered to that window, just -as for events that occur in a normal rectangular border. - - -An -InputOnly -window can have its bounding region set, but it is a -Match -error to attempt to set a clip region on an -InputOnly -window or to specify its clip region as a source to a request -in this extension. - - - -The server must accept changes to the clip region of a root window, but -the server is permitted to ignore requested changes to the bounding region -of a root window. If the server accepts bounding region changes, the contents -of the screen outside the bounding region are implementation dependent. - - - - -C Language Binding - - -The C functions provide direct access to the protocol and add no additional -semantics. - - -The include file for this extension is -<X11/extensions/shape.h>. -The defined shape kinds are -ShapeBounding -and -ShapeClip -The defined region operations are -ShapeSet -ShapeUnion -ShapeIntersect -ShapeSubtract -and -ShapeInvert. - - - -Bool XShapeQueryExtension -Display *display -int *event_base -int *error_base - - - - -XShapeQueryExtension -returns -True -if the specified display supports the SHAPE extension else -False -If the extension is supported, *event_base is set to the event number for -ShapeNotify -events and *error_base would be set to the error number for the first error for -this extension. Because no errors are defined for this version of -the extension, the value returned here is not defined (nor useful). - - - - -Status XShapeQueryVersion -Display *display -int *major_version -int *minor_version - - - - -If the extension is supported, -XShapeQueryVersion -sets the major and minor version numbers of the -extension supported by the display and returns a nonzero value. -Otherwise, the arguments are not set and zero is returned. - - - - -XShapeCombineRegion -Display *display -Window dest -int dest_kind -int x_off -int y_off -int region -int op -REGION *region - - - - -XShapeCombineRegion -converts the specified region into a list of rectangles and calls -XShapeCombineRectangles - - - - -XShapeCombineRectangles -Display *display -Window dest -int dest_kind -int x_off -int y_off -XRectangle *rectangles -int n_rects -int op -int ordering - - - - -If the extension is supported, -XShapeCombineRectangles -performs a -ShapeRectangles -operation; otherwise, the request is ignored. - - - - -XShapeCombineMask -Display *display -int dest -int dest_kind -int x_off -int y_off -Pixmap src -int op - - - - -If the extension is supported, -XShapeCombineMask -performs a -ShapeMask -operation; otherwise, the request is ignored. - - - - -XShapeCombineShape -Display *display -Window dest -int dest_kind -int x_off -int y_off -Window src -int src_kind -int op - - - - -If the extension is supported, -XShapeCombineShape -performs a -ShapeCombine -operation; otherwise, the request is ignored. - - - - -XShapeOffsetShape -display -dest -dest_kind -x_off -y_off - - - - -If the extension is supported, -XShapeOffsetShape -performs a -ShapeOffset -operation; otherwise, the request is ignored. - - - - -Status XShapeQueryExtents -Display *display -Window window -Bool *bounding_shaped -int *x_bounding -int *y_bounding -unsigned int *w_bounding -unsigned int *h_bounding -Bool *clip_shaped -int *x_clip -int *y_clip -unsigned int *w_clip -unsigned int *h_clip - - - - -If the extension is supported, -XShapeQueryExtents -sets x_bounding, y_bounding, w_bounding, h_bounding to the extents of the -bounding shape and sets x_clip, y_clip, w_clip, h_clip to the extents of -the clip shape. For unspecified client regions, the extents of the -corresponding default region are used. - - - -If the extension is supported, a nonzero value is returned; otherwise, -zero is returned. - - - - -XShapeSelectInput -Display *display -Window window -unsigned long mask - - - - -To make this extension more compatible with other interfaces, although -only one event type can be selected via the extension, -XShapeSelectInput -provides a general mechanism similar to the standard Xlib binding for -window events. A mask value has been defined, -ShapeNotifyMask -that is the only valid bit in mask that may be specified. -The structure for this event is defined as follows: - - - -typedef struct { - int type; /* of event */ - unsigned long serial; /* # of last request processed by server */ - Bool send_event; /* true if this came frome a SendEvent request */ - Display *display; /* Display the event was read from */ - Window window; /* window of event */ - int kind; /* ShapeBounding or ShapeClip */ - int x, y; /* extents of new region */ - unsigned width, height; - Time time; /* server timestamp when region changed */ - Bool shaped; /* true if the region exists */ -} XShapeEvent; - - - - -unsigned long XShapeInputSelected -Display *display -Window window - - - - -XShapeInputSelected -returns the current input mask for extension events on the specified -window; the value returned if -ShapeNotify -is selected for is -ShapeNotifyMask -otherwise, it returns zero. -If the extension is not supported, it returns zero. - - - - -XRectangle *XShapeGetRectangles -Display *display -Window window -int kind -int *count -int *ordering - - - - -If the extension is not supported, -XShapeGetRectangles -returns NULL. Otherwise, it returns a list of rectangles that describe the -region specified by kind. - - - - - - - bounding region - The area of the parent window that this window will occupy. -This area is divided into two parts: the border and the interior. - - - - - clip region - The interior of the window, as a subset of the bounding -region. This region describes the area that will be painted with the -window background when the window is cleared, will contain all graphics -output to the window, and will clip any subwindows. - - - - default bounding region - The rectangular area, as described by the core protocol -window size, that covers the interior of the window and its border. - - - - - default clip region - The rectangular area, as described by the core protocol -window size, that covers the interior of the window and excludes the border. - - - - - client bounding region - The region associated with a window that is directly -modified via this extension when specified by -ShapeBounding -This region is used in conjunction with the default bounding region -to produce the effective bounding region. - - - - client clip region - The region associated with a window that is directly -modified via this extension when specified by -ShapeClip -This region is used in conjunction with the default clip region -and the client bounding region to produce the effective clip region. - - - - - effective bounding region - The actual shape of the window on the screen, including -border and interior (but excluding the effects of overlapping windows). -When a window has a client bounding region, the effective bounding region -is the intersection of the default bounding region and the client bounding -region. Otherwise, the effective bounding region is the same as the -default bounding region. - - - - - effective clip region - The actual shape of the interior of the window on the -screen (excluding the effects of overlapping windows). When a window -has a client clip region or a client bounding region, the effective -clip region is the intersection of the default clip region, the client -clip region (if any) and the client bounding region (if any). Otherwise, -the effective clip region is the same as the default clip region. - - - - + + + + + + + + X Nonrectangular Window Shape Extension Library + X Consortium Standard + X Version 11, Release 6.4 + + + KeithPackard + + + MIT X Consortium + 1989X Consortium + Version 1.0 + MIT X Consortium + X Version 11, Release 6.4 + + + + +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, sublicense, and/or sell copies of the Software, and +to permit persons to whom the Software is furnished to do so, subject to +the following conditions: + + + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + + + +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. +IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + + + +Except as contained in this notice, the name of the X Consortium shall not be +used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from the X Consortium. + + + + + +Overview + +This extension provides arbitrary window and border shapes within +the X11 protocol. + + + +The restriction of rectangular windows within the X protocol is a significant +limitation in the implementation of many styles of user interface. For +example, many transient windows would like to display a +“drop shadow” to give the illusion of 3 dimensions. As +another example, some user interface style guides call for buttons with +rounded corners; the full simulation of a nonrectangular shape, +particularly with respect to event distribution and cursor shape, is not +possible within the core X protocol. As a final example, round clocks +and nonrectangular icons are desirable visual addition to the desktop. + + + +This extension provides mechanisms for changing the visible shape of a +window to an arbitrary, possibly disjoint, nonrectangular form. The intent +of the extension is to supplement the existing semantics, not replace them. +In particular, it is desirable for clients that are unaware of the +extension to still be able to cope reasonably with shaped windows. For +example, window managers should still be able to negotiate screen +real estate in rectangular pieces. Toward this end, any shape specified for +a window is clipped by the bounding rectangle for the window as specified by +the window's geometry in the core protocol. An expected convention would be +that client programs expand their shape to fill the area offered by the +window manager. + + + + +Description + + +Each window (even with no shapes specified) is defined by two regions: the +bounding region and the +clip region. The bounding region is the +area of the parent window that the window will occupy (including border). +The clip region is the subset of the bounding region that is available for +subwindows and graphics. The area between the bounding region and the +clip region is defined to be the border of the window. + + + +A nonshaped window will have a bounding region that is a rectangle spanning +the window, including its border; the clip region will be a rectangle +filling the inside dimensions (not including the border). In this document, +these areas are referred to as the +default bounding region and the +default clip region. For a window with +inside size of width by +height and border width +bwidth, the default bounding and clip +regions are the rectangles (relative to the window origin): + + + +bounding.x = -bwidth +bounding.y = -bwidth +bounding.width = width + 2 * bwidth +bounding.height = height + 2 * bwidth + +clip.x = 0 +clip.y = 0 +clip.width = width +clip.height = height + + + +This extension allows a client to modify either or both of the bounding or +clip regions by specifying new regions that combine with the default +regions. These new regions are called the +client bounding region and the +client clip region. They are specified +relative to the origin of the window and are always defined by offsets +relative to the window origin (that is, region adjustments are not +required when the window is moved). Three mechanisms for specifying +regions are provided: a list of rectangles, a bitmap, and an existing +bounding or clip region from a window. This is modeled on the specification +of regions in graphics contexts in the core protocol and allows a variety +of different uses of the extension. + + + +When using an existing window shape as an operand in specifying a new shape, +the client region is used, unless none has been set, in which case the +default region is used instead. + + + +The effective bounding region of a window is +defined to be the intersection of the client bounding region with the default +bounding region. Any portion of the client bounding region that is not +included in the default bounding region will not be included in the +effective bounding region on the screen. This means that window managers +(or other geometry managers) used to dealing with rectangular client windows +will be able to constrain the client to a rectangular area of the screen. + + + +Construction of the effective bounding region is dynamic; the client bounding +region is not mutated to obtain the effective bounding region. If a client +bounding region is specified that extends beyond the current default bounding +region, and the window is later enlarged, the effective bounding region will +be enlarged to include more of the client bounding region. + + + +The effective clip region of a window is +defined to be the intersection of the client clip region with both the +default clip region and the client bounding region. Any portion of the +client clip region that is not included in both the default clip region +and the client bounding region will not be included in the effective clip +region on the screen. + + + +Construction of the effective clip region is dynamic; the client clip region is +not mutated to obtain the effective clip region. If a client clip region is +specified that extends beyond the current default clip region and the +window or its bounding region is later enlarged, the effective clip region will +be enlarged to include more of the client clip region if it is included in +the effective bounding region. + + + +The border of a window is defined to be the difference between the effective +bounding region and the effective clip region. If this region is empty, no +border is displayed. If this region is nonempty, the border is filled +using the border-tile or border-pixel of the window as specified in the core +protocol. Note that a window with a nonzero border width will never be able +to draw beyond the default clip region of the window. Also note that a zero +border width does not prevent a window from having a border, since the clip +shape can still be made smaller than the bounding shape. + + + +All output to the window and visible regions of any subwindows will be +clipped to the effective clip region. The server must not retain window +contents beyond the effective bounding region with backing store. The window's +origin (for graphics operations, background tiling, and subwindow placement) +is not affected by the existence of a bounding region or clip region. + + + +Areas that are inside the default bounding region but outside the effective +bounding region are not part of the window; these areas of the screen will +be occupied by other windows. Input events that occur within the default +bounding region but outside the effective bounding region will be delivered as +if the window was not occluding the event position. Events that occur in +a nonrectangular border of a window will be delivered to that window, just +as for events that occur in a normal rectangular border. + + +An +InputOnly +window can have its bounding region set, but it is a +Match +error to attempt to set a clip region on an +InputOnly +window or to specify its clip region as a source to a request +in this extension. + + + +The server must accept changes to the clip region of a root window, but +the server is permitted to ignore requested changes to the bounding region +of a root window. If the server accepts bounding region changes, the contents +of the screen outside the bounding region are implementation dependent. + + + + +C Language Binding + + +The C functions provide direct access to the protocol and add no additional +semantics. + + +The include file for this extension is +<X11/extensions/shape.h>. +The defined shape kinds are +ShapeBounding +and +ShapeClip +The defined region operations are +ShapeSet +ShapeUnion +ShapeIntersect +ShapeSubtract +and +ShapeInvert. + + + +Bool XShapeQueryExtension +Display *display +int *event_base +int *error_base + + + + +XShapeQueryExtension +returns +True +if the specified display supports the SHAPE extension else +False +If the extension is supported, *event_base is set to the event number for +ShapeNotify +events and *error_base would be set to the error number for the first error for +this extension. Because no errors are defined for this version of +the extension, the value returned here is not defined (nor useful). + + + + +Status XShapeQueryVersion +Display *display +int *major_version +int *minor_version + + + + +If the extension is supported, +XShapeQueryVersion +sets the major and minor version numbers of the +extension supported by the display and returns a nonzero value. +Otherwise, the arguments are not set and zero is returned. + + + + +XShapeCombineRegion +Display *display +Window dest +int dest_kind +int x_off +int y_off +int region +int op +REGION *region + + + + +XShapeCombineRegion +converts the specified region into a list of rectangles and calls +XShapeCombineRectangles + + + + +XShapeCombineRectangles +Display *display +Window dest +int dest_kind +int x_off +int y_off +XRectangle *rectangles +int n_rects +int op +int ordering + + + + +If the extension is supported, +XShapeCombineRectangles +performs a +ShapeRectangles +operation; otherwise, the request is ignored. + + + + +XShapeCombineMask +Display *display +int dest +int dest_kind +int x_off +int y_off +Pixmap src +int op + + + + +If the extension is supported, +XShapeCombineMask +performs a +ShapeMask +operation; otherwise, the request is ignored. + + + + +XShapeCombineShape +Display *display +Window dest +int dest_kind +int x_off +int y_off +Window src +int src_kind +int op + + + + +If the extension is supported, +XShapeCombineShape +performs a +ShapeCombine +operation; otherwise, the request is ignored. + + + + +XShapeOffsetShape +display +dest +dest_kind +x_off +y_off + + + + +If the extension is supported, +XShapeOffsetShape +performs a +ShapeOffset +operation; otherwise, the request is ignored. + + + + +Status XShapeQueryExtents +Display *display +Window window +Bool *bounding_shaped +int *x_bounding +int *y_bounding +unsigned int *w_bounding +unsigned int *h_bounding +Bool *clip_shaped +int *x_clip +int *y_clip +unsigned int *w_clip +unsigned int *h_clip + + + + +If the extension is supported, +XShapeQueryExtents +sets x_bounding, y_bounding, w_bounding, h_bounding to the extents of the +bounding shape and sets x_clip, y_clip, w_clip, h_clip to the extents of +the clip shape. For unspecified client regions, the extents of the +corresponding default region are used. + + + +If the extension is supported, a nonzero value is returned; otherwise, +zero is returned. + + + + +XShapeSelectInput +Display *display +Window window +unsigned long mask + + + + +To make this extension more compatible with other interfaces, although +only one event type can be selected via the extension, +XShapeSelectInput +provides a general mechanism similar to the standard Xlib binding for +window events. A mask value has been defined, +ShapeNotifyMask +that is the only valid bit in mask that may be specified. +The structure for this event is defined as follows: + + + +typedef struct { + int type; /* of event */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came frome a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* window of event */ + int kind; /* ShapeBounding or ShapeClip */ + int x, y; /* extents of new region */ + unsigned width, height; + Time time; /* server timestamp when region changed */ + Bool shaped; /* true if the region exists */ +} XShapeEvent; + + + + +unsigned long XShapeInputSelected +Display *display +Window window + + + + +XShapeInputSelected +returns the current input mask for extension events on the specified +window; the value returned if +ShapeNotify +is selected for is +ShapeNotifyMask +otherwise, it returns zero. +If the extension is not supported, it returns zero. + + + + +XRectangle *XShapeGetRectangles +Display *display +Window window +int kind +int *count +int *ordering + + + + +If the extension is not supported, +XShapeGetRectangles +returns NULL. Otherwise, it returns a list of rectangles that describe the +region specified by kind. + + + + + + + bounding region + The area of the parent window that this window will occupy. +This area is divided into two parts: the border and the interior. + + + + + clip region + The interior of the window, as a subset of the bounding +region. This region describes the area that will be painted with the +window background when the window is cleared, will contain all graphics +output to the window, and will clip any subwindows. + + + + default bounding region + The rectangular area, as described by the core protocol +window size, that covers the interior of the window and its border. + + + + + default clip region + The rectangular area, as described by the core protocol +window size, that covers the interior of the window and excludes the border. + + + + + client bounding region + The region associated with a window that is directly +modified via this extension when specified by +ShapeBounding +This region is used in conjunction with the default bounding region +to produce the effective bounding region. + + + + client clip region + The region associated with a window that is directly +modified via this extension when specified by +ShapeClip +This region is used in conjunction with the default clip region +and the client bounding region to produce the effective clip region. + + + + + effective bounding region + The actual shape of the window on the screen, including +border and interior (but excluding the effects of overlapping windows). +When a window has a client bounding region, the effective bounding region +is the intersection of the default bounding region and the client bounding +region. Otherwise, the effective bounding region is the same as the +default bounding region. + + + + + effective clip region + The actual shape of the interior of the window on the +screen (excluding the effects of overlapping windows). When a window +has a client clip region or a client bounding region, the effective +clip region is the intersection of the default clip region, the client +clip region (if any) and the client bounding region (if any). Otherwise, +the effective clip region is the same as the default clip region. + + + + diff --git a/libXext/specs/synclib.xml b/libXext/specs/synclib.xml index 3edeaaaa7..36c716297 100644 --- a/libXext/specs/synclib.xml +++ b/libXext/specs/synclib.xml @@ -1,813 +1,813 @@ - - - - - - - - - X Synchronization Extension Library - X Consortium Standard - X Version 11, Release 6.4 - - - TimGlauert - Olivetti Research/MultiWorks - - - Dave - Carver - Digital Equipment Corporation, MIT/Project Athena - - - Jim - Gettys - Digital Equipment Corporation, Cambridge Research Laboratory - - - David - Wiggins - X Consortium, Inc. - - - Version 3.0 - X Consortium - X Version 11, Release 6.4 - - - -Copyright 1991 by Olivetti Research Limited, Cambridge England and Digital Equipment Corporation, Maynard, Massachusetts - - - -Permission to use, copy, modify, and distribute this documentation for any -purpose and without fee is hereby granted, provided that the above -copyright notice appear in all copies. Olivetti, Digital, MIT, and the -X Consortium make no representations about the suitability for any purpose -of the information in this document. This documentation is provided as -is without express or implied warranty. - - - - - - -Copyright © 1991 X Consortium, Inc. - - - -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, sublicense, and/or sell copies of -the Software, and to permit persons to whom the Software is furnished -to do so, subject to the following conditions: - - - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - - -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. -IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. - - - -Except as contained in this notice, the name of the X Consortium shall -not be used in advertising or otherwise to promote the sale, use or other -dealings in this Software without prior written authorization from the -X Consortium. - - - - - - -Synchronization Protocol - - -The core X protocol makes no guarantees about the relative order of -execution of requests for different clients. This means that any -synchronization between clients must be done at the client level in an -operating system-dependent and network-dependent manner. Even if there -was an accepted standard for such synchronization, the use of a network -introduces unpredictable delays between the synchronization of the clients and -the delivery of the resulting requests to the X server. - - -The core X protocol also makes no guarantees about the time at which -requests are executed, which means that all clients with real-time constraints -must implement their timing on the host computer. Any such timings are -subject to error introduced by delays within the operating system and -network and are inefficient because of the need for round-trip requests that -keep the client and server synchronized. - - -The synchronization extension provides primitives that allow synchronization -between clients to take place entirely within the X server. This removes any -error introduced by the network and makes it possible to synchronize clients -on different hosts running different operating systems. This is important for -multimedia applications, where audio, video, and graphics data streams are -being synchronized. The extension also provides internal timers within the X -server to which client requests can be synchronized. This allows simple -animation applications to be implemented without any round-trip requests -and makes best use of buffering within the client, network, and server. - - - -Description - -The mechanism used by this extension for synchronization within the X server -is to block the processing of requests from a client until a specific -synchronization condition occurs. When the condition occurs, the client is -released and processing of requests continues. Multiple clients may block on -the same condition to give inter-client synchronization. Alternatively, a single -client may block on a condition such as an animation frame marker. - - -The extension adds Counter and -Alarm to the set of resources managed by -the server. A counter has a 64-bit integer value that may be increased or -decreased by client requests or by the server internally. A client can -block by sending an Await request that waits until -one of a set of synchronization conditions, called TRIGGERs, becomes TRUE. - - -The CreateCounter request allows a client to create -a Counter that can be changed by explicit -SetCounter and ChangeCounter -requests. These can be used to implement synchronization between -different clients. - - -There are some counters, called System Counters, -that are changed by the server internally rather than by client -requests. The effect of any change to a system counter is not visible -until the server has finished processing the current request. In other -words, system counters are apparently updated in the gaps between the -execution of requests rather than during the actual execution of a -request. The extension provides a system counter that advances with the -server time as defined by the core protocol, and it may also provide -counters that advance with the real-world time or that change each -time the CRT screen is refreshed. Other extensions may provide their own -extension-specific system counters. - - -The extension provides an Alarm mechanism that allows clients to receive an -event on a regular basis when a particular counter is changed. - - - - - -C Language Binding - - -The C routines provide direct access to the protocol and add no additional -semantics. - - -The include file for this extension is <X11/extensions/sync.h>. -Most of the names in the language binding are derived from the protocol -names by prepending XSync to the protocol name and changing the -capitalization. - - - -C Functions - - -Most of the following functions generate SYNC protocol requests. - - - - - Status XSyncQueryExtension - Display *dpy - int *event_base_return - int *error_base_return - - - - -If dpy supports the SYNC extension, -XSyncQueryExtension returns True, -sets *event_base_return to the event number for the first SYNC event, and -sets *error_base_return to the error number for the first SYNC error. If dpy -does not support the SYNC extension, it returns False. - - - - - Status XSyncInitialize - Display *dpy - int *major_version_return - int *minor_version_return - - - - -XSyncInitialize sets *major_version_return and -*minor version return to the major/minor SYNC protocol version supported -by the server. If the XSync library is compatible with the version -returned by the server, this function returns True. -If dpy does not support the SYNC extension, or if there was an error -during communication with the server, or if the server and library protocol -versions are incompatible, this function returns False. -The only XSync function that may be called before this function is -XSyncQueryExtension. If a client violates this rule, the effects of all XSync -calls that it makes are undefined. - - - - - XSyncSystemCounter *XSyncListSystemCounters - Display *dpy - int *n_counters_return - - - - -XSyncListSystemCounters returns a pointer to an array -of system counters supported by the display and sets *n_counters_return -to the number of counters in the array. The array should be freed with -XSyncFreeSystemCounterList. If dpy does not support -the SYNC extension, or if there was an error during communication with -the server, or if the server does not support any system counters, -this function returns NULL. - - - -XSyncSystemCounter has the following fields: - - - -char * name; /* null-terminated name of system counter */ -XSyncCounter counter; /* counter id of this system counter */ -XSyncValue resolution; /* resolution of this system counter */ - - - - - void XSyncFreeSystemCounterList - XSyncSystemCounter *list - - - - -XSyncFreeSystemCounterList frees the memory -associated with the system counter list returned by -XSyncListSystemCounters. - - - - - XSyncCounter XSyncCreateCounter - Display *dpy - XSyncValue initial_value - - - - -XSyncCreateCounter creates a counter on the dpy -with the given initial value and returns the counter ID. It returns -None if dpy does not support the SYNC extension. - - - - - Status XSyncSetCounter - Display *dpy - XSyncCounter counter - XSyncValue value - - - - - -XSyncSetCounter sets counter to value. It returns -False if dpy does not -support the SYNC extension; otherwise, it returns True. - - - - - Status XSyncChangeCounter - Display *dpy - XSyncCounter counter - XSyncValue value - - - - -XSyncChangeCounter adds value to counter. It returns -False if dpy does not support the SYNC extension; -otherwise, it returns -True. - - - - Status XSyncDestroyCounter - Display *dpy - XSyncCounter counter - - - - -XSyncDestroyCounter destroys counter. It returns -False if dpy does not support the SYNC extension; -otherwise, it returns True. - - - - - Status XSyncQueryCounter - Display *dpy - XSyncCounter counter - XSyncValue *value_return - - - - -XSyncQueryCounter sets *value_return to the current -value of counter. It returns False if there was an -error during communication with the server or if dpy does not support the -SYNC extension; otherwise, it returns True. - - - - - Status XSyncAwait - Display *dpy - XSyncWaitCondition *wait_list - int n_conditions - - - - -XSyncAwait awaits on the conditions in wait_list. -The n_conditions is the number of wait conditions in wait_list. It -returns False if dpy does not support the SYNC -extension; otherwise, it returns True. The await is -processed asynchronously by the server; this function always returns -immediately after issuing the request. - - -XSyncWaitCondition has the following fields: - - - -XSyncCounter trigger.counter; /*counter to trigger on */ -XSyncValueType trigger.value_type; /*absolute/relative */ -XSyncValue trigger.wait_value; /*value to compare counter to */ -XSyncTestType trigger.test_type; /*pos/neg comparison/transtion */ -XSyncValue event_threshold; /*send event if past threshold */ - - - -XSyncValueType can be either -XSyncAbsolute or XSyncRelative. - - - -XSyncTestType can be one of -XSyncPositiveTransition, -XSyncNegativeTransition, -XSyncPositiveComparison, or -XSyncNegativeComparison. - - - - - XSyncAlarm XSyncCreateAlarm - Display *dpy - unsigned long values_mask - XSyncAlarmAttributes *values` - - - - -XSyncCreateAlarm creates an alarm and returns the -alarm ID. It returns None if the display does not support the SYNC -extension. The values_mask and values specify the alarm attributes. - - - -XSyncAlarmAttributes has the following fields. The -attribute_mask column specifies the symbol that the caller should OR -into values_mask to indicate that the value for the corresponding -attribute was actually supplied. Default values are used for all -attributes that do not have their attribute_mask OR’ed into values_mask. -See the protocol description for CreateAlarm for the -defaults. - - - -type field name attribute_mask -XSyncCounter trigger.counter; XSyncCACounter -XSyncValueType trigger.value_type; XSyncCAValueType -XSyncValue trigger.wait_value; XSyncCAValue -XSyncTestType trigger.test_type; XSyncCATestType -XSyncValue delta; XSyncCADelta -Bool events; XSyncCAEvents -XSyncAlarmState state; client cannot set this - - - - - Status XSyncDestroyAlarm - Display *dpy - XSyncAlarm alarm - - - - -XSyncDestroyAlarm destroys alarm. It returns -False if dpy does not support -the SYNC extension; otherwise, it returns True. - - - - - Status XSyncQueryAlarm - Display *dpy - XSyncAlarm alarm - XSyncAlarmAttributes *values_return - - - - - -XSyncQueryAlarm sets *values_return to the alarm’s -attributes. It returns False if there was an error -during communication with the server or if dpy does not support the -SYNC extension; otherwise, it returns True. - - - - - Status XSyncChangeAlarm - Display *dpy - XSyncAlarm alarm - unsigned long values_mask - XSyncAlarmAttributes *values - - - - -XSyncChangeAlarm changes alarm’s attributes. The -attributes to change are specified as in -XSyncCreateAlarm. It returns -False if dpy does not support -the SYNC extension; otherwise, it returns True. - - - - - Status XSyncSetPriority - Display *dpy - XID client_resource_id - int priority - - - - -XSyncSetPriority sets the priority of the client -owning client_resource_id to priority. If client_resource_id is None, it -sets the caller’s priority. It returns -False if dpy does not support the SYNC extension; -otherwise, it returns True. - - - - - Status XSyncGetPriority - Display *dpy - XID client_resource_id - int *return_priority - - - - -XSyncGetPriority sets *return_priority to the -priority of the client owning client_resource_id. If client_resource_id -is None, it sets *return_priority to the caller’s priority. It returns -False if there was an error during communication -with the server or if dpy does not support the SYNC extension; otherwise, it -returns True. - - - - - -C Macros/Functions - - -The following procedures manipulate 64-bit values. They are defined both as -macros and as functions. By default, the macro form is used. To use the -function form, #undef the macro name to uncover the function. - - - - - void XSyncIntToValue - XSyncValue *pv - int i - - - - -Converts i to an XSyncValue and stores it in *pv. -Performs sign extension (*pv will have the same sign as i.) - - - - - void XSyncIntsToValue - XSyncValue *pv - unsigned int low - int high - - - - -Stores low in the low 32 bits of *pv and high in the high 32 bits of *pv. - - - - - - Bool XSyncValueGreaterThan - XSyncValue a - XSyncValue b - - - - -Returns True if a is greater than b, else returns -False. - - - - - Bool XSyncValueLessThan - XSyncValue a - XSyncValue b - - - - -Returns True if a is less than b, else returns -False. - - - - - - Bool XSyncValueGreaterOrEqual - XSyncValue a - XSyncValue b - - - - -Returns True if a is greater than or equal to b, -else returns False. - - - - - Bool XSyncValueLessOrEqual - XSyncValue a - XSyncValue b - - - - -Returns True if a is less than or equal to b, -else returns False. - - - - - Bool XSyncValueEqual - XSyncValue a - XSyncValue b - - - - -Returns True if a is equal to b, -else returns False. - - - - - Bool XSyncValueIsNegative - XSyncValue v - - - - -Returns True if v is negative, -else returns False. - - - - - Bool XSyncValueIsZero - XSyncValue v - - - - -Returns True if v is zero, -else returns False. - - - - - Bool XSyncValueIsPositive - XSyncValue v - - - - -Returns True if v is positive, -else returns False. - - - - - unsigned int XSyncValueLow32 - XSyncValue v - - - - -Returns the low 32 bits of v. - - - - - unsigned int XSyncValueHigh32 - XSyncValue v - - - - -Returns the high 32 bits of v. - - - - - void XSyncValueAdd - XSyncValue *presult - XSyncValue a - XSyncValue b - Bool *poverflow - - - - -Adds a to b and stores the result in *presult. If the result could not -fit in 64 bits, *poverflow is set to True, else it is -set to False. - - - - - void XSyncValueSubtract - XSyncValue *presult - XSyncValue a - XSyncValue b - Bool *poverflow - - - - -Subtracts b from a and stores the result in *presult. If the result could not -fit in 64 bits, *poverflow is set to True, else it is -set to False. - - - - - void XSyncMaxValue - XSyncValue *pv - - - - -Sets *pv to the maximum value expressible in 64 bits. - - - - - void XSyncMinValue - XSyncValue *pv - - - - -Sets *pv to the minimum value expressible in 64 bits. - - - - - -Events - - -Let event_base be the value event base return as defined in the function -XSyncQueryExtension. - - - -An XSyncCounterNotifyEvent’s type field has the value -event_base + XSyncCounterNotify. The fields of this -structure are: - - - -int type; /* event base + XSyncCounterNotify */ -unsigned long serial; /* number of last request processed by server */ -Bool send event; /* true if this came from a SendEvent request */ -Display * display; /* Display the event was read from */ -XSyncCounter counter; /* counter involved in await */ -XSyncValue wait_value; /* value being waited for */ -XSyncValue counter_value; /* counter value when this event was sent */ -Time time; /* milliseconds */ -int count; /* how many more events to come */ -Bool destroyed; /* True if counter was destroyed */ - - - -An XSyncAlarmNotifyEvent’s type field has the value -event_base + XSyncAlarmNotify. The fields of -this structure are: - - - -int type; /* event_base + XSyncAlarmNotify */ -unsigned long serial; /* number of last request processed by server */ -Bool send_event; /* true if this came from a SendEvent request */ -Display * display; /*Display the event was read from */ -XSyncAlarm alarm; /* alarm that triggered */ -XSyncValue counter_value /* value that triggered the alarm */ -XSyncValue alarm_value /* test value of trigger in alarm */ -Time time; /* milliseconds */ -XSyncAlarmState state; /* new state of alarm */ - - - - - -Errors - -Let error_base be the value -error_base_return as defined in the function -XSyncQueryExtension. - - - -An XSyncAlarmError’s error_code field has -XSyncBadAlarm. The fields of this structure are: - - - -int type -Display * display; /* Display the event was read from */ -XSyncCounter counter; /* resource id */ -unsigned long serial; /* serial number of failed request */ -unsigned char error_code; /* error_base + XSyncBadAlarm */ -unsigned char request_code; /* Major op-code of failed request */ -unsigned char minor_code; /* Minor op-code of failed request */ - - - -An XSyncCounterError’s error code field has the value -error_base + XSyncBadCounter. The fields of this -structure are: - - -int type -Display * display; /* Display the event was read from */ -XSyncCounter counter; /* resource id */ -unsigned long serial; /* serial number of failed request */ -unsigned char error_code; /* error_base + XSyncBadCounter */ -unsigned char request_code; /* Major op-code of failed request */ -unsigned char minor_code; /* Minor op-code of failed request */ - - - - - + + + + + + + + + X Synchronization Extension Library + X Consortium Standard + X Version 11, Release 6.4 + + + TimGlauert + Olivetti Research/MultiWorks + + + Dave + Carver + Digital Equipment Corporation, MIT/Project Athena + + + Jim + Gettys + Digital Equipment Corporation, Cambridge Research Laboratory + + + David + Wiggins + X Consortium, Inc. + + + Version 3.0 + X Consortium + X Version 11, Release 6.4 + + + +Copyright 1991 by Olivetti Research Limited, Cambridge England and Digital Equipment Corporation, Maynard, Massachusetts + + + +Permission to use, copy, modify, and distribute this documentation for any +purpose and without fee is hereby granted, provided that the above +copyright notice appear in all copies. Olivetti, Digital, MIT, and the +X Consortium make no representations about the suitability for any purpose +of the information in this document. This documentation is provided as +is without express or implied warranty. + + + + + + +Copyright © 1991 X Consortium, Inc. + + + +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, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished +to do so, subject to the following conditions: + + + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + + +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. +IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + + + +Except as contained in this notice, the name of the X Consortium shall +not be used in advertising or otherwise to promote the sale, use or other +dealings in this Software without prior written authorization from the +X Consortium. + + + + + + +Synchronization Protocol + + +The core X protocol makes no guarantees about the relative order of +execution of requests for different clients. This means that any +synchronization between clients must be done at the client level in an +operating system-dependent and network-dependent manner. Even if there +was an accepted standard for such synchronization, the use of a network +introduces unpredictable delays between the synchronization of the clients and +the delivery of the resulting requests to the X server. + + +The core X protocol also makes no guarantees about the time at which +requests are executed, which means that all clients with real-time constraints +must implement their timing on the host computer. Any such timings are +subject to error introduced by delays within the operating system and +network and are inefficient because of the need for round-trip requests that +keep the client and server synchronized. + + +The synchronization extension provides primitives that allow synchronization +between clients to take place entirely within the X server. This removes any +error introduced by the network and makes it possible to synchronize clients +on different hosts running different operating systems. This is important for +multimedia applications, where audio, video, and graphics data streams are +being synchronized. The extension also provides internal timers within the X +server to which client requests can be synchronized. This allows simple +animation applications to be implemented without any round-trip requests +and makes best use of buffering within the client, network, and server. + + + +Description + +The mechanism used by this extension for synchronization within the X server +is to block the processing of requests from a client until a specific +synchronization condition occurs. When the condition occurs, the client is +released and processing of requests continues. Multiple clients may block on +the same condition to give inter-client synchronization. Alternatively, a single +client may block on a condition such as an animation frame marker. + + +The extension adds Counter and +Alarm to the set of resources managed by +the server. A counter has a 64-bit integer value that may be increased or +decreased by client requests or by the server internally. A client can +block by sending an Await request that waits until +one of a set of synchronization conditions, called TRIGGERs, becomes TRUE. + + +The CreateCounter request allows a client to create +a Counter that can be changed by explicit +SetCounter and ChangeCounter +requests. These can be used to implement synchronization between +different clients. + + +There are some counters, called System Counters, +that are changed by the server internally rather than by client +requests. The effect of any change to a system counter is not visible +until the server has finished processing the current request. In other +words, system counters are apparently updated in the gaps between the +execution of requests rather than during the actual execution of a +request. The extension provides a system counter that advances with the +server time as defined by the core protocol, and it may also provide +counters that advance with the real-world time or that change each +time the CRT screen is refreshed. Other extensions may provide their own +extension-specific system counters. + + +The extension provides an Alarm mechanism that allows clients to receive an +event on a regular basis when a particular counter is changed. + + + + + +C Language Binding + + +The C routines provide direct access to the protocol and add no additional +semantics. + + +The include file for this extension is <X11/extensions/sync.h>. +Most of the names in the language binding are derived from the protocol +names by prepending XSync to the protocol name and changing the +capitalization. + + + +C Functions + + +Most of the following functions generate SYNC protocol requests. + + + + + Status XSyncQueryExtension + Display *dpy + int *event_base_return + int *error_base_return + + + + +If dpy supports the SYNC extension, +XSyncQueryExtension returns True, +sets *event_base_return to the event number for the first SYNC event, and +sets *error_base_return to the error number for the first SYNC error. If dpy +does not support the SYNC extension, it returns False. + + + + + Status XSyncInitialize + Display *dpy + int *major_version_return + int *minor_version_return + + + + +XSyncInitialize sets *major_version_return and +*minor version return to the major/minor SYNC protocol version supported +by the server. If the XSync library is compatible with the version +returned by the server, this function returns True. +If dpy does not support the SYNC extension, or if there was an error +during communication with the server, or if the server and library protocol +versions are incompatible, this function returns False. +The only XSync function that may be called before this function is +XSyncQueryExtension. If a client violates this rule, the effects of all XSync +calls that it makes are undefined. + + + + + XSyncSystemCounter *XSyncListSystemCounters + Display *dpy + int *n_counters_return + + + + +XSyncListSystemCounters returns a pointer to an array +of system counters supported by the display and sets *n_counters_return +to the number of counters in the array. The array should be freed with +XSyncFreeSystemCounterList. If dpy does not support +the SYNC extension, or if there was an error during communication with +the server, or if the server does not support any system counters, +this function returns NULL. + + + +XSyncSystemCounter has the following fields: + + + +char * name; /* null-terminated name of system counter */ +XSyncCounter counter; /* counter id of this system counter */ +XSyncValue resolution; /* resolution of this system counter */ + + + + + void XSyncFreeSystemCounterList + XSyncSystemCounter *list + + + + +XSyncFreeSystemCounterList frees the memory +associated with the system counter list returned by +XSyncListSystemCounters. + + + + + XSyncCounter XSyncCreateCounter + Display *dpy + XSyncValue initial_value + + + + +XSyncCreateCounter creates a counter on the dpy +with the given initial value and returns the counter ID. It returns +None if dpy does not support the SYNC extension. + + + + + Status XSyncSetCounter + Display *dpy + XSyncCounter counter + XSyncValue value + + + + + +XSyncSetCounter sets counter to value. It returns +False if dpy does not +support the SYNC extension; otherwise, it returns True. + + + + + Status XSyncChangeCounter + Display *dpy + XSyncCounter counter + XSyncValue value + + + + +XSyncChangeCounter adds value to counter. It returns +False if dpy does not support the SYNC extension; +otherwise, it returns +True. + + + + Status XSyncDestroyCounter + Display *dpy + XSyncCounter counter + + + + +XSyncDestroyCounter destroys counter. It returns +False if dpy does not support the SYNC extension; +otherwise, it returns True. + + + + + Status XSyncQueryCounter + Display *dpy + XSyncCounter counter + XSyncValue *value_return + + + + +XSyncQueryCounter sets *value_return to the current +value of counter. It returns False if there was an +error during communication with the server or if dpy does not support the +SYNC extension; otherwise, it returns True. + + + + + Status XSyncAwait + Display *dpy + XSyncWaitCondition *wait_list + int n_conditions + + + + +XSyncAwait awaits on the conditions in wait_list. +The n_conditions is the number of wait conditions in wait_list. It +returns False if dpy does not support the SYNC +extension; otherwise, it returns True. The await is +processed asynchronously by the server; this function always returns +immediately after issuing the request. + + +XSyncWaitCondition has the following fields: + + + +XSyncCounter trigger.counter; /*counter to trigger on */ +XSyncValueType trigger.value_type; /*absolute/relative */ +XSyncValue trigger.wait_value; /*value to compare counter to */ +XSyncTestType trigger.test_type; /*pos/neg comparison/transtion */ +XSyncValue event_threshold; /*send event if past threshold */ + + + +XSyncValueType can be either +XSyncAbsolute or XSyncRelative. + + + +XSyncTestType can be one of +XSyncPositiveTransition, +XSyncNegativeTransition, +XSyncPositiveComparison, or +XSyncNegativeComparison. + + + + + XSyncAlarm XSyncCreateAlarm + Display *dpy + unsigned long values_mask + XSyncAlarmAttributes *values` + + + + +XSyncCreateAlarm creates an alarm and returns the +alarm ID. It returns None if the display does not support the SYNC +extension. The values_mask and values specify the alarm attributes. + + + +XSyncAlarmAttributes has the following fields. The +attribute_mask column specifies the symbol that the caller should OR +into values_mask to indicate that the value for the corresponding +attribute was actually supplied. Default values are used for all +attributes that do not have their attribute_mask OR’ed into values_mask. +See the protocol description for CreateAlarm for the +defaults. + + + +type field name attribute_mask +XSyncCounter trigger.counter; XSyncCACounter +XSyncValueType trigger.value_type; XSyncCAValueType +XSyncValue trigger.wait_value; XSyncCAValue +XSyncTestType trigger.test_type; XSyncCATestType +XSyncValue delta; XSyncCADelta +Bool events; XSyncCAEvents +XSyncAlarmState state; client cannot set this + + + + + Status XSyncDestroyAlarm + Display *dpy + XSyncAlarm alarm + + + + +XSyncDestroyAlarm destroys alarm. It returns +False if dpy does not support +the SYNC extension; otherwise, it returns True. + + + + + Status XSyncQueryAlarm + Display *dpy + XSyncAlarm alarm + XSyncAlarmAttributes *values_return + + + + + +XSyncQueryAlarm sets *values_return to the alarm’s +attributes. It returns False if there was an error +during communication with the server or if dpy does not support the +SYNC extension; otherwise, it returns True. + + + + + Status XSyncChangeAlarm + Display *dpy + XSyncAlarm alarm + unsigned long values_mask + XSyncAlarmAttributes *values + + + + +XSyncChangeAlarm changes alarm’s attributes. The +attributes to change are specified as in +XSyncCreateAlarm. It returns +False if dpy does not support +the SYNC extension; otherwise, it returns True. + + + + + Status XSyncSetPriority + Display *dpy + XID client_resource_id + int priority + + + + +XSyncSetPriority sets the priority of the client +owning client_resource_id to priority. If client_resource_id is None, it +sets the caller’s priority. It returns +False if dpy does not support the SYNC extension; +otherwise, it returns True. + + + + + Status XSyncGetPriority + Display *dpy + XID client_resource_id + int *return_priority + + + + +XSyncGetPriority sets *return_priority to the +priority of the client owning client_resource_id. If client_resource_id +is None, it sets *return_priority to the caller’s priority. It returns +False if there was an error during communication +with the server or if dpy does not support the SYNC extension; otherwise, it +returns True. + + + + + +C Macros/Functions + + +The following procedures manipulate 64-bit values. They are defined both as +macros and as functions. By default, the macro form is used. To use the +function form, #undef the macro name to uncover the function. + + + + + void XSyncIntToValue + XSyncValue *pv + int i + + + + +Converts i to an XSyncValue and stores it in *pv. +Performs sign extension (*pv will have the same sign as i.) + + + + + void XSyncIntsToValue + XSyncValue *pv + unsigned int low + int high + + + + +Stores low in the low 32 bits of *pv and high in the high 32 bits of *pv. + + + + + + Bool XSyncValueGreaterThan + XSyncValue a + XSyncValue b + + + + +Returns True if a is greater than b, else returns +False. + + + + + Bool XSyncValueLessThan + XSyncValue a + XSyncValue b + + + + +Returns True if a is less than b, else returns +False. + + + + + + Bool XSyncValueGreaterOrEqual + XSyncValue a + XSyncValue b + + + + +Returns True if a is greater than or equal to b, +else returns False. + + + + + Bool XSyncValueLessOrEqual + XSyncValue a + XSyncValue b + + + + +Returns True if a is less than or equal to b, +else returns False. + + + + + Bool XSyncValueEqual + XSyncValue a + XSyncValue b + + + + +Returns True if a is equal to b, +else returns False. + + + + + Bool XSyncValueIsNegative + XSyncValue v + + + + +Returns True if v is negative, +else returns False. + + + + + Bool XSyncValueIsZero + XSyncValue v + + + + +Returns True if v is zero, +else returns False. + + + + + Bool XSyncValueIsPositive + XSyncValue v + + + + +Returns True if v is positive, +else returns False. + + + + + unsigned int XSyncValueLow32 + XSyncValue v + + + + +Returns the low 32 bits of v. + + + + + unsigned int XSyncValueHigh32 + XSyncValue v + + + + +Returns the high 32 bits of v. + + + + + void XSyncValueAdd + XSyncValue *presult + XSyncValue a + XSyncValue b + Bool *poverflow + + + + +Adds a to b and stores the result in *presult. If the result could not +fit in 64 bits, *poverflow is set to True, else it is +set to False. + + + + + void XSyncValueSubtract + XSyncValue *presult + XSyncValue a + XSyncValue b + Bool *poverflow + + + + +Subtracts b from a and stores the result in *presult. If the result could not +fit in 64 bits, *poverflow is set to True, else it is +set to False. + + + + + void XSyncMaxValue + XSyncValue *pv + + + + +Sets *pv to the maximum value expressible in 64 bits. + + + + + void XSyncMinValue + XSyncValue *pv + + + + +Sets *pv to the minimum value expressible in 64 bits. + + + + + +Events + + +Let event_base be the value event base return as defined in the function +XSyncQueryExtension. + + + +An XSyncCounterNotifyEvent’s type field has the value +event_base + XSyncCounterNotify. The fields of this +structure are: + + + +int type; /* event base + XSyncCounterNotify */ +unsigned long serial; /* number of last request processed by server */ +Bool send event; /* true if this came from a SendEvent request */ +Display * display; /* Display the event was read from */ +XSyncCounter counter; /* counter involved in await */ +XSyncValue wait_value; /* value being waited for */ +XSyncValue counter_value; /* counter value when this event was sent */ +Time time; /* milliseconds */ +int count; /* how many more events to come */ +Bool destroyed; /* True if counter was destroyed */ + + + +An XSyncAlarmNotifyEvent’s type field has the value +event_base + XSyncAlarmNotify. The fields of +this structure are: + + + +int type; /* event_base + XSyncAlarmNotify */ +unsigned long serial; /* number of last request processed by server */ +Bool send_event; /* true if this came from a SendEvent request */ +Display * display; /*Display the event was read from */ +XSyncAlarm alarm; /* alarm that triggered */ +XSyncValue counter_value /* value that triggered the alarm */ +XSyncValue alarm_value /* test value of trigger in alarm */ +Time time; /* milliseconds */ +XSyncAlarmState state; /* new state of alarm */ + + + + + +Errors + +Let error_base be the value +error_base_return as defined in the function +XSyncQueryExtension. + + + +An XSyncAlarmError’s error_code field has +XSyncBadAlarm. The fields of this structure are: + + + +int type +Display * display; /* Display the event was read from */ +XSyncCounter counter; /* resource id */ +unsigned long serial; /* serial number of failed request */ +unsigned char error_code; /* error_base + XSyncBadAlarm */ +unsigned char request_code; /* Major op-code of failed request */ +unsigned char minor_code; /* Minor op-code of failed request */ + + + +An XSyncCounterError’s error code field has the value +error_base + XSyncBadCounter. The fields of this +structure are: + + +int type +Display * display; /* Display the event was read from */ +XSyncCounter counter; /* resource id */ +unsigned long serial; /* serial number of failed request */ +unsigned char error_code; /* error_base + XSyncBadCounter */ +unsigned char request_code; /* Major op-code of failed request */ +unsigned char minor_code; /* Minor op-code of failed request */ + + + + + -- cgit v1.2.3