[PATCH] Describe the wayland protocol using inline XML comments

[Yuval Fledel]

Describe interfaces, requests and events in the protocol using inline
XML comments.

Signed-off-by: Yuval Fledel <yuvalfl at gmail.com>
---
 protocol/wayland.xml |   95 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 92 insertions(+), 3 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 506e59b..ac1db0c 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1,57 +1,103 @@
+<?xml version="1.0" encoding="UTF-8"?>
 <protocol name="wayland">

+  <!-- The core global object. This is a special singleton object.
+       It is used for internal wayland protocol features. -->
  <interface name="display" version="1">
+    <!-- sync is an just an echo, which will reply with a sync event.
+         Since requests are handled in the same order, this can be used
+         as a barrier to ensure all previous requests have ben handled.
+         The key argument can be used to correlate between multiple sync
+         invocations. -->
    <request name="sync">
      <arg name="key" type="uint"/>
    </request>

+    <!-- Request notification when the next frame is displayed.
+         Useful for throttling redrawing operations, and for lip-sync.
+         The notification will only be posted for one frame unless requested
+         again. -->
    <request name="frame">
      <arg name="key" type="uint"/>
    </request>

+    <!-- Some request has been called upon a non-existant object id. -->
    <event name="invalid_object">
      <arg name="object_id" type="uint"/>
    </event>

+    <!-- Some request had a bad opcode. -->
    <event name="invalid_method">
      <arg name="object_id" type="uint"/>
      <arg name="opcode" type="uint"/>
    </event>

+    <!-- Some request has failed due to an out of memory error. -->
    <event name="no_memory"/>

+    <!-- Notify the client of global objects. These are objects that are
+         created by the server. Globals are published on the initial client
+         connection sequence, or upon device hotplugs, device disconnects,
+         or reconfiguration.  -->
    <event name="global">
      <arg name="id" type="new_id" interface="object"/>
      <arg name="name" type="string"/>
      <arg name="version" type="uint"/>
    </event>

+    <!-- Internal, deprecated, and will be changed.
+         This is an object IDs range that can be used by the client
+         to allocate object IDs in "new_id" type arguments.
+         The server sends range allocations to the client before the
+         next range is about to be deplated. -->
    <event name="range">
      <arg name="base" type="uint"/>
    </event>

+    <!-- An echo reply of the "sync" request.
+         All requests made before the "sync" request that had the
+         same key as the one present in this event have been processed
+         by the server. -->
    <event name="sync">
      <arg name="key" type="uint"/>
    </event>

+    <!-- A Frame update notification. Sent only if requested via the
+         "frame" request. The key is the one used in the request.
+         time is in millisecond units, and denotes the time when the frame
+         was posted on the display. time can be used to compoensate for
+         jitter. -->
    <event name="frame">
      <arg name="key" type="uint"/>
      <arg name="time" type="uint"/>
    </event>
  </interface>

+  <!-- A compositor. This object is a global.
+       The compositor is in charge of combining the contents of multiple
+       surfaces into one displayable output. -->
  <interface name="compositor" version="1">
+    <!-- Factory request for a surface objects. A surface is akin to a
+         window. -->
    <request name="create_surface">
      <arg name="id" type="new_id" interface="surface"/>
    </request>
  </interface>

+  <!-- DRI2 support. This object is created by the server and published
+       using the display's global event. -->
  <interface name="drm" version="1">
-    <!-- dri2 auth and create buffer -->
+    <!-- Call this request with the magic received from drmGetMagic().
+         It will be passed on to the drmAuthMagic() or DRIAuthConnection()
+         call. This authentication must be completed before create_buffer
+         could be used, or the client could be root and authenticate
+         itself. -->
    <request name="authenticate">
      <arg name="id" type="uint"/>
    </request>

+    <!-- Transfer a DRM surface to the server.
+         The DRM surface must have a name using the flink ioctl -->
    <request name="create_buffer">
      <arg name="id" type="new_id" interface="buffer"/>
      <arg name="name" type="uint"/>
@@ -61,14 +107,26 @@
      <arg name="visual" type="object" interface="visual"/>
    </request>

+    <!-- Notification of the path of the DRM device which is used
+         by the server. The client should use this device for creating local
+         buffers. Only buffers created from this device should be be passed
+         to the server using this object's create_buffer request. -->
    <event name="device">
      <arg name="name" type="string"/>
    </event>

+    <!-- Raised if the authenticate request succeeded -->
    <event name="authenticated"/>
  </interface>

