diff options
Diffstat (limited to 'src/3rdparty/protocol/wayland.xml')
| -rw-r--r-- | src/3rdparty/protocol/wayland.xml | 1608 |
1 files changed, 1608 insertions, 0 deletions
diff --git a/src/3rdparty/protocol/wayland.xml b/src/3rdparty/protocol/wayland.xml new file mode 100644 index 00000000..3bce022c --- /dev/null +++ b/src/3rdparty/protocol/wayland.xml @@ -0,0 +1,1608 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="wayland"> + + <copyright> + Copyright © 2008-2011 Kristian Høgsberg + Copyright © 2010-2011 Intel Corporation + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + the copyright holders not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. The copyright holders make no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN + AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </copyright> + + <interface name="wl_display" version="1"> + <description summary="core global object"> + The core global object. This is a special singleton object. It + is used for internal Wayland protocol features. + </description> + + <request name="sync"> + <description summary="asynchronous roundtrip"> + The sync request asks the server to emit the 'done' event + on the returned wl_callback object. Since requests are + handled in-order and events are delivered in-order, this can + used as a barrier to ensure all previous requests and the + resulting events have been handled. + + The object returned by this request will be destroyed by the + compositor after the callback is fired and as such the client must not + attempt to use it after that point. + </description> + <arg name="callback" type="new_id" interface="wl_callback"/> + </request> + + <request name="get_registry"> + <description summary="get global registry object"> + This request creates a registry object that allows the client + to list and bind the global objects available from the + compositor. + </description> + <arg name="callback" type="new_id" interface="wl_registry"/> + </request> + + <event name="error"> + <description summary="fatal error event"> + The error event is sent out when a fatal (non-recoverable) + error has occurred. The object_id argument is the object + where the error occurred, most often in response to a request + to that object. The code identifies the error and is defined + by the object interface. As such, each interface defines its + own set of error codes. The message is an brief description + of the error, for (debugging) convenience. + </description> + <arg name="object_id" type="object"/> + <arg name="code" type="uint"/> + <arg name="message" type="string"/> + </event> + + <enum name="error"> + <description summary="global error values"> + These errors are global and can be emitted in response to any + server request. + </description> + <entry name="invalid_object" value="0" + summary="server couldn't find object"/> + <entry name="invalid_method" value="1" + summary="method doesn't exist on the specified interface"/> + <entry name="no_memory" value="2" + summary="server is out of memory"/> + </enum> + + <event name="delete_id"> + <description summary="acknowledge object ID deletion"> + This event is used internally by the object ID management + logic. When a client deletes an object, the server will send + this event to acknowledge that it has seen the delete request. + When the client receive this event, it will know that it can + safely reuse the object ID. + </description> + <arg name="id" type="uint" /> + </event> + </interface> + + <interface name="wl_registry" version="1"> + <description summary="global registry object"> + The global registry object. The server has a number of global + objects that are available to all clients. These objects + typically represent an actual object in the server (for example, + an input device) or they are singleton objects that provide + extension functionality. + + When a client creates a registry object, the registry object + will emit a global event for each global currently in the + registry. Globals come and go as a result of device or + monitor hotplugs, reconfiguration or other events, and the + registry will send out global and global_remove events to + keep the client up to date with the changes. To mark the end + of the initial burst of events, the client can use the + wl_display.sync request immediately after calling + wl_display.get_registry. + + A client can bind to a global object by using the bind + request. This creates a client-side handle that lets the object + emit events to the client and lets the client invoke requests on + the object. + </description> + + <request name="bind"> + <description summary="bind an object to the display"> + Binds a new, client-created object to the server using the + specified name as the identifier. + </description> + <arg name="name" type="uint" summary="unique name for the object"/> + <arg name="id" type="new_id"/> + </request> + + <event name="global"> + <description summary="announce global object"> + Notify the client of global objects. + + The event notifies the client that a global object with + the given name is now available, and it implements the + given version of the given interface. + </description> + <arg name="name" type="uint"/> + <arg name="interface" type="string"/> + <arg name="version" type="uint"/> + </event> + + <event name="global_remove"> + <description summary="announce removal of global object"> + Notify the client of removed global objects. + + This event notifies the client that the global identified + by name is no longer available. If the client bound to + the global using the bind request, the client should now + destroy that object. + + The object remains valid and requests to the object will be + ignored until the client destroys it, to avoid races between + the global going away and a client sending a request to it. + </description> + <arg name="name" type="uint"/> + </event> + </interface> + + <interface name="wl_callback" version="1"> + <description summary="callback object"> + Clients can handle the 'done' event to get notified when + the related request is done. + </description> + <event name="done"> + <description summary="done event"> + Notify the client when the related request is done. + </description> + <arg name="serial" type="uint" summary="serial of the event"/> + </event> + </interface> + + <interface name="wl_compositor" version="2"> + <description summary="the compositor singleton"> + A compositor. This object is a singleton global. The + compositor is in charge of combining the contents of multiple + surfaces into one displayable output. + </description> + + <request name="create_surface"> + <description summary="create new surface"> + Ask the compositor to create a new surface. + </description> + <arg name="id" type="new_id" interface="wl_surface"/> + </request> + + <request name="create_region"> + <description summary="create new region"> + Ask the compositor to create a new region. + </description> + <arg name="id" type="new_id" interface="wl_region"/> + </request> + </interface> + + <interface name="wl_shm_pool" version="1"> + <description summary="a shared memory pool"> + The wl_shm_pool object encapsulates a piece of memory shared + between the compositor and client. Through the wl_shm_pool + object, the client can allocate shared memory wl_buffer objects. + All objects created through the same pool share the same + underlying mapped memory. Reusing the mapped memory avoids the + setup/teardown overhead and is useful when interactively resizing + a surface or for many small buffers. + </description> + + <request name="create_buffer"> + <description summary="create a buffer from the pool"> + Create a wl_buffer object from the pool. + + The buffer is created offset bytes into the pool and has + width and height as specified. The stride arguments specifies + the number of bytes from beginning of one row to the beginning + of the next. The format is the pixel format of the buffer and + must be one of those advertised through the wl_shm.format event. + + A buffer will keep a reference to the pool it was created from + so it is valid to destroy the pool immediately after creating + a buffer from it. + </description> + + <arg name="id" type="new_id" interface="wl_buffer"/> + <arg name="offset" type="int"/> + <arg name="width" type="int"/> + <arg name="height" type="int"/> + <arg name="stride" type="int"/> + <arg name="format" type="uint"/> + </request> + + <request name="destroy" type="destructor"> + <description summary="destroy the pool"> + Destroy the shared memory pool. + + The mmapped memory will be released when all + buffers that have been created from this pool + are gone. + </description> + </request> + + <request name="resize"> + <description summary="change the size of the pool mapping"> + This request will cause the server to remap the backing memory + for the pool from the file descriptor passed when the pool was + created, but using the new size. + </description> + + <arg name="size" type="int"/> + </request> + </interface> + + <interface name="wl_shm" version="1"> + <description summary="shared memory support"> + A global singleton object that provides support for shared + memory. + + Clients can create wl_shm_pool objects using the create_pool + request. + + At connection setup time, the wl_shm object emits one or more + format events to inform clients about the valid pixel formats + that can be used for buffers. + </description> + + <enum name="error"> + <description summary="wl_shm error values"> + These errors can be emitted in response to wl_shm requests. + </description> + <entry name="invalid_format" value="0" summary="buffer format is not known"/> + <entry name="invalid_stride" value="1" summary="invalid size or stride during pool or buffer creation"/> + <entry name="invalid_fd" value="2" summary="mmapping the file descriptor failed"/> + </enum> + + <enum name="format"> + <description summary="pixel formats"> + This describes the memory layout of an individual pixel. + </description> + <entry name="argb8888" value="0" summary="32-bit ARGB format"/> + <entry name="xrgb8888" value="1" summary="32-bit RGB format"/> + </enum> + + <request name="create_pool"> + <description summary="create a shm pool"> + Create a new wl_shm_pool object. + + The pool can be used to create shared memory based buffer + objects. The server will mmap size bytes of the passed file + descriptor, to use as backing memory for the pool. + </description> + + <arg name="id" type="new_id" interface="wl_shm_pool"/> + <arg name="fd" type="fd"/> + <arg name="size" type="int"/> + </request> + + <event name="format"> + <description summary="pixel format description"> + Informs the client about a valid pixel format that + can be used for buffers. Known formats include + argb8888 and xrgb8888. + </description> + <arg name="format" type="uint"/> + </event> + </interface> + + <interface name="wl_buffer" version="1"> + <description summary="content for a wl_surface"> + A buffer provides the content for a wl_surface. Buffers are + created through factory interfaces such as wl_drm, wl_shm or + similar. It has a width and a height and can be attached to a + wl_surface, but the mechanism by which a client provides and + updates the contents is defined by the buffer factory interface. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy a buffer"> + Destroy a buffer. If and how you need to release the backing + storage is defined by the buffer factory interface. + + For possible side-effects to a surface, see wl_surface.attach. + </description> + </request> + + <event name="release"> + <description summary="compositor releases buffer"> + Sent when this wl_buffer is no longer used by the compositor. + The client is now free to re-use or destroy this buffer and its + backing storage. + + If a client receives a release event before the frame callback + requested in the same wl_surface.commit that attaches this + wl_buffer to a surface, then the client is immediately free to + re-use the buffer and its backing storage, and does not need a + second buffer for the next surface content update. Typically + this is possible, when the compositor maintains a copy of the + wl_surface contents, e.g. as a GL texture. This is an important + optimization for GL(ES) compositors with wl_shm clients. + </description> + </event> + </interface> + + + <interface name="wl_data_offer" version="1"> + <description summary="offer to transfer data"> + A wl_data_offer represents a piece of data offered for transfer + by another client (the source client). It is used by the + copy-and-paste and drag-and-drop mechanisms. The offer + describes the different mime types that the data can be + converted to and provides the mechanism for transferring the + data directly from the source client. + </description> + + <request name="accept"> + <description summary="accept one of the offered mime types"> + Indicate that the client can accept the given mime type, or + NULL for not accepted. + + Used for feedback during drag-and-drop. + </description> + + <arg name="serial" type="uint"/> + <arg name="mime_type" type="string" allow-null="true"/> + </request> + + <request name="receive"> + <description summary="request that the data is transferred"> + To transfer the offered data, the client issues this request + and indicates the mime type it wants to receive. The transfer + happens through the passed file descriptor (typically created + with the pipe system call). The source client writes the data + in the mime type representation requested and then closes the + file descriptor. + + The receiving client reads from the read end of the pipe until + EOF and the closes its end, at which point the transfer is + complete. + </description> + <arg name="mime_type" type="string"/> + <arg name="fd" type="fd"/> + </request> + + <request name="destroy" type="destructor"> + <description summary="destroy data offer"> + Destroy the data offer. + </description> + </request> + + <event name="offer"> + <description summary="advertise offered mime type"> + Sent immediately after creating the wl_data_offer object. One + event per offered mime type. + </description> + + <arg name="mime_type" type="string"/> + </event> + </interface> + + <interface name="wl_data_source" version="1"> + <description summary="offer to transfer data"> + The wl_data_source object is the source side of a wl_data_offer. + It is created by the source client in a data transfer and + provides a way to describe the offered data and a way to respond + to requests to transfer the data. + </description> + + <request name="offer"> + <description summary="add an offered mime type"> + This request adds a mime type to the set of mime types + advertised to targets. Can be called several times to offer + multiple types. + </description> + <arg name="mime_type" type="string"/> + </request> + + <request name="destroy" type="destructor"> + <description summary="destroy the data source"> + Destroy the data source. + </description> + </request> + + <event name="target"> + <description summary="a target accepts an offered mime type"> + Sent when a target accepts pointer_focus or motion events. If + a target does not accept any of the offered types, type is NULL. + + Used for feedback during drag-and-drop. + </description> + + <arg name="mime_type" type="string" allow-null="true"/> + </event> + + <event name="send"> + <description summary="send the data"> + Request for data from the client. Send the data as the + specified mime type over the passed file descriptor, then + close it. + </description> + + <arg name="mime_type" type="string"/> + <arg name="fd" type="fd"/> + </event> + + <event name="cancelled"> + <description summary="selection was cancelled"> + This data source has been replaced by another data source. + The client should clean up and destroy this data source. + </description> + </event> + + </interface> + + <interface name="wl_data_device" version="1"> + <description summary="data transfer device"> + There is one wl_data_device per seat which can be obtained + from the global wl_data_device_manager singleton. + + A wl_data_device provides access to inter-client data transfer + mechanisms such as copy-and-paste and drag-and-drop. + </description> + <request name="start_drag"> + <description summary="start drag-and-drop operation"> + This request asks the compositor to start a drag-and-drop + operation on behalf of the client. + + The source argument is the data source that provides the data + for the eventual data transfer. If source is NULL, enter, leave + and motion events are sent only to the client that initiated the + drag and the client is expected to handle the data passing + internally. + + The origin surface is the surface where the drag originates and + the client must have an active implicit grab that matches the + serial. + + The icon surface is an optional (can be NULL) surface that + provides an icon to be moved around with the cursor. Initially, + the top-left corner of the icon surface is placed at the cursor + hotspot, but subsequent wl_surface.attach request can move the + relative position. Attach requests must be confirmed with + wl_surface.commit as usual. + + The current and pending input regions of the icon wl_surface are + cleared, and wl_surface.set_input_region is ignored until the + wl_surface is no longer used as the icon surface. When the use + as an icon ends, the the current and pending input regions + become undefined, and the wl_surface is unmapped. + </description> + <arg name="source" type="object" interface="wl_data_source" allow-null="true"/> + <arg name="origin" type="object" interface="wl_surface"/> + <arg name="icon" type="object" interface="wl_surface" allow-null="true"/> + <arg name="serial" type="uint" summary="serial of the implicit grab on the origin"/> + </request> + + <request name="set_selection"> + <description summary="copy data to the selection"> + This request asks the compositor to set the selection + to the data from the source on behalf of the client. + + To unset the selection, set the source to NULL. + </description> + <arg name="source" type="object" interface="wl_data_source" allow-null="true"/> + <arg name="serial" type="uint" summary="serial of the event that triggered this request"/> + </request> + + <event name="data_offer"> + <description summary="introduce a new wl_data_offer"> + The data_offer event introduces a new wl_data_offer object, + which will subsequently be used in either the + data_device.enter event (for drag-and-drop) or the + data_device.selection event (for selections). Immediately + following the data_device_data_offer event, the new data_offer + object will send out data_offer.offer events to describe the + mime types it offers. + </description> + + <arg name="id" type="new_id" interface="wl_data_offer"/> + </event> + + <event name="enter"> + <description summary="initiate drag-and-drop session"> + This event is sent when an active drag-and-drop pointer enters + a surface owned by the client. The position of the pointer at + enter time is provided by the x an y arguments, in surface + local coordinates. + </description> + + <arg name="serial" type="uint"/> + <arg name="surface" type="object" interface="wl_surface"/> + <arg name="x" type="fixed"/> + <arg name="y" type="fixed"/> + <arg name="id" type="object" interface="wl_data_offer" allow-null="true"/> + </event> + + <event name="leave"> + <description summary="end drag-and-drop session"> + This event is sent when the drag-and-drop pointer leaves the + surface and the session ends. The client must destroy the + wl_data_offer introduced at enter time at this point. + </description> + </event> + + <event name="motion"> + <description summary="drag-and-drop session motion"> + This event is sent when the drag-and-drop pointer moves within + the currently focused surface. The new position of the pointer + is provided by the x an y arguments, in surface local + coordinates. + </description> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="x" type="fixed"/> + <arg name="y" type="fixed"/> + </event> + + <event name="drop"> + <description summary="end drag-and-drag session successfully"> + The event is sent when a drag-and-drop operation is ended + because the implicit grab is removed. + </description> + </event> + + <event name="selection"> + <description summary="advertise new selection"> + The selection event is sent out to notify the client of a new + wl_data_offer for the selection for this device. The + data_device.data_offer and the data_offer.offer events are + sent out immediately before this event to introduce the data + offer object. The selection event is sent to a client + immediately before receiving keyboard focus and when a new + selection is set while the client has keyboard focus. The + data_offer is valid until a new data_offer or NULL is received + or until the client loses keyboard focus. + </description> + <arg name="id" type="object" interface="wl_data_offer" allow-null="true"/> + </event> + </interface> + + <interface name="wl_data_device_manager" version="1"> + <description summary="data transfer interface"> + The wl_data_device_manager is a a singleton global object that + provides access to inter-client data transfer mechanisms such as + copy-and-paste and drag-and-drop. These mechanisms are tied to + a wl_seat and this interface lets a client get a wl_data_device + corresponding to a wl_seat. + </description> + + <request name="create_data_source"> + <description summary="create a new data source"> + Create a new data source. + </description> + <arg name="id" type="new_id" interface="wl_data_source"/> + </request> + + <request name="get_data_device"> + <description summary="create a new data device"> + Create a new data device for a given seat. + </description> + <arg name="id" type="new_id" interface="wl_data_device"/> + <arg name="seat" type="object" interface="wl_seat"/> + </request> + </interface> + + <interface name="wl_shell" version="1"> + <description summary="create desktop-style surfaces"> + This interface is implemented by servers that provide + desktop-style user interfaces. + + It allows clients to associate a wl_shell_surface with + a basic surface. + </description> + + <request name="get_shell_surface"> + <description summary="create a shell surface from a surface"> + Create a shell surface for an existing surface. + + Only one shell surface can be associated with a given surface. + </description> + <arg name="id" type="new_id" interface="wl_shell_surface"/> + <arg name="surface" type="object" interface="wl_surface"/> + </request> + </interface> + + <interface name="wl_shell_surface" version="1"> + + <description summary="desktop-style metadata interface"> + An interface that may be implemented by a wl_surface, for + implementations that provide a desktop-style user interface. + + It provides requests to treat surfaces like toplevel, fullscreen + or popup windows, move, resize or maximize them, associate + metadata like title and class, etc. + + On the server side the object is automatically destroyed when + the related wl_surface is destroyed. On client side, + wl_shell_surface_destroy() must be called before destroying + the wl_surface object. + </description> + + <request name="pong"> + <description summary="respond to a ping event"> + A client must respond to a ping event with a pong request or + the client may be deemed unresponsive. + </description> + <arg name="serial" type="uint" summary="serial of the ping event"/> + </request> + + <request name="move"> + <description summary="start an interactive move"> + Start a pointer-driven move of the surface. + + This request must be used in response to a button press event. + The server may ignore move requests depending on the state of + the surface (e.g. fullscreen or maximized). + </description> + <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/> + <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/> + </request> + + <enum name="resize"> + <description summary="edge values for resizing"> + These values are used to indicate which edge of a surface + is being dragged in a resize operation. The server may + use this information to adapt its behavior, e.g. choose + an appropriate cursor image. + </description> + <entry name="none" value="0"/> + <entry name="top" value="1"/> + <entry name="bottom" value="2"/> + <entry name="left" value="4"/> + <entry name="top_left" value="5"/> + <entry name="bottom_left" value="6"/> + <entry name="right" value="8"/> + <entry name="top_right" value="9"/> + <entry name="bottom_right" value="10"/> + </enum> + + <request name="resize"> + <description summary="start an interactive resize"> + Start a pointer-driven resizing of the surface. + + This request must be used in response to a button press event. + The server may ignore resize requests depending on the state of + the surface (e.g. fullscreen or maximized). + </description> + <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/> + <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/> + <arg name="edges" type="uint" summary="which edge or corner is being dragged"/> + </request> + + <request name="set_toplevel"> + <description summary="make the surface a toplevel surface"> + Map the surface as a toplevel surface. + + A toplevel surface is not fullscreen, maximized or transient. + </description> + </request> + + <enum name="transient"> + <description summary="details of transient behaviour"> + These flags specify details of the expected behaviour + of transient surfaces. Used in the set_transient request. + </description> + <entry name="inactive" value="0x1" summary="do not set keyboard focus"/> + </enum> + + <request name="set_transient"> + <description summary="make the surface a transient surface"> + Map the surface relative to an existing surface. + + The x and y arguments specify the locations of the upper left + corner of the surface relative to the upper left corner of the + parent surface. + + The flags argument controls details of the transient behaviour. + </description> + + <arg name="parent" type="object" interface="wl_surface"/> + <arg name="x" type="int"/> + <arg name="y" type="int"/> + <arg name="flags" type="uint"/> + </request> + + <enum name="fullscreen_method"> + <description summary="different method to set the surface fullscreen"> + Hints to indicate to the compositor how to deal with a conflict + between the dimensions of the surface and the dimensions of the + output. The compositor is free to ignore this parameter. + </description> + <entry name="default" value="0" summary="no preference, apply default policy"/> + <entry name="scale" value="1" summary="scale, preserve the surface's aspect ratio and center on output"/> + <entry name="driver" value="2" summary="switch output mode to the smallest mode that can fit the surface, add black borders to compensate size mismatch"/> + <entry name="fill" value="3" summary="no scaling, center on output and add black borders to compensate size mismatch"/> + </enum> + + <request name="set_fullscreen"> + <description summary="make the surface a fullscreen surface"> + Map the surface as a fullscreen surface. + + If an output parameter is given then the surface will be made + fullscreen on that output. If the client does not specify the + output then the compositor will apply its policy - usually + choosing the output on which the surface has the biggest surface + area. + + The client may specify a method to resolve a size conflict + between the output size and the surface size - this is provided + through the method parameter. + + The framerate parameter is used only when the method is set + to "driver", to indicate the preferred framerate. A value of 0 + indicates that the app does not care about framerate. The + framerate is specified in mHz, that is framerate of 60000 is 60Hz. + + The compositor must reply to this request with a configure event + with the dimensions for the output on which the surface will + be made fullscreen. + </description> + <arg name="method" type="uint"/> + <arg name="framerate" type="uint"/> + <arg name="output" type="object" interface="wl_output" allow-null="true"/> + </request> + + <request name="set_popup"> + <description summary="make the surface a popup surface"> + Map the surface as a popup. + + A popup surface is a transient surface with an added pointer + grab. + + An existing implicit grab will be changed to owner-events mode, + and the popup grab will continue after the implicit grab ends + (i.e. releasing the mouse button does not cause the popup to + be unmapped). + + The popup grab continues until the window is destroyed or a + mouse button is pressed in any other clients window. A click + in any of the clients surfaces is reported as normal, however, + clicks in other clients surfaces will be discarded and trigger + the callback. + </description> + + <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/> + <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/> + <arg name="parent" type="object" interface="wl_surface"/> + <arg name="x" type="int"/> + <arg name="y" type="int"/> + <arg name="flags" type="uint"/> + </request> + + <request name="set_maximized"> + <description summary="make the surface a maximized surface"> + Map the surface as a maximized surface. + + If an output parameter is given then the surface will be + maximized on that output. If the client does not specify the + output then the compositor will apply its policy - usually + choosing the output on which the surface has the biggest surface + area. + + The compositor will reply with a configure event telling + the expected new surface size. The operation is completed + on the next buffer attach to this surface. + + A maximized surface typically fills the entire output it is + bound to, except for desktop element such as panels. This is + the main difference between a maximized shell surface and a + fullscreen shell surface. + + The details depend on the compositor implementation. + </description> + <arg name="output" type="object" interface="wl_output" allow-null="true"/> + </request> + + <request name="set_title"> + <description summary="set surface title"> + Set a short title for the surface. + + This string may be used to identify the surface in a task bar, + window list, or other user interface elements provided by the + compositor. + + The string must be encoded in UTF-8. + </description> + <arg name="title" type="string"/> + </request> + + <request name="set_class"> + <description summary="set surface class"> + Set a class for the surface. + + The surface class identifies the general class of applications + to which the surface belongs. A common convention is to use + the file name (full path if non-standard location) of the + applications .desktop file as the class. + </description> + <arg name="class_" type="string"/> + </request> + + <event name="ping"> + <description summary="ping client"> + Ping a client to check if it is receiving events and sending + requests. A client is expected to reply with a pong request. + </description> + <arg name="serial" type="uint"/> + </event> + + <event name="configure"> + <description summary="suggest resize"> + The configure event asks the client to resize its surface. + + The size is a hint, in the sense that the client is free to + ignore it if it doesn't resize, pick a smaller size (to + satisfy aspect ratio or resize in steps of NxM pixels). + + The edges parameter provides a hint about how the surface + was resized. The client may use this information to decide + how to adjust its content to the new size (e.g. a scrolling + area might adjust its content position to leave the viewable + content unmoved). + + The client is free to dismiss all but the last configure + event it received. + </description> + + <arg name="edges" type="uint"/> + <arg name="width" type="int"/> + <arg name="height" type="int"/> + </event> + + <event name="popup_done"> + <description summary="popup interaction is done"> + The popup_done event is sent out when a popup grab is broken, + that is, when the users clicks a surface that doesn't belong + to the client owning the popup surface. + </description> + </event> + </interface> + + <interface name="wl_surface" version="2"> + <description summary="an onscreen surface"> + A surface is a rectangular area that is displayed on the screen. + It has a location, size and pixel contents. + + Surfaces are also used for some special purposes, e.g. as + cursor images for pointers, drag icons, etc. + </description> + + <request name="destroy" type="destructor"> + <description summary="delete surface"> + Deletes the surface and invalidates its object ID. + </description> + </request> + + <request name="attach"> + <description summary="set the surface contents"> + Set a buffer as the content of this surface. + + The x and y arguments specify the location of the new pending + buffer's upper left corner, relative to the current buffer's + upper left corner. In other words, the x and y, and the width + and height of the wl_buffer together define in which directions + the surface's size changes. + + Surface contents are double-buffered state, see wl_surface.commit. + + The initial surface contents are void; there is no content. + wl_surface.attach assigns the given wl_buffer as the pending + wl_buffer. wl_surface.commit makes the pending wl_buffer the new + surface contents, and the size of the surface becomes the size of + the wl_buffer, as described above. After commit, there is no + pending buffer until the next attach. + + Committing a pending wl_buffer allows the compositor to read the + pixels in the wl_buffer. The compositor may access the pixels at + any time after the wl_surface.commit request. When the compositor + will not access the pixels anymore, it will send the + wl_buffer.release event. Only after receiving wl_buffer.release, + the client may re-use the wl_buffer. A wl_buffer that has been + attached and then replaced by another attach instead of committed + will not receive a release event, and is not used by the + compositor. + + Destroying the wl_buffer after wl_buffer.release does not change + the surface contents. However, if the client destroys the + wl_buffer before receiving wl_buffer.release, the surface + contents become undefined immediately. + + Only if wl_surface.attach is sent with a NULL wl_buffer, the + following wl_surface.commit will remove the surface content. + </description> + + <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"/> + <arg name="x" type="int"/> + <arg name="y" type="int"/> + </request> + + <request name="damage"> + <description summary="mark part of the surface damaged"> + This request is used to describe the regions where the pending + buffer is different from the current surface contents, and where + the surface therefore needs to be repainted. The pending buffer + must be set by wl_surface.attach before sending damage. The + compositor ignores the parts of the damage that fall outside of + the surface. + + Damage is double-buffered state, see wl_surface.commit. + + The initial value for pending damage is empty: no damage. + wl_surface.damage adds pending damage: the new pending damage + is the union of old pending damage and the given rectangle. + + wl_surface.commit assigns pending damage as the current damage, + and clears pending damage. The server will clear the current + damage as it repaints the surface. + </description> + + <arg name="x" type="int"/> + <arg name="y" type="int"/> + <arg name="width" type="int"/> + <arg name="height" type="int"/> + </request> + + <request name="frame"> + <description summary="request repaint feedback"> + Request notification when the next frame is displayed. Useful + for throttling redrawing operations, and driving animations. + The frame request will take effect on the next wl_surface.commit. + The notification will only be posted for one frame unless + requested again. + + A server should avoid signalling the frame callbacks if the + surface is not visible in any way, e.g. the surface is off-screen, + or completely obscured by other opaque surfaces. + + A client can request a frame callback even without an attach, + damage, or any other state changes. wl_surface.commit triggers a + display update, so the callback event will arrive after the next + output refresh where the surface is visible. + + The object returned by this request will be destroyed by the + compositor after the callback is fired and as such the client must not + attempt to use it after that point. + </description> + + <arg name="callback" type="new_id" interface="wl_callback"/> + </request> + + <request name="set_opaque_region"> + <description summary="set opaque region"> + This request sets the region of the surface that contains + opaque content. + + The opaque region is an optimization hint for the compositor + that lets it optimize out redrawing of content behind opaque + regions. Setting an opaque region is not required for correct + behaviour, but marking transparent content as opaque will result + in repaint artifacts. + + The compositor ignores the parts of the opaque region that fall + outside of the surface. + + Opaque region is double-buffered state, see wl_surface.commit. + + wl_surface.set_opaque_region changes the pending opaque region. + wl_surface.commit copies the pending region to the current region. + Otherwise, the pending and current regions are never changed. + + The initial value for opaque region is empty. Setting the pending + opaque region has copy semantics, and the wl_region object can be + destroyed immediately. A NULL wl_region causes the pending opaque + region to be set to empty. + </description> + + <arg name="region" type="object" interface="wl_region" allow-null="true"/> + </request> + + <request name="set_input_region"> + <description summary="set input region"> + This request sets the region of the surface that can receive + pointer and touch events. + + Input events happening outside of this region will try the next + surface in the server surface stack. The compositor ignores the + parts of the input region that fall outside of the surface. + + Input region is double-buffered state, see wl_surface.commit. + + wl_surface.set_input_region changes the pending input region. + wl_surface.commit copies the pending region to the current region. + Otherwise the pending and current regions are never changed, + except cursor and icon surfaces are special cases, see + wl_pointer.set_cursor and wl_data_device.start_drag. + + The initial value for input region is infinite. That means the + whole surface will accept input. Setting the pending input region + has copy semantics, and the wl_region object can be destroyed + immediately. A NULL wl_region causes the input region to be set + to infinite. + </description> + + <arg name="region" type="object" interface="wl_region" allow-null="true"/> + </request> + + <request name="commit"> + <description summary="commit pending surface state"> + Surface state (input, opaque, and damage regions, attached buffers, + etc.) is double-buffered. Protocol requests modify the pending + state, as opposed to current state in use by the compositor. Commit + request atomically applies all pending state, replacing the current + state. After commit, the new pending state is as documented for each + related request. + + On commit, a pending wl_buffer is applied first, all other state + second. This means that all coordinates in double-buffered state are + relative to the new wl_buffer coming into use, except for + wl_surface.attach itself. If there is no pending wl_buffer, the + coordinates are relative to the current surface contents. + + All requests that need a commit to become effective are documented + to affect double-buffered state. + + Other interfaces may add further double-buffered surface state. + </description> + </request> + + <event name="enter"> + <description summary="surface enters an output"> + This is emitted whenever a surface's creation, movement, or resizing + results in some part of it being within the scanout region of an + output. + + Note that a surface may be overlapping with zero or more outputs. + </description> + <arg name="output" type="object" interface="wl_output"/> + </event> + + <event name="leave"> + <description summary="surface leaves an output"> + This is emitted whenever a surface's creation, movement, or resizing + results in it no longer having any part of it within the scanout region + of an output. + </description> + <arg name="output" type="object" interface="wl_output"/> + </event> + + <!-- Version 2 additions --> + + <request name="set_buffer_transform" since="2"> + <description summary="sets the buffer transformation"> + This request sets an optional transformation on how the compositor + interprets the contents of the buffer attached to the surface. The + accepted values for the transform parameter are the values for + wl_output.transform. + + Buffer transform is double-buffered state, see wl_surface.commit. + + A newly created surface has its buffer transformation set to normal. + + The purpose of this request is to allow clients to render content + according to the output transform, thus permiting the compositor to + use certain optimizations even if the display is rotated. Using + hardware overlays and scanning out a client buffer for fullscreen + surfaces are examples of such optmizations. Those optimizations are + highly dependent on the compositor implementation, so the use of this + request should be considered on a case-by-case basis. + + Note that if the transform value includes 90 or 270 degree rotation, + the width of the buffer will become the surface height and the height + of the buffer will become the surface width. + </description> + <arg name="transform" type="int"/> + </request> + </interface> + + <interface name="wl_seat" version="1"> + <description summary="group of input devices"> + A seat is a group of keyboards, pointer and touch devices. This + object is published as a global during start up, or when such a + device is hot plugged. A seat typically has a pointer and + maintains a keyboard focus and a pointer focus. + </description> + + <enum name="capability"> + <description summary="seat capability bitmask"> + This is a bitmask of capabilities this seat has; if a member is + set, then it is present on the seat. + </description> + <entry name="pointer" value="1" summary="The seat has pointer devices"/> + <entry name="keyboard" value="2" summary="The seat has one or more keyboards"/> + <entry name="touch" value="4" summary="The seat has touch devices"/> + </enum> + + <event name="capabilities"> + <description summary="seat capabilities changed"> + This is emitted whenever a seat gains or loses the pointer, + keyboard or touch capabilities. The argument is a capability + enum containing the complete set of capabilities this seat has. + </description> + <arg name="capabilities" type="uint"/> + </event> + + <request name="get_pointer"> + <description summary="return pointer object"> + The ID provided will be initialized to the wl_pointer interface + for this seat. + + This request only takes effect if the seat has the pointer + capability. + </description> + <arg name="id" type="new_id" interface="wl_pointer"/> + </request> + + <request name="get_keyboard"> + <description summary="return keyboard object"> + The ID provided will be initialized to the wl_keyboard interface + for this seat. + + This request only takes effect if the seat has the keyboard + capability. + </description> + <arg name="id" type="new_id" interface="wl_keyboard"/> + </request> + + <request name="get_touch"> + <description summary="return touch object"> + The ID provided will be initialized to the wl_touch interface + for this seat. + + This request only takes effect if the seat has the touch + capability. + </description> + <arg name="id" type="new_id" interface="wl_touch"/> + </request> + </interface> + + <interface name="wl_pointer" version="1"> + <description summary="pointer input device"> + The wl_pointer interface represents one or more input devices, + such as mice, which control the pointer location and pointer_focus + of a seat. + + The wl_pointer interface generates motion, enter and leave + events for the surfaces that the pointer is located over, + and button and axis events for button presses, button releases + and scrolling. + </description> + + <request name="set_cursor"> + <description summary="set the pointer surface"> + Set the pointer surface, i.e., the surface that contains the + pointer image (cursor). This request only takes effect if the pointer + focus for this device is one of the requesting client's surfaces + or the surface parameter is the current pointer surface. If + there was a previous surface set with this request it is + replaced. If surface is NULL, the pointer image is hidden. + + The parameters hotspot_x and hotspot_y define the position of + the pointer surface relative to the pointer location. Its + top-left corner is always at (x, y) - (hotspot_x, hotspot_y), + where (x, y) are the coordinates of the pointer location. + + On surface.attach requests to the pointer surface, hotspot_x + and hotspot_y are decremented by the x and y parameters + passed to the request. Attach must be confirmed by + wl_surface.commit as usual. + + The hotspot can also be updated by passing the currently set + pointer surface to this request with new values for hotspot_x + and hotspot_y. + + The current and pending input regions of the wl_surface are + cleared, and wl_surface.set_input_region is ignored until the + wl_surface is no longer used as the cursor. When the use as a + cursor ends, the current and pending input regions become + undefined, and the wl_surface is unmapped. + </description> + + <arg name="serial" type="uint" summary="serial of the enter event"/> + <arg name="surface" type="object" interface="wl_surface" allow-null="true"/> + <arg name="hotspot_x" type="int" summary="x coordinate in surface-relative coordinates"/> + <arg name="hotspot_y" type="int" summary="y coordinate in surface-relative coordinates"/> + </request> + + <event name="enter"> + <description summary="enter event"> + Notification that this seat's pointer is focused on a certain + surface. + + When an seat's focus enters a surface, the pointer image + is undefined and a client should respond to this event by setting + an appropriate pointer image with the set_cursor request. + </description> + + <arg name="serial" type="uint"/> + <arg name="surface" type="object" interface="wl_surface"/> + <arg name="surface_x" type="fixed" summary="x coordinate in surface-relative coordinates"/> + <arg name="surface_y" type="fixed" summary="y coordinate in surface-relative coordinates"/> + </event> + + <event name="leave"> + <description summary="leave event"> + Notification that this seat's pointer is no longer focused on + a certain surface. + + The leave notification is sent before the enter notification + for the new focus. + </description> + <arg name="serial" type="uint"/> + <arg name="surface" type="object" interface="wl_surface"/> + </event> + + <event name="motion"> + <description summary="pointer motion event"> + Notification of pointer location change. The arguments + surface_x and surface_y are the location relative to the + focused surface. + </description> + + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="surface_x" type="fixed" summary="x coordinate in surface-relative coordinates"/> + <arg name="surface_y" type="fixed" summary="y coordinate in surface-relative coordinates"/> + </event> + + <enum name="button_state"> + <description summary="physical button state"> + Describes the physical state of a button which provoked the button + event. + </description> + <entry name="released" value="0" summary="The button is not pressed"/> + <entry name="pressed" value="1" summary="The button is pressed"/> + </enum> + + <event name="button"> + <description summary="pointer button event"> + Mouse button click and release notifications. + + The location of the click is given by the last motion or + enter event. + The time argument is a timestamp with millisecond + granularity, with an undefined base. + </description> + + <arg name="serial" type="uint"/> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="button" type="uint"/> + <arg name="state" type="uint"/> + </event> + + <enum name="axis"> + <description summary="axis types"> + Describes the axis types of scroll events. + </description> + <entry name="vertical_scroll" value="0"/> + <entry name="horizontal_scroll" value="1"/> + </enum> + + <event name="axis"> + <description summary="axis event"> + Scroll and other axis notifications. + + For scroll events (vertical and horizontal scroll axes), the + value parameter is the length of a vector along the specified + axis in a coordinate space identical to those of motion events, + representing a relative movement along the specified axis. + + For devices that support movements non-parallel to axes multiple + axis events will be emitted. + + When applicable, for example for touch pads, the server can + choose to emit scroll events where the motion vector is + equivalent to a motion event vector. + + When applicable, clients can transform its view relative to the + scroll distance. + </description> + + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="axis" type="uint"/> + <arg name="value" type="fixed"/> + </event> + </interface> + + <interface name="wl_keyboard" version="1"> + <description summary="keyboard input device"> + The wl_keyboard interface represents one or more keyboards + associated with a seat. + </description> + + <enum name="keymap_format"> + <description summary="keyboard mapping format"> + This specifies the format of the keymap provided to the + client with the wl_keyboard.keymap event. + </description> + <entry name="xkb_v1" value="1" summary="libxkbcommon compatible"/> + </enum> + + <event name="keymap"> + <description summary="keyboard mapping"> + This event provides a file descriptor to the client which can be + memory-mapped to provide a keyboard mapping description. + </description> + <arg name="format" type="uint"/> + <arg name="fd" type="fd"/> + <arg name="size" type="uint"/> + </event> + + <event name="enter"> + <description summary="enter event"> + Notification that this seat's keyboard focus is on a certain + surface. + </description> + <arg name="serial" type="uint"/> + <arg name="surface" type="object" interface="wl_surface"/> + <arg name="keys" type="array" summary="the currently pressed keys"/> + </event> + + <event name="leave"> + <description summary="leave event"> + Notification that this seat's keyboard focus is no longer on + a certain surface. + + The leave notification is sent before the enter notification + for the new focus. + </description> + <arg name="serial" type="uint"/> + <arg name="surface" type="object" interface="wl_surface"/> + </event> + + <enum name="key_state"> + <description summary="physical key state"> + Describes the physical state of a key which provoked the key event. + </description> + <entry name="released" value="0" summary="key is not pressed"/> + <entry name="pressed" value="1" summary="key is pressed"/> + </enum> + + <event name="key"> + <description summary="key event"> + A key was pressed or released. + The time argument is a timestamp with millisecond + granularity, with an undefined base. + </description> + + <arg name="serial" type="uint"/> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="key" type="uint"/> + <arg name="state" type="uint"/> + </event> + + <event name="modifiers"> + <description summary="modifier and group state"> + Notifies clients that the modifier and/or group state has + changed, and it should update its local state. + </description> + + <arg name="serial" type="uint"/> + <arg name="mods_depressed" type="uint"/> + <arg name="mods_latched" type="uint"/> + <arg name="mods_locked" type="uint"/> + <arg name="group" type="uint"/> + </event> + </interface> + + <interface name="wl_touch" version="1"> + <description summary="touchscreen input device"> + The wl_touch interface represents a touchscreen + associated with a seat. + + Touch interactions can consist of one or more contacts. + For each contact, a series of events is generated, starting + with a down event, followed by zero or more motion events, + and ending with an up event. Events relating to the same + contact point can be identified by the ID of the sequence. + </description> + + <event name="down"> + <description summary="touch down event and beginning of a touch sequence"> + A new touch point has appeared on the surface. This touch point is + assigned a unique @id. Future events from this touchpoint reference + this ID. The ID ceases to be valid after a touch up event and may be + re-used in the future. + </description> + <arg name="serial" type="uint"/> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="surface" type="object" interface="wl_surface"/> + <arg name="id" type="int" summary="the unique ID of this touch point"/> + <arg name="x" type="fixed" summary="x coordinate in surface-relative coordinates"/> + <arg name="y" type="fixed" summary="y coordinate in surface-relative coordinates"/> + </event> + + <event name="up"> + <description summary="end of a touch event sequence"> + The touch point has disappeared. No further events will be sent for + this touchpoint and the touch point's ID is released and may be + re-used in a future touch down event. + </description> + <arg name="serial" type="uint"/> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="id" type="int" summary="the unique ID of this touch point"/> + </event> + + <event name="motion"> + <description summary="update of touch point coordinates"> + A touchpoint has changed coordinates. + </description> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="id" type="int" summary="the unique ID of this touch point"/> + <arg name="x" type="fixed" summary="x coordinate in surface-relative coordinates"/> + <arg name="y" type="fixed" summary="y coordinate in surface-relative coordinates"/> + </event> + + <event name="frame"> + <description summary="end of touch frame event"> + Indicates the end of a contact point list. + </description> + </event> + + <event name="cancel"> + <description summary="touch session cancelled"> + Sent if the compositor decides the touch stream is a global + gesture. No further events are sent to the clients from that + particular gesture. Touch cancellation applies to all touch points + currently active on this client's surface. The client is + responsible for finalizing the touch points, future touch points on + this surface may re-use the touch point ID. + </description> + </event> + </interface> + + <interface name="wl_output" version="1"> + <description summary="compositor output region"> + An output describes part of the compositor geometry. The + compositor works in the 'compositor coordinate system' and an + output corresponds to rectangular area in that space that is + actually visible. This typically corresponds to a monitor that + displays part of the compositor space. This object is published + as global during start up, or when a monitor is hotplugged. + </description> + + <enum name="subpixel"> + <description summary="subpixel geometry information"> + This enumeration describes how the physical + pixels on an output are layed out. + </description> + <entry name="unknown" value="0"/> + <entry name="none" value="1"/> + <entry name="horizontal_rgb" value="2"/> + <entry name="horizontal_bgr" value="3"/> + <entry name="vertical_rgb" value="4"/> + <entry name="vertical_bgr" value="5"/> + </enum> + + <enum name="transform"> + <description summary="transform from framebuffer to output"> + This describes the transform that a compositor will apply to a + surface to compensate for the rotation or mirroring of an + output device. + + The flipped values correspond to an initial flip around a + vertical axis followed by rotation. + + The purpose is mainly to allow clients render accordingly and + tell the compositor, so that for fullscreen surfaces, the + compositor will still be able to scan out directly from client + surfaces. + </description> + + <entry name="normal" value="0"/> + <entry name="90" value="1"/> + <entry name="180" value="2"/> + <entry name="270" value="3"/> + <entry name="flipped" value="4"/> + <entry name="flipped_90" value="5"/> + <entry name="flipped_180" value="6"/> + <entry name="flipped_270" value="7"/> + </enum> + + <event name="geometry"> + <description summary="properties of the output"> + The geometry event describes geometric properties of the output. + The event is sent when binding to the output object and whenever + any of the properties change. + </description> + <arg name="x" type="int" + summary="x position within the global compositor space"/> + <arg name="y" type="int" + summary="y position within the global compositor space"/> + <arg name="physical_width" type="int" + summary="width in millimeters of the output"/> + <arg name="physical_height" type="int" + summary="height in millimeters of the output"/> + <arg name="subpixel" type="int" + summary="subpixel orientation of the output"/> + <arg name="make" type="string" + summary="textual description of the manufacturer"/> + <arg name="model" type="string" + summary="textual description of the model"/> + <arg name="transform" type="int" + summary="transform that maps framebuffer to output"/> + </event> + + <enum name="mode"> + <description summary="mode information"> + These flags describe properties of an output mode. + They are used in the flags bitfield of the mode event. + </description> + <entry name="current" value="0x1" + summary="indicates this is the current mode"/> + <entry name="preferred" value="0x2" + summary="indicates this is the preferred mode"/> + </enum> + + <event name="mode"> + <description summary="advertise available modes for the output"> + The mode event describes an available mode for the output. + + The event is sent when binding to the output object and there + will always be one mode, the current mode. The event is sent + again if an output changes mode, for the mode that is now + current. In other words, the current mode is always the last + mode that was received with the current flag set. + </description> + <arg name="flags" type="uint" summary="bitfield of mode flags"/> + <arg name="width" type="int" summary="width of the mode in pixels"/> + <arg name="height" type="int" summary="height of the mode in pixels"/> + <arg name="refresh" type="int" summary="vertical refresh rate in mHz"/> + </event> + </interface> + + <interface name="wl_region" version="1"> + <description summary="region interface"> + A region object describes an area. + + Region objects are used to describe the opaque and input + regions of a surface. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy region"> + Destroy the region. This will invalidate the object ID. + </description> + </request> + + <request name="add"> + <description summary="add rectangle to region"> + Add the specified rectangle to the region. + </description> + + <arg name="x" type="int"/> + <arg name="y" type="int"/> + <arg name="width" type="int"/> + <arg name="height" type="int"/> + </request> + + <request name="subtract"> + <description summary="subtract rectangle from region"> + Subtract the specified rectangle from the region. + </description> + + <arg name="x" type="int"/> + <arg name="y" type="int"/> + <arg name="width" type="int"/> + <arg name="height" type="int"/> + </request> + + </interface> + +</protocol> |