<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.
+ is used for internal Wayland protocol features.
</description>
- <request name="bind">
- <description summary="bind an object to the display">
- Binds a new, client created object to the server using @name as
- the identifier.
- </description>
- <arg name="name" type="uint" summary="unique number id for object"/>
- <arg name="interface" type="string"/>
- <arg name="version" type="uint"/>
- <arg name="id" type="new_id" interface="wl_object"/>
- </request>
<request name="sync">
<description summary="asynchronous roundtrip">
- The sync request asks the server to invoke the 'done' request
+ The sync request asks the server to emit the 'done' event
on the provided wl_callback object. Since requests are
handled in-order, this can be used as a barrier to ensure all
previous requests have been handled.
<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.
+ 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" interface="wl_object"/>
+ <arg name="object_id" type="object"/>
<arg name="code" type="uint"/>
<arg name="message" type="string"/>
</event>
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 provides
+ 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 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 @name as
+ the identifier.
+ </description>
+ <arg name="name" type="uint" summary="unique number id for object"/>
+ <arg name="id" type="new_id"/>
+ </request>
+
<event name="global">
<description summary="announce global object">
- Notify the client of global objects. These are objects that
- are created by the server. Globals are published on the
- initial client connection sequence, upon device hotplugs,
- device disconnects, reconfiguration or other events. 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.
+ Notify the client of global objects.
</description>
<arg name="name" type="uint"/>
<arg name="interface" type="string"/>
<event name="global_remove">
<description summary="announce removal of global object">
- Notify the client of removed global objects.
+ Notify the client of removed global objects. This event
+ notifies the client that the global identifies 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>
-
- <event name="delete_id">
- <description summary="acknowledge object id deletion">
- Server has deleted the id and client can now reuse it.
- </description>
- <arg name="id" type="uint" />
- </event>
</interface>
<interface name="wl_callback" version="1">
<event name="done">
- <arg name="time" type="uint"/>
+ <arg name="serial" type="uint"/>
</event>
</interface>
</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.
+ The objects will 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 wl_buffer from pool">
+ Create a wl_buffer from the pool. The buffer is created a
+ 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 pool.
+ </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 fd passed when the pool was creating but
+ using the new size.
+ </description>
+
+ <arg name="size" type="int"/>
+ </request>
</interface>
<interface name="wl_shm" version="1">
<entry name="xrgb8888" value="1"/>
</enum>
- <request name="create_buffer">
- <description summary="create a wl_buffer">
- Transfer a shm buffer to the server. The allocated buffer
- would include at least 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 format describe the respective properties of the pixel
- data contained in the buffer.
+ <request name="create_pool">
+ <description summary="create a shm pool">
+ This creates wl_shm_pool object, which can be used to create
+ shared memory based wl_buffer objects. The server will mmap
+ size bytes of the passed fd, to use as backing memory for then
+ pool.
</description>
- <arg name="id" type="new_id" interface="wl_buffer"/>
+ <arg name="id" type="new_id" interface="wl_shm_pool"/>
<arg name="fd" type="fd"/>
- <arg name="width" type="int"/>
- <arg name="height" type="int"/>
- <arg name="stride" type="uint"/>
- <arg name="format" type="uint"/>
+ <arg name="size" type="int"/>
</request>
<event name="format">
<interface name="wl_buffer" version="1">
<description summary="content for a wl_surface">
- A buffer provides the content for a wl_surface. Buffers are
+ 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
+ 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
+ updates the contents is defined by the buffer factory interface.
</description>
- <request name="damage">
- <description summary="mark part of the buffer damaged">
- Notify the server that the specified area of the buffers
- contents have changed. To describe a more complicated area of
- damage, break down the region into rectangles and use this
- request several times.
- </description>
-
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
- <arg name="width" type="int"/>
- <arg name="height" type="int"/>
- </request>
-
<request name="destroy" type="destructor">
<description summary="destroy a buffer">
- Destroy a buffer. This will invalidate the object id.
+ 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 an attached buffer is no longer used by the compositor.
+ 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. Use for feedback during drag and drop.
</description>
- <arg name="time" type="uint"/>
- <arg name="type" type="string"/>
+ <arg name="serial" type="uint"/>
+ <arg name="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 fd (typically a pipe(7) file
+ descriptor). The source client writes the data in the
+ mime-type representation requested and then closes the fd.
+ 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>
</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
a target does not accept any of the offered types, type is NULL.
</description>
- <arg name="mime_type" type="string"/>
+ <arg name="mime_type" type="string" allow-null="true"/>
</event>
<event name="send">
<event name="cancelled">
<description summary="selection was cancelled">
- Another selection became active.
+ This data source has been replaced by another data source.
+ The client should clean up and destroy this data source.
</description>
</event>
<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. The origin surface is the surface where the drag
- originates and the client must have an active implicit grab
- that matches the timestamp. The icon surface is an optional
- (can be nil) 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
- surface.attach request can move the relative position.
- </description>
- <arg name="source" type="object" interface="wl_data_source"/>
+ 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 nil) 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"/>
- <arg name="time" type="uint"/>
+ <arg name="icon" type="object" interface="wl_surface" allow-null="true"/>
+ <arg name="serial" type="uint"/>
</request>
<request name="set_selection">
- <arg name="source" type="object" interface="wl_data_source"/>
- <arg name="time" type="uint"/>
+ <arg name="source" type="object" interface="wl_data_source" allow-null="true"/>
+ <arg name="serial" type="uint"/>
</request>
<event name="data_offer">
</event>
<event name="enter">
- <arg name="time" type="uint"/>
+ <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="int"/>
- <arg name="y" type="int"/>
- <arg name="id" type="object" interface="wl_data_offer"/>
+ <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"/>
+ <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"/>
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
+ <arg name="x" type="fixed"/>
+ <arg name="y" type="fixed"/>
</event>
<event name="drop"/>
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"/>
+ <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">
<arg name="id" type="new_id" interface="wl_data_source"/>
</request>
<request name="get_data_device">
<arg name="id" type="new_id" interface="wl_data_device"/>
- <arg name="input_device" type="object" interface="wl_input_device"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
</request>
</interface>
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"/>
+ </request>
+
<request name="move">
- <arg name="input_device" type="object" interface="wl_input_device"/>
- <arg name="time" type="uint"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ <arg name="serial" type="uint"/>
</request>
<enum name="resize">
</enum>
<request name="resize">
- <arg name="input_device" type="object" interface="wl_input_device"/>
- <arg name="time" type="uint"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ <arg name="serial" type="uint"/>
<arg name="edges" type="uint"/>
</request>
</description>
</request>
+ <enum name="transient">
+ <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
that relative position during moves.
</description>
- <arg name="parent" type="object" interface="wl_shell_surface"/>
+ <arg name="parent" type="object" interface="wl_surface"/>
<arg name="x" type="int"/>
<arg name="y" type="int"/>
<arg name="flags" type="uint"/>
<request name="set_fullscreen">
<description summary="make the surface a fullscreen surface">
- Map the surface as a fullscreen surface. On the output the
- surface is assigned to. The client can use different fulllscreen
- method to fix the size mismatch issue: default, scale, driver
- and fill. And the framerate parameter is used for "driver" method,
- to indicate the preferred framerate. framerate=0 means that the
- app does not care about framerate
+ 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
+ fullscreen_method parameter.
+
+ The framerate parameter is used only when the fullscreen_method is set
+ to "driver", to indicate the preferred framerate. framerate=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"/>
+ <arg name="output" type="object" interface="wl_output" allow-null="true"/>
</request>
<enum name="fullscreen_method">
<description summary="different method to set the surface fullscreen">
- Hints to indicate compositor how to deal with this fullscreen surface.
- "default" means the client has no preference on fullscreen
- behavior, policies are determined by compositor.
- "scale" means the client prefers scaling by the compositor.
- Scaling would always preserve surface's aspect ratio.
- And the surface is centered.
- "driver" means the client wants to switch video mode to the
- smallest mode that can fit the client buffer. If the
- sizes do not match, black borders are added.
- "fill" means the client wants to add blackborders to the
- surface. This would be preferring 1:1 pixel mapping
- in the monitor native video mode. The surface is
- centered.
+ Hints to indicate compositor how to deal with a conflict between the
+ dimensions for the surface and the dimensions of the output. As a hint
+ the compositor is free to ignore this parameter.
+
+ "default" The client has no preference on fullscreen behavior,
+ policies are determined by compositor.
+
+ "scale" The client prefers scaling by the compositor. Scaling would
+ always preserve surface's aspect ratio with surface centered on the
+ output
+
+ "driver" The client wants to switch video mode to the smallest mode
+ that can fit the client buffer. If the sizes do not match the
+ compositor must add black borders.
+
+ "fill" The surface is centered on the output on the screen with no
+ scaling. If the surface is of insufficient size the compositor must
+ add black borders.
</description>
<entry name="default" value="0"/>
<entry name="scale" value="1"/>
inside or outside the surface?
</description>
- <arg name="input_device" type="object" interface="wl_input_device"/>
- <arg name="time" type="uint"/>
- <arg name="parent" type="object" interface="wl_shell_surface"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ <arg name="serial" type="uint"/>
+ <arg name="parent" type="object" interface="wl_surface"/>
<arg name="x" type="int"/>
<arg name="y" type="int"/>
<arg name="flags" type="uint"/>
to, except the panel area. This is the main difference between
a maximized shell surface and a fullscreen shell surface.
</description>
- <arg name="output" type="object" interface="wl_output"/>
+ <arg name="output" type="object" interface="wl_output" allow-null="true"/>
</request>
+ <request name="set_title">
+ <description summary="set surface title">
+ </description>
+ <arg name="title" type="string"/>
+ </request>
+
+ <request name="set_class">
+ <description summary="set surface class">
+ The surface class identifies the general class of applications
+ to which the surface belongs. The class is the file name of
+ the applications .desktop file (absolute path if non-standard
+ location).
+ </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 ration or resize in steps of NxM pixels). The
+ satisfy aspect ratio or resize in steps of NxM pixels). The
client is free to dismiss all but the last configure event it
received.
</description>
- <arg name="time" type="uint"/>
<arg name="edges" type="uint"/>
<arg name="width" type="int"/>
<arg name="height" type="int"/>
<request name="attach">
<description summary="set the surface contents">
- Copy the contents of a buffer into this surface. The x and y
- arguments specify the location of the new buffers upper left
- corner, relative to the old buffers upper left corner.
+ Set the contents of a buffer into 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 applies the pending wl_buffer as the new
+ surface contents, and the size of the surface becomes the size of
+ the wl_buffer. The wl_buffer is also kept as pending, until
+ changed by wl_surface.attach or the wl_buffer is destroyed.
+
+ 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, even if the wl_buffer is still pending for the
+ next commit. In such case, the next commit 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 nil wl_buffer, the
+ following wl_surface.commit will remove the surface content.
</description>
- <arg name="buffer" type="object" interface="wl_buffer"/>
+ <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">
- After attaching a new buffer, this request is used to describe
- the regions where the new buffer is different from the
- previous buffer and needs to be repainted. Coordinates are
- relative to the new buffer.
+ This request is used to describe the regions where the pending
+ buffer (or if pending buffer is none, the current buffer as updated
+ in-place) on the next wl_surface.commit will be different from the
+ current buffer, and needs to be repainted. The pending buffer can be
+ set by wl_surface.attach. 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"/>
<request name="frame">
<description summary="request repaint feedback">
- Request notification when the next frame is displayed. Useful
+ 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.
</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 nil 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
+ nil 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 the pending wl_buffer is none, 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.
+ </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>
</interface>
- <interface name="wl_input_device" version="1">
- <description summary="input device group">
- A group of keyboards and pointer devices (mice, for
- example). This object is published as a global during start up,
- or when such a device is hot plugged. A input_device group
- typically has a pointer and maintains a keyboard_focus and a
- pointer_focus.
+ <interface name="wl_seat" version="1">
+ <description summary="seat">
+ A group of keyboards, pointer (mice, for example) 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>
- <request name="attach">
- <description summary="set the pointer image">
- Set the pointer's image. This request only takes effect if
- the pointer focus for this device is one of the requesting
- clients surfaces.
+ <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="wl_pointer"/>
+ <entry name="keyboard" value="2" summary="wl_keyboard"/>
+ <entry name="touch" value="4" summary="wl_touch"/>
+ </enum>
- <arg name="time" type="uint"/>
- <arg name="buffer" type="object" interface="wl_buffer"/>
+
+ <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 wl_seat_caps_mask
+ 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.
+ </description>
+ <arg name="id" type="new_id" interface="wl_pointer"/>
+ </request>
+
+ <request name="get_keyboard">
+ <description summary="return pointer object">
+ The ID provided will be initialized to the wl_keyboard interface
+ for this seat.
+ </description>
+ <arg name="id" type="new_id" interface="wl_keyboard"/>
+ </request>
+
+ <request name="get_touch">
+ <description summary="return pointer object">
+ The ID provided will be initialized to the wl_touch interface
+ for this seat.
+ </description>
+ <arg name="id" type="new_id" interface="wl_touch"/>
+ </request>
+ </interface>
+
+ <interface name="wl_pointer" version="1">
+ <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"/>
+ <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
<arg name="hotspot_x" type="int"/>
<arg name="hotspot_y" type="int"/>
</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.
+ </description>
+
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ <arg name="surface_x" type="fixed"/>
+ <arg name="surface_y" type="fixed"/>
+ </event>
+
+ <event name="leave">
+ <description summary="leave event">
+ </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_[xy]
</description>
<arg name="time" type="uint"/>
- <arg name="surface_x" type="int"/>
- <arg name="surface_y" type="int"/>
+ <arg name="surface_x" type="fixed"/>
+ <arg name="surface_y" type="fixed"/>
</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="button is not pressed"/>
+ <entry name="pressed" value="1" summary="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 pointer_focus event.
</description>
+ <arg name="serial" type="uint"/>
<arg name="time" type="uint"/>
<arg name="button" type="uint"/>
<arg name="state" type="uint"/>
</event>
- <event name="key">
- <description summary="key event">
- A key was pressed or released.
+ <enum name="axis">
+ <description summary="axis types"/>
+ <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"/>
- <arg name="key" type="uint"/>
- <arg name="state" type="uint"/>
+ <arg name="axis" type="uint"/>
+ <arg name="value" type="fixed"/>
</event>
+ </interface>
- <event name="pointer_enter">
- <description summary="pointer enter event">
- Notification that this input device's pointer is focused on
- certain surface. When an input_device enters a surface, the
- pointer image is undefined and a client should respond to this
- event by setting an appropriate pointer image.
+ <interface name="wl_keyboard" version="1">
+ <description summary="keyboard input device">
+ </description>
+
+ <enum name="keymap_format">
+ <description summary="keyboard mapping format">
+ This enum specifies the format of the keymap provided to the client
+ with the wl_keyboard::keymap event.
</description>
+ <entry name="xkb_v1" value="1" description="libxkbcommon compatible"/>
+ </enum>
- <arg name="time" type="uint"/>
- <arg name="surface" type="object" interface="wl_surface"/>
- <arg name="surface_x" type="int"/>
- <arg name="surface_y" type="int"/>
+ <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="pointer_leave">
- <description summary="pointer leave event">
- </description>
- <arg name="time" type="uint"/>
+ <event name="enter">
+ <arg name="serial" type="uint"/>
<arg name="surface" type="object" interface="wl_surface"/>
+ <arg name="keys" type="array"/>
</event>
- <event name="keyboard_enter">
- <arg name="time" type="uint"/>
+ <event name="leave">
+ <arg name="serial" type="uint"/>
<arg name="surface" type="object" interface="wl_surface"/>
- <arg name="keys" type="array"/>
</event>
- <event name="keyboard_leave">
+ <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.
+ </description>
+
+ <arg name="serial" type="uint"/>
<arg name="time" type="uint"/>
- <arg name="surface" type="object" interface="wl_surface"/>
+ <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="touch screen input device">
+ </description>
- <event name="touch_down">
+ <event name="down">
+ <arg name="serial" type="uint"/>
<arg name="time" type="uint"/>
<arg name="surface" type="object" interface="wl_surface"/>
<arg name="id" type="int" />
- <arg name="x" type="int" />
- <arg name="y" type="int" />
+ <arg name="x" type="fixed" />
+ <arg name="y" type="fixed" />
</event>
- <event name="touch_up">
+ <event name="up">
+ <arg name="serial" type="uint"/>
<arg name="time" type="uint"/>
<arg name="id" type="int" />
</event>
- <event name="touch_motion">
+ <event name="motion">
<arg name="time" type="uint"/>
<arg name="id" type="int" />
- <arg name="x" type="int" />
- <arg name="y" type="int" />
+ <arg name="x" type="fixed" />
+ <arg name="y" type="fixed" />
</event>
- <event name="touch_frame">
+ <event name="frame">
<description summary="end of touch frame event">
Indicates the end of a contact point list.
</description>
</event>
- <event name="touch_cancel">
+ <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
<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">
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
- <arg name="physical_width" type="int"/>
- <arg name="physical_height" type="int"/>
- <arg name="subpixel" type="int"/>
- <arg name="make" type="string"/>
- <arg name="model" type="string"/>
+ <description summary="properties of the output"/>
+ <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="values for the flags bitfield in the mode event"/>
- <entry name="current" value="0x1"/>
- <entry name="preferred" value="0x2"/>
+ <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">
- <arg name="flags" type="uint"/>
+ <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="mask of wl_output_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">
+ Region.
+ </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"/>
- <arg name="refresh" type="int"/>
- </event>
+ </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>