+  <!-- SHared Memory support -->
  <interface name="shm" version="1">
+    <!-- Transfer a shm buffer to the server.
+         The allocated buffer would include stride*height bytes starting at
+         the beginning of fd. The file descriptor is transferred over the
+         socket using AF_UNIX magical features. width, height, stride and
+         visual describe the respective properties of the pixmap contained
+         in the buffer. -->
    <request name="create_buffer">
      <arg name="id" type="new_id" interface="buffer"/>
      <arg name="fd" type="fd"/>
@@ -79,7 +137,10 @@
    </request>
  </interface>

+  <!-- A pixmap buffer. Created using DRM or SHM.
+       It has a size, visual and contents, but not a location on the screen -->
  <interface name="buffer" version="1">
+    <!-- Abandon a buffer. This will invalidate the object id. -->
    <request name="destroy" type="destructor"/>
  </interface>

@@ -184,7 +245,7 @@
    </event>

    <!-- Similar to device::motion.  Sent to potential target surfaces
-        as the drag pointer moves around in the surface. -->
+         as the drag pointer moves around in the surface. -->
    <event name="motion">
      <arg name="time" type="uint"/>
      <arg name="x" type="int"/>
@@ -200,13 +261,19 @@
    <event name="drop"/>
  </interface>

+  <!-- A surface. This is an image that is displayed on the screen.
+       It has a location, size and pixel contents. Similar to a window. -->
  <interface name="surface" version="1">
+    <!-- Deletes the surface and invalidates its object id. -->
    <request name="destroy" type="destructor"/>

+    <!-- Copy the contents of a buffer into this surface. -->
    <request name="attach">
      <arg name="buffer" type="object" interface="buffer"/>
    </request>

+    <!-- Set the location on the screen that this surface will
+         be displayed. -->
    <request name="map">
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
@@ -214,6 +281,10 @@
      <arg name="height" type="int"/>
    </request>

+    <!-- Notify the server that the attached buffer's contents have
+         changed, and request a redraw. The arguments allow you to damage
+         only a part of the surface, but the server may ignore it and redraw
+         the entire contents of the surface. -->
    <request name="damage">
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
@@ -222,7 +293,10 @@
    </request>
  </interface>

+  <!-- A keyboard, a mouse or similar. This object is published as a global
+       during start up, or when such a device is hot plugged. -->
  <interface name="input_device" version="1">
+    <!-- Change the pointer's image. -->
    <request name="attach">
      <arg name="time" type="uint"/>
      <arg name="buffer" type="object" interface="buffer"/>
@@ -230,6 +304,9 @@
      <arg name="hotspot_y" type="int"/>
    </request>

+    <!-- Notification of pointer location change.
+         x,y are the absolute location on the screen.
+         surface_[xy] are the location relative to the focused surface. -->
    <event name="motion">
      <arg name="time" type="uint"/>
      <arg name="x" type="int"/>
@@ -238,18 +315,22 @@
      <arg name="surface_y" type="int"/>
    </event>

+    <!-- Mouse button click and release notifications. -->
    <event name="button">
      <arg name="time" type="uint"/>
      <arg name="button" type="uint"/>
      <arg name="state" type="uint"/>
    </event>

+    <!-- Keyboard click. -->
    <event name="key">
      <arg name="time" type="uint"/>
      <arg name="key" type="uint"/>
      <arg name="state" type="uint"/>
    </event>

+    <!-- Notification that this input device's pointer is focused on
+         certain surface. -->
    <event name="pointer_focus">
      <arg name="time" type="uint"/>
      <arg name="surface" type="object" interface="surface"/>
@@ -266,13 +347,21 @@
    </event>
  </interface>

+  <!-- A monitor. A screen. Something that can display an image.
+       This object is published as global during start up, or when
+       a screen is hot plugged. -->
  <interface name="output" version="1">
+    <!-- Notification about the screen size. -->
    <event name="geometry">
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </event>
  </interface>

-  <interface name="visual" version="1" />
+  <!-- A visual is the pixel format.
+       This functions as an enumeration.
+       visuals are published globally by the server upon the initial
+       handshake. -->
+  <interface name="visual" version="1"/>

 </protocol>
\ No newline at end of file
--
1.7.1
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Describe-interfaces-requests-and-events-in-the-proto.patch
Type: application/octet-stream
Size: 10145 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20101129/2521e393/attachment-0001.obj>