- XML-XCB
+ xcb/proto
Description
===========
-XML-XCB generates C bindings to the X Window System protocol based on XML
-descriptions of the protocol. It is designed for use with XCB, the X C
-binding <http://xcb.freedesktop.org>. XML-XCB consists of:
+xcb/proto is a set of XML files describing the X Window System protocol
+It is designed for use with libxcb, the X C binding
+<http://xcb.freedesktop.org/>. xcb/proto consists of:
xcb.xsd An XML Schema defining the data format for describing the X
- protocol. Included in xcb-proto.
+ protocol.
-c-client.xsl An XSLT code generator that transforms the protocol descriptions
- into C bindings. Included in xcb.
+*.py Code generator helpers that read the protocol descriptions
+ into python structures. See libxcb for example usage.
*.xml XML descriptions of the core X protocol and many extensions.
- Included in xcb-proto.
-
-
-Dependencies
-============
-
-c-client.xsl requires an XSLT processor that supports XSLT 1.0
-<http://www.w3.org/TR/1999/REC-xslt-19991116> and the EXSLT node-set extension
-<http://www.exslt.org/exsl/functions/node-set/index.html>. The XCB build
-system currently uses xsltproc. You can get xsltproc through your
-distribution's packaging system, or from <http://xmlsoft.org/XSLT/>.
Generating C bindings
=====================
-The C bindings for the core protocol and all the currently supported
-extensions are built as part of the xcb build system. However, for the
-purposes of creating and debugging new protocol descriptions, it can be useful
-to generate the bindings directly by invoking c-client.xsl to the XML protocol
-description.
-
-You must provide several parameters to c-client.xsl:
-
-mode: header or source; specifies which part of the C bindings to generate.
-base-path: path to the core X protocol descriptions.
-extension-path: path to the extension descriptions.
-
-For example, using xsltproc, you can generate the header for a protocol
-description "protocol.xml" with the command:
-
-xsltproc --stringparam base-path /path/to/xcb-proto/src \
- --stringparam extension-path /path/to/xcb-proto/src/extensions \
- --stringparam mode header /path/to/xcb/src/c-client.xsl protocol.xml
+See libxcb <http://cgit.freedesktop.org/xcb/libxcb/>.
Protocol Description Format
The import element allows the protocol description to reference types
declared in another extension. The content is be the basename of the
extension XML file, which is also the header attribute of the extension's
- root node. Note that types from xcb_types and xproto are automatically
- available, without explicitly importing them.
+ root node. Note that types from xproto are automatically available, without
+ explicitly importing them.
<struct name="identifier">structure contents</struct>
------------------
Note: "type" attributes below refer to types defined by previous elements,
-either in the current extension, xproto, xcb_types, or one of the imported
-extensions. The type name must refer to only one possible type; if more than
-one type matches, an error occurs. To avoid this, the type may be explicitly
-prefixed with a namespace, which should be the value of the header attribute
-on the protocol description containing the desired type. The namespace and
-type are separated by a single colon. For example, to refer to the PIXMAP
-type defined in glx rather than the one defined in xcb_types, use
-type="glx:PIXMAP" rather than type="PIXMAP".
+either in the current extension, xproto, or one of the imported extensions.
+The type name must refer to only one possible type; if more than one type
+matches, an error occurs. To avoid this, the type may be explicitly prefixed
+with a namespace, which should be the value of the header attribute on the
+protocol description containing the desired type. The namespace and type are
+separated by a single colon. For example, to refer to the PIXMAP type defined
+in glx rather than the one defined in xproto, use type="glx:PIXMAP" rather
+than type="PIXMAP".
+
+Note: Most of the below may optionally contain an enum, altenum, or mask
+attribute, which follows the above rules for "type". "enum" is an exhaustive
+enum; the value is restricted to one of the constants named in the enum.
+"altenum" may be one of the values contained in the enum, but it need not be.
+"mask" refers to an enum to be used as a bitmask.
<pad bytes="integer" />
defining the set of values included, and a list containing these values.
value-mask-type gives the type of the bitmask; this must be CARD16 or
CARD32. value-mask-name gives the field name of the bitmask, and
- value-list-name gives the field name of the list of values.
+ value-list-name gives the field name of the list of values. Please use
+ <switch> instead for new protocol definitions.
+<switch name="identifier"> switch expression
+ <bitcase> bitcase expression, fields </bitcase> </switch>
+
+ This element represents conditional inclusion of fields. It can be viewed
+ as sequence of multiple ifs: if ( switch expression & bitcase expression )
+ is equal to bitcase expression, bitcase fields are included in structure.
+ It can be used only as the last field of structure. New protocol definitions
+ should prefer to use this instead of <valueparam>.
Expressions
-----------
The bit element represents a literal bitmask value in an expression.
The integer must be in the range 0..31, expanding to (1<<n) in C.
+
+<enumref ref="identifier">enum item identifier</enumref>
+
+ This element represents a reference to item of enum.
+
+<unop op="operator">expression</unop>
+
+ This element represents a unary operator, with the op attribute specifying
+ which operator. The only supported operation so far is ~, and its semantic
+ is identical to the corresponding operator in C.
+
+<sumof ref="identifier" />
+
+ This element represents a sumation of the elements of the referenced list.
+
+<popcount>expression</popcount>
+
+ This element represents the number of bits set in the expression.
+
projects / free-sw / xcb / proto / blobdiff