diff options
author | Eric Anholt <eric@anholt.net> | 2007-01-09 10:52:55 -0800 |
---|---|---|
committer | Eric Anholt <eric@anholt.net> | 2007-01-09 10:55:31 -0800 |
commit | 181ab067fdb5b55834cb6a8f3587f80f243dc401 (patch) | |
tree | 63daf8af8ddfb02acade36784189207e7db071c5 /specs | |
parent | ac409b9b393c739fc49e193c15412848124dec32 (diff) |
Remove duplicated specs from proto modules.
Updates that happened to these files (assuming the initial import was already
from modular) have been propagated back to the proper locations in the
protocol modules.
Diffstat (limited to 'specs')
-rw-r--r-- | specs/Composite/protocol | 281 | ||||
-rw-r--r-- | specs/Damage/protocol | 190 | ||||
-rw-r--r-- | specs/Fixes/protocol | 564 | ||||
-rw-r--r-- | specs/Randr/protocol.txt | 519 |
4 files changed, 0 insertions, 1554 deletions
diff --git a/specs/Composite/protocol b/specs/Composite/protocol deleted file mode 100644 index aba9df4..0000000 --- a/specs/Composite/protocol +++ /dev/null @@ -1,281 +0,0 @@ - Composite Extension - - Version 0.2 - 2004-7-8 - Keith Packard - keithp@keithp.com - - Version 0.3 - 2006-5-13 - Deron Johnson - deron.johnson@sun.com - - -1. Introduction - -Many user interface operations would benefit from having pixel contents of -window hierarchies available without respect to sibling and antecedent -clipping. In addition, placing control over the composition of these pixel -contents into a final screen image in an external application will enable -a flexible system for dynamic application content presentation. - -2. Acknowledgements - -This small extension has been brewing for several years, contributors to -both early prototypes and the final design include: - - + Bill Haneman for motivating the ability to magnify occluded windows - with his work on accessibility - - + Carsten Haitzler for Enlightenment, the original eye-candy window - manager which demonstrated that clever hacks are an awfully - close substitute for changes in the underlying system. - - + Jim Gettys for key insights into the relationship between damage - events and per-window pixmap usage - - + Mike Harris and Owen Taylor for figuring out what to call it. - -3. Architecture - -The composite extension provides two related mechanisms: - - 1. Per-hierarchy storage. The rendering of an entire hierarchy of windows - is redirected to off-screen storage. The pixels of that hierarchy - are available whenever it is viewable. Storage is automatically - reallocated when the top level window changes size. Contents beyond - the geometry of the top window are not preserved. - - 2. Automatic shadow update. When a hierarchy is rendered off-screen, - the X server provides an automatic mechanism for presenting those - contents within the parent window. The implementation is free to - make this update lag behind actual rendering operations by an - unspecified amount of time. This automatic update mechanism may - be disabled so that the parent window contents can be completely - determined by an external application. - -Per-hierarchy storage may be created for individual windows or for all -children of a window. Manual shadow update may be selected by only a single -application for each window; manual update may also be selected on a -per-window basis or for each child of a window. Detecting when to update -may be done with the Damage extension. - -The off-screen storage includes the window contents, its borders and the -contents of all descendants. - -Version 0.2 of the protocol introduces a mechanism for associating an XID -with the off-screen pixmap used to store these contents. This can be used -to hold onto window contents after the window is unmapped (and hence animate -it's disappearance), and also to access the border of the window, which is -not reachable through the Window ID itself. A new pixmap is created each -time the window is mapped or resized; as these events are nicely signalled -with existing events, no additional notification is needed. The old pixmap -will remain allocated as long as the Pixmap ID is left valid, it is -important that the client use the FreePixmap request when it is done with -the contents and to create a new name for the newly allocated pixmap. - -In automatic update mode, the X server is itself responsible for presenting -the child window contents within the parent. It seems reasonable, then, for -rendering to the parent window to be clipped so as not to interfere with any -child window content. In an environment with a mixure of manual and -automatic updating windows, rendering to the parent in the area nominally -occupied by a manual update window should be able to affect parent pixel -values in those areas, but such rendering should be clipped to automatic -update windows, and presumably to other manual update windows managed by -other applications. In any of these cases, it should be easy to ensure that -rendering has no effect on any non-redirected windows. - -Instead of attempting to define new clipping modes for rendering, the -Composite extension instead defines ClipByChildren rendering to the parent -to exclude regions occupied by redirected windows (either automatic or -manual). The CreateRegionFromBorderClip request can be used along with -IncludeInferiors clipping modes to restrict manual shadow updates to the -apporpriate region of the screen. Bracketing operations with -GrabServer/UngrabServer will permit atomic sequences that can update the -screen without artifact. As all of these operations are asynchronous, -network latency should not adversely affect update latency. - -4. Errors - -The composite extension does not define any new errors. - -5. Types - - UPDATETYPE { Automatic, Manual } - -6. Events - -The composite extension does not define any new events. - -7. Extension Initialization - -The client must negotiate the version of the extension before executing -extension requests. Otherwise, the server will return BadRequest for any -operations other than QueryVersion. - - QueryVersion - - client-major-version: CARD32 - client-minor-version: CARD32 - - -> - - major-version: CARD32 - minor-version: CARD32 - - The client sends the highest supported version to the server and - the server sends the highest version it supports, but no higher than - the requested version. Major versions changes can introduce - incompatibilities in existing functionality, minor version - changes introduce only backward compatible changes. It is - the client's responsibility to ensure that the server supports - a version which is compatible with its expectations. Servers - are encouraged to support multiple versions of the extension. - -8. Hierarchy Redirection - - RedirectWindow - - window: Window - update: UPDATETYPE - - errors: Window, Access, Match - - The hierarchy starting at 'window' is directed to off-screen - storage. 'automatic-update' specifies whether the contents - are mirrored to the parent window automatically or not. Only - one client may specify this flag, another attempt will result in an - Access error. When all clients enabling redirection terminate, - the redirection will automatically be disabled. - - The root window may not be redirected. Doing so results in a Match - error. - - RedirectSubwindows - - window: Window - update UPDATETYPE - - errors: Window, Access - - Hierarchies starting at all current and future children of window - will be redirected as in RedirectWindow. If update is Manual, - then painting of the window background during window manipulation - and ClearArea requests is inhibited. - - UnredirectWindow: - - window: Window - - errors: Window, Value - - Redirection of the specified window will be terminated. If - the specified window was not selected for redirection by the - current client, a 'Value' error results. - - UnredirectWindows: - - window: Window - - errors: Window, Value - - Redirection of all children of window will be terminated. If - the specified window was not selected for sub-redirection by the - current client, a 'Value' error results. - -9. Clip lists - - CreateRegionFromBorderClip - - region: Region - window: Window - - errors: Window, IDChoice - - This request creates a region containing the "usual" border clip - value; that is the area of the window clipped against siblings and - the parent. This region can be used to restrict rendering to - suitable areas while updating only a single window. The region - is copied at the moment the request is executed; future changes - to the window hierarchy will not be reflected in this region. - -10. Associating a Pixmap ID with the off-screen storage (0.2 and later) - - NameWindowPixmap - - window: Window - pixmap: Pixmap - - errors: Window, Match, IDChoice - - This request makes 'pixmap' a reference to the off-screen storage - for 'window'. This pixmap will remain allocated until freed, even - if 'window' is unmapped, reconfigured or destroyed. However, - 'window' will get a new pixmap allocated each time it is - mapped or resized, so this request will need to be reinvoked for - the client to continue to refer to the storage holding the current - window contents. Generates a 'Match' error if 'window' is not - redirected. - -Version 0.3: - -11. Composite Overlay Window - -The Composite Overlay Window provides composite managers with a -surface on which to draw without interference. This window is always -above normal windows and is always below the screen saver window. It -is an InputOutput window whose width and height are the screen -dimensions. Its visual is the root visual and its border width is -zero. Attempts to redirect it using the composite extension are -ignored. This window does not appear in the reply of the QueryTree -request. It is also an override redirect window. These last two -features make it invisible to window managers and other X11 -clients. The only way to access the XID of this window is via the -CompositeGetOverlayWindow request. Initially, the Composite Overlay -Window is unmapped. - -CompositeGetOverlayWindow returns the XID of the Composite Overlay -Window. If the window has not yet been mapped, it is mapped by this -request. When all clients who have called this request have terminated -their X11 connections the window is unmapped. - -Composite managers may render directly to the Composite Overlay -Window, or they may reparent other windows to be children of this -window and render to these. Multiple clients may render to the -Composite Overlay Window, create child windows of it, reshape it, and -redefine its input region, but the specific arbitration rules followed -by these clients is not defined by this specification; these policies -should be defined by the clients themselves. - - CompositeGetOverlayWindow - - window: Window - - -> - - overlayWin: Window - - This request returns the XID of the Composite Overlay Window for - the screen specified by the argument 'window'. This request - indicates that the client wishes to use the Composite Overlay - Window of this screen. If this Composite Overlay Window has not - yet been mapped, it is mapped by this request. - - The Composite Overlay Window for a particular screen will be - unmapped when all clients who have invoked this request have - also invoked CompositeReleaseOverlayWindow for that screen. Also, - CompositeReleaseOverlayWindow for a screen will be implicitly - called when a client using the Composite Overlay Window on that - screen terminates its X11 connection. - - - CompositeReleaseOverlayWindow - - window: Window - - This request specifies that the client is no longer using the - Composite Overlay Window on the screen specified by the - argument 'window'. A screen's Composite Overlay Window is - unmapped when there are no longer any clients using it. - - diff --git a/specs/Damage/protocol b/specs/Damage/protocol deleted file mode 100644 index 7bbfc13..0000000 --- a/specs/Damage/protocol +++ /dev/null @@ -1,190 +0,0 @@ - The DAMAGE Extension - Protocol Version 0.0 - Document Revision 1 - 2003-11-03 - - Keith Packard - keithp@keithp.com - -1. Introduction - -Monitoring the regions affected by rendering has wide-spread use, from -VNC-like systems scraping the screen to screen magnifying applications -designed to aid users with limited visual acuity. The DAMAGE extension is -designed to make such applications reasonably efficient in the face of -server-client latency. - -2. Acknolwedgements - -As usual, the author had significant input from many people, in particular: - - + Havoc Pennington who designed and implemented a Damage extension - last year which was then lost to the mists of time. - - + Bill Haneman whose work on accessibility in the Gnome environment - is legendary. - - + Jim Gettys who found a way to avoid streaming damage rectangles - to the client in many cases. - - + Owen Taylor who suggested that streaming damage rectangles may - be warranted in some cases after all. - -3. Damage Model - -We call changes made to pixel contents of windows and pixmaps 'damage' -throughout this extension. Another notion of 'damage' are drawable regions -which are in need of redisplay to repair the effects of window manipulation -or other data loss. This extension doesn't deal with this second notion at -all; suggestions on a better term which isn't easily conflated with existing -notions are eagerly solicited. - -Damage accumulates as drawing occurs in the drawable. Each drawing operation -'damages' one or more rectangular areas within the drawable. The rectangles -are guaranteed to include the set of pixels modified by each operation, but -may include significantly more than just those pixels. The desire is for -the damage to strike a balance between the number of rectangles reported and -the extraneous area included. A reasonable goal is for each primitive -object drawn (line, string, rectangle) to be represented as a single -rectangle and for the damage area of the operation to be the union of these -rectangles. - -The DAMAGE extension allows applications to either receive the raw -rectangles as a stream of events, or to have them partially processed within -the X server to reduce the amount of data transmitted as well as reduce the -processing latency once the repaint operation has started. - -Damage to a window reflects both drawing within the window itself as well as -drawing within any inferior window that affects pixels seen by -IncludeInferiors rendering operations. To reduce the computational -complexity of this, the DAMAGE extension allows the server to monitor all -rendering operations within the physical target pixel storage that fall -within the bounds of the window. In a system with a single frame buffer -holding all windows, this means that damage will accumulate for all -rendering operations that lie within the visible part of the window. - -The precise reason for this architecture will be made clear in the XSPLITTREE -extension which will provide multiple pixel storage areas for the screen -contents. - -4. Data types - -The "Damage" object holds any accumulated damage region and reflects the -relationship between the drawable selected for damage notification and the -drawable for which damage is tracked. - -5. Errors - -Damage - A value for a DAMAGE argument does not name a defined DAMAGE. - -6. Types - - DAMAGE 32-bit value (top three bits guaranteed to be zero) - - DamageReportLevel { DamageReportRawRectangles, - DamageReportDeltaRectangles, - DamageReportBoundingBox, - DamageReportNonEmpty } - - DamageReportRawRectangles - - Delivers DamageNotify events each time the screen - is modified with rectangular bounds that circumscribe - the damaged area. No attempt to compress out overlapping - rectangles is made. - - DamageReportDeltaRectangles - - Delivers DamageNotify events each time damage occurs - which is not included in the damage region. The - reported rectangles include only the changes to that - area, not the raw damage data. - - DamageReportBoundingBox - - Delivers DamageNotify events each time the bounding - box enclosing the damage region increases in size. - The reported rectangle encloses the entire damage region, - not just the changes to that size. - - DamageReportNonEmpty - - Delivers a single DamageNotify event each time the - damage rectangle changes from empty to non-empty, and - also whenever the result of a DamageSubtract request - results in a non-empty region. - -7. Events - -DamageNotify - - level: DamageReportLevel - drawable: Drawable - damage: DAMAGE - more: Bool - timestamp: Timestamp - area: Rectangle - drawable-geometry: Rectangle - - 'more' indicates whether there are subsequent damage events - being delivered immediately as part of a larger damage region - -8. Extension Initialization - -The client must negotiate the version of the extension before executing -extension requests. Otherwise, the server will return BadRequest for any -operations other than QueryVersion. - -QueryVersion - - client-major-version: CARD32 - client-minor-version: CARD32 - - -> - - major-version: CARD32 - minor-version: CARD32 - - The client sends the highest supported version to the server and - the server sends the highest version it supports, but no higher than - the requested version. Major versions changes can introduce - incompatibilities in existing functionality, minor version - changes introduce only backward compatible changes. It is - the clients responsibility to ensure that the server supports - a version which is compatible with its expectations. Servers - are encouraged to support multiple versions of the extension. - -9. Enable Monitoring - -DamageCreate - - damage: DAMAGE - drawable: Drawable - level: DamageReportLevel - - Creates a damage object to monitor changes to Drawable - -DamageDestroy - damage: DAMAGE - - Destroys damage. - -DamageSubtract - - damage: DAMAGE - repair: Region or None - parts: Region - - Synchronously modifies the regions in the following manner: - - If repair is None: - - 1) parts = damage - 2) damage = <empty> - - Otherwise: - - 1) parts = damage INTERSECT repair - 2) damage = damage - parts - 3) Generate DamageNotify for remaining damage areas diff --git a/specs/Fixes/protocol b/specs/Fixes/protocol deleted file mode 100644 index 65f042c..0000000 --- a/specs/Fixes/protocol +++ /dev/null @@ -1,564 +0,0 @@ - The XFIXES Extension - Version 4.0 - Document Revision 1 - 2006-12-14 - Keith Packard - keithp@keithp.com - -1. Introduction - -X applications have often needed to work around various shortcomings in the -core X window system. This extension is designed to provide the minimal -server-side support necessary to eliminate problems caused by these -workarounds. - -2. Acknowledgements - -This extension is a direct result of requests made by application -developers, in particular, - - + Owen Taylor for describing the issues raised with the XEMBED - mechanisms and SaveSet processing and his initial extension - to handle this issue. - - + Bill Haneman for the design for cursor image tracking. - - + Havoc Pennington - - + Fredrik Höglund for cursor names - - + Deron Johnson for cursor visibility - -3. Basic Premise - -Requests in this extension may seem to wander all over the map of X server -capabilities, but they are tied by a simple rule -- resolving issues raised -by application interaction with core protocol mechanisms that cannot be -adequately worked around on the client side of the wire. - -4. Extension initialization - -The client must negotiate the version of the extension before executing -extension requests. Behavior of the server is undefined otherwise. - -QueryVersion - - client-major-version: CARD32 - client-minor-version: CARD32 - - -> - - major-version: CARD32 - minor-version: CARD32 - - The client sends the highest supported version to the server and - the server sends the highest version it supports, but no higher than - the requested version. Major versions changes can introduce - new requests, minor version changes introduce only adjustments to - existing requests or backward compatible changes. It is - the clients responsibility to ensure that the server supports - a version which is compatible with its expectations. - -************* XFIXES VERSION 1 OR BETTER *********** - -5. Save Set processing changes - -Embedding one application within another provides a way of unifying -disparate documents and views within a single framework. From the X -protocol perspective, this appears similar to nested window managers; the -embedding application "manages" the embedded windows much as a window -manager does for top-level windows. To protect the embedded application -from embedding application failure, it is reasonable to use the core SaveSet -mechanism so that embedding application failure causes embedded windows to -be preserved instead of destroyed. - -The core save set mechanism defines the target for each save set member -window as the nearest enclosing window not owned by the terminating client. -For embedding applications, this nearest window is usually the window -manager frame. The problem here is that the window manager will not -generally expect to receive and correctly manage new windows appearing within -that window by the save set mechanism, and will instead destroy the frame -window in response to the client window destruction. This causes the -embedded window to be destroyed. - -An easy fix for this problem is to change the target of the save set member -to a window which won't be affected by the underlying window destruction. -XFIXES chooses the root window as the target. - -Having embedded windows suddenly appear at the top level can confuse users, -so XFIXES also permits these windows to remain unmapped instead of being -remapped. - -5.1 Requests - -ChangeSaveSet - - window: Window - mode: { Insert, Delete } - target: { Nearest, Root } - map: { Map, Unmap } - - ChangeSaveSet is an extension of the core protocol ChangeSaveSet - request. As in that request, mode specifies whether the indicated - window is inserted or deleted from the save-set. Target specifies - whether the window is reparented to the nearest non-client window as - in the core protocol, or reparented to the root window. Map - specifies whether the window is mapped as in the core protocol or - unmapped. - -6. Selection Tracking - -Applications wishing to monitor the contents of current selections must -poll for selection changes. XFIXES improves this by providing an event -delivered whenever the selection ownership changes. - -6.1 Types - - SELECTIONEVENT { SetSelectionOwner, - SelectionWindowDestroy, - SelectionClientClose } - -6.1 Events - -SelectionNotify - - subtype: SELECTIONEVENT - window: Window - owner: Window - selection: Atom - timestamp: Timestamp - selection-timestamp: Timestamp - -6.2 Requests - -SelectSelectionInput - - window: Window - selection: Atom - event-mask: SETofSELECTIONEVENT - - Selects for events to be delivered to window when various causes of - ownership of selection occur. Subtype indicates the cause of the - selection ownership change. Owner is set to the current selection - owner, or None. Timestamp indicates the time the event was - generated while selection-timestamp indicates the timestamp used to - own the selection. - -7. Cursor Image Monitoring - -Mirroring the screen contents is easily done with the core protocol or VNC -addons, except for the current cursor image. There is no way using the core -protocol to discover which cursor image is currently displayed. The -cursor image often contains significant semantic content about the user -interface. XFIXES provides a simple mechanism to discover when the cursor -image changes and to fetch the current cursor image. - -As the current cursor may or may not have any XID associated with it, there -is no stable name available. Instead, XFIXES returns only the image of the -current cursor and provides a way to identify cursor images to avoid -refetching the image each time it changes to a previously seen cursor. - -7.1 Types - CURSOREVENT { DisplayCursor } - -7.2 Events - -CursorNotify - - subtype: CURSOREVENT - window: Window - cursor-serial: CARD32 - timestamp: Timestamp - name: Atom (Version 2 only) - -7.3 Requests - -SelectCursorInput - - window: Window - event-mask: SETofCURSOREVENT - - This request directs cursor change events to the named window. - Events will be delivered irrespective of the screen on which they - occur. Subtype indicates the cause of the cursor image change - (there is only one subtype at present). Cursor-serial is a number - assigned to the cursor image which identifies the image. Cursors - with different serial numbers may have different images. Timestamp - is the time of the cursor change. - -GetCursorImage - - -> - - x: INT16 - y: INT16 - width: CARD16 - height: CARD16 - x-hot: CARD16 - y-hot: CARD16 - cursor-serial: CARD32 - cursor-image: LISTofCARD32 - - GetCursorImage returns the image of the current cursor. X and y are - the current cursor position. Width and height are the size of the - cursor image. X-hot and y-hot mark the hotspot within the cursor - image. Cursor-serial provides the number assigned to this cursor - image, this same serial number will be reported in a CursorNotify - event if this cursor image is redisplayed in the future. - - The cursor image itself is returned as a single image at 32 bits per - pixel with 8 bits of alpha in the most significant 8 bits of the - pixel followed by 8 bits each of red, green and finally 8 bits of - blue in the least significant 8 bits. The color components are - pre-multiplied with the alpha component. - -************* XFIXES VERSION 2 OR BETTER *********** - -8. Region Objects - -The core protocol doesn't expose regions as a primitive object and this -makes many operations more complicated than they really need to be. Adding -region objects simplifies expose handling, the Shape extension and other -operations. These operations are also designed to support a separate -extension, the X Damage Extension. - -8.1 Types - - Region: XID - WINDOW_REGION_KIND: { Bounding, Clip } - -8.2 Errors - - Region The specified region is invalid - -8.3 Requests - -CreateRegion - - region: REGION - rects: LISTofRECTANGLE - - Creates a region initialized to the specified list of rectangles. - The rectangles may be specified in any order, their union becomes - the region. The core protocol allows applications to specify an - order for the rectangles, but it turns out to be just as hard to - verify the rectangles are actually in that order as it is to simply - ignore the ordering information and union them together. Hence, - this request dispenses with the ordering information. - - Errors: IDChoice - -CreateRegionFromBitmap - - region: REGION - bitmap: PIXMAP - - Creates a region initialized to the set of 'one' pixels in bitmap - (which must be depth 1, else Match error). - - Errors: Pixmap, IDChoice, Match - -CreateRegionFromWindow - - window: Window - kind: WINDOW_REGION_KIND - region: Region - - Creates a region initialized to the specified window region. See the - Shape extension for the definition of Bounding and Clip regions. - - Errors: Window, IDChoice, Value - -CreateRegionFromGC - - gc: GContext - region: Region - - Creates a region initialized from the clip list of the specified - GContext. - - Errors: GContext, IDChoice - -CreateRegionFromPicture - - picture: Picture - region: Region - - - Creates a region initialized from the clip list of the specified - Picture. - - Errors: Picture, IDChoice - -DestroyRegion - - region: Region - - Destroys the specified region. - - Errors: Region - -SetRegion - - region: Region - rects: LISTofRECTANGLE - - This replaces the current contents of region with the region formed - by the union of rects. - -CopyRegion - source: Region - destination: Region - - This replaces the contents of destination with the contents of - source. - -UnionRegion -IntersectRegion -SubtractRegion - - source1: Region - source2: Region - destination: Region - - Combines source1 and source2, placing the result in destination. - Destination may be the same as either source1 or source2. - - Errors: Region, Value - -InvertRegion - - source: Region - bounds: RECTANGLE - destination: Region - - The source region is subtracted from the region specified by - bounds. The result is placed in destination, replacing its contents. - - Errors: Region - -TranslateRegion - - region: Region - dx, dy: INT16 - - The region is translated by dx, dy in place. - - Errors: Region - -RegionExtents - - source: Region - destination: Region - - The extents of the source region are placed in the destination - -FetchRegion - - region: Region - -> - extents: RECTANGLE - rectangles: LISTofRECTANGLE - - The region is returned as a list of rectangles in YX-banded order. - - Errors: Region - -SetGCClipRegion - - gc: GCONTEXT - clip-x-origin, clip-y-origin: INT16 - region: Region or None - - This request changes clip-mask in gc to the specified region and - sets the clip origin. Output will be clipped to remain contained - within the region. The clip origin is interpreted relative to the - origin of whatever destination drawable is specified in a graphics - request. The region is interpreted relative to the clip origin. - Future changes to region have no effect on the gc clip-mask. - - Errors: GContext, Region - -SetWindowShapeRegion - - dest: Window - destKind: SHAPE_KIND - xOff, yOff: INT16 - region: Region or None - - This request sets the specified (by destKind) Shape extension region - of the window to region, offset by xOff and yOff. Future changes to - region have no effect on the window shape. - - Errors: Window, Value, Region - -SetPictureClipRegion - - picture: Picture - clip-x-origin, clip-y-origin: INT16 - region: Region or None - - This request changes clip-mask in picture to the specified region - and sets the clip origin. Input and output will be clipped to - remain contained within the region. The clip origin is interpreted - relative to the origin of the drawable associated with picture. The - region is interpreted relative to the clip origin. Future changes - to region have no effect on the picture clip-mask. - - Errors: Picture, Region - -9. Cursor Names - -Attaching names to cursors permits some abstract semantic content to be -associated with specific cursor images. Reflecting those names back to -applications allows that semantic content to be related to the user through -non-visual means. - -9.1 Events - -CursorNotify - - subtype: CURSOREVENT - window: Window - cursor-serial: CARD32 - timestamp: Timestamp - name: Atom or None - - In Version 2 of the XFIXES protocol, this event adds the atom - of any name associated with the current cursor (else None). - -9.2 Requests - -SetCursorName - - cursor: CURSOR - name: LISTofCARD8 - - This request interns name as an atom and sets that atom as the name - of cursor. - - Errors: Cursor - -GetCursorName - - cursor: CURSOR - -> - atom: ATOM or None - name: LISTofCARD8 - - This request returns the name and atom of cursor. If no name is - set, atom is None and name is empty. - - Errors: Cursor - -GetCursorImageAndName - - -> - - x: INT16 - y: INT16 - width: CARD16 - height: CARD16 - x-hot: CARD16 - y-hot: CARD16 - cursor-serial: CARD32 - cursor-atom: ATOM - cursor-name: LISTofCARD8 - cursor-image: LISTofCARD32 - - This is similar to GetCursorImage except for including both - the atom and name of the current cursor. - -ChangeCursor - - source, destination: CURSOR - - This request replaces all references to the destination with a - reference to source. Any existing uses of the destination cursor - object will now show the source cursor image. - -ChangeCursorByName - - src: CURSOR - name: LISTofCARD8 - - This request replaces the contents of all cursors with the specified - name with the src cursor. - -************* XFIXES VERSION 3 OR BETTER *********** - -10. Region Expansion - -This update provides another operation on the region objects defined in -Section 8 of this document. - -10.1 Requests - -ExpandRegion - source: REGION - destination: REGION - left, right, top, bottom: CARD16 - - Creates destination region containing the area specified by - expanding each rectangle in the source region by the specified - number of pixels to the left, right, top and bottom. - -************* XFIXES VERSION 4 OR BETTER *********** - -11. Cursor Visibility - -Composite managers may want to render the cursor themselves instead of -relying on the X server sprite drawing, this provides a way for them to -do so without getting a double cursor image. - -11.1 Requests - -HideCursor - - window: WINDOW - - A client sends this request to indicate that it wants the - cursor image to be hidden (i.e. to not be displayed) when - the sprite is inside the specified window, or one of its - subwindows. If the sprite is inside a window for which one - or more active clients have requested cursor hiding then the - cursor image will not be displayed. - - Note that even though cursor hiding causes the cursor image - to be invisible, CursorNotify events will still be sent - normally, as if the cursor image were visible. - - If, during a grab, one or more active clients have requested - cursor hiding for grab window, or one of its ancestors, the - cursor image of the grab cursor will not be displayed during - the lifetime of that grab. - - When a client with outstanding cursor hiding requests - terminates its connection these requests will be deleted. - -ShowCursor - - window: WINDOW - - A client sends this request to indicate that it wants the - cursor image to be displayed when the sprite is inside the - specified window, or one of its subwindows. If the sprite - is inside a window for which no active clients have requested - cursor hiding then the cursor image for that window will be - displayed. In other words, if a client calls HideCursor for - a specified window, or window subtree, this request reverses - the effects of the HideCursor request. - - If the client has made no outstanding HideCursor requests - a BadMatch error is generated. - - -99. Future compatibility - -This extension is not expected to remain fixed. Future changes will -strive to remain compatible if at all possible. The X server will always -support version 1 of the extension protocol if requested by a client. - -Additions to the protocol will always by marked by minor version number -changes so that applications will be able to detect what requests are -supported. diff --git a/specs/Randr/protocol.txt b/specs/Randr/protocol.txt deleted file mode 100644 index aa15f83..0000000 --- a/specs/Randr/protocol.txt +++ /dev/null @@ -1,519 +0,0 @@ - The X Resize, Rotate and Reflect Extension - Version 1.0 - 2002-10-4 - - Jim Gettys - Jim.Gettys@hp.com - - Keith Packard - keithp@xfree86.org - - Cambridge Research Laboratory - HP Labs - Hewlett Packard Company - -1. Introduction - -The X Resize, Rotate and Reflect Extension, called RandR for short, -brings the ability to resize, rotate and reflect the root window of a -screen. It is based on the X Resize and Rotate Extension as specified -in the Proceedings of the 2001 Usenix Technical Conference [RANDR]. - -RandR as implemented and integrated into the XFree86 server differs in -one substantial fashion from the design discussed in that paper: that -is, RandR 1.0 does not implement the depth switching described in that -document, and the support described for that in the protocol in that -document and in the XFree86 implementationhas been removed from the -protocol described here, as it has been overtaken by events. - -These events include: - o Modern toolkits (in this case, GTK+ 2.x) have progressed to the point - of implementing migration between screens of arbitrary depths - o The continued advance of Moore's law has made limited amounts of VRAM - less of an issue, reducing the pressure to implement depth switching - on laptops or desktop systems - o The continued decline of legacy toolkits whose design would have - required depth switching to support migration - o The lack of depth switchin implementation experience in the - intervening time, due to events beyond our control - -Additionally, the requirement to support depth switching might -complicate other re-engineering of the device independent part of the -X server that is currently being contemplated. - -Rather than further delaying RandR's widespread deployment for a -feature long wanted by the community (resizing of screens, -particularly on laptops), or the deployment of a protocol design that -might be flawed due to lack of implementation experience, we decided -to remove depth switching from the protocol. It may be implementated -at a later time if resources and interests permit as a revision to the -protocol described here, which will remain a stable base for -applications. The protocol described here has been implemented in the -main XFree86 server, and more fully in the TinyX implementation in the -XFree86 distribution, which fully implements resizing, rotation and -reflection. - -2. Acknowlegements - -Our thanks to the contributors to the design found on the xpert mailing list. - -2. Screen change model - -Screens may change dynamically, either under control of this -extension, or due to external events. Examples include: monitors being -swapped, you pressing a button to switch from internal display to an -external monitor on a laptop, or, eventually, the hotplug of a display -card entirely on busses such as Cardbus which permit hot-swap (which -will require other work in addition to this extension). - -Since the screen configuration is dynamic and asynchronous to the -client and may change at any time RandR provides mechanisms to ensure -that your clients view is up to date with the configuration -possibilities of the moment and enforces applications that wish to -control the configuration to prove that their information is up to -date before honoring requests to change the screen configuration (by -requiring a timestamp on the request). - -Interested applications are notified whenever the screen configuration -changes, providing the current size of the screen and subpixel order -(see the Render extension [RENDER]), to enabel proper rendering of -subpixel decimated client text to continue, along with a time stamp of -the configuration change. A client must refresh its knowledge of the -screen configuration before attempting to change the configuration -after a notification, or the request will fail. - -To avoid multiplicative explosion between orientation, reflection -and sizes, the sizes are only those sizes in the normal (0) rotation. - -Rotation and reflection and how they interact can be confusing. In -Randr, the coordinate system is rotated in a counter-clockwise -direction relative to the normal orientation. Reflection is along the -window system coordinate system, not the physical screen X and Y axis, -so that rotation and reflection do not interact. The other way to -consider reflection is to is specified in the "normal" orientation, -before rotation, if you find the other way confusing. - -We expect that most clients and toolkits will be oblivious to changes -to the screen stucture, as they generally use the values in the -connections Display structure directly. By toolkits updating the -values on the fly, we believe pop-up menus and other pop up windows -will position themselves correctly in the face of screen configuration -changes (the issue is ensuring that pop-ups are visible on the -reconfigured screen). - -3. Data Types - -The subpixel order is shared with the Render extension, and is -documented there. The only datatype defined is the screen size, -defined in the normal (0 degree) orientation. - - -4. Errors - -There are no new error types defined by this extension. - -5. Protocol Types - -ROTATION { - RR_rotate_0 - RR_rotate_90 - RR_rotate_180 - RR_rotate_270 - RR-Reflect_X - RR_Reflect_Y } - -RRSELECTMASK { RRScreenChangeNotifyMask } - -SIZEID { CARD16 } - -SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render - SubPixelHorizontalRGB extensions definitions; they are here - SubPixelHorizontalBGR only for convenience. - SubPixelVerticalRGB - SubPixelVerticalBGR - SubPixelNone } - - -6. Extension Initialization - -The name of this extension is "RANDR". - -RRQueryVersion - client-major-version: CARD32 - client-minor-version: CARD32 - -> - major-version: CARD32 - minor-version: CARD32 - - The client sends the highest supported version to the server - and the server sends the highest version it supports, but no - higher than the requested version. Major versions changes can - introduce incompatibilities in existing functionality, minor - version changes introduce only backward compatible changes. - It is the clients responsibility to ensure that the server - supports a version which is compatible with its expectations. - -7. Extension Requests - -RRSelectInput - window: WINDOW - enable: SETofRRSELECTMASK - - Errors: BadWindow, BadValue - - If enable is RRScreenChangeNotifyMask, RRScreenChangeNotify - events will be sent anytime the screen configuration changes, - either from this protocol extension, or due to detected - external screen configuration changes. RRScreenChangeNotify - may also be sent immediately if the screen configuration has - changed since the client connected, to avoid race conditions. - -RRSetScreenConfig - drawable: DRAWABLE - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - sizeID: SIZEID - rotation: ROTATION - rate: CARD16 - - -> - - new-timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - root: WINDOW - subpixelOrder: SUBPIXELORDER - - Errors: BadValue, BadMatch - - If the timestamp in this request is less than the time when - the configuration was last successfully set, the request is - ignored and False returned in success. If the - config-timestamp in this request is not equal to when the - server's screen configurations last changed, the request is - ignored and False returned in success. This could occur if - the screen changed since you last made a RRGetScreenInfo - request, perhaps by a different piece of display hardware - being installed. Rather than allowing an incorrect call to be - executed based on stale data, the server will ignore the - request. - - If rate is zero, the server selects an appropriate rate. - - If the request succeeds, this request sets the screen to the - specified size, rate, rotation and reflection. If the requests - succeeds, the new-time-stamp is returned containing the time - when the screen configuration was changed and config-timestamp - is returned to indicate when the possible screen - configurations were last changed, and success is set to True. - The root window for the screen indicated by the drawable - argument is also returned, along with the subpixel order, to - allow correct subpixel rendering. - - BadValue errors are generated if the rotation is not an - allowed rotation. BadValue errors are generated, if, when the - timestamps would allow the operation to succeed, or size-index - are not possible (out of range). - - -RRGetScreenInfo - window: WINDOW - - -> - - rotations: SETofROTATION - root: WINDOW - timestamp: TIMESTAMP - config-timestamp: TIMESTAMP - nSizes: CARD16 - sizeID: SIZEID - rotation: ROTATION - rate: CARD16 - sizes: LISTofSCREENSIZE - refresh: LISTofREFRESH - - where: - - SCREENSIZE { - widthInPixels, heightInPixels: CARD16 - widthInMillimeters, heightInMillimeters: CARD16 } - - REFRESH { - rates: LISTofCARD16 - } - - Errors: BadWindow - - This event is delivered to clients selecting for notification - with RRSelectInput requests using a RRScreenChangeNotifyMask. - - Size-index indicates which size is active. The returned - window is the window requsting notification. - - This call returns the root window of the screen which has changed. - - Rotations contains the set of rotations and reflections - supported by the screen of the window requested. The root - window of that screen is reported. The number of current sizes - supported is returned, along with which size rotation and - reflection the screen is currently set to. - - The config-timestamp indicates when the screen configuration - information last changed: requests to set the screen will fail - unless the timestamp indicates that the information the client - is using is up to date, to ensure clients can be well behaved - in the face of race conditions. Similarly, timestamp indicates - when the configuration was last set, and must both must be up - to date in a call to RRSetScreenConfig for it to succeed. - - Rate is the current refresh rate. This is zero when the refresh - rate is unknown or on devices for which refresh is not relevant. - - Sizes is the list of possible frame buffer sizes (at the - normal orientation, each provide both the linear physical size - of the screen and the pixel size. - - Refresh is the list of refresh rates for each size, each element - of sizes has a cooresponding element in refresh. An empty list - indicates no known rates, or a device for which refresh is not - relevant. - - The default size of the screen (the size that would become the - current size when the server resets) is the first size in the - list. The potential screen sizes themselves are also - returned. - - Toolkits SHOULD use RRScreenChangeSelectInput to be notified - via a RRScreenChangeNotify event, so that they can adapt to - screen size changes. - - -8. Extension Events - -Clients MAY select for ConfigureNotify on the root window to be -informed of screen changes. This may be advantageous if all your -clients need to know is the size of the root window, as it avoids -round trips to set up the extension. - -RRScreenChangeNotify is sent if RRSelectInput has requested it -whenever properties of the screen change, which may be due to external -factors, such as recabling a monitor, etc. - -RRScreenChangeNotify - - rotation: ROTATION; new rotation - sequenceNumber: CARD16 low 16 bits of request's seq. number - timestamp: TIMESTAMP time screen was changed - configTimestamp: TIMESTAMP time config data was changed - root: WINDOW root window of screen - window: WINDOW window requesting notification - sizeID: SIZEID new ID of size - subpixelOrder: SUBPIXELORDER order of subpixels - widthInPixels: INT16 - heightInPixels: INT16 - widthInMillimeters: INT16 - heightInMillimeters: INT16 - - This event is generated whenever the screen configuration is - changed and sent to requesting clients. The timestamp included - indicates when the screen configuration was changed, and - configTimestamp says when the last time the configuration was - changed. The root is the root of the screen the change - occurred on, and the event window is also returned. SizeID - contains an index indicating which size is current. - - This event is sent whenever the screen's configuration changes - or if a new screen configuration becomes available that was - not available in the past. In this case (config-timestamp in - the event not being equal to the config-timestamp returned in - the last call to RRGetScreenInfo), the client MUST call - RRGetScreenInfo to update its view of possible screen - configurations to have a correct view of possible screen - organizations. Timestamp is set to when the active screen - configuration was changed. - - Clients which select screen change notification events may be - sent an event immediately if the screen configuration was - changed between when they connected to the X server and - selected for notification. This is to prevent a common race - that might occur on log-in, where many applications start up - just at the time when a display manager or log in script might - be changing the screen size or configuration. - - -9. Extension Versioning - -The RandR extension was developed in parallel with the implementation -to ensure the feasibility of various portions of the design. As -portions of the extension are implemented, the version number of the -extension has changed to reflect the portions of the standard provied. -This document describes the version 1.0 of the specification, the -partial implementations have version numbers less than that. Here's a -list of what each version before 1.0 implemented: - - 0.0: This prototype implemented resize and rotation in the - TinyX server Used approximately the protocol described in - the Usenix paper. Appeared in the TinyX server in - XFree86 4.2, but not in the XFree86 main server. - - 0.1: Added subpixel order, added an event for subpixel order. - This version was never checked in to XFree86 CVS. - - 1.0: Implements resize, rotation, and reflection. Implemented - both in the XFree86 main server (size change only at this - date), and fully (size change, rotation, and reflection) - in XFree86's TinyX server. - - 1.1: Added refresh rates - -Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients -will fail against 1.0 servers. The wire encoding op-codes were -changed for GetScreenInfo to ensure this failure in a relatively -graceful way. Version 1.1 servers and clients are cross compatible with -1.0. Version 1.1 is considered to be stable and we intend upward -compatibility from this point. - - -Appendix A. Protocol Encoding - -Syntactic Conventions - -This document uses the same syntactic conventions as the core X -protocol encoding document. - - -A.1 Common Types - - SETofROTATION - - 0x0001 RR_Rotate_0 - 0x0002 RR_Rotate_90 - 0x0004 RR_Rotate_180 - 0x0008 RR_Rotate_270 - 0x0010 RR_Reflect_X - 0x0020 RR_Reflect_Y - - - SETofRRSELECTMASK - - 0x0001 RRScreenChangeNotifyMask - - -A.2 Protocol Requests - - -Opcodes 0x1 and 0x3 were used in the 0.0 protocols, and will return -errors if used in version 1.0. - - RRQueryVersion - - 1 CARD8 major opcode - 1 0x01 RandR opcode - 2 3 length - 4 CARD32 major version - 4 CARD32 minor version - -> - 1 1 Reply - 1 unused - 2 CARD16 sequence number - 4 0 reply length - 1 CARD32 major version - 1 CARD32 minor version - - RRSetScreenConfig - - 1 CARD8 major opcode - 1 0x02 RandR opcode - 2 5 length - 4 DRAWABLE drawable on screen to be configured - 4 TIMESTAMP timestamp - 2 SIZEID size id - 2 ROTATION rotation/reflection - 2 CARD16 refresh rate (1.1 only) - 2 CARD16 pad - -> - 1 1 Reply - 1 CARD8 status - 0x0 RRSetConfigSuccess - 0x1 RRSetConfigInvalidConfigTime - 0x2 RRSetConfigInvalidTime - 0x3 RRSetConfigFailed - 2 CARD16 sequence number - 4 0 reply length - 4 TIMESTAMP new timestamp - 4 TIMESTAMP new configuration timestamp - 4 WINDOW root - 2 SUBPIXELORDER subpixel order defined in Render - 2 CARD16 pad4 - 4 CARD32 pad5 - 4 CARD32 pad6 - - - RRSelectInput - - 1 CARD8 major opcode - 1 0x04 RandR opcode - 2 3 length - 4 WINDOW window - 2 SETofRRSELECTMASK enable - 2 CARD16 pad - - - RRGetScreenInfo - - 1 CARD8 major opcode - 1 0x05 RandR opcode - 2 2 length - 4 WINDOW window - -> - 1 1 Reply - 1 CARD8 set of Rotations - 2 CARD16 sequence number - 4 0 reply length - 4 WINDOW root window - 4 TIMESTAMP timestamp - 4 TIMESTAMP config timestamp - 2 CARD16 number of SIZE following - 2 SIZEID sizeID - 2 ROTATION current rotation and reflection - 2 CARD16 rate (1.1) - 2 CARD16 length of rate info (number of CARD16s) - 2 CARD16 pad - - SIZE - 2 CARD16 width in pixels - 2 CARD16 height in pixels - 2 CARD16 width in millimeters - 2 CARD16 height in millimeters - - REFRESH - 2 CARD16 number of rates (n) - 2n CARD16 rates - -A.2 Protocol Event - - RRScreenChangeNotify - - 1 Base + 0 code - 1 ROTATION new rotation and reflection - 2 CARD16 sequence number - 4 TIMESTAMP timestamp - 4 TIMESTAMP configuration timestamp - 4 WINDOW root window - 4 WINDOW request window - 2 SIZEID size ID - 2 SUBPIXELORDER subpixel order defined in Render - 2 CARD16 width in pixels - 2 CARD16 height in pixels - 2 CARD16 width in millimeters - 2 CARD16 height in millimeters - - -Bibliography - -[RANDR] Gettys, Jim and Keith Packard, "The X Resize and Rotate - Extension - RandR", Proceedings of the 2001 USENIX Annual - Technical Conference, Boston, MA - -[RENDER] - Packard, Keith, "The X Rendering Extension", work in progress, - documents found in xc/specs/Render. |