[PATCH 13/21] docs: Improve wl_surface protocol docs
Jason Ekstrand
jason at jlekstrand.net
Mon Apr 1 09:41:12 PDT 2013
Looks good!
--Jason Ekstrand
On Mar 30, 2013 12:24 AM, <matthias.clasen at gmail.com> wrote:
> From: Matthias Clasen <mclasen at redhat.com>
>
> Use NULL consistently. And add some more information in a few
> places.
> ---
> protocol/wayland.xml | 123
> +++++++++++++++++++++++++++++----------------------
> 1 file 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>
> --
> 1.8.1.4
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20130401/7e6982b0/attachment-0001.html>
More information about the wayland-devel
mailing list