diff options
Diffstat (limited to 'protocol/wayland.xml')
| -rw-r--r-- | protocol/wayland.xml | 123 |
1 files changed, 69 insertions, 54 deletions
diff --git a/protocol/wayland.xml b/protocol/wayland.xml index a3599f0..3e674f3 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -874,48 +874,54 @@ <interface name="wl_surface" version="2"> <description summary="an onscreen surface"> - A surface. This is an image that is displayed on the screen. + 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. + Deletes the surface and invalidates its object ID. </description> </request> <request name="attach"> <description summary="set the surface contents"> - 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. + 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 + 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. After commit, there is no pending buffer until the - next attach. + 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 nil wl_buffer, 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> @@ -928,18 +934,20 @@ <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. + 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. + 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"/> @@ -972,11 +980,14 @@ <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. + 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. @@ -984,11 +995,11 @@ 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. + 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 + destroyed immediately. A NULL wl_region causes the pending opaque region to be set to empty. </description> @@ -998,10 +1009,11 @@ <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. + 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. @@ -1011,10 +1023,11 @@ 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. + 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"/> @@ -1044,18 +1057,20 @@ <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. + 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. + 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> |