From 3f1718e39c73475fb8384e61b6dc78f313d926f9 Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Wed, 30 Jun 2010 13:21:28 -0400 Subject: specs: convert protocol .ms specs from xorg-docs module to DocBook XML Signed-off-by: Gaetan Nadon --- specs/.gitignore | 6 + specs/Makefile.am | 64 +++ specs/dbe.xml | 1061 ++++++++++++++++++++++++++++++++++++ specs/security.xml | 1532 ++++++++++++++++++++++++++++++++++++++++++++++++++++ specs/sync.xml | 1062 ++++++++++++++++++++++++++++++++++++ 5 files changed, 3725 insertions(+) create mode 100644 specs/.gitignore create mode 100644 specs/Makefile.am create mode 100644 specs/dbe.xml create mode 100644 specs/security.xml create mode 100644 specs/sync.xml (limited to 'specs') diff --git a/specs/.gitignore b/specs/.gitignore new file mode 100644 index 0000000..12fe512 --- /dev/null +++ b/specs/.gitignore @@ -0,0 +1,6 @@ +# Add & Override for this directory and it's subdirectories +*.html +*.ps +*.pdf +*.txt +*.css diff --git a/specs/Makefile.am b/specs/Makefile.am new file mode 100644 index 0000000..9d94e85 --- /dev/null +++ b/specs/Makefile.am @@ -0,0 +1,64 @@ +# +# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. +# +# 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 (including the next +# paragraph) 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 AUTHORS OR COPYRIGHT HOLDERS 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. +# + +if ENABLE_SPECS +doc_sources = dbe.xml security.xml sync.xml +dist_doc_DATA = $(doc_sources) + +if HAVE_XMLTO +doc_DATA = $(doc_sources:.xml=.html) + +if HAVE_FOP +doc_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf) +endif + +if HAVE_XMLTO_TEXT +doc_DATA += $(doc_sources:.xml=.txt) +endif + +if HAVE_STYLESHEETS +XMLTO_FLAGS = -m $(XSL_STYLESHEET) + +doc_DATA += xorg.css +xorg.css: $(STYLESHEET_SRCDIR)/xorg.css + $(AM_V_GEN)cp -pf $(STYLESHEET_SRCDIR)/xorg.css $@ +endif + +CLEANFILES = $(doc_DATA) + +SUFFIXES = .xml .ps .pdf .txt .html + +.xml.txt: + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $< + +.xml.html: + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $< + +.xml.pdf: + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $< + +.xml.ps: + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $< + +endif HAVE_XMLTO +endif ENABLE_SPECS diff --git a/specs/dbe.xml b/specs/dbe.xml new file mode 100644 index 0000000..ce7a327 --- /dev/null +++ b/specs/dbe.xml @@ -0,0 +1,1061 @@ + + + + + + + + + + Double Buffer Extension Protocol + X Consortium Standard + X Version 11, Release 6.4 + + + IanElliott + + + + DavidWiggins + X Consortium + + Hewlett-Packard Company + + 1989 + X Consortium, Inc and Digital Equipment Corporation + + + 1992 + X Consortium, Inc and Intergraph Corporation + + + 1993 + X Consortium, Inc and Silicon Graphics, Inc + + + 1994 + X Consortium, Inc and Hewlett-Packard Company + + Version 1.0 + + + +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. In +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 windo'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 windo'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 windo'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 windo'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. + + + + + + +Requests +The DBE defines the following requests. + + +DBEGetVersion + +This request returns the major and minor version numbers of this extension. + + +DBEGetVersion + + + + + + + client-major-version + CARD8 + + + client-minor-version + CARD8 + + + => + + + + server-major-version + CARD8 + + + server-minor-version + CARD8 + + + + + + +The client-major-version and client-minor-version numbers indicate what +version of the protocol the client wants the server to implement. The +server-major-version and the server-minor-version numbers returned indicate +the protocol this extension actually supports. This might not equal the +version sent by the client. An implementation can (but need not) support +more than one version simultaneously. The server-major-version and +server-minor-version allow the creation of future revisions of the DBE +protocol that may be necessary. In general, the major version +would increment for incompatible changes, and the minor version would increment +for small, upward-compatible changes. Servers that support the protocol +defined in this document will return a server-major-version of one (1), and a +server-minor-version of zero (0). + + + +The DBE client must issue a DBEGetVersion request before any other double +buffering request in order to negotiate a compatible protocol version; +otherwise, the client will get undefined behavior (DBE may or may not work). + + + + + +DBEGetVisualInfo + +This request returns information about which visuals support double buffering. + + +DBEGetVisualInfo + + + + + + + + screen-specifiers + LISTofDRAWABLE + + + => + + + + visinfo + LISTofSCREENVISINFO + + + + +where: + + + + + + + + SCREENVISINFO + LISTofVISINFO + + + VISINFO + [ visual: VISUALID + + + + depth: CARD8 + + + + perflevel: CARD8 ] + + + + + +Errors: Drawable + + +All of the values passed in screen-specifiers must be valid DRAWABLEs (or a +Drawable error results). For each drawable in +screen-specifiers, the reply will contain a list of VISINFO structures for +visuals that support double-buffering on the screen on which the drawable +resides. The visual member specifies the VISUALID. The depth member specifies +the depth in bits for the visual. The perflevel is a performance hint. The +only operation defined on a perflevel is comparison to a perflevel of another +visual on the same screen. The visual having the higher perflevel is likely +to have better double-buffer graphics performance than the visual having the +lower perflevel. Nothing can be deduced from any of the following: the +magnitude of the difference of two perflevels, a perflevel value in isolation, +or comparing perflevels from different servers. + + + +If the list of screen-specifiers is empty, information for all screens is +returned, starting with screen zero. + + + + + +DBEAllocateBackBufferName + + +This request allocates a drawable ID used to refer to the back buffer of a +window. + + +DBEAllocateBackBufferName + + + + + + + + window + WINDOW + + + back-buffer-name + BACKBUFFER + + + swap-action-hint + SWAPACTION + + + + + + +Errors: Alloc, Value, IDChoice, Match, Window + + + +If the window is not already a double-buffered window, the window becomes +double-buffered, and the back-buffer-name is associated with the window. The +swap-action-hint tells the server which swap action is most likely to be +used with the window in subsequent DBESwapBuffers +requests. The swap-action-hint must have one of the values specified for type +SWAPACTION (or a Value error results). See the description of the +DBESwapBuffers request for a complete discussion of +swap actions and the SWAPACTION type. + + + +If the window already is a double-buffered window, nothing about the window +changes, except that an additional 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. + + + +The window passed into the request must be a valid WINDOW (or a Window error +results). The window passed into the request must be an InputOutput window (or +a Match error results). The visual of the window must be in the list returned +by DBEGetVisualInfo (or a Match error results). The +back-buffer-name must be in the range assigned to the client, and must not +already be in use (or an IDChoice error results). If the server cannot +allocate all resources associated with turning on double-buffering for the +window, an Alloc error results, the windo's double-buffer status (whether it +is already double-buffered or not) remains unchanged, and the +back-buffer-name is freed. + + + + +DBEDeallocateBackBufferName + +This request frees a drawable ID that was obtained by +DBEAllocateBackBufferName. + + +DBEDeallocateBackBufferName + + + + + + + + back-buffer-name + BACKBUFFER + + + + + +Errors: Buffer + + +The back-buffer-name passed in the request is freed and no longer associated +with the window. If this is the last back-buffer-name associated with the +window, then the back buffer is no longer accessible to clients, and all +double-buffering resources associated with the window may be freed. The +window's current front buffer remains the front buffer. + + + +The back-buffer-name must be a valid BACKBUFFER associated with a window (or +a Buffer error results). + + + + +DBESwapBuffers + +This request swaps the buffers for all windows listed, applying the +appropriate swap action for each window. + + +DBESwapBuffers + + + + + + + windows + LISTofSWAPINFO + + + + +where: + + + + + + SWAPINFO + [ window: WINDOW + + + + swap-action: SWAPACTION ] + + + SWAPACTION + { Undefined, Background, Untouched, Copied } + + + + + +Errors: Match, Window, Value + + +Each window passed into the request must be a valid WINDOW (or a +Window error results). Each window passed into the +request must be a double-buffered window (or a Match +error results). Each window passed into the request must only be listed +once (or a Match error results). Each swap-action in +the list must have one of the values specified for type SWAPACTION (or a +Value error results). If an error results, none of +the valid double-buffered windows will have their buffers swapped. + + + +The swap-action determines what will happen to the new back buffer of the +window it is paired with in the list in addition to making the old back +buffer become visible. The defined actions are as follows: + + + + + Undefined + +The contents of the new back buffer become undefined. This may be the +most efficient action since it allows the implementation to discard the +contents of the buffer if it needs to. + + + + Background + +The unobscured region of the new back buffer will be tiled with the window +background. The background action allows devices to use a fast clear +capability during a swap. + + + + Untouched + +The unobscured region of the new back buffer will be unmodified by the swap. + + + + Copied + +The unobscured region of the new back buffer will be the contents of the +old back buffer. + + + + + +If DBESwapBuffers is included in a "swap and clear" +type of idiom, it must immediately follow the +DBEBeginIdiom request. + + + + +DBEBeginIdiom + +This request informs the server that a complex swap will immediately follow +this request. + + +DBEBeginIdiom + + +As previously discussed, a complex swap action is a group/series of +requests that, taken together, may be combined into an atomic operation by +the implementation. The sole function of this request is to serve as a +"marker" that the server can use to aid in idiom processing. The server is +free to implement this request as a no-op. + + + + +DBEEndIdiom + + + +This request informs the server that a complex swap has concluded. + + +DBEEndIdiom + + +The sole function of this request is to serve as a "marker" that the server +can use to aid in idiom processing. The server is free to implement this +request as a no-op. + + + + + +DBEGetBackBufferAttributes + +This request returns information about a back buffer. + +DBEGetBackBufferAttributes + + + + + + + + back-buffer-name + BACKBUFFER + + + => + + + + attributes + BUFFER_ATTRIBUTES + + + + + +where: + +BUFFER_ATTRIBUTES: [ window: WINDOW ] + + +If back-buffer-name is a valid BACKBUFFER, the window field of the +attributes in the reply will be the window which has the back buffer that +back-buffer-name refers to. If back-buffer-name is not a valid BACKBUFFER, +the window field of the attributes in the reply will be None. + + + + + + +Encoding + +Please refer to the X11 Protocol Encoding document as this section uses +syntactic conventions and data types established there. + + +The name of this extension is "DOUBLE-BUFFER". + + +Type +The following new types are used by the extension. + + +BACKBUFFER: XID +SWAPACTION + +#x00 Undefined +#x01 Background +#x02 Untouched +#x03 Copied + + +SWAPINFO + +4 WINDOW window +1 SWAPACTION swap action +3 unused + + + +VISINFO +4 VISUALID visual +1 CARD8 depth +1 CARD8 perflevel +2 unused + +SCREENVISINFO +4 CARD32 n, number in list +8n LISTofVISINFO n VISINFOs + +BUFFER_ATTRIBUTES +4 WINDOW window + + + + +Error +Buffer + +1 0 error +1 error base + 0 code +2 CARD16 sequence number +4 CARD32 bad buffer +2 CARD16 minor-opcode +1 CARD8 major-opcode +21 unused + + + + +Request + + +DBEGetVersion +1 CARD8 major-opcode +1 0 minor-opcode +2 2 request length +1 CARD8 client-major-version +1 CARD8 client-minor-version +2 unused +=> +1 unused +2 CARD16 sequence number +4 0 reply length +1 CARD8 server-major-version +1 CARD8 server-minor-version +22 unused + + +DBEAllocateBackBufferName + +1 CARD8 major-opcode +1 1 minor-opcode +2 4 request length +4 WINDOW window +4 BACKBUFFER back buffer name +1 SWAPACTION swap action hint +3 unused + + +DBEDeallocateBackBufferName + +1 CARD8 major-opcode +1 2 minor-opcode +2 2 request length +4 BACKBUFFER back buffer name + + + +DBESwapBuffers + +1 CARD8 major-opcode +1 3 minor-opcode +2 2+2n request length +4 CARD32 n, number of window/swap action pairs in list +8n LISTofSWAPINFO window/swap action pairs + + + +DBEBeginIdiom + +1 CARD8 major-opcode +1 4 minor-opcode +2 1 request length + + +DBEEndIdiom + +1 CARD8 major-opcode +1 5 minor-opcode +2 1 request length + + +DBEGetVisualInfo + +1 CARD8 major-opcode +1 6 minor-opcode +2 2+n request length +4 CARD32 n, number of screen specifiers in list +4n LISTofDRAWABLE n screen specifiers +=> +1 1 Reply +1 unused +2 CARD16 sequence number +4 CARD32 reply length +4 CARD32 m, number of SCREENVISINFOs in list +20 unused +4j LISTofSCREENVISINFO m SCREENVISINFOs + + +DBEGetBackBufferAttributes + +1 CARD8 major-opcode +1 7 minor-opcode +2 2 request length +4 BACKBUFFER back-buffer-name +=> +1 unused +2 CARD16 sequence number +4 0 reply length +4 BUFFER_ATTRIBUTES attributes +20 unused + + + + + + +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/specs/security.xml b/specs/security.xml new file mode 100644 index 0000000..bcf0153 --- /dev/null +++ b/specs/security.xml @@ -0,0 +1,1532 @@ + + + + + + + + Security Extension Specification + X Consortium Standard + X Version 11, Release 6.8 + November 15, 1996 + + + DavidWiggins + + + X Consortium Standard + 1996X Consortium + Version 7.1 + X Consortium + X Version 11, Release 6.8 + + + +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. + + + + + + +Introduction + + +The Security extension contains new protocol needed to provide enhanced X +server security. The Security extension should not be exposed to untrusted +clients (defined below). + + + + + +Requests + + +SecurityQueryVersion + +This request returns the major and minor version numbers of this extension. + + +SecurityQueryVersion + + + + + + + client-major-version + + + CARD16 + + + + + client-minor-version + + + CARD16 + + + + + => + + + + + server-major-version + + + CARD16 + + + + + server-minor-version + + + CARD16 + + + + + + + + + + + + +The client-major-version and client-minor-version numbers indicate what +version of the protocol the client wants the server to implement. The +server-major-version and the server-minor-version numbers returned +indicate the protocol this extension actually supports. This might not +equal the version sent by the client. An implementation can (but need not) +support more than one version simultaneously. The server-major-version +and server-minor-version allow the creation of future revisions of the +Security protocol that may be necessary. In general, the major version +would increment for incompatible changes, and the minor version would +increment for small, upward-compatible changes. Servers that support +the protocol defined in this document will return a server-major-version +of one (1), and a server-minor-version of zero (0). + + + +Clients using the Security extension must issue a SecurityQueryVersion +request before any other Security request in order to negotiate a compatible +protocol version; otherwise, the client will get undefined behavior +(Security may or may not work). + + + + +SecurityGenerateAuthorization + + +This request causes the server to create and return a new authorization with +specific characteristics. Clients can subsequently connect using the new +authorization and will inherit some of the characteristics of the +authorization. + + + +SecurityGenerateAuthorization + + + + + + + authorization-protocol-name + + + STRING8 + + + + + authorization-protocol-data + + + STRING8 + + + + + value-mask + + + BITMASK + + + + + value-list + + + LISTofVALUE + + + + + => + + + + + + + authorization-id + + + AUTHID + + + + + authorization-data-return + + + STRING8 + + + + + + + + + + + + + + +Errors: AuthorizationProtocol, Value, Alloc + + + +authorization-protocol-name is the name of the authorization method for +which the server should generate a new authorization that subsequent +clients can use to connect to the server. If the authorization-protocol-name +is not one that the server supports, or if authorization-protocol-data +does not make sense for the given authorization-protocol-name, an +AuthorizationProtocol error results. + + + +authorization-protocol-data is authorization-method specific data that can +be used in some way to generate the authorization. + + + +In this version of the extension, the only authorization method +required to be supported is "MIT-MAGIC-COOKIE-1" with any amount +of authorization-protocol-data (including none). The server may use the +authorization-protocol-data as an additional source of randomness used +to generate the authorization. Other authorization methods can supply +their own interpretation of authorization-protocol-data. + + + +The value-mask and value-list specify attributes of the authorization +that are to be explicitly initialized. The possible values are: + + + + + + + + + + + + + Attribute + + + Type + + + Default + + + + + timeout + + + CARD32 + + + 60 + + + + + group + + + XID or None + + + None + + + + + trust-level + + + {SecurityClientTrusted, + + + + + + + + SecurityClientUntrusted} + + + SecurityClientUntrusted + + + + + event-mask + + + SecurityAuthorizationRevoked, + + + + + + + + or None + + + None + + + + + + + + + + + + + + + + + +timeout is the timeout period in seconds for this authorization. A +timeout value of zero means this authorization will never expire. For +non-zero timeout values, when timeout seconds have elapsed since the +last time that the authorization entered the state of having no +connections authorized by it, and if no new connections used the +authorization during that time, the authorization is automatically purged. +(Note that when an authorization is created, it enters the state of having no +connections authorized by it.) Subsequent connection attempts using that +authorization will fail. This is to facilitate "fire and forget" launching of +applications. + + + +group is an application group ID as defined by the Application Group +extension, or None. Any other values will cause a Value error. When a +group is destroyed, all authorizations specifying that group are revoked +as described under the SecurityRevokeAuthorization request. The Application +Group extension attaches additional semantics to the group. + + + +trust-level tells whether clients using the authorization are trusted or +untrusted. If trust-level is not one of the constants SecurityClientTrusted +or SecurityClientUntrusted, a Value error results. + + + +event-mask defines which events the client is interested in for this +authorization. When the authorization expires or is revoked if event-mask +contains SecurityAuthorizationRevoked a SecurityAuthorizationRevoked event +is reported to the client. + + + +The SecurityAuthorizationRevoked event contains the following field: + + + + + + + + + + + + + Field + + + Type + + + + + authorization-id + + + AUTHID + + + + + + + + + + + + + + + + + +where authorization-id is the identification of the authorization that was +revoked. + + +If an invalid value-mask is specified, a Value error occurs. + + + +The returned authorization-id is a non-zero value that uniquely identifies +this authorization for use in other requests. The value space for type +AUTHID is not required to be disjoint from values spaces of other core +X types, e.g. resource ids, atoms, visual ids, and keysyms. Thus, a given +numeric value might be both a valid AUTHID and a valid atom, for example. + + + +authorization-data-return is the data that a client should use in some +authorization-method-specific way to make a connection with this +authorization. For "MIT-MAGIC-COOKIE-1," authorization-data-return should +be sent as the authorization-protocol-data in the connection setup message. +It is not required that other authorization methods use +authorization-data-return this way. + + + + + +SecurityRevokeAuthorization + + +This request deletes an authorization created by SecurityGenerateAuthorization. + + + +SecurityRevokeAuthorization + + + + + + + + authorization-id + + + AUTHID + + + + + + + + + + + + +Errors: Authorization + + + +If authorization-id does not name a valid authorization, an Authorization +error occurs. Otherwise, this request kills all clients currently connected +using the authorization specified by authorization-id. The authorization is +deleted from the server's database, so future attempts by clients to connect +with this authorization will fail. + + + + + + +Changes to Core Requests + + +A server supporting this extension modifies the handling of some core +requests in the following ways. + + +Resource ID Usage + + +If an untrusted client makes a request that specifies a resource ID that is +not owned by another untrusted client, a protocol error is sent to the +requesting client indicating that the specified resource does not exist. +The following exceptions apply. An untrusted client can: + + + + + +use the QueryTree, GetGeometry, and TranslateCoordinates requests +without restriction. + + + + +use colormap IDs that are returned in the default-colormap field of its +connection setup information in any colormap requests. + + + + specify a root window as: + + + +the drawable field of CreatePixmap, CreateGC, and QueryBestSize. + + + + the parent field of CreateWindow. + + + +the window field of CreateColormap, ListProperties, and GetWindowAttributes. + + + + the grab-window or confine-to fields of GrabPointer. + + + + the grab-window field of UngrabButton. + + + +the destination of SendEvent, but only if all of the following are true. +(These conditions cover all the events that the ICCCM specifies with +a root window destination.) + + + + The propogate field of SendEvent is False. + + + +The event-mask field of SendEvent is ColormapChange, +StructureNotify, or the logical OR of SubstructureRedirect with +SubstructureNotify. + + + + +The event type being sent is UnmapNotify, ConfigureRequest, or +ClientMessage. + + + + + + +the window field of ChangeWindowAttributes, but only if the value-mask +contains only event-mask and the corresponding value is StructureNotify, +PropertyChange, or the logical OR of both. + + + + + + + + +ISSUE: are root window exceptions needed for these? WarpPointer, ReparentWindow +(parent), CirculateWindow, QueryPointer (emacs does this), GetMotionEvents. + + + + + +Extension Security + + +This extension introduces the notion of secure and insecure extensions. A +secure extension is believed to be safe to use by untrusted clients; that +is, there are no significant security concerns known that an untrusted +client could use to destroy, modify, or steal data of trusted clients. This +belief may be founded on a careful analysis of the extension protocol, +its implementation, and measures taken to "harden" the extension to close +security weaknesses. All extensions not considered secure are called +insecure. The implementation details of how an extension is identified as +secure or insecure are beyond the scope of this specification. + + + +ListExtensions will only return names of secure +extensions to untrusted clients. + + + +If an untrusted client uses QueryExtension on an +insecure extension that the server supports, the reply will have the +present field set to False and the major-opcode field set to zero to +indicate that the extension is not supported. + + + +If an untrusted client successfully guesses the major opcode of an +insecure extension, attempts by it to execute requests with that major +opcode will fail with a Request error. + + + + + +Keyboard Security + + + +The protocol interpretation changes in this section are intended to prevent +untrusted applications from stealing keyboard input that was meant for +trusted clients and to prevent them from interfering with the use of the +keyboard. + + + +The behavior of some keyboard-related requests and events is modified when +the client is untrusted depending on certain server state at the time of +request execution or event generation. Specifically, if a hypothetical +keyboard event were generated given the current input focus, pointer +position, keyboard grab state, and window event selections, and if that +keyboard event would not be delivered to any untrusted client, the +following changes apply: + + + + + +The bit vector representing the up/down state of the keys returned by +QueryKeymap and +KeymapNotify is all zeroes. + + + + GrabKeyboard returns a status of AlreadyGrabbed. + + + +SetInputFocus does nothing. Note that this means the +Globally Active +Input and WM_TAKE_FOCUS mechanisms specified in the ICCCM will +not work with untrusted clients. + + + + +Passive grabs established by GrabKey that would otherwise have activated +do not activate. + + + + + +If an untrusted client attempts to use any of the following requests, the +only effect is that the client receives an Access error: SetModifierMapping, +ChangeKeyboardMapping, ChangeKeyboardControl. + + + +If an InputOnly window owned by an untrusted client has a parent owned by a +trusted client, all attempts to map the window will be ignored. This includes +mapping attempts resulting from MapWindow, MapSubwindows, ReparentWindow, +and save-set processing. + + +However, if the parent of an InputOnly window owned by an untrusted client +is the root window, attempts to map that window will be performed as +expected. This is in line with the root window exceptions above. + + + + +Image Security + + +It should be impossible for an untrusted client to retrieve the image +contents of a trusted window unless a trusted client takes action to allow +this. We introduce the following defenses in support of this requirement. + + + +The restrictions on resource ID usage listed above prevent untrusted clients +from using GetImage directly on windows not belonging to trusted clients. + + + +If an untrusted client tries to set the background-pixmap attribute of an +untrusted window to None, the server will instead use a server-dependent +background which must be different than None. + + + +The X protocol description of GetImage states that the +returned contents of regions of a window obscured by noninferior windows are +undefined if the window has no backing store. Some implementations return the +contents of the obscuring windows in these regions. When an untrusted client +uses GetImage, this behavior is forbidden; the server must +fill the obscured regions in the returned image with a server-dependent pattern. + + + +If an untrusted window has trusted inferiors, their contents are vulnerable +to theft via GetImage on the untrusted parent, as well +as being vulnerable to destruction via drawing with subwindow-mode +IncludeInferiors on the untrusted parent. An untrusted window having trusted +inferiors can only occur at the request of a trusted client. It is expected +to be an unusual configuration. + + + + + + +Property Security + + +Unlike the other security provisions described in this document, security for +property access is not amenable to a fixed policy because properties are +used for inter-client communication in diverse ways and may contain data of +varying degrees of sensitivity. Therefore, we only list the possible +restrictions the server may decide to impose on use of properties on trusted +windows by untrusted clients. How the server chooses which restrictions from +this list to apply to a particular property access is implementation dependent + +In the X Consortium server implementation, property access is controlled by +a configuration file; see the -sp option in the Xserver(1) manual page. + . + + +The X Protocol property requests are +ChangeProperty, +GetProperty, +DeleteProperty, +RotateProperties, and +ListProperties. For these requests, the server can +allow the request to execute normally (as if it had been issued by a +trusted client), ignore the request completely (as if it were a NoOperation), +or ignore the request except to send an Atom error to the client. Ignoring +a ListProperties request means replying that +the window has no properties. ListProperties may also +reply with a subset of the existing properties if the server is doing +property hiding; see below. An ignored GetProperty +request may reply that the property does not exist, or that it exists but +contains no data. + + + +The server may decide to hide certain properties on certain windows from +untrusted clients + +The X Consortium server implementation does not currently provide a way to +hide properties. + . +If a property is to be hidden, it must be done consistently to avoid +confusing clients. This means that for untrusted clients: + + + + + +That property should not be returned by +ListProperties. + + + + +PropertyNotify events should not be sent for that +property. + + + +GetProperty on that property should reply that the +property does not exist (the return type is None, the format and +bytes-after are zero, and the value is empty). + + + + + +For a property that the server is protecting but not hiding, consistency +must also be maintained: + + + + + +That property should be returned by ListProperties. + + + + +PropertyNotify events should be sent for that property. + + + + +GetProperty on that property should reply that the +property exists (if it really does) but the value is empty +(return type and format are their real values, and the "length of value" +field in the reply is zero). + + + + + + + +Miscellaneous Security + + +If an untrusted client attempts to use +ChangeHosts, +ListHosts, or +SetAccessControl, +the only effect is that the client receives an Access error. + + + +If an untrusted client attempts to use ConvertSelection +on a selection with a trusted selection owner window, the server generates +a SelectionNotify event to the requestor with property None. + + + + + +New Authorization Method + + +This extension includes a new authorization method named +"XC-QUERY-SECURITY-1". Its purpose is to allow an external agent such as +the X firewall proxy to probe an X server to determine whether that server +meets certain security criteria without requiring the agent to have its +own authorization for that server. The agent may use the returned information +to make a decision. For example, the X firewall proxy may choose not to +forward client connections to servers that do not meet the criteria. + + + +To use this authorization method, the client (or proxy) sends +"XC-QUERY-SECURITY-1" as the authorization-protocol-name in the initial +connection setup message. The authorization-protocol-data may be empty or +may contain additional security criteria desribed below. If the success +field of the server's reply is Authenticate, the server supports the +security extension, and the server meets all specified additional security +criteria. In this case, the client should resend the initial connection +setup message substituting the authorization protocol name and data +that should be used to authorize the connection. If the success field of the +server's reply is anything other than Authenticate, either the server does not +support the security extension, does not meet (or cannot determine if it +meets) all of the additional security criteria, or chooses for internal reasons +not to answer with Authenticate. In this case, the client should close the +connection. + + + +If the authorization-protocol-data sent with "XC-QUERY-SECURITY-1" is not +empty, it specifies additional security criteria for the server to check, as +follows. + + + +authorization-protocol-data + + + + + + + + policy-mask + + + BITMASK + + + + + policies + + + LISTofSECURITYPOLICY + + + + + + + + + + + + +The policy-mask field is any logical-OR combination of the constants +Extensions and SitePolicies. For each bit set in policy-mask, there is a +SECURITYPOLICY element in policies. The nth element in policies corresponds +to the nth 1-bit in policy-mask, counting upward from bit 0. + + +SECURITYPOLICY + + + + + + + policy-type + + + {Disallow, Permit} + + + + + names + + + LISTofSTR + + + + + + + + + + + + +For a SECURITYPOLICY corresponding to policy-mask Extensions, if +policy-type is Disallow the server is required to consider as insecure +all extensions given in names. No policy is specified for extensions +not listed in names. If policy-type is Permit the server may consider +only those extensions given in names to be secure; all other extensions +must be treated as insecure. If these constraints are not met, the server +should not return Authenticate in the success field of the reply. +Servers can but need not dynamically configure themselves in response +to an Extensions SECURITYPOLICY; a conforming server might simply compare +the policy with a compiled-in table of extensions and their security status. + + + +For a SECURITYPOLICY corresponding to policy-mask SitePolicies, policy-type +Disallow means the server must not have been configured with any of the site +policies given in names. Policy-type Permit means the server must have +been configured with at least one of the site policies given in names. If +these constraints are not met, the server should not return Authenticate in +the success field of the reply. + + + +SitePolicies provide a way to express new forms of security-relevant +information that could not be anticipated at the time of this writing. +For example, suppose the server is found to have a critical security defect. +When a fix is developed, a site policy string could be associated with the +fix. Servers with the fix would advertise that site policy, and the X +firewall proxy would specify that site policy in a SECURITYPOLICY with +policy-type Permit. + + + + + +Encoding + + +Please refer to the X11 Protocol Encoding document as this section +uses syntactic conventions and data types established there. + + + +The name of this extension is "SECURITY". + + + +Types + +AUTHID: CARD32 + + + + +Request Encoding + + +SecurityQueryVersion + + +1 CARD8 major-opcode +1 0 minor-opcode +2 2 request length +2 CARD16 client-major-version +2 CARD16 client-minor-version +=> +1 1 Reply +1 unused +2 CARD16 sequence number +4 0 reply length +2 CARD16 server-major-version +2 CARD16 server-minor-version +20 unused + + + +SecurityRevokeAuthorization + + + +1 CARD8 major-opcode +1 2 minor-opcode +2 2 request length +4 AUTHID authorization-id + + + +SecurityGenerateAuthorization + + + +1 CARD8 major-opcode +1 1 minor-opcode +2 3 + (m+n+3)/4 + s request length +2 CARD16 m, number of bytes in authorization protocol name +2 CARD16 n, number of bytes in authorization data +m STRING8 authorization protocol name +n STRING8 authorization protocol data +p unused, p=pad(m+n) +4 BITMASK value-mask (has s bits set to 1) + #x00000001 timeout + #x00000002 trust-level + #x00000004 group + #x00000008 event-mask +4s LISTofVALUE value-list + + + +VALUES + + +4 CARD32 timeout +4 trust-level + 0 SecurityClientTrusted + 1 SecurityClientUntrusted +4 XID group +0 None +4 CARD32 event-mask + #x00000001 SecurityAuthorizationRevoked +=> +1 1 Reply +1 unused +2 CARD16 sequence number +4 (q+3)/4 reply length +4 AUTHID authorization-id +2 CARD16 data-length +18 unused +q STRING8 authorization-data-return +r unused, r=pad(q) + + + + + +Event Encoding + +SecurityAuthorizationRevoked + + + +1 0+extension event base code +1 unused +2 CARD16 sequence number +4 AUTHID authorization id +24 unused + + + + + +Authorization Method Encoding + + +For authorization-protocol-name "XC-QUERY-SECURITY-1", the +authorization-protocol-data is interpreted as follows: + + + +authorization-protocol-data + + +1 BITMASK policy-mask + #x00000001 Extensions + #x00000002 SitePolicies +m LISTofSECURITYPOLICY policies + + + +SECURITYPOLICY + + + +1 policy-type + 0 Permit + 1 Disallow +1 CARD8 number of STRs in names +n LISTofSTR names + + + +LISTofSTR has the same encoding as in the X protocol: each STR is a single +byte length, followed by that many characters, and there is no padding or +termination between STRs. + + + + + +C Language Binding + + +The header for this extension is <X11/extensions/security.h>. All +identifier names provided by this header begin with XSecurity. + + + +All functions that have return type Status will return nonzero for +success and zero for failure. + + + + + Status XSecurityQueryExtension + Display *dpy + int *major_version_return + int *minor_version_return + + + + +XSecurityQueryExtension sets major_version_return and +minor_version_return to the major and minor Security protocol version +supported by the server. If the Security library is compatible with the +version returned by the server, it returns nonzero. If dpy does not support +the Security 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 XSecurity functions may be called before this +function. If a client violates this rule, the effects of all subsequent +XSecurity calls that it makes are undefined. + + + + + Xauth *XSecurityAllocXauth + void + + + +In order to provide for future evolution, Xauth structures are used to +pass and return authorization data, and the library provides ways to +allocate and deallocate them. + + + +XSecurityAllocXauth must be used to allocate the +Xauth structure that is passed to +XSecurityGenerateAuthorization. + + + +For the purposes of the Security extension, the Xauth structure has +the following fields: + + + + + + + + + + + + + Type + + + Field name + + + Description + + + + + unsigned short + + + name_length + + + number of bytes in name + + + + + char * + + + name + + + authorization protocol name + + + + + unsigned short + + + data_length + + + number of bytes in data + + + + + char * + + + data + + + authorization protocol data + + + + + + + + + + + + + + + + +The Xauth structure returned by this function is initialized as follows: +name_length and data_length are zero, and name and data are NULL. + + + + + void XSecurityFreeXauth + Xauth *auth + + + + +XSecurityFreeXauth must be used to free Xauth +structures allocated by +XSecurityAllocXauth or returned by +XSecurityGenerateAuthorization. It is the +caller's responsibility to fill in the name and data fields of Xauth structures +allocated with XSecurityAllocXauth, so this function +will not attempt to free them. In contrast, all storage associated with +Xauth structures returned from +XSecurityGenerateAuthorization will be freed by this +function, including the name and data fields. + + + + + + Bool XSecurityRevokeAuthorization + Display *dpy + XSecurityAuthorization auth_id + + + + +XSecurityRevokeAuthorization deletes the authorization +specified by auth_id, which must be a value returned in the auth_id_return +parameter of XSecurityGenerateAuthorization. All +clients that connected with that authorization are be killed. Subsequently, +clients that attempt to connect using that authorization will be refused. + + + + + + Xauth *XSecurityGenerateAuthorization + Display *dpy + Xauth *auth_in + unsigned long valuemask + XSecurityAutorizationAttributes *attributes + XSecurityAutorization *auth_id_return + + + + +XSecurityGenerateAuthorization creates a new +authorization with the specified attributes. The auth_in argument must be +allocated by XSecurityAllocXauth. The +name and name_length fields of auth_in should be initialized to the +authorization protocol name and its length in characters respectively. +If there is authorization data, the data and data_length fields of +auth_in should be initialized to the data and its length in characters +respectivley. The library does not assume that name and data are +null-terminated strings. The auth_in argument must be freed with +XSecurityFreeXauth. + + + +The XSecurityAuthorizationAttributes structure has the following fields: + + + + + + + + + + + + + Type + + + Field name + + + Mask + + + + + unsigned int + + + trust_level + + + XSecurityTrustLevel + + + + + unsigned int + + + timeout + + + XSecurityTimeout + + + + + XID + + + group + + + XSecurityGroup + + + + + long + + + event_mask + + + XSecurityEventMask + + + + + + + + + + + + + + + + + +These correspond to the trust-level, timeout, group, and event-mask +described in the SecurityGenerateAuthorization protocol request. The +caller can fill in values for any subset of these attributes. The valuemask +argument must be the bitwise OR of the symbols listed in the Mask column +for all supplied attributes. The event_mask attribute can be None, +XSecurityAuthorizationRevokedMask, or XSecurityAllEventMasks. In this +revision of the protocol specification XSecurityAllEventMasks is equivalent +to XSecurityAuthorizationRevokedMask. If the caller does not need to +specify any attributes, the attributes argument can be NULL, and the +valuemask argument must be zero. + + +If the function fails, NULL is returned and auth_id_return is filled in +with zero. Otherwise, a pointer to an Xauth structure is returned. The name +and name_length fields of the returned Xauth structure will be copies of the +name that was passed in, and the data and data_length fields will be set to +the authorization data returned by the server. The caller should not assume +that name and data are null-terminated strings. If no authorization data was +returned by the server, the data and data_length fields will be set to NULL +and zero repectively. The returned Xauth structure must be freed with +XSecurityFreeXauth; the caller should not use any other +means free the structure or any of its components. The auth_id_return +argument will be filled in with the non-zero authorization id of the created +authorization. + + + +The XSecurityAuthorizationRevokedEvent structure has the following fields: + + + + + + + + + + + + + Type + + + Field name + + + Description + + + + + + int + + + type + + + event base + XSecurityAuthorizationRevoked + + + + + unsigned long + + + serial + + + # of last request processed by server + + + + + Bool + + + send_event + + + true if this came from SendEvent + + + + + Display* + + + display + + + Display the event was read from + + + + + XSecurityAuthorization + + + auth_id + + + revoked authorization id + + + + + + + + + + + + + + + + + diff --git a/specs/sync.xml b/specs/sync.xml new file mode 100644 index 0000000..a8064a9 --- /dev/null +++ b/specs/sync.xml @@ -0,0 +1,1062 @@ + + + + + + + + + + X Synchronization Extention Protocol + X Consortium Standard + X Version 11, Release 6.6.84 + + + TimGlauert + Olivetti Research/MultiWorks + + + Dave + Carver + Digital EquipmentCorporation, MIT/Project Athena + + + Jim + Gettys + Digital EquipmentCorporation, Cambridge Research Laboratory + + + David + Wiggins + X Consortium, Inc. + + + X Consortium Standard + + + 1991 + +Olivetti Research Limited, Cambridge England and +Digital Equipment Corporation, Maynard, Massachusetts + + + 1991X Consortium + + Version 3.0 + X Consortium + X Version 11, Release 6.8 + + + +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. + + + +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. + + + + +Types + +Please refer to the X11 Protocol specification as this document uses +syntactic conventions established there and references types defined there. + + +The following new types are used by the extension. + + +INT64: 64-bit signed integer +COUNTER: XID +VALUETYPE: {Absolute,Relative}; +TESTTYPE: {PositiveTransition,NegativeTransition, + PositiveComparison,NegativeComparison} +TRIGGER: [ + counter:COUNTER, + value-type:VALUETYPE, + wait-value:INT64, + test-type:TESTTYPE + ] +WAITCONDITION: [ + trigger:TRIGGER, + event-threshold:INT64 + ] +SYSTEMCOUNTER: [ + name:STRING8, + counter:COUNTER, + resolution:INT64 + ] +ALARM: XID +ALARMSTATE: {Active,Inactive,Destroyed} + + + +The COUNTER type defines the client-side handle on a server +Counter. The value of a counter is an INT64. + + + +The TRIGGER type defines a test on a counter that is either TRUE or FALSE. The +value of the test is determined by the combination of a test value, the value +of the counter, and the specified test-type. + + + +The test value for a trigger is calculated using the value-type and +wait-value fields when the trigger is initialized. If the value-type field +is not one of the named VALUETYPE constants, the request that initialized the +trigger will return a Value error. If the value-type +field is Absolute, the test value is given by the +wait-value field. If the value-type field is Relative, +the test value is obtained by adding the wait-value field to the value of the +counter. If the resulting test value would lie outside the range for an +INT64, the request that initialized the trigger will return a +Value error. If counter is None +and the value-type is Relative, the request that +initialized the trigger will return a Match error. If +counter is not None and does not name a valid counter, a Counter error is +generated. + + + +If the test-type is PositiveTransition, the trigger is +initialized to FALSE, and it will become TRUE when the counter changes from +a value less than the test value to a value greater than or equal to the +test value. If the test-type is NegativeTransition, +the trigger is initialize to FALSE, and it will become TRUE when the counter +changes from a value greater than the test value to a value less than or +equal to the test value. If the test-type is +PositiveComparison, the trigger is TRUE if the +counter is greater than or equal to the test value and FALSE otherwise. If the +test-type is NegativeComparison, the trigger is TRUE +if the counter is less than or equal to the test value and FALSE otherwise. +If the test-type is not one of the named TESTTYPE constants, the request that +initialized the trigger will return a Value error. A trigger with a counter +value of None and a valid test-type is always TRUE. + + + +The WAITCONDITION type is simply a trigger with an associated event-threshold. +The event threshold is used by the Await request to +decide whether or not to generate an event to the client after the trigger has +become TRUE. By setting the event-threshold to an appropriate value, it is +possible to detect the situation where an Await request +was processed after the TRIGGER became TRUE, which usually indicates that +the server is not processing requests as fast as the client expects. + + + +The SYSTEMCOUNTER type provides the client with information about a +SystemCounter. The name field is the textual name of +the counter that identifies the counter to the client. The counter field +is the client-side handle that should be used in requests that require a +counter. The resolution field gives the approximate step size of the system +counter. This is a hint to the client +that the extension may not be able to resolve two wait conditions with test +values that differ by less than this step size. A microsecond clock, for +example, may advance in steps of 64 microseconds, so a counter based on this +clock would have a resolution of 64. + + + +The only system counter that is guaranteed to be present is called SERVERTIME, +which counts milliseconds from some arbitrary starting point. The least +significant 32 bits of this counter track the value of Time used by the +server in Events and Requests. Other system counters may be provided by +different implementations of the extension. The X Consortium will maintain a +registry of system counter names to avoid collisions in the name space. + + + +An ALARM is the client-side handle on an Alarm resource. + + + + +Errors + + + + Counter + + +This error is generated if the value for a COUNTER argument in a request +does not name a defined COUNTER. + + + + + Alarm + + +This error is generated if the value for an ALARM argument in a request +does not name a defined ALARM. + + + + + + + + +Requests + + + + Initialize + + +version-major,version-minor: CARD8 +=> +version-major,version-minor: CARD8 + + + +This request must be executed before any other requests for this extension. If a +client violates this rule, the results of all SYNC requests that it issues are +undefined. The request takes the version number of the extension that the +client wishes to use and returns the actual version number being implemented +by the extension for this client. The extension may return different +version numbers to a client depending of the version number supplied by +that client. This request should be executed only once for each client +connection. + + +Given two different versions of the SYNC protocol, v1 and v2, v1 is +compatible with v2 if and only if v1.version_major = v2.version_major +and v1.version_minor <= v2.version_minor. Compatible means that the +functionality is fully supported in an identical fashion in the two versions. + + +This document describes major version 3, minor version 0 of the SYNC protocol. + + + + + ListSystemCounters + + +=> +system-counters: LISTofSYSTEMCOUNTER +Errors: Alloc + + +This request returns a list of all the system counters that are available at +the time the request is executed, which includes the system counters +that are maintained by other extensions. The list returned by this +request may change as counters are created and destroyed by other extensions. + + + + + CreateCounter + + +id: COUNTER +initial-value: INT64 +Errors: IDChoice,Alloc + + +This request creates a counter and assigns the specified id to it. The counter +value is initialized to the specified initial-value and there are no clients +waiting on the counter. + + + + + DestroyCounter + + +counter: COUNTER +Errors: Counter,Access + + +This request destroys the given counter and sets the counter fields for all +triggers that specify this counter to None. All clients +waiting on the counter are released and a CounterNotify +event with the destroyed field set to TRUE is sent to each waiting client, +regardless of the event-threshold. All alarms specifying the counter become +Inactive and an AlarmNotify +event with a state field of Inactive is generated. A +counter is destroyed automatically when the connection to the creating client +is closed down if the close-down mode is Destroy. An +Access error is generated if counter is a system +counter. A Counter error is generated if counter does +not name a valid counter. + + + + + QueryCounter + + +counter: COUNTER +=> +value: INT64 +Errors: Counter + + +This request returns the current value of the given counter or a generates +Counter error if counter does not name a valid counter. + + + + + Await + + +wait-list: LISTofWAITCONDITION +Errors: Counter,Alloc,Value + + +When this request is executed, the triggers in the wait-list are initialized +using the wait-value and value-type fields, as described in the definition of +TRIGGER above. The processing of further requests for the client is blocked +until one or more of the triggers becomes TRUE. This may happen immediately, +as a result of the initialization, or at some later time, as a result of +a subsequent SetCounter, +ChangeCounter or +DestroyCounter request. + + +A Value error is generated if wait-list is empty. + + +When the client becomes unblocked, each trigger is checked to determine +whether a CounterNotify event should be generated. +The difference between the counter and the test value is calculated by +subtracting the test value from the value of the counter. If the test-type +is PositiveTransition or +PositiveComparison, a +CounterNotify event is generated if the difference is +at least event-threshold. If the test-type is +NegativeTransition or +NegativeComparison, a +CounterNotify event is generated if the difference +is at most event-threshold. If the difference lies outside the range for an +INT64, an event is not generated. + + +This threshold check is made for each trigger in the list and a +CounterNotify event is generated for every trigger for +which the check succeeds. The check for +CounterNotify events is performed even if one of the +triggers is TRUE when the request is first executed. Note that a +CounterNotify event may be generated for a trigger +that is FALSE if there are multiple triggers in the request. A +CounterNotify event with the destroyed flag set to +TRUE is always generated if the counter for one of the triggers is +destroyed. + + + + + ChangeCounter + + +counter: COUNTER +amount: INT64 +Errors: Counter,Access,Value + + +This request changes the given counter by adding amount to the current +counter value. If the change to this counter satisfies a trigger for which a client +is waiting, that client is unblocked and one or more +CounterNotify events may be generated. If the change to +the counter satisfies the trigger for an alarm, an +AlarmNotify event is generated and the +alarm is updated. An Access error is generated if +counter is a system counter. A Counter error is +generated if counter does not name a valid counter. If the resulting value +for the counter would be outside the range for an INT64, a +Value error is generated and the counter is not changed. + + +It should be noted that all the clients whose triggers are satisfied by this +change are unblocked, so this request cannot be used to implement mutual +exclusion. + + + + + SetCounter + + +counter: COUNTER +value: INT64 +Errors: Counter,Access + + +This request sets the value of the given counter to value. The effect is +equivalent to executing the appropriate ChangeCounter request to change +the counter value to value. An Access error is generated if counter names a +system counter. A Counter error is generated if counter does not name a valid +counter. + + + + + CreateAlarm + + +id: ALARM +values-mask: CARD32 +values-list: LISTofVALUE +left">Errors: IDChoice,Counter,Match,Value,Alloc + + +This request creates an alarm and assigns the identifier id to it. The +values-mask and values-list specify the attributes that are to be explicitly +initialized. The attributes for an Alarm and their defaults are: + + + + + + + + + + Attribute + Type + Default + + + + + + + + + trigger + TRIGGER + counter + None + + + + + value-type + Absolute + + + + + value + 0 + + + + + test-type + PositiveComparison + + + delta + INT64 + 1 + + + events + BOOL + TRUE + + + + + +The trigger is initialized as described in the definition of TRIGGER, with an +error being generated if necessary. + + +If the counter is None, the state of the alarm is set +to Inactive, else it is set to Active. + + +Whenever the trigger becomes TRUE, either as a result of this request or as the +result of a SetCounter, +ChangeCounter, DestroyCounter, or +ChangeAlarm request, an +AlarmNotify event is generated and the alarm is +updated. The alarm is updated by repeatedly adding delta to the value of the +trigger and reinitializing it until it becomes FALSE. If this update would +cause value to fall outside the range for an INT64, or if the counter +value is None, or if the delta is 0 and test-type +is PositiveComparison or +NegativeComparison, no change is made to value and +the alarm state is changed to Inactive before the +event is generated. No further events are generated by an +Inactive alarm until a ChangeAlarm +or DestroyAlarm request is executed. + + +If the test-type is PositiveComparison or +PositiveTransition and delta is less than zero, or +if the test-type is NegativeComparison or +NegativeTransition and delta is greater than zero, +a Match error is generated. + + +The events value enables or disables delivery of +AlarmNotify events +to the requesting client. The alarm keeps a separate event flag for +each client so that other clients may select to receive events from this +alarm. + + +An AlarmNotify event is always generated at some time +after the execution of a CreateAlarm request. This +will happen immediately if the trigger is TRUE, or it will happen later +when the trigger becomes TRUE or the Alarm is destroyed. + + + + + ChangeAlarm + + +id: ALARM +values-mask: CARD32 +values-list: LISTofVALUE +Errors: Alarm,Counter,Value,Match + + +This request changes the parameters of an Alarm. All of the parameters +specified for the CreateAlarm request may be changed +using this request. The trigger is reinitialized and an +AlarmNotify event is generated if appropriate, as +explained in the description of the CreateAlarm request. + + +Changes to the events flag affect the event delivery to the requesting +client only and may be used by a client to select or deselect event delivery +from an alarm created by another client. + + +The order in which attributes are verified and altered is server-dependent. +If an error is generated, a subset of the attributes may have been altered. + + + + + DestroyAlarm + + +alarm: ALARM +Errors: Alarm + + +This request destroys an alarm. An alarm is automatically destroyed when the +creating client is closed down if the close-down mode is +Destroy. When an alarm is destroyed, an +AlarmNotify event is generated with a state value of +Destroyed. + + + + + QueryAlarm + + +alarm: ALARM +=> +trigger: TRIGGER +delta: INT64 +events: ALARMEVENTMASK +state: ALARMSTATE +Errors: Alarm + + This request retrieves the current parameters for an Alarm. + + + + SetPriority + + +client-resource: XID +priority: INT32 +Errors: Match + + +This request changes the scheduling priority of the client that created +client-resource. If client-resource is None, then +the priority for the client making the request is changed. A +Match error is generated if client-resource is not +None and does not name an existing resource in the +server. For any two priority values, A and B, A is higher priority if +and only if A is greater than B. + + +The priority of a client is set to 0 when the initial client connection is + made. + + +The effect of different client priorities depends on the particular +implementation of the extension, and in some cases it may have no effect at +all. However, the intention is that higher priority clients will have +their requests executed before those of lower priority clients. + + +For most animation applications, it is desirable that animation clients be +given priority over nonrealtime clients. This improves the smoothness of the +animation on a loaded server. Because a server is free to implement very strict +priorities, processing requests for the highest priority client to the +exclusion of all others, it is important that a client that may potentially +monopolize the whole server, such as an animation that produces continuous +output as fast as it can with no rate control, is run at low rather than high +priority. + + + + + GetPriority + + +client-resource: XID +=> +priority: INT32 +Errors: Match + + +This request returns the scheduling priority of the client that created +client-resource. If client-resource is None, then the +priority for the client making the request is returned. A +Match error is generated if client-resource is +not None and does not name an existing resource in the +server. + + + + + + + +Events + + + + CounterNotify + + +counter: COUNTER +wait-value: INT64 +counter-value: INT64 +time: TIME +count: CARD16 +destroyed: BOOL + + +CounterNotify events may be generated when a client +becomes unblocked after an Await request has been +processed. The wait-value is the value being waited for, and counter-value +is the actual value of the counter at the time the event was generated. +The destroyed flag is TRUE if this request was generated as the result of +the destruction of the counter and FALSE otherwise. The time is the server +time at which the event was generated. + + +When a client is unblocked, all the CounterNotify +events for the Await request are generated contiguously. If count is 0, +there are no more events to follow for this request. If count is n, +there are at least n more events to follow. + + + + + AlarmNotify + + +alarm: ALARM +counter-value: INT64 +alarm-value: INT64 +state: ALARMSTATE +time: TIME + + +An AlarmNotify event is generated when an alarm is +triggered. alarm-value is the test value of the trigger in the alarm when +it was triggered, counter-value is the value of the counter that triggered +the alarm, and time is the server time at which the event was generated. +The state is the new state of the alarm. If state is +Inactive, no more events will be generated by this +alarm until a ChangeAlarm request is executed, the alarm +is destroyed, or the counter for the alarm is destroyed. + + + + + + + + +Encoding + +Please refer to the X11 Protocol Encoding document as this section uses +syntactic conventions established there and references types defined there. + +The name of this extension is "SYNC". + + +Encoding New Types + +The following new types are used by the extension. + + + +ALARM: CARD32 +ALARMSTATE: + 0 Active + 1 Inactive + 2 Destroyed +COUNTER: CARD32 +INT64: 64-bit signed integer +SYSTEMCOUNTER: + 4 COUNTER counter + 8 INT64 resolution + 2 n length of name in bytes + n STRING8 name + p pad,p=pad(n+2) +TESTTYPE: + 0 PositiveTransition + 1 NegativeTransition + 2 PositiveComparison + 3 NegativeComparison +TRIGGER: + 4 COUNTER counter + 4 VALUETYPE wait-type + 8 INT64 wait-value + 4 TESTTYPE test-type VALUETYPE: + 0 Absolute + 1 Relative +WAITCONDITION: + 20 TRIGGER trigger + 8 INT64 event threshold + + + +An INT64 is encoded in 8 bytes with the most significant 4 bytes +first followed by the least significant 4 bytes. Within these 4-byte +groups, the byte ordering determined during connection setup is used. + + + + +Encoding Errors + +Counter + 1 0 Error + 1 Base + 0 code + 2 CARD16 sequence number + 4 CARD32 bad counter + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +Alarm + 1 0 Error + 1 Base + 1 code + 2 CARD16 sequence number + 4 CARD32 bad alarm + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused + + + + + +Encoding Requests + + +Initialize + 1 CARD8 major opcode + 1 0 minor opcode + 2 2 request length + 1 CARD8 major version + 1 CARD8 minor version + 2 unused +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 reply length + 1 CARD8 major version + 1 CARD8 minor version + 2 unused + 20 unused + +ListSystemCounters + 1 CARD8 major opcode + 1 1 minor opcode + 2 1 request length +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 reply length + 4 INT32 list length + 20 unused + 4n list of SYSTEMCOUNTER system counters + +CreateCounter + 1 CARD8 major opcode + 1 2 minor opcode + 2 4 request length + 4 COUNTER id + 8 INT64 initial value + +DestroyCounter + 1 CARD8 major opcode + 1 6 minor opcodeA previous version of this document gave an incorrect minor opcode + 2 2 request length + 4 COUNTER counter +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 reply length + 8 INT64 counter value + 16 unused + +Await + 1 CARD8 major opcode + 1 7 minor opcodeA previous version of this document gave an incorrect minor opcode. + 2 1 + 7*n request length + 28n LISTofWAITCONDITION wait conditions + +ChangeCounter + 1 CARD8 major opcode + 1 4 minor opcodeA previous version of this document gave an incorrect minor opcode. + 2 4 request length + 4 COUNTER counter + 8 INT64 amount + +SetCounter + 1 CARD8 major opcode + 1 3 minor opcodeA previous version of this document gave an incorrect minor opcode. + 2 4 request length + 4 COUNTER counter + 8 INT64 value + +CreateAlarm + 1 CARD8 major opcode + 1 8 minor opcode + 2 3+n request length + 4 ALARM id + 4 BITMASK values mask + + #x00000001 counter + #x00000002 value-type + #x00000004 value + #x00000008 test-type + #x00000010 delta + #x00000020 events + + 4n LISTofVALUE values + +VALUES + 4 COUNTER counter + 4 VALUETYPE value-type + 8 INT64 value + 4 TESTTYPE test-type + 8 INT64 delta + 4 BOOL events + +ChangeAlarm + 1 CARD8 major opcode + 1 9 minor opcode + 2 3+n request length + 4 ALARM id + 4 BITMASK values mask + encodings as for CreateAlarm + 4n LISTofVALUE values + encodings as for CreateAlarm + +DestroyAlarm + 1 CARD8 major opcode + 1 11 minor opcodeA previous version of this document gave an incorrect minor opcode. + 2 2 request length + 4 ALARM alarm + +QueryAlarm + 1 CARD8 major opcode + 1 10 minor opcodeA previous version of this document gave an incorrect minor opcode. + 2 2 request length + 4 ALARM alarm +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 2 reply length + 20 TRIGGER trigger + 8 INT64 delta + 1 BOOL events + 1 ALARMSTATE state + 2 unused + +SetPriority + 1 CARD8 major opcode + 1 12 minor opcode + 2 3 request length + 4 CARD32 id + 4 INT32 priority + +GetPriority + 1 CARD8 major opcode + 1 13 minor opcode + 2 1 request length + 4 CARD32 id +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 reply length + 4 INT32 priority + 20 unused + + + + + + +Encoding Events + + +CounterNotify + 1 Base + 0 code + 1 0 kind + 2 CARD16 sequence number + 4 COUNTER counter + 8 INT64 wait value + 8 INT64 counter value + 4 TIME timestamp + 2 CARD16 count + 1 BOOL destroyed + 1 unused + +AlarmNotify + 1 Base + 1 code + 1 1 kind + 2 CARD16 sequence number + 4 ALARM alarm + 8 INT64 counter value + 8 INT64 alarm value + 4 TIME timestamp + 1 ALARMSTATE state + 3 unused + + + + -- cgit v1.2.3 From 69996150256954ef71c45ee7727fea96e02f8db2 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 30 Jun 2010 13:39:21 -0400 Subject: specs: move geproto.txt in the specs directory Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 2 +- specs/geproto.txt | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 specs/geproto.txt (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index 9d94e85..c717d04 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -23,7 +23,7 @@ if ENABLE_SPECS doc_sources = dbe.xml security.xml sync.xml -dist_doc_DATA = $(doc_sources) +dist_doc_DATA = $(doc_sources) geproto.txt if HAVE_XMLTO doc_DATA = $(doc_sources:.xml=.html) diff --git a/specs/geproto.txt b/specs/geproto.txt new file mode 100644 index 0000000..1054def --- /dev/null +++ b/specs/geproto.txt @@ -0,0 +1,84 @@ + X Generic Event Extension + Peter Hutterer + peter.hutterer@who-t.net + + +1. Introduction +2. Extension Initialization +3. Events +4. Notes + +_____________________________________________________________________________ +1. Introduction + +X was designed to provide 64 event opcodes for all extensions. These events +are limited to 32 bytes. + +The Generic Event Extension provides a template event for extensions to re-use +a single event opcode. GE only provide headers and the most basic +functionality, leaving the extensions to interpret the events in their +specific context. + +GenericEvents may be longer than 32 bytes. If so, the number of 4 byte units +following the initial 32 bytes must be specified in the length field of the +event. +_____________________________________________________________________________ +2. Extension Initialization + +The name of this extension is "Generic Event Extension" + +┌─── + GEQueryVersion + client-major-version: CARD16 + client-minor-version: CARD16 + â–¶ + major-version: CARD16 + minor-version: CARD16 +└─── + + 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. + + + As of version 1.0, no other requests are provided by this extension. +_____________________________________________________________________________ +3. Events + +GE defines a single event, to be used by all extensions. The event's structure +is similar to a reply. This is a core protocol event, ID 35, and is not itself +an extension event. + +┌─── + GenericEvent + type: BYTE; always GenericEvent (35) + extension: CARD8; extension offset + sequenceNumber: CARD16 low 16 bits of request seq. number + length: CARD32 length + evtype: CARD16 event type +└─── + + The field 'extension' is to be set to the major opcode of the + extension. The 'evtype' field is the actual opcode of the event. + The length field specifies the number of 4-byte blocks after the + initial 32 bytes. If length is 0, the event is 32 bytes long. +_____________________________________________________________________________ +4. Notes + +Although the wire event is of arbitrary length, the actual size of an XEvent +is restricted to sizeof(XEvent) [96 bytes, see Xlib.h]. If an extension +converts a wire event to an XEvent > 96 bytes, it will overwrite the space +allocated for the event. See struct _XSQEvent in Xlibint.h for details. + +Extensions need to malloc additional data and fill the XEvent structure with +pointers to the malloc'd data. The client then needs to free the data, only +the XEvent structure will be released by Xlib. + +The server must not send GenericEvents longer than 32 bytes until it has +verified that the client is able to interpret these events. If a long event is +sent to a client unable to process GenericEvents, future interpretation of +replies and events by this client will fail. -- cgit v1.2.3 From cf083a0d35da6665b2aebc6eea4f65009c32411b Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Sun, 1 Aug 2010 20:41:48 -0400 Subject: specs: convert protocol shape.ms specs from xorg-docs module to DocBook XML Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 2 +- specs/shape.xml | 1236 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1237 insertions(+), 1 deletion(-) create mode 100644 specs/shape.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index c717d04..c1b843b 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -22,7 +22,7 @@ # if ENABLE_SPECS -doc_sources = dbe.xml security.xml sync.xml +doc_sources = dbe.xml security.xml sync.xml shape.xml dist_doc_DATA = $(doc_sources) geproto.txt if HAVE_XMLTO diff --git a/specs/shape.xml b/specs/shape.xml new file mode 100644 index 0000000..7e5f2f7 --- /dev/null +++ b/specs/shape.xml @@ -0,0 +1,1236 @@ + + + + + + + + + X Nonrectangular Window Shape Extension Protocol + X.Org Standard + Version 1.1 + + + KeithPackard +MIT X Consortium Intel Corporation + + + HidekiHiura + SunSoft, Inc. + + + X Consortium Standard + 1989The Open Group + 2004The Open Group + 2006Keith Packard + X Consortium + X Version 11, Release 7 + + + + +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 +COPYRIGHT HOLDERS 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 copyright holders +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 +copyright holders. + + + + +TITLE + +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 both the visible and interactive shape of a +window to arbitrary, possibly disjoint, nonrectangular forms. 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 three regions: the +bounding region, the clip +region and the input 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. The input region is the subset of the +bounding region that can "contain" the pointer. + + + +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); the input +region will match the bounding region. In this document, +these areas are referred to as the +default bounding region, the +default clip region and the +default input region. For a window with inside +size of width by +height and border width +bwidth, the default bounding, clip +and input 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 + +input.x = -bwidth +input.y = -bwidth +input.width = width + 2 * bwidth +input.height = height + 2 * bwidth + + + +This extension allows a client to modify any combination of the bounding, +clip or input regions by specifying new regions that combine with the default +regions. These new regions are called the +client bounding region, +the client clip region and the +client input 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. + + + +The effective input region of a window is +defined to be the intersection of the +client input region with both the default input region and the client bounding +region. Any portion of the client input region that is not included in both +the default input region and the client bounding region will not be included in +the effective input region on the screen. + + + +Construction of the effective input region is dynamic; the client input region is +not mutated to obtain the effective input region. If a client input region is +specified that extends beyond the current default input region and the +window or its bounding region is later enlarged, the effective input region will +be enlarged to include more of the client input region if it is included in +the effective bounding 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 or input 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 and input regions 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. + + + + +Types + + +The following types are used in the request and event definitions in +subsequent sections. + + + +SHAPE_KIND: +{ Bounding, +Clip, +Input } + + + +SHAPE_OP: +{ Set, +Union, +Intersect, +Subtract, +Invert } + + + +Set +indicates that the region specified as an explicit source in the request is +stored unaltered as the new destination client region. +Union +indicates that the source and destination regions are unioned together to +produce the new destination client region. +Intersect +indicates that the source and destination regions are intersected together to +produce the new destination client region. +Subtract +indicates that the source region is subtracted from the destination region to +produce the new destination region. +Invert +indicates that the destination region is subtracted from the source region to +produce the new destination region. + + + + +Requests + +ShapeQueryVersion + + + + => + + + +majorVersion: CARD16 + + +minorVersion: CARD16 + + + +This request can be used to ensure that the server version of the SHAPE +extension is usable by the client. This document defines major version one +(1), minor version one (1). + + + +ShapeRectangles + + + + + + + + dest: WINDOW + + + destKind: SHAPE_KIND + + + op: SHAPE_OP + + + xOff, yOff: INT16 + + + rectangles: LISTofRECTANGLES + + + ordering: +{ UnSorted, +YSorted, +YXSorted, +YXBanded } + + + + +Errors: +Window, +Length, +Match, +Value + + + + + + + +This request specifies an array of rectangles, relative to the origin of the +window plus the specified offset (xOff and yOff) that together +define a region. This region is combined (as specified by the operator +op) with the existing client region (specified by destKind) of the +destination window, and the result is stored as the specified client region of +the destination window. Note that the list of rectangles can be empty, +specifying an empty region; this is not the same as passing +None to +ShapeMask, + + + +If known by the client, +ordering relations on the rectangles can be specified with the ordering +argument. +This may provide faster operation by the server. +The meanings of the ordering values are the same as in the core protocol +SetClipRectangles +request. +If an incorrect ordering is specified, +the server may generate a +Match +error, but it is not required to do so. +If no error is generated, +the graphics results are undefined. +Except for +UnSorted , +the rectangles should be nonintersecting, or the resulting region will +be undefined. +UnSorted +means that the rectangles are in arbitrary order. +YSorted +means that the rectangles are nondecreasing in their Y origin. +YXSorted +additionally constrains +YSorted +order in that all rectangles with an equal Y origin are +nondecreasing in their X origin. +YXBanded +additionally constrains +YXSorted +by requiring that, for every possible Y scanline, +all rectangles that include that scanline have identical Y origins and Y +extents. + + + +ShapeMask + + + + + + + + +dest: WINDOW +destKind: SHAPE_KIND +op: SHAPE_OP +xOff, yOff: INT16 +source: PIXMAP or +None + + + + +Errors: +Window, +Pixmap, +Match, +Value + + + + + + + +The source in this request is a 1-bit deep pixmap, or +None . +If source is +None , +the specified client region is removed from the window, causing the effective +region to revert to the default region. The +ShapeNotify +event generated by this request and subsequent +ShapeQueryExtents +will report that a client shape has not been specified. +If a valid pixmap is specified, it is converted +to a region, with bits set to one included in the region and bits set to +zero excluded, and an offset from the window origin as specified by +xOff and yOff. The resulting region is then combined (as +specified by the operator op) with the existing client region +(indicated by destKind) of the destination window, and the result is +stored as the specified client region of the destination window. The source +pixmap and destination window must have been created on the same screen, +or else a +Match +error results. + + + +ShapeCombine + + + + + + + + +dest: WINDOW + + + + +destKind: SHAPE_KIND + + + + +op: SHAPE_OP + + + + +xOff, yOff: INT16 + + + + +source: WINDOW + + + + +sourceKind: SHAPE_KIND + + + + +Errors: +Window, +Match, +Value + + + + + + + +The client region, indicated by sourceKind, of the source window is +offset from the window origin by xOff and yOff and combined with +the client region, indicated by destKind, of the destination window. +The result is stored as the specified client region of the destination +window. +The source and destination windows must be on the same screen, or else a +Match +error results. + + + +ShapeOffset + + + + + + + + +dest: WINDOW + + + + +destKind: SHAPE_KIND + + + + +xOff, yOff: INT16 + + + + +Errors: +Window, +Match, +Value + + + + + + + +The client region, indicated by destKind, is moved relative to its +current position by the amounts xOff and yOff. + + + +ShapeQueryExtents + + + + + + + + +dest: WINDOW + + + + + + + + => + + + + + + + + +boundingShaped: BOOL + + + + +clipShaped: BOOL + + + + +xBoundingShape: INT16 + + + + +yBoundingShape: INT16 + + + + +widthBoundingShape: CARD16 + + + + +heightBoundingShape: CARD16 + + + + +xClipShape: INT16 + + + + +yClipShape: INT16 + + + + +widthClipShape: CARD16 + + + + +heightClipShape: CARD16 + + + + +Errors: +Window + + + + + + + +The boundingShaped and clipShaped results are +True +if the corresponding client regions have been specified, else they are +False . +The x, y, width, and height values define the extents of the client regions, +when a client region has not been specified, the extents of the +corresponding default region are reported. + + + +ShapeSelectInput + + + + + + + + +window: WINDOW + + + + +enable: BOOL + + + + +Errors: +Window, +Value + + + + + + + +Specifying enable as +True +causes the server to send the requesting client a +ShapeNotify +event whenever the bounding, clip or input region of the specified window is +altered by any client. +Specifying enable as +False +causes the server to stop sending such events. + + + +ShapeInputSelected + + + + + + + + +window: WINDOW + + + + +=> +enable: BOOL + + + + +Errors: +Window + + + + + + + +If enable is +True, then +ShapeNotify +events for the window are generated for this client. + + + +ShapeGetRectangles + + + + + + + + +window: WINDOW + + + + +kind: SHAPE_KIND + + + + + => +rectangles: LISTofRECTANGLE + + + + +ordering: +{ UnSorted, +YSorted, +YXSorted, +YXBanded } + + + + +Errors: +Window, +Match + + + + + + + +A list of rectangles describing the region indicated by kind, and the +ordering of those rectangles, is returned. The meaning of the ordering +values is the same as in the +ShapeRectangles +request. + + + + +Events + +ShapeNotify + + + + + + + + +window: WINDOW + + + + +kind: SHAPE_KIND + + + + +shaped: BOOL + + + + +x, y: INT16 + + + + +width, +height: CARD16 + + + + +time: TIMESTAMP + + + + + + + +Whenever the client bounding, clip or input shape of a window is modified, a +ShapeNotify +event is sent to each client that has used +ShapeSelectInput +to request it. + + + +Kind indicates which client region (bounding or clip) has been modified; +shaped is +True +when the window has a client shape of type kind, and is +False +when the window no longer has a client shape of this type. +The x, y, width, and height indicate the extents of the +current shape. When shaped is +False +these will indicate the extents of the default region. The timestamp +indicates the server time when the shape was changed. + + + + +Encoding + +Please refer to the X11 Protocol Encoding document as this document uses +conventions established there. + + + +The name of this extension is "SHAPE". + + + +New Types + + +SHAPE_KIND + 0 Bounding + 1 Clip + 2 Input + + + +SHAPE_OP + 0 Set + 1 Union + 2 Intersect + 3 Subtract + 4 Invert + + + + +Requests + +ShapeQueryVersion + 1 CARD8 opcode + 1 0 shape opcode + 2 1 request length + +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 length + 2 CARD16 major version + 2 CARD16 minor version + 20 unused + + + +ShapeRectangles + 1 CARD8 opcode + 1 1 shape opcode + 2 4+2n request length + 1 SHAPE_OP operation + 1 SHAPE_KIND destination kind + 1 ordering + 0 UnSorted + 1 YSorted + 2 YXSorted + 3 YXBanded + 1 unused + 4 WINDOW destination window + 2 INT16 x offset + 2 INT16 y offset + 8n LISTofRECTANGLE rectangles + + + + +ShapeMask + 1 CARD8 opcode + 1 2 shape opcode + 2 5 request length + 1 SHAPE_OP operation + 1 SHAPE_KIND destination kind + 2 unused + 4 WINDOW destination window + 2 INT16 x offset + 2 INT16 y offset + 4 PIXMAP source bitmap + 0 None + + + + +ShapeCombine + 1 CARD8 opcode + 1 3 shape opcode + 2 5 request length + 1 SHAPE_OP operation + 1 SHAPE_KIND destination kind + 1 SHAPE_KIND source kind + 1 unused + 4 WINDOW destination window + 2 INT16 x offset + 2 INT16 y offset + 4 WINDOW source window + + + +ShapeOffset + 1 CARD8 opcode + 1 4 shape opcode + 2 4 request length + 1 SHAPE_KIND destination kind + 3 unused + 4 WINDOW destination window + 2 INT16 x offset + 2 INT16 y offset + + + +ShapeQueryExtents + 1 CARD8 opcode + 1 5 shape opcode + 2 2 request length + 4 WINDOW destination window + + => + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 reply length + 1 BOOL bounding shaped + 1 BOOL clip shaped + 2 unused + 2 INT16 bounding shape extents x + 2 INT16 bounding shape extents y + 2 CARD16 bounding shape extents width + 2 CARD16 bounding shape extents height + 2 INT16 clip shape extents x + 2 INT16 clip shape extents y + 2 CARD16 clip shape extents width + 2 CARD16 clip shape extents height + 4 unused + + + +ShapeSelectInput + 1 CARD8 opcode + 1 6 shape opcode + 2 3 request length + 4 WINDOW destination window + 1 BOOL enable + 3 unused + + + +ShapeInputSelected + 1 CARD8 opcode + 1 7 shape opcode + 2 2 request length + 4 WINDOW destination window + => + 1 1 Reply + 1 BOOL enabled + 2 CARD16 sequence number + 4 0 reply length + 24 unused + + + +ShapeGetRectangles + 1 CARD8 opcode + 1 8 shape opcode + 2 3 request length + 4 WINDOW window + 1 SHAPE_KIND source kind + 3 unused + => + 1 1 Reply + 1 ordering + 0 UnSorted + 1 YSorted + 2 YXSorted + 3 YXBanded + 2 CARD16 sequence number + 4 2n reply length + 4 CARD32 nrects + 20 unused + 8n LISTofRECTANGLE rectangles + + + + +Events + +ShapeNotify + 1 CARD8 type (0 + extension event base) + 1 SHAPE_KIND shape kind + 2 CARD16 sequence number + 4 WINDOW affected window + 2 INT16 x value of extents + 2 INT16 y value of extents + 2 CARD16 width of extents + 2 CARD16 height of extents + 4 TIMESTAMP server time + 1 BOOL shaped + 11 unused + + + + + + +Glossary + + 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. + + + + + + input region + + +The subset of the bounding region which can ``contain'' the +pointer. + + + + + + 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. + + + + + + default input region + + +The rectangular area, as described by the core protocol window size, that +covers the interior of the window and its 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. + + + + + + client input region + + +The region associated with a window that is directly modified via this +extension when specified by + ShapeInput . +This region is used in conjunction with the default input region +and the client bounding region to produce the effective input 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. + + + + + + effective input region + + +The actual shape of the window on the screen (excluding the +effects of overlapping windows) which can ``contain'' the pointer. +When a window has a client input region or +a client bounding region, the effective input region is the intersection of +the default input region, the client input region (if any) and the client +bounding region (if any). Otherwise, the effective input region is the +same as the default input region. + + + + + + + -- cgit v1.2.3 From 7c9b2197cbb0f787b6330243eb777f612251064d Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Mon, 2 Aug 2010 10:40:47 -0400 Subject: specs: convert protocol shm.ms specs from xorg-docs module to DocBook XML Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 2 +- specs/shm.xml | 474 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 475 insertions(+), 1 deletion(-) create mode 100644 specs/shm.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index c1b843b..56fd128 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -22,7 +22,7 @@ # if ENABLE_SPECS -doc_sources = dbe.xml security.xml sync.xml shape.xml +doc_sources = dbe.xml security.xml shape.xml shm.xml sync.xml dist_doc_DATA = $(doc_sources) geproto.txt if HAVE_XMLTO diff --git a/specs/shm.xml b/specs/shm.xml new file mode 100644 index 0000000..24c989c --- /dev/null +++ b/specs/shm.xml @@ -0,0 +1,474 @@ + + + + + + + + + MIT-SHM(The MIT Shared Memory Extension) + How the shared memory extension works + Version 1.0 + + + JonathanCorbet + Atmospheric Technology Division National Center for Atmospheric Research + corbet@ncar.ucar.edu + + + Formatted and edited for release 5 by + KeithPackard + MIT X Consortium + + + X Consortium Standard + 1991X Consortium + X Consortium + X Version 11, Release 7 + + + +This document briefly describes how to use the MIT-SHM shared memory +extension. I have tried to make it accurate, but it would not surprise me +if some errors remained. If you find anything wrong, do let me know and I +will incorporate the corrections. Meanwhile, please take this document "as +is" (eman improvement over what was there before, but certainly not the +definitive word.) + + + + + +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. + + + + + +TITLE + +REQUIREMENTS + +The shared memory extension is provided only by some X servers. To find out +if your server supports the extension, use xdpyinfo(1). In particular, to +be able to use this extension, your system must provide the SYSV shared +memory primitives. There is not an mmap-based version of this extension. +To use shared memory on Sun systems, you must have built your kernel with +SYSV shared memory enabled -- which is not the default configuration. +Additionally, the shared memeory maximum size will need to be increased on +both Sun and Digital systems; the defaults are far too small for any useful +work. + + + + +WHAT IS PROVIDED + + +The basic capability provided is that of shared memory XImages. This is +essentially a version of the ximage interface where the actual image data +is stored in a shared memory segment, and thus need not be moved through +the Xlib interprocess communication channel. For large images, use of this +facility can result in some real performance increases. + + + +Additionally, some implementations provided shared memory pixmaps. These +are 2 dimensional arrays of pixels in a format specified by the X server, +where the image data is stored in the shared memory segment. Through use of +shared memory pixmaps, it is possible to change the contents of these +pixmaps without using any Xlib routines at all. Shared memory pixmaps can +only be supported when the X server can use regular virtual memory for +pixmap data; if the pixmaps are stored in some magic graphics hardware, your +application will not be able to share them with the server. Xdpyinfo(1) +doesn't print this particular nugget of information. + + + + +HOW TO USE THE SHARED MEMORY EXTENSION + +Code which uses the shared memory extension must include a number of header +files: + + + +#include <X11/Xlib.h> /* of course */ +#include <sys/ipc.h> +#include <sys/shm.h> +#include <X11/extensions/XShm.h> + + + +Of course, if the system you are building on does not support shared +memory, the file XShm.h may not be present. You may want to make +liberal use of #ifdefs. + + + +Any code which uses the shared memory extension should first check to see +that the server provides the extension. You could always be running over +the net, or in some other environment where the extension will not work. +To perform this check, call either + + + + + Status XShmQueryExtension + Display *display + + + + +or + + + + + Status XShmQueryVersion + Display *display + int *major + int *minor + Bool *pixmaps + + + + +Where "display" is, of course, the display on which you are running. If +the shared memory extension may be used, the return value from either +function will be True; otherwise your program should operate using +conventional Xlib calls. When the extension is available, +\fCXShmQueryVersion\fP also returns "major" and "minor" which are the +version numbers of the extension implementation, and "pixmaps" which is +True iff shared memory pixmaps are supported. + + + + +USE OF SHARED MEMORY XIMAGES + +The basic sequence of operations for shared memory XImages is as follows: + + + + + +Create the shared memory XImage structure + + + + +Create a shared memory segment to store the image data + + + + +Inform the server about the shared memory segment + + + + +Use the shared memory XImage, much like a normal one. + + + + + +To create a shared memory XImage, use: + + + + + XImage *XShmCreateImage + Display *display + Visual *visual + unsigned int depth + int format + char *data + XShmSegmentInfo *shminfo + unsigned int width + unsigned int height + + + + +Most of the arguments are the same as for XCreateImage; I will not go +through them here. Note, however, that there are no "offset", "bitmap_pad", +or "bytes_per_line" arguments. These quantities will be defined by the +server itself, and your code needs to abide by them. Unless you have already +allocated the shared memory segment (see below), you should pass in NULL for +the "data" pointer. + + + +There is one additional argument: "shminfo", which is a pointer to a +structure of type XShmSegmentInfo. You must allocate one of these +structures such that it will have a lifetime at least as long as that of +the shared memory XImage. There is no need to initialize this structure +before the call to XShmCreateImage. + + + +The return value, if all goes well, will be an XImage structure, which you +can use for the subsequent steps. + + + +The next step is to create the shared memory segment. This is +best done after the creation of the XImage, since you need to make use of +the information in that XImage to know how much memory to allocate. To +create the segment, you need a call like: + + + + +shminfo.shmid = shmget (IPC_PRIVATE, + image->bytes_per_line * image->height, IPC_CREAT|0777); + + + +(assuming that you have called your shared memory XImage "image"). You +should, of course, follow the Rules and do error checking on all of these +system calls. Also, be sure to use the bytes_per_line field, not the width +you used to create the XImage as they may well be different. + + + +Note that the shared memory ID returned by the system is stored in the +shminfo structure. The server will need that ID to attach itself to the +segment. + + + +Also note that, on many systems for security reasons, the X server +will only accept to attach to the shared memory segment if it's +readable and writeable by "other". On systems where the X server is +able to determine the uid of the X client over a local transport, the +shared memory segment can be readable and writeable only by the uid of +the client. + + + +Next, attach this shared memory segment to your process: + + + +shminfo.shmaddr = image->data = shmat (shminfo.shmid, 0, 0); + + + +The address returned by shmat should be stored in *both* the XImage +structure and the shminfo structure. + + + +To finish filling in the shminfo structure, you need to decide how you want +the server to attach to the shared memory segment, and set the "readOnly" +field as follows. Normally, you would code: + + +shminfo.readOnly = False; + + + +If you set it to True, the server will not be able to write to this +segment, and thus XShmGetImage calls will fail. + + + +Finally, tell the server to attach to your shared memory segment with: + + + +Status XShmAttach (display, shminfo); + + + +If all goes well, you will get a non-zero status back, and your XImage is +ready for use. + + + +To write a shared memory XImage into an X drawable, use XShmPutImage: + + + + + Status XShmPutImage + Display *display + Drawable d + GC gc + XImage *image + int src_x + int src_y + int dest_x + int dest_y + unsigned int width + unsigned int height + bool send_event + + + + +The interface is identical to that of XPutImage, so I will spare my fingers +and not repeat that documentation here. There is one additional parameter, +however, called "send_event". If this parameter is passed as True, the +server will generate a "completion" event when the image write is complete; +thus your program can know when it is safe to begin manipulating the shared +memory segment again. + + + +The completion event has type XShmCompletionEvent, which is defined as the +following: + + + +typedef struct { + int type; /* of event */ + unsigned long serial; /* # of last request processed */ + Bool send_event; /* true if came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Drawable drawable; /* drawable of request */ + int major_code; /* ShmReqCode */ + int minor_code; /* X_ShmPutImage */ + ShmSeg shmseg; /* the ShmSeg used in the request */ + unsigned long offset; /* the offset into ShmSeg used */ +} XShmCompletionEvent; + + + +The event type value that will be used can be determined at run time with a +line of the form: + + + +int CompletionType = XShmGetEventBase (display) + ShmCompletion; + + + +If you modify the shared memory segment before the arrival of the +completion event, the results you see on the screen may be inconsistent. + + + +To read image data into a shared memory XImage, use the following: + + + + + Status XShmGetImage + Display *display + Drawable d + XImage *image + int x + int y + unsigned long plane_mask + + + + +Where "display" is the display of interest, "d" is the source drawable, +"image" is the destination XImage, "x" and "y" are the offsets within +"d", and "plane_mask" defines which planes are to be read. + + + +To destroy a shared memory XImage, you should first instruct the server to +detach from it, then destroy the segment itself, as follows: + + + +XShmDetach (display, shminfo); +XDestroyImage (image); +shmdt (shminfo.shmaddr); +shmctl (shminfo.shmid, IPC_RMID, 0); + + + + + +USE OF SHARED MEMORY PIXMAPS + +Unlike X images, for which any image format is usable, the shared memory +extension supports only a single format (i.e. XYPixmap or ZPixmap) for the +data stored in a shared memory pixmap. This format is independent of the +depth of the image (for 1-bit pixmaps it doesn't really matter what this +format is) and independent of the screen. Use XShmPixmapFormat to get the +format for the server: + + + + + int XShmPixmapFormat + Display *display + + + + +If your application can deal with the server pixmap data format (including +bits-per-pixel et al.), create a shared memory segment and "shminfo" +structure in exactly the same way as is listed above for shared memory +XImages. While it is, not strictly necessary to create an XImage first, +doing so incurs little overhead and will give you an appropriate +bytes_per_line value to use. + + + +Once you have your shminfo structure filled in, simply call: + + + + + Pixmap XShmCreatePixmap + Display *display + Drawable d + char *data + XShmSegmentInfo *shminfo + unsigned int width + unsigned int height + unsigned int depth + + + + +The arguments are all the same as for XCreatePixmap, with two additions: +"data" and "shminfo". The second of the two is the same old shminfo +structure that has been used before. The first is the pointer to the shared +memory segment, and should be the same as the shminfo.shmaddr field. I am +not sure why this is a separate parameter. + + + +If everything works, you will get back a pixmap, which you can manipulate in +all of the usual ways, with the added bonus of being able to tweak its +contents directly through the shared memory segment. Shared memory pixmaps +are destroyed in the usual manner with XFreePixmap, though you should detach +and destroy the shared memory segment itself as shown above. + + + + -- cgit v1.2.3 From fc2c585ab9bfe0815a917c897e0b463bf04f8475 Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Mon, 2 Aug 2010 10:46:54 -0400 Subject: specs: convert protocol dpms.ms specs from xorg-docs module to DocBook XML Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 2 +- specs/dpms.xml | 563 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 564 insertions(+), 1 deletion(-) create mode 100644 specs/dpms.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index 56fd128..c02d05f 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -22,7 +22,7 @@ # if ENABLE_SPECS -doc_sources = dbe.xml security.xml shape.xml shm.xml sync.xml +doc_sources = dbe.xml dpms.xml security.xml shape.xml shm.xml sync.xml dist_doc_DATA = $(doc_sources) geproto.txt if HAVE_XMLTO diff --git a/specs/dpms.xml b/specs/dpms.xml new file mode 100644 index 0000000..d5323b1 --- /dev/null +++ b/specs/dpms.xml @@ -0,0 +1,563 @@ + + + + + + + X Display Power Management Signaling (DPMS) Extension Protocol Specification + X Project Team Standard + Version 1.0 + + + Rob Lembree + Digital Equipment Corporation + lembree@zk3.dec.com + + + X Consortium Standard + 1996Digital Equipment Corporation + 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. + + + + + + +TITLE + +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. + +X Window System is a trademark of The Open Group. + + + + + + + +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. + + + +The design goal of the DPMS extension is to be a logical extension to +the traditional screen saver. The protocol and sample implementation is +designed to use the same date types and time units as the screen saver. +The sample implementation works independently from the screen saver so that +policy as it pertains to the interaction between screen saver and DPMS can +be deferred to the user or screen saver application. The extension has +been tested with and shown to work correctly with both the internal blanking +and non-blanking screen savers, as well as with screen saver extension +clients. + + +The DPMS extension is designed to be simple, yet export sufficient +VESA DPMS information to enable full function clients to be written. +Included is the ability to sense DPMS capability, set and get DPMS timeouts, +enable and disable individual DPMS modes, enable and disable DPMS (without +destroying timeout values), and sense current DPMS on/off state and +power level. + + +There are four power levels specified by the Video Electronics Standards +Association (VESA) Display Power Management Signaling (DPMS) standard. +These are: + + + +DPMS Extension Power Levels + 0 DPMSModeOn In use + 1 DPMSModeStandby Blanked, low power + 2 DPMSModeSuspend Blanked, lower power + 3 DPMSModeOff Shut off, awaiting activity + + + +It is logical to assume that successive DPMS modes be chronologically +at the same time or later than one another, and the protocol is designed +to enforce this rule. + + + +Note however that a concious decision is made to decouple the timeouts +associated with screen saver from the DPMS timeouts. While it might be +considered logical to require that the first non-zero DPMS timeout be +greater than or equal to the screen saver timeout, this is intentionally +omitted, leaving this policy decision to the user or the screen saver +application. In the case of a laptop where power may be scarce, the +importance of power savings should supersede the screen saver. If the +laptop user plugs the unit in and power is no longer a scarce commodity, +it may be decided to make DPMS less aggressive, or disable it completely. + + + + +Requests + +DPMSGetVersion + + + + + + + + +client_major_version: CARD16 + + + + +client_minor_version: CARD16 + + + + => + + + +server_major_version: CARD16 + + + + +server_minor_version: CARD16 + + + + + + + +If supplied, the client_major_version and +client_minor_version indicate what version +of the protocol the +client wants the server to implement. The server version numbers +returned indicate the protocol this extension actually supports. This +might not equal the version sent by the client. An implementation can +(but need not) support more than one version simultaneously. The +server_major_version and the +server_minor_version are a +mechanism to support future revisions of the Display Power Management +Signaling protocol which may be necessary. In general, the major version +would increment for incompatible changes, and the minor version would +increment for small, upward-compatible changes. Servers that support the +protocol defined in this document will return a +server_major_version +of one (1), and a server_minor_version +of one (1). + + + +DPMSCapable + + + + + + + + => + + + +capable: BOOL + + + + + + + +This request is used to determine whether or not the currently running +server's devices are capable of DPMS operations. The truth value of this +request is implementation defined, but is generally based on the capabilities +of the graphic card and monitor combination. Also, the return value in the +case of heterogeneous multi-head servers is implementation defined. + + + +DPMSGetTimeouts + + + + + + + + => + + + +standby_timeout: CARD16 + + + + +suspend_timeout: CARD16 + + + + +off_timeout: CARD16 + + + + + + + +This request returns the current values of the DPMS timeout values. All +values are in units of seconds. + + + +standby_timeout is the amount of time +of inactivity 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 indicates that this mode is disabled. + + + +suspend_timeout is the amount of time +of inactivity 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 indicates that this mode is disabled. + + + +off_timeout is the amount of time of +inactivity 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 indicates that this mode is disabled. + + + +DPMSSetTimeouts + + + + + + + + +standby_timeout: CARD16 + + + + +suspend_timeout: CARD16 + + + + +off_timeout: CARD16 + + + + => + + + + + + + +All values are in units of seconds. +standby_timeout is the amount of +time of inactivity before standby mode will be invoked. This is the +lightest level of power savings, and the monitor is generally immediately +ready upon detection of user activity. This is most often implemented by +shutting off the horizontal sync signal to the monitor. +A value of zero disables this mode. + + + +The suspend_timeout specifies the amount +of time of inactivity +before the screen is placed into suspend mode. Suspend mode is the +middle level of power savings, resulting in a slightly longer recovery +upon detection of activity. Suspend mode is most often implemented by +pulsing the horizontal sync signal, and removing the vertical sync +signal. A value of zero disables this mode. + + + +The off_timeout specifies the amount of +time of inactivity before +the monitor is shut off. Off mode is the deepest level of power management, +resulting in the greatest power savings and the longest recovery time. +Off mode is most often implemented by removing both the horizontal and +vertical signals. A value of zero disables this mode. + + +The values of successive power levels must be greater than or equal +to the value of the previous (non-zero) level. A BadValue error is generated +if an illegal combination is detected. + + +DPMSEnable + + +=> + + + +This request enables the DPMS characteristics of the server, using the +server's currently stored timeouts. If DPMS is already enabled, no change is +effected. + + + +DPMSDisable + + +=> + + + +This request disables the DPMS characteristics of the server. It does +not affect the core or extension screen savers. If DPMS is already +disabled, no change is effected. This request is provided so that DPMS +may be disabled without damaging the server's stored timeout values. + + + +DPMSForceLevel + + + + + + + + +power_level: CARD16 + + + + => + + + + + + +This request forces a specific DPMS level on the server. If DPMS is +disabled, a BadMatch error is generated. If an erroneous power level +is specified, a BadValue error is returned, and the error value contains +the bad value. If the power level specified is already in effect, no +changes occur. Power Level must be one of DPMSModeOn, DPMSModeStandby, +DPMSModeSuspend or DPMSModeOff. + + + +DPMSInfo + + + + + + + + => + + + +power_level: CARD16 + + + + +state: BOOL + + + + + + + +This request returns information about the current DPMS state of the +display. state is one of DPMSEnabled +or DPMSDisabled. +If state is DPMSEnabled, +power_level is returned as one +of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend or DPMSModeOff, otherwise +it is undefined. + + + + + +Events and Errors + +No new events or errors are defined by this extension. + + + + +Encoding + +Please refer to the X11 Protocol Encoding document as this document uses +conventions established there. + + + +The name of this extension is "DPMS". + + + +DPMSGetVersion + 1 CARD8 opcode + 1 0 DPMS opcode + 2 2 request length + 2 CARD16 client_major_version + 2 CARD16 client_minor_version +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 length + 2 CARD16 server_major_version + 2 CARD16 server_minor_version + 20 unused + + + +DPMSCapable + 1 CARD8 opcode + 1 1 DPMS opcode + 2 1 request length +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 length + 1 BOOL capable + 23 unused + + + +DPMSGetTimeouts + 1 CARD8 opcode + 1 2 DPMS opcode + 2 1 request length +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 length + 2 CARD16 standby_timeout + 2 CARD16 suspend_timeout + 2 CARD16 off_timeout + 18 unused + + + +DPMSSetTimeouts + 1 CARD8 opcode + 1 3 DPMS opcode + 2 3 request length + 2 CARD16 standby_timeout + 2 CARD16 suspend_timeout + 2 CARD16 off_timeout + 2 unused +=> + + + +DPMSEnable + 1 CARD8 opcode + 1 4 DPMS opcode + 2 1 request length + => + + + +DPMSDisable + 1 CARD8 opcode + 1 5 DPMS opcode + 2 1 request length + => + + + +DPMSForceLevel + 1 CARD8 opcode + 1 6 DPMS opcode + 2 2 request length + 2 power_level + 0 DPMSModeOn + 1 DPMSModeStandby + 2 DPMSModeSuspend + 3 DPMSModeOff + 2 unused +=> + + + +DPMSInfo + 1 CARD8 opcode + 1 7 DPMS opcode + 2 1 request length +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 length + 2 power_level + 0 DPMSModeOn + 1 DPMSModeStandby + 2 DPMSModeSuspend + 3 DPMSModeOff + 1 BOOL state + 21 unused + + + + + -- cgit v1.2.3 From 99a5fde423a301167cb825edbf718de7af9f1158 Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Mon, 2 Aug 2010 13:21:31 -0400 Subject: specs: convert protocol tog-cup.ms from xorg-docs to DocBook XML Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 10 +- specs/tog-cup.xml | 562 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 571 insertions(+), 1 deletion(-) create mode 100644 specs/tog-cup.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index c02d05f..d46c391 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -22,7 +22,15 @@ # if ENABLE_SPECS -doc_sources = dbe.xml dpms.xml security.xml shape.xml shm.xml sync.xml +doc_sources = \ + dbe.xml \ + dpms.xml \ + security.xml \ + shape.xml \ + shm.xml \ + sync.xml \ + tog-cup.xml + dist_doc_DATA = $(doc_sources) geproto.txt if HAVE_XMLTO diff --git a/specs/tog-cup.xml b/specs/tog-cup.xml new file mode 100644 index 0000000..08bb19b --- /dev/null +++ b/specs/tog-cup.xml @@ -0,0 +1,562 @@ + + + + + + + + Colormap Utilization Policy and Extension + X Project Team Standard + Version 1.0 + + + Kaleb + S. + Keithley + The Open Group + + + X Consortium Standard + 1986-1997The Open Group + X Consortium + X Version 11, Release 6.8 + + + + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this +software and associated documentation files (the Software), to use the +Software +without restriction, including, without limitation, the rights to copy, +modify, merge, +publish, distribute and sublicense the Software, to make, have made, +license and +distribute derivative works thereof, and to permit persons to whom the +Software is +furnished to do so, subject to the following conditions: + + +The above copyright notice and the following permission notice shall be +included in all copies 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 NON- +INFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF +CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN +CONNNECTION WITH THE SOFTWARE OR THE USE OF OTHER DEALINGS IN +THE SOFTWARE. + + +Except as contained in this notice, the name of The Open Group shall not be +used in +advertising or otherwise to promote the use or other dealings in this +Software without prior written authorization from The Open Group. + + +X Window System is a trademark of The Open Group. + + + + + + +TITLE + +Overview + +This extension has three purposes: a) to provide mechanism for a special +application (a colormap manager) to discover any special colormap +requirements, e.g. the colormap entries that are nominally reserved for +desktop colors in the MS-Windows environment and initialize the default +colormap so that it can be more easily shared; and b) to encourage colormap +sharing and reduce colormap flashing on low-end 8-bit frame buffers by +providing a policy for sharing; and c) when colormaps aren't shared, +define a behavior in the X server color allocation scheme to reduce +colormap flashing. + + + +To encourage colormap sharing and accomodate special colormap requirements +two new protocols are defined: the first provides a way to query the +server for a list of reserved colormap entries, and the second is a way +to initialize read-only (shareable) colormap entries at specific locations +in a colormap. + + + +To minimize colormap flashing when the root window's default visual is one +of GrayScale, PseudoColor, or DirectColor, and a private colormap for the +default visual is being used, a minor (but compatible) change to the +server implementation of the AllocColor and AllocNamedColor requests is +required. Where the core protocol says nothing about the pixel values +returned, when this extension is in effect, the AllocColor and AllocNamedColor +requests will first look for a matching color in the default colormap, and, +if a match is found and the same cell in the private colormap has not +already been allocated, the color will be allocated in the private colormap +at the same locaton as in the default colormap (instead of in the first +available location.) + + + + +Requests + +QueryVersion + + + + + + + + +client_major_version: CARD16 + + + + +client_minor_version: CARD16 + + + + +=> + + + + +server_major_version: CARD16 + + + + +server_minor_version: CARD16 + + + + + + + +If supplied, the client_major_version and client_minor_version indicate +what version of the protocol the client wants the server to implement. +The server version numbers returned indicate the protocol this extension +actually supports. This might not equal the version sent by the client. +An implementation can (but need not) support more than one version +simultaneously. The server_major_version and the server_minor_version +are a mechanism to support future revisions of the TOG-CUP protocol that +may be necessary. In general, the major version would increment for +incompatible changes, and the minor version would increment for small +upward-compatible changes. Servers that support the protocol defined in +this document will return a server_major_version of one (1), and a +server_minor_version of zero (0). + + + +GetReservedColormapEntries + + + + + + + + +screen: CARD32 + + + + +=> + + + + +entries: LISTofCOLORITEM + + + + + + + +This request returns a list of colormap entries (pixels) that are reserved +by the system, e.g. MS-Windows reserved desktop colors. This list will, at a +minimum, contain entries for the BlackPixel and WhitePixel of the specified +screen. The do-red, do-green, and do-blue elements of the COLORITEMs are +unused in this reply. + + + +Rationale: There are colormap entries (pixels) that, e.g., MS-Windows +desktop reserves as desktop colors, that should not be altered. If they +are altered then X programs will cause colormap flashing between X and +MS-Windows applications running/displaying on the same desktop. + + + +StoreColors + + + + + + + + +cmap: COLORMAP + + + + +items: LISTofCOLORITEM + + + + +=> + + + + +items: LISTofCOLORITEM + + + + + + + +This request changes the colormap entries of the specified pixels. The +colormap entries are allocated as if by an AllocColor request. The do-red, +do-green, and do-blue elements of the COLORITEMs are unused in this request. +A boolean alloc-ok element (a bit) is returned indicating whether the +particular pixel was successfully allocated or not. If successfully +allocated the RGB and pixel are returned. + + + +A Value error is generated if a pixel is not a valid index into cmap. A +BadMatch error is generated if if cmap does not belong to a GrayScale, +PseudoColor, or DirectColor visual. + + + + + +Events and Errors + +No new events or errors are defined by this extension. + + + + +Changes to existing protocol. + +None. + + + + +Encoding + +The name of this extension is "TOG-CUP". + + + +The conventions used here are the same as those for the core X11 +Protocol Encoding. + + + +QueryVersion + 1 CARD8 opcode + 1 0 TOG-CUP opcode + 2 2 request length + 2 CARD16 client_major_version + 2 CARD16 client_minor_version +=> + 1 1 reply + 1 unused + 2 CARD16 sequence number + 4 0 length + 2 CARD16 server_major_version + 2 CARD16 server_minor_number + 20 unused + + + +GetReservedColormapEntries + 1 CARD8 opcode + 1 1 TOG-CUP opcode + 2 2 request length + 4 CARD32 screen +=> + 1 1 reply + 1 unused + 2 CARD16 sequence number + 4 3n length + 24 unused + 12n LISTofCOLORITEM items + + + +StoreColors + 1 CARD8 opcode + 1 2 TOG-CUP opcode + 2 2+3n request length + 4 COLORMAP cmap + 12n LISTofCOLORITEM items +=> + 1 1 reply + 1 unused + 2 CARD16 sequence number + 4 3n length + 24 unused + 12n LISTofCOLORITEM items + + + +(The definition of COLORITEM here is only for the purpose of defining the +additional alloc-ok member in the CUPStoreColors reply.) + + + + COLORITEM + 4 CARD32 pixel + 2 CARD16 red + 2 CARD16 green + 2 CARD16 blue + 1 alloc-ok + #x07 unused + #x08 alloc-ok (1 is True, 0 is False) + #xF0 unused + 1 unused + + + + +C Language Binding + + +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 deleting XCup +at the start of the function. All functions that have return type Status +will return nonzero for success and zero for failure. + + + +The include file for this extension is +<X11/extensions/Xcup.h>. + + + + + Status XCupQueryVersion + Display* display + int* major_version_return + int* minor_version_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + major_version_return + + + +Returns the major version supported by the server. + + + + + + minor_version_return + + + +Returns the minor version supported by the server. + + + + + + + +XCupQueryVersions sets major_version_return and minor_version_return to +the major and minor TOG-CUP protocol version supported by the server. If +the TOG-CUP library is compatible with the version returned by the server, +it returns nonzero. If dpy does not support the TOG-CUP 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 +XCup functions may be called before this function. If a client violates +this rule, the effects of all subsequent XCup calls that it makes are +undefined. + + + +To get the list of reserved colormap entries, use +XCupGetReservedColormapEntries. + + + + + Status XCupGetReservedColormapEntries + Display* display + int screen + XColor** colors_out + int* ncolors + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + colors_out + + + +Returns the values reserved by the server. + + + + + + ncolors + + + +Returns the number of items in colors_out. + + + + + + +The XCupGetReservedColormapEntries function gets system specific colormap +entries. E.g. the MS-Windows desktop uses N colormap entries at the beginning +(0..N) and end (256-N..255) of the colormap. Use XFree to free colors_out. + + + +To allocate one or more read-only color cells with RGB values, use +XCupStoreColors. + + + + + Status XCupStoreColors + Display* display + Colormap colormap + XColor* colors_in_out + int ncolors + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + colormap + + + +Specifies the colormap. + + + + + + colors_in_out + + + +Specifies and returns the values actually used in the colormap. + + + + + + ncolors + + + +Specifies the number of items in colors_in_out. + + + + + + +The XCupStoreColors function changes the colormap entries of the pixel +values specified in the pixel members of the XColor structures. The colormap +entries are allocated as if an AllocColor had been used instead, i.e. the +colors are read-only (shareable). XCupStoreColors returns the number of +colors that were successfully allocated in the colormap. + + + + + +Using the TOG-CUP extension and Colormap Utilization Policy + +The X server preallocates any hardware or desktop special colors in the +default colormap; e.g. UNIX X servers preallocate Black and White pixels. +PC X servers should also preallocate the MS-Windows desktop colors. (Note +to implementors: in the Sample Implementation special colors are allocated +in the default colormap in cfbCreateDefColormap for dumb memory framebuffers.) + + + +To minimize colormap flash an application which installs its own private +colormap should query the special colors by calling +XCupGetReservedColormapEntries, and can then store those entries (in the +proper location) in its private colormap using XCupStoreColors. + + + +Applications which allocate many colors in a screen's default colormap, e.g. +a color-cube or a gray-ramp, should allocate them with XCupStoreColors. By +using XCupStoreColors the colors will be allocated sharable (read-only) and +any other application which allocates the same color will share that color +cell. + + + + -- cgit v1.2.3 From f825b85bd8bde4b78c6e3d0b05b713e6f48a2ff5 Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Mon, 2 Aug 2010 13:28:07 -0400 Subject: specs: convert protocol appgroup.ms from xorg-docs to DocBook XML Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 1 + specs/appgroup.xml | 248 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 249 insertions(+) create mode 100644 specs/appgroup.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index d46c391..af88d05 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -23,6 +23,7 @@ if ENABLE_SPECS doc_sources = \ + appgroup.xml \ dbe.xml \ dpms.xml \ security.xml \ diff --git a/specs/appgroup.xml b/specs/appgroup.xml new file mode 100644 index 0000000..eebf843 --- /dev/null +++ b/specs/appgroup.xml @@ -0,0 +1,248 @@ + + + + + + + + Description of the Application Group Extension + Implementation for the X11 Sample Server + Version 1.0 + + + Kaleb KEITHLEY + FUJITSU Limited. + blah@blah.com + + + X Consortium Standard + 1996X Consortium + X Consortium + X Version 11, Release 7 + + + +The following document explains the server side of the Application +Group Extension. + + + + + + + +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. + + + +The following document explains the server side of the Application +Group Extension. + + + +WindowsNT is a trademark of Microsoft, Inc. Macintosh and Apple +are trademarks of Apple Computer, Inc. X Window System is a +trademark of X Consortium, Inc. + + + + + +TITLE + +To understand this document and the accompanying source code, you +should know the C language, should be familiar with X server +internals, and should also have a general knowledge of the X +Window System. + + + +AppGroup Server Public Functions + +The AppGroup extension adds seven new functions that are called +from elsewhere in the server. They are: XagExtensionInit, +XagDefaultColormap, XagRootVisual, XagLeader, XagIsControlledRoot, +XagConnectionInfo, XagCallClientStateChange. + + +XagExtensionInit is the extension initialization function called +from InitExtension in mi/miinitext.c. Note that an new resource +type, RT_APPGROUP, is created, specifying the destructor function +XagAppGroupFree. + + +XagDefaultColormap returns the colormap ID that was specified in +the creation of the AppGroup. Any time CopyFromParent is specified +for a top-level window's colormap, i.e. in a CreateWindow or +ChangeWindowAttributes request, this function is called to see +if there is an AppGroup specific colormap to use. If there is +one, its ID is returned, otherwise None is returned. + + +XagRootVisual returns the visual ID that was specified in the +creation of the Appgroup. Like XagDefaultColormap, when CopyFromParent +is specified for a top-level window's visual in a CreateWindow +request, this function is called to see if there is an AppGroup +specific visual to use. If there is one, its ID is returned, +otherwise 0 (zero) is returned. + + +XagLeader returns the ClientPtr of the client that is the AppGroup +Leader. Normally when an application maps or configures a top-level +window a MapRequest or ConfigureRequest event is delivered to the +client, e.g. a window manager, that has selected SubstructureRedirect +on the root window. However, when the application is part of an +AppGroup, the MapRequest and ConfigureRequest events are delivered +to the AppGroup Leader instead. + + +XagIsControlledRoot returns a boolean: True if the window is a +top-level window of a client in an AppGroup, False otherwise. +In a combined server, i.e. one that provides both UI and printing, +the application may create and map windows on the "printing" +screens; thus it becomes necessary to discriminate between the +AppGroup's root window and other root windows. If an AppGroup +member creates and maps a [top-level] window then the window's +parent [the root window] is tested to determine whether to send +MapRequest or ConfigureRequest events to the AppGroup Leader to +to some other client. + + +In the trivial case XagIsControlledRoot returns True if the parent +window has no parent itself, i.e. it is a root window. In the case +where the application is embedded, indicated by the singleScreen +attribute being True, the parent's drawable ID is compared to the +AppGroup's root window ID, and if it is the same, True is returned. +If neither case is true, then False is returned. + + +XagConnectionInfo returns an abreviated version of the connection +setup information. When an embedded AppGroup is created the server +returns only the information about the [UI] screen that the +application is embedded within in the connection setup in order to +prevent the application from creating windows on other screens; +thus attempting to guarantee that any window that should be embedded +can be reparented into the AppGroup Leader's window hierarchy. + + +XagCallClientStateChange is called to invoke the extension's client +state change callback additional times as necessary -- currently +only once, after the auth data becomes available between +ClientStateInitial and ClientStateConnected. Client state change +callbacks were introduced in the Record extension, which specifies +when the callbacks are invoked. Unfortunately the points at which +they are called are not necessarily the best as far as the AppGroup +Extension is concerned. Adding an additional state and calling all +the callbacks works too, however this seemed unnecessary overkill. + + + + +AppGroup Server Private APIs + +The AppGroup extension adds the following functions which are +private to the extension: ProcXagDispatch and SProcXagDispatch, +ProcXagQueryVersion and SProcXagQueryVersion, ProcXagCreate and +SProcXagCreate, ProcXagDestroy and SProcXagDestroy, +ProcGetAttr and SProcGetAttr, ProcXagQuery and SProcXagQuery, +ProcXagCreateAssoc and SProcXagCreateAssoc, ProcXagDestroyAssoc +and SProcXagDestroyAssoc, XagResetProc, and XagAppGroupFree. + + +The ProcXagDispatch, SProcXagDispatch, and XagResetProc functions +should be familiar to anyone familiar with X server internals and +I won't elaborate on them here. Similarly the wrapper functions: +SProcXagQueryVersion, SProcXagCreate, SProcXagDestroy, SProcXagGetAttr, +SProcXagQuery, SProcXagCreateAssoc, and SProcXagDestroyAssoc, as +wrappers which handle swapping integer data into the host's byte +order will not be explained in any detail. + + +ProcXagQueryVersion returns the major and minor versions of the +AppGroup extension supported by the server. + + +ProcXagCreate creates an AppGroup. A new record in a linked list +of AppGroups is allocated and initialized. The attributes from the +request are validated and copied to the AppGroup record. If necessary +an abbreviated version of the connection setup information is compiled +and also stored in the AppGroup record. The first time an AppGroup +is created a client-state-change callback is registered and a +reference count is incremented. + + +ProcXagDestroy destroys an AppGroup an AppGroup by calling +FreeResource specifying the AppGroup ID. This will result in +the destructor function XagAppGroupFree being called. The +reference count is decremented and when it reaches zero the +client-state-change callback is deleted. + + +ProcXagGetAttr returns the AppGroup Attributes to the requesting +client. + + +ProcXagQuery returns the AppGroup ID of an arbitrary resource to +the requesting client. + + +ProcXagCreateAssoc creates an association between an X window ID +and system-specific data. In native X this functionality is +unnecessary but for various personal computers, e.g. Macintosh, +OS/2, and MS-Windows it is necessary to associate an X window ID +with the system's native window identifier so that when the +AppGroup Leader issues a ReparentWindow request the personal +computer X server can lookup the system-specific window ID and +make the necessary function call(s) with it. + + +ProcXagDestroyAssoc destroys the association created with +ProcXagCreateAssoc. + + +XagResetProc removes the client-state-change callback, sets the +reference count to zero, and frees all the AppGroup records in +the linked list by calling XagAppGroupFree. + + +XagAppGroupFree calls CloseDownClient for each client in an +AppGroup if the AppGroup has a leader, unlinks the AppGroup +record from the linked list, frees allocated memory referenced +by the record, and finally frees the record itself. + + + + +Known Problems in this release. + +In a combined UI/Print server the connection setup returned to an +embedded application will not have information about the print +screens. + + +The LBX proxy caches connection setup information and will return +incorrect connection setup information to an embedded client. + + + + -- cgit v1.2.3 From c86700c0c87de8d6ec7f085d06e9a48558bb5118 Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Mon, 2 Aug 2010 13:35:26 -0400 Subject: specs: convert protocol evi.ms from xorg-docs to DocBook XML Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 1 + specs/evi.xml | 518 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 519 insertions(+) create mode 100644 specs/evi.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index af88d05..0848fc6 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -26,6 +26,7 @@ doc_sources = \ appgroup.xml \ dbe.xml \ dpms.xml \ + evi.xml \ security.xml \ shape.xml \ shm.xml \ diff --git a/specs/evi.xml b/specs/evi.xml new file mode 100644 index 0000000..1136278 --- /dev/null +++ b/specs/evi.xml @@ -0,0 +1,518 @@ + + + + + + + + Extended Visual Information Extension + X Project Team Standard + Version 1.0 + + + PeterDaifuku + Silicon Graphics, Inc. + + + X Consortium Standard + 1986-97The Open Group + X Consortium + X Version 11, Release 6.8 + + + + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this +software and associated documentation files (the Software), to use the +Software without restriction, including, without limitation, the rights to +copy, modify, merge, publish, distribute and sublicense the Software, +to make, have made, license and distribute derivative works thereof, and +to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + + + +The above copyright notice and the following permission notice shall be +included in all copies 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 NON- +INFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER USEABILITIY, WHETHER IN AN ACTION OF +CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN +CONNNECTION WITH THE SOFTWARE OR THE USE OF OTHER DEALINGS IN +THE SOFTWARE. + + + +Except as contained in this notice, the name of The Open Group shall not +be used in advertising or otherwise to promote the use or other dealings +in this Software without prior written authorization from The Open Group. + + + +X Window System is a trademark of The Open Group. + + + + + + +TITLE + +Introduction + +EVI (Extended Visual Information extension) allows a client to determine +information about core X visuals beyond what the core protocol provides. + + + + +Goals + +As the X Window System has evolved, it has become clear that the information +returned by the core X protocol regarding Visuals is often insufficient for a +client to determine which is the most appropriate visual for its needs. This +extension allows clients to query the X server for additional visual +information, specifically as regards colormaps and framebuffer levels. + + + +This extension is meant to address the needs of pure X clients only. It is +specifically and purposefully not designed to address the needs of X +extensions. Extensions that have an impact on visual information should provide +their own mechanisms for delivering that information. For example, the Double +Buffering Extension (DBE) provides its own mechanism for determining which +visuals support double-buffering. + + + + +Requests + +GetVersion + + + + + + + + +client_major_version: CARD8 + + + + +client_minor_version: CARD8 + + + + +=> + + + + +server_major_version: CARD8 + + + + +server_minor_version: CARD8 + + + + + + + + + +If supplied, the client_major_version and client_minor_version indicate +what version of the protocol the client wants the server to implement. +The server version numbers returned indicate the protocol this extension +actually supports. This might not equal the version sent by the client. +An implementation can (but need not) support more than one version +simultaneously. The server_major_version and the server_minor_version +are a mechanism to support future revisions of the EVI protocol that +may be necessary. In general, the major version would increment for +incompatible changes, and the minor version would increment for small +upward-compatible changes. Servers that support the protocol defined in +this document will return a server_major_version of one (1), and a +server_minor_version of zero (0). + + + + GetVisualInfo + + + + + + + + +visual_list: LISTofVISUALID + + + + +=> + + + + +per_visual_info: LISTofVISUALINFO + + + + + + + +where: + + + + + + + + +VISUALINFO: [core_visual_id: VISUALID + + + + +screen: CARD8 + + + + +level: INT8 + + + + +transparency_type: CARD8 + + + + +unused: CARD8 + + + + +transparency_value: CARD32 + + + + +min_hw_colormaps: CARD8 + + + + +max_hw_colormaps: CARD8 + + + + +num_colormap_conflicts: CARD16 + + + + +colormap_conflicts: LISTofVISUALID] + + + + + + + + + +level is 0 for normal planes, > 0 for overlays, < 0 for underlays. + + + + +transparency_type is 0 for none, 1 for transparent pixel, 2 for +transparent mask. + + + + +transparency_value: value to get transparent pixel if transparency +supported. + + + + +min_hw_colormaps: minimum number of hardware colormaps backing up the +visual. + + + + +max_hw_colormaps: maximum number of hardware colormaps backing up the +visual. + + + (architectures with static colormap allocation/reallocation would have min += max) + + + + +num_colormap_conflicts: number of elements in colormap_conflicts. + + + + +colormap_conflicts: list of visuals that may conflict with this one. For +example, if a 12-bit colormap is overloaded to support 8-bit visuals, the +8-bit visuals would conflict with the 12-bit visuals. + + + + + + +Events and Errors + +No new events or errors are defined by this extension. + + + + +Changes to existing protocol. + +None. + + + + +Encoding + +The name of this extension is "Extended-Visual-Information". + + + +The conventions used here are the same as those for the core X11 +Protocol Encoding. + + + +GetVersion + 1 CARD8 opcode + 1 0 EVI opcode + 2 2 request length + 2 CARD16 client_major_version + 2 CARD16 client_minor_version +=> + 1 1 reply + 1 unused + 2 CARD16 sequence number + 4 0 length + 2 CARD16 server_major_version + 2 CARD16 server_minor_version + 20 unused + + + +GetVisualInfo + 1 CARD8 opcode + 1 1 EVI opcode + 2 2+n request length + 4 CARD32 n_visual + 4n CARD32 visual_ids +=> + 1 1 reply + 1 unused + 2 CARD16 sequence number + 4 n length + 4 CARD32 n_info + 4 CARD32 n_conflicts + 16 unused + 16n LISTofVISUALINFO items + + + +VISUALINFO + 4 VisualID core_visual_id + 1 INT8 screen + 1 INT8 level + 1 CARD8 transparency_type + 1 CARD8 unused + 4 CARD32 transparency_value + 1 CARD8 min_hw_colormaps + 1 CARD8 max_hw_colormaps + 2 CARD16 num_colormap_conflicts + + + + +C Language Binding + + +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 deleting Xevi +at the start of the function. All functions that have return type Status +will return nonzero for success and zero for failure. + + + +The include file for this extension is: +< X11/extensions/XEVI.h>. + + + + + Bool XeviQueryVersion + Display *display + int *major_version_return + int *minor_version_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + major_version_return + + + +Returns the major version supported by the server. + + + + + + minor_version_return + + + +Returns the minor version supported by the server. + + + + + + +XeviQueryVersion sets major_version_return and minor_version_return to +the major and minor EVI protocol version supported by the server. If +the EVI library is compatible with the version returned by the server, +it returns nonzero. If dpy does not support the EVI 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 +Xevi functions may be called before this function. If a client violates +this rule, the effects of all subsequent Xevi calls that it makes are +undefined. + + + +To get the extended information for any subset of visuals use +XeviGetVisualInfo. + + + + + int XeviGetVisualInfo + Display *display + VisualID *visual + int n_visual + ExtendedVisualInfo **evi_return + int *n_info_return + + + + + + + display + + + +Specifies the connection to the X server. + + + + + + visual + + + +If NULL, then information for all visuals of all +screens is returned. Otherwise, a pointer to a list of visuals for which +extended visual information is desired. + + + + + + n_visual + + + +If 0, then information for all visuals of all screens is returned. Otherwise, +the number of elements in the array visual. + + + + + + evi_return + + + +Returns a pointer to a list of ExtendedVisualInfo. When done, the client +should free the list using XFree. + + + + + + n_info_return + + + +Returns the number of elements in the list of +ExtendedVisualInfo. + + + + + + +XeviGetVisualInfo returns a list of ExtendedVisualInfo structures that describe +visual information beyond that supported by the core protocol. This includes +layer information relevant for systems supporting overlays and/or underlay +planes, and information that allows applications better to determine the level +of hardware support for multiple colormaps. XeviGetVisualInfo returns Success +if successful, or an X error otherwise. + + + + + -- cgit v1.2.3 From 4240526710d837cf06502521ee58c6a4538c6c0e Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Mon, 2 Aug 2010 13:43:32 -0400 Subject: specs: convert protocol buffer.ms from xorg-docs to DocBook XML multibuf.xml Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 1 + specs/multibuf.xml | 1628 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1629 insertions(+) create mode 100644 specs/multibuf.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index 0848fc6..1ca8f35 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -27,6 +27,7 @@ doc_sources = \ dbe.xml \ dpms.xml \ evi.xml \ + multibuf.xml \ security.xml \ shape.xml \ shm.xml \ diff --git a/specs/multibuf.xml b/specs/multibuf.xml new file mode 100644 index 0000000..263d580 --- /dev/null +++ b/specs/multibuf.xml @@ -0,0 +1,1628 @@ + + + + + + + + + Extending X for Double-Buffering, Multi-Buffering, and Stereo + X Version 11, Release 6.4 + + + + JeffreyFriedberg + + + LarrySeiler + + + JeffVroom + + + 1989Digital Equipment Corporation + 1989X Consortium + 1994X Consortium + Version 3.3 + X Consortium + + + +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 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. This document +is subject to change. + + +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. + + +X Window System is a trademark of X Consortium, Inc. + + + + + + +TITLE + +The Multi-Buffering extension described here +was a draft standard of the X Consortium prior to Release 6.1. It has been +superseded by the Double Buffer +Extension (DBE). DBE is an X Consortium Standard as of Release 6.1. + + + +Introduction + + +Several proposals have been written that address some of the +issues surrounding the support of double-buffered, multi-buffered, +and stereo windows in the X Window System: + + + + + +Extending X for Double-Buffering, +Jeffrey Friedberg, Larry Seiler, Randi Rost. + + + + +(Proposal for) Double-Buffering Extensions, +Jeff Vroom. + + + + +An Extension to X.11 for Displays with Multiple Buffers, +David S.H. Rosenthal. + + + + +A Multiple Buffering/Stereo Proposal, +Mark Patrick. + + + + + +The authors of this proposal have tried to unify the above documents +to yield a proposal that incorporates support for double-buffering, +multi-buffering, and stereo in a way that is acceptable to all concerned. + + + + +Goals + + +Clients should be able to: + + + + + +Associate multiple buffers with a window. + + + + +Paint in any buffer associated with a window. + + + + +Display any buffer associated with a window. + + + + +Display a series of buffers in a window in rapid succession +to achieve a smooth animation. + + + + +Request simultaneous display of different buffers in different windows. + + + + + +In addition, the extension should: + + + + + +Allow existing X applications to run unchanged. + + + + +Support a range of implementation methods that can capitalize on +existing hardware features. + + + + + + + +Image Buffers + + +Normal windows are created using the standard +CreateWindow request: + + + +CreateWindow + parent : WINDOW + w_id : WINDOW + depth : CARD8 + visual : VISUALID or CopyFromParent + x, y : INT16 + width, height : INT16 + border_width : INT16 + value_mask : BITMASK + value_list : LISTofVALUE + + + +This request allocates a set of window attributes and +a buffer into which an image can be drawn. +The contents of this image buffer will +be displayed when the window is mapped to the screen. + + + +To support double-buffering and multi-buffering, +we introduce the notion that additional image buffers can +be created and bound together to form groups. +The following rules will apply: + + + + + +All image buffers in a group will have the same +visual type, depth, and geometry (ie: width and height). + + + + +Only one image buffer per group can be displayed +at a time. + + + + +Draw operations can occur to any image buffer at +any time. + + + + +Window management requests (MapWindow, DestroyWindow, +ConfigureWindow, etc...) +affect all image buffers associated with a window. + + + + +Appropriate resize and exposure events will be generated +for every image buffer that is affected by a window +management operation. + + + + + +By allowing draw operations to occur on any image buffer at any time, +a client could, on a multi-threaded multi-processor server, +simultaneously build up images for display. +To support this, each buffer must have its own resource ID. +Since buffers are different than windows and pixmaps +(buffers are not hierarchical and pixmaps cannot be displayed) +a new resource, Buffer, is introduced. +Furthermore, a Buffer is also a Drawable, thus +draw operations may also be performed on buffers simply +by passing a buffer ID to the existing pixmap/window +interface. + + + +To allow existing X applications to work unchanged, we assume +a window ID passed in a draw request, for a multi-buffered +window, will be an alias for the ID of the currently +displayed image buffer. Any draw requests (eq: GetImage) on +the window will be relative to the displayed image buffer. + + + +In window management requests, only a window ID will be +accepted. Requests like QueryTree, will continue to +return only window ID's. Most events will return +just the window ID. Some new events, described in a subsequent +section, will return a buffer ID. + + + +When a window has backing store the contents of the window +are saved off-screen. Likewise, when the contents of an image +buffer of a multi-buffer window is saved off-screen, it is +said to have backing store. This applies to all image buffers, +whether or not they are selected for display. + + + +In some multi-buffer implementations, undisplayed buffers might be +implemented using pixmaps. Since the contents of pixmaps exist +off-screen and are not affected by occlusion, these image buffers +in effect have backing store. + + + +On the other hand, both the displayed and undisplayed image buffers +might be implemented using a subset of the on-screen pixels. +In this case, unless the contents of an image buffer are saved +off-screen, these image buffers in effect do not have backing store. + + + +Output to any image buffer of an unmapped multi-buffered window +that does not have backing store is discarded. Output to any +image buffer of a mapped multi-buffer window will be performed; +however, portions of an image buffer may be occluded or clipped. + + + +When an unmapped multi-buffered window becomes mapped, the contents +of any image buffer buffer that did not have backing store is +tiled with the background and zero or more exposure events are +generated. If no background is defined for the window, then +the screen contents are not altered and the contents of any +undisplayed image buffers are undefined. If backing store was +maintained for an image buffer, then no exposure events are generated. + + + + +New Requests + + +The new request, CreateImageBuffers, creates a group of +image buffers and associates them with a normal X window: + + + +CreateImageBuffers + w_id : WINDOW + buffers : LISTofBUFFER + update_action : {Undefined,Background,Untouched,Copied} + update_hint : {Frequent,Intermittent,Static} + => + number_buffers : CARD16 + + (Errors: Window, IDChoice, Value) + + + +One image buffer will be associated with each ID passed in +buffers. +The first buffer of the list is referred to as buffer[0], the next +buffer[1], and so on. Each buffer will have the same visual type +and geometry as the window. +Buffer[0] will refer to the image buffer already associated +with the window ID and its contents will not be modified. +The displayed image buffer attribute is set to buffer[0]. + + + +Image buffers for the remaining ID's (buffer[1],...) are allocated. +If the window is mapped, or if these image buffers have backing +store, their contents will be tiled with the window background +(if no background is defined, the buffer contents are undefined), +and zero or more expose events will be generated for each of these +buffers. The contents of an image buffer is undefined when +the window is unmapped and the buffer does not have backing store. + + + +If the window already has a group of image buffers +associated with it (ie: from a previous CreateImageBuffers request) +the actions described for DestroyImageBuffers are performed first +(this will delete the association of the previous buffer ID's and +their buffers as well as de-allocate all buffers except for the +one already associated with the window ID). + + + +To allow a server implementation to efficiently allocate the +buffers, the total number of buffers required and +the update action (how they will behave during an update) +is specified "up front" in the request. +If the server cannot allocate all the buffers requested, the +total number of buffers actually allocated will be returned. +No Alloc errors will be generated \- buffer[0] can +always be associated with the existing displayed image buffer. + + + +For example, an application that wants to animate a short movie +loop may request 64 image buffers. The server may only be able to +support 16 image buffers of this type, size, and depth. +The application can then decide 16 buffers is sufficient and may +truncate the movie loop, or it may decide it really needs +64 and will free the buffers and complain to the user. + + + +One might be tempted to provide a request that inquires whether +n +buffers of a particular type, size, and depth +could be allocated. +But if the query is decoupled from the actual allocation, +another client could sneak in and take the buffers before the +original client has allocated them. + + + +While any buffer of a group can be selected for display, +some applications may display buffers in a predictable order +(ie: the movie loop application). The +list order +(buffer[0], buffer[1], ...) will be used as a hint by the +server as to which buffer will be displayed next. +A client displaying buffers in this order may see a +performance improvement. + + + +update_action indicates what should happen to a previously +displayed buffer when a different buffer becomes displayed. +Possible actions are: + + + + + Undefined + + +The contents of the buffer that was +last displayed will become undefined after the update. This +is the most efficient action since it allows the implementation +to trash the contents of the buffer if it needs to. + + + + + Background + + +The contents of the buffer that was +last displayed will be set to the background of the window after the update. +The background action allows devices to use a fast clear +capability during an update. + + + + + Untouched + + +The contents of the buffer that was +last displayed will be untouched after the update. Used +primarily when cycling through images that have already +been drawn. + + + + + Copied + + +The contents of the buffer that was +last displayed will become the same as those that are being +displayed after the update. This is useful when incrementally +adding to an image. + + + + + + + + +update_hint indicates how often the client will +request a different buffer to be displayed. +This hint will allow smart server implementations to choose the +most efficient means to support a multi-buffered window based +on the current need of the application (dumb implementations +may choose to ignore this hint). Possible hints are: + + + + + Frequent + + +An animation or movie loop is +being attempted and the fastest, most efficient means for +multi-buffering should be employed. + + + + + Intermittent + + +The displayed image will be +changed every so often. This is common for images that are +displayed at a rate slower than a second. For example, a +clock that is updated only once a minute. + + + + + Static + + +The displayed image buffer will +not be changed any time soon. Typically set by an application +whenever there is a pause in the animation. + + + + + + +To display an image buffer the following request can be used: + + + +DisplayImageBuffers + buffers : LISTofBUFFER + min_delay : CARD16 + max_delay : CARD16 + + (Errors: Buffer, Match) + + + +The image buffers listed will become displayed as simultaneously +as possible and the update action, bound at +CreateImageBuffers +time, will be performed. + + + +A list of buffers is specified to +allow the server to efficiently change the display of more than one +window at a time (ie: when a global screen swap method is used). +Attempting to simultaneously display +multiple image buffers from the same window is an error +(Match) since it violates the rule that only one +image buffer per group can be displayed at a time. + + + +If a specified buffer is already displayed, +any delays and update action will still be +performed for that buffer. In this instance, +only the update action of Background +(and possibly +Undefined) will have any affect on the +contents of the displayed buffer. These semantics allow +an animation application to successfully execute +even when there is only a single buffer available +for a window. + + + +When a DisplayImageBuffers request is made to an unmapped +multi-buffered window, the effect of the update action depends +on whether the image buffers involved have backing store. +When the target of the update action is an image buffer that +does not have backing store, output is discarded. When the +target image buffer does have backing store, the update is performed; +however, when the source of the update is an image buffer does not +have backing store (as in the case of update action +Copied), the +contents of target image buffer will become undefined. + + + +min_delay and +max_delay put a bound on how long the +server should wait before processing the display request. +For each of the windows to be updated by this request, at least +min_delay milli-seconds should elapse since +the last +time any of the windows were updated; conversely, no window +should have to wait more than max_delay +milli-seconds before being updated. + + + +min_delay allows an application to +slow down an animation or movie loop so that +it appears +synchronized at a rate the server can support given the current load. +For example, a min_delay of 100 indicates the +server should +wait at least 1/10 of a second since the last time any of the +windows were updated. A min_delay of zero +indicates no waiting is necessary. + + + +max_delay can be thought of as an additional +delay beyond min_delay the server is allowed +to wait +to facilitate such things as efficient update of multiple windows. +If max_delay would require an update before +min_delay +is satisfied, then the server should process the display request as +soon as the min_delay requirement is met. A +typical value for max_delay is zero. + + + +To implement the above functionality, the time since the last +update by a DisplayImageBuffers request for each +multi-buffered +window needs to be saved as state by the server. +The server may delay execution of the DisplayImageBuffers +request until the appropriate time (e.g. by requeuing the +request after computing the timeout); +however, the entire request must be processed in one operation. +Request execution indivisibility must be maintained. When +a server is implemented with internal concurrency, the +extension must adhere to the same concurrency semantics +as those defined for the core protocol. + + + +To explicitly clear a rectangular area of an image buffer to +the window background, the following request can be used: + + + +ClearImageBufferArea + buffer : BUFFER + x, y : INT16 + w, h : CARD16 + exposures : BOOL + + (Errors: Buffer, Value) + + + +Like the X ClearArea request, +x and y +are relative to +the window's origin and specify the upper-left corner of the rectangle. +If width is zero, it is replaced with the +current window width +minus x. If +height is zero it is replaced with the current +window height minus y. If the window has a +defined background tile, the rectangle is tiled with a plane mask of all ones, +a function of Copy, and a subwindow-mode of +ClipByChildren. +If the window has background None, the +contents of the buffer +are not changed. In either case, if +exposures is true, then one or +more exposure events are generated for regions of the rectangle that are +either visible or are being retained in backing store. + + + + +The group of image buffers allocated by a +CreateImageBuffers +request can be destroyed with the following request: + + + +DestroyImageBuffers + w_id : WINDOW + + (Error: Window) + + + +The association between the buffer ID's and their corresponding +image buffers are deleted. Any image buffers not selected for +display are de-allocated. If the window is not multi-buffered, +the request is ignored. + + + + + +Attributes + + +The following attributes will be associated with each window that +is multi-buffered: + + + + displayed_buffer : CARD16 + update_action : {Undefined,Background,Untouched,Copied} + update_hint : {Frequent,Intermittent,Static} + window_mode : {Mono,Stereo} + buffers : LISTofBUFFER + + + +displayed_buffer is set to the +index of the currently +displayed image buffer (for stereo windows, this will be +the index of the left buffer \- the index of the right buffer +is simply index+1). +window_mode indicates whether this window is +Mono or Stereo. +The ID for each buffer associated with the window is recorded +in the buffers list. +The above attributes can be queried with the following request: + + + +GetMultiBufferAttributes + w_id : WINDOW + => + displayed_buffer : CARD16 + update_action : {Undefined,Background,Untouched,Copied} + update_hint : {Frequent,Intermittent,Static} + window_mode : {Mono,Stereo} + buffers : LISTofBUFFER + + (Errors: Window, Access, Value) + + + +If the window is not multi-buffered, a Access error +will be generated. +The only multi-buffer attribute that can be explicitly set +is update_hint. Rather than have a specific +request to set this attribute, a generic set request is provided to +allow for future expansion: + + + +SetMultiBufferAttributes + w_id : WINDOW + value_mask : BITMASK + value_list : LISTofVALUE + + (Errors: Window, Match, Value) + + + +If the window is not multi-buffered, a Match error +will be generated. +The following attributes are maintained for each buffer of a +multi-buffered window: + + + + window : WINDOW + event_mask : SETofEVENT + index : CARD16 + side : {Mono,Left,Right} + + + +window indicates the window this buffer is +associated with. +event_mask specifies which events, relevant to +buffers, will be sent back to the client via the associated buffer ID +(initially no events are selected). +index is the list position (0, 1, ...) of the +buffer. +side indicates whether this buffer is +associated with +the left side or right side of a stereo window. +For non-stereo windows, this attribute will be set to +Mono. +These attributes can be queried with the following request: + + + +GetBufferAttributes + buffer : BUFFER + => + window : WINDOW + event_mask : SETofEVENT + index : CARD16 + side : {Mono,Left,Right} + + (Errors: Buffer, Value) + + + +The only buffer attribute that can be explicitly set +is event_mask. +The only events that are valid are +Expose and the new +ClobberNotify and UpdateNotify +event (see Events section below). +A Value error will be generated if an event not +selectable for a buffer is specified in an event mask. +Rather than have a specific request +to set this attribute, a generic set request is provided to +allow for future expansion: + + + +SetBufferAttributes + buffer : BUFFER + value_mask : BITMASK + value_list : LISTofVALUE + + (Errors: Buffer, Value) + + + +Clients may want to query the server about basic multi-buffer +and stereo capability on a per screen basis. The following request +returns a large list of information +that would most likely be read once by Xlib for each screen, and used as a +data base for other Xlib queries: + + + +GetBufferInfo + root : WINDOW + => + info : LISTofSCREEN_INFO + + + +Where SCREEN_INFO and +BUFFER_INFO are defined as: + + + + SCREEN_INFO : [ normal_info : LISTofBUFFER_INFO, + stereo_info : LISTofBUFFER_INFO ] + + BUFFER_INFO : [ visual : VISUALID, + max_buffers : CARD16, + depth : CARD8 ] + + + +Information regarding multi-buffering of normal (mono) windows +is returned in the normal_info list. +The stereo_info +list contains information about stereo windows. +If the stereo_info list is empty, stereo +windows are +not supported on the screen. If +max_buffers is zero, +the maximum number of buffers for the depth and visual is +a function of the size of the created window and current +memory limitations. + + + +The following request returns the major and minor version numbers +of this extension: + + + +GetBufferVersion + => + major_number : CARD8 + minor_number : CARD8 + + + +The version numbers are an escape hatch in case future revisions of +the protocol are necessary. In general, the major version would +increment for incompatible changes, and the minor version would +increment for small upward compatible changes. Barring changes, the +major version will be 1, and the minor version will be 1. + + + + +Events + + +All events normally generated for single-buffered +windows are also generated for multi-buffered windows. +Most of these events (ie: ConfigureNotify) will +only be generated for the window and not for each buffer. +These events will return a window ID. + + + +Expose events will be generated for both the window +and any buffer affected. When this event is generated for +a buffer, the same event structure will be used +but a buffer ID is returned instead of a window ID. +Clients, when processing these events, will know whether an +ID returned in an event structure is for a window or a buffer +by comparing the returned ID to the ones returned when the +window and buffer were created. + + + +GraphicsExposure and +NoExposure are generated +using whatever ID is specified in the graphics operation. +If a window ID is specified, the event will contain the +window ID. If a buffer ID is specified, the event will +contain the buffer ID. + + +In some implementations, moving a window +over a multi-buffered window may cause one or more of its buffers +to get overwritten or become unwritable. To allow a +client drawing into one of these buffers the opportunity +to stop drawing until some portion of the buffer is +writable, the following event is added: + + + +ClobberNotify + buffer : BUFFER + state : {Unclobbered,PartiallyClobbered,FullyClobbered} + + + +The ClobberNotify event is reported to clients selecting +ClobberNotify on a buffer. When a buffer +that was fully +or partially clobbered becomes unclobbered, an event with +Unclobbered +is generated. When a buffer that was unclobbered becomes +partially clobbered, an event with +PartiallyClobbered +is generated. When a buffer that was unclobbered or +partially clobbered becomes fully clobbered, an event with +FullyClobbered is generated. + + + +ClobberNotify events on a given buffer are +generated before any Expose events on that buffer, +but it is not required that all ClobberNotify +events on all buffers be generated before all +Expose events on all buffers. + + + +The ordering of ClobberNotify events with respect +to VisibilityNotify events is not constrained. + + + +If multiple buffers were used as an image FIFO between an image +server and the X display server, then the FIFO manager would like +to know when a buffer that was previously displayed, has been +undisplayed and updated, as the side effect of a +DisplayImageBuffers +request. This allows the FIFO manager to load up a future frame as +soon as a buffer becomes available. To support this, +the following event is added: + + + +UpdateNotify + buffer : BUFFER + + + +The UpdateNotify event is reported to clients selecting +UpdateNotify on a buffer. Whenever a buffer +becomes updated +(e.g. its update action is performed as part of a +DisplayImageBuffers +request), an UpdateNotify event is generated. + + + + +Errors + + +The following error type has been added to support +this extension: + + + +Buffer + +A value for a BUFFER argument does not name a defined BUFFER. + + + + +Double-Buffering Normal Windows + + +The following pseudo-code fragment illustrates how to create and display +a double-buffered image: + + + +/* + * Create a normal window + */ +CreateWindow( W, ... ) + +/* + * Create two image buffers. Assume after display, buffer + * contents become "undefined". Assume we will "frequently" + * update the display. Abort if we don't get two buffers, + */ +n = CreateImageBuffers( W, [B0,B1], Undefined, Frequent ) +if (n != 2) <abort> + +/* + * Map window to the screen + */ +MapWindow( W ) + +/* + * Draw images using alternate buffers, display every + * 1/10 of a second. Note we draw B1 first so it will + * "pop" on the screen + */ +while animating +{ + <draw picture using B1> + DisplayImageBuffers( [B1], 100, 0 ) + + <draw picture using B0> + DisplayImageBuffers( [B0], 100, 0 ) +} + +/* + * Strip image buffers and leave window with + * contents of last displayed image buffer. + */ +DestroyImageBuffers( W ) + + + + + +Multi-Buffering Normal Windows + + +Multi-buffered images are also supported by these requests. +The following pseudo-code fragment illustrates how to create a +a multi-buffered image and cycle through the images to +simulate a movie loop: + + + +/* + * Create a normal window + */ +CreateWindow( W, ... ) + +/* + * Create 'N' image buffers. Assume after display, buffer + * contents are "untouched". Assume we will "frequently" + * update the display. Abort if we don't get all the buffers. + */ +n = CreateImageBuffers( W, [B0,B1,...,B(N-1)], Untouched, Frequent ) +if (n != N) <abort> + +/* + * Map window to screen + */ +MapWindow( W ) + +/* + * Draw each frame of movie one per buffer + */ +foreach frame + <draw frame using B(i)> + +/* + * Cycle through frames, one frame every 1/10 of a second. + */ +while animating +{ + foreach frame + DisplayImageBuffers( [B(i)], 100, 0 ) +} + + + + + +Stereo Windows + +How stereo windows are supported on a server +is implementation +dependent. A server may contain specialized hardware that allows +left and right images to be toggled at field or frame rates. The +stereo affect may only be perceived with the aid of special +viewing glasses. The display of a +stereo picture should +be independent of how often the contents of the picture are +updated by an application. Double and +multi-buffering +of images should be possible regardless of whether the image +is displayed normally or in stereo. + + + +To achieve this goal, a simple extension to normal windows +is suggested. Stereo windows are just like normal windows +except the displayed image is made up of a left image +buffer and a right image buffer. To create a stereo window, +a client makes the following request: + + + +CreateStereoWindow + parent : WINDOW + w_id : WINDOW + left, right : BUFFER + depth : CARD8 + visual : VISUALID or CopyFromParent + x, y : INT16 + width, height : INT16 + border_width : INT16 + value_mask : BITMASK + value_list : LISTofVALUE + + (Errors: Alloc, Color, Cursor, Match, + Pixmap, Value, Window) + + + +This request, modeled after the CreateWindow request, +adds just two new parameters: left and +right. +For stereo, it is essential that one can distinguish whether +a draw operation is to occur on the left image or right image. +While an internal mode could have been added to achieve this, +using two buffer ID's allows clients to simultaneously build up +the left and right components of a stereo image. These +ID's always refer to (are an alias for) the left and right +image buffers that are currently displayed. + + + +Like normal windows, the window ID is used whenever a window +management operation is to be performed. Window queries would +also return this window ID (eg: QueryTree) as would most +events. Like the window ID, the left and right buffer ID's +each have their own event mask. They can be set and queried +using the Set/GetBufferAttributes requests. + + + +Using the window ID of a stereo window in a draw request +(eg: GetImage) results in pixels that are +undefined. +Possible semantics are that both left and right images get +drawn, or just a single side is operated on (existing applications +will have to be re-written to explicitly use the left and right +buffer ID's in order to successfully create, fetch, and store +stereo images). + + + +Having an explicit CreateStereoWindow request is helpful +in that a server implementation will know from the onset whether +a stereo window is desired and can return appropriate status +to the client if it cannot support this functionality. + + + +Some hardware may support separate stereo and non-stereo modes, +perhaps with different vertical resolutions. For example, the +vertical resolution in stereo mode may be half that of non-stereo +mode. Selecting one mode or the other must be done through some +means outside of this extension (eg: by providing a separate +screen for each hardware display mode). The screen attributes +(ie: x/y resolution) for a screen that supports normal windows, +may differ from a screen that supports stereo windows; +however, all windows, regardless of type, displayed on the +same screen must have the same screen attributes +(ie: pixel aspect ratio). + + + +If a screen that supports stereo windows also supports +normal windows, then the images presented to the left and +right eyes for normal windows should be the same +(ie: have no stereo offset). + + + + + +Single-Buffered Stereo Windows + + +The following shows how to create and display a single-buffered +stereo image: + + +/* + * Create the stereo window, map it the screen, + * and draw the left and right images + */ +CreateStereoWindow( W, L, R, ... ) + +MapWindow( W ) + +<draw picture using L,R> + + + + +Double-Buffering Stereo Windows + + +Additional image buffers may be added to a stereo window +to allow double or multi-buffering of stereo images. +Simply use the the CreateImageBuffers request. +Even numbered buffers (0,2,...) will be left buffers. +Odd numbered buffers (1,3,...) will be right buffers. +Displayable stereo images are formed by consecutive +left/right pairs of image buffers. For example, +(buffer[0],buffer[1]) form the first displayable +stereo image; (buffer[2],buffer[3]) the next; +and so on. + + + +The CreateImageBuffers request will only create +pairs of left and right image buffers for stereo windows. +By always pairing left and right image +buffers together, implementations might be able to +perform some type of optimization. If an odd number +of buffers is specified, a Value error is generated. +All the rules mentioned at the start of this proposal +still apply to the image buffers supported by a stereo window. + + + +To display a image buffer pair of a multi-buffered stereo image, +either the left buffer ID or right buffer ID may be specified in a +DisplayImageBuffers request, but not both. + + + +To double-buffer a stereo window: + + + +/* + * Create stereo window and map it to the screen + */ +CreateStereoWindow( W, L, R, ... ) + +/* + * Create two pairs of image buffers. Assume after display, + * buffer contents become "undefined". Assume we will "frequently" + * update the display. Abort if we did get all the buffers. + */ +n = CreateImageBuffers( W, [L0,R0,L1,R1], Undefined, Frequently ) +if (n != 4) <abort> + +/* + * Map window to the screen + */ +MapWindow( W ) + +/* + * Draw images using alternate buffers, + * display every 1/10 of a second. + */ +while animating +{ + <draw picture using L1,R1> + DisplayImageBuffers( [L1], 100, 0 ) + + <draw picture using L0,R0> + DisplayImageBuffers( [L0], 100, 0 ) +} + + + + + +Multi-Buffering Stereo Windows + + +To cycle through N stereo images: + + + +/* + * Create stereo window + */ +CreateStereoWindow( W, L, R, ... ) + +/* + * Create N pairs of image buffers. Assume after display, + * buffer contents are "untouched". Assume we will "frequently" + * update the display. Abort if we don't get all the buffers. + */ +n = CreateImageBuffers( W, [L0,R0,...,L(N-1),R(N-1)], Untouched, Frequently ) +if (n != N*2) <abort> + +/* + * Map window to screen + */ +MapWindow( W ) + +/* + * Draw the left and right halves of each image + */ +foreach stereo image + <draw picture using L(i),R(i)> + +/* + * Cycle through images every 1/10 of a second + */ +while animating +{ + foreach stereo image + DisplayImageBuffers( [L(i)], 100, 0 ) +} + + + + +Protocol Encoding + + +The official name of this extension is "Multi-Buffering". +When this string passed to QueryExtension the +information returned should be interpreted as follows: + + + + + major-opcode + + +Specifies the major opcode of this extension. +The first byte of each extension request should +specify this value. + + + + + first-event + + +Specifies the code that will be returned when +ClobberNotify events are generated. + + + + + first-error + + +Specifies the code that will be returned when +Buffer errors are generated. + + + + + + +The following sections describe the protocol +encoding for this extension. + + + + + +TYPES + + +BUFFER_INFO + +4 VISUALID visual +2 CARD16 max-buffers +1 CARD8 depth +1 unused + + + +SETofBUFFER_EVENT + + #x00008000 Exposure + #x02000000 ClobberNotify + #x04000000 UpdateNotify + + + + + +EVENTS + + +ClobberNotify +1 see first-event code +1 unused +2 CARD16 sequence number +4 BUFFER buffer +1 state + 0 Unclobbered + 1 PartiallyClobbered + 2 FullyClobbered +23 unused + + + +UpdateNotify +1 first-event+1 code +1 unused +2 CARD16 sequence number +4 BUFFER buffer +24 unused + + + + +ERRORS + + +Buffer +1 0 Error +1 see first-error code +2 CARD16 sequence number +4 CARD32 bad resource id +2 CARD16 minor-opcode +1 CARD8 major-opcode +21 unused + + + + + +REQUESTS + + +GetBufferVersion +1 see major-opcode major-opcode +1 0 minor-opcode +2 1 request length +-> +1 1 Reply +1 unused +2 CARD16 sequencenumber +4 0 reply length +1 CARD8 majorversion number +1 CARD8 minorversion number +22 unused + + +CreateImageBuffers + +1 see major-opcode major-opcode +1 1 minor-opcode +2 3+n requestlength +4 WINDOW wid +1 update-action + 0 Undefined + 1 Background + 2 Untouched + 3 Copied +1 update-hint + 0 Frequent + 1 Intermittent + 2 Static +2 unused +4n LISTofBUFFER buffer-list +-> +1 1 Reply +1 unused +2 CARD16 sequencenumber +4 0 reply length +2 CARD16 number-buffers +22 unused + + +DestroyImageBuffers + +1 see major-opcode major-opcode +1 2 minor-opcode +2 2 request length +4 WINDOW wid + + +DisplayImageBuffers + + +1 see major-opcode major-opcode +2 2+n requestlength +2 CARD16 min-delay +2 CARD16 max-delay +4n LISTofBUFFER buffer-list + + +SetMultiBufferAttributes + +1 see major-opcode major-opcode +1 4 minor-opcode +2 3+n requestlength +4 WINDOW wid +4 BITMASK value-mask (has n bits set to 1) + #x00000001 update-hint +4n LISTofVALUE value-list +VALUEs +1 update-hint + 0 Frequent + 1 Intermittent + 2 Static + + +GetMultiBufferAttributes + +1 see major-opcode major-opcode +1 5 minor-opcode +2 2 request length +4 WINDOW wid +® +1 1 Reply +1 unused +2 CARD16 sequencenumber +4 n reply length +2 CARD16 displayed-buffer +1 update-action + 0 Undefined + 1 Background + 2 Untouched + 3 Copied +1 update-hint + 0 Frequent + 1 Intermittent + 2 Static +1 window-mode + 0 Mono + 1 Stereo +19 unused +4n LISTofBUFFER buffer list + + +SetBufferAttributes + +1 see major-opcode major-opcode +1 6 minor-opcode +2 3+n requestlength +4 BUFFER buffer +4 BITMASK value-mask (has n bits set to 1) + #x00000001 event-mask +4n LISTofVALUE value-list +VALUEs +4 SETofBUFFER_EVENT event-mask + +GetBufferAttributes + +1 see major-opcode major-opcode +1 7 minor-opcode +2 2 request length +4 BUFFER buffer +-> +1 1 Reply +1 unused +2 CARD16 sequencenumber +4 0 reply length +4 WINDOW wid +4 SETofBUFFER_EVENT event-mask +2 CARD16 index + 1 side + 0 Mono + 1 Left + 2 Right +13 unused + +GetBufferInfo + +1 see major-opcode major-opcode +1 8 minor-opcode +2 2 request length +4 WINDOW root +® +1 1 Reply +1 unused +2 CARD16 sequencenumber +4 2(n+m) replylength +2 n number BUFFER_INFO in normal-info +2 m number BUFFER_INFO in stereo-info +20 unused +8n LISTofBUFFER_INFO normal-info +8m LISTofBUFFER_INFO stereo-info + +CreateStereoWindow + +1 see major-opcode major-opcode +1 9 minor-opcode +2 11+n requestlength +3 unused +1 CARD8 depth +4 WINDOW wid +4 WINDOW parent +4 BUFFER left +4 BUFFER right +2 INT16 x +2 INT16 y +2 CARD16 width +2 CARD16 height +2 CARD16 border-width +2 class + 0 CopyFromParent + 1 InputOutput + 2 InputOnly +4 VISUALID visual + 0 CopyFromParent +4 BITMASK value-mask (has n bits set to 1) + encodings are the same + as for CreateWindow +4n LISTofVALUE value-list + encodings are the same + as for CreateWindow + + +ClearImageBufferArea + +1 see major-opcode major-opcode +1 10 minor-opcode +2 5 request length +4 WINDOW buffer +2 INT16 x +2 INT16 y +2 CARD16 width +2 CARD16 height +3 unused +1 BOOL exposures + + + + + + -- cgit v1.2.3 From 260da6ca1dec9abde11c064d0aeac01f695a1596 Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Mon, 2 Aug 2010 15:10:04 -0400 Subject: specs: convert protocol xtest.ms from xorg-docs to DocBook XML Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 3 +- specs/xtest.xml | 722 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 724 insertions(+), 1 deletion(-) create mode 100644 specs/xtest.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index 1ca8f35..a1acb2e 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -32,7 +32,8 @@ doc_sources = \ shape.xml \ shm.xml \ sync.xml \ - tog-cup.xml + tog-cup.xml \ + xtest.xml dist_doc_DATA = $(doc_sources) geproto.txt diff --git a/specs/xtest.xml b/specs/xtest.xml new file mode 100644 index 0000000..6da29f1 --- /dev/null +++ b/specs/xtest.xml @@ -0,0 +1,722 @@ + + + + + + + XTEST Extension Protocol + X Consortium Standard + Version 2.2 + + + KieronDrake + UniSoft Ltd. + + + 1992UniSoft Group Ltd. + 1992,1994X Consortium + + + +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. UniSoft 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. + + + +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. + + + + + + +TITLE + + +Overview + +This extension is a minimal set of client and server extensions +required to completely test the X11 server with no user intervention. + + + +This extension is not intended to support general journaling and +playback of user actions. This is a difficult area [XTrap, 89] as it attempts +to synchronize synthetic user interactions with their effects; it is at the +higher level of dialogue recording/playback rather than at the strictly lexical +level. We are interested only in the latter, simpler, case. A more detailed +discussion and justification of the extension functionality is given in +[Drake, 91]. + + + +We are aiming only to provide a minimum set of facilities that +solve immediate testing and validation problems. The testing extension +itself needs testing, where possible, and so should be as simple as possible. + + + +We have also tried to: + + + + + +Confine the extension to an appropriate high level within the server +to minimize portability problems. In practice this means that the extension +should be at the DIX level or use the DIX/DDX interface, or both. This +has effects, in particular, on the level at which "input synthesis" +can occur. + + + + +Minimize the changes required in the rest of the server. + + + + +Minimize performance penalties on normal server operation. + + + + + + +Description + +The functions provided by this extension fall into two groups: + + + + + Client Operations + + +These routines manipulate otherwise hidden client-side behavior. The +actual implementation will depend on the details of the actual language +binding and what degree of request buffering, GContext caching, and so on, is +provided. +In the C binding, defined in "XTEST Extension Library", routines are +provided to access the internals of two opaque data structures +-- GCs +and +Visuals -- +and to discard any requests pending within the +output buffer of a connection. The exact details can be expected to differ for +other language bindings. + + + + + Server Requests + + +The first of these requests is similar to that provided in most +extensions: it allows a client to specify a major and minor version +number to the server and for the server to respond with major and minor +versions of its own. The remaining two requests allow the following: + + + + + +Access to an otherwise "write-only" server resource: the cursor +associated with a given window + + + + +Perhaps most importantly, limited synthesis of input device events, +almost as if a cooperative user had moved the pointing device +or pressed a key or button. + + + + + + + + + + +Types + +The following types are used in the request and event definitions in +subsequent sections: + + + + + + + + + +FAKE_EVENT_TYPE +{ KeyPress, +KeyRelease, +MotionNotify, +ButtonPress, +ButtonRelease } + + + + + + + FAKE_EVENT + [type: FAKE_EVENT_TYPE, + + + + detail: BYTE, + + + + time: TIME, + + + + root: WINDOW, + + + + rootX, rootY: INT16] + + + + + + +CURSOR { CurrentCursor, None } +or a cursor as defined by the X11 Protocol. + + + + + +Client Operations + + +These are abstract definitions of functionality. They refer to client-side +objects such as "GC" and "VISUAL" that are quoted to +denote their abstract nature. Concrete versions of these functions are +defined only for particular language bindings. In some circumstances +a particular language binding may not implement the relevant abstract +type or may provide it as a transparent, rather than opaque, type, with +the result that the corresponding function does not make sense or is +not required, respectively. + + + +XTestSetGContextOfGC + + + + + + + + +gc: "GC" + + + + +gid: GCONTEXT + + + + + + + +Sets the GCONTEXT within the "GC" gc to have +the value specified by gid. + + + +XTestSetVisualIDOfVisual + + + + + + + + +visual: "VISUAL" + + + + +visualid: VISUALID + + + + + + + +Sets the VISUALID within the "VISUAL" visual to have +the value specified by visualid. + + + +XTestDiscard + + + + + + + + +dpy: "CONNECTION" + + + + +=> + + + + +status: BOOL + + + + + + + +Discards any requests that are present in the request buffer associated with +the "CONNECTION" dpy. +The status returned is +True +if there were one or more requests +in the buffer and +False +otherwise. + + + + +Server Requests + +XTestGetVersion + + + + + + + + +clientMajorVersion: CARD16 + + + + +clientMinorVersion: CARD16 + + + + + => + + + + +serverMajorVersion: CARD16 + + + + +serverMinorVersion: CARD16 + + + + +Errors: Length + + + + + + + + +This request can be used to ensure that the server version of the XTEST +extension is usable by the client. This document defines major version two +(2), minor version one (1). + + + +XTestCompareCursor + + + + + + + + +window: WINDOW + + + + +cursor-id: CURSOR or +CurrentCursor +or +None + + + + +=> + + + + +same: BOOL + + + + +Errors: +Window, +Length, +Cursor + + + + + + + +This request looks up the cursor associated with the window and +compares it with either the null cursor if cursor-id is +None , +or the current cursor (that is, the one being displayed), +or the cursor whose ID is cursor-id, and returns +the result of the comparison in same. + + + +XTestFakeInput + + + + + + + + +events: LISTofFAKE_EVENT + + + + +Errors: +Window, +Length, +Alloc, +Value + + + + + + + +This request simulates the limited set of core protocol +events within the set FAKE_EVENT_TYPE. Only the following event fields, +defined in FAKE_EVENT, are interpreted: + + + + + + type + + + +This must be one of +KeyPress, +KeyRelease, +MotionNotify, +ButtonPress, +or +ButtonRelease, +or else a +Value +error occurs. + + + + + + detail + + + +For key events, this field is interpreted as the physical keycode. +If the keycode is less than min-keycode or greater than max-keycode, +as returned in the connection setup, then a +Value +error occurs. +For button events, this field is interpreted as the physical (or core) button, +meaning it will be mapped to the corresponding logical button according to +the most recent +SetPointerMapping +request. +If the button number is less than one or greater than the number of physical +buttons, then a +Value +error occurs. +For motion events, if this field is +True , +then rootX and rootY +are relative distances from the current pointer location; if this field is +False, +then they are absolute positions. + + + + + + time + + + +This is either +CurrentTime +(meaning no delay) +or the delay in milliseconds that the server should wait before +simulating this event. No other requests from this client will be +processed until this delay, if any, has expired and subsequent processing +of the simulated event has been completed. + + + + + + root + + + +In the case of motion events this field is the ID of the root window on +which the new motion is to take place. If +None +is specified, the root window of the screen the pointer is currently on +is used instead. +If this field is not a valid window, then a +Window +error occurs. + + + + + + rootX & + rootY + + + +In the case of motion events these fields indicate relative distance or +absolute pointer coordinates, according to the setting of detail. +If the specified coordinates are off-screen, the closest on-screen +coordinates will be substituted. + + + + + + +When the simulated event(s) are processed, they cause event propagation, +passive grab activation, and so on, just as if the corresponding input device +action had occurred. However, motion events might not be recorded in the +motion history buffer. + + + +For the currently supported event types, the event list must have length one, +otherwise a +BadLength +error occurs. + + + +XTestGrabControl + + + + + + + + +impervious: BOOL + + + + + + + +If impervious is +True, +then the executing client becomes impervious to server grabs; +that is, it can continue executing requests even if another client +grabs the server. +If impervious is +False, +then the executing client returns to the normal state of being +susceptible to server grabs. + + + + +Encoding + +Please refer to the X11 Protocol Encoding document as this document uses +conventions established there. + + + +The name of this extension is "XTEST". + + + +New Types + +FAKE_EVENT_TYPE + 2 KeyPress + 3 KeyRelease + 4 ButtonPress + 5 ButtonRelease + 6 MotionNotify + + + +NOTE that the above values are defined to be the same as those for +the corresponding core protocol event types. + + + + +Requests + + +XTestGetVersion + 1 CARD8 opcode + 1 0 xtest opcode + 2 2 request length + 1 CARD8 client major version + 1 unused + 2 CARD16 client minor version +=> + 1 1 Reply + 1 CARD8 server major version + 2 CARD16 sequence number + 4 0 reply length + 2 CARD16 server minor version + 22 unused + + + +XTestCompareCursor + 1 CARD8 opcode + 1 1 xtest opcode + 2 3 request length + 4 WINDOW window + 4 CURSOR cursor-id + 0 None + 1 CurrentCursor +=> + 1 1 Reply + 1 BOOL cursors are the same + 2 CARD16 sequence number + 4 0 reply length + 24 unused + + + +XTestFakeInput + 1 CARD8 opcode + 1 2 xtest opcode + 2 1+(1*8) request length + 1 FAKE_EVENT_TYPE fake device event type + 1 BYTE detail: button or keycode + 2 unused + 4 TIME delay (milliseconds) + 0 CurrentTime + 4 WINDOW root window for MotionNotify + 0 None + 8 unused + 2 INT16 x position for MotionNotify + 2 INT16 y position for MotionNotify + 8 unused + + + +XTestGrabControl + 1 CARD8 opcode + 1 3 xtest opcode + 2 2 request length + 1 BOOL impervious + 3 unused + + + + + +References + +Annicchiarico, D., et al., +XTrap: The XTrap Architecture. +Digital Equipment Corporation, July 1991. + + + +Drake, K. J., +Some Proposals for a +Minimum X11 Testing Extension. +UniSoft Ltd., June 1991. + + + + -- cgit v1.2.3 From 35741d9dc745532dc4af37cc07e256392e3880da Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Tue, 3 Aug 2010 11:03:49 -0400 Subject: specs: convert protocol geproto.txt to DocBook XML Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 3 +- specs/geproto.txt | 84 ----------------------------------------------- specs/geproto.xml | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 99 insertions(+), 85 deletions(-) delete mode 100644 specs/geproto.txt create mode 100644 specs/geproto.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index a1acb2e..3e631a1 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -27,6 +27,7 @@ doc_sources = \ dbe.xml \ dpms.xml \ evi.xml \ + geproto.xml \ multibuf.xml \ security.xml \ shape.xml \ @@ -35,7 +36,7 @@ doc_sources = \ tog-cup.xml \ xtest.xml -dist_doc_DATA = $(doc_sources) geproto.txt +dist_doc_DATA = $(doc_sources) if HAVE_XMLTO doc_DATA = $(doc_sources:.xml=.html) diff --git a/specs/geproto.txt b/specs/geproto.txt deleted file mode 100644 index 1054def..0000000 --- a/specs/geproto.txt +++ /dev/null @@ -1,84 +0,0 @@ - X Generic Event Extension - Peter Hutterer - peter.hutterer@who-t.net - - -1. Introduction -2. Extension Initialization -3. Events -4. Notes - -_____________________________________________________________________________ -1. Introduction - -X was designed to provide 64 event opcodes for all extensions. These events -are limited to 32 bytes. - -The Generic Event Extension provides a template event for extensions to re-use -a single event opcode. GE only provide headers and the most basic -functionality, leaving the extensions to interpret the events in their -specific context. - -GenericEvents may be longer than 32 bytes. If so, the number of 4 byte units -following the initial 32 bytes must be specified in the length field of the -event. -_____________________________________________________________________________ -2. Extension Initialization - -The name of this extension is "Generic Event Extension" - -┌─── - GEQueryVersion - client-major-version: CARD16 - client-minor-version: CARD16 - â–¶ - major-version: CARD16 - minor-version: CARD16 -└─── - - 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. - - - As of version 1.0, no other requests are provided by this extension. -_____________________________________________________________________________ -3. Events - -GE defines a single event, to be used by all extensions. The event's structure -is similar to a reply. This is a core protocol event, ID 35, and is not itself -an extension event. - -┌─── - GenericEvent - type: BYTE; always GenericEvent (35) - extension: CARD8; extension offset - sequenceNumber: CARD16 low 16 bits of request seq. number - length: CARD32 length - evtype: CARD16 event type -└─── - - The field 'extension' is to be set to the major opcode of the - extension. The 'evtype' field is the actual opcode of the event. - The length field specifies the number of 4-byte blocks after the - initial 32 bytes. If length is 0, the event is 32 bytes long. -_____________________________________________________________________________ -4. Notes - -Although the wire event is of arbitrary length, the actual size of an XEvent -is restricted to sizeof(XEvent) [96 bytes, see Xlib.h]. If an extension -converts a wire event to an XEvent > 96 bytes, it will overwrite the space -allocated for the event. See struct _XSQEvent in Xlibint.h for details. - -Extensions need to malloc additional data and fill the XEvent structure with -pointers to the malloc'd data. The client then needs to free the data, only -the XEvent structure will be released by Xlib. - -The server must not send GenericEvents longer than 32 bytes until it has -verified that the client is able to interpret these events. If a long event is -sent to a client unable to process GenericEvents, future interpretation of -replies and events by this client will fail. diff --git a/specs/geproto.xml b/specs/geproto.xml new file mode 100644 index 0000000..7bba357 --- /dev/null +++ b/specs/geproto.xml @@ -0,0 +1,97 @@ + + + + + X Generic Event Extension + + + Peter + + Hutterer + + + peter.hutterer@who-t.net + + + + + + Introduction + + X was designed to provide 64 event opcodes for all extensions. These + events are limited to 32 bytes. + + The Generic Event Extension provides a template event for extensions + to re-use a single event opcode. GE only provide headers and the most + basic functionality, leaving the extensions to interpret the events in + their specific context. + + GenericEvents may be longer than 32 bytes. If so, the number of 4 + byte units following the initial 32 bytes must be specified in the length + field of the event. + + + + Extension Initialization + + The name of this extension is "Generic Event Extension" + + GEQueryVersion + client-major-version: CARD16 + client-minor-version: CARD16 +==> + major-version: CARD16 + minor-version: CARD16 + + 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. + + As of version 1.0, no other requests are provided by this extension. + + + + + Events + + GE defines a single event, to be used by all extensions. The event's + structure is similar to a reply. This is a core protocol event, ID 35, and + is not itself an extension event. + + GenericEvent + type: BYTE always GenericEvent (35) + extension: CARD8 extension offset + sequenceNumber: CARD16 low 16 bits of request seq. number + length: CARD32 length + evtype: CARD16 event type + + The field 'extension' is to be set to the major opcode of the + extension. The 'evtype' field is the actual opcode of the event. The + length field specifies the number of 4-byte blocks after the initial 32 + bytes. If length is 0, the event is 32 bytes long. + + + + Notes + + Although the wire event is of arbitrary length, the actual size of + an XEvent is restricted to sizeof(XEvent) [96 bytes, see Xlib.h]. If an + extension converts a wire event to an XEvent > 96 bytes, it will + overwrite the space allocated for the event. See struct _XSQEvent in + Xlibint.h for details. + + Extensions need to malloc additional data and fill the XEvent + structure with pointers to the malloc'd data. The client then needs to + free the data, only the XEvent structure will be released by Xlib. + + The server must not send GenericEvents longer than 32 bytes until it + has verified that the client is able to interpret these events. If a long + event is sent to a client unable to process GenericEvents, future + interpretation of replies and events by this client will fail. + + -- cgit v1.2.3 From 5508eec058c0ffbb180f3d98f8a02083d6de428b Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Thu, 9 Sep 2010 16:41:21 -0400 Subject: Remove the appgroup specs which is the one for the server side. The spec for the protocol side is still in Framemaker format. See doc/xorg-docs/specs/Xext/AppGroup.mif Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 1 - specs/appgroup.xml | 248 ----------------------------------------------------- 2 files changed, 249 deletions(-) delete mode 100644 specs/appgroup.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index 3e631a1..21e5fba 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -23,7 +23,6 @@ if ENABLE_SPECS doc_sources = \ - appgroup.xml \ dbe.xml \ dpms.xml \ evi.xml \ diff --git a/specs/appgroup.xml b/specs/appgroup.xml deleted file mode 100644 index eebf843..0000000 --- a/specs/appgroup.xml +++ /dev/null @@ -1,248 +0,0 @@ - - - - - - - - Description of the Application Group Extension - Implementation for the X11 Sample Server - Version 1.0 - - - Kaleb KEITHLEY - FUJITSU Limited. - blah@blah.com - - - X Consortium Standard - 1996X Consortium - X Consortium - X Version 11, Release 7 - - - -The following document explains the server side of the Application -Group Extension. - - - - - - - -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. - - - -The following document explains the server side of the Application -Group Extension. - - - -WindowsNT is a trademark of Microsoft, Inc. Macintosh and Apple -are trademarks of Apple Computer, Inc. X Window System is a -trademark of X Consortium, Inc. - - - - - -TITLE - -To understand this document and the accompanying source code, you -should know the C language, should be familiar with X server -internals, and should also have a general knowledge of the X -Window System. - - - -AppGroup Server Public Functions - -The AppGroup extension adds seven new functions that are called -from elsewhere in the server. They are: XagExtensionInit, -XagDefaultColormap, XagRootVisual, XagLeader, XagIsControlledRoot, -XagConnectionInfo, XagCallClientStateChange. - - -XagExtensionInit is the extension initialization function called -from InitExtension in mi/miinitext.c. Note that an new resource -type, RT_APPGROUP, is created, specifying the destructor function -XagAppGroupFree. - - -XagDefaultColormap returns the colormap ID that was specified in -the creation of the AppGroup. Any time CopyFromParent is specified -for a top-level window's colormap, i.e. in a CreateWindow or -ChangeWindowAttributes request, this function is called to see -if there is an AppGroup specific colormap to use. If there is -one, its ID is returned, otherwise None is returned. - - -XagRootVisual returns the visual ID that was specified in the -creation of the Appgroup. Like XagDefaultColormap, when CopyFromParent -is specified for a top-level window's visual in a CreateWindow -request, this function is called to see if there is an AppGroup -specific visual to use. If there is one, its ID is returned, -otherwise 0 (zero) is returned. - - -XagLeader returns the ClientPtr of the client that is the AppGroup -Leader. Normally when an application maps or configures a top-level -window a MapRequest or ConfigureRequest event is delivered to the -client, e.g. a window manager, that has selected SubstructureRedirect -on the root window. However, when the application is part of an -AppGroup, the MapRequest and ConfigureRequest events are delivered -to the AppGroup Leader instead. - - -XagIsControlledRoot returns a boolean: True if the window is a -top-level window of a client in an AppGroup, False otherwise. -In a combined server, i.e. one that provides both UI and printing, -the application may create and map windows on the "printing" -screens; thus it becomes necessary to discriminate between the -AppGroup's root window and other root windows. If an AppGroup -member creates and maps a [top-level] window then the window's -parent [the root window] is tested to determine whether to send -MapRequest or ConfigureRequest events to the AppGroup Leader to -to some other client. - - -In the trivial case XagIsControlledRoot returns True if the parent -window has no parent itself, i.e. it is a root window. In the case -where the application is embedded, indicated by the singleScreen -attribute being True, the parent's drawable ID is compared to the -AppGroup's root window ID, and if it is the same, True is returned. -If neither case is true, then False is returned. - - -XagConnectionInfo returns an abreviated version of the connection -setup information. When an embedded AppGroup is created the server -returns only the information about the [UI] screen that the -application is embedded within in the connection setup in order to -prevent the application from creating windows on other screens; -thus attempting to guarantee that any window that should be embedded -can be reparented into the AppGroup Leader's window hierarchy. - - -XagCallClientStateChange is called to invoke the extension's client -state change callback additional times as necessary -- currently -only once, after the auth data becomes available between -ClientStateInitial and ClientStateConnected. Client state change -callbacks were introduced in the Record extension, which specifies -when the callbacks are invoked. Unfortunately the points at which -they are called are not necessarily the best as far as the AppGroup -Extension is concerned. Adding an additional state and calling all -the callbacks works too, however this seemed unnecessary overkill. - - - - -AppGroup Server Private APIs - -The AppGroup extension adds the following functions which are -private to the extension: ProcXagDispatch and SProcXagDispatch, -ProcXagQueryVersion and SProcXagQueryVersion, ProcXagCreate and -SProcXagCreate, ProcXagDestroy and SProcXagDestroy, -ProcGetAttr and SProcGetAttr, ProcXagQuery and SProcXagQuery, -ProcXagCreateAssoc and SProcXagCreateAssoc, ProcXagDestroyAssoc -and SProcXagDestroyAssoc, XagResetProc, and XagAppGroupFree. - - -The ProcXagDispatch, SProcXagDispatch, and XagResetProc functions -should be familiar to anyone familiar with X server internals and -I won't elaborate on them here. Similarly the wrapper functions: -SProcXagQueryVersion, SProcXagCreate, SProcXagDestroy, SProcXagGetAttr, -SProcXagQuery, SProcXagCreateAssoc, and SProcXagDestroyAssoc, as -wrappers which handle swapping integer data into the host's byte -order will not be explained in any detail. - - -ProcXagQueryVersion returns the major and minor versions of the -AppGroup extension supported by the server. - - -ProcXagCreate creates an AppGroup. A new record in a linked list -of AppGroups is allocated and initialized. The attributes from the -request are validated and copied to the AppGroup record. If necessary -an abbreviated version of the connection setup information is compiled -and also stored in the AppGroup record. The first time an AppGroup -is created a client-state-change callback is registered and a -reference count is incremented. - - -ProcXagDestroy destroys an AppGroup an AppGroup by calling -FreeResource specifying the AppGroup ID. This will result in -the destructor function XagAppGroupFree being called. The -reference count is decremented and when it reaches zero the -client-state-change callback is deleted. - - -ProcXagGetAttr returns the AppGroup Attributes to the requesting -client. - - -ProcXagQuery returns the AppGroup ID of an arbitrary resource to -the requesting client. - - -ProcXagCreateAssoc creates an association between an X window ID -and system-specific data. In native X this functionality is -unnecessary but for various personal computers, e.g. Macintosh, -OS/2, and MS-Windows it is necessary to associate an X window ID -with the system's native window identifier so that when the -AppGroup Leader issues a ReparentWindow request the personal -computer X server can lookup the system-specific window ID and -make the necessary function call(s) with it. - - -ProcXagDestroyAssoc destroys the association created with -ProcXagCreateAssoc. - - -XagResetProc removes the client-state-change callback, sets the -reference count to zero, and frees all the AppGroup records in -the linked list by calling XagAppGroupFree. - - -XagAppGroupFree calls CloseDownClient for each client in an -AppGroup if the AppGroup has a leader, unlinks the AppGroup -record from the linked list, frees allocated memory referenced -by the record, and finally frees the record itself. - - - - -Known Problems in this release. - -In a combined UI/Print server the connection setup returned to an -embedded application will not have information about the print -screens. - - -The LBX proxy caches connection setup information and will return -incorrect connection setup information to an embedded client. - - - - -- cgit v1.2.3 From f6ee80371c4bf9ebd99418a4328a351186ac0847 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Tue, 9 Nov 2010 15:19:09 -0500 Subject: config: HTML file generation: use the installed copy of xorg.css Currenlty the xorg.css file is copied in each location where a DocBook/XML file resides. This produces about 70 copies in the $(docdir) install tree. Signed-off-by: Gaetan Nadon --- specs/.gitignore | 2 -- specs/Makefile.am | 7 ++----- 2 files changed, 2 insertions(+), 7 deletions(-) (limited to 'specs') diff --git a/specs/.gitignore b/specs/.gitignore index 12fe512..6fa5c31 100644 --- a/specs/.gitignore +++ b/specs/.gitignore @@ -1,6 +1,4 @@ -# Add & Override for this directory and it's subdirectories *.html *.ps *.pdf *.txt -*.css diff --git a/specs/Makefile.am b/specs/Makefile.am index 21e5fba..6fcafe7 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -49,11 +49,8 @@ doc_DATA += $(doc_sources:.xml=.txt) endif if HAVE_STYLESHEETS -XMLTO_FLAGS = -m $(XSL_STYLESHEET) - -doc_DATA += xorg.css -xorg.css: $(STYLESHEET_SRCDIR)/xorg.css - $(AM_V_GEN)cp -pf $(STYLESHEET_SRCDIR)/xorg.css $@ +XMLTO_FLAGS = -m $(XSL_STYLESHEET) \ + --stringparam html.stylesheet=$(STYLESHEET_SRCDIR)/xorg.css endif CLEANFILES = $(doc_DATA) -- cgit v1.2.3 From 3102665110846af5c87792b221e1ef6a9dc1a0e2 Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Mon, 29 Nov 2010 16:29:44 -0500 Subject: specs: add appgroup specs in DocBook/XML format Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 11 +- specs/appendix.xml | 61 ++++ specs/appgroup.xml | 1018 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1085 insertions(+), 5 deletions(-) create mode 100644 specs/appendix.xml create mode 100644 specs/appgroup.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index 6fcafe7..a5d34fd 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -23,6 +23,7 @@ if ENABLE_SPECS doc_sources = \ + appgroup.xml \ dbe.xml \ dpms.xml \ evi.xml \ @@ -35,7 +36,7 @@ doc_sources = \ tog-cup.xml \ xtest.xml -dist_doc_DATA = $(doc_sources) +dist_doc_DATA = $(doc_sources) appendix.xml if HAVE_XMLTO doc_DATA = $(doc_sources:.xml=.html) @@ -57,16 +58,16 @@ CLEANFILES = $(doc_DATA) SUFFIXES = .xml .ps .pdf .txt .html -.xml.txt: +%.txt: %.xml $(dist_doc_DATA) $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $< -.xml.html: +%.html: %.xml $(dist_doc_DATA) $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $< -.xml.pdf: +%.pdf: %.xml $(dist_doc_DATA) $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $< -.xml.ps: +%.ps: %.xml $(dist_doc_DATA) $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $< endif HAVE_XMLTO diff --git a/specs/appendix.xml b/specs/appendix.xml new file mode 100644 index 0000000..b6c0f1d --- /dev/null +++ b/specs/appendix.xml @@ -0,0 +1,61 @@ + + + +System Window Encodings + + +The AppGroupCreateAssoc request has the following possible variations: + + + +AppGroupCreateAssoc (X11) + 1 CARD8 opcode + 1 6 XC-APPGROUP opcode + 2 n length + 4 WINDOW window + 2 0 window_type + 2 4 system_window_len + 4 WINDOW Window + + + +AppGroupCreateAssoc (Macintosh) + 1 CARD8 opcode + 1 6 XC-APPGROUP opcode + 2 n length + 4 WINDOW window + 2 1 window_type + 2 12 system_window_len + 4 CARD32 WindowPtr + 2 INT16 Rect.top + 2 INT16 Rect.left + 2 INT16 Rect.bottom + 2 INT16 Rect.right + + + +AppGroupCreateAssoc (Win32) + 1 CARD8 opcode + 1 6 XC-APPGROUP opcode + 2 n length + 4 WINDOW window + 2 2 window_type + 2 4 system_window_len + 4 CARD32 HWND + + + +AppGroupCreateAssoc (Win16) + 1 CARD8 opcode + 1 6 XC-APPGROUP opcode + 2 n length + 4 WINDOW window + 2 3 window_type + 2 4 system_window_len + 2 CARD16 HWND offset + 2 CARD16 HWND segment + + + diff --git a/specs/appgroup.xml b/specs/appgroup.xml new file mode 100644 index 0000000..f506d86 --- /dev/null +++ b/specs/appgroup.xml @@ -0,0 +1,1018 @@ + + + +
+ + + Application Group Extension to the X Protocol + X Consortium Standard + + + Kaleb + S. + KEITHLEY + X Consortium, Inc + kaleb@x.org + + + X Version 11, Release 6.4 + 27 September 1996 + + + +Copyright © 1996 X Consortium, Inc. All Rights Reserved. + + + +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 OF 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. + + + + + +The Application Group Extension to the X protocol is intended to provide a framework to allow +more than one program to manage X applications on the desktop. The initial use of this extension +will be to insert or embed the windows of X programs into the windows of another program, such +as a web browser. This extension is not intended to address larger embedding issues that, for +example, OpenDoc does, such as shared menu bars, etc. + + + + + +Purpose and Goals + + +The Application Group Extension to the X protocol is intended to provide +a framework to allow more than one program to manage X applications on +the desktop. The initial use of this extension will be to insert or embed +the windows of X programs into the windows of another program, such as a +web browser. This extension is not intended to address larger embedding +issues that, for example, OpenDoc does, such as shared menu bars, etc. +Using X programs on the World Wide Web allows for greater control of the +presentation and takes advantage of the existing body of X programs rather +than re-implement them in another language. In addition it allows the +embedding of non-X programs into web browsers by using third party products +like Wabi, MAE, and WinCenter. + +Wabi is a trademark of Sun Microsystems, Inc. MAE is a trademark of Apple +Computer, Inc. WinCenter is a trademark of Network Computing Devices, Inc. + + + + + + +Overview of the protocol. + + +This extension introduces the concept of an Application Group. An Application Group is a set of one or more applications that are primarily managed by a special application known as the Application Group Leader, which, for example, might be a web browser. The primary purpose of Application Groups is to provide a means of sharing the Substructure-Redirect attribute of the root window between the window manager and one or more Application Group Leaders. + + + +To join an Application Group an application must present the proper authorization during the connection setup. Authorizations are generated by the X server at the request of an Application Group Leader, and are then stored for the application to use to establish its connection to the X server. To generate an authorization the Application Group Leader sends a request to the server naming the Application Group to which the authorization will be bound, and any applications that connect using that authorization will automatically become part of the associated Application Group. The protocol to generate an authorization is defined in the Security Extension specification. + + + +As a member of an Application Group, when an application creates and maps a window as a child of the root window, the MapRequest and ConfigureRequest events are delivered to the Application Group Leader instead of the window manager. The Application Group Leader may then reparent the window into its own window hierarchy; or reissue the map request, in which case the window comes under the control of the window manager. + + + + +Requests + + +AppGroupQueryVersion + + + + + + + client_major_version: CARD16 + + + client_minor_version: CARD16 + + + => + + + server_major_version: CARD16 + + + server_minor_version: CARD16 + + + + + + +If supplied, the client_major_version and client_minor_version indicate what version of the protocol the application wants the server to implement. The server version numbers returned indicate the version of the protocol the X server actually supports. This may not match the versions requested by the application. An implementation may (but need not) support more than one version simultaneously. The server_major_version and server_minor_version numbers are a mechanism to support any future revisions of the Application Group extension protocol which may be necessary. In general, the major version would increment for incompatible changes, and the minor version would increment for small, upward-compatible changes. X servers that support the protocol defined in this document will return a server_major_version of 1 and a server_minor_version of 0. + + + +AppGroupCreate + + + + + + + app_group: APPGROUP + + + value_mask: BITMASK + + + value_list: LISTofVALUE + + + + + + +This request creates an Application Group using app_group as the Application Group ID. + + + + +  + + + + +The value_mask and value_list specify attributes of the Application Group that are to be explicitly initialized. The attributes, their types, and the default values are: + + + + + + + + + + Attribute + Type + Default + + + app_group_leader + Bool + True + + + single_screen + Bool + True + + + default_root + Window + None + + + root_visual + VisualID + None + + + default_colormap + Colormap + None + + + black_pixel + Pixel + 0 + + + white_pixel + Pixel + 0 + + + + + + +If the single_screen attribute is True then the number of video screens returned to a program in the Application Group in the connection setup message is one, irrespective of how many video screens the server actually has. If a server supports both video and print screens, then all print screens will always be returned. If single_screen is specified as True then the connection setup message will contain only the information about the video screen which has default_root as its root window, plus any print screens. + + + +The intent is to allow an embedding manager to ensure that it will be able to reparent any top-level windows that Application Group members create. By hiding the fact that there are other screens it can be reasonably assured that applications will only create top-level windows on the same screen that it itself appears on. An embedding manager should take care not to supply an invalid display, e.g. :0.1, to a program that will be in an Application Group where the single_screen attribute is True. + + + +If single_screen is set to True default_root specifies which screen will be returned as screen zero in the connection setup message for applications in the Application Group. If set to None, then the real screen zero is used, otherwise the screen which has default_root as its root window will be used. + + + + +If single_screen is set to True the root_visual and default_colormap attributes may be used to over-ride the default values that are returned in the connection setup information returned to new programs in the Application Group. If None is specified for root_visual or default_colormap then the normal default values for the screen (possibly spedified by default_root) are used, otherwise the specified values are used. If root_visual and/or default_colormap are specified they must be valid, i.e. root_visual must be a visual type available on the screen, and the colormap, if specified, must be a valid colormap for the visual that is used. + + + +IF single_screen is set to True and default_colormap is not specified as None, the black_pixel and white_pixel attributes must be specified, and they will over-ride the default values that are returned in the connection setup returned to new programs in the Application Group. If default_colormap is specified as None and black_pixel and/or white_pixel are specified, they will be ignored. + + + +The app_group_leader attribute is used to identify the Application Group Leader program for the app_group. By specifying True the server will identify the program making the request as the Application Group Leader for the application group. The Application Group Leader receives MapRequest and ConfigureRequest events from the server when an attempt is made to map or configure top-level windows of a program in an Application Group, instead of being sent to a window manager that has selected SubstructureRedirect events on the root window. The parent window field in these events will contain the Application Group ID. + + +AppGroupDestroy + +app_group: APPGROUP + + + +This request destroys the app_group. If the app_group_leader attribute for the app_group is True, then any applications in the Application Group that are still connected will be killed as if a KillClient request had been received for that application. + + + +If the application that created a non-embedded Application Group exits, and therefore any Authorizations to be cancelled, and any applications that attempt to open new connections to the X server using one of those Authorizations will be unable to do so. + + +AppGroupGetAttr + + + + + + + + >app_group: APPGROUP + + + => + + + LISTofVALUE + + + + + + +This request returns the application group attributes for app_group. + + +AppGroupQuery + + + + + + + resource: XID + + + => + + + app_group: APPGROUP + + + + + + +This request returns the Application Group ID of the application that created resource or None if that application is not associated with any Application Group. The resource value may be the resource base of the application. + + +AppGroupCreateAssociation + + + + + + + window: WINDOW + + + window_type: CARD32 + + + system_window: LISTofCARD8 + + + + + + +This request associates window with system_window. The window_type indicates the native window system of the application making the request. For non-X window_types both the embedding manager and the server must be executing on the same host. When system_window is Microsoft Windows or OS/2 Presentation Manager, the system_window is an HWND; when the native window system is Macintosh, the system_window is a WindowPtr and a Rect. The window may be used for any X request that takes a Window. + + +AppGroupDestroyAssociation + + + + + + + window: WINDOW + + + + + + +This request destroys the association created with AppGroupCreateAssociation. The window is destroyed. The system_window that was specified in the AppGroupCreateAssociation request is not affected. + + + + + +Changes to Existing Requests + + +MapWindow + + +If the override-redirect attribute of the window is False and if the window is a child of a root window and if the window belongs to an application that is in an application group and if some other application is the application group leader for that group, then a MapRequest event is generated and the window remains unmapped. Otherwise, the core protocol semantics apply. + + + + +ConfigureWindow + + +If the override-redirect attribute of the window is False and if the window is a child of a root window and if the window belongs to an application that is in an application group and if some other application is the application group leader for that group, then a ConfigureRequest event is generated and the window remains unchanged. Otherwise, the core protocol semantics apply. + + + + +CreateWindow + + +When a program in an Application Group creates a window that is a child of a root window and specifies CopyFromParent for the Visual, if the single_screen attribute is True and the root_visual attribute is set to something other than None, then the window will be created using the Application Group’s root_visual, otherwise core protocol semantics apply. + + + +When a program in an Application Group creates a window that is a child of a root window and specifies CopyFromParent for the Colormap, if the single_screen attribute is True, the default_colormap attribute is set to something other than None, and the window’s Visual is the same as the Application Group’s root_visual attribute, then the window will be created using the Application Group’s default_colormap, otherwise core protocol semantics apply. + + + + + +ChangeWindowAttributes + + +When a program in an Application Group changes the attributes of a window that is a child of a root window and specifies CopyFromParent for the Colormap, if the single_screen attribute is True, the default_colormap attribute is set to something other than None, and the window’s Visual is the same as the Application Group’s root_visual attribute, then the window will be created using the Application Group’s default_colormap, otherwise core protocol semantics apply. + + + + + + + +Changes to Existing Events + + +When the top-level window of an application that is a member of an Application Group is the target of a MapWindow or ConfigureWindow request, if there is an Application Group Leader then MapRequest and ConfigureRequest events are automatically delivered to it, otherwise the core protocol semantics apply, i.e. they are delivered to the client, if any, that has SubstructureRedirect set in its root-window event mask, e.g. the window manager. + + + +The Application Group Leader must not select SubstructuRedirect events on a root window as doing so would result in a core protocol error; only one client is permitted to do so, and that is usually the window manager. + + + + +MapRequest + + +When a MapWindow request is received for a window whose override-redirect attribut is set to False and whose parent is the root window and the window belongs to an application that is in an application group and there is an application group leader for the group, then this event is delivered to the Application Group Leader with the parent field in the event set to the AppGroup ID. Otherwise the core protocol semantics apply. + + + + +ConfigureRequest + + +When a ConfigureWindow request is received for a window whose override-redirect attribut is set to False and whose parent is the root window and the window belongs to an application that is in an application group and there is an application group leader for the group, then this event is delivered to the Application Group Leader with the parent field in the event set to the AppGroup ID. Otherwise the core protocol semantics apply. + + + + + + +Errors + + +AppGroupQueryVersion + + +There are no errors for AppGroupQueryVersion. + + + + + +AppGroupCreate + + +A Window error is returned if default_root is specified and is not a valid root window.. + + + +A Color error is returned default_colormap is specified but default_colormap is not a valid colormap for the screen of default_root. + + + +A Match error is returned if root_visual and default_colormap are both specified, but + + + +default_colormap’s visual is not root_visual. + + + +A Match error is returned if root_visual does not exist for the screen of the default_root. + + + + + +AppGroupDestroy + + +An AppGroup error is returned if app_group is not a valid Application Group. + + + +An Access error is returned if an untrusted application attempts to destroy an Application Group created by a trusted application. + + + + + +AppGroupGetAttr + + +An AppGroup error is returned if app_group is not a valid Application Group. + + + +An Access error is returned if an untrusted application attempts to get the attributes of an Application Group created by a trusted application. + + + + + +AppGroupQuery + + +An Access error is returned if an untrusted application attempts to query the Application Group of a trusted application. + + + + + +AppGroupCreateAssociation + + +A Match error is returned if the X server does not support the window_type. + + + +An Access error may be returned if the X server only supports the window_type on the local host and the program making the request is on a non-local host. + + + +A Window error may be returned for system-specific errors related to system_window, e.g. system_window does not represent a valid native window. + + + + + +AppGroupDestroyAssociation + + +A Window error is returned if window was not specified in a previous AppGroupCreateAssociation request. + + + + + + +Encoding + + +Please refer to the X11 Protocol encoding document as this document uses conventions established there. + + + + +The name of this extension is XC-APPGROUP + + + + +AppGroupQueryVersion + 1 CARD8 opcode + 1 0 XC-APPGROUP opcode + 2 3 length + 2 CARD16 client_major_version + 2 CARD16 client_minor_version +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence_number + 4 0 length + 2 CARD16 server_major_version + 2 CARD16 server_minor_version + 20 unused + + + + +AppGroupCreate + 1 CARD8 opcode + 1 1 XC-APPGROUP opcode + 2 8+n length + 4 XID app_group + 4 BITMASK attrib_mask + #x00000001 app_group_leader + #x00000002 single_screen + #0x0000004 default_root + #x00000008 root_visual + #x00000010 default_colormap + #x00000020 black_pixel + #x00000040 white_pixel + n LISTofVALUE value-list +VALUEs + 4 BOOL app_group_leader + 4 BOOL single_screen + 4 WINDOW default_root + 4 VISUALID root_visual + 4 COLORMAP default_colormap + 4 CARD32 black_pixel + 4 CARD32 white_pixel + + + + +AppGroupDestroy + 1 CARD8 opcode + 1 2 XC-APPGROUP opcode + 2 2 length + 4 XID app_group + + + +AAppGroupGetAttr + 1 CARD8 opcode + 1 4 XC-APPGROUP opcode + 2 2 length + 4 XID app_group +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence_number + 4 0 length + 4 WINDOW default_root + 4 VISUALID root_visual + 4 COLORMAP default_colormap + 4 CARD32 black_pixel + 4 CARD32 whte_pixel + 1 BOOL single_screen + 1 BOOL app_group_leader + 2 unused + + + + +AppGroupQuery + 1 CARD8 opcode + 1 5 XC-APPGROUP opcode + 2 2 length + 4 XID resource +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence_number + 4 0 length + 4 XID app_group + 20 unused + + + +AppGroupCreateAssoc + 1 CARD8 opcode + 1 6 XC-APPGROUP opcode + 2 n length + 4 WINDOW window + 2 CARD16 window_type + #0 X11 + #1 Macintosh + #2 Win32, OS/2 PM 2.x + #3 Win16, OS/2 PM 1.x + 2 n system_window_len + n LISTofCARD8 system_window + + + + +AppGroupDestroyAssoc + 1 CARD8 opcode + 1 7 XC-APPGROUP opcode + 2 2 length + 4 WINDOW window + + + + + +Library API + + + + + + + +Status XagQueryVersion ( xkb, keycode) /* macro */ + + + + +Display dpy; + + + + +int * major_version_return; + + + + +int * minor_version_return; + + + + + + + +XagQueryVersion sets major_version_return and minor_version_return to the major and minor Application Group protocol version supported by the server. If the Xag library is compatible with the version returned by the server it returns non-zero. If dpy does not support the Application Group extension, or if the server and library protocol versions are incompatible, or if there was an error during communication with the server, it returns zero. No other Xag functions may be called before this function. If a program violates this rule, the effects of all subsequent Xag calls that it makes are undefined. + + + +An embedding manager in, e.g. a Personal Computer Web Browser, will need to open a connection to the Personal Computer X server by calling XOpenDisplay() before using the Application Group extension. + + + +An embedding manager such as a web browser that intends to embed programs in an Application Group should create the Application Group with XagCreateEmbeddedApplicationGroup. + + + + + + + + + +Status XagCreateEmbeddedApplicationGroup( + + + + + Display* dpy, + + + + + VisualID root_visual, + + + + + Colormap default_colormap, + + + + + unsigned long black_pixel, + + + + + unsigned long white_pixel, + + + + + XAppGroup* app_group_return); + + + + + + + + +XagCreateEmbeddedApplicationGroup creates an Application Group for an embedding manager with the attributes specified. It also sets the default_root attribute to DefaultRoot(dpy, DefaultsScreen(dpy)) and the single_screen and app_group_leader attributes to True. It returns the Application Group ID in app_group_return. + + + +You can create an Application Group without intending to do embedding. One reason for doing this is to give a group of clients their own font-path. + + + +A special font-path can be created by creating an Application Group, getting an Authorization using XSecurityGenerateAuthorization, and then running ‘xset fp+ <new font path>’ as a member of the Application Group. Font-path elements added in this way will be "private" to the Application Group. + + + + + + + + +Status XagCreateNonembeddedApplicationGroup( + + + + + Display* dpy, + + + + + XAppGroup* app_group_return); + + + + + + + +An Application Group created with XagCreateNonembeddedApplicationGroup will have the default_root, root_visual, and default_colormap attributes all set to None; the single_screen and app_group_leader attributes are set to False, and the black_pixel and white_pixel attributes are not used since the default_colormap attribute is None. + + + +To destroy an Application Group use XagDestroyApplicationGroup. + + + + + + + + +Status XagDestroyApplicationGroup( + + + + + Display* dpy, + + + + + XAppGroup app_group); + + + + + + + +The Application Group specified by app_group is destroyed. If the Application Group was created using XagCreateEmbeddingApplicationGroup, i.e. and therefore the app_group_leader attribute is True, all programs that are members of the Application Group are killed as if a KillClient request had been issued. + + + + +To retrieve the attributes of an Application Group use XagGetApplicationGroupAttributes. + + + + + + + + + +Status XagGetApplicationGroupAttributes( + + + + + Display* dpy, + + + + + XAppGroup app_group, + + + + + ...); + + + + + + + + + +XagGetApplicationGroupAttributes is a varargs function that retrieves the Application Group’s attributes specified in the vararg parameter list. + + + +The attributes that may be specified are: XagNappGroupLeader, XagNsingleScreen, XagNdefaultRoot, XagNrootVisual, XagNdefaultColormap, XagNblackPixel, and XagNwhitePixel; which correspond to app_group_leader, single_screen, default_root, root_visual, default_colormap, black_pixel, and white_pixel respectively. See AppGroupCreate in Section 3 for a description of each attribute. + + + +The types for each of the parameters are pointers to the following: + + + + single_screen Bool + default_root Window + root_visual VisualID + default_colormap Colormap + black_pixel unsigned long + white_pixel unsigned long + app_group_leader Bool + + + +Example: + ... + Boolean app_group_leader, single_screen; + Window default_root; + VisualID root_visual; + Colormap default_colormap; + Pixel black_pixel, white_pixel; + ... + status = XagGetApplicationGroupAttributes(dpy, app_group, + XagNappGroupLeader, &app_group_leader, + XagNsingleScreen, &single_screen, + XagNdefault_root, &default_root, + XagNrootVisual, &root_visual, + XagNdefaultColormap, &default_colormap, + XagNblackPixel, &black_pixel, + XagNwhitePixel, &white_pixel, + NULL); + ... + + + + +To determine which Application Group a resource (such as a window) belongs to, use XagQueryApplicationGroup. + + + + + + + + +Status XagQueryApplicationGroup( + + + + + Display* dpy, + + + + + XID resource, + + + + + XAppGroup* app_group_return); + + + + + + + + +The Application Group is returned in app_group_return, if the resource is not in any Application Group then app_group_return will be set to None. + + + +To associate an X Window ID with a system-specific window ID, such as a HWND or a WindowPtr, use XagCreateAssociation. + + + + + + + + +Status XagCreateAssociation( + + + + + Display* dpy, + + + + + Window* window_return, + + + + + void* system_window); + + + + + + + + +The window_ret may be used as the target for a ReparentWindow request. + + + +Because XReparentWindow is not constrained in the same way that Win32’s SetParent and the Macintosh are, there is no reason to call XagCreateAssociation in an X-based embedding manager. As such if XagCreateAssociation is called in a native X program, the window_return will be the same as the system_window, and the implementation may even elect to not generate any protocol. + + +To create an association on the Macintosh: + + + struct { + WindowPtr win; + Rect rect; + } system_window; + system_window.win = win_ptr; + system_window.rect.top = system_window.rect.left = 20; + system_window.rect.bottom = 180; + system_window.rect.right = 380; + + + + status = XagCreateAssociation (dpy, &window, (void*)&system_window); + + + +To create an association using a Win16, Win32, or OS/2 PM: + + + + HWND system_window; + status = XagCreateAssociation (dpy, &window, (void*)&system_window); + + + +To destroy the association created with XagCreateAssociation use XagDestroyAssociation. + + + + + + + + + +Status XagDestroyAssociation( + + + + + Display* dpy, + + + + + Window window); + + + + + + + +After calling XagDestroyAssociation the window may no longer be used to +reparent windows with XReparentWindow. + + + +Like XagCreateAssociation, if the native window system is X11 the implementation may elect to not generate any protocol as a result of this function call in order to avoid unintentionally destroying the the system_window that was specified in the prior XagCreateAssociation call. + + + +
-- cgit v1.2.3 From fd8a26edefc53b370c554a60c75ff32fc60b99c8 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Tue, 30 Nov 2010 09:05:07 -0500 Subject: specs: add low bandwith spec from xorg-docs Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 1 + specs/lbx.xml | 6291 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 6292 insertions(+) create mode 100644 specs/lbx.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index a5d34fd..3792353 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -28,6 +28,7 @@ doc_sources = \ dpms.xml \ evi.xml \ geproto.xml \ + lbx.xml \ multibuf.xml \ security.xml \ shape.xml \ diff --git a/specs/lbx.xml b/specs/lbx.xml new file mode 100644 index 0000000..f42f9f9 --- /dev/null +++ b/specs/lbx.xml @@ -0,0 +1,6291 @@ + + + +
+ + + Low Bandwidth X Extension + X Consortium Standard + + + D. + Converse + + + J. + Fulton + + + D. + Lemke + + + R. + Mor + + + K. + Packard + + + R. + Tice + + + D. + Tonogai + + + Protocol Version 1.0 + + + + +Copyright (c) 1996 X Consortium + + +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 +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. + + + + + + + + +Introduction + + +Low Bandwidth X (LBX) is a network-transparent protocol for running X Window +System applications over transport channels whose bandwidth and latency are +significantly worse than that used in local area networks. It combines a +variety of caching and reencoding techniques to reduce the volume of data that +must be sent over the wire. It can be used with existing clients by placing a +proxy between the clients and server, so that the low bandwidth/high latency +communication occurs between the proxy and server. + + + + +This extension was designed and implemented by Jim Fulton, David Lemke, Keith +Packard, and Dale Tonogai, all of Network Computing Devices (NCD). Chris Kent +Kantarjiev (Xerox PARC) participated in early design discussions. Ralph Mor (X +Consortium) designed and implemented additional sections. Donna Converse (X +Consortium) authored the protocol description and encoding from design notes +and the implementation. Ray Tice (X Consortium) resolved the open issues in the +design and specification. Bob Scheifler (X Consortium) helped out in many areas. + + + + +The extension name is "LBX". + + + + + +Description + + +The design center for LBX is to use a proxy as an intermediary between the +client and server. The proxy reencodes and compresses requests, events, replies +and errors, as well as the resulting data stream. Additionally, the proxy can +cache information from the server to provide low-latency replies to clients. +This reply generation by the proxy is known as short-circuiting. A proxy can +handle multiple clients for a given server, but does not prevent clients from +connecting directly to the server. The design allows the proxy to multiplex +multiple clients into a single data stream to the server. + + + + +Much of LBX is implemented as an extension. The compression and reencoding +changes can be isolated to the transport and dispatch portions of the server, +while short-circuiting requires minor changes to the server’s colormap and +property code. + + + + +LBX employs several different compression and short-circuiting methods. Use of +these methods is negotiable, and in some cases, the algorithm used by a given +method is negotiable as well. LBX also provides for negotiation of extensions +to LBX. + + + + +Data Flow + + +The LBX data stream goes through a number of layers: + + + + + +Client requests + + +Read by LBX and potential byte-swapping + + +Request-specific compression + + +Potential byte swapping + + +Multiplexing of client request streams + + +Delta replacement + + +Stream compression + + + + +Transport + + + + + +Stream decompression + + +Delta substitution + + +Demultiplexing of client request streams + + +Potential byte swapping + + +Reencoding + + +Request processing + + + + +The reverse process occurs with X server replies, events, and errors. + + + + + +Tags + + +Tags are used to support caching of large data items that are expected to be +queried multiple times. Such things as the keyboard map and font metrics are +often requested by multiple clients. Rather than send the data each time, the +first time the data is sent it includes a tag. The proxy saves this data, so +that subsequent requests can send only the tag to refer to that same data. The +different types of tags are used for connection information, keyboard maps, +modifier maps, fonts information and properties. + + + + +Tag usage is negotiated as a boolean in the +LbxStartProxy + message. The proxy controls how many tags are stored in the proxy. The server +may wish to observe the proxy’s InvalidateTag behavior to limit how many tags +are cached at any one time. Tagged data is not shared across types of tags, but +the number space used for the tag ids is. The tag ids are generated by the +server. + + + + +The X server keeps track of what tags are known to the proxy. The proxy can +invalidate a tag if no tag bearing replies of that type are pending. The proxy +sends an +LbxInvalidateTag + message to release the tagged data. The proxy must not invalidate connection +tags unless instructed to do so by the server. + + + + +If the server wishes to discard tagged data, it must either have received an + +LbxInvalidateTag + request from the proxy or send an +LbxInvalidateTag + event to the proxy for that tag. + + + + +Tag Substitution in Requests + + +Many substitution requests have a tag field, followed by fields marked +optional. For these requests, if the optional fields are present, the +data in them is stored in the indicated tag, unless the tag is 0. If +the optional fields are absent, the tag field indicates the tag that +contains the data for the "optional" fields. + + + + + +Property Tags + + +Property data makes special use of tags. A common use of properties is for +inter-client communication. If both clients use the proxy, it is wasteful to +send the data to the server and then back, when the server may never need it. + +LbxChangeProperty + request does the same work as the core +ChangeProperty + request, but it does not send the data. The reply to this request contains a +tag id corresponding to the data. If the property information is used locally, +the server responds to +LbxGetProperty + with the tag, and the property data need never be sent to the server. If the +server does require the data, it can issue an +LbxQueryTag + message. The proxy can also send the data on at any time if it judges it +appropriate (i.e., when the wire goes idle). Since the proxy owns the property +data, it must not invalidate the tag before sending the data back to the server +via an +LbxTagData + request. + + + + + + +Short-circuiting + + +Short-circuiting is used to handle constant data. This includes atoms, color +name/RGB mappings, and +AllocColor + calls. Atoms and color name/RGB mappings stay constant for the life of the +server. +AllocColor + + +replies are constant for each colormap. Short-circuiting replaces round-trip +requests with one-way requests, and can sometimes use one in place of many. + + + + +Atoms are used heavily for ICCCM communication. Once the proxy knows the string +to atom mapping, it has no need to send subsequent requests for this atom to +the server. + + + + +Colorname/RGB mappings are constant, so once the proxy sees the response from + +LookupColor +, it need not forward any subsequent requests. + + + + +Clients often use the same color cells, so once a read-only color allocation +has occurred, the proxy knows what RGB values should be returned to the client. +The proxy doesn't need to forward any +AllocColor + requests it can resolve, but it must tell the server to modify the color +cell's reference count. +LbxIncrementPixel + is used to support this. + + + + +For all three classes of short-circuiting, the proxy must still tell the server +a request has occurred, so that the request sequence numbers stay in sync. This +is done with +LbxModifySequence +. + + + + +Sequence numbers cause the major complication with short-circuiting. X +guarantees that any replies, events or errors generated by a previous request +will be sent before those of a later request. This means that any requests that +can be handled by the proxy must have their reply sent after any previous +events or errors. + + + + +If a proxy’s applications do not require strict adherence to the X protocol +ordering of errors or events, a proxy might provide further optimization by +avoiding the overhead of maintaining this ordering, however, the resulting +protocol is not strictly X11 compliant. + + + + + +Graphics Re-encoding + + +The LBX proxy attempts to reencode PolyPoint, +PolyLine, PolySegment, +PolyRectangle, PolyArc, +FillPoly, PolyFillRectangle, +PolyFillArc, CopyArea, +CopyPlane, PolyText8, +PolyText16, ImageText8, +and ImageText16 requests. If the request can be +reencoded, it may be replaced by an equivalent LBX form of the request. +The requests are reencoded by attempting to reduce 2-byte coordinate, +length, width and angle fields to 1 byte. Where applicable, the +coordinate mode is also converted to Previous + to improve the compressibility of the resulting data. In image requests, +the image data may also be compressed. + + + + +Motion events + + +To prevent clogging the wire with MotionNotify + events, the server and proxy work together to control the number +of events on the wire. This is done with the +LbxAllowMotion + request. The request adds an amount to an allowed motion count in +the server, which is kept on a per-proxy basis. Every motion notify +event sent to the proxy decrements the allowed motion counter. If +the allowed motion count is less than or equal to zero, motion +events not required by the X protocol definition are not sent to the +proxy. The allowed motion counter has a minimum value of -2^31. + + + + +Event Squishing + + +In the core protocol, all events are padded as needed to be 32 bytes long. The +LBX extension reduces traffic by removing padding at the end of events, and +implying the event length from its type. This is known as squishing. + + + + +Master Client + + +When the initial X connection between the proxy and the server is converted to +LBX mode, the proxy itself becomes the master client. New client requests and +some tag messages are sent in the context of the master client. + + + + + +Multiplexing of Clients + + +The LBX proxy multiplexes the data streams of all its clients into one stream, +and then splits them apart again when they are received. The +LbxSwitch + message is used to tell each end which client is using the wire at the time. + + + + +The server should process delta requests in the order that they appear on the +LBX connection. If the server does not maintain the interclient request order +for requests sent by the proxy, it must still obey the semantics implied by the +interclient request order so that the delta cache functions correctly. + + + + +The server can affect the multiplexing of clients by the proxy using the + +LbxListenToOne + and +LbxListenToAll + messages. This is useful during grabs, since the master connection can not be +blocked during grabs like other clients. The proxy is responsible for tracking +server grabs issued by its clients so that the proxy can multiplex the client +streams in an order executable by the server. + + + + +Replies must be ordered in the multiplexed data stream from the server to the +proxy such that the reply carrying tagged data precedes replies that refer to +that tagged data. + + + + + +Swapping + + +Swapping is handled as with any X extension, with one caveat. Since a proxy can +be supporting clients with different byte orders, and they all share the same +wire, the length fields of all messages between the server and proxy are +expressed in the proxy byte order. This prevents any problems with length +computation that may occur when clients are switched. + + + + + +Delta cache + + +LBX takes advantage of the fact that an X message may be very similar to one +that has been previously sent. For example, a +KeyPress + event may differ from a previous +KeyPress + event in just a few bytes. By sending just the bytes that differ (or +"deltas"), the number of bytes sent over the wire can be substantially reduced. +Delta compaction is used on requests being sent by the proxy as well as on +replies and events being sent by the server. + + + + +The server and the proxy each keep per-proxy request and response caches. The +response cache contains events, errors and replies. All messages are saved in +the appropriate delta cache if they are of an appropriate type and more than 8 +bytes long but fit within the delta cache. The number of entries in the delta +cache and the maximum saved message size are negotiated in the +LbxStartProxy + request. + + + + +The LBX requests that are never stored in the request delta cache are the + +LbxQueryVersion +, +LbxStartProxy +, +LbxSwitch +, +LbxNewClient +, +LbxAllowMotion +, +LbxDelta +, +LbxQueryExtension +, +LbxPutImage +, +LbxGetImage +, +LbxBeginLargeRequest +, +LbxLargeRequestData +, +LbxEndLargeRequest + and +LbxInternAtoms + requests. The responses that are never stored in the response cache are + +LbxSwitchEvent + and +LbxDeltaResponse +. The message carried by a +delta +message is also cached, if it meets the other requirements. Messages after the + +LbxStartProxy + request are cached starting at index 0, and incrementing the index, modulo the +number of entries, thereafter. The request and response caches are +independently indexed. + + + + +If the current message is cachable and the same length as a message in the +corresponding delta cache, a delta message may be substituted in place of the +original message in the protocol stream. + + + + + +Stream Compression + + +Before being passed down to the transport layer messages can be passed through +a general purpose data compressor. The choice of compression algorithm is +negotiated with See LbxStartProxy. The proxy +and server are not required to support any specific stream compressor. As an +example, however, the X Consortium implementation of a ZLIB based compressor is +described below. + + + +The XC-ZLIB compressor is presented with a simple byte stream - the X and LBX +message boundaries are not apparent. The data is broken up into fixed sized +blocks. Each block is compressed using zlib 1.0 (by Gailly & Adler), then a +two byte header is prepended, and then the entire packet is transmitted. The +header has the following information: + + + out[0] = (length & 0xfff) >> 8 | ((compflag) ? 0x80 : 0); + out[1] = length & 0xff; + + + + +Authentication Protocols + + +The current version of LBX does not support multipass authentication protocols +for clients of the proxy. These authentication protocols return an +Authenticate + message in response to a connection setup request, and require additional +authentication data from the client after the +LbxNewClient + request, and before the reply to +LbxNewClient +. One example of such a protocol is XC-QUERY-SECURITY-1. + + + + + + +C Library Interfaces + + +The C Library routines for LBX are in the Xext library. The prototypes are +located in a file named "XLbx.h". + + + + +Application Library Interfaces + + +In a proxy environment, applications do not need to call these routines to take +advantage of LBX. Clients can, however, obtain information about the LBX +extension to the server using this interface. Use of this routine may be +altered when connected through a proxy, as described in See C Library Interfaces. + + + + +XLbxQueryVersion + + +To determine the version of LBX supported by the X server, call +XLbxQueryVersion +. + + + + +Bool XLbxQueryVersion + Display * display + int * major_version_return + int * minor_version_return + + + + + + display + Specifies the connection to the X server. + + + major_version_return + Returns the extension major version number. + + + minor_version_return + Returns the extension minor version number. + + + + +The +XLbxQueryVersion + function determines if the LBX extension is present. If the extension is not +present, +XLbxQueryVersion + returns +False +; otherwise, it returns +True +. If the extension is present, +XLbxQueryVersion + returns the major and minor version numbers of the extension as supported by +the X server. + + + + + + +Proxy Library Interfaces + + +The following interfaces are intended for use by the proxy. + + + +XLbxQueryExtension + + +To determine the dynamically assigned codes for the extension, use the Xlib +function +XQueryExtension + or the LBX function +XLbxQueryExtension +. + + + + +Bool XLbxQueryExtension + Display * display + int * major_opcode_return + int * first_event_return + int * first_error_return + + + + + + display + Specifies the connection to the X server. + + + major_opcode_return + Returns the major opcode. + + + first_event_return + Returns the first event code. + + + first_error_return + Returns the first error code. + + + + +The +XLbxQueryExtension + function determines if the LBX extension is present. If the extension is not +present, +XLbxQueryExtension + returns +False +; otherwise, it returns +True +. If the extension is present, +XLbxQueryExtension + returns the major opcode for the extension to major_opcode_return, the base +event type code to first_event_return, and the base error code to +first_error_return; otherwise, the return values are undefined. + + + + + +XLbxGetEventBase + +To determine the base event type code, use the Xlib function +XQueryExtension + or the LBX function +XLbxGetEventBase. + + + + + +int XLbxGetEventBase + Display * display + + + + + + display + Specifies the connection to the X server. + + + + +The XLbxGetEventBase +function returns the base event type code if the extension is +present; otherwise, it returns -1. + + + + + + + + +Protocol + + +Syntactic Conventions and Common Types + + +Please refer to the X Window System Protocol specification, +as this document uses the syntactic conventions established +there and references types defined there. + + + + +The following additional types are defined by this extension: + + + +DIFFITEM +1 CARD8 offset +1 CARD8 diff + + + +LBXANGLE: CARD8 or 2 BYTE + where (in order of precedence): + (0 <= in <= A(95)) && !(in % A(5)) out = 0x5a + (in / +A(5)) + A(105) <= in <= A(360) && !(in % A(15)) out = 0x67 + +(in / A(15)) + -A(100) <= in <= -A(5) && !(in % A(5)) out = 0xa6 + +(in / A(5)) + -A(360) < in <= -A(105) && !(in % A(15)) out = 0x98 + +(in / A(15)) + -A(360) < in <= A(360) out[0] = in >> 8; out[1] = in + + + +LBXARC: + [x, y: LBXINT16, + width, height: LBXCARD16, + angle1, angle2: LBXANGLE] + + + +Within a list of arcs, after the first arc, x and y are +relative to the corresponding fields of the prior arc. + + + +LBXCARD16: CARD8 or 2 BYTE + where: + 0x0000 <= in < 0x00F0 CARD8 + 0x00F0 <= in < 0x10F0 out[0] = 0xF0 | ((in - 0xF0) >> +8) + out[1] = in - 0xF0 + + + +LBXGCANDDRAWENT +[ gc-cache-index, drawable-cache-index: CARD4 ] + + + +LBXGCANDDRAWUPDATE + drawable: DRAWABLE /* present only if +drawable-cache-index + == 0 */ +gc: GC] /* present only if gc-cache-index == 0 */ + + + +LBXGCANDDRAWABLE + cache-entries: LBXGCANDDRAWENT + updates: LBXGCANDDRAWUPDATE + + + +LBXINT16: INT8 or 2 BYTE + where: + 0xF790 <= in < 0xFF90 out[0] = 0x80 | (((in + 0x70) >> +8) & 0x0F) + out[1] = in + 0x70 + 0xFF90 <= in < 0x0080 CARD8 + 0x0080 <= in < 0x0880 out[0] = 0x80 | (((in - 0x80) >> +8) & 0x0F) + out[1] = in - 0x80 + + + +LBXPINT16: CARD8 or 2 BYTE /* for +usually positive numbers */ + where: + 0xFE00 <= in < 0x0000 out[0] = 0xF0 | (((in + 0x1000) +>> 8) & 0x0F) + out[1] = in + 0x1000 + 0x0000 <= in < 0x00F0 CARD8 + 0x00F0 <= in < 0x0EF0 out[0] = 0xF0 | ((in - 0xF0) >>8) + out[1] = in - 0xF0 + + + +LBXPOINT: [x, y: LBXINT16] + Within a list of points, after the first rectangle, x and y are +relative to the corresponding fields of the prior point. + + + +LBXRECTANGLE: + [x, y: LBXINT16, + width, height: LBXCARD16] + + + +Within a list of rectangles, after the first rectangle, x and +y are relative to the corresponding fields of the prior rectangle. + + + +MASK: CARD8 + + + + + +Errors + + +As with the X11 protocol, when a request terminates with an error, +the request has no side effects (that is, there is no partial execution). + + + + +There is one error, +LbxClient +. This error indicates that the client field of an LBX request was invalid, or +that the proxy’s connection was in an invalid state for a start or stop proxy +request. + + + + + +Requests + + +There is one request that is expected to be used only by the client: +LbxQueryVersion + + + + +There is one request that is expected to be used by the client or the proxy: + +LbxQueryExtension +. + + + + +The following requests are expected to be used only by the proxy, and are +instigated by the proxy: +LbxStartProxy +, +LbxStopProxy +, +LbxNewClient +, +LbxSwitch +, +LbxCloseClient +, +LbxModifySequence +, +LbxAllowMotion +, +LbxInvalidateTag +, +LbxTagData + and +LbxQueryTag +. + + + + +All other requests are sent by the proxy to the LBX server and are instigated +by reception of an X request from the client. They replace the X request. + + + + +Requests Initiated by the Proxy or by the Client + + + + + + + LbxQueryVersion + + + + + =>; + + + majorVersion: CARD16 + + + minorVersion: CARD16 + + + + + + +This request returns the major and minor version numbers of the LBX protocol. + + + + +The encoding of this request is on See +LbxQueryVersion. + + + + + + +Requests Initiated or Substituted by the Proxy + + + + + + + LbxQueryExtension + + + + + +nbytes +: CARD32 + + + +name +: STRING8 + + + => + + + num-requests: CARD8 + + + present: BOOL + + + major-opcode: CARD8 + + + first-event: CARD8 + + + first-error: CARD8 + + + reply-mask: LISTofMASK /* optional */ + + + event-mask:LISTofMASK /* optional */ + + + Errors: +Alloc + + + + + + + +This request is identical to the +QueryExtension + request, with an additional field, and two optional additional fields. When +the client issues an +QueryExtension + request, the proxy will substitute an +LbxQueryExtension + request. + + + + +This request determines if the named extension is present. If so, the major +opcode for the extension is returned, if it has one. Otherwise, zero is +returned. Any minor opcode and the request formats are specific to the +extension. If the extension involves additional event types, the base event +type code is returned. Otherwise, zero is returned. The format of events is +specific to the extension. If the extension involves additional error codes, +the base error code is returned. Otherwise, zero is returned. The format of +additional data in the errors is specific to the extension. + + + + +In addition, the number of requests defined by the named extension is returned. +If the number of requests is nonzero, and if the information is available, +reply-mask and event-mask will be included in the reply. The reply-mask +represents a bit-wise one-to-one correspondence with the extension requests. +The least significant bit corresponds to the first request, and the next bit +corresponds to the next request, and so on. Each element in the list contains +eight meaningful bits, except for the last element, which contains eight or +fewer meaningful bits. Unused bits are not guaranteed to be zero. The bit +corresponding to a request is set if the request could generate a reply, +otherwise it is zero. In the same way, the event-mask represents a bit-wise +one-to-one correspondence with the extension requests. A bit is set if the +corresponding request could result in the generation of one or more extension +or X11 events. If reply-mask is present in the reply, event-mask will also be +present. + + + + +The encoding of this request is on See +LbxQueryExtension. + + + + + + +Control Requests Initiated by the Proxy + + + + + + + LbxStartProxy + + + + + +options +: LISTofOPTION + + + => + + + choices: LISTofCHOICE + + + Errors: +LbxClient +, +Alloc + + + + where: + + + OPTION [optcode: CARD8, + + + len: OPTLEN, + + + option: (See See StartProxy Options) ] + + + CHOICE [optcode: CARD8, + + + len: OPTLEN, + + + choice: (See See StartProxy Options) ] + + + + + + + + + StartProxy Options + + + + + + + + optcode + option + choice + default + + + + + delta-proxy + DELTAOPT + DELTACHOICE + entries=16, maxlen=64 + + + delta-server + DELTAOPT + DELTACHOICE + entries=16, maxlen=64 + + + stream-comp + LISTofNAMEDOPT + INDEXEDCHOICE + No Compression + + + bitmap-comp + LISTofSTRING8 + LISTofINDEXEDOPT + No Compression + + + pixmap-comp + LISTofPIXMAPMETHOD + LISTofPIXMAPCHOICE + No Compression + + + use-squish + BOOL + BOOL + True + + + use-tags + BOOL + BOOL + True + + + colormap + LISTofSTRING8 + INDEXEDCHOICE + No Colormap Grabbing + + + extension + NAMEDOPT + INDEXEDCHOICE + Extension Disabled + + + +
+ + + + + + +   + + + DELTAOPT [minN, maxN, prefN: CARD8 + + + minMaxMsgLen, maxMaxMsgLen, prefMaxMsgLen: +CARD8] + + + DELTACHOICE [entries, maxlen: +CARD8] + + + INDEXEDCHOICE [index: CARD8, + + + data: LISTofBYTE] + + + INDEXEDOPT [index, opcode: CARD8] + + + NAMEDOPT [name: STRING8, + + + detail: LISTofBYTE] + + + OPTLEN 1 or 3 CARD8 + + + where: + + + (0 < in <= 0xFF): out = +in + + + (0 <= in<= 0xFFFF): out[0] = +0; out[1] = in >> 8; out[2] = in& 0xFF; + + + PIXMAPMETHOD [name: STRING8, + + + format-mask: BITMASK, + + + depths: LISTofCARD8] + + + PIXMAPCHOICE [index, opcode: CARD8, + + + format-mask: BITMASK, + + + depths: LISTofCARD8] + + + + + + + + + +This request negotiates LBX protocol options, and switches the proxy-server +connection from X11 protocol to LBX protocol. + + + + +The proxy gives the preferred protocol options in the request. The server +chooses from the given options and informs the proxy which to use. The options +may be listed in any order, and the proxy may choose which options to +negotiate. If an option is not successfully negotiated, the default is used. + + + + +The server delta cache and proxy delta caches can be configured for number of +entries, and the length of entries. (See See Delta +cache for details.) The delta caches are configured using the +delta-server + and +delta-proxy + options. To configure a cache, the proxy sends the minimum, maximum and +preferred values for the number of cache entries, ( +minN, maxN, prefN +), and the length of the cache entries, ( +minMaxMsgLen, maxMaxMsgLen, prefMaxMsgLen +). The server’s reply fields, +entries + and +maxlen +, contains the values to use. These values must be within the ranges specified +by the proxy. The server may also specify an +entries + value of 0 to disable delta caching. The cache entry lengths are specified in +units of 4 bytes. + + + + +The stream compression algorithm is selected using the +stream-comp +option. (Stream compression is described in See +Stream Compression.) Each algorithm has a name that follows the naming +conventions in See Algorithm Naming. To +negotiate using the stream-comp option, the proxy lists its available +compressors. For each candidate algorithm, the proxy sends the name in the + +name + field, and uses the +detail + field to send any additional data specific to each compression algorithm. The +reply contains a 0-based index into the list of algorithms to indicate which +algorithm to use, followed by data specific to that algorithm. + + + + +Bitmap compression is negotiated using the +bitmap-comp + option. The proxy sends a list of names of available algorithms, and the +server reply lists the algorithms to use. For each bitmap algorithm in the +reply, a 0-based index into the list of algorithms indicates the algorithm, and +the +opcode + field gives the value for use in requests. The algorithm names follow the +conventions in See Algorithm Naming. + + + + +Pixmap compression is negotiated using the +pixmap-comp + option. The proxy sends a list of available algorithms. For each algorithm, +the list includes, the name, a bitmask of supported formats, and a list of +depths that the format supports. The server reply lists the algorithms to use. +For each pixmap algorithm in the reply, the reply contains a 0-based index into +the list of proxy algorithms, the opcode to use in requests when referring to +this algorithm, a mask of valid formats, and a list of valid depths. Algorithm +names follow the conventions in See Algorithm +Naming. + + + + +Squishing is negotiated using the use-squish option. If the proxy desires +squishing, it sends a true value. The reply from the server indicates whether +to do squishing, and will indicate squishing only if +use-squish + is set to true in the request. + + + + +Tag caching, described in See Tags, is +negotiated using the use-tag option. If the proxy desires tag caching, it sends +a true value. The reply from the server indicates whether to do tag caching, +and will demand caching only if +use-tag + is set to true in the request. + + + + +The colormap option is used to negotiate what color matching algorithm will be +used by the proxy when the proxy uses the +LbxAllocColor + request to allocate pixels in a grabbed colormap. To negotiate using the +colormap option, the proxy lists the names of available colormap algorithms. +The choice in the reply contains a 0-based index into the list of algorithms to +indicate which algorithm to use, followed by data specific to that algorithm. +If no colormap algorithm is successfully negotiated, then the +LbxAllocColor +, +LbxGrabCmap +, and +LbxReleaseCmap + requests will not be used. + + + + +The extension option is used to control extensions to LBX. These extensions +may, for example, enable other types of compression. To negotiate an extension, +the name of the extension is sent, followed by any data specific to that +extension. The extension name follows the conventions in See Algorithm Naming. The extension option may +occur multiple times in the start proxy message, since multiple extensions can +be negotiated. The reply to an extension option contains the zero-based index +of the extension option, as counted in the +LbxStartProxy + message. This index is followed by extension-specific information. The server +does not respond to extensions it does not recognize. + + + + +An +LbxClient + error is returned when a client which is already communicating through an LBX +proxy to the X server sends a +LbxStartProxy + request. + + + + +The encoding for this request is on See +LbxStartProxy. + + + + + + + + + LbxStopProxy + + + + + Errors: +LbxClient + + + + + + + +This request terminates the connection between the proxy and X server, and +terminates any clients connected through the proxy. + + + + +The encoding for this request is on See +LbxStopProxy. + + + + +An +LbxClient + error is returned if the requesting client is not an LBX proxy. + + + + + + + + + LbxNewClient + + + + + +byte-order +: CARD8 + + + +client-id +: CARD32 + + + +protocol-major-version +: CARD16 + + + +protocol-minor-version: + CARD16 + + + +authorization-protocol-name +: STRING8 + + + +authorization-protocol-data +: STRING8 + + + => + + + Core X reply (if connection is rejected) + + +   + + + OR + + +   + + + success: BOOL + + + change-type: {NoDeltas, NormalClientDeltas, +AppGroupDeltas} + + + protocol-major-version: CARD16 + + + protocol-minor-version: CARD16 + + + tag-id: CARD32 + + + length: CARD16 + + + connection-data: CONINFO or CONDIF or +CONDIFROOT + + +   + + + where: + + + CONINFO: (the "additional data" +portion of the core connection reply for successes) + + + CONDIF: [resource-id-base: CARD32, + + + root-input-masks: LISTofSETofEVENT] + + + CONDIFROOT: [resource-id-base: +CARD32, + + + root: WINDOW + + + root-visual: VISUALID + + + default-colormap: COLORMAP + + + white-pixel, black-pixel: CARD32 + + + root-input-masks: LISTofSETofEVENT] + + + + + + +Errors: LbxClient, Alloc + + + + +This request, which is sent by the proxy over the control connection, creates a +new virtual connection to the server. + + + + +Much of the information in the +LbxNewClient + request and reply is identical to the connection setup and reply information +in the core X protocol. + + + + +For the +LbxNewClient + request, the field unique to LBX is client-id. For the +LbxNewClient + reply, +tag-id + and +change-type + are fields unique to LBX, and the contents of connection-data may be different +in LBX from the core X protocol (see below). + + + + +The proxy assigns each virtual connection a unique identifier using the + +client-id + field in the +LbxNewClient + request. This client-id is used in the LBX protocol to specify the current +client (see the +LbxSwitch + request and the +LbxSwitchEvent +). client-id 0 is reserved for the proxy control connection. An +LbxClient + error will result if the +LbxNewClient + request contains a client-id of 0 or an already in use client-id. + + + + +If the server rejects this new virtual connection, the server sends a core X +connection failure reply to the proxy. The current version of LBX does not +support the return of an +Authenticate + reply. + + + + +If the +change-type + field is set to +NoDeltas +, then +connection-data + is sent using the CONINFO structure, which is identical to the additional data +of the core connection reply. If the +tag-id + is non-zero, then the connection-data is stored by the proxy using this tag +value. Tagged connection data must be stored by the proxy, and can not be +invalidated by the proxy until an +LbxInvalidateTag + event is received for that tag. + + + + +When the +change-type + field is not set to +NoDeltas +, then connection data is sent as changes against connection information +previously sent to the proxy. The +tag-id + field, if non-zero, has the tag of the previously sent data to apply the +changes to. A zero tag-id indicates that the changes are with respect to the +connection information sent when the proxy connected to the server. + + + + +If the +change-type + field is set to +NormalClientDeltas +, then +connection-data + is sent using the CONDIF structure. The values in the CONDIF structure are +substituted for the identically named fields of the connection information for +the new connection. + + + + +If the +change-type + field is set to +AppGroupDeltas +, then +connection-data + is sent using the CONDIFROOT structure. The +root +, +root-visual +, and +default-colormap + fields, when nonzero, are substituted for the corresponding fields in the +reference connection information. The +white-pixel + and +black-pixel + fields are substituted only when the +default-colormap + field of the reply is non-zero. When +default-colormap + field of the reply is zero, so are +white-pixel + and +black-pixel +. The first entry in the +root-input-masks + field is the current-input-mask for the default root window. The remaining +entries in +root-input-masks + are input masks for non-video screens, as defined by the X Print Extension. +The number of non-video screens is one less than the number of entries in + +root-input-masks +. These screens are at the end of screen list in the reference connection +information. + + + + +The encoding for this request is on See The +description of this request is on page 13.. + + + + + + + + + LbxCloseClient + + + + + +client +: CARD32 + + + + Errors: +LbxClient + + + + + + + +This requests the server to close down the connection represented by the +specified proxy’s client identifier. If the specified client wasn’t +previously registered with the server by a +LbxNewClient + request, the server will send the +LbxClient + error. + + + + +The encoding for this request is on See The +description of this request is on page 12.. + + + + + + + + + LbxSwitch + + + + + +client +: CARD32 + + + + Errors: +LbxClient + + + + + + + +This request causes the X server to treat subsequent requests as being from a +connection to the X server represented by the specified client identifier. + + + + +If the client making the request is not the proxy, or if the client identifier +sent in the request was not previously sent in a +LbxNewClient + request, an +LbxClient + error is returned. + + + + +The encoding for this request is on See +LbxSwitch. + + + + + + + + + LbxSync + + + + + => + + + + + + +The sync request causes the server to send a reply when all requests before the +sync request have been processed. + + + + +The encoding for this client is on See +LbxSync. + + + + + + + + + LbxModifySequence + + + + + +adjust +: CARD32 + + + + Errors: None + + + + + + +This request advances the sequence number of the virtual client connection by +the specified amount. The proxy sends the +LbxModifySequence + request to the server when it replies to a client request without forwarding +the client request on to the X server. + + + + +The encoding for this client is on See The +description of this request is on page 13.. + + + + + + + + + LbxAllowMotion + + + + + +num +: CARD32 + + + + Errors: None + + + + + + +This request controls the delivery of optional motion notify events, as +described in See Motion events. The num +field specifies an increase in the allowed number of motion notify events sent. + + + + +The encoding for this request is on See The +description of this request is on page 14.. + + + + + + + + + LbxInvalidateTag + + + + + +tag +: CARD32 + + + + + + +The LBX proxy sends this notification to the X server when it refuses to store +tagged data, or when it releases tagged data which was previously stored and +which was not invalidated by a notification from the X server. + + + + +The encoding for this request is on See +LbxInvalidateTag. + + + + + + + + + LbxTagData + + + + + +tag +: CARD32 + + + +real-length +: CARD32 + + + +data +: LISTofBYTE + + + + + + +This request specifies the data associated with a previously assigned tag. It +is sent in two circumstances: in response to receiving a +SendTagDataEvent +, and spontaneously, when the proxy must rely on the server to store data which +was not previously received from the server. The data is carried in the byte +order and structure as would have originally been sent in the core protocol +request. + + + + +The encoding for this request is on See +LbxTagData. + + + + + + + + + LbxGrabCmap + + + + + +cmap +: Colormap + + + => + + + + +smart-grab +: BOOL + + + +large-pixel: +BOOL /* optional */ + + + +auto-release: +BOOL /* optional */ + + + +three-channels +: BOOL /* optional */ + + + +bits-per-rgb: +CARD4 /* optional */ + + + +cells +: LISTofCHAN /* optional */ + + +   + + + where: + + + CHAN: LISTofLBXPIXEL + + + LBXPIXEL: PIXELPRIVATE or PIXELPRIVATERANGE +or + + + PIXELALLOC or PIXELALLOCRANGE + + + PIXEL: CARD8 or CARD16 + + + PIXELPRIVATE: [ pixel: PIXEL ] + + + PIXELPRIVATERANGE: [ first-pixel, +last-pixel: PIXEL] + + + PIXELALLOC: [ pixel: PIXEL, + + + color: COLORSINGLE or COLORTRIPLE] + + + PIXELALLOCRANGE: [ first-pixel, +last-pixel: PIXEL, + + + colors: LISTofCOLORSINGLE or +LISTofCOLORTRIPLE] + + + COLORSINGLE: [ value: CARD8 or CARD16 +] + + + COLORTRIPLE: [ r, g, b: +COLORSINGLE] + + + + Errors: +Colormap + + + + + + + +This request asks the server for control of allocating new colormap cells in +the specified colormap. The server grants control by replying to this request. +If no changes have occurred since the last time this proxy grabbed this +colormap, then the +smart-grab + field of the reply is set to true, and the optional fields are not sent. +Otherwise, the current contents of the colormap are placed in the reply, as +described later in this section. + + + + +Once the proxy has received the reply, it can use the +LbxAllocColor + request to allocate new colormap cells without the performance penalty of +round trips. The proxy is still permitted to use the normal colormap and + +LbxIncrementPixel + requests while the colormap is grabbed. The grab is valid across all virtual +connections of the proxy. + + + + +The +LbxGrabCmap + request is limited to colormaps for the visual types negotiated as part of the +colormap algorithm negotiation in the start proxy request at connection setup. + + + + +The server and other proxies may not allocate new colormap cells in the +colormap while the colormap is grabbed by this proxy. If the server or another +proxy needs to allocate new colormap cells, the server sends a Lbx +ReleaseCmap + event to the proxy holding the grab, which then issues an +LbxReleaseCmap + request. + + + + +The server and other proxies may free colormap cells in a colormap grabbed by a +proxy. The server will send an +LbxFreeCells + event to the proxy that currently has the colormap grabbed when the cell +reference count reaches 0. + + + + +If the colormap is a of a static visual type, such as +StaticGray +, +StaticColor +, +GrayScale +, or +TrueColor +, then the proxy’s grab is immediately released by the server, and the proxy +must use +LbxIncrementPixel + requests in place of +LbxAllocColor + requests for this colormap. + + + + +If the cmap field does not refer to a valid colormap or the colormap is already +grabbed by this proxy then a +Colormap + error is generated. + + + + +The reply describes the contents of the colormap via several arguments and a +descriptive list containing one or three channels, with each channel describing +allocations in the colormap. + + + + +The +large-pixel + argument, if True, specifies that PIXEL indices will be listed as CARD16 +quantities instead of CARD8. The + auto-release + field, if True, indicates that this colormap is of a static visual type and +the proxy’s grab is immediately released by the server. + + + + +If +three-channels + is False, a single channel is enclosed and color values are described using +COLORTRIPLE, which has fields for red, green and blue. A single channel is used +when the visual type is not +DirectColor + or +TrueColor +. + + + + +If +three-channels + is True, separate red, green and blue channel lists are enclosed, for +describing a +DirectColor + or +TrueColor + colormap. Color values for entries in each channel are sent using COLORSINGLE +and the corresponding PIXEL value refers to the RGB subfield of the current +channel, as defined by the corresponding red-mask, green-mask and blue-mask of +the visual. + + + + +The +bits-per-rgb + value is one less than the bits-per-rgb-value field of the visual that the +colormap belongs to. If the value is 7 or less, then COLORSINGLE values in the +descriptive list are sent using CARD8 fields. Otherwise these values are sent +using CARD16 fields. + + + + +The list describing current colormap allocations contains entries of the +following types: + + + + +An LBXPIXELPRIVATE entry indicates that the pixel in the +pixel +field is unavailable for allocation. + + + + +An LBXPIXELPRIVATERANGE entry indicates that a contiguous range of pixels are +unavailable for allocation. The range is +first-pixel + to +last-pixel +, and includes +last-pixel +. + + + + +An LBXPIXELALLOC entry indicates that the pixel in the +pixel +field is allocated as a read-only pixel. The +color + field carries the color information of the pixel. + + + + +An LBXPIXELALLOCRANGE entry indicates that a contiguous range of pixels are +allocated as read-only. The range starts +first-pixel + to +last-pixel +, and includes +last-pixel +. These fields are followed by a list of COLORSINGLE or COLORTRIPLE, depending +on the value of +three-channels +. + + + + +A NEXTCHANNEL entry indicates that the next channel of the colormap will be +described. + + + + +A LISTEND entry indicates the end of the colormap description. + + + + +All pixels not described in the reply are unallocated. + + + + +The encoding for this request is on See +LbxGrabCmap. + + + + + + + + + + LbxReleaseCmap + + + + + +cmap +: Colormap + + + + + + +This request releases the specified grabbed colormap. If the +cmap + field does not refer to a colormap, a +BadColormap + error is produced. + + + + +The proxy must remember the state of the colormap when the +LbxReleaseCmap + request is issued if this proxy may at some future time issue another + +LbxGrabCmap + request on this colormap before the state of the colormap changes. + + + + +The encoding for this request is on See +LbxReleaseCmap. + + + + + + + + + LbxInternAtoms + + + + + +count +: CARD16 + + + +names: LISTofSTRING8 + + + + => + + + + +atoms +: LISTofATOM + + + + Errors: +Alloc + + + + + + + +This request allows the proxy to intern a group of atoms in a single round +trip. The server will create any atoms that do not exist. + + + + +The encoding for this request is on See +LbxInternAtoms. + + + + + + +Substitution Requests + + + + + + + LbxAllocColor + + + + + +cmap +: Colormap + + + +pixel +: CARD32 + + + +red +, +green +, +blue +: CARD16 + + + + + + +This request is sent by a proxy that has given colormap grabbed to allocate a +new read-only cell in the colormap. The proxy may substitute this request for +the core +AllocColor + and +AllocNamedColor + requests. + + + + +The +pixel + field identifies the colormap cell to allocate. The +red +, +green +, and +blue + fields are the hardware specific color values of the corresponding fields of +the core +AllocColor + request. The mapping to hardware specific colormap values by the proxy is +performed using the color algorithm negotiated by +LbxStartProxy +. + + + + +For colormaps of static visual types, the +LbxIncrementPixel + request is used instead of LBX +AllocColor +. + + + + +If the +cmap + field does not identify a grabbed colormap then a +BadAccess + error is produced. If the +pixel + field refers to a read-write entry, or the pixel field refers to a pixel +outside of the range of this colormap, a +BadAlloc + error is produced. + + + + +The encoding for this request is on See +LbxAllocColor. + + + + + + + + + LbxIncrementPixel + + + + + +cmap +: COLORMAP + + + +pixel +: CARD32 + + + + Errors: None + + + + + + +This request replaces the +AllocColor + request for read-only pixels currently allocated for the current client. If +the visual type of the colormap is of a static type, this request may be used +on currently unallocated pixels. The colormap is not required to be grabbed to +use this request. + + + + +The encoding for this request is on See The +description of this request is on page 14.. + + + + + + + + + LbxDelta + + + + + +count +: CARD8 + + + +cache-index +: CARD8 + + + +diffs +: LISTofDIFFITEM + + + + + + +This request contains a minimal amount of information relative to a similar +prior request. The information is in the form of a difference comparison to a +prior request. The prior request is specified by an index to a cache, +independently maintained by both the proxy and the server. + + + + +The encoding for this request is on See The +description of this request is on page 18.. + + + + + + + + + LbxGetModifierMapping + + + + + => + + + + +keyspermod +: CARD8 + + + +tag +: CARD32 + + + +keycodes +: LISTofKEYCODE /* optional */ + + + + + + +This request is identical to the core +GetModifierMapping + request, with the addition of a tag being returned in the reply. See See Tag Substitution in Requests for a description +of the +tag + field and optional fields. + + + + +The encoding for this request is on See +LbxGetModifierMapping. + + + + + + + + + LbxGetKeyboardMapping + + + + + +firstKeyCode +: KEYCODE + + + +count +: CARD8 + + + => + + + + +keysperkeycode +: CARD8 + + + +tag +: CARD32 + + + +keysyms +: LISTofKEYSYM /* optional */ + + + + Errors: +Value + + + + + + + +This request is identical to the X +GetKeyboardMapping + protocol request, with the addition that a tag is returned in the reply. See +See Tag Substitution in Requests for a +description of the +tag + field and optional fields. + + + + +The encoding for this request is on See +LbxGetKeyboardMapping. + + + + + + + + + + LbxGetWinAttrAndGeom + + + + + +window +: WINDOW + + + => + + + + visual: VISUALID + + + class: {InputOutput, InputOnly} + + + bit-gravity: BITGRAVITY + + + win-gravity: WINGRAVITY + + + backing-store: {NotUseful, WhenMapped, +Always} + + + backing-planes: CARD32 + + + backing-pixel: CARD32 + + + save-under: BOOL + + + colormap: COLORMAP or None + + + map-is-installed: BOOL + + + map-state: {Unmapped, Unviewable, +Viewable} + + + all-event-masks, your-event-mask: +SETofEVENT + + + do-not-propagate-mask: SETofDEVICEEVENT + + + override-redirect: BOOL + + + root: WINDOW + + + depth: CARD8 + + + x, y: INT16 + + + width, height, border-width: CARD16 + + + + Errors: +Window + + + + + + + + +GetWindowAttributes + and +GetGeometry + are frequently used together in the X protocol. +LbxGetWinAttrAndGeom + allows the proxy to request the same information in one round trip. + + + + +The encoding for this request is on See +LbxGetWinAttrAndGeom. + + + + + + + + + + LbxQueryFont + + + + + +font +: FONTABLE + + + => + + + compression: BOOL + + + tag: CARD32 + + + font-info: FONTINFO /* optional +*/ + + + char-infos: LISTofCHARINFO or LISTofLBXCHARINFO + /* optional */ + + + where: + + + LBXCHARINFO: [left-side-bearing: +INT6 + + + right-side-bearing: INT7 + + + character-width: INT6 + + + ascent: INT6 + + + descent: INT7] + + + + Errors: +Font,Alloc + + + + + + + +This request is used to replace the core +QueryFont + request and has identical semantics. + + + + +See See Tag Substitution in Requests for a +description of the +tag + field and optional fields. + + + + +The +compression + field is True if the +char-infos + field is represented using LBXCHARINFO. + + + + +The per-character information will be encoded in an LBXCHARINFO when, for every +character, the character-width, left-side-bearing, and ascent can each be +represented in not more than 6 bits, and the right-side-bearing and descent can +each be represented in not more than 7 bits, and the attributes field is +identical the attributes field of the max_bounds of the +font_info + field of the font. + + + + +The encoding for this request is on See +LbxQueryFont. + + + + + + + + + + LbxChangeProperty + + + + + +window +: WINDOW + + + +property +: ATOM + + + +type +: ATOM + + + +format +: {0,8,16,32} + + + +mode +: {Replace, Prepend, Append} + + + +nUnits +: CARD32 + + + => + + + tag: CARD32 + + + + + + +This request is sent to the server when the client sends an X +ChangeProperty +request through the proxy. The size of the data is sent with this request, but +not the property data itself. The server reply contains a tag identifier for +the data, which is stored in the proxy. The proxy must not discard this data +before it is sent to the server, or invalidated by the server. This means that +before issuing an +LbxStopProxy + request, or exiting, the proxy must send Lbx +TagData + requests for these items. If the server loses the connection before the +information is sent back, the server should revert the property value to its +last known value, if possible. + + + + +If the +mode + field is +Prepend + or +Append +, the tag refers only to the prepended or appended data. + + + + +If the tag in the reply is zero, then the change was ignored by the server, as +defined in the security extension. The proxy should dump the associated data, +since the server will never ask for it. + + + + +The encoding for this request is on See +LbxChangeProperty. + + + + + + + + + LbxGetProperty + + + + + +window +: WINDOW + + + +property +: ATOM + + + +type +: ATOM or AnyPropertyType + + + +long-offset +: CARD32 + + + +long-length +: CARD32 + + + +delete +: CARD8 + + + => + + + + type: ATOM or None + + + format: {0, 8, 16, 32} + + + bytes-after: CARD32 + + + nItems: CARD32 + + + tag: CARD32 + + + value: LISTofINT8 or LISTofINT16 or +LISTofINT32 + + + + + + +This request may be used by the proxy as a substitution for a core +GetProperty + request. It allows tags to be used for property data that is unlikely to +change often in value, but is likely to be fetched by multiple clients. + + + + +The +LbxGetProperty + request has the same arguments as the core +GetProperty + request. The reply for +LbxGetProperty + has all of the fields from the core +GetProperty + reply, but has the additional fields of +nItems + and +tag +. + + + + +In order to utilize tags in +LbxGetProperty + for a specific property, the server must first send the complete property data +to the proxy and associate this data with a tag. More precisely, the server +sends an +LbxGetProperty + reply with a new +tag +, +nItems + set to the number of items in the property, the size of the property data in +the reply length field, and the complete property data in value. The proxy +stores the property data in its tag cache and associates it with the specified +tag. + + + + +In response to future +LbxGetProperty + requests for the same property, if the server thinks that the proxy has the +actual property data in its tag cache, it may choose to send an +LbxGetProperty + reply without the actual property data. In this case, the reply would include +a non-zero +tag +, a zero reply length, and no data for value. + + + + +If the server chooses not to generate a tagged reply to +LbxGetProperty +, or for some reason is unable to do so, it would send a reply with a +tag + of zero, the size of the property data in the reply length field, and the +complete property data in value. + + + + +The encoding for this request is on See +LbxGetProperty. + + + + + + + + + LbxPolyPoint + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +points +: LISTofLBXPOINT + + + + Errors: +Alloc + and those given for the corresponding X request. + + + + + + +This request replaces the +PolyPoint + request. Not all +PolyPoint + requests can be represented as +LbxPolyPoint + requests. + + + + +The proxy will convert the representation of the points to be relative to the +previous point, as described by previous coordinate mode in the X protocol. + + + + +The encoding for this request is on See +LbxPolyPoint. + + + + + + + + + LbxPolyLine + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +points +: LISTofLBXPOINT + + + + Errors: +Alloc + and those given for the corresponding X request. + + + + + + +This request replaces the +PolyLine + request. Not all +PolyLine + requests can be represented as +LbxPolyline + requests. + + + + +The proxy will convert the representation of the points to be relative to the +previous point, as described by previous coordinate mode in the X protocol. + + + + +The encoding for this request is on See The +description of this request is on page 21.. + + + + + + + + + LbxPolySegment + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +segments +: LISTofLBXSEGMENT + + +   + + + where: + + + LBXSEGEMENT; [x1, y1, x2, y2: LBXINT16] + + + + Errors: +Alloc + and those given for the corresponding X request. + + + + + + +This request replaces the +PolySegment + request. Not all +PolySegment + requests can be represented as +LbxPolySegment + requests. + + + + +For segments other than the first segment of the request, [x1, y1] is +relative to [x1, y1] of the previous segment. For all segments, [x2, y2] is +relative to that segment’s [x1, y1]. + + + + +The encoding for this request is on See +LbxPolySegment. + + + + + + + + + LbxPolyRectangle + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +rectangles +: LISTofLBXRECTANGLE + + + + Errors: +Alloc + and those given for the corresponding X request. + + + + + + +This request replaces the +PolyRectangle + request. Not all +PolyRectangle + requests can be represented as +LbxPolyRectangle + requests. + + + + +The encoding for this request is on See The +description of this request is on page 22.. + + + + + + + + + LbxPolyArc + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +arcs +: LISTofLBXARC + + + + Errors: +Alloc + and those given for the corresponding X request. + + + + + + +This request replaces the +PolyArc + request. Not all +PolyArc + requests can be represented as +LbxPolyArc + requests. + + + + +The encoding for this request is on See +LbxPolyArc. + + + + + + + + + LbxPolyFillRectangle + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +rectangles +: LISTofLBXRECTANGLE + + + + Errors: +Alloc + and those given for the corresponding X request. + + + + + + +This request replaces the +PolyFillRectangle + request. Not all +PolyFillRectangle + requests can be represented as +LbxPolyFillRectangle + requests. + + + + +The encoding for this request is on See +LbxPolyFillRectangle. + + + + + + + + + LbxPolyFillArc + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +arcs +: LISTofLBXARC + + + + Errors: +Alloc + and those given for the corresponding X request. + + + + + + +This request replaces the +PolyFillArc + request. Not all +PolyFillArc + requests can be represented as +LbxPolyFillArc + requests. + + + + +The encoding for this request is on See The +description of this request is on page 22.. + + + + + + + + + LbxFillPoly + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +shape +: BYTE + + + +points +: LISTofLBXPOINT + + + + Errors: +Alloc + and those given for the corresponding X request. + + + + + + +This request replaces the +FillPoly + request. Not all +FillPoly + requests can be represented as +LbxFillPoly + requests. + + + + +The proxy will convert the representation of the points to be relative to the +previous point, as described by previous coordinate mode in the X protocol. + + + + +The encoding for this request is on See +LbxFillPoly. + + + + + + + + + LbxCopyArea + + + + + +srcCache +: CARD8 /* source drawable */ + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +src-Drawable +: CARD32 + + + +src-x +: LBXPINT16 + + + +src-y +: LBXPINT16 + + + +width +: LBXCARD16 + + + +height +: LBXCARD16 + + + +dst-x +: LBXPINT16 + + + +dst-y +: LBXPINT16 + + + + Errors: Those given for the corresponding X +request. + + + + + + +This request replaces the +CopyArea + request for requests within its encoding range. + + + + +The encoding for this request is on See +LbxCopyArea. + + + + + + + + + LbxCopyPlane + + + + + +bit-plane +: CARD32 + + + +src-cache +: CARD8 /* cache reference for source drawable */ + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +src-drawable +: CARD32 + + + +src-x +: LBXPINT16 + + + +src-y +: LBXPINT16 + + + +width +: LBXCARD16 + + + +height +: LBXCARD16 + + + +dst-x +: LBXPINT16 + + + +dst-y +: LBXPINT16 + + + + Errors: Those given for the corresponding X +request. + + + + + + +This request replaces the +CopyPlane + request for requests within its coding range. + + + + +The encoding for this request is on See +LbxCopyPlane. + + + + + + + + + LbxPolyText8 + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +x +: LBXPINT16 + + + +y +: LBXPINT16 + + + +items +: LISTofTEXTITEM8 + + + + Errors: +Alloc +, and those given for the corresponding X request. + + + + + + +This request replaces the +PolyText8 + request for requests within its encoding range. + + + + +The encoding for this request is on See The +description of this request is on page 23.. + + + + + + + + + LbxPolyText16 + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +x: + LBXPINT16 + + + +y +: LBXPINT16 + + + +items +: LISTofTEXTITEM16 + + + + Errors: +Alloc +, and those given for the corresponding X request. + + + + + + +This request replaces the +PolyText16 + request for requests within its encoding range. + + + + +The encoding for this request is on See The +description of this request is on page 24.. + + + + + + + + + LbxImageText8 + + + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +nChars +: CARD8 + + + +x +: LBXPINT16 + + + +y +: LBXPINT16 + + + +string +: STRING8 + + + + Errors: +Alloc +, and those given for the corresponding X request. + + + + + + +This request replaces the +ImageText8 + request for requests within its encoding range. + + + + +The encoding for this request is on See The +description of this request is on page 24.. + + + + + + + + + LbxImageText16 + + + + + +nChars +: CARD8 + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + x: LBXPINT16 + + + +y +: LBXPINT16 + + + +string +: STRING16 + + + + Errors: +Alloc +, and those given for the corresponding X request. + + + + + + +This request replaces the +ImageText16 + request for requests within its encoding range. + + + + +The encoding for this request is on See The +description of this request is on page 24.. + + + + + + + + + LbxPutImage + + + + + +compression-method +: CARD8 + + + +format +: { +Bitmap +, +XYPixmap +, +ZPixmap +} /* packed */ + + + +gc-and-drawable: +LBXGCANDDRAWABLE + + + +width +, +height +: LBXCARD16 + + + +dst-x +, +dst-y +: LBXPINT16 + + + +depth +: CARD8 /* packed */ + + + +left-pad +: CARD8 /* packed */ + + + +pad-bytes +: CARD8 /* packed */ + + + +data +:LISTofBYTE + + + + Errors: +Alloc +, +Value + + + + + + + +When the request can be usefully compressed, this request replaces the + +PutImage + request. The +compression-method + parameter contains the opcode of a compression method returned in the + +LbxStartProxy + reply. The +pad-bytes + parameter gives the number of unused pad bytes that follow the compressed +image data. All other parameters are as in the X request. If the specified +compression method is not recognized, the server returns a +Value + error. + + + + +The encoding for this request is on See +LbxPutImage. + + + + + + + + + LbxGetImage + + + + + +drawable +: DRAWABLE + + + +x +, +y +: INT16 + + + +width +, +height +: CARD16 + + + +plane-mask +: CARD32 + + + +format +: {XYPixmap, ZPixmap} + + + => + + + depth: CARD8 + + + x-length: CARD32 + + + visual: VISUALID or None + + + compression-method: CARD8 + + + data: LISTofBYTE + + + + Errors: +Alloc,Match,Value + + + + + + + +This request can replace the +GetImage + request. The same semantics apply, with the following exceptions. + + + + +The +compression-method + field contains the opcode of the compression method used in the reply. The +compression opcodes are supplied in the +LbxStartProxy + reply. The +x-length +field + +contains the length of the uncompressed version of the reply in 4 byte units. + + + + +A +Value + error is returned if the format is not recognized by the X server. A +Match + error is returned under the same circumstances as described by the +GetImage + request. + + + + +The encoding for this request is on See +LbxGetImage. + + + + + + + + + + LbxBeginLargeRequest + + + + + +large-request-length +: CARD32 + + + + Errors: +Alloc + + + + + + + +This request, along with the Lbx +LargeRequestData + and Lbx +EndLargeRequest + requests, is used to transport a large request in pieces. The smaller size of +the resulting requests allows smoother multiplexing of clients on a single low +bandwidth connection to the server. The resulting finer-grained multiplexing +improves responsiveness for the other clients. + + + + +After a +LbxBeginLargeRequest + request is sent, multiple +LbxLargeRequestData + requests are sent to transport all of the data in the large request, and +finally an +LbxEndLargeRequest + request is sent. The large-request-length field expresses the total length of +the transported large request, expressed as the number of bytes in the +transported request divided by four. + + + + +The encoding for this request is on See The +description of this request is on page 25.. + + + + + + + + + LbxLargeRequestData + + + + + +data +: LISTofBYTE + + + + Errors: +Alloc + + + + + + + +This request is used to carry the segments of a larger request, as described in +the definition of +LbxBeginLargeRequest +. The data must be carried in order, starting with the request header, and each +segment must be multiples of 4 bytes long. If the +LbxLargeRequestData + is not preceded by a corresponding +LbxBeginLargeRequest +, a +BadAlloc + error is generated. + + + + +The encoding for this request is on See The +description of this request is on page 26.. + + + + + + + + + LbxEndLargeRequest + + + + + Errors: +Length, Alloc + + + + + + + +As described in the definition of +LbxBeginLargeRequest +, +LbxEndLargeRequest + is used to signal the end of a series of +LargeRequestData + requests. If the total length of the data transported by the +LbxLargeRequestData + requests does not match the large-request-length field of the preceding + +LbxBeginLargeRequest + request, then a +Length + error occurs. If the +LbxEndLargeRequest + is not preceded by a corresponding +LbxBeginLargeRequest +, a +BadAlloc + error is generated. The request is executed in order for that client as if it +were the request after the request preceding +LbxEndLargeRequest +. + + + + +The encoding for this request is on See +LbxEndLargeRequest. + + + + + + + +Events + + + + + + + LbxSwitchEvent + + + + + +client +: CARD32 + + + + + + +Notify the proxy that the subsequent replies, events, and errors are relative +to the specified client. + + + + +The encoding for this event is on See +LbxSwitchEvent. + + + + + + + + + LbxCloseEvent + + + + + +client +: CARD32 + + + + + + +Notify the proxy that the specified client's connection to the server is closed. + + + + +The encoding for this event is on See The +description of this event is on page 27.. + + + + + + + + + LbxInvalidateTagEvent + + + + + +tag +: CARD32 + + + +tag-type +: {Modmap, Keymap, Property, Font, ConnInfo} + + + + + + +This message informs the proxy that the tag and the server data referenced by +the tag are obsolete, and should be discarded. The tag type may be one of the +following values: +LbxTagTypeModmap +, +LbxTagTypeKeymap +, +LbxTagTypeProperty +, +LbxTagTypeFont +, +LbxTagTypeConnInfo +. + + + + +The encoding for this event is on See +LbxInvalidateTagEvent. + + + + + + + + + LbxSendTagDataEvent + + + + + +tag +: CARD32 + + + +tag-type +: {Property} + + + + + + +The server sends this event to the proxy to request a copy of tagged data which +is being stored by the proxy. The request contains a tag which was previously +assigned to the data by the server. The proxy should respond to +SendTagData + by sending a +TagData + request to the server. The tag type may be one of the following values: + +LbxTagTypeProperty +. + + + + +The encoding for this event is on See +LbxSendTagDataEvent. + + + + + + + + + LbxListenToOne + + + + + +client +: CARD32 or +0xffffffff + + + + + + + +When the server is grabbed, +ListenToOne + is sent to the proxy. As an X client, the proxy itself is unaffected by grabs, +in order that it may respond to requests for data from the X server. + + + + +When the client grabbing the server is managed through the proxy, the proxy +will permit messages from itself and the grabbing client to be sent immediately +to the server, and may buffer requests from other clients of the proxy. The +client is identified in the event. + + + + +When the client grabbing the server is not managed through the proxy, the +client field in the event will be +0xffffffff +. The proxy will communicate with the server, and it may buffer requests from +other clients. The proxy will continue to handle new connections while the +server is grabbed. + + + + +The server will send +ListenToAll + to the proxy when the server is ungrabbed. There is no time-out for this +interval in the protocol. + + + + +The encoding for this event is on See The +description of this event is on page 27.. + + + + + + + + + LbxListenToAll + + + + + + +Notify the proxy that the server has been ungrabbed, and that the proxy may now +send all buffered client requests on to the server. + + + + +The encoding for this event is on See The +description of this event is on page 27.. + + + + + + + + + LbxQuickMotionDeltaEvent + + + + + +deltaTime +: CARD8 + + + +deltaX +: INT8 + + + +deltaY +: INT8 + + + + + + +This event is used as a replacement for the +MotionNotify + event when possible. The fields are used as deltas to the most recent + +MotionNotify + event encoded as a +MotionNotify + event, +LbxQuickMotionDeltaEvent +, or +LbxMotionDeltaEvent +. Not every +MotionNotify + event can be encoded as a +LbxQuickMotionDeltaEvent +. + + + + +The encoding for this event is on See +LbxQuickMotionDeltaEvent. + + + + + + + + + LbxMotionDeltaEvent + + + + + +deltaX +: INT8 + + + +deltaY +: INT8 + + + +deltaTime +: CARD16 + + + +deltaSequence +: CARD16 + + + + + + +This event is used as a replacement for the +MotionNotify + event when possible. The fields are used as deltas to the most recent + +MotionNotify + event encoded as a +MotionNotify + event, +LbxQuickMotionDeltaEvent +, or +LbxMotionDeltaEvent +. Not every +MotionNotify + event can be encoded as +a LbxMotionDeltaEvent +. + + + + +The encoding for this event is on See +LbxMotionDeltaEvent. + + + + + + + + + LbxReleaseCmapEvent + + + + + +colormap +: Colormap + + + + + + +This event notifies the proxy that it must release the grab on this colormap +via the ReleaseCmap request. See +LbxReleaseCmap + + + + +The encoding for this event is on See +LbxReleaseCmapEvent. + + + + + + + + + LbxFreeCellsEvent + + + + + +colormap +: Colormap + + + +pixelStart, pixelEnd +: CARD32 + + + + + + +The +LbxFreeCells + event is sent to a proxy that has a colormap grabbed to notify the proxy that +the reference count of the described cells were decremented to zero by the +server or another proxy. The reference count includes those by this proxy. The +proxy must update its copy of the colormap state accordingly if the colormap is +still grabbed, or if the proxy may in the future grab the colormap using +smart-grab mode. See LbxGrabCmap + + + + +The pixelStart and pixelEnd fields of the event denote a continuous range of +cells that were freed. + + + + +The encoding for this event is on See +LbxFreeCellsEvent. + + + + +Responses + + +Responses are messages from the server to the proxy that not, strictly +speaking, events, replies or errors. + + + + + + + + LbxDeltaResponse + + + + + +count +: CARD8 + + + +cache-index +: CARD8 + + + +diffs +: LISTofDIFFITEM + + + + + + +This response carries an event, reply, or error that has been encoded relative +to a message in the response delta cache. The +cache-index + field is the index into the cache. Each entry in +diffs + provides a byte offset and replacement value to use in reconstructing the +response. + + + + +The encoding for this event is on See +LbxDeltaResponse. + + + + + + +Algorithm Naming + + +To avoid potential clashes between different but similar algorithms for stream, +bitmap, and pixmap compression, the following naming scheme will be adhered to: + + + + +Each algorithm has a unique name, which is a STRING8, of the following form: + + + + + <organization>-<some-descriptive-name> + + + + +The organization field above is the organization name as registered in section +1 of the X Registry (the registry is provided as a free service by the X +Consortium.) This prevents conflicts among different vendor’s extensions. + + + + +As an example, the X Consortium defines a zlib-based stream compression +algorithm called XC-ZLIB. + + + + + +Encoding + + +The syntax and types used in the encoding are taken from the X protocol +encoding. Where LBX defines new types, they are defined earlier in this +document. + + + + +As in the X protocol, in various cases, the number of bytes occupied by a +component will be specified by a lowercase single-letter variable name instead +of a specific numeric value, and often some other component will have its value +specified as a simple numeric expression involving these variables. Components +specified with such expressions are always interpreted as unsigned integers. +The scope of such variables is always just the enclosing request, reply, error, +event, or compound type structure. + + + + +For unused bytes, the encode-form is: + + + +N unused + + + +If the number of unused bytes is variable, the encode-form typically is: + + + +p unused, p=pad(E) + + + +where E is some expression, and pad(E) is the number of bytes needed to round E +up to a multiple of four. + + + + +pad(E) = (4 - (E mod 4)) mod 4 + + + + +In many of the encodings, the length depends on many variable length fields. +The variable L is used to indicate the number of padded 4 byte units needed to +carry the request. Similarly, the variable Lpad indicates the number of bytes +needed to pad the request to a 4 byte boundary. + + + +For counted lists there is a common encoding of NLISTofFOO: + + + +NLISTofFOO +1 m num items +m LISTofFOO items + + + +For cached GC and Drawables: + + + +LBXGCANDDRAWUPDATE +4 or 0 DRAWBLE optional drawable +4 or 0 GC optional GC + + + + + +LBXGCANDDRAWABLE +8 LBXGCANDDRAWENT cache-entries +8 unused +m LBXGCANDDRAWUPDATE optional GC and Drawable + + + + +Errors + + +LbxClient +1 0 Error +1 CARD8 error-base + 0 +2 CARD16 sequence number +4 unused +2 CARD16 lbx opcode +1 CARD8 major opcode +21 unused + + + + +Requests + + +LbxQueryVersion +1 CARD8 opcode +1 0 lbx opcode +2 1 request length +=> +1 1 Reply +1 unused +2 CARD16 sequence number +4 0 reply length +2 CARD16 major version +2 CARD16 minor version +20 unused + + + +The description of this request is on See +LbxQueryVersion. + + + + +LbxStartProxy +1 CARD8 opcode +1 1 lbx opcode +2 L request length +n NLISTofOPTION-REQUEST options +p unused, p=pad(n) + +OPTION-REQUEST +1 OPTCODE option-code +m OPTLEN option-request-byte-length, (b=m+a+1) +a DELTAOPT or option + NLISTofNAMEDOPT or + NLISTofSTR or + NLISTofPIXMAPMETHOD or + BOOL + + + +The encoding of the option field depends on the option-code. +See See StartProxy Options. + + + +1 OPTCODE option-code +0 LbxOptionDeltaProxy +1 LbxOptionDeltaServer +2 LbxOptionStreamCompression +3 LbxOptionBitmapCompression +4 LbxOptionPixmapCompression +5 LbxOptionMessageCompression /* also known as squishing */ +6 LbxOptionUseTags +7 LbxOptionColormapAllocation +255 LbxOptionExtension + + + +OPTLEN has two possible encodings, depending on the size of the value carried: + + + +OPTLEN +1 CARD8 b (0 < b <= 255) + +OPTLEN +1 0 long length header +1 c length0, c = b >> 8 +1 d length1, d= b & #xff + +DELTAOPT +1 CARD8 min-cache-size +1 CARD8 max-cache-size +1 CARD8 preferred-cache-size +1 CARD8 min-message-length +1 CARD8 max-message-length (in 4-byte units) +1 CARD8 preferred-message-length + +NAMEDOPT +f STR type-name +1 g+1 option-data-length +g LISTofBYTE option-data (option specific) + +PIXMAPMETHOD +h STR name +1 BITMASK format mask +1 j depth count +j LISTofCARD8 depths + +=> +=> + +1 1 Reply +1 CARD8 count + +0xff options in request cannot be decoded +2 CARD16 sequence number +4 (a+p-32)/4 reply length +a LISTofCHOICE options-reply +p unused, if (n<24) p=24-n else p=pad(n) + +CHOICE +1 CARD8 request-option-index +b OPTLEN reply-option-byte-length +c DELTACHOICE or choice + INDEXEDCHOICE or + NLISTofINDEXEDOPT or + NLISTofPIXMAPCHOICE or + BOOL or + INDEXEDCHOICE + + + +The encoding of the choice field depends on the option-code. See See StartProxy Options. + + + +DELTACHOICE +1 CARD8 preferred cache size +1 CARD8 preferred message length in 4-byte units + +INDEXEDCHOICE +1 CARD8 index +d LISTofBYTE data + +PIXMAPCHOICE +1 CARD8 index +1 CARD8 opcode +1 BITMASK format mask +e NLISTofCARD8 depths + + + +The description of this request is on See +LbxStartProxy. + + + + +LbxStopProxy +1 CARD8 opcode +1 2 lbx opcode +2 1 request length + + + +The description of this request is on See +LbxStopProxy. + + + + +LbxSwitch +1 CARD8 opcode +1 3 lbx opcode +2 2 request length +4 CARD32 client + + + +The description of this request is on +See LbxSwitch. + + + + +LbxNewClient +1 CARD8 opcode +1 4 lbx opcode +2 L request length +4 CARD32 client +The remaining bytes of the request are the core connection setup. +=> +If the connection is rejected, a core connection reply is sent. Otherwise the +reply has the form: +1 BOOL success +1 change type + 0 no-deltas + 1 normal-client-deltas + 2 app-group-deltas +2 CARD16 major version +2 CARD16 minor version +2 1 + a length +4 CARD32 tag id + + + +The remaining bytes depend on the value of change-type and length. + + + +For no-deltas, the remaining bytes are the "additional data" +bytes of the core reply. (a = length of core reply, in 4 byte quantities). + + + +For normal-client-deltas, the additional bytes have the form, with a length (a += 1 +b): + + + +4 CARD32 resource id base +4b LISTofSETofEVENT root input masks + + + +For app-group-deltas, the additional bytes have the following form, with a +length of (a = 1 + 4c): + + + +4 CARD32 resource id base +4 WINDOW root id base +4 VISUALID visual +4 COLORMAP colormap +4 CARD32 white pixel +4 CARD32 black pixel +4c LISTofSETofEVENT root input masks + + + +The description of this request is on +See LbxNewClient. + + + + +LbxCloseClient +1 CARD8 opcode +1 5 lbx opcode +2 2 request length +4 CARD32 client + + + +The description of this request is on +See LbxCloseClient. + + + + +LbxModifySequence +1 CARD8 opcode +1 6 lbx opcode +2 2 request length +4 CARD32 offset to sequence number + + + +The description of this request is on See +LbxModifySequence. + + + + +LbxAllowMotion +1 CARD8 opcode +1 7 lbx opcode +2 2 request length +4 CARD32 number of MotionNotify events + + + +The description of this request is on See +LbxAllowMotion. + + + + +LbxIncrementPixel +1 CARD8 opcode +1 8 lbx opcode +2 3 request length +4 COLORMAP colormap +4 CARD32 pixel + + + +The description of this request is on See +LbxIncrementPixel. + + + + +LbxDelta +1 CARD8 opcode +1 9 lbx opcode +2 1+(2n +p+2)/4 request length +1 n count of diffs +1 CARD8 cache index +2n LISTofDIFFITEM offsets and differences +p unused, p=pad(2n + 2) + + + +The description of this request is on See +LbxDelta. + + + + +LbxGetModifierMapping +1 CARD8 opcode +1 10 lbx opcode +2 1 request length +=> +1 1 Reply +1 n keycodes-per-modifier +2 CARD16 sequence number +4 2n reply length +4 CARD32 tag +20 unused +8n LISTofKEYCODE keycodes + + + +The description of this request is on See +LbxGetModifierMapping. + + + + +LbxInvalidateTag +1 CARD8 opcode +1 12 lbx opcode +2 2 request length +4 CARD32 tag + + + +The description of this request is on See +LbxInvalidateTag. + + + + +LbxPolyPoint +1 CARD8 opcode +1 13 lbx opcode +2 1+(m+n+p)/4 request length +m LBXGCANDDRAWABLE cache entries +n LISTofLBXPOINT points (n is data-dependent) +p 0 unused, p=Lpad + + + +The description of this request is on See +LbxPolyPoint. + + + + +LbxPolyLine +1 CARD8 opcode +1 14 lbx opcode +2 1+(m+n+p)/4 request length +m LBXGCANDDRAWABLE cache entries +n LISTofLBXPOINT points (n is data-dependent) +p 0 unused, p=Lpad + + + +The description of this request is on See +LbxPolyLine. + + + + +LbxPolySegment +1 CARD8 opcode +1 15 lbx opcode +2 1+(m+n+p)/4 request length +m LBXGCANDDRAWABLE cache entries +n LISTofLBXSEGMENT segments (n is data-dependent) +p 0 unused, p=Lpad + + + +The description of this request is on See +LbxPolySegment. + + + + +LbxPolyRectangle +1 CARD8 opcode +1 16 lbx opcode +2 1+(m+n+p)/4 request length +m LBXGCANDDRAWABLE cache entries +n LISTofLBXRECTANGLE rectangles (n is data-dependent) +p 0 unused, p=pad(m+n) + + + +The description of this request is on See +LbxPolyRectangle. + + + + +LbxPolyArc +1 CARD8 opcode +1 17 lbx opcode +2 1+(m+n+p)/4 request length +m LBXGCANDDRAWABLE cache entries +n LISTofLBXARCS arcs (n is data-dependent) +p 0 unused, p=Lpad + + + +The description of this request is on See +LbxPolyArc. + + + + +LbxFillPoly +1 CARD8 opcode +1 18 lbx opcode +2 1+(3+m+n+p)/4 request length +1 LBXGCANDDRAWENT cache entries +1 shape +0 Complex +1 Nonconvex +2 Convex +1 p pad byte count +m LBXGCANDDRAWUPDATE optional gc and drawable +n LISTofLBXPOINT points (n is data-dependent) +p 0 unused, p=Lpad + + + +The description of this request is on See +LbxFillPoly. + + + + +LbxPolyFillRectangle +1 CARD8 opcode +1 19 lbx opcode +2 1+(m+n+p)/4 request length +m LBXGCANDDRAWABLE cache entries +n LISTofLBXRECTANGLE rectangles (n is data-dependent) +p 0 unused, p=Lpad + + + +The description of this request is on See +LbxPolyFillRectangle. + + + + +LbxPolyFillArc +1 CARD8 opcode +1 20 lbx opcode +2 1+(m+n+p)/4 request length +m LBXGCANDDRAWABLE cache entries +n LISTofLBXARC arcs (n is data-dependent) +p 0 unused, p=Lpad + + + +The description of this request is on See +LbxPolyFillArc. + + + + +LbxGetKeyboardMapping +1 CARD8 opcode +1 21 lbx opcode +2 2 request length +1 KEYCODE first keycode +1 m count +2 unused +=> +1 1 Reply +1 n keysyms-per-keycode +2 CARD16 sequence number +4 nm reply length (m = count field from the request) +4 CARD32 tag +20 unused +4nm LISTofKEYSYM keysyms + + + +The description of this request is on See +LbxGetKeyboardMapping. + + + + +LbxQueryFont +1 CARD8 opcode +1 22 lbx opcode +2 2 request length +4 FONTABLE font +=> +1 1 Reply +1 BOOL compression +2 CARD16 sequence number +4 L reply length +4 CARD32 tag +20 unused +All of the following is conditional: +12 CHARINFO min-bounds +4 unused +12 CHARINFO max-bounds +4 unused +2 CARD16 min-char-or-byte2 +2 CARD16 max-char-or-byte2 +2 CARD16 default-char +2 n number of FONTPROPs in properties +1 draw-direction +0 LeftToRight +1 RightToLeft +1 CARD8 min-byte1 +1 CARD8 max-byte1 +1 BOOL all-chars-exist +2 INT16 font-ascent +2 INT16 font-descent +4 m number of elements in char-infos +8n LISTofFONTPROP properties +and either +12m LISTofCHARINFO char-infos +or +m LISTofLBXCHARINFO char-infos + + + +The description of this request is on See +LbxQueryFont. + + + + +LbxChangeProperty +1 CARD8 opcode +1 23 lbx opcode +2 6 request length +4 WINDOW window +4 ATOM property +4 ATOM type +1 CARD8 format +1 mode +0 Replace +1 Preprend +2 Append +2 unused +4 CARD32 length of data in format units + (= n for format = 8) + (= n/2 for format = 16) + (= n/4 for format = 32) +=> +1 1 Reply +1 unused +2 CARD16 sequence number +4 0 reply length +4 CARD32 tag +20 unused + + + +The description of this request is on See +LbxChangeProperty. + + + + +LbxGetProperty +1 CARD8 opcode +1 24 lbx opcode +2 7 request length +4 WINDOW window +4 ATOM property +4 ATOM type +0 AnyPropertyType +1 CARD8 delete +3 unused +4 CARD32 long-offset +4 CARD32 long-length +=> +1 1 Reply +1 CARD8 format +2 CARD16 sequence number +4 CARD32 reply length +4 ATOM type +0 None +4 CARD32 bytes-after +4 CARD32 length of value in format units + (= 0 for format = 0) + (= n for format = 8) + (= n/2 for format = 16) + (= n/4 for format = 32) +4 CARD32 tag +8 unused + + + +The description of this request is on See +LbxGetProperty. + + + + +LbxTagData +1 CARD8 opcode +1 25 lbx opcode +2 3+(n+p)/4 request length +4 CARD32 tag +4 CARD32 length of data in bytes +n LISTofBYTE data +p unused, p=pad(n) + + + +The description of this request is on See +LbxTagData. + + + + +LbxCopyArea +1 CARD8 opcode +1 26 lbx opcode +2 L request length +1 CARD8 source drawable cache entry +1 LBXGCANDDRAWENT cache entries +4 or 0 DRAWABLE optional source drawable +b LBXGCANDDRAWUPDATE optional gc and dest drawable +c LBXPINT16 src-x +d LBXPINT16 src-y +e LBXPINT16 dst-x +f LBXPINT16 dst-y +g LBXCARD16 width +h LBXCARD16 height +p unused, p=Lpad + + + +The description of this request is on See +LbxCopyArea. + + + + +LbxCopyPlane +1 CARD8 opcode +1 27 lbx opcode +2 L request length +4 CARD32 bit plane +1 CARD8 source drawable cache entry +1 LBXGCANDDRAWENT cache entries +4 or 0 DRAWABLE optional source drawable +b LBXGCANDDRAWUPDATE optional gc and dest drawable +c LBXPINT16 src-x +d LBXPINT16 src-y +e LBXPINT16 dst-x +f LBXPINT16 dst-y +g LBXCARD16 width +h LBXCARD16 height +p unused, p=Lpad + + + +The description of this request is on See +LbxCopyPlane. + + + + +LbxPolyText8 +1 CARD8 opcode +1 28 lbx opcode +2 L request length +1 LBXGCANDDRAWENT cache entries +a LBXGCANDDRAWUPDATE optional gc and drawable +b LBXPINT16 x +c LBXPINT16 y +n LISTofTEXTITEM8 items +p unused, p=Lpad + + + +The description of this request is on See +LbxPolyText8. + + + + +LbxPolyText16 +1 CARD8 opcode +1 29 lbx opcode +2 L request length +1 LBXGCANDDRAWENT cache entries +a LBXGCANDDRAWUPDATE optional gc and drawable +b LBXPINT16 x +c LBXPINT16 y +2n LISTofTEXTITEM16 items +p unused, p=Lpad + + + +The description of this request is on See +LbxPolyText16. + + + + +LbxImageText8 +1 CARD8 opcode +1 30 lbx opcode +2 L request length +1 LBXGCANDDRAWENT cache entries +a LBXGCANDDRAWUPDATE optional gc and drawable +b LBXPINT16 x +c LBXPINT16 y +n STRING8 string +p unused, p=Lpad + + + +The description of this request is on See +LbxImageText8. + + + + +LbxImageText16 +1 CARD8 opcode +1 31 lbx opcode +2 L request length +1 LBXGCANDDRAWENT cache entries +a LBXGCANDDRAWUPDATE optional gc and drawable +b LBXPINT16 x +c LBXPINT16 y +2n STRING16 string +p unused, p=Lpad + + + +The description of this request is on See +LbxImageText16. + + + + +LbxQueryExtension +1 CARD8 opcode +1 32 lbx opcode +2 2+(n+p)/4 request length +4 n length of extension name +n STRING8 extension name +p unused, p=pad(n) +=> +1 1 Reply +1 n number of requests in the extension +2 CARD16 sequence number +4 0 or 2*(m + p) reply length, m = (n+7)/8 +1 BOOL present +1 CARD8 major opcode +1 CARD8 first event +1 CARD8 first error +20 unused +m LISTofMASK optional reply-mask +p unused, p=pad(m) +m LISTofMASK optional event-mask +p unused, p=pad(m) + + + +The description of this request is on See +LbxQueryExtension. + + + + +LbxPutImage +1 CARD8 opcode +1 33 lbx opcode +2 L request length +1 CARD8 compression method +1 LBXGCANDDRAWENT cache entries +a PIPACKED bit-packed +b LBXGCANDDRAWUPDATE optional gc and drawable +c LBXCARD16 width +d LBXCARD16 height +e LBXPINT16 x +f LBXPINT16 y +n LISTofBYTE compressed image data +p unused, p=Lpad + + + +If there is no left padding and the depth is less than or equal to nine, +PIPPACKED is encoded as follows: + + + +PIPACKED +1 #x80 | (format << 5) | ((depth -1) << 2) + + + +Otherwise PIPACKED is defined as: + + + +PIPACKED +1 (depth -1) << 2) +1 (format << 5) | left-pad + + + +The description of this request is on See +LbxPutImage. + + + + +LbxGetImage +1 CARD8 opcode +1 34 lbx opcode +2 6 request length +4 DRAWABLE drawable +2 INT16 x +2 INT16 y +2 CARD16 width +2 CARD16 height +4 CARD32 plane mask +1 CARD8 format +3 unused +=> +1 1 Reply +1 CARD8 depth +2 CARD16 sequence number +4 (n+p)/4 reply length +4 (m+p)/4 X reply length; if uncompressed, m=n +4 VISUALID visual +0 None +1 compression method +15 unused +n LISTofBYTE data +p unused, p=pad(n) + + + +The description of this request is on See +LbxGetImage. + + + + +LbxBeginLargeRequest +1 CARD8 opcode +1 35 lbx opcode +2 2 request length +4 CARD32 large request length + + + +The description of this request is on See +LbxBeginLargeRequest. + + + + +LbxLargeRequestData +1 CARD8 opcode +1 36 lbx opcode +2 1+n request length +4n LISTofBYTE data + + + +The description of this request is on See +LbxLargeRequestData. + + + + +LbxEndLargeRequest +1 CARD8 opcode +1 37 lbx opcode +2 1 request length + + + +The description of this request is on See +LbxEndLargeRequest. + + + + +LbxInternAtoms +1 CARD8 opcode +1 38 lbx opcode +2 1+(2+m+n+p)/4 request length +2 m num-atoms +n LISTofLONGSTR names +p pad p=Lpad +=> +1 1 Reply +1 unused +2 CARD16 sequence number +4 a reply length, a = MAX(m - 6, 0) +4*m LISTofATOM atoms +p pad p = MAX(0, 4*(6 - m)) +  +LONGSTR +2 c string length +c STRING8 string + + + +The description of this request is on See +LbxInternAtoms. + + + + +LbxGetWinAttrAndGeom +1 CARD8 opcode +1 39 lbx opcode +2 2 request length +4 CARD32 window id +=> +1 1 Reply +1 backing store +0 NotUseful +1 WhenMapped +2 Always +2 CARD16 sequence number +4 7 reply length +4 VISUALID visual id +2 class +1 InputOutput +2 InputOnly +1 BITGRAVITY bit gravity +1 WINGRAVITY window gravity +4 CARD32 backing bit planes +4 CARD32 backing pixel +1 BOOL save under +1 BOOL map installed +1 map state +0 Unmapped +1 Unviewable +2 Viewable +1 BOOL override +4 COLORMAP colormap +4 SETofEVENT all events mask +4 SETofEVENT your event mask +2 SETofDEVICEEVENT do not propagate mask +2 unused +4 WINDOW root +2 INT16 x +2 INT16 y +2 CARD16 width +2 CARD16 height +2 CARD16 border width +1 CARD8 depth +1 unused + + + +The description of this request is on See +LbxGetWinAttrAndGeom. + + + + +LbxGrabCmap +1 CARD8 opcode +1 40 lbx opcode +2 2 request length +4 COLORMAP colormap +=> + + + +If smart-grab is true, the reply is as follows: + + + +1 1 Reply +1 #x80 flags +2 CARD16 sequence number +4 0 reply length +24 unused + +If smart-grab is false, the reply is as follows: + +1 1 Reply +1 flags (set of) + #x40 auto-release + #x20 three-channels + #x10 two-byte-pixels +lower four bits specifies bits-per-pixel +2 CARD16 sequence number +4 L reply length +m CHAN or CHANNELS cells (CHAN if !three-channels) +p 0 pad(m) + +CHANNELS +a CHAN red +1 5 next channel +b CHAN green +1 5 next channel +c CHAN blue +1 0 list end + +CHAN +d LISTofLBXPIXEL + +LBXPIXEL +e PIXELPRIVATE or + PIXELPRIVATERANGE or + PIXELALLOC or + PIXELALLOCRANGE + +PIXELPRIVATE +1 1 pixel-private +f PIXEL pixel + +PIXEL +f CARD8 or CARD16 (CARD8 if !two-byte-pixels) + +PIXELPRIVATERANGE +1 2 pixel-private-range +f PIXEL fist-pixel +f PIXEL last-pixel + +PIXELALLOC +1 3 pixel-private +f PIXEL pixel +g COLORSINGLE or COLORTRIPLE color (COLORSINGLE if +three-channels) + +COLORSINGLE +h CARD8 or CARD16 value (CARD8 if bits-per-rgb =< 7) + +COLORTRIPLE +h COLORSINGLE red +h COLORSINGLE green +h COLORSINGLE blue + +PIXELALLOCRANGE +1 4 pixel-private +f PIXEL first-pixel +f PIXEL last-pixel +j LISTofCOLORSINGLE or color (COLORSINGLE if three-channels) + LISTofCOLORTRIPLE + + + +The description of this request is on See +LbxGrabCmap. + + + + +LbxReleaseCmap +1 CARD8 opcode +1 41 lbx opcode +2 2 request length +4 COLORMAP cmap + + + +The description of this request is on See +LbxReleaseCmap. + + + + +LbxAllocColor +1 CARD8 opcode +1 42 lbx opcode +2 5 request length +4 COLORMAP colormap +4 CARD32 pixel +2 CARD16 red +2 CARD16 green +2 CARD16 blue +2 unused + + + +The description of this request is on See +LbxAllocColor. + + + + +LbxSync +1 CARD8 opcode +1 43 lbx opcode +2 1 request length +=> +1 1 Reply +1 n unused +2 CARD16 sequence number +4 0 reply length +24 unused + + + +The description of this request is on See +LbxSync. + + + + + + +Events + + +LbxSwitchEvent +1 base + 0 code +1 0 lbx type +2 CARD16 sequence number +4 CARD32 client +24 unused + + + +The description of this event is on See +LbxSwitchEvent. + + + + +LbxCloseEvent +1 base + 0 code +1 1 lbx type +2 CARD16 sequence number +4 CARD32 client +24 unused + + + +The description of this event is on See +LbxCloseEvent. + + + + +LbxInvalidateTagEvent +1 base + 0 code +1 3 lbx type +2 CARD16 sequence number +4 CARD32 tag +4 tag-type +1 LbxTagTypeModmap +2 LbxTagTypeKeymap +3 LbxTagTypeProperty +4 LbxTagTypeFont +5 LbxTagTypeConnInfo +20 unused + + + +The description of this event is on See +LbxInvalidateTagEvent. + + + + +LbxSendTagDataEvent +1 base + 0 code +1 4 lbx type +2 CARD16 sequence number +4 CARD32 tag +4 tag-type +3 LbxTagTypeProperty +20 unused + + + +The description of this event is on See +LbxSendTagDataEvent. + + + + +LbxListenToOne +1 base + 0 code +1 5 lbx type +2 CARD16 sequence number +4 CARD32 client +#xFFFFFFFF +a client not managed by the proxy +24 unused + + + +The description of this event is on See +LbxListenToOne. + + + + +LbxListenToAll +1 base + 0 code +1 6 lbx type +2 CARD16 sequence number +28 unused + + + +The description of this event is on See +LbxListenToAll. + + + + +LbxQuickMotionDeltaEvent +1 base + 1 code +1 CARD8 delta-time +1 INT8 delta-x +1 INT8 delta-y + + + +This event is not padded to 32 bytes. + + + + +The description of this event is on See +LbxQuickMotionDeltaEvent. + + + + +LbxMotionDeltaEvent +1 base + 0 code +1 7 lbx type +1 INT8 delta-x +1 INT8 delta-y +2 CARD16 delta-time +2 CARD16 delta-sequence + + + +This event is not padded to 32 bytes. + + + + +The description of this event is on See +LbxMotionDeltaEvent. + + + + +LbxReleaseCmapEvent +1 base + 0 code +1 8 lbx type +2 CARD16 sequence number +4 COLORMAP colormap +24 unused + + + +The description of this event is on See +LbxReleaseCmapEvent. + + + + +LbxFreeCellsEvent +1 base + 0 code +1 9 lbx type +2 CARD16 sequence number +4 COLORMAP colormap +4 PIXEL pixel start +4 PIXEL pixel end +16 unused + + + +The description of this event is on See +LbxFreeCellsEvent. + + + + + +Re-encoding of X Events + + +The X protocol requires all X events to be 32 bytes. The LBX server reduces the +number of bytes sent between the server and the proxy for some X events by not +appending unused pad bytes to the event data. The offsets of X event data are +unchanged. The proxy will pad the events to 32 bytes before passing them on to +the client. + + + + +LBX reencodes X event representations into the following sizes, if squishing is +enabled: + + + +KeyOrButton 32 +EnterOrLeave 32 +Keymap 32 +Expose 20 +GraphicsExposure 24 +NoExposure 12 +VisibilityNotify 12 +CreateNotify 24 +DestroyNotify 12 +UnmapNotify 16 +MapNotify 16 +MapRequest 12 +Reparent 24 +ConfigureNotify 28 +ConfigureRequest 28 +GravityNotify 16 +ResizeRequest 12 +Circulate 20 +Property Notify 20 +SelectionClear 20 +SelectionRequest 28 +SelectionNotify 24 +Colormap Notify 16 +MappingNotify 8 +ClientMessage 32 +Unknown 32 + + + + +Responses + + +LbxDeltaResponse +1 event_base + 0 event code +1 2 lbx type +2 1+(2+2n+p)/4 request length +1 n count of diffs +1 CARD8 cache index +2n LISTofDIFFITEM offsets and differences +p unused, p=pad(2n) + + + +The description of this response is on See +LbxDeltaResponse. + + + + +
-- cgit v1.2.3 From 9ba2065b63ea0e61a17b8221ad454c02a1755373 Mon Sep 17 00:00:00 2001 From: James Jones Date: Wed, 11 Aug 2010 15:03:59 -0700 Subject: Document changes in XSync version 3.1 Signed-off-by: James Jones Reviewed-by: Pierre-Loup Griffais Reviewed-by: Aaron Plattner Reviewed-by: Robert Morell Acked-by: Alan Coopersmith --- specs/sync.xml | 229 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 220 insertions(+), 9 deletions(-) (limited to 'specs') diff --git a/specs/sync.xml b/specs/sync.xml index a8064a9..e61dc17 100644 --- a/specs/sync.xml +++ b/specs/sync.xml @@ -32,6 +32,11 @@ by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,ref Wiggins X Consortium, Inc. + + James + Jones + NVIDIA Corporation + X Consortium Standard @@ -43,8 +48,9 @@ Digital Equipment Corporation, Maynard, Massachusetts 1991X Consortium + 2010NVIDIA Corporation - Version 3.0 + Version 3.1 X Consortium X Version 11, Release 6.8 @@ -52,10 +58,10 @@ 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 notice appear in all copies. Olivetti, Digital, MIT, the +X Consortium, and NVIDIA 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. @@ -133,12 +139,17 @@ frame marker. -The extension adds Counter and -Alarm to the set of resources managed by the +The extension adds Counter, Alarm, +and Fence 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. +conditions, called TRIGGERs, becomes TRUE. Alarms generate events when +counter values go through a specified transition. A fence has two possible +states: triggered and not triggered. Client requests can put the fence in +either of these states. A client can block until one of a set of fences +becomes triggered by sending an AwaitFence request. Fences are bound to a +particular screen at creation time. @@ -168,6 +179,21 @@ clients to receive an event on a regular basis when a particular counter is changed. + +The CreateFence request allows a client to create a +Fence that can be triggered and reset using +TriggerFence and ResetFence +requests, respectively. CreateFence takes a drawable +argument that implies which screen the fence should be created on. The +TriggerFence request changes the fence's state only +after all previous rendering commands affecting objects owned by the given +fence's screen have completed. Note that while fence objects are bound +to a screen and the simple trigger operation provided by this extension +operates at screen granularity, other extensions may add more fine-grained +trigger operations based on any number of events. The screen binding +merely establishes an upper bound for the scope of fence operations. + + Types @@ -201,6 +227,7 @@ SYSTEMCOUNTER: [ ] ALARM: XID ALARMSTATE: {Active,Inactive,Destroyed} +FENCE: XID @@ -283,6 +310,14 @@ registry of system counter names to avoid collisions in the name space. An ALARM is the client-side handle on an Alarm resource. + + +The FENCE type defines the client-side handle on a server +Fence. A fence can only be in one of two states, +represented by a BOOL. If the value is TRUE, the fence is in the triggered +state. Otherwise, the fence is in the not triggered state. + + @@ -307,6 +342,15 @@ does not name a defined ALARM. + + Fence + + +This error is generated if the value for a FENCE argument in a request +does not name a defined FENCE. + + + @@ -341,7 +385,7 @@ and v1.version_minor <= v2.version_minor. Compatible means that the functionality is fully supported in an identical fashion in the two versions. -This document describes major version 3, minor version 0 of the SYNC protocol. +This document describes major version 3, minor version 1 of the SYNC protocol. @@ -740,6 +784,118 @@ server. + + CreateFence + + +drawable: DRAWABLE +id: FENCE +initially-triggered: BOOL +Errors: IDChoice,Alloc + + +This request creates a fence on the screen associated with drawable and +assigns the specified id to it. The fence is in the triggered state iff +initially-triggered is TRUE. There are no clients waiting on the fence. + + + + + TriggerFence + + +fence: FENCE +Errors: Fence + + +This request puts the given fence in the triggered state after all rendering +from previous requests that affects resources owned by the fence's screen has +completed. This includes requests from other clients if those requests have +been dispatched. This request has no visible effects if the fence was already +in the triggered state. A Fence error is generated if +fence does not name a valid fence. + + +Note that the given fence's state is not necessarily directly modified by this +request. The state change need only be queued to occur after the required +rendering has completed. Clients should take care to not assume the fence will +be in the triggered state in subsequent requests, such as those that operate +on the given fence immediately. AwaitFence should first +be issued if subsequent requests require the fence to be in the triggered +state. + + + + + ResetFence + + +fence: FENCE +Errors: Fence,Match + + +This request immediately puts the given fence in the not triggered state. +A Match error is generated if the fence is not in the +triggered state. A Fence error is generated if fence +does not name a valid fence. + + +See the warnings above regarding TriggerFence's delayed +effect. In particular, a TriggerFence request +immediately followed by a ResetFence request is likely +to result in a Match error. An +AwaitFence request should be issued between the two. + + + + + DestroyFence + + +fence: FENCE +Errors: Fence + + +This request destroys the given fence. All clients waiting on this fence are +released. A fence is destroyed automatically when the connection to the client +that created the fence is closed if the close-down mode is +DestroyAll. A Fence error is +generated if fence does not name a valid fence. + + + + + QueryFence + + +fence: FENCE +=> +triggered: BOOL +Errors: Fence + + +This request returns TRUE if the given fence is triggered, or FALSE if it +is not triggered. A Fence error is generated if +fence does not name a valid fence. + + + + + AwaitFence + + +fence-list: LISTofFENCE +Errors: Fence,Alloc + + +When this request is executed, the processing of further requests for the +client is blocked until one or more of the fences in fence-list reaches the +triggered state. If any of the fences are already in the triggered state, +request processing resumes immediately. A Fence error +is generated if any member of fence-list does not name a valid fence. + + + @@ -844,6 +1000,7 @@ TRIGGER: WAITCONDITION: 20 TRIGGER trigger 8 INT64 event threshold +FENCE: CARD32 @@ -872,6 +1029,14 @@ groups, the byte ordering determined during connection setup is used. 2 CARD16 minor opcode 1 CARD8 major opcode 21 unused +Fence + 1 0 Error + 1 Base + 2 code + 2 CARD16 sequence number + 4 CARD32 bad fence + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused @@ -1026,6 +1191,52 @@ GetPriority 4 INT32 priority 20 unused +CreateFence + 1 CARD8 major opcode + 1 14 minor opcode + 2 4 request length + 4 DRAWABLE drawable + 4 FENCE id + 1 BOOL initially triggered + 3 unused + +TriggerFence + 1 CARD8 major opcode + 1 15 minor opcode + 2 2 request length + 4 FENCE id + +ResetFence + 1 CARD8 major opcode + 1 16 minor opcode + 2 2 request length + 4 FENCE id + +DestroyFence + 1 CARD8 major opcode + 1 17 minor opcode + 2 2 request length + 4 FENCE id + +QueryFence + 1 CARD8 major opcode + 1 18 minor opcode + 2 2 request length + 4 FENCE id +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence number + 4 0 reply length + 1 BOOL triggered + 23 unused + +AwaitFence + 1 CARD8 major opcode + 1 19 minor opcode + 2 1 + n request length + 4*n LISTofFENCE wait conditions + -- cgit v1.2.3 From 77c2b72d8df53e918b0fbff5425af82ac7f5693a Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Thu, 9 Dec 2010 17:43:29 -0800 Subject: specs/sync.xml: Fix minor typos in document title section Signed-off-by: Alan Coopersmith --- specs/sync.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'specs') diff --git a/specs/sync.xml b/specs/sync.xml index e61dc17..ea8033f 100644 --- a/specs/sync.xml +++ b/specs/sync.xml @@ -9,7 +9,7 @@ by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,ref - X Synchronization Extention Protocol + X Synchronization Extension Protocol X Consortium Standard X Version 11, Release 6.6.84 @@ -20,12 +20,12 @@ by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,ref Dave Carver - Digital EquipmentCorporation, MIT/Project Athena + Digital Equipment Corporation, MIT/Project Athena Jim Gettys - Digital EquipmentCorporation, Cambridge Research Laboratory + Digital Equipment Corporation, Cambridge Research Laboratory David -- cgit v1.2.3 From 6aa72ae8e629e065f09a6b6c05504363806d76a3 Mon Sep 17 00:00:00 2001 From: Paulo Zanoni Date: Tue, 14 Dec 2010 16:23:56 -0200 Subject: Use the same docbookx.dtd version (4.3) for all docs This way we don't need to require 4.1.2 and 4.5 The geproto xml was inconsistent, by the way. Signed-off-by: Paulo Zanoni Reviewed-by: Matt Dew Signed-off-by: Alan Coopersmith --- specs/dbe.xml | 4 ++-- specs/geproto.xml | 4 ++-- specs/security.xml | 4 ++-- specs/sync.xml | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) (limited to 'specs') diff --git a/specs/dbe.xml b/specs/dbe.xml index ce7a327..c85dfda 100644 --- a/specs/dbe.xml +++ b/specs/dbe.xml @@ -1,6 +1,6 @@ - + diff --git a/specs/sync.xml b/specs/sync.xml index ea8033f..44a6b2c 100644 --- a/specs/sync.xml +++ b/specs/sync.xml @@ -1,6 +1,6 @@ - + -- cgit v1.2.3 From 9df8b77604b7ea7132d32f65f2280720b91249c1 Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Thu, 16 Dec 2010 23:54:45 -0800 Subject: specs: Fix section titles/nesting Signed-off-by: Alan Coopersmith --- specs/dpms.xml | 17 +++++------- specs/evi.xml | 29 +++++++++----------- specs/multibuf.xml | 77 +++++++++++++++++++++++++++--------------------------- specs/shape.xml | 34 ++++++++++++------------ specs/shm.xml | 21 +++++++-------- specs/tog-cup.xml | 30 ++++++++++----------- specs/xtest.xml | 37 ++++++++++++-------------- 7 files changed, 114 insertions(+), 131 deletions(-) (limited to 'specs') diff --git a/specs/dpms.xml b/specs/dpms.xml index d5323b1..98aaaa3 100644 --- a/specs/dpms.xml +++ b/specs/dpms.xml @@ -34,9 +34,7 @@ provided "as is" without express or implied warranty. - -TITLE - + Overview This extension provides X Protocol control over the VESA Display @@ -119,9 +117,9 @@ importance of power savings should supersede the screen saver. If the laptop user plugs the unit in and power is no longer a scarce commodity, it may be decided to make DPMS less aggressive, or disable it completely. - + - + Requests DPMSGetVersion @@ -430,16 +428,16 @@ of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend or DPMSModeOff, otherwise it is undefined. - + - + Events and Errors No new events or errors are defined by this extension. - + - + Encoding Please refer to the X11 Protocol Encoding document as this document uses @@ -558,6 +556,5 @@ The name of this extension is "DPMS". 21 unused - diff --git a/specs/evi.xml b/specs/evi.xml index 1136278..a565f73 100644 --- a/specs/evi.xml +++ b/specs/evi.xml @@ -62,17 +62,15 @@ X Window System is a trademark of The Open Group. - -TITLE - + Introduction EVI (Extended Visual Information extension) allows a client to determine information about core X visuals beyond what the core protocol provides. - + - + Goals As the X Window System has evolved, it has become clear that the information @@ -90,9 +88,9 @@ their own mechanisms for delivering that information. For example, the Double Buffering Extension (DBE) provides its own mechanism for determining which visuals support double-buffering. - + - + Requests GetVersion @@ -285,22 +283,22 @@ example, if a 12-bit colormap is overloaded to support 8-bit visuals, the - - + + Events and Errors No new events or errors are defined by this extension. - + - + Changes to existing protocol. None. - + - + Encoding The name of this extension is "Extended-Visual-Information". @@ -358,9 +356,9 @@ VISUALINFO 1 CARD8 max_hw_colormaps 2 CARD16 num_colormap_conflicts - + - + C Language Binding @@ -513,6 +511,5 @@ of hardware support for multiple colormaps. XeviGetVisualInfo returns Success if successful, or an X error otherwise. - diff --git a/specs/multibuf.xml b/specs/multibuf.xml index 263d580..eb01829 100644 --- a/specs/multibuf.xml +++ b/specs/multibuf.xml @@ -70,16 +70,16 @@ in this Software without prior written authorization from the X Consortium. - -TITLE +Warning The Multi-Buffering extension described here was a draft standard of the X Consortium prior to Release 6.1. It has been superseded by the Double Buffer Extension (DBE). DBE is an X Consortium Standard as of Release 6.1. + - + Introduction @@ -120,9 +120,9 @@ The authors of this proposal have tried to unify the above documents to yield a proposal that incorporates support for double-buffering, multi-buffering, and stereo in a way that is acceptable to all concerned. - + - + Goals @@ -176,9 +176,9 @@ existing hardware features. - + - + Image Buffers @@ -316,9 +316,9 @@ the screen contents are not altered and the contents of any undisplayed image buffers are undefined. If backing store was maintained for an image buffer, then no exposure events are generated. - + - + New Requests @@ -671,9 +671,9 @@ display are de-allocated. If the window is not multi-buffered, the request is ignored. - + - + Attributes @@ -860,9 +860,9 @@ increment for incompatible changes, and the minor version would increment for small upward compatible changes. Barring changes, the major version will be 1, and the minor version will be 1. - + - + Events @@ -958,9 +958,9 @@ becomes updated DisplayImageBuffers request), an UpdateNotify event is generated. - + - + Errors @@ -968,14 +968,14 @@ The following error type has been added to support this extension: - + Buffer A value for a BUFFER argument does not name a defined BUFFER. - + - + Double-Buffering Normal Windows @@ -1023,9 +1023,9 @@ while animating DestroyImageBuffers( W ) - + - + Multi-Buffering Normal Windows @@ -1070,9 +1070,9 @@ while animating } - + - + Stereo Windows How stereo windows are supported on a server @@ -1175,9 +1175,9 @@ right eyes for normal windows should be the same (ie: have no stereo offset). - + - + Single-Buffered Stereo Windows @@ -1195,9 +1195,9 @@ MapWindow( W ) <draw picture using L,R> - + - + Double-Buffering Stereo Windows @@ -1267,9 +1267,9 @@ while animating } - + - + Multi-Buffering Stereo Windows @@ -1310,9 +1310,9 @@ while animating DisplayImageBuffers( [L(i)], 100, 0 ) } - + - + Protocol Encoding @@ -1356,10 +1356,10 @@ Specifies the code that will be returned when The following sections describe the protocol encoding for this extension. - + - + TYPES @@ -1379,9 +1379,9 @@ SETofBUFFER_EVENT #x04000000 UpdateNotify - + - + EVENTS @@ -1406,8 +1406,8 @@ SETofBUFFER_EVENT 24 unused - - + + ERRORS @@ -1421,9 +1421,9 @@ SETofBUFFER_EVENT 21 unused - + - + REQUESTS @@ -1623,6 +1623,5 @@ VALUEs - diff --git a/specs/shape.xml b/specs/shape.xml index 7e5f2f7..3386443 100644 --- a/specs/shape.xml +++ b/specs/shape.xml @@ -60,8 +60,7 @@ copyright holders. -TITLE - + Overview @@ -94,9 +93,9 @@ 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 three regions: the @@ -264,9 +263,9 @@ 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. - + - + Types @@ -307,9 +306,9 @@ produce the new destination region. indicates that the destination region is subtracted from the source region to produce the new destination region. - + - + Requests ShapeQueryVersion @@ -802,9 +801,9 @@ values is the same as in the ShapeRectangles request. - + - + Events ShapeNotify @@ -870,9 +869,9 @@ current shape. When shaped is these will indicate the extents of the default region. The timestamp indicates the server time when the shape was changed. - + - + Encoding Please refer to the X11 Protocol Encoding document as this document uses @@ -883,7 +882,7 @@ conventions established there. The name of this extension is "SHAPE". - + New Types @@ -901,9 +900,9 @@ SHAPE_OP 3 Subtract 4 Invert - + - + Requests ShapeQueryVersion @@ -1055,9 +1054,9 @@ SHAPE_OP 20 unused 8n LISTofRECTANGLE rectangles - + - + Events ShapeNotify @@ -1073,7 +1072,6 @@ SHAPE_OP 1 BOOL shaped 11 unused - diff --git a/specs/shm.xml b/specs/shm.xml index 24c989c..19d9309 100644 --- a/specs/shm.xml +++ b/specs/shm.xml @@ -67,9 +67,7 @@ in this Software without prior written authorization from the X Consortium. - -TITLE - + REQUIREMENTS The shared memory extension is provided only by some X servers. To find out @@ -82,9 +80,9 @@ Additionally, the shared memeory maximum size will need to be increased on both Sun and Digital systems; the defaults are far too small for any useful work. - + - + WHAT IS PROVIDED @@ -106,9 +104,9 @@ pixmap data; if the pixmaps are stored in some magic graphics hardware, your application will not be able to share them with the server. Xdpyinfo(1) doesn't print this particular nugget of information. - + - + HOW TO USE THE SHARED MEMORY EXTENSION Code which uses the shared memory extension must include a number of header @@ -165,9 +163,9 @@ conventional Xlib calls. When the extension is available, version numbers of the extension implementation, and "pixmaps" which is True iff shared memory pixmaps are supported. - + - + USE OF SHARED MEMORY XIMAGES The basic sequence of operations for shared memory XImages is as follows: @@ -408,9 +406,9 @@ shmdt (shminfo.shmaddr); shmctl (shminfo.shmid, IPC_RMID, 0); - + - + USE OF SHARED MEMORY PIXMAPS Unlike X images, for which any image format is usable, the shared memory @@ -469,6 +467,5 @@ contents directly through the shared memory segment. Shared memory pixmaps are destroyed in the usual manner with XFreePixmap, though you should detach and destroy the shared memory segment itself as shown above. - diff --git a/specs/tog-cup.xml b/specs/tog-cup.xml index 08bb19b..bb6fb25 100644 --- a/specs/tog-cup.xml +++ b/specs/tog-cup.xml @@ -64,9 +64,7 @@ X Window System is a trademark of The Open Group. - -TITLE - + Overview This extension has three purposes: a) to provide mechanism for a special @@ -101,9 +99,9 @@ already been allocated, the color will be allocated in the private colormap at the same locaton as in the default colormap (instead of in the first available location.) - + - + Requests QueryVersion @@ -246,23 +244,23 @@ BadMatch error is generated if if cmap does not belong to a GrayScale, PseudoColor, or DirectColor visual. - + - + Events and Errors No new events or errors are defined by this extension. - - + + Changes to existing protocol. None. - + - + Encoding The name of this extension is "TOG-CUP". @@ -338,9 +336,9 @@ additional alloc-ok member in the CUPStoreColors reply.) #xF0 unused 1 unused - + - + C Language Binding @@ -531,9 +529,9 @@ colors are read-only (shareable). XCupStoreColors returns the number of colors that were successfully allocated in the colormap. - + - + Using the TOG-CUP extension and Colormap Utilization Policy The X server preallocates any hardware or desktop special colors in the @@ -557,6 +555,6 @@ using XCupStoreColors the colors will be allocated sharable (read-only) and any other application which allocates the same color will share that color cell. - + diff --git a/specs/xtest.xml b/specs/xtest.xml index 6da29f1..cdf5e63 100644 --- a/specs/xtest.xml +++ b/specs/xtest.xml @@ -59,10 +59,7 @@ in this Software without prior written authorization from the X Consortium. - -TITLE - - + Overview This extension is a minimal set of client and server extensions @@ -110,9 +107,9 @@ Minimize performance penalties on normal server operation. - + - + Description The functions provided by this extension fall into two groups: @@ -167,9 +164,9 @@ or pressed a key or button. - + - + Types The following types are used in the request and event definitions in @@ -223,9 +220,9 @@ CURSOR { CurrentCursor, None } or a cursor as defined by the X11 Protocol. - + - + Client Operations @@ -330,9 +327,9 @@ in the buffer and False otherwise. - + - + Server Requests XTestGetVersion @@ -607,9 +604,9 @@ If impervious is then the executing client returns to the normal state of being susceptible to server grabs. - + - + Encoding Please refer to the X11 Protocol Encoding document as this document uses @@ -620,7 +617,7 @@ conventions established there. The name of this extension is "XTEST". - + New Types FAKE_EVENT_TYPE @@ -635,9 +632,9 @@ FAKE_EVENT_TYPE NOTE that the above values are defined to be the same as those for the corresponding core protocol event types. - + - + Requests @@ -700,10 +697,10 @@ the corresponding core protocol event types. 1 BOOL impervious 3 unused - + - + References Annicchiarico, D., et al., @@ -717,6 +714,6 @@ Drake, K. J., Minimum X11 Testing Extension. UniSoft Ltd., June 1991. - + -- cgit v1.2.3 From 8c6cc9ddb5776a2b32d42a41d27b3df56e62c44f Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Thu, 24 Feb 2011 20:44:00 -0500 Subject: Docbook: change the book id to match the xml file basename Rename appgroup.xml as it conflicts with xorg-docs/specs/Xserver/appgroup.xml This is required for the up-coming external references support. Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 2 +- specs/appgroup.xml | 1018 ---------------------------------------------------- specs/appgrp.xml | 1018 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1019 insertions(+), 1019 deletions(-) delete mode 100644 specs/appgroup.xml create mode 100644 specs/appgrp.xml (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index 3792353..e689dff 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -23,7 +23,7 @@ if ENABLE_SPECS doc_sources = \ - appgroup.xml \ + appgrp.xml \ dbe.xml \ dpms.xml \ evi.xml \ diff --git a/specs/appgroup.xml b/specs/appgroup.xml deleted file mode 100644 index f506d86..0000000 --- a/specs/appgroup.xml +++ /dev/null @@ -1,1018 +0,0 @@ - - - -
- - - Application Group Extension to the X Protocol - X Consortium Standard - - - Kaleb - S. - KEITHLEY - X Consortium, Inc - kaleb@x.org - - - X Version 11, Release 6.4 - 27 September 1996 - - - -Copyright © 1996 X Consortium, Inc. All Rights Reserved. - - - -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 OF 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. - - - - - -The Application Group Extension to the X protocol is intended to provide a framework to allow -more than one program to manage X applications on the desktop. The initial use of this extension -will be to insert or embed the windows of X programs into the windows of another program, such -as a web browser. This extension is not intended to address larger embedding issues that, for -example, OpenDoc does, such as shared menu bars, etc. - - - - - -Purpose and Goals - - -The Application Group Extension to the X protocol is intended to provide -a framework to allow more than one program to manage X applications on -the desktop. The initial use of this extension will be to insert or embed -the windows of X programs into the windows of another program, such as a -web browser. This extension is not intended to address larger embedding -issues that, for example, OpenDoc does, such as shared menu bars, etc. -Using X programs on the World Wide Web allows for greater control of the -presentation and takes advantage of the existing body of X programs rather -than re-implement them in another language. In addition it allows the -embedding of non-X programs into web browsers by using third party products -like Wabi, MAE, and WinCenter. - -Wabi is a trademark of Sun Microsystems, Inc. MAE is a trademark of Apple -Computer, Inc. WinCenter is a trademark of Network Computing Devices, Inc. - - - - - - -Overview of the protocol. - - -This extension introduces the concept of an Application Group. An Application Group is a set of one or more applications that are primarily managed by a special application known as the Application Group Leader, which, for example, might be a web browser. The primary purpose of Application Groups is to provide a means of sharing the Substructure-Redirect attribute of the root window between the window manager and one or more Application Group Leaders. - - - -To join an Application Group an application must present the proper authorization during the connection setup. Authorizations are generated by the X server at the request of an Application Group Leader, and are then stored for the application to use to establish its connection to the X server. To generate an authorization the Application Group Leader sends a request to the server naming the Application Group to which the authorization will be bound, and any applications that connect using that authorization will automatically become part of the associated Application Group. The protocol to generate an authorization is defined in the Security Extension specification. - - - -As a member of an Application Group, when an application creates and maps a window as a child of the root window, the MapRequest and ConfigureRequest events are delivered to the Application Group Leader instead of the window manager. The Application Group Leader may then reparent the window into its own window hierarchy; or reissue the map request, in which case the window comes under the control of the window manager. - - - - -Requests - - -AppGroupQueryVersion - - - - - - - client_major_version: CARD16 - - - client_minor_version: CARD16 - - - => - - - server_major_version: CARD16 - - - server_minor_version: CARD16 - - - - - - -If supplied, the client_major_version and client_minor_version indicate what version of the protocol the application wants the server to implement. The server version numbers returned indicate the version of the protocol the X server actually supports. This may not match the versions requested by the application. An implementation may (but need not) support more than one version simultaneously. The server_major_version and server_minor_version numbers are a mechanism to support any future revisions of the Application Group extension protocol which may be necessary. In general, the major version would increment for incompatible changes, and the minor version would increment for small, upward-compatible changes. X servers that support the protocol defined in this document will return a server_major_version of 1 and a server_minor_version of 0. - - - -AppGroupCreate - - - - - - - app_group: APPGROUP - - - value_mask: BITMASK - - - value_list: LISTofVALUE - - - - - - -This request creates an Application Group using app_group as the Application Group ID. - - - - -  - - - - -The value_mask and value_list specify attributes of the Application Group that are to be explicitly initialized. The attributes, their types, and the default values are: - - - - - - - - - - Attribute - Type - Default - - - app_group_leader - Bool - True - - - single_screen - Bool - True - - - default_root - Window - None - - - root_visual - VisualID - None - - - default_colormap - Colormap - None - - - black_pixel - Pixel - 0 - - - white_pixel - Pixel - 0 - - - - - - -If the single_screen attribute is True then the number of video screens returned to a program in the Application Group in the connection setup message is one, irrespective of how many video screens the server actually has. If a server supports both video and print screens, then all print screens will always be returned. If single_screen is specified as True then the connection setup message will contain only the information about the video screen which has default_root as its root window, plus any print screens. - - - -The intent is to allow an embedding manager to ensure that it will be able to reparent any top-level windows that Application Group members create. By hiding the fact that there are other screens it can be reasonably assured that applications will only create top-level windows on the same screen that it itself appears on. An embedding manager should take care not to supply an invalid display, e.g. :0.1, to a program that will be in an Application Group where the single_screen attribute is True. - - - -If single_screen is set to True default_root specifies which screen will be returned as screen zero in the connection setup message for applications in the Application Group. If set to None, then the real screen zero is used, otherwise the screen which has default_root as its root window will be used. - - - - -If single_screen is set to True the root_visual and default_colormap attributes may be used to over-ride the default values that are returned in the connection setup information returned to new programs in the Application Group. If None is specified for root_visual or default_colormap then the normal default values for the screen (possibly spedified by default_root) are used, otherwise the specified values are used. If root_visual and/or default_colormap are specified they must be valid, i.e. root_visual must be a visual type available on the screen, and the colormap, if specified, must be a valid colormap for the visual that is used. - - - -IF single_screen is set to True and default_colormap is not specified as None, the black_pixel and white_pixel attributes must be specified, and they will over-ride the default values that are returned in the connection setup returned to new programs in the Application Group. If default_colormap is specified as None and black_pixel and/or white_pixel are specified, they will be ignored. - - - -The app_group_leader attribute is used to identify the Application Group Leader program for the app_group. By specifying True the server will identify the program making the request as the Application Group Leader for the application group. The Application Group Leader receives MapRequest and ConfigureRequest events from the server when an attempt is made to map or configure top-level windows of a program in an Application Group, instead of being sent to a window manager that has selected SubstructureRedirect events on the root window. The parent window field in these events will contain the Application Group ID. - - -AppGroupDestroy - -app_group: APPGROUP - - - -This request destroys the app_group. If the app_group_leader attribute for the app_group is True, then any applications in the Application Group that are still connected will be killed as if a KillClient request had been received for that application. - - - -If the application that created a non-embedded Application Group exits, and therefore any Authorizations to be cancelled, and any applications that attempt to open new connections to the X server using one of those Authorizations will be unable to do so. - - -AppGroupGetAttr - - - - - - - - >app_group: APPGROUP - - - => - - - LISTofVALUE - - - - - - -This request returns the application group attributes for app_group. - - -AppGroupQuery - - - - - - - resource: XID - - - => - - - app_group: APPGROUP - - - - - - -This request returns the Application Group ID of the application that created resource or None if that application is not associated with any Application Group. The resource value may be the resource base of the application. - - -AppGroupCreateAssociation - - - - - - - window: WINDOW - - - window_type: CARD32 - - - system_window: LISTofCARD8 - - - - - - -This request associates window with system_window. The window_type indicates the native window system of the application making the request. For non-X window_types both the embedding manager and the server must be executing on the same host. When system_window is Microsoft Windows or OS/2 Presentation Manager, the system_window is an HWND; when the native window system is Macintosh, the system_window is a WindowPtr and a Rect. The window may be used for any X request that takes a Window. - - -AppGroupDestroyAssociation - - - - - - - window: WINDOW - - - - - - -This request destroys the association created with AppGroupCreateAssociation. The window is destroyed. The system_window that was specified in the AppGroupCreateAssociation request is not affected. - - - - - -Changes to Existing Requests - - -MapWindow - - -If the override-redirect attribute of the window is False and if the window is a child of a root window and if the window belongs to an application that is in an application group and if some other application is the application group leader for that group, then a MapRequest event is generated and the window remains unmapped. Otherwise, the core protocol semantics apply. - - - - -ConfigureWindow - - -If the override-redirect attribute of the window is False and if the window is a child of a root window and if the window belongs to an application that is in an application group and if some other application is the application group leader for that group, then a ConfigureRequest event is generated and the window remains unchanged. Otherwise, the core protocol semantics apply. - - - - -CreateWindow - - -When a program in an Application Group creates a window that is a child of a root window and specifies CopyFromParent for the Visual, if the single_screen attribute is True and the root_visual attribute is set to something other than None, then the window will be created using the Application Group’s root_visual, otherwise core protocol semantics apply. - - - -When a program in an Application Group creates a window that is a child of a root window and specifies CopyFromParent for the Colormap, if the single_screen attribute is True, the default_colormap attribute is set to something other than None, and the window’s Visual is the same as the Application Group’s root_visual attribute, then the window will be created using the Application Group’s default_colormap, otherwise core protocol semantics apply. - - - - - -ChangeWindowAttributes - - -When a program in an Application Group changes the attributes of a window that is a child of a root window and specifies CopyFromParent for the Colormap, if the single_screen attribute is True, the default_colormap attribute is set to something other than None, and the window’s Visual is the same as the Application Group’s root_visual attribute, then the window will be created using the Application Group’s default_colormap, otherwise core protocol semantics apply. - - - - - - - -Changes to Existing Events - - -When the top-level window of an application that is a member of an Application Group is the target of a MapWindow or ConfigureWindow request, if there is an Application Group Leader then MapRequest and ConfigureRequest events are automatically delivered to it, otherwise the core protocol semantics apply, i.e. they are delivered to the client, if any, that has SubstructureRedirect set in its root-window event mask, e.g. the window manager. - - - -The Application Group Leader must not select SubstructuRedirect events on a root window as doing so would result in a core protocol error; only one client is permitted to do so, and that is usually the window manager. - - - - -MapRequest - - -When a MapWindow request is received for a window whose override-redirect attribut is set to False and whose parent is the root window and the window belongs to an application that is in an application group and there is an application group leader for the group, then this event is delivered to the Application Group Leader with the parent field in the event set to the AppGroup ID. Otherwise the core protocol semantics apply. - - - - -ConfigureRequest - - -When a ConfigureWindow request is received for a window whose override-redirect attribut is set to False and whose parent is the root window and the window belongs to an application that is in an application group and there is an application group leader for the group, then this event is delivered to the Application Group Leader with the parent field in the event set to the AppGroup ID. Otherwise the core protocol semantics apply. - - - - - - -Errors - - -AppGroupQueryVersion - - -There are no errors for AppGroupQueryVersion. - - - - - -AppGroupCreate - - -A Window error is returned if default_root is specified and is not a valid root window.. - - - -A Color error is returned default_colormap is specified but default_colormap is not a valid colormap for the screen of default_root. - - - -A Match error is returned if root_visual and default_colormap are both specified, but - - - -default_colormap’s visual is not root_visual. - - - -A Match error is returned if root_visual does not exist for the screen of the default_root. - - - - - -AppGroupDestroy - - -An AppGroup error is returned if app_group is not a valid Application Group. - - - -An Access error is returned if an untrusted application attempts to destroy an Application Group created by a trusted application. - - - - - -AppGroupGetAttr - - -An AppGroup error is returned if app_group is not a valid Application Group. - - - -An Access error is returned if an untrusted application attempts to get the attributes of an Application Group created by a trusted application. - - - - - -AppGroupQuery - - -An Access error is returned if an untrusted application attempts to query the Application Group of a trusted application. - - - - - -AppGroupCreateAssociation - - -A Match error is returned if the X server does not support the window_type. - - - -An Access error may be returned if the X server only supports the window_type on the local host and the program making the request is on a non-local host. - - - -A Window error may be returned for system-specific errors related to system_window, e.g. system_window does not represent a valid native window. - - - - - -AppGroupDestroyAssociation - - -A Window error is returned if window was not specified in a previous AppGroupCreateAssociation request. - - - - - - -Encoding - - -Please refer to the X11 Protocol encoding document as this document uses conventions established there. - - - - -The name of this extension is XC-APPGROUP - - - - -AppGroupQueryVersion - 1 CARD8 opcode - 1 0 XC-APPGROUP opcode - 2 3 length - 2 CARD16 client_major_version - 2 CARD16 client_minor_version -=> - 1 1 Reply - 1 unused - 2 CARD16 sequence_number - 4 0 length - 2 CARD16 server_major_version - 2 CARD16 server_minor_version - 20 unused - - - - -AppGroupCreate - 1 CARD8 opcode - 1 1 XC-APPGROUP opcode - 2 8+n length - 4 XID app_group - 4 BITMASK attrib_mask - #x00000001 app_group_leader - #x00000002 single_screen - #0x0000004 default_root - #x00000008 root_visual - #x00000010 default_colormap - #x00000020 black_pixel - #x00000040 white_pixel - n LISTofVALUE value-list -VALUEs - 4 BOOL app_group_leader - 4 BOOL single_screen - 4 WINDOW default_root - 4 VISUALID root_visual - 4 COLORMAP default_colormap - 4 CARD32 black_pixel - 4 CARD32 white_pixel - - - - -AppGroupDestroy - 1 CARD8 opcode - 1 2 XC-APPGROUP opcode - 2 2 length - 4 XID app_group - - - -AAppGroupGetAttr - 1 CARD8 opcode - 1 4 XC-APPGROUP opcode - 2 2 length - 4 XID app_group -=> - 1 1 Reply - 1 unused - 2 CARD16 sequence_number - 4 0 length - 4 WINDOW default_root - 4 VISUALID root_visual - 4 COLORMAP default_colormap - 4 CARD32 black_pixel - 4 CARD32 whte_pixel - 1 BOOL single_screen - 1 BOOL app_group_leader - 2 unused - - - - -AppGroupQuery - 1 CARD8 opcode - 1 5 XC-APPGROUP opcode - 2 2 length - 4 XID resource -=> - 1 1 Reply - 1 unused - 2 CARD16 sequence_number - 4 0 length - 4 XID app_group - 20 unused - - - -AppGroupCreateAssoc - 1 CARD8 opcode - 1 6 XC-APPGROUP opcode - 2 n length - 4 WINDOW window - 2 CARD16 window_type - #0 X11 - #1 Macintosh - #2 Win32, OS/2 PM 2.x - #3 Win16, OS/2 PM 1.x - 2 n system_window_len - n LISTofCARD8 system_window - - - - -AppGroupDestroyAssoc - 1 CARD8 opcode - 1 7 XC-APPGROUP opcode - 2 2 length - 4 WINDOW window - - - - - -Library API - - - - - - - -Status XagQueryVersion ( xkb, keycode) /* macro */ - - - - -Display dpy; - - - - -int * major_version_return; - - - - -int * minor_version_return; - - - - - - - -XagQueryVersion sets major_version_return and minor_version_return to the major and minor Application Group protocol version supported by the server. If the Xag library is compatible with the version returned by the server it returns non-zero. If dpy does not support the Application Group extension, or if the server and library protocol versions are incompatible, or if there was an error during communication with the server, it returns zero. No other Xag functions may be called before this function. If a program violates this rule, the effects of all subsequent Xag calls that it makes are undefined. - - - -An embedding manager in, e.g. a Personal Computer Web Browser, will need to open a connection to the Personal Computer X server by calling XOpenDisplay() before using the Application Group extension. - - - -An embedding manager such as a web browser that intends to embed programs in an Application Group should create the Application Group with XagCreateEmbeddedApplicationGroup. - - - - - - - - - -Status XagCreateEmbeddedApplicationGroup( - - - - - Display* dpy, - - - - - VisualID root_visual, - - - - - Colormap default_colormap, - - - - - unsigned long black_pixel, - - - - - unsigned long white_pixel, - - - - - XAppGroup* app_group_return); - - - - - - - - -XagCreateEmbeddedApplicationGroup creates an Application Group for an embedding manager with the attributes specified. It also sets the default_root attribute to DefaultRoot(dpy, DefaultsScreen(dpy)) and the single_screen and app_group_leader attributes to True. It returns the Application Group ID in app_group_return. - - - -You can create an Application Group without intending to do embedding. One reason for doing this is to give a group of clients their own font-path. - - - -A special font-path can be created by creating an Application Group, getting an Authorization using XSecurityGenerateAuthorization, and then running ‘xset fp+ <new font path>’ as a member of the Application Group. Font-path elements added in this way will be "private" to the Application Group. - - - - - - - - -Status XagCreateNonembeddedApplicationGroup( - - - - - Display* dpy, - - - - - XAppGroup* app_group_return); - - - - - - - -An Application Group created with XagCreateNonembeddedApplicationGroup will have the default_root, root_visual, and default_colormap attributes all set to None; the single_screen and app_group_leader attributes are set to False, and the black_pixel and white_pixel attributes are not used since the default_colormap attribute is None. - - - -To destroy an Application Group use XagDestroyApplicationGroup. - - - - - - - - -Status XagDestroyApplicationGroup( - - - - - Display* dpy, - - - - - XAppGroup app_group); - - - - - - - -The Application Group specified by app_group is destroyed. If the Application Group was created using XagCreateEmbeddingApplicationGroup, i.e. and therefore the app_group_leader attribute is True, all programs that are members of the Application Group are killed as if a KillClient request had been issued. - - - - -To retrieve the attributes of an Application Group use XagGetApplicationGroupAttributes. - - - - - - - - - -Status XagGetApplicationGroupAttributes( - - - - - Display* dpy, - - - - - XAppGroup app_group, - - - - - ...); - - - - - - - - - -XagGetApplicationGroupAttributes is a varargs function that retrieves the Application Group’s attributes specified in the vararg parameter list. - - - -The attributes that may be specified are: XagNappGroupLeader, XagNsingleScreen, XagNdefaultRoot, XagNrootVisual, XagNdefaultColormap, XagNblackPixel, and XagNwhitePixel; which correspond to app_group_leader, single_screen, default_root, root_visual, default_colormap, black_pixel, and white_pixel respectively. See AppGroupCreate in Section 3 for a description of each attribute. - - - -The types for each of the parameters are pointers to the following: - - - - single_screen Bool - default_root Window - root_visual VisualID - default_colormap Colormap - black_pixel unsigned long - white_pixel unsigned long - app_group_leader Bool - - - -Example: - ... - Boolean app_group_leader, single_screen; - Window default_root; - VisualID root_visual; - Colormap default_colormap; - Pixel black_pixel, white_pixel; - ... - status = XagGetApplicationGroupAttributes(dpy, app_group, - XagNappGroupLeader, &app_group_leader, - XagNsingleScreen, &single_screen, - XagNdefault_root, &default_root, - XagNrootVisual, &root_visual, - XagNdefaultColormap, &default_colormap, - XagNblackPixel, &black_pixel, - XagNwhitePixel, &white_pixel, - NULL); - ... - - - - -To determine which Application Group a resource (such as a window) belongs to, use XagQueryApplicationGroup. - - - - - - - - -Status XagQueryApplicationGroup( - - - - - Display* dpy, - - - - - XID resource, - - - - - XAppGroup* app_group_return); - - - - - - - - -The Application Group is returned in app_group_return, if the resource is not in any Application Group then app_group_return will be set to None. - - - -To associate an X Window ID with a system-specific window ID, such as a HWND or a WindowPtr, use XagCreateAssociation. - - - - - - - - -Status XagCreateAssociation( - - - - - Display* dpy, - - - - - Window* window_return, - - - - - void* system_window); - - - - - - - - -The window_ret may be used as the target for a ReparentWindow request. - - - -Because XReparentWindow is not constrained in the same way that Win32’s SetParent and the Macintosh are, there is no reason to call XagCreateAssociation in an X-based embedding manager. As such if XagCreateAssociation is called in a native X program, the window_return will be the same as the system_window, and the implementation may even elect to not generate any protocol. - - -To create an association on the Macintosh: - - - struct { - WindowPtr win; - Rect rect; - } system_window; - system_window.win = win_ptr; - system_window.rect.top = system_window.rect.left = 20; - system_window.rect.bottom = 180; - system_window.rect.right = 380; - - - - status = XagCreateAssociation (dpy, &window, (void*)&system_window); - - - -To create an association using a Win16, Win32, or OS/2 PM: - - - - HWND system_window; - status = XagCreateAssociation (dpy, &window, (void*)&system_window); - - - -To destroy the association created with XagCreateAssociation use XagDestroyAssociation. - - - - - - - - - -Status XagDestroyAssociation( - - - - - Display* dpy, - - - - - Window window); - - - - - - - -After calling XagDestroyAssociation the window may no longer be used to -reparent windows with XReparentWindow. - - - -Like XagCreateAssociation, if the native window system is X11 the implementation may elect to not generate any protocol as a result of this function call in order to avoid unintentionally destroying the the system_window that was specified in the prior XagCreateAssociation call. - - - -
diff --git a/specs/appgrp.xml b/specs/appgrp.xml new file mode 100644 index 0000000..099fca1 --- /dev/null +++ b/specs/appgrp.xml @@ -0,0 +1,1018 @@ + + + +
+ + + Application Group Extension to the X Protocol + X Consortium Standard + + + Kaleb + S. + KEITHLEY + X Consortium, Inc + kaleb@x.org + + + X Version 11, Release 6.4 + 27 September 1996 + + + +Copyright © 1996 X Consortium, Inc. All Rights Reserved. + + + +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 OF 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. + + + + + +The Application Group Extension to the X protocol is intended to provide a framework to allow +more than one program to manage X applications on the desktop. The initial use of this extension +will be to insert or embed the windows of X programs into the windows of another program, such +as a web browser. This extension is not intended to address larger embedding issues that, for +example, OpenDoc does, such as shared menu bars, etc. + + + + + +Purpose and Goals + + +The Application Group Extension to the X protocol is intended to provide +a framework to allow more than one program to manage X applications on +the desktop. The initial use of this extension will be to insert or embed +the windows of X programs into the windows of another program, such as a +web browser. This extension is not intended to address larger embedding +issues that, for example, OpenDoc does, such as shared menu bars, etc. +Using X programs on the World Wide Web allows for greater control of the +presentation and takes advantage of the existing body of X programs rather +than re-implement them in another language. In addition it allows the +embedding of non-X programs into web browsers by using third party products +like Wabi, MAE, and WinCenter. + +Wabi is a trademark of Sun Microsystems, Inc. MAE is a trademark of Apple +Computer, Inc. WinCenter is a trademark of Network Computing Devices, Inc. + + + + + + +Overview of the protocol. + + +This extension introduces the concept of an Application Group. An Application Group is a set of one or more applications that are primarily managed by a special application known as the Application Group Leader, which, for example, might be a web browser. The primary purpose of Application Groups is to provide a means of sharing the Substructure-Redirect attribute of the root window between the window manager and one or more Application Group Leaders. + + + +To join an Application Group an application must present the proper authorization during the connection setup. Authorizations are generated by the X server at the request of an Application Group Leader, and are then stored for the application to use to establish its connection to the X server. To generate an authorization the Application Group Leader sends a request to the server naming the Application Group to which the authorization will be bound, and any applications that connect using that authorization will automatically become part of the associated Application Group. The protocol to generate an authorization is defined in the Security Extension specification. + + + +As a member of an Application Group, when an application creates and maps a window as a child of the root window, the MapRequest and ConfigureRequest events are delivered to the Application Group Leader instead of the window manager. The Application Group Leader may then reparent the window into its own window hierarchy; or reissue the map request, in which case the window comes under the control of the window manager. + + + + +Requests + + +AppGroupQueryVersion + + + + + + + client_major_version: CARD16 + + + client_minor_version: CARD16 + + + => + + + server_major_version: CARD16 + + + server_minor_version: CARD16 + + + + + + +If supplied, the client_major_version and client_minor_version indicate what version of the protocol the application wants the server to implement. The server version numbers returned indicate the version of the protocol the X server actually supports. This may not match the versions requested by the application. An implementation may (but need not) support more than one version simultaneously. The server_major_version and server_minor_version numbers are a mechanism to support any future revisions of the Application Group extension protocol which may be necessary. In general, the major version would increment for incompatible changes, and the minor version would increment for small, upward-compatible changes. X servers that support the protocol defined in this document will return a server_major_version of 1 and a server_minor_version of 0. + + + +AppGroupCreate + + + + + + + app_group: APPGROUP + + + value_mask: BITMASK + + + value_list: LISTofVALUE + + + + + + +This request creates an Application Group using app_group as the Application Group ID. + + + + +  + + + + +The value_mask and value_list specify attributes of the Application Group that are to be explicitly initialized. The attributes, their types, and the default values are: + + + + + + + + + + Attribute + Type + Default + + + app_group_leader + Bool + True + + + single_screen + Bool + True + + + default_root + Window + None + + + root_visual + VisualID + None + + + default_colormap + Colormap + None + + + black_pixel + Pixel + 0 + + + white_pixel + Pixel + 0 + + + + + + +If the single_screen attribute is True then the number of video screens returned to a program in the Application Group in the connection setup message is one, irrespective of how many video screens the server actually has. If a server supports both video and print screens, then all print screens will always be returned. If single_screen is specified as True then the connection setup message will contain only the information about the video screen which has default_root as its root window, plus any print screens. + + + +The intent is to allow an embedding manager to ensure that it will be able to reparent any top-level windows that Application Group members create. By hiding the fact that there are other screens it can be reasonably assured that applications will only create top-level windows on the same screen that it itself appears on. An embedding manager should take care not to supply an invalid display, e.g. :0.1, to a program that will be in an Application Group where the single_screen attribute is True. + + + +If single_screen is set to True default_root specifies which screen will be returned as screen zero in the connection setup message for applications in the Application Group. If set to None, then the real screen zero is used, otherwise the screen which has default_root as its root window will be used. + + + + +If single_screen is set to True the root_visual and default_colormap attributes may be used to over-ride the default values that are returned in the connection setup information returned to new programs in the Application Group. If None is specified for root_visual or default_colormap then the normal default values for the screen (possibly spedified by default_root) are used, otherwise the specified values are used. If root_visual and/or default_colormap are specified they must be valid, i.e. root_visual must be a visual type available on the screen, and the colormap, if specified, must be a valid colormap for the visual that is used. + + + +IF single_screen is set to True and default_colormap is not specified as None, the black_pixel and white_pixel attributes must be specified, and they will over-ride the default values that are returned in the connection setup returned to new programs in the Application Group. If default_colormap is specified as None and black_pixel and/or white_pixel are specified, they will be ignored. + + + +The app_group_leader attribute is used to identify the Application Group Leader program for the app_group. By specifying True the server will identify the program making the request as the Application Group Leader for the application group. The Application Group Leader receives MapRequest and ConfigureRequest events from the server when an attempt is made to map or configure top-level windows of a program in an Application Group, instead of being sent to a window manager that has selected SubstructureRedirect events on the root window. The parent window field in these events will contain the Application Group ID. + + +AppGroupDestroy + +app_group: APPGROUP + + + +This request destroys the app_group. If the app_group_leader attribute for the app_group is True, then any applications in the Application Group that are still connected will be killed as if a KillClient request had been received for that application. + + + +If the application that created a non-embedded Application Group exits, and therefore any Authorizations to be cancelled, and any applications that attempt to open new connections to the X server using one of those Authorizations will be unable to do so. + + +AppGroupGetAttr + + + + + + + + >app_group: APPGROUP + + + => + + + LISTofVALUE + + + + + + +This request returns the application group attributes for app_group. + + +AppGroupQuery + + + + + + + resource: XID + + + => + + + app_group: APPGROUP + + + + + + +This request returns the Application Group ID of the application that created resource or None if that application is not associated with any Application Group. The resource value may be the resource base of the application. + + +AppGroupCreateAssociation + + + + + + + window: WINDOW + + + window_type: CARD32 + + + system_window: LISTofCARD8 + + + + + + +This request associates window with system_window. The window_type indicates the native window system of the application making the request. For non-X window_types both the embedding manager and the server must be executing on the same host. When system_window is Microsoft Windows or OS/2 Presentation Manager, the system_window is an HWND; when the native window system is Macintosh, the system_window is a WindowPtr and a Rect. The window may be used for any X request that takes a Window. + + +AppGroupDestroyAssociation + + + + + + + window: WINDOW + + + + + + +This request destroys the association created with AppGroupCreateAssociation. The window is destroyed. The system_window that was specified in the AppGroupCreateAssociation request is not affected. + + + + + +Changes to Existing Requests + + +MapWindow + + +If the override-redirect attribute of the window is False and if the window is a child of a root window and if the window belongs to an application that is in an application group and if some other application is the application group leader for that group, then a MapRequest event is generated and the window remains unmapped. Otherwise, the core protocol semantics apply. + + + + +ConfigureWindow + + +If the override-redirect attribute of the window is False and if the window is a child of a root window and if the window belongs to an application that is in an application group and if some other application is the application group leader for that group, then a ConfigureRequest event is generated and the window remains unchanged. Otherwise, the core protocol semantics apply. + + + + +CreateWindow + + +When a program in an Application Group creates a window that is a child of a root window and specifies CopyFromParent for the Visual, if the single_screen attribute is True and the root_visual attribute is set to something other than None, then the window will be created using the Application Group’s root_visual, otherwise core protocol semantics apply. + + + +When a program in an Application Group creates a window that is a child of a root window and specifies CopyFromParent for the Colormap, if the single_screen attribute is True, the default_colormap attribute is set to something other than None, and the window’s Visual is the same as the Application Group’s root_visual attribute, then the window will be created using the Application Group’s default_colormap, otherwise core protocol semantics apply. + + + + + +ChangeWindowAttributes + + +When a program in an Application Group changes the attributes of a window that is a child of a root window and specifies CopyFromParent for the Colormap, if the single_screen attribute is True, the default_colormap attribute is set to something other than None, and the window’s Visual is the same as the Application Group’s root_visual attribute, then the window will be created using the Application Group’s default_colormap, otherwise core protocol semantics apply. + + + + + + + +Changes to Existing Events + + +When the top-level window of an application that is a member of an Application Group is the target of a MapWindow or ConfigureWindow request, if there is an Application Group Leader then MapRequest and ConfigureRequest events are automatically delivered to it, otherwise the core protocol semantics apply, i.e. they are delivered to the client, if any, that has SubstructureRedirect set in its root-window event mask, e.g. the window manager. + + + +The Application Group Leader must not select SubstructuRedirect events on a root window as doing so would result in a core protocol error; only one client is permitted to do so, and that is usually the window manager. + + + + +MapRequest + + +When a MapWindow request is received for a window whose override-redirect attribut is set to False and whose parent is the root window and the window belongs to an application that is in an application group and there is an application group leader for the group, then this event is delivered to the Application Group Leader with the parent field in the event set to the AppGroup ID. Otherwise the core protocol semantics apply. + + + + +ConfigureRequest + + +When a ConfigureWindow request is received for a window whose override-redirect attribut is set to False and whose parent is the root window and the window belongs to an application that is in an application group and there is an application group leader for the group, then this event is delivered to the Application Group Leader with the parent field in the event set to the AppGroup ID. Otherwise the core protocol semantics apply. + + + + + + +Errors + + +AppGroupQueryVersion + + +There are no errors for AppGroupQueryVersion. + + + + + +AppGroupCreate + + +A Window error is returned if default_root is specified and is not a valid root window.. + + + +A Color error is returned default_colormap is specified but default_colormap is not a valid colormap for the screen of default_root. + + + +A Match error is returned if root_visual and default_colormap are both specified, but + + + +default_colormap’s visual is not root_visual. + + + +A Match error is returned if root_visual does not exist for the screen of the default_root. + + + + + +AppGroupDestroy + + +An AppGroup error is returned if app_group is not a valid Application Group. + + + +An Access error is returned if an untrusted application attempts to destroy an Application Group created by a trusted application. + + + + + +AppGroupGetAttr + + +An AppGroup error is returned if app_group is not a valid Application Group. + + + +An Access error is returned if an untrusted application attempts to get the attributes of an Application Group created by a trusted application. + + + + + +AppGroupQuery + + +An Access error is returned if an untrusted application attempts to query the Application Group of a trusted application. + + + + + +AppGroupCreateAssociation + + +A Match error is returned if the X server does not support the window_type. + + + +An Access error may be returned if the X server only supports the window_type on the local host and the program making the request is on a non-local host. + + + +A Window error may be returned for system-specific errors related to system_window, e.g. system_window does not represent a valid native window. + + + + + +AppGroupDestroyAssociation + + +A Window error is returned if window was not specified in a previous AppGroupCreateAssociation request. + + + + + + +Encoding + + +Please refer to the X11 Protocol encoding document as this document uses conventions established there. + + + + +The name of this extension is XC-APPGROUP + + + + +AppGroupQueryVersion + 1 CARD8 opcode + 1 0 XC-APPGROUP opcode + 2 3 length + 2 CARD16 client_major_version + 2 CARD16 client_minor_version +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence_number + 4 0 length + 2 CARD16 server_major_version + 2 CARD16 server_minor_version + 20 unused + + + + +AppGroupCreate + 1 CARD8 opcode + 1 1 XC-APPGROUP opcode + 2 8+n length + 4 XID app_group + 4 BITMASK attrib_mask + #x00000001 app_group_leader + #x00000002 single_screen + #0x0000004 default_root + #x00000008 root_visual + #x00000010 default_colormap + #x00000020 black_pixel + #x00000040 white_pixel + n LISTofVALUE value-list +VALUEs + 4 BOOL app_group_leader + 4 BOOL single_screen + 4 WINDOW default_root + 4 VISUALID root_visual + 4 COLORMAP default_colormap + 4 CARD32 black_pixel + 4 CARD32 white_pixel + + + + +AppGroupDestroy + 1 CARD8 opcode + 1 2 XC-APPGROUP opcode + 2 2 length + 4 XID app_group + + + +AAppGroupGetAttr + 1 CARD8 opcode + 1 4 XC-APPGROUP opcode + 2 2 length + 4 XID app_group +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence_number + 4 0 length + 4 WINDOW default_root + 4 VISUALID root_visual + 4 COLORMAP default_colormap + 4 CARD32 black_pixel + 4 CARD32 whte_pixel + 1 BOOL single_screen + 1 BOOL app_group_leader + 2 unused + + + + +AppGroupQuery + 1 CARD8 opcode + 1 5 XC-APPGROUP opcode + 2 2 length + 4 XID resource +=> + 1 1 Reply + 1 unused + 2 CARD16 sequence_number + 4 0 length + 4 XID app_group + 20 unused + + + +AppGroupCreateAssoc + 1 CARD8 opcode + 1 6 XC-APPGROUP opcode + 2 n length + 4 WINDOW window + 2 CARD16 window_type + #0 X11 + #1 Macintosh + #2 Win32, OS/2 PM 2.x + #3 Win16, OS/2 PM 1.x + 2 n system_window_len + n LISTofCARD8 system_window + + + + +AppGroupDestroyAssoc + 1 CARD8 opcode + 1 7 XC-APPGROUP opcode + 2 2 length + 4 WINDOW window + + + + + +Library API + + + + + + + +Status XagQueryVersion ( xkb, keycode) /* macro */ + + + + +Display dpy; + + + + +int * major_version_return; + + + + +int * minor_version_return; + + + + + + + +XagQueryVersion sets major_version_return and minor_version_return to the major and minor Application Group protocol version supported by the server. If the Xag library is compatible with the version returned by the server it returns non-zero. If dpy does not support the Application Group extension, or if the server and library protocol versions are incompatible, or if there was an error during communication with the server, it returns zero. No other Xag functions may be called before this function. If a program violates this rule, the effects of all subsequent Xag calls that it makes are undefined. + + + +An embedding manager in, e.g. a Personal Computer Web Browser, will need to open a connection to the Personal Computer X server by calling XOpenDisplay() before using the Application Group extension. + + + +An embedding manager such as a web browser that intends to embed programs in an Application Group should create the Application Group with XagCreateEmbeddedApplicationGroup. + + + + + + + + + +Status XagCreateEmbeddedApplicationGroup( + + + + + Display* dpy, + + + + + VisualID root_visual, + + + + + Colormap default_colormap, + + + + + unsigned long black_pixel, + + + + + unsigned long white_pixel, + + + + + XAppGroup* app_group_return); + + + + + + + + +XagCreateEmbeddedApplicationGroup creates an Application Group for an embedding manager with the attributes specified. It also sets the default_root attribute to DefaultRoot(dpy, DefaultsScreen(dpy)) and the single_screen and app_group_leader attributes to True. It returns the Application Group ID in app_group_return. + + + +You can create an Application Group without intending to do embedding. One reason for doing this is to give a group of clients their own font-path. + + + +A special font-path can be created by creating an Application Group, getting an Authorization using XSecurityGenerateAuthorization, and then running ‘xset fp+ <new font path>’ as a member of the Application Group. Font-path elements added in this way will be "private" to the Application Group. + + + + + + + + +Status XagCreateNonembeddedApplicationGroup( + + + + + Display* dpy, + + + + + XAppGroup* app_group_return); + + + + + + + +An Application Group created with XagCreateNonembeddedApplicationGroup will have the default_root, root_visual, and default_colormap attributes all set to None; the single_screen and app_group_leader attributes are set to False, and the black_pixel and white_pixel attributes are not used since the default_colormap attribute is None. + + + +To destroy an Application Group use XagDestroyApplicationGroup. + + + + + + + + +Status XagDestroyApplicationGroup( + + + + + Display* dpy, + + + + + XAppGroup app_group); + + + + + + + +The Application Group specified by app_group is destroyed. If the Application Group was created using XagCreateEmbeddingApplicationGroup, i.e. and therefore the app_group_leader attribute is True, all programs that are members of the Application Group are killed as if a KillClient request had been issued. + + + + +To retrieve the attributes of an Application Group use XagGetApplicationGroupAttributes. + + + + + + + + + +Status XagGetApplicationGroupAttributes( + + + + + Display* dpy, + + + + + XAppGroup app_group, + + + + + ...); + + + + + + + + + +XagGetApplicationGroupAttributes is a varargs function that retrieves the Application Group’s attributes specified in the vararg parameter list. + + + +The attributes that may be specified are: XagNappGroupLeader, XagNsingleScreen, XagNdefaultRoot, XagNrootVisual, XagNdefaultColormap, XagNblackPixel, and XagNwhitePixel; which correspond to app_group_leader, single_screen, default_root, root_visual, default_colormap, black_pixel, and white_pixel respectively. See AppGroupCreate in Section 3 for a description of each attribute. + + + +The types for each of the parameters are pointers to the following: + + + + single_screen Bool + default_root Window + root_visual VisualID + default_colormap Colormap + black_pixel unsigned long + white_pixel unsigned long + app_group_leader Bool + + + +Example: + ... + Boolean app_group_leader, single_screen; + Window default_root; + VisualID root_visual; + Colormap default_colormap; + Pixel black_pixel, white_pixel; + ... + status = XagGetApplicationGroupAttributes(dpy, app_group, + XagNappGroupLeader, &app_group_leader, + XagNsingleScreen, &single_screen, + XagNdefault_root, &default_root, + XagNrootVisual, &root_visual, + XagNdefaultColormap, &default_colormap, + XagNblackPixel, &black_pixel, + XagNwhitePixel, &white_pixel, + NULL); + ... + + + + +To determine which Application Group a resource (such as a window) belongs to, use XagQueryApplicationGroup. + + + + + + + + +Status XagQueryApplicationGroup( + + + + + Display* dpy, + + + + + XID resource, + + + + + XAppGroup* app_group_return); + + + + + + + + +The Application Group is returned in app_group_return, if the resource is not in any Application Group then app_group_return will be set to None. + + + +To associate an X Window ID with a system-specific window ID, such as a HWND or a WindowPtr, use XagCreateAssociation. + + + + + + + + +Status XagCreateAssociation( + + + + + Display* dpy, + + + + + Window* window_return, + + + + + void* system_window); + + + + + + + + +The window_ret may be used as the target for a ReparentWindow request. + + + +Because XReparentWindow is not constrained in the same way that Win32’s SetParent and the Macintosh are, there is no reason to call XagCreateAssociation in an X-based embedding manager. As such if XagCreateAssociation is called in a native X program, the window_return will be the same as the system_window, and the implementation may even elect to not generate any protocol. + + +To create an association on the Macintosh: + + + struct { + WindowPtr win; + Rect rect; + } system_window; + system_window.win = win_ptr; + system_window.rect.top = system_window.rect.left = 20; + system_window.rect.bottom = 180; + system_window.rect.right = 380; + + + + status = XagCreateAssociation (dpy, &window, (void*)&system_window); + + + +To create an association using a Win16, Win32, or OS/2 PM: + + + + HWND system_window; + status = XagCreateAssociation (dpy, &window, (void*)&system_window); + + + +To destroy the association created with XagCreateAssociation use XagDestroyAssociation. + + + + + + + + + +Status XagDestroyAssociation( + + + + + Display* dpy, + + + + + Window window); + + + + + + + +After calling XagDestroyAssociation the window may no longer be used to +reparent windows with XReparentWindow. + + + +Like XagCreateAssociation, if the native window system is X11 the implementation may elect to not generate any protocol as a result of this function call in order to avoid unintentionally destroying the the system_window that was specified in the prior XagCreateAssociation call. + + + +
-- cgit v1.2.3 From d16788e87438015d3e121ffb046bc6a4ce01da89 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Fri, 25 Feb 2011 08:51:47 -0500 Subject: Docbook: change the book id to match the xml file basename This is required for the up-coming external references support. Signed-off-by: Gaetan Nadon --- specs/multibuf.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'specs') diff --git a/specs/multibuf.xml b/specs/multibuf.xml index eb01829..1c8e363 100644 --- a/specs/multibuf.xml +++ b/specs/multibuf.xml @@ -4,7 +4,7 @@ - + Extending X for Double-Buffering, Multi-Buffering, and Stereo -- cgit v1.2.3 From a6a542841e85344115bbb6a1ba35c4f3487995e4 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Fri, 25 Feb 2011 08:53:55 -0500 Subject: Docbook: change the book id to match the xml file basename This is required for the up-coming external references support. Signed-off-by: Gaetan Nadon --- specs/shm.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'specs') diff --git a/specs/shm.xml b/specs/shm.xml index 19d9309..127412c 100644 --- a/specs/shm.xml +++ b/specs/shm.xml @@ -4,7 +4,7 @@ - + MIT-SHM(The MIT Shared Memory Extension) -- cgit v1.2.3 From 6dba94ecadfa4f58dd1b2ee0ceb39d4710900ac8 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Sun, 27 Feb 2011 15:06:18 -0500 Subject: Documentation: add Docbook external references support When writing technical documentation, it is often necessary to cross reference to other information. When that other information is not in the current document, additional support is needed, namely . A new feature with version 1.7 of xorg-sgml-doctools adds references to other documents within or outside this package. This patch adds technical support for this feature but does not change the content of the documentation as seen by the end user. Each book or article must generate a database containing the href of sections that can be referred to from another document. This database is installed in DATAROOTDIR/sgml/X11/dbs. There is a requirement that the value of DATAROOTDIR for xorg-sgml-doctools and for the package documentation is the same. This forms a virtual document tree. This database is consulted by other documents while they are being generated in order to fulfill the missing information for linking. Refer to the xorg-sgml-doctools for further technical information. Co-authored-by: Matt Dew Signed-off-by: Gaetan Nadon --- specs/.gitignore | 1 + specs/Makefile.am | 64 +++++++++---------------------------------------------- 2 files changed, 11 insertions(+), 54 deletions(-) (limited to 'specs') diff --git a/specs/.gitignore b/specs/.gitignore index 6fa5c31..92946c9 100644 --- a/specs/.gitignore +++ b/specs/.gitignore @@ -2,3 +2,4 @@ *.ps *.pdf *.txt +*.db diff --git a/specs/Makefile.am b/specs/Makefile.am index e689dff..b319f8b 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -1,28 +1,9 @@ -# -# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. -# -# 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 (including the next -# paragraph) 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 AUTHORS OR COPYRIGHT HOLDERS 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. -# if ENABLE_SPECS -doc_sources = \ +if HAVE_XMLTO + +# Main DocBook/XML files (DOCTYPE book) +docbook = \ appgrp.xml \ dbe.xml \ dpms.xml \ @@ -37,39 +18,14 @@ doc_sources = \ tog-cup.xml \ xtest.xml -dist_doc_DATA = $(doc_sources) appendix.xml - -if HAVE_XMLTO -doc_DATA = $(doc_sources:.xml=.html) - -if HAVE_FOP -doc_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf) -endif - -if HAVE_XMLTO_TEXT -doc_DATA += $(doc_sources:.xml=.txt) -endif - -if HAVE_STYLESHEETS -XMLTO_FLAGS = -m $(XSL_STYLESHEET) \ - --stringparam html.stylesheet=$(STYLESHEET_SRCDIR)/xorg.css -endif - -CLEANFILES = $(doc_DATA) - -SUFFIXES = .xml .ps .pdf .txt .html - -%.txt: %.xml $(dist_doc_DATA) - $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $< - -%.html: %.xml $(dist_doc_DATA) - $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $< +# Included chapters, appendix, images +chapters = appendix.xml -%.pdf: %.xml $(dist_doc_DATA) - $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $< +# The location where the DocBook/XML files and their generated formats are installed +shelfdir = $(docdir) -%.ps: %.xml $(dist_doc_DATA) - $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $< +# Generate DocBook/XML output formats with or without stylesheets +include $(top_srcdir)/docbook.am endif HAVE_XMLTO endif ENABLE_SPECS -- cgit v1.2.3 From 4f42558a78d3e14b611247249f3f300424f8ecd3 Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Wed, 25 May 2011 21:56:10 -0600 Subject: Add id attributes to funcsynopsis to allow other docs to olink to them. Signed-off-by: Matt Dew Reviewed-by: Alan Coopersmith Reviewed-by: Gaetan Nadon --- specs/evi.xml | 4 ++-- specs/security.xml | 10 +++++----- specs/shm.xml | 14 +++++++------- specs/tog-cup.xml | 6 +++--- 4 files changed, 17 insertions(+), 17 deletions(-) (limited to 'specs') diff --git a/specs/evi.xml b/specs/evi.xml index a565f73..12f8923 100644 --- a/specs/evi.xml +++ b/specs/evi.xml @@ -374,7 +374,7 @@ The include file for this extension is: < X11/extensions/XEVI.h>. - + Bool XeviQueryVersion Display *display @@ -433,7 +433,7 @@ To get the extended information for any subset of visuals use XeviGetVisualInfo. - + int XeviGetVisualInfo Display *display diff --git a/specs/security.xml b/specs/security.xml index ee132f3..828ea5c 100644 --- a/specs/security.xml +++ b/specs/security.xml @@ -1141,7 +1141,7 @@ All functions that have return type Status will return nonzero for success and zero for failure. - + Status XSecurityQueryExtension Display *dpy @@ -1162,7 +1162,7 @@ function. If a client violates this rule, the effects of all subsequent XSecurity calls that it makes are undefined. - + Xauth *XSecurityAllocXauth void @@ -1266,7 +1266,7 @@ The Xauth structure returned by this function is initialized as follows: name_length and data_length are zero, and name and data are NULL. - + void XSecurityFreeXauth Xauth *auth @@ -1287,7 +1287,7 @@ function, including the name and data fields. - + Bool XSecurityRevokeAuthorization Display *dpy @@ -1304,7 +1304,7 @@ clients that attempt to connect using that authorization will be refused. - + Xauth *XSecurityGenerateAuthorization Display *dpy diff --git a/specs/shm.xml b/specs/shm.xml index 127412c..a389c05 100644 --- a/specs/shm.xml +++ b/specs/shm.xml @@ -133,7 +133,7 @@ the net, or in some other environment where the extension will not work. To perform this check, call either - + Status XShmQueryExtension Display *display @@ -144,7 +144,7 @@ To perform this check, call either or - + Status XShmQueryVersion Display *display @@ -198,7 +198,7 @@ Use the shared memory XImage, much like a normal one. To create a shared memory XImage, use: - + XImage *XShmCreateImage Display *display @@ -313,7 +313,7 @@ ready for use. To write a shared memory XImage into an X drawable, use XShmPutImage: - + Status XShmPutImage Display *display @@ -376,7 +376,7 @@ completion event, the results you see on the screen may be inconsistent. To read image data into a shared memory XImage, use the following: - + Status XShmGetImage Display *display @@ -419,7 +419,7 @@ format is) and independent of the screen. Use XShmPixmapFormat to get the format for the server: - + int XShmPixmapFormat Display *display @@ -439,7 +439,7 @@ bytes_per_line value to use. Once you have your shminfo structure filled in, simply call: - + Pixmap XShmCreatePixmap Display *display diff --git a/specs/tog-cup.xml b/specs/tog-cup.xml index bb6fb25..4107ddc 100644 --- a/specs/tog-cup.xml +++ b/specs/tog-cup.xml @@ -354,7 +354,7 @@ The include file for this extension is <X11/extensions/Xcup.h>. - + Status XCupQueryVersion Display* display @@ -414,7 +414,7 @@ To get the list of reserved colormap entries, use XCupGetReservedColormapEntries. - + Status XCupGetReservedColormapEntries Display* display @@ -468,7 +468,7 @@ To allocate one or more read-only color cells with RGB values, use XCupStoreColors. - + Status XCupStoreColors Display* display -- cgit v1.2.3 From 84ddb52e2362953c2e646e85eb745c34c1c01e2a Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Sun, 12 Jun 2011 17:54:50 -0400 Subject: Install xml versions of specs even if HAVE_XMLTO is false DocBook/XML input source is also a usefull output format that can be viewed with an XML viewer or editor and by some O/S help system. Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 2 -- 1 file changed, 2 deletions(-) (limited to 'specs') diff --git a/specs/Makefile.am b/specs/Makefile.am index b319f8b..3b046a6 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -1,6 +1,5 @@ if ENABLE_SPECS -if HAVE_XMLTO # Main DocBook/XML files (DOCTYPE book) docbook = \ @@ -27,5 +26,4 @@ shelfdir = $(docdir) # Generate DocBook/XML output formats with or without stylesheets include $(top_srcdir)/docbook.am -endif HAVE_XMLTO endif ENABLE_SPECS -- cgit v1.2.3 From 2ff4ebb7014d739744d30a873c90530bc4103927 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Fri, 9 Sep 2011 21:03:36 -0400 Subject: Use more appropriate docbook element to get "Edited by" The proper element to use is . The was a hack to insert text and showed up in the wrong location Signed-off-by: Gaetan Nadon --- specs/shm.xml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'specs') diff --git a/specs/shm.xml b/specs/shm.xml index a389c05..a2e2eed 100644 --- a/specs/shm.xml +++ b/specs/shm.xml @@ -16,11 +16,10 @@ Atmospheric Technology Division National Center for Atmospheric Research corbet@ncar.ucar.edu - - Formatted and edited for release 5 by + KeithPackard MIT X Consortium - + X Consortium Standard 1991X Consortium -- cgit v1.2.3 From a19f712304f9a606dd2f9d805d5292b37371b31d Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Sun, 11 Sep 2011 19:49:54 -0400 Subject: docs: remove which is not used by default This element is not rendered by default on the title. A template customization is required to display it. X Window System does not have a product number. Signed-off-by: Gaetan Nadon --- specs/dpms.xml | 1 - specs/evi.xml | 1 - specs/security.xml | 1 - specs/shape.xml | 1 - specs/shm.xml | 1 - specs/sync.xml | 1 - specs/tog-cup.xml | 1 - 7 files changed, 7 deletions(-) (limited to 'specs') diff --git a/specs/dpms.xml b/specs/dpms.xml index 98aaaa3..5e759b4 100644 --- a/specs/dpms.xml +++ b/specs/dpms.xml @@ -18,7 +18,6 @@ X Consortium Standard 1996Digital Equipment Corporation X Consortium - X Version 11, Release 6.8 diff --git a/specs/evi.xml b/specs/evi.xml index 12f8923..86192f3 100644 --- a/specs/evi.xml +++ b/specs/evi.xml @@ -18,7 +18,6 @@ X Consortium Standard 1986-97The Open Group X Consortium - X Version 11, Release 6.8 diff --git a/specs/security.xml b/specs/security.xml index 828ea5c..300bc6c 100644 --- a/specs/security.xml +++ b/specs/security.xml @@ -21,7 +21,6 @@ xhtml,docbook,html,refcaption --> 1996X Consortium Version 7.1 X Consortium - X Version 11, Release 6.8 diff --git a/specs/shape.xml b/specs/shape.xml index 3386443..6c14f9b 100644 --- a/specs/shape.xml +++ b/specs/shape.xml @@ -25,7 +25,6 @@ 2004The Open Group 2006Keith Packard X Consortium - X Version 11, Release 7 diff --git a/specs/shm.xml b/specs/shm.xml index a2e2eed..f93c73a 100644 --- a/specs/shm.xml +++ b/specs/shm.xml @@ -24,7 +24,6 @@ X Consortium Standard 1991X Consortium X Consortium - X Version 11, Release 7 diff --git a/specs/sync.xml b/specs/sync.xml index 44a6b2c..7e51aea 100644 --- a/specs/sync.xml +++ b/specs/sync.xml @@ -52,7 +52,6 @@ Digital Equipment Corporation, Maynard, Massachusetts Version 3.1 X Consortium - X Version 11, Release 6.8 diff --git a/specs/tog-cup.xml b/specs/tog-cup.xml index 4107ddc..cf6f6dc 100644 --- a/specs/tog-cup.xml +++ b/specs/tog-cup.xml @@ -20,7 +20,6 @@ X Consortium Standard 1986-1997The Open Group X Consortium - X Version 11, Release 6.8 -- cgit v1.2.3 From 895d967d56711617ff59e2d2d60389609557072b Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Mon, 12 Sep 2011 11:23:00 -0400 Subject: docs: use the &fullrelvers; entity to set X11 release information Signed-off-by: Gaetan Nadon --- specs/appgrp.xml | 7 +++++-- specs/dbe.xml | 7 +++++-- specs/dpms.xml | 6 +++++- specs/evi.xml | 6 +++++- specs/geproto.xml | 6 +++++- specs/lbx.xml | 6 +++++- specs/multibuf.xml | 7 +++++-- specs/security.xml | 7 +++++-- specs/shape.xml | 6 +++++- specs/shm.xml | 6 +++++- specs/sync.xml | 7 +++++-- specs/tog-cup.xml | 6 +++++- specs/xtest.xml | 6 +++++- 13 files changed, 65 insertions(+), 18 deletions(-) (limited to 'specs') diff --git a/specs/appgrp.xml b/specs/appgrp.xml index 099fca1..74bc5fc 100644 --- a/specs/appgrp.xml +++ b/specs/appgrp.xml @@ -1,13 +1,17 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]>
Application Group Extension to the X Protocol X Consortium Standard + X Version 11, Release &fullrelvers; Kaleb @@ -17,7 +21,6 @@ kaleb@x.org - X Version 11, Release 6.4 27 September 1996 diff --git a/specs/dbe.xml b/specs/dbe.xml index c85dfda..5e0f9cf 100644 --- a/specs/dbe.xml +++ b/specs/dbe.xml @@ -1,6 +1,9 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> Double Buffer Extension Protocol X Consortium Standard - X Version 11, Release 6.4 + X Version 11, Release &fullrelvers; IanElliott diff --git a/specs/dpms.xml b/specs/dpms.xml index 5e759b4..48575a9 100644 --- a/specs/dpms.xml +++ b/specs/dpms.xml @@ -1,12 +1,16 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> X Display Power Management Signaling (DPMS) Extension Protocol Specification X Project Team Standard + X Version 11, Release &fullrelvers; Version 1.0 diff --git a/specs/evi.xml b/specs/evi.xml index 86192f3..23c76aa 100644 --- a/specs/evi.xml +++ b/specs/evi.xml @@ -1,6 +1,9 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> @@ -8,6 +11,7 @@ Extended Visual Information Extension X Project Team Standard + X Version 11, Release &fullrelvers; Version 1.0 diff --git a/specs/geproto.xml b/specs/geproto.xml index 3356d45..fe1848f 100644 --- a/specs/geproto.xml +++ b/specs/geproto.xml @@ -1,9 +1,13 @@ +"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> X Generic Event Extension + X Version 11, Release &fullrelvers; Peter diff --git a/specs/lbx.xml b/specs/lbx.xml index f42f9f9..8d7a89d 100644 --- a/specs/lbx.xml +++ b/specs/lbx.xml @@ -1,13 +1,17 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]>
Low Bandwidth X Extension X Consortium Standard + X Version 11, Release &fullrelvers; D. diff --git a/specs/multibuf.xml b/specs/multibuf.xml index 1c8e363..f85dc41 100644 --- a/specs/multibuf.xml +++ b/specs/multibuf.xml @@ -1,6 +1,9 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> @@ -8,7 +11,7 @@ Extending X for Double-Buffering, Multi-Buffering, and Stereo - X Version 11, Release 6.4 + X Version 11, Release &fullrelvers; diff --git a/specs/security.xml b/specs/security.xml index 300bc6c..a380987 100644 --- a/specs/security.xml +++ b/specs/security.xml @@ -1,6 +1,9 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> @@ -10,7 +13,7 @@ xhtml,docbook,html,refcaption --> Security Extension Specification X Consortium Standard - X Version 11, Release 6.8 + X Version 11, Release &fullrelvers; November 15, 1996 diff --git a/specs/shape.xml b/specs/shape.xml index 6c14f9b..c24928e 100644 --- a/specs/shape.xml +++ b/specs/shape.xml @@ -1,6 +1,9 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> @@ -9,6 +12,7 @@ X Nonrectangular Window Shape Extension Protocol X.Org Standard + X Version 11, Release &fullrelvers; Version 1.1 diff --git a/specs/shm.xml b/specs/shm.xml index f93c73a..8a0fd56 100644 --- a/specs/shm.xml +++ b/specs/shm.xml @@ -1,6 +1,9 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> @@ -9,6 +12,7 @@ MIT-SHM(The MIT Shared Memory Extension) How the shared memory extension works + X Version 11, Release &fullrelvers; Version 1.0 diff --git a/specs/sync.xml b/specs/sync.xml index 7e51aea..cf316b4 100644 --- a/specs/sync.xml +++ b/specs/sync.xml @@ -1,6 +1,9 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> @@ -11,7 +14,7 @@ by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,ref X Synchronization Extension Protocol X Consortium Standard - X Version 11, Release 6.6.84 + X Version 11, Release &fullrelvers; TimGlauert diff --git a/specs/tog-cup.xml b/specs/tog-cup.xml index cf6f6dc..12ba787 100644 --- a/specs/tog-cup.xml +++ b/specs/tog-cup.xml @@ -1,6 +1,9 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> @@ -8,6 +11,7 @@ Colormap Utilization Policy and Extension X Project Team Standard + X Version 11, Release &fullrelvers; Version 1.0 diff --git a/specs/xtest.xml b/specs/xtest.xml index cdf5e63..cb73f29 100644 --- a/specs/xtest.xml +++ b/specs/xtest.xml @@ -1,12 +1,16 @@ + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + %defs; +]> XTEST Extension Protocol X Consortium Standard + X Version 11, Release &fullrelvers; Version 2.2 -- cgit v1.2.3 From 08f39a5f52ef9e10ae7b32d9ae21d64f5eaef354 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 14 Sep 2011 20:55:08 -0400 Subject: sync: fix author name and authors affiliation Signed-off-by: Gaetan Nadon --- specs/sync.xml | 48 +++++++++++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 19 deletions(-) (limited to 'specs') diff --git a/specs/sync.xml b/specs/sync.xml index cf316b4..16c48dd 100644 --- a/specs/sync.xml +++ b/specs/sync.xml @@ -16,25 +16,35 @@ by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,ref X Consortium Standard X Version 11, Release &fullrelvers; - - 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. - + + TimGlauert + + Olivetti Research + MultiWorks + + + + Dave + Carver + + Digital Equipment Corporation + MIT/Project Athena + + + + Jim + Gettys + + Digital Equipment Corporation + Cambridge Research Laboratory + + + + David + P. + Wiggins + X Consortium, Inc. + James Jones -- cgit v1.2.3 From b1f8a6d384b6866ce70c8289a727d25aa5de7dbf Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Tue, 20 Sep 2011 20:54:02 -0400 Subject: appgrp: use markup and minor titlepage fixes Signed-off-by: Gaetan Nadon --- specs/appgrp.xml | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'specs') diff --git a/specs/appgrp.xml b/specs/appgrp.xml index 74bc5fc..dfeee9e 100644 --- a/specs/appgrp.xml +++ b/specs/appgrp.xml @@ -11,7 +11,6 @@ Application Group Extension to the X Protocol X Consortium Standard - X Version 11, Release &fullrelvers; Kaleb @@ -21,15 +20,18 @@ kaleb@x.org - 27 September 1996 + X Version 11, Release &fullrelvers; + Version 1.0 + 1996X Consortium, Inc. + -Copyright © 1996 X Consortium, Inc. All Rights Reserved. +All Rights Reserved. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +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, @@ -42,8 +44,11 @@ Except as contained in this notice, the name of the X Consortium shall not be us or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium. +X Window System is a trademark of The OpenGroup. +27 September 1996 + The Application Group Extension to the X protocol is intended to provide a framework to allow -- cgit v1.2.3 From 40814443d5f73f340879719d945f6a8cfd2fb3fd Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 09:26:11 -0400 Subject: dbe spec: fix author affiliation and copyright notices Signed-off-by: Gaetan Nadon --- specs/dbe.xml | 41 ++++++++++++++++------------------------- 1 file changed, 16 insertions(+), 25 deletions(-) (limited to 'specs') diff --git a/specs/dbe.xml b/specs/dbe.xml index 5e0f9cf..8c87548 100644 --- a/specs/dbe.xml +++ b/specs/dbe.xml @@ -15,33 +15,24 @@ xhtml,docbook,html,refcaption --> Double Buffer Extension Protocol X Consortium Standard - X Version 11, Release &fullrelvers; - - IanElliott - + + IanElliott + Hewlett-Packard Company + + + DavidP.Wiggins + X Consortium + - - DavidWiggins - X Consortium - - Hewlett-Packard Company - - 1989 - X Consortium, Inc and Digital Equipment Corporation - - - 1992 - X Consortium, Inc and Intergraph Corporation - - - 1993 - X Consortium, Inc and Silicon Graphics, Inc - - - 1994 - X Consortium, Inc and Hewlett-Packard Company + 1989199219931994 + X Consortium, Inc. + 1989Digital Equipment Corporation + 1992Intergraph Corporation + 1993Silicon Graphics, Inc. + 1994Hewlett-Packard Company + X Version 11, Release &fullrelvers; Version 1.0 @@ -51,7 +42,7 @@ 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" +of the information in this document. This documentation is provided “as is” without express or implied warranty. -- cgit v1.2.3 From ff0477883d6015e00b5f323c697d2bdd7e746298 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 09:44:15 -0400 Subject: dpms spec: fix author affiliation Signed-off-by: Gaetan Nadon --- specs/dpms.xml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'specs') diff --git a/specs/dpms.xml b/specs/dpms.xml index 48575a9..fe97da9 100644 --- a/specs/dpms.xml +++ b/specs/dpms.xml @@ -10,8 +10,6 @@ X Display Power Management Signaling (DPMS) Extension Protocol Specification X Project Team Standard - X Version 11, Release &fullrelvers; - Version 1.0 Rob Lembree @@ -19,9 +17,9 @@ lembree@zk3.dec.com - X Consortium Standard + X Version 11, Release &fullrelvers; + Version 1.0 1996Digital Equipment Corporation - X Consortium @@ -31,7 +29,7 @@ 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. +provided “as is” without express or implied warranty. -- cgit v1.2.3 From 91f892076e7fa842993aa2ce17eafd8c61fbe024 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 09:52:43 -0400 Subject: evi spec: fix copyright and orphan markup Signed-off-by: Gaetan Nadon --- specs/evi.xml | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) (limited to 'specs') diff --git a/specs/evi.xml b/specs/evi.xml index 23c76aa..8489b37 100644 --- a/specs/evi.xml +++ b/specs/evi.xml @@ -11,17 +11,15 @@ Extended Visual Information Extension X Project Team Standard - X Version 11, Release &fullrelvers; - Version 1.0 PeterDaifuku Silicon Graphics, Inc. - X Consortium Standard - 1986-97The Open Group - X Consortium + X Version 11, Release &fullrelvers; + Version 1.0 + 1986-1997The Open Group @@ -42,7 +40,7 @@ included in all copies of the Software: -THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, +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 NON- INFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY -- cgit v1.2.3 From 414fdfca99ac0b787ce63777024fa306126f4505 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 10:12:06 -0400 Subject: geproto: fix author's e-mail Signed-off-by: Gaetan Nadon --- specs/geproto.xml | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) (limited to 'specs') diff --git a/specs/geproto.xml b/specs/geproto.xml index fe1848f..7684ac8 100644 --- a/specs/geproto.xml +++ b/specs/geproto.xml @@ -7,17 +7,12 @@ X Generic Event Extension - X Version 11, Release &fullrelvers; - Peter - Hutterer - - - peter.hutterer@who-t.net - + peter.hutterer@who-t.net + X Version 11, Release &fullrelvers; -- cgit v1.2.3 From 11529183d7294901074332e1369364fc0ed0cafa Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 10:20:31 -0400 Subject: lbx: complete the authors name Signed-off-by: Gaetan Nadon --- specs/lbx.xml | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) (limited to 'specs') diff --git a/specs/lbx.xml b/specs/lbx.xml index 8d7a89d..a06569d 100644 --- a/specs/lbx.xml +++ b/specs/lbx.xml @@ -11,45 +11,42 @@ Low Bandwidth X Extension X Consortium Standard - X Version 11, Release &fullrelvers; - D. + Donna Converse - J. + Jim Fulton - D. + David Lemke - R. + Ralph Mor - K. + Keith Packard - R. + Ray Tice - D. + Dale Tonogai - Protocol Version 1.0 - + X Version 11, Release &fullrelvers; + Version 1.0 + 1996X Consortium -Copyright (c) 1996 X Consortium - - 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 @@ -65,7 +62,7 @@ copies or substantial portions of the Software. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +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 @@ -78,11 +75,9 @@ used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium. - - +X Window System is a trademark of The OpenGroup. - -- cgit v1.2.3 From ac60c5c5081690e2984192a8aeed7790c8b98297 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 10:30:12 -0400 Subject: multibuf spec: refactor copyright legal text for multi licensing Signed-off-by: Gaetan Nadon --- specs/multibuf.xml | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) (limited to 'specs') diff --git a/specs/multibuf.xml b/specs/multibuf.xml index f85dc41..39a5dbf 100644 --- a/specs/multibuf.xml +++ b/specs/multibuf.xml @@ -11,8 +11,6 @@ Extending X for Double-Buffering, Multi-Buffering, and Stereo - X Version 11, Release &fullrelvers; - JeffreyFriedberg @@ -25,10 +23,8 @@ 1989Digital Equipment Corporation - 1989X Consortium - 1994X Consortium + X Version 11, Release &fullrelvers; Version 3.3 - X Consortium @@ -41,6 +37,10 @@ this document. This documentation is provided "as is" without express or implied warranty. This document is subject to change. + + + +Copyright © 1989, 1994 X Consortium Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ``Software''), to deal @@ -54,7 +54,7 @@ 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 +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 @@ -66,9 +66,7 @@ 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. - -X Window System is a trademark of X Consortium, Inc. - +X Window System is a trademark of The OpenGroup. -- cgit v1.2.3 From 77f8d11c0d2e521b1dfbd27acfde381a4dcfb135 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 10:35:58 -0400 Subject: security: fix X Consortium copyrigh legal text and minor markups Signed-off-by: Gaetan Nadon --- specs/security.xml | 43 ++++++++++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 11 deletions(-) (limited to 'specs') diff --git a/specs/security.xml b/specs/security.xml index a380987..228d350 100644 --- a/specs/security.xml +++ b/specs/security.xml @@ -13,26 +13,47 @@ xhtml,docbook,html,refcaption --> Security Extension Specification X Consortium Standard - X Version 11, Release &fullrelvers; - November 15, 1996 - DavidWiggins + DavidP.Wiggins + X Consortium - X Consortium Standard - 1996X Consortium + X Version 11, Release &fullrelvers; Version 7.1 - X Consortium + 1996X Consortium - -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. - + +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. + +X Window System is a trademark of The OpenGroup. +November 15, 1996 + -- cgit v1.2.3 From 7961ee6a9d2d398f0f05ca7058644c4894822910 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 15:24:12 -0400 Subject: shape spec: fix author affiliation and copyright text Signed-off-by: Gaetan Nadon --- specs/shape.xml | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) (limited to 'specs') diff --git a/specs/shape.xml b/specs/shape.xml index c24928e..659253c 100644 --- a/specs/shape.xml +++ b/specs/shape.xml @@ -12,24 +12,21 @@ X Nonrectangular Window Shape Extension Protocol X.Org Standard - X Version 11, Release &fullrelvers; - Version 1.1 KeithPackard -MIT X Consortium Intel Corporation + MIT X Consortium + Intel Corporation HidekiHiura SunSoft, Inc. - X Consortium Standard - 1989The Open Group - 2004The Open Group + X Version 11, Release &fullrelvers; + Version 1.1 + 19892004The Open Group 2006Keith Packard - X Consortium - @@ -45,7 +42,7 @@ 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 +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 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -- cgit v1.2.3 From daf6658219cac1fb1bde12f9e827a7832162536a Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 15:31:39 -0400 Subject: shm spec: fix author affiliation and copyright text Signed-off-by: Gaetan Nadon --- specs/shm.xml | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) (limited to 'specs') diff --git a/specs/shm.xml b/specs/shm.xml index 8a0fd56..027aa54 100644 --- a/specs/shm.xml +++ b/specs/shm.xml @@ -12,12 +12,13 @@ MIT-SHM(The MIT Shared Memory Extension) How the shared memory extension works - X Version 11, Release &fullrelvers; - Version 1.0 JonathanCorbet - Atmospheric Technology Division National Center for Atmospheric Research + + National Center for Atmospheric Research + Atmospheric Technology Division + corbet@ncar.ucar.edu @@ -25,20 +26,9 @@ MIT X Consortium - X Consortium Standard + X Version 11, Release &fullrelvers; + Version 1.0 1991X Consortium - X Consortium - - - -This document briefly describes how to use the MIT-SHM shared memory -extension. I have tried to make it accurate, but it would not surprise me -if some errors remained. If you find anything wrong, do let me know and I -will incorporate the corrections. Meanwhile, please take this document "as -is" (eman improvement over what was there before, but certainly not the -definitive word.) - - @@ -54,7 +44,7 @@ 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 +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 @@ -66,7 +56,20 @@ 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. +X Window System is a trademark of The OpenGroup. + + + +This document briefly describes how to use the MIT-SHM shared memory +extension. I have tried to make it accurate, but it would not surprise me +if some errors remained. If you find anything wrong, do let me know and I +will incorporate the corrections. Meanwhile, please take this document "as +is" (eman improvement over what was there before, but certainly not the +definitive word.) + + + -- cgit v1.2.3 From b72a529226cce698b3550a75ecedfea6585daccf Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 15:40:08 -0400 Subject: sync spec: fix copyright markup for multiple authors Signed-off-by: Gaetan Nadon --- specs/sync.xml | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) (limited to 'specs') diff --git a/specs/sync.xml b/specs/sync.xml index 16c48dd..895c7d4 100644 --- a/specs/sync.xml +++ b/specs/sync.xml @@ -14,7 +14,6 @@ by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,ref X Synchronization Extension Protocol X Consortium Standard - X Version 11, Release &fullrelvers; TimGlauert @@ -51,21 +50,15 @@ by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,ref NVIDIA Corporation - X Consortium Standard - - - 1991 - -Olivetti Research Limited, Cambridge England and -Digital Equipment Corporation, Maynard, Massachusetts - + X Version 11, Release &fullrelvers; + Version 3.1 + 1991 + Olivetti Research Limited, Cambridge England + Digital Equipment Corporation, Maynard, Massachusetts + X Consortium - 1991X Consortium 2010NVIDIA Corporation - Version 3.1 - X Consortium - Permission to use, copy, modify, and distribute this documentation for any -- cgit v1.2.3 From c43e9edc3bed977885ec69c8e3a7f106d778b931 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 15:42:18 -0400 Subject: top-cup spec: remove orphan corpname markup Signed-off-by: Gaetan Nadon --- specs/tog-cup.xml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'specs') diff --git a/specs/tog-cup.xml b/specs/tog-cup.xml index 12ba787..a06d7cc 100644 --- a/specs/tog-cup.xml +++ b/specs/tog-cup.xml @@ -21,9 +21,7 @@ The Open Group - X Consortium Standard 1986-1997The Open Group - X Consortium @@ -45,7 +43,7 @@ The above copyright notice and the following permission notice shall be included in all copies of the Software: -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +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 NON- INFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY -- cgit v1.2.3 From 7c7f6b9e21cea649e833afa4402fd4848c97e047 Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 15:44:59 -0400 Subject: xtest spec: fix copyright markup Signed-off-by: Gaetan Nadon --- specs/xtest.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'specs') diff --git a/specs/xtest.xml b/specs/xtest.xml index cb73f29..e20f06a 100644 --- a/specs/xtest.xml +++ b/specs/xtest.xml @@ -10,16 +10,16 @@ XTEST Extension Protocol X Consortium Standard - X Version 11, Release &fullrelvers; - Version 2.2 KieronDrake UniSoft Ltd. + X Version 11, Release &fullrelvers; + Version 2.2 1992UniSoft Group Ltd. - 1992,1994X Consortium + 19921994X Consortium @@ -46,7 +46,7 @@ all copies or substantial portions of the Software. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +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 -- cgit v1.2.3 From 8f35303d8d40a68deb8c4830e8946ea356b0577f Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 21 Sep 2011 19:35:12 -0400 Subject: geproto spec: add missing copyright with the author's permission http://cgit.freedesktop.org/xorg/proto/xextproto/commit/geproto.txt ?id=69356e4165f11f3ed4b377d29df038549191a91e Signed-off-by: Gaetan Nadon --- specs/geproto.xml | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) (limited to 'specs') diff --git a/specs/geproto.xml b/specs/geproto.xml index 7684ac8..4cca9ac 100644 --- a/specs/geproto.xml +++ b/specs/geproto.xml @@ -12,7 +12,37 @@ Hutterer peter.hutterer@who-t.net - X Version 11, Release &fullrelvers; + X Version 11, Release &fullrelvers; + Version 1.0 + 2007Peter Hutterer + + + + 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 (including the next + paragraph) 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 + AUTHORS OR COPYRIGHT HOLDERS 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. + + + -- cgit v1.2.3 From 618cea608d726c0aeb48960da7bedc2dd8b36bba Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Fri, 30 Sep 2011 22:28:10 -0600 Subject: #1 - fix the capitalization of the ID attriutes to match either the or <funcdef> string it goes with. #2 - fix any <linkend>'s that were affected by #1 #3 - any <function> in the docs that has an actual funcdef, will become an olink. Signed-off-by: Matt Dew <marcoz@osource.org> --- specs/appgrp.xml | 42 ++++++++++++++--------------- specs/dbe.xml | 40 ++++++++++++++-------------- specs/dpms.xml | 32 +++++++++++------------ specs/evi.xml | 6 ++--- specs/multibuf.xml | 38 +++++++++++++-------------- specs/security.xml | 77 +++++++++++++++++++++++++++--------------------------- specs/shm.xml | 14 +++++----- specs/sync.xml | 23 ++++++++-------- specs/tog-cup.xml | 8 +++--- specs/xtest.xml | 10 +++---- 10 files changed, 144 insertions(+), 146 deletions(-) (limited to 'specs') diff --git a/specs/appgrp.xml b/specs/appgrp.xml index dfeee9e..cf2c2d0 100644 --- a/specs/appgrp.xml +++ b/specs/appgrp.xml @@ -60,7 +60,7 @@ example, OpenDoc does, such as shared menu bars, etc. </abstract> </articleinfo> -<sect1 id='purpose_and_goals'> +<sect1 id='Purpose_and_Goals'> <title>Purpose and Goals @@ -83,7 +83,7 @@ Computer, Inc. WinCenter is a trademark of Network Computing Devices, Inc. - + Overview of the protocol. @@ -99,7 +99,7 @@ As a member of an Application Group, when an application creates and maps a wind - + Requests @@ -343,10 +343,10 @@ This request destroys the association created with AppGroupCreateAssociation. Th - + Changes to Existing Requests - + MapWindow @@ -354,7 +354,7 @@ If the override-redirect attribute of the window is False and if the window is a - + ConfigureWindow @@ -362,7 +362,7 @@ If the override-redirect attribute of the window is False and if the window is a - + CreateWindow @@ -375,7 +375,7 @@ When a program in an Application Group creates a window that is a child of a roo - + ChangeWindowAttributes @@ -386,7 +386,7 @@ When a program in an Application Group changes the attributes of a window that i - + Changes to Existing Events @@ -398,7 +398,7 @@ The Application Group Leader must not select SubstructuRedirect events on a root - + MapRequest @@ -406,7 +406,7 @@ When a MapWindow request is received for a window whose override-redirect attrib - + ConfigureRequest @@ -416,10 +416,10 @@ When a ConfigureWindow request is received for a window whose override-redirect - + Errors - + AppGroupQueryVersion @@ -428,7 +428,7 @@ There are no errors for AppGroupQueryVersion. - + AppGroupCreate @@ -453,7 +453,7 @@ A Match error is returned if root_visual does not exist for the screen of the de - + AppGroupDestroy @@ -466,7 +466,7 @@ An Access error is returned if an untrusted application attempts to destroy an A - + AppGroupGetAttr @@ -479,7 +479,7 @@ An Access error is returned if an untrusted application attempts to get the attr - + AppGroupQuery @@ -488,7 +488,7 @@ An Access error is returned if an untrusted application attempts to query the Ap - + AppGroupCreateAssociation @@ -505,7 +505,7 @@ A Window error may be returned for system-specific errors related to system_wind - + AppGroupDestroyAssociation @@ -515,7 +515,7 @@ A Window error is returned if window was not specified in a previous AppGroupCre - + Encoding @@ -643,7 +643,7 @@ VALUEs - + Library API diff --git a/specs/dbe.xml b/specs/dbe.xml index 8c87548..d0319d3 100644 --- a/specs/dbe.xml +++ b/specs/dbe.xml @@ -48,7 +48,7 @@ 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 @@ -64,7 +64,7 @@ The result is a flicker-free animation. - + Goals This extension should enable clients to: @@ -125,7 +125,7 @@ access (DGHA) architectures. - + Concepts @@ -281,7 +281,7 @@ frame rate) should investigate the Synchronization Extension, an X Consortium standard. - + Window Management Operations @@ -333,7 +333,7 @@ It is tiled with the window background in both buffers, and - + Complex Swap Actions DBE has no explicit knowledge of ancillary buffers (for example, depth @@ -435,11 +435,11 @@ ensure best possible performance across a wide variety of implementations. - + Requests The DBE defines the following requests. - + DBEGetVersion This request returns the major and minor version numbers of this extension. @@ -498,7 +498,7 @@ otherwise, the client will get undefined behavior (DBE may or may not work). - + DBEGetVisualInfo This request returns information about which visuals support double buffering. @@ -577,7 +577,7 @@ returned, starting with screen zero. - + DBEAllocateBackBufferName @@ -645,7 +645,7 @@ back-buffer-name is freed. - + DBEDeallocateBackBufferName This request frees a drawable ID that was obtained by @@ -683,7 +683,7 @@ a Buffer error results). - + DBESwapBuffers This request swaps the buffers for all windows listed, applying the @@ -782,7 +782,7 @@ type of idiom, it must immediately follow the - + DBEBeginIdiom This request informs the server that a complex swap will immediately follow @@ -800,7 +800,7 @@ free to implement this request as a no-op. - + DBEEndIdiom @@ -818,7 +818,7 @@ request as a no-op. - + DBEGetBackBufferAttributes This request returns information about a back buffer. @@ -860,7 +860,7 @@ the window field of the attributes in the reply will be None. - + Encoding Please refer to the X11 Protocol Encoding document as this section uses @@ -869,7 +869,7 @@ syntactic conventions and data types established there. The name of this extension is "DOUBLE-BUFFER". - + Type The following new types are used by the extension. @@ -906,7 +906,7 @@ BUFFER_ATTRIBUTES - + Error Buffer @@ -920,7 +920,7 @@ BUFFER_ATTRIBUTES - + Request @@ -1018,7 +1018,7 @@ DBEGetVersion - + Acknowledgements We wish to thank the following individuals who have contributed their time @@ -1042,7 +1042,7 @@ draft of the specification. David served as architect. - + References Jeffrey Friedberg, Larry Seiler, and Jeff Vroom, "Multi-buffering Extension diff --git a/specs/dpms.xml b/specs/dpms.xml index fe97da9..617744c 100644 --- a/specs/dpms.xml +++ b/specs/dpms.xml @@ -123,7 +123,7 @@ it may be decided to make DPMS less aggressive, or disable it completely. Requests -DPMSGetVersion +DPMSGetVersion @@ -178,7 +178,7 @@ of one (1). -DPMSCapable +DPMSCapable @@ -206,7 +206,7 @@ case of heterogeneous multi-head servers is implementation defined. -DPMSGetTimeouts +DPMSGetTimeouts @@ -275,7 +275,7 @@ value of zero indicates that this mode is disabled. -DPMSSetTimeouts +DPMSSetTimeouts @@ -339,7 +339,7 @@ to the value of the previous (non-zero) level. A BadValue error is generated if an illegal combination is detected. -DPMSEnable +DPMSEnable => @@ -352,7 +352,7 @@ effected. -DPMSDisable +DPMSDisable => @@ -366,7 +366,7 @@ may be disabled without damaging the server's stored timeout values. -DPMSForceLevel +DPMSForceLevel @@ -395,7 +395,7 @@ DPMSModeSuspend or DPMSModeOff. -DPMSInfo +DPMSInfo @@ -450,7 +450,7 @@ The name of this extension is "DPMS". -DPMSGetVersion +DPMSGetVersion 1 CARD8 opcode 1 0 DPMS opcode 2 2 request length @@ -467,7 +467,7 @@ The name of this extension is "DPMS". -DPMSCapable +DPMSCapable 1 CARD8 opcode 1 1 DPMS opcode 2 1 request length @@ -481,7 +481,7 @@ The name of this extension is "DPMS". -DPMSGetTimeouts +DPMSGetTimeouts 1 CARD8 opcode 1 2 DPMS opcode 2 1 request length @@ -497,7 +497,7 @@ The name of this extension is "DPMS". -DPMSSetTimeouts +DPMSSetTimeouts 1 CARD8 opcode 1 3 DPMS opcode 2 3 request length @@ -509,7 +509,7 @@ The name of this extension is "DPMS". -DPMSEnable +DPMSEnable 1 CARD8 opcode 1 4 DPMS opcode 2 1 request length @@ -517,7 +517,7 @@ The name of this extension is "DPMS". -DPMSDisable +DPMSDisable 1 CARD8 opcode 1 5 DPMS opcode 2 1 request length @@ -525,7 +525,7 @@ The name of this extension is "DPMS". -DPMSForceLevel +DPMSForceLevel 1 CARD8 opcode 1 6 DPMS opcode 2 2 request length @@ -539,7 +539,7 @@ The name of this extension is "DPMS". -DPMSInfo +DPMSInfo 1 CARD8 opcode 1 7 DPMS opcode 2 1 request length diff --git a/specs/evi.xml b/specs/evi.xml index 8489b37..e5cfac4 100644 --- a/specs/evi.xml +++ b/specs/evi.xml @@ -292,7 +292,7 @@ No new events or errors are defined by this extension. - + Changes to existing protocol. None. @@ -375,7 +375,7 @@ The include file for this extension is: < X11/extensions/XEVI.h>. - + Bool XeviQueryVersion Display *display @@ -434,7 +434,7 @@ To get the extended information for any subset of visuals use XeviGetVisualInfo. - + int XeviGetVisualInfo Display *display diff --git a/specs/multibuf.xml b/specs/multibuf.xml index 39a5dbf..9e2b065 100644 --- a/specs/multibuf.xml +++ b/specs/multibuf.xml @@ -80,7 +80,7 @@ Extension (DBE). DBE is an X Consortium Standard as of Release 6.1. - + Introduction @@ -123,7 +123,7 @@ multi-buffering, and stereo in a way that is acceptable to all concerned. - + Goals @@ -179,7 +179,7 @@ existing hardware features. - + Image Buffers @@ -319,7 +319,7 @@ maintained for an image buffer, then no exposure events are generated. - + New Requests @@ -674,7 +674,7 @@ the request is ignored. - + Attributes @@ -863,7 +863,7 @@ major version will be 1, and the minor version will be 1. - + Events @@ -961,7 +961,7 @@ request), an UpdateNotify event is generated. - + Errors @@ -969,14 +969,14 @@ The following error type has been added to support this extension: - + Buffer A value for a BUFFER argument does not name a defined BUFFER. - + Double-Buffering Normal Windows @@ -1026,7 +1026,7 @@ DestroyImageBuffers( W ) - + Multi-Buffering Normal Windows @@ -1073,7 +1073,7 @@ while animating - + Stereo Windows How stereo windows are supported on a server @@ -1178,7 +1178,7 @@ right eyes for normal windows should be the same - + Single-Buffered Stereo Windows @@ -1198,7 +1198,7 @@ MapWindow( W ) - + Double-Buffering Stereo Windows @@ -1270,7 +1270,7 @@ while animating - + Multi-Buffering Stereo Windows @@ -1313,7 +1313,7 @@ while animating - + Protocol Encoding @@ -1360,7 +1360,7 @@ encoding for this extension. - + TYPES @@ -1382,7 +1382,7 @@ SETofBUFFER_EVENT - + EVENTS @@ -1408,7 +1408,7 @@ SETofBUFFER_EVENT - + ERRORS @@ -1424,7 +1424,7 @@ SETofBUFFER_EVENT - + REQUESTS diff --git a/specs/security.xml b/specs/security.xml index 228d350..b920618 100644 --- a/specs/security.xml +++ b/specs/security.xml @@ -56,7 +56,7 @@ in this Software without prior written authorization from the X Consortium. - + Introduction @@ -67,10 +67,10 @@ clients (defined below). - + Requests - + SecurityQueryVersion This request returns the major and minor version numbers of this extension. @@ -150,7 +150,7 @@ protocol version; otherwise, the client will get undefined behavior - + SecurityGenerateAuthorization @@ -460,7 +460,7 @@ authorization-data-return this way. - + SecurityRevokeAuthorization @@ -506,14 +506,14 @@ with this authorization will fail. - + Changes to Core Requests A server supporting this extension modifies the handling of some core requests in the following ways. - + Resource ID Usage @@ -603,7 +603,7 @@ ISSUE: are root window exceptions needed for these? WarpPointer, ReparentWindow - + Extension Security @@ -638,7 +638,7 @@ opcode will fail with a Request error. - + Keyboard Security @@ -705,7 +705,7 @@ expected. This is in line with the root window exceptions above. - + Image Security @@ -745,8 +745,7 @@ to be an unusual configuration. - - + Property Security @@ -840,7 +839,7 @@ field in the reply is zero). - + Miscellaneous Security @@ -859,7 +858,7 @@ a SelectionNotify event to the requestor with property None. - + New Authorization Method @@ -998,7 +997,7 @@ policy-type Permit. - + Encoding @@ -1010,14 +1009,14 @@ uses syntactic conventions and data types established there. The name of this extension is "SECURITY". - + Types AUTHID: CARD32 - + Request Encoding @@ -1097,7 +1096,7 @@ r unused, r=pad(q) - + Event Encoding SecurityAuthorizationRevoked @@ -1113,7 +1112,7 @@ r unused, r=pad(q) - + Authorization Method Encoding @@ -1151,7 +1150,7 @@ termination between STRs. - + C Language Binding @@ -1164,7 +1163,7 @@ All functions that have return type Status will return nonzero for success and zero for failure. - + Status XSecurityQueryExtension Display *dpy @@ -1174,7 +1173,7 @@ success and zero for failure. -XSecurityQueryExtension sets major_version_return and + sets major_version_return and minor_version_return to the major and minor Security protocol version supported by the server. If the Security library is compatible with the version returned by the server, it returns nonzero. If dpy does not support @@ -1185,7 +1184,7 @@ function. If a client violates this rule, the effects of all subsequent XSecurity calls that it makes are undefined. - + Xauth *XSecurityAllocXauth void @@ -1198,9 +1197,9 @@ allocate and deallocate them. -XSecurityAllocXauth must be used to allocate the + must be used to allocate the Xauth structure that is passed to -XSecurityGenerateAuthorization. +. @@ -1289,7 +1288,7 @@ The Xauth structure returned by this function is initialized as follows: name_length and data_length are zero, and name and data are NULL. - + void XSecurityFreeXauth Xauth *auth @@ -1297,20 +1296,20 @@ name_length and data_length are zero, and name and data are NULL. -XSecurityFreeXauth must be used to free Xauth + must be used to free Xauth structures allocated by -XSecurityAllocXauth or returned by -XSecurityGenerateAuthorization. It is the + or returned by +. It is the caller's responsibility to fill in the name and data fields of Xauth structures -allocated with XSecurityAllocXauth, so this function +allocated with , so this function will not attempt to free them. In contrast, all storage associated with Xauth structures returned from -XSecurityGenerateAuthorization will be freed by this + will be freed by this function, including the name and data fields. - + Bool XSecurityRevokeAuthorization Display *dpy @@ -1319,15 +1318,15 @@ function, including the name and data fields. -XSecurityRevokeAuthorization deletes the authorization + deletes the authorization specified by auth_id, which must be a value returned in the auth_id_return -parameter of XSecurityGenerateAuthorization. All +parameter of . All clients that connected with that authorization are be killed. Subsequently, clients that attempt to connect using that authorization will be refused. - + Xauth *XSecurityGenerateAuthorization Display *dpy @@ -1339,16 +1338,16 @@ clients that attempt to connect using that authorization will be refused. -XSecurityGenerateAuthorization creates a new + creates a new authorization with the specified attributes. The auth_in argument must be -allocated by XSecurityAllocXauth. The +allocated by . The name and name_length fields of auth_in should be initialized to the authorization protocol name and its length in characters respectively. If there is authorization data, the data and data_length fields of auth_in should be initialized to the data and its length in characters respectivley. The library does not assume that name and data are null-terminated strings. The auth_in argument must be freed with -XSecurityFreeXauth. +. @@ -1453,7 +1452,7 @@ the authorization data returned by the server. The caller should not assume that name and data are null-terminated strings. If no authorization data was returned by the server, the data and data_length fields will be set to NULL and zero repectively. The returned Xauth structure must be freed with -XSecurityFreeXauth; the caller should not use any other +; the caller should not use any other means free the structure or any of its components. The auth_id_return argument will be filled in with the non-zero authorization id of the created authorization. diff --git a/specs/shm.xml b/specs/shm.xml index 027aa54..f6ad347 100644 --- a/specs/shm.xml +++ b/specs/shm.xml @@ -138,7 +138,7 @@ the net, or in some other environment where the extension will not work. To perform this check, call either - + Status XShmQueryExtension Display *display @@ -149,7 +149,7 @@ To perform this check, call either or - + Status XShmQueryVersion Display *display @@ -203,7 +203,7 @@ Use the shared memory XImage, much like a normal one. To create a shared memory XImage, use: - + XImage *XShmCreateImage Display *display @@ -318,7 +318,7 @@ ready for use. To write a shared memory XImage into an X drawable, use XShmPutImage: - + Status XShmPutImage Display *display @@ -381,7 +381,7 @@ completion event, the results you see on the screen may be inconsistent. To read image data into a shared memory XImage, use the following: - + Status XShmGetImage Display *display @@ -424,7 +424,7 @@ format is) and independent of the screen. Use XShmPixmapFormat to get the format for the server: - + int XShmPixmapFormat Display *display @@ -444,7 +444,7 @@ bytes_per_line value to use. Once you have your shminfo structure filled in, simply call: - + Pixmap XShmCreatePixmap Display *display diff --git a/specs/sync.xml b/specs/sync.xml index 895c7d4..6df45a6 100644 --- a/specs/sync.xml +++ b/specs/sync.xml @@ -98,7 +98,7 @@ Consortium. - + Synchronization Protocol The core X protocol makes no guarantees about the relative order of execution @@ -131,7 +131,7 @@ 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 @@ -200,7 +200,7 @@ merely establishes an upper bound for the scope of fence operations. - + Types Please refer to the X11 Protocol specification as this document uses @@ -325,7 +325,7 @@ state. Otherwise, the fence is in the not triggered state. - + Errors @@ -359,8 +359,7 @@ does not name a defined FENCE. - - + Requests @@ -904,7 +903,7 @@ is generated if any member of fence-list does not name a valid fence. - + Events @@ -962,7 +961,7 @@ is destroyed, or the counter for the alarm is destroyed. - + Encoding Please refer to the X11 Protocol Encoding document as this section uses @@ -970,7 +969,7 @@ syntactic conventions established there and references types defined there. The name of this extension is "SYNC". - + Encoding New Types The following new types are used by the extension. @@ -1015,7 +1014,7 @@ groups, the byte ordering determined during connection setup is used. - + Encoding Errors Counter @@ -1046,7 +1045,7 @@ groups, the byte ordering determined during connection setup is used. - + Encoding Requests @@ -1246,7 +1245,7 @@ AwaitFence - + Encoding Events diff --git a/specs/tog-cup.xml b/specs/tog-cup.xml index a06d7cc..c8597a6 100644 --- a/specs/tog-cup.xml +++ b/specs/tog-cup.xml @@ -254,7 +254,7 @@ No new events or errors are defined by this extension. - + Changes to existing protocol. None. @@ -355,7 +355,7 @@ The include file for this extension is <X11/extensions/Xcup.h>. - + Status XCupQueryVersion Display* display @@ -415,7 +415,7 @@ To get the list of reserved colormap entries, use XCupGetReservedColormapEntries. - + Status XCupGetReservedColormapEntries Display* display @@ -469,7 +469,7 @@ To allocate one or more read-only color cells with RGB values, use XCupStoreColors. - + Status XCupStoreColors Display* display diff --git a/specs/xtest.xml b/specs/xtest.xml index e20f06a..121a8d5 100644 --- a/specs/xtest.xml +++ b/specs/xtest.xml @@ -241,7 +241,7 @@ not required, respectively. -XTestSetGContextOfGC +XTestSetGContextOfGC @@ -268,7 +268,7 @@ the value specified by gid. -XTestSetVisualIDOfVisual +XTestSetVisualIDOfVisual @@ -295,7 +295,7 @@ the value specified by visualid. -XTestDiscard +XTestDiscard @@ -581,7 +581,7 @@ error occurs. -XTestGrabControl +XTestGrabControl @@ -694,7 +694,7 @@ the corresponding core protocol event types. -XTestGrabControl +XTestGrabControl 1 CARD8 opcode 1 3 xtest opcode 2 2 request length -- cgit v1.2.3 From 38c6d386637eecc105f6e6b03ff10e6299bd0002 Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Mon, 16 Jan 2012 13:18:50 -0700 Subject: informaltable cleanup On certain tables, add top and bottom borders to table header and a bottom border to the table. This matches what those tables in the old pdfs looked like. the prevents tables from splitting across pages. Useful for tiny tables. Converting the colwidth to a floating point, IE, 1* -> 1.0* cleans up these build errors: WARNING: table-layout="fixed" and column-width unspecified => falling back to proportional-column-width(1) Signed-off-by: Matt Dew --- specs/appgrp.xml | 159 ++++---- specs/dbe.xml | 162 ++++---- specs/dpms.xml | 70 ++-- specs/evi.xml | 51 +-- specs/lbx.xml | 1038 +++++++++++++++++++++++++++------------------------- specs/security.xml | 435 +++++++++------------- specs/shape.xml | 148 ++++---- specs/sync.xml | 75 ++-- specs/tog-cup.xml | 39 +- specs/xtest.xml | 88 ++--- 10 files changed, 1139 insertions(+), 1126 deletions(-) (limited to 'specs') diff --git a/specs/appgrp.xml b/specs/appgrp.xml index cf2c2d0..0f91e16 100644 --- a/specs/appgrp.xml +++ b/specs/appgrp.xml @@ -105,9 +105,10 @@ As a member of an Application Group, when an application creates and maps a wind AppGroupQueryVersion - - - + + + + client_major_version: CARD16 @@ -135,9 +136,10 @@ If supplied, the client_major_version and client_minor_version indicate what ver AppGroupCreate - - - + + + + app_group: APPGROUP @@ -166,13 +168,14 @@ This request creates an Application Group using app_group as the Application Gro The value_mask and value_list specify attributes of the Application Group that are to be explicitly initialized. The attributes, their types, and the default values are: - - - - - + + + + + + - + Attribute Type Default @@ -257,9 +260,10 @@ If the application that created a non-embedded Application Group exits, and ther AppGroupGetAttr - - - + + + + >app_group: APPGROUP @@ -280,9 +284,10 @@ This request returns the application group attributes for app_group. AppGroupQuery - - - + + + + resource: XID @@ -303,9 +308,10 @@ This request returns the Application Group ID of the application that created re AppGroupCreateAssociation - - - + + + + window: WINDOW @@ -326,9 +332,10 @@ This request associates window with system_window. The window_type indicates the AppGroupDestroyAssociation - - - + + + + window: WINDOW @@ -647,25 +654,26 @@ VALUEs Library API - - + + + - + Status XagQueryVersion ( xkb, keycode) /* macro */ - + Display dpy; - + int * major_version_return; - + int * minor_version_return; @@ -688,40 +696,41 @@ An embedding manager such as a web browser that intends to embed programs in an - - + + + - + Status XagCreateEmbeddedApplicationGroup( - + Display* dpy, - + VisualID root_visual, - + Colormap default_colormap, - + unsigned long black_pixel, - + unsigned long white_pixel, - + XAppGroup* app_group_return); @@ -744,20 +753,21 @@ A special font-path can be created by creating an Application Group, getting an - - + + + - + Status XagCreateNonembeddedApplicationGroup( - + Display* dpy, - + XAppGroup* app_group_return); @@ -775,20 +785,21 @@ To destroy an Application Group use XagDestroyApplicationGroup. - - + + + - + Status XagDestroyApplicationGroup( - + Display* dpy, - + XAppGroup app_group); @@ -808,25 +819,26 @@ To retrieve the attributes of an Application Group use XagGetApplicationGroupAtt - - + + + - + Status XagGetApplicationGroupAttributes( - + Display* dpy, - + XAppGroup app_group, - + ...); @@ -886,25 +898,26 @@ To determine which Application Group a resource (such as a window) belongs to, u - - + + + - + Status XagQueryApplicationGroup( - + Display* dpy, - + XID resource, - + XAppGroup* app_group_return); @@ -923,25 +936,26 @@ To associate an X Window ID with a system-specific window ID, such as a HWND or - - + + + - + Status XagCreateAssociation( - + Display* dpy, - + Window* window_return, - + void* system_window); @@ -991,20 +1005,21 @@ To destroy the association created with XagCreateAssociation use XagDestroyAssoc - - + + + - + Status XagDestroyAssociation( - + Display* dpy, - + Window window); diff --git a/specs/dbe.xml b/specs/dbe.xml index d0319d3..5af90a6 100644 --- a/specs/dbe.xml +++ b/specs/dbe.xml @@ -446,30 +446,31 @@ This request returns the major and minor version numbers of this extension. DBEGetVersion - - - - + + + + + - client-major-version - CARD8 + client-major-version + CARD8 - client-minor-version - CARD8 + client-minor-version + CARD8 - => - + => + - server-major-version - CARD8 + server-major-version + CARD8 - server-minor-version - CARD8 + server-minor-version + CARD8 @@ -506,48 +507,50 @@ This request returns information about which visuals support double buffering. DBEGetVisualInfo - - - - + + + + + - screen-specifiers - LISTofDRAWABLE + screen-specifiers + LISTofDRAWABLE - => - + => + - visinfo - LISTofSCREENVISINFO + visinfo + LISTofSCREENVISINFO where: - - - - + + + + + - SCREENVISINFO - LISTofVISINFO + SCREENVISINFO + LISTofVISINFO - VISINFO - [ visual: VISUALID + VISINFO + [ visual: VISUALID - - depth: CARD8 + + depth: CARD8 - - perflevel: CARD8 ] + + perflevel: CARD8 ] @@ -587,22 +590,23 @@ window. DBEAllocateBackBufferName - - - - + + + + + - window - WINDOW + window + WINDOW - back-buffer-name - BACKBUFFER + back-buffer-name + BACKBUFFER - swap-action-hint - SWAPACTION + swap-action-hint + SWAPACTION @@ -654,14 +658,15 @@ This request frees a drawable ID that was obtained by DBEDeallocateBackBufferName - - - - + + + + + - back-buffer-name - BACKBUFFER + back-buffer-name + BACKBUFFER @@ -692,33 +697,37 @@ appropriate swap action for each window. DBESwapBuffers - - - + + + + + - windows - LISTofSWAPINFO + windows + LISTofSWAPINFO where: - - - + + + + + - SWAPINFO - [ window: WINDOW + SWAPINFO + [ window: WINDOW - - swap-action: SWAPACTION ] + + swap-action: SWAPACTION ] - SWAPACTION - { Undefined, Background, Untouched, Copied } + SWAPACTION + { Undefined, Background, Untouched, Copied } @@ -825,22 +834,23 @@ request as a no-op. DBEGetBackBufferAttributes - - - - + + + + + - back-buffer-name - BACKBUFFER + back-buffer-name + BACKBUFFER - => - + => + - attributes - BUFFER_ATTRIBUTES + attributes + BUFFER_ATTRIBUTES diff --git a/specs/dpms.xml b/specs/dpms.xml index 617744c..f504ab7 100644 --- a/specs/dpms.xml +++ b/specs/dpms.xml @@ -127,28 +127,29 @@ it may be decided to make DPMS less aggressive, or disable it completely. - - + + + - + client_major_version: CARD16 - + client_minor_version: CARD16 - + => - + server_major_version: CARD16 - + server_minor_version: CARD16 @@ -182,13 +183,14 @@ of one (1). - - + + + - + => - + capable: BOOL @@ -210,23 +212,24 @@ case of heterogeneous multi-head servers is implementation defined. - - + + + - + => - + standby_timeout: CARD16 - + suspend_timeout: CARD16 - + off_timeout: CARD16 @@ -279,25 +282,26 @@ value of zero indicates that this mode is disabled. - - + + + - + standby_timeout: CARD16 - + suspend_timeout: CARD16 - + off_timeout: CARD16 - + => @@ -370,15 +374,16 @@ may be disabled without damaging the server's stored timeout values. - - + + + - + power_level: CARD16 - + => @@ -399,18 +404,19 @@ DPMSModeSuspend or DPMSModeOff. - - + + + - + => - + power_level: CARD16 - + state: BOOL diff --git a/specs/evi.xml b/specs/evi.xml index e5cfac4..7b661f6 100644 --- a/specs/evi.xml +++ b/specs/evi.xml @@ -98,30 +98,31 @@ visuals support double-buffering. - - + + + - + client_major_version: CARD8 - + client_minor_version: CARD8 - + => - + server_major_version: CARD8 - + server_minor_version: CARD8 @@ -152,20 +153,21 @@ server_minor_version of zero (0). - - + + + - + visual_list: LISTofVISUALID - + => - + per_visual_info: LISTofVISUALINFO @@ -179,55 +181,56 @@ where: - - + + + - + VISUALINFO: [core_visual_id: VISUALID - + screen: CARD8 - + level: INT8 - + transparency_type: CARD8 - + unused: CARD8 - + transparency_value: CARD32 - + min_hw_colormaps: CARD8 - + max_hw_colormaps: CARD8 - + num_colormap_conflicts: CARD16 - + colormap_conflicts: LISTofVISUALID] diff --git a/specs/lbx.xml b/specs/lbx.xml index a06569d..87060b7 100644 --- a/specs/lbx.xml +++ b/specs/lbx.xml @@ -969,21 +969,22 @@ by reception of an X request from the client. They replace the X request. Requests Initiated by the Proxy or by the Client - - + + + - + LbxQueryVersion - + =>; - + majorVersion: CARD16 - + minorVersion: CARD16 @@ -1007,49 +1008,50 @@ LbxQueryVersion. Requests Initiated or Substituted by the Proxy - - + + + - + LbxQueryExtension - + nbytes : CARD32 - + name : STRING8 - + => - + num-requests: CARD8 - + present: BOOL - + major-opcode: CARD8 - + first-event: CARD8 - + first-error: CARD8 - + reply-mask: LISTofMASK /* optional */ - + event-mask:LISTofMASK /* optional */ - + Errors: Alloc @@ -1112,52 +1114,53 @@ LbxQueryExtension. Control Requests Initiated by the Proxy - - + + + - + LbxStartProxy - + options : LISTofOPTION - + => - + choices: LISTofCHOICE - + Errors: LbxClient , Alloc - + where: - + OPTION [optcode: CARD8, - + len: OPTLEN, - + option: (See See StartProxy Options) ] - + CHOICE [optcode: CARD8, - + len: OPTLEN, - + choice: (See See StartProxy Options) ] @@ -1165,19 +1168,20 @@ url="lbx.htm#35444">See StartProxy Options) ] - +
StartProxy Options - - - - - + + + + + + - + optcode option choice @@ -1185,55 +1189,55 @@ url="lbx.htm#35444">See StartProxy Options) ] - + delta-proxy DELTAOPT DELTACHOICE entries=16, maxlen=64 - + delta-server DELTAOPT DELTACHOICE entries=16, maxlen=64 - + stream-comp LISTofNAMEDOPT INDEXEDCHOICE No Compression - + bitmap-comp LISTofSTRING8 LISTofINDEXEDOPT No Compression - + pixmap-comp LISTofPIXMAPMETHOD LISTofPIXMAPCHOICE No Compression - + use-squish BOOL BOOL True - + use-tags BOOL BOOL True - + colormap LISTofSTRING8 INDEXEDCHOICE No Colormap Grabbing - + extension NAMEDOPT INDEXEDCHOICE @@ -1246,71 +1250,72 @@ url="lbx.htm#35444">See StartProxy Options) ] --> - - + + + - +   - + DELTAOPT [minN, maxN, prefN: CARD8 - + minMaxMsgLen, maxMaxMsgLen, prefMaxMsgLen: CARD8] - + DELTACHOICE [entries, maxlen: CARD8] - + INDEXEDCHOICE [index: CARD8, - + data: LISTofBYTE] - + INDEXEDOPT [index, opcode: CARD8] - + NAMEDOPT [name: STRING8, - + detail: LISTofBYTE] - + OPTLEN 1 or 3 CARD8 - + where: - + (0 < in <= 0xFF): out = in - + (0 <= in<= 0xFFFF): out[0] = 0; out[1] = in >> 8; out[2] = in& 0xFF; - + PIXMAPMETHOD [name: STRING8, - + format-mask: BITMASK, - + depths: LISTofCARD8] - + PIXMAPCHOICE [index, opcode: CARD8, - + format-mask: BITMASK, - + depths: LISTofCARD8] - + @@ -1469,15 +1474,16 @@ LbxStartProxy. - - + + + - + LbxStopProxy - + Errors: LbxClient @@ -1506,115 +1512,116 @@ LbxClient - - + + + - + LbxNewClient - + byte-order : CARD8 - + client-id : CARD32 - + protocol-major-version : CARD16 - + protocol-minor-version: CARD16 - + authorization-protocol-name : STRING8 - + authorization-protocol-data : STRING8 - + => - + Core X reply (if connection is rejected) - +   - + OR - +   - + success: BOOL - + change-type: {NoDeltas, NormalClientDeltas, AppGroupDeltas} - + protocol-major-version: CARD16 - + protocol-minor-version: CARD16 - + tag-id: CARD32 - + length: CARD16 - + connection-data: CONINFO or CONDIF or CONDIFROOT - +   - + where: - + CONINFO: (the "additional data" portion of the core connection reply for successes) - + CONDIF: [resource-id-base: CARD32, - + root-input-masks: LISTofSETofEVENT] - + CONDIFROOT: [resource-id-base: CARD32, - + root: WINDOW - + root-visual: VISUALID - + default-colormap: COLORMAP - + white-pixel, black-pixel: CARD32 - + root-input-masks: LISTofSETofEVENT] @@ -1774,21 +1781,22 @@ description of this request is on page 13.. - - + + + - + LbxCloseClient - + client : CARD32 - + Errors: LbxClient @@ -1815,21 +1823,22 @@ description of this request is on page 12.. - - + + + - + LbxSwitch - + client : CARD32 - + Errors: LbxClient @@ -1861,15 +1870,16 @@ LbxSwitch. - - + + + - + LbxSync - + => @@ -1889,21 +1899,22 @@ LbxSync. - - + + + - + LbxModifySequence - + adjust : CARD32 - + Errors: None @@ -1926,21 +1937,22 @@ description of this request is on page 13.. - - + + + - + LbxAllowMotion - + num : CARD32 - + Errors: None @@ -1961,15 +1973,16 @@ description of this request is on page 14.. - - + + + - + LbxInvalidateTag - + tag : CARD32 @@ -1992,25 +2005,26 @@ LbxInvalidateTag. - - + + + - + LbxTagData - + tag : CARD32 - + real-length : CARD32 - + data : LISTofBYTE @@ -2037,103 +2051,104 @@ LbxTagData. - - + + + - + LbxGrabCmap - + cmap : Colormap - + => - + smart-grab : BOOL - + large-pixel: BOOL /* optional */ - + auto-release: BOOL /* optional */ - + three-channels : BOOL /* optional */ - + bits-per-rgb: CARD4 /* optional */ - + cells : LISTofCHAN /* optional */ - +   - + where: - + CHAN: LISTofLBXPIXEL - + LBXPIXEL: PIXELPRIVATE or PIXELPRIVATERANGE or - + PIXELALLOC or PIXELALLOCRANGE - + PIXEL: CARD8 or CARD16 - + PIXELPRIVATE: [ pixel: PIXEL ] - + PIXELPRIVATERANGE: [ first-pixel, last-pixel: PIXEL] - + PIXELALLOC: [ pixel: PIXEL, - + color: COLORSINGLE or COLORTRIPLE] - + PIXELALLOCRANGE: [ first-pixel, last-pixel: PIXEL, - + colors: LISTofCOLORSINGLE or LISTofCOLORTRIPLE] - + COLORSINGLE: [ value: CARD8 or CARD16 ] - + COLORTRIPLE: [ r, g, b: COLORSINGLE] - + Errors: Colormap @@ -2349,15 +2364,16 @@ LbxGrabCmap. - - + + + - + LbxReleaseCmap - + cmap : Colormap @@ -2392,35 +2408,36 @@ LbxReleaseCmap. - - + + + - + LbxInternAtoms - + count : CARD16 - + names: LISTofSTRING8 - + => - + atoms : LISTofATOM - + Errors: Alloc @@ -2447,25 +2464,26 @@ LbxInternAtoms. Substitution Requests - - + + + - + LbxAllocColor - + cmap : Colormap - + pixel : CARD32 - + red , @@ -2538,26 +2556,27 @@ LbxAllocColor. - - + + + - + LbxIncrementPixel - + cmap : COLORMAP - + pixel : CARD32 - + Errors: None @@ -2581,25 +2600,26 @@ description of this request is on page 14.. - - + + + - + LbxDelta - + count : CARD8 - + cache-index : CARD8 - + diffs : LISTofDIFFITEM @@ -2623,29 +2643,30 @@ description of this request is on page 18.. - - + + + - + LbxGetModifierMapping - + => - + keyspermod : CARD8 - + tag : CARD32 - + keycodes : LISTofKEYCODE /* optional */ @@ -2672,45 +2693,46 @@ LbxGetModifierMapping. - - + + + - + LbxGetKeyboardMapping - + firstKeyCode : KEYCODE - + count : CARD8 - + => - + keysperkeycode : CARD8 - + tag : CARD32 - + keysyms : LISTofKEYSYM /* optional */ - + Errors: Value @@ -2738,82 +2760,83 @@ LbxGetKeyboardMapping. - - + + + - + LbxGetWinAttrAndGeom - + window : WINDOW - + => - + visual: VISUALID - + class: {InputOutput, InputOnly} - + bit-gravity: BITGRAVITY - + win-gravity: WINGRAVITY - + backing-store: {NotUseful, WhenMapped, Always} - + backing-planes: CARD32 - + backing-pixel: CARD32 - + save-under: BOOL - + colormap: COLORMAP or None - + map-is-installed: BOOL - + map-state: {Unmapped, Unviewable, Viewable} - + all-event-masks, your-event-mask: SETofEVENT - + do-not-propagate-mask: SETofDEVICEEVENT - + override-redirect: BOOL - + root: WINDOW - + depth: CARD8 - + x, y: INT16 - + width, height, border-width: CARD16 - + Errors: Window @@ -2841,57 +2864,58 @@ LbxGetWinAttrAndGeom. - - + + + - + LbxQueryFont - + font : FONTABLE - + => - + compression: BOOL - + tag: CARD32 - + font-info: FONTINFO /* optional */ - + char-infos: LISTofCHARINFO or LISTofLBXCHARINFO /* optional */ - + where: - + LBXCHARINFO: [left-side-bearing: INT6 - + right-side-bearing: INT7 - + character-width: INT6 - + ascent: INT6 - + descent: INT7] - + Errors: Font,Alloc @@ -2943,48 +2967,49 @@ LbxQueryFont. - - + + + - + LbxChangeProperty - + window : WINDOW - + property : ATOM - + type : ATOM - + format : {0,8,16,32} - + mode : {Replace, Prepend, Append} - + nUnits : CARD32 - + => - + tag: CARD32 @@ -3033,64 +3058,65 @@ LbxChangeProperty. - - + + + - + LbxGetProperty - + window : WINDOW - + property : ATOM - + type : ATOM or AnyPropertyType - + long-offset : CARD32 - + long-length : CARD32 - + delete : CARD8 - + => - + type: ATOM or None - + format: {0, 8, 16, 32} - + bytes-after: CARD32 - + nItems: CARD32 - + tag: CARD32 - + value: LISTofINT8 or LISTofINT16 or LISTofINT32 @@ -3171,26 +3197,27 @@ LbxGetProperty. - - + + + - + LbxPolyPoint - + gc-and-drawable: LBXGCANDDRAWABLE - + points : LISTofLBXPOINT - + Errors: Alloc and those given for the corresponding X request. @@ -3223,26 +3250,27 @@ LbxPolyPoint. - - + + + - + LbxPolyLine - + gc-and-drawable: LBXGCANDDRAWABLE - + points : LISTofLBXPOINT - + Errors: Alloc and those given for the corresponding X request. @@ -3275,35 +3303,36 @@ description of this request is on page 21.. - - + + + - + LbxPolySegment - + gc-and-drawable: LBXGCANDDRAWABLE - + segments : LISTofLBXSEGMENT - +   - + where: - + LBXSEGEMENT; [x1, y1, x2, y2: LBXINT16] - + Errors: Alloc and those given for the corresponding X request. @@ -3337,26 +3366,27 @@ LbxPolySegment. - - + + + - + LbxPolyRectangle - + gc-and-drawable: LBXGCANDDRAWABLE - + rectangles : LISTofLBXRECTANGLE - + Errors: Alloc and those given for the corresponding X request. @@ -3383,26 +3413,27 @@ description of this request is on page 22.. - - + + + - + LbxPolyArc - + gc-and-drawable: LBXGCANDDRAWABLE - + arcs : LISTofLBXARC - + Errors: Alloc and those given for the corresponding X request. @@ -3429,26 +3460,27 @@ LbxPolyArc. - - + + + - + LbxPolyFillRectangle - + gc-and-drawable: LBXGCANDDRAWABLE - + rectangles : LISTofLBXRECTANGLE - + Errors: Alloc and those given for the corresponding X request. @@ -3475,26 +3507,27 @@ LbxPolyFillRectangle. - - + + + - + LbxPolyFillArc - + gc-and-drawable: LBXGCANDDRAWABLE - + arcs : LISTofLBXARC - + Errors: Alloc and those given for the corresponding X request. @@ -3521,31 +3554,32 @@ description of this request is on page 22.. - - + + + - + LbxFillPoly - + gc-and-drawable: LBXGCANDDRAWABLE - + shape : BYTE - + points : LISTofLBXPOINT - + Errors: Alloc and those given for the corresponding X request. @@ -3578,61 +3612,62 @@ LbxFillPoly. - - + + + - + LbxCopyArea - + srcCache : CARD8 /* source drawable */ - + gc-and-drawable: LBXGCANDDRAWABLE - + src-Drawable : CARD32 - + src-x : LBXPINT16 - + src-y : LBXPINT16 - + width : LBXCARD16 - + height : LBXCARD16 - + dst-x : LBXPINT16 - + dst-y : LBXPINT16 - + Errors: Those given for the corresponding X request. @@ -3654,66 +3689,67 @@ LbxCopyArea. - - + + + - + LbxCopyPlane - + bit-plane : CARD32 - + src-cache : CARD8 /* cache reference for source drawable */ - + gc-and-drawable: LBXGCANDDRAWABLE - + src-drawable : CARD32 - + src-x : LBXPINT16 - + src-y : LBXPINT16 - + width : LBXCARD16 - + height : LBXCARD16 - + dst-x : LBXPINT16 - + dst-y : LBXPINT16 - + Errors: Those given for the corresponding X request. @@ -3735,36 +3771,37 @@ LbxCopyPlane. - - + + + - + LbxPolyText8 - + gc-and-drawable: LBXGCANDDRAWABLE - + x : LBXPINT16 - + y : LBXPINT16 - + items : LISTofTEXTITEM8 - + Errors: Alloc , and those given for the corresponding X request. @@ -3787,36 +3824,37 @@ description of this request is on page 23.. - - + + + - + LbxPolyText16 - + gc-and-drawable: LBXGCANDDRAWABLE - + x: LBXPINT16 - + y : LBXPINT16 - + items : LISTofTEXTITEM16 - + Errors: Alloc , and those given for the corresponding X request. @@ -3839,41 +3877,42 @@ description of this request is on page 24.. - - + + + - + LbxImageText8 - + gc-and-drawable: LBXGCANDDRAWABLE - + nChars : CARD8 - + x : LBXPINT16 - + y : LBXPINT16 - + string : STRING8 - + Errors: Alloc , and those given for the corresponding X request. @@ -3896,39 +3935,40 @@ description of this request is on page 24.. - - + + + - + LbxImageText16 - + nChars : CARD8 - + gc-and-drawable: LBXGCANDDRAWABLE - + x: LBXPINT16 - + y : LBXPINT16 - + string : STRING16 - + Errors: Alloc , and those given for the corresponding X request. @@ -3951,20 +3991,21 @@ description of this request is on page 24.. - - + + + - + LbxPutImage - + compression-method : CARD8 - + format : { @@ -3975,47 +4016,47 @@ XYPixmap ZPixmap } /* packed */ - + gc-and-drawable: LBXGCANDDRAWABLE - + width , height : LBXCARD16 - + dst-x , dst-y : LBXPINT16 - + depth : CARD8 /* packed */ - + left-pad : CARD8 /* packed */ - + pad-bytes : CARD8 /* packed */ - + data :LISTofBYTE - + Errors: Alloc , @@ -4052,63 +4093,64 @@ LbxPutImage. - - + + + - + LbxGetImage - + drawable : DRAWABLE - + x , y : INT16 - + width , height : CARD16 - + plane-mask : CARD32 - + format : {XYPixmap, ZPixmap} - + => - + depth: CARD8 - + x-length: CARD32 - + visual: VISUALID or None - + compression-method: CARD8 - + data: LISTofBYTE - + Errors: Alloc,Match,Value @@ -4157,21 +4199,22 @@ LbxGetImage. - - + + + - + LbxBeginLargeRequest - + large-request-length : CARD32 - + Errors: Alloc @@ -4213,21 +4256,22 @@ description of this request is on page 25.. - - + + + - + LbxLargeRequestData - + data : LISTofBYTE - + Errors: Alloc @@ -4258,15 +4302,16 @@ description of this request is on page 26.. - - + + + - + LbxEndLargeRequest - + Errors: Length, Alloc @@ -4315,15 +4360,16 @@ LbxEndLargeRequest. Events - - + + + - + LbxSwitchEvent - + client : CARD32 @@ -4345,15 +4391,16 @@ LbxSwitchEvent. - - + + + - + LbxCloseEvent - + client : CARD32 @@ -4374,20 +4421,21 @@ description of this event is on page 27.. - - + + + - + LbxInvalidateTagEvent - + tag : CARD32 - + tag-type : {Modmap, Keymap, Property, Font, ConnInfo} @@ -4420,20 +4468,21 @@ LbxInvalidateTagEvent. - - + + + - + LbxSendTagDataEvent - + tag : CARD32 - + tag-type : {Property} @@ -4463,15 +4512,16 @@ LbxSendTagDataEvent. - - + + + - + LbxListenToOne - + client : CARD32 or @@ -4523,10 +4573,11 @@ description of this event is on page 27.. - - + + + - + LbxListenToAll @@ -4546,25 +4597,26 @@ description of this event is on page 27.. - - + + + - + LbxQuickMotionDeltaEvent - + deltaTime : CARD8 - + deltaX : INT8 - + deltaY : INT8 @@ -4600,30 +4652,31 @@ LbxQuickMotionDeltaEvent. - - + + + - + LbxMotionDeltaEvent - + deltaX : INT8 - + deltaY : INT8 - + deltaTime : CARD16 - + deltaSequence : CARD16 @@ -4659,15 +4712,16 @@ LbxMotionDeltaEvent. - - + + + - + LbxReleaseCmapEvent - + colormap : Colormap @@ -4690,20 +4744,21 @@ LbxReleaseCmapEvent. - - + + + - + LbxFreeCellsEvent - + colormap : Colormap - + pixelStart, pixelEnd : CARD32 @@ -4745,25 +4800,26 @@ speaking, events, replies or errors. - - + + + - + LbxDeltaResponse - + count : CARD8 - + cache-index : CARD8 - + diffs : LISTofDIFFITEM diff --git a/specs/security.xml b/specs/security.xml index b920618..93073c5 100644 --- a/specs/security.xml +++ b/specs/security.xml @@ -78,51 +78,49 @@ This request returns the major and minor version numbers of this extension. SecurityQueryVersion - - + + + + + - + client-major-version - + CARD16 - + client-minor-version - + CARD16 - + => - + server-major-version - + CARD16 - + server-minor-version - + CARD16 - - - - - @@ -163,69 +161,65 @@ authorization. SecurityGenerateAuthorization - - + + + + + - + authorization-protocol-name - + STRING8 - + authorization-protocol-data - + STRING8 - + value-mask - + BITMASK - + value-list - + LISTofVALUE - + => - + authorization-id - + AUTHID - + authorization-data-return - - STRING8 - - - - - - + STRING8 @@ -264,95 +258,80 @@ The value-mask and value-list specify attributes of the authorization that are to be explicitly initialized. The possible values are: - - - - - - - - - - - Attribute - - - Type - - - Default - + + + + + + + + + Attribute + Type + Default + + - + timeout - + CARD32 - + 60 - + group - + XID or None - + None - + trust-level - + {SecurityClientTrusted, - + - + SecurityClientUntrusted} - + SecurityClientUntrusted - + event-mask - + SecurityAuthorizationRevoked, - + - + or None - + None - - - - - - - - - - @@ -395,40 +374,26 @@ is reported to the client. The SecurityAuthorizationRevoked event contains the following field: - - - + + + + + + - - - - - - - Field - - - Type - + Field + Type - - + + + + authorization-id - + AUTHID - - - - - - - - - - @@ -471,22 +436,20 @@ This request deletes an authorization created by SecurityGenerateAuthorization. SecurityRevokeAuthorization - - + + + + + - + authorization-id - + AUTHID - - - - - @@ -898,30 +861,28 @@ follows. authorization-protocol-data - - + + + + + - + policy-mask - + BITMASK - + policies - + LISTofSECURITYPOLICY - - - - - @@ -935,30 +896,28 @@ to the nth 1-bit in policy-mask, counting upward from bit 0. SECURITYPOLICY - - + + + + + - + policy-type - + {Disallow, Permit} - + names - + LISTofSTR - - - - - @@ -1207,79 +1166,64 @@ For the purposes of the Security extension, the Xauth structure has the following fields: - - - + + + + + + + - - - - - - - Type - - - Field name - - - Description - + Type + Field name + Description + + - + unsigned short - + name_length - + number of bytes in name - + char * - + name - + authorization protocol name - + unsigned short - + data_length - + number of bytes in data - + char * - + data - + authorization protocol data - - - - - - - - - - @@ -1354,79 +1298,64 @@ null-terminated strings. The auth_in argument must be freed with The XSecurityAuthorizationAttributes structure has the following fields: - - - - - - - - + + + + + + + - - Type - - - Field name - - - Mask - + Type + Field name + Mask + + - + unsigned int - + trust_level - + XSecurityTrustLevel - + unsigned int - + timeout - + XSecurityTimeout - + XID - + group - + XSecurityGroup - + long - + event_mask - + XSecurityEventMask - - - - - - - - - - @@ -1462,91 +1391,75 @@ authorization. The XSecurityAuthorizationRevokedEvent structure has the following fields: - - - - - - - - + + + + + + + - - Type - - - Field name - - - Description - - + Type + Field name + Description + + - + int - + type - + event base + XSecurityAuthorizationRevoked - + unsigned long - + serial - + # of last request processed by server - + Bool - + send_event - + true if this came from SendEvent - + Display* - + display - + Display the event was read from - + XSecurityAuthorization - + auth_id - + revoked authorization id - - - - - - - - - - diff --git a/specs/shape.xml b/specs/shape.xml index 659253c..16751ff 100644 --- a/specs/shape.xml +++ b/specs/shape.xml @@ -336,25 +336,26 @@ extension is usable by the client. This document defines major version one - - + + + - + dest: WINDOW - + destKind: SHAPE_KIND - + op: SHAPE_OP - + xOff, yOff: INT16 - + rectangles: LISTofRECTANGLES - + ordering: { UnSorted, YSorted, @@ -362,7 +363,7 @@ extension is usable by the client. This document defines major version one YXBanded } - + Errors: Window, @@ -427,10 +428,11 @@ extents. - - + + + - + dest: WINDOW destKind: SHAPE_KIND @@ -440,7 +442,7 @@ extents. None - + Errors: Window, @@ -482,40 +484,41 @@ error results. - - + + + - + dest: WINDOW - + destKind: SHAPE_KIND - + op: SHAPE_OP - + xOff, yOff: INT16 - + source: WINDOW - + sourceKind: SHAPE_KIND - + Errors: Window, @@ -543,25 +546,26 @@ error results. - - + + + - + dest: WINDOW - + destKind: SHAPE_KIND - + xOff, yOff: INT16 - + Errors: Window, @@ -583,10 +587,11 @@ current position by the amounts xOff and yOff. - - + + + - + dest: WINDOW @@ -600,60 +605,61 @@ current position by the amounts xOff and yOff. - - + + + - + boundingShaped: BOOL - + clipShaped: BOOL - + xBoundingShape: INT16 - + yBoundingShape: INT16 - + widthBoundingShape: CARD16 - + heightBoundingShape: CARD16 - + xClipShape: INT16 - + yClipShape: INT16 - + widthClipShape: CARD16 - + heightClipShape: CARD16 - + Errors: Window @@ -678,20 +684,21 @@ corresponding default region are reported. - - + + + - + window: WINDOW - + enable: BOOL - + Errors: Window, @@ -719,21 +726,22 @@ causes the server to stop sending such events. - - + + + - + window: WINDOW - + => enable: BOOL - + Errors: Window @@ -755,26 +763,27 @@ events for the window are generated for this client. - - + + + - + window: WINDOW - + kind: SHAPE_KIND - + => rectangles: LISTofRECTANGLE - + ordering: { UnSorted, @@ -783,7 +792,7 @@ ordering: YXBanded } - + Errors: Window, @@ -810,36 +819,37 @@ request. - - + + + - + window: WINDOW - + kind: SHAPE_KIND - + shaped: BOOL - + x, y: INT16 - + width, height: CARD16 - + time: TIMESTAMP diff --git a/specs/sync.xml b/specs/sync.xml index 6df45a6..afb0783 100644 --- a/specs/sync.xml +++ b/specs/sync.xml @@ -570,57 +570,54 @@ This request creates an alarm and assigns the identifier id to it. The values-mask and values-list specify the attributes that are to be explicitly initialized. The attributes for an Alarm and their defaults are: - - - - - - - - - Attribute - Type - Default - - - - - - + + + + + + + + + + Attribute + Type + Default + + - trigger - TRIGGER - counter - None + trigger + TRIGGER + counter + None - - - value-type - Absolute + + + value-type + Absolute - - - value - 0 + + + value + 0 - - - test-type - PositiveComparison + + + test-type + PositiveComparison - delta - INT64 - 1 + delta + INT64 + 1 - events - BOOL - TRUE + events + BOOL + TRUE diff --git a/specs/tog-cup.xml b/specs/tog-cup.xml index c8597a6..a35ff8c 100644 --- a/specs/tog-cup.xml +++ b/specs/tog-cup.xml @@ -109,30 +109,31 @@ available location.) - - + + + - + client_major_version: CARD16 - + client_minor_version: CARD16 - + => - + server_major_version: CARD16 - + server_minor_version: CARD16 @@ -161,20 +162,21 @@ server_minor_version of zero (0). - - + + + - + screen: CARD32 - + => - + entries: LISTofCOLORITEM @@ -203,25 +205,26 @@ MS-Windows applications running/displaying on the same desktop. - - + + + - + cmap: COLORMAP - + items: LISTofCOLORITEM - + => - + items: LISTofCOLORITEM diff --git a/specs/xtest.xml b/specs/xtest.xml index 121a8d5..4893b88 100644 --- a/specs/xtest.xml +++ b/specs/xtest.xml @@ -178,11 +178,11 @@ subsequent sections: - - - + + + - + FAKE_EVENT_TYPE { KeyPress, @@ -192,26 +192,26 @@ FAKE_EVENT_TYPE ButtonRelease } - + FAKE_EVENT [type: FAKE_EVENT_TYPE, - + detail: BYTE, - + time: TIME, - + root: WINDOW, - + rootX, rootY: INT16] @@ -245,15 +245,15 @@ not required, respectively. - - + + - + gc: "GC" - + gid: GCONTEXT @@ -272,15 +272,15 @@ the value specified by gid. - - + + - + visual: "VISUAL" - + visualid: VISUALID @@ -299,20 +299,20 @@ the value specified by visualid. - - + + - + dpy: "CONNECTION" - + => - + status: BOOL @@ -340,35 +340,35 @@ otherwise. - - + + - + clientMajorVersion: CARD16 - + clientMinorVersion: CARD16 - + => - + serverMajorVersion: CARD16 - + serverMinorVersion: CARD16 - + Errors: Length @@ -389,15 +389,15 @@ extension is usable by the client. This document defines major version two - - + + - + window: WINDOW - + cursor-id: CURSOR or CurrentCursor @@ -405,17 +405,17 @@ or None - + => - + same: BOOL - + Errors: Window, @@ -441,15 +441,15 @@ the result of the comparison in same. - - + + - + events: LISTofFAKE_EVENT - + Errors: Window, @@ -585,10 +585,10 @@ error occurs. - - + + - + impervious: BOOL -- cgit v1.2.3