7311911f60e3d2aaedbaaed3b66b05bdd7afe08e
[free-sw/xcb/proto] / doc / xml-xcb.txt
1                                   xcb/proto
2
3 Description
4 ===========
5
6 xcb/proto is a set of XML files describing the  X Window System protocol
7 It is designed for use with libxcb, the X C binding
8 <http://xcb.freedesktop.org/>.  xcb/proto consists of:
9
10 xcb.xsd      An XML Schema defining the data format for describing the X
11              protocol.
12
13 *.py         Code generator helpers that read the protocol descriptions
14              into python structures. See libxcb for example usage.
15
16 *.xml        XML descriptions of the core X protocol and many extensions.
17
18
19 Generating C bindings
20 =====================
21
22 See libxcb <http://cgit.freedesktop.org/xcb/libxcb/>.
23
24
25 Protocol Description Format
26 ===========================
27
28 Root element
29 ------------
30
31 <xcb header="string" extension-name="string" extension-xname="string">
32   top-level elements
33 </xcb>
34
35   This is the root element of a protocol description.  The attributes are all
36   various forms of the extension name.  header is the basename of the XML
37   protocol description file, which will be used as the basename for generated
38   bindings as well.  extension-name is the name of the extension in InterCaps,
39   which will be used in the names of functions.  extension-xname is the name
40   of the extension as passed to QueryExtension.
41
42   As an example, the XML-XCB description for the GO-FASTER extension would use
43   the root element <xcb header="gofaster" extension-name="GoFaster"
44   extension-xname="GO-FASTER">; as a result, C bindings will be put in
45   gofaster.h and gofaster.c, extension functions will be named
46   XCBGoFasterFunctionName, and the extension initialization will call
47   QueryExtension with the name "GO-FASTER".
48
49   This element can contain any number of the elements listed in the section
50   "Top-Level Elements" below.
51
52
53 Top-Level Elements
54 ------------------
55
56 <import>header_name</import>
57
58   The import element allows the protocol description to reference types
59   declared in another extension.  The content is be the basename of the
60   extension XML file, which is also the header attribute of the extension's
61   root node.  Note that types from xproto are automatically available, without
62   explicitly importing them.
63
64 <struct name="identifier">structure contents</struct>
65
66   This element represents a data structure.  The name attribute gives the name
67   of the structure.  The content represents the fields of the structure, and
68   consists of one or more of the field, pad, and list elements described in
69   the section "Structure Contents" below.
70
71 <union name="identifier">structure contents</union>
72
73   This element represents a union of data types, which can hold one value of
74   any of those types.  The name attribute gives the name of the union.  The
75   content represents the fields of the union, and consists of one or more of
76   the field and pad elements described in the section "Structure Contents
77   below".
78
79 <xidtype name="identifier" />
80
81   This element represents an identifier for a particular type of resource.
82   The name attribute gives the name of the new type.
83
84 <enum name="identifier">
85   <item name="identifier">[optional expression]</item>
86   ...
87 </enum>
88
89   The enum element represents an enumeration type, which can take on any of
90   the values given by the contained item elements.  The name attribute on the
91   enum gives the name of the enumerated type.
92
93   The item element represents one possible value of an enumerated type.  The
94   name attribute on the item gives the name of that value, and the optional
95   content is an expression giving the numeric value.  If the expression is
96   omitted, the value will be one more than that of the previous item, or 0 for
97   the first item.
98
99 <typedef oldname="identifier" newname="identifier" />
100
101   The typedef element declares the type given by the newname attribute to be
102   an alias for the type given by the oldname attribute.
103
104 <request name="identifier" opcode="integer" [combine-adjacent="true"]>
105   structure contents
106   [<reply>structure contents</reply>]
107 </request>
108
109   The request element represents an X protocol request.  The name attribute
110   gives the name of the request, and the opcode attribute gives the numeric
111   request code.  The content of the request element represents the fields in
112   the request, and consists of one or more of any of the elements listed in
113   the "Structure Contents" section below.  Note that for requests in the core
114   protocol, the first field in the request goes into the one-byte gap between
115   the major opcode and the length; if the request does not have any data in
116   that gap, put a one byte pad as the first element.  Extension requests
117   always have this gap filled with the minor opcode.
118
119   The optional reply element is present if the request has a reply.  The
120   content of the reply element represents the fields in the reply, and
121   consists of zero or more of the field, pad, and list elements listed in the
122   "Structure Contents" section below.  Note that the first field in the reply
123   always goes into the one-byte gap between the response type and the sequence
124   number; if the reply does not have any data in that gap, put a one byte pad
125   as the first element.
126
127   If the optional combine-adjacent attribute is true, multiple adjacent
128   requests of the same type may be combined into a single request without
129   affecting the semantics of the requests.
130
131 <event name="identifier" number="integer"
132        [[no-sequence-number="true"] | [xge="true"]]>
133   structure contents
134 </event>
135
136   This element represents an X protocol event.  The name attribute gives the
137   name of the event, and the number attribute gives the event number.  The
138   content of the event element represents the fields in the event, and
139   consists of zero or more of the field, pad, and list elements listed in the
140   "Structure Contents" section below.
141
142   If the optional no-sequence-number attribute is true, the event does not
143   include a sequence number.  This is a special-case for the KeymapNotify
144   event in the core protocol, and should not be used in any other event.
145
146   If the optional xge attribute is true, the event is an X Generic Event and
147   will be treated as such.
148
149   The no-sequence-number and xge attribute can not be combined.
150
151 <error name="identifier" number="integer">
152   structure contents
153 </error>
154
155   This element represents an X protocol error.  The name attribute gives the
156   name of the error, and the number attribute gives the error number.  The
157   content of the error element represents the fields in the error, and
158   consists of zero or more of the field, pad, and list elements listed in the
159   "Structure Contents" section below.
160
161 <eventcopy name="identifier" number="identifier" ref="identifier" />
162
163   This element creates an alias for the event named in the ref attribute, with
164   the new name given in the name attribute, and the new event number given in
165   the number attribute.
166
167 <errorcopy name="identifier" number="identifier" ref="identifier" />
168
169   This element creates an alias for the error named in the ref attribute, with
170   the new name given in the name attribute, and the new error number given in
171   the number attribute.
172
173
174 Structure Contents
175 ------------------
176
177 Note: "type" attributes below refer to types defined by previous elements,
178 either in the current extension, xproto, or one of the imported extensions.
179 The type name must refer to only one possible type; if more than one type
180 matches, an error occurs.  To avoid this, the type may be explicitly prefixed
181 with a namespace, which should be the value of the header attribute on the
182 protocol description containing the desired type.  The namespace and type are
183 separated by a single colon.  For example, to refer to the PIXMAP type defined
184 in glx rather than the one defined in xproto, use type="glx:PIXMAP" rather
185 than type="PIXMAP".
186
187 Note: Most of the below may optionally contain an enum, altenum, or mask
188 attribute, which follows the above rules for "type". "enum" is an exhaustive
189 enum; the value is restricted to one of the constants named in the enum.
190 "altenum" may be one of the values contained in the enum, but it need not be.
191 "mask" refers to an enum to be used as a bitmask.
192
193 <pad bytes="integer" />
194
195   This element declares some padding in a data structure.  The bytes
196   attribute declares the number of bytes of padding.
197
198 <field type="identifier" name="identifier" />
199
200   This element represents a field in a data structure.  The type attribute
201   declares the data type of the field, and the name attribute gives the name
202   of the field.
203
204 <list type="identifier" name="identifier">expression</list>
205
206   This element represents an array or list of fields in a data structure.  The
207   type attribute declares the data type of the field, and the name attribute
208   gives the name of the field.  The content is an expression giving the length
209   of the list in terms of other fields in the structure.  See the section
210   "Expressions" for details on the expression representation.
211
212 <localfield type="identifier" name="identifier" />
213
214   This element represents a parameter in a request that is not sent over the
215   wire.  The field can be referenced in the length expressions of lists or in
216   an exprfield.  The type attribute declares the data type of the field, and
217   the name attribute gives the name of the field.
218
219 <exprfield type="identifier" name="identifier">expression</exprfield>
220
221   This element represents a field in a request that is calculated rather than
222   supplied by the caller.  The type attribute declares the data type of the
223   field, and the name attribute gives the name of the field.  The content is
224   the expression giving the value of the field.  See the section "Expressions"
225   for details on the expression representation.
226
227 <valueparam value-mask-type="identifier" value-mask-name="identifier"
228             value-list-name="identifier" />
229
230   This element represents a BITMASK/LISTofVALUE parameter pair: a bitmask
231   defining the set of values included, and a list containing these values.
232   value-mask-type gives the type of the bitmask; this must be CARD16 or
233   CARD32.  value-mask-name gives the field name of the bitmask, and
234   value-list-name gives the field name of the list of values. Please use
235   <switch> instead for new protocol definitions.
236
237 <switch name="identifier"> switch expression
238     <bitcase> bitcase expression(s), fields </bitcase> </switch>
239
240   This element represents conditional inclusion of fields. It can be viewed
241   as sequence of multiple ifs: if ( switch expression & bitcase expression )
242   is non-zero, bitcase fields are included in structure.  It can be used only
243   as the last field of a structure.
244
245   When a bitcase includes multiple <enumref> clauses, the contents of the
246   bitcase are only present once regardless of the number of bitcase expressions
247   that match.
248
249   New protocol definitions should prefer to use this instead of <valueparam>.
250
251 Expressions
252 -----------
253
254   Expressions consist of a tree of <op> elements with leaves consisting of
255   <fieldref> or <value> elements.
256
257 <op op="operator">expression expression</op>
258
259   The op element represents an operator, with the op attribute specifying
260   which operator.  The supported operations are +, -, *, /, &amp;, and
261   &lt;&lt;, and their semantics are identical to the corresponding operators
262   in C.  The two operand expressions may be other expression elements.
263
264 <fieldref>identifier</fieldref>
265
266   The fieldref element represents a reference to the value of another field in
267   the structure containing this expression.  The identifier is the value of
268   the "name" attribute on the referenced field.
269
270 <value>integer</value>
271
272   The value element represents a literal integer value in an expression.  The
273   integer may be expressed in decimal or hexadecimal.
274
275 <bit>integer</bit>
276
277   The bit element represents a literal bitmask value in an expression.
278   The integer must be in the range 0..31, expanding to (1<<n) in C.
279
280 <enumref ref="identifier">enum item identifier</enumref>
281
282   This element represents a reference to item of enum.
283
284 <unop op="operator">expression</unop>
285
286   This element represents a unary operator, with the op attribute specifying
287   which operator. The only supported operation so far is ~, and its semantic
288   is identical to the corresponding operator in C.
289
290 <sumof ref="identifier" />
291
292   This element represents a sumation of the elements of the referenced list.
293
294 <popcount>expression</popcount>
295
296   This element represents the number of bits set in the expression.
297
298 Documentation
299 -------------
300
301   Documentation for each request, reply or event is stored in the appropriate
302   element using a <doc> element. The <doc> element can contain the following
303   elements:
304
305 <brief>brief description</brief>
306
307   A short description of the request, reply or event. For example "makes a
308   window visible" for MapWindow. This will end up in the manpage NAME section
309   and in the doxygen @brief description.
310
311 <description><![CDATA[longer description]]></description>
312
313   The full description. Use `` to highlight words, such as "Draws
314   `points_len`-1 lines between each pair of points…"
315
316 <example><![CDATA[example code]]</description>
317
318   Example C code illustrating the usage of the particular request, reply or
319   event.
320
321 <field name="name">field description</field>
322
323   The full description for the specified field. Depending on the context, this
324   is either a request parameter or a reply/event datastructure field.
325
326 <error type="type">error description</field>
327
328   The full description for an error which can occur due to this request.
329
330 <see type="request" name="name" />
331
332   A reference to another relevant program, function, request or event.