Describe interfaces, requests and events in the protocol using inline XML comments.
Signed-off-by: Yuval Fledel <[email protected]> --- 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
Describe-interfaces-requests-and-events-in-the-proto.patch
Description: Binary data
_______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